docs: update stale entry docs and deprecate superseded docs with annotations

- docs/lithosananke/README.md + ROADMAP.md: correct branch topology (no lithosananke branch post-split; master is the sole line), mark M7.1 as live, and fix build commands (kernel/Makefile, not Makefile.starkernel) - docs/README.md: refresh current active work (Tripod = Hera/Artemis/Hestia, M7.1 live, StarForth v4) and flag INDEX.md as stale - docs/INDEX.md: add dated-snapshot staleness banner - Add TARGET-HAL / OBSOLETE / SUPERSEDED banners to stale HAL, physics, heartbeat, and DoE docs under docs/working/ (annotation only, no deletions)
2026-10-09 18:21:10 -04:00
parent f1419e739c
commit 2e6262c91f
21 changed files with 147 additions and 32 deletions
@@ -1,5 +1,13 @@
 # docs/INDEX.md — Documentation Triage

+> **⚠ STALE — dated snapshot (triage performed 2026-06-16; this banner added 2026-10-09).**
+> This index is maintained by hand and has not been re-run since June 2026. Do not trust its
+> status tags or file lists as current: use `.claude/CLAUDE.md` and the
+> `docs/fabric/FABRIC-*.md` documents for authoritative status, and re-run the Phase 1 triage
+> from `docs/CLAUDE.md` if a fresh inventory is needed. Paths shown here are pre-reorg
+> (`docs/03-architecture/...`, `docs/02-experiments/...`) and may have moved to
+> `docs/working/architecture/03-architecture/...` / `docs/working/experiments/02-experiments/...`.
+
 **Phase 1 triage:** 2026-06-16 · **Phase 2 reorg:** 2026-06-16 · **Phase 3 stubs:** 2026-06-16
 **Total files inventoried:** 328  
 **Status tags:** CURRENT · WORKING · HISTORICAL · SUPERSEDED · OBSOLETE · DELETE
@@ -16,11 +16,13 @@ doesn't fit either tier.
 - **[working/](working/)** — Living documents: architecture design notes, DoE
  experiment logs, hardware/platform notes, draft specs, academic-paper source
  material, and an archive of superseded docs. Source material for `formal/`.
- **[03-architecture/](03-architecture/)** — Tripod VM architecture constraints
-  (Hera/Hermes/Artemis) and the word-level ACL system design.
+- **[03-architecture/](03-architecture/)** — Tripod VM architecture constraints and the
+  word-level ACL system design. (Note: the fleet is now **Hera/Artemis/Hestia** post-
+  reshuffle; the old Hera/Hermes/Artemis framing in older docs is historical. The older,
+  triaged copy of this tree is `working/architecture/03-architecture/`.)
 - **[lithosananke/](lithosananke/)** — LithosAnanke kernel branch documentation:
-  milestone roadmap, system architecture, HAL reference, kernel command-line
-  argument design, and the amd64 APIC-timer ISR postmortem.
+  milestone roadmap, system architecture, HAL reference, kernel command-line argument
+  design, and the amd64 APIC-timer ISR postmortem.
 - **[birthing/](birthing/)** — VM birthing plan and status for the Hera-spawns-
  Hermes/Artemis constellation, plus three-architecture QEMU acceptance logs.
 - **[patent/](patent/)** — Provisional patent application source. **Legal hold —
@@ -32,12 +34,19 @@ doesn't fit either tier.

 ## Current Active Work

- **LithosAnanke M7/M7.1** — VM parity validation and init capsule architecture.
-  See `lithosananke/README.md` and `lithosananke/M7.1.md`.
- **Word-level ACL system** — Phase 6 complete on `master`; Phase 7 (LithosAnanke
-  parity) is the next step. See `03-architecture/word-acl/README.md`.
- **Tripod VMs** — Hera (governor), Hermes (messenger), Artemis (memory/block
-  storage). See `03-architecture/tripod/README.md` and `birthing/`.
+> **⚠ `INDEX.md` is a dated triage snapshot (2026-06-16) and is stale.** The authoritative
+> current status lives in `.claude/CLAUDE.md` and `docs/fabric/FABRIC-2.md` /
+> `FABRIC-3.md` / `FABRIC-3.5.md` / `FABRIC-3.6.md` — not in the status tags in `INDEX.md`.
+
+- **LithosAnanke M7.1 — live** — init capsules, the Tripod fleet, Stadium physics-economy,
+  and word-level ACL (Phases 1–7 complete; Phase 8 Ed25519 PKI pending). See
+  `lithosananke/ROADMAP.md` and the FABRIC documents above.
+- **Tripod VMs (post-reshuffle)** — Hera (governor), Artemis (memory/block storage),
+  Hestia; the Hermes VM was removed and messaging moved into the kernel as kernel-Hermes.
+  See `.claude/CLAUDE.md`.
+- **StarForth v4** — the F18-derived 32-opcode engine with the node/mesh design. See
+  `v4.0.0/` and `../v4/README.md`.
+- **Word-level ACL system** — see `03-architecture/word-acl/` and `lithosananke/ROADMAP.md`.

 ## Contributing

@@ -1,8 +1,15 @@
 # LithosAnanke — StarForth Kernel Branch

-**Branch:** `lithosananke`
-**Status:** M7 Complete (VM Parity Validation)
-**Parent:** `master` (hosted StarForth)
+> **⚠ PARTIALLY STALE (flagged 2026-10-09).** This page predates the repo split and the
+> Tripod/kernel reshuffle. There is no `lithosananke` branch in this repo — `master` is the
+> sole production line — and the VM fleet is now **Hera / Artemis / Hestia** (the Hermes VM
+> was removed; messaging moved into the kernel as kernel-Hermes). M7.1 is **live**, not
+> merely designed. For authoritative status see `.claude/CLAUDE.md` and
+> `docs/fabric/FABRIC-2.md` / `FABRIC-3.md` / `FABRIC-3.5.md` / `FABRIC-3.6.md`; for the
+> milestone plan see `ROADMAP.md` (this file is an orientation page).
+
+**Line:** `master` (sole production line post-split)
+**Status:** M7 Complete (VM Parity) · M7.1 Live (capsules, Tripod, Stadium, word-level ACL Phases 1–7)

 ---

@@ -66,20 +73,24 @@ The name reflects the project's nature: a necessary foundation for StarshipOS.
 | M5 | Timer Calibration | Complete |
 | M6 | Kernel Heap | Complete |
 | **M7** | **VM Parity Validation** | **Complete** |
-| M7.1 | Init Capsule Architecture | Design Complete |
-| M8 | REPL + Interactive Forth | Planned |
-| M9 | Block Storage | Planned |
+| **M7.1** | **Capsules · Tripod · Stadium · ACL** | **Live** (see FABRIC docs) |
+| M8 | REPL (keyboard input) | Superseded — see FABRIC-0 §25.5 item 4.4 |
+| M9 | Block Storage / Block I/O | Live (virtio-blk + block subsystem) |

 ---

 ## Build & Run

 ```bash
-# Build kernel with VM integration
-make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1
+# Build kernel with VM integration (loader + kernel)
+make -f kernel/Makefile ARCH=amd64 STARFORTH_ENABLE_VM=1

 # Run in QEMU
-make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1 qemu
+make -f kernel/Makefile ARCH=amd64 STARFORTH_ENABLE_VM=1 qemu
+
+# Other architectures
+make -f kernel/Makefile ARCH=aarch64 qemu
+make -f kernel/Makefile ARCH=riscv64 qemu
 ```

 **Output artifacts:**
@@ -168,11 +179,11 @@ src/starkernel/

 ## Contributing

-The lithosananke branch is experimental. Changes should:
+The contributing rules are:

 1. Maintain parity validation (M7 baseline)
-2. Pass QEMU boot test
-3. Not break hosted StarForth (master branch)
+2. Pass the three-arch QEMU boot test (`ARCH={amd64,aarch64,riscv64}`)
+3. Not break the hosted VM build (plain `make` at the repo root)

 ---

@@ -550,13 +550,13 @@ identically afterward.)

 ```bash
 # Build
-make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1
+make -f kernel/Makefile ARCH=amd64 STARFORTH_ENABLE_VM=1

 # Run QEMU
-make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1 qemu
+make -f kernel/Makefile ARCH=amd64 STARFORTH_ENABLE_VM=1 qemu

 # Clean
-make -f Makefile.starkernel ARCH=amd64 clean-kernel
+make -f kernel/Makefile ARCH=amd64 clean-kernel
 ```

 ---
@@ -564,13 +564,9 @@ make -f Makefile.starkernel ARCH=amd64 clean-kernel
 ## Branch Relationship

 ```
-master (hosted StarForth)
-    │
-    ├── lithosananke (kernel branch)
-    │       │
-    │       └── M7 complete, M7.1 design complete
-    │
-    └── starkernel-junkyard (legacy, can delete)
+master (post-split: sole LithosAnanke production line — the old
+lithosananke/master two-branch topology no longer exists in this repo)
+    └── M0–M7 complete, M7.1 live (capsules / Tripod / Stadium / ACL)
 ```

 ---
@@ -1,4 +1,9 @@
 <!-- Moved from docs/03-architecture/adaptive-systems/loop-5-sketch.md to docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ SUPERSEDED (flagged 2026-10-09).** Superseded by `window-inference-redesign.md`
+> (Levene's-test window inference — the shipped Loop #5 mechanism). This undated sketch ended
+> in an open question and was never approved as designed. Kept for historical record.
+
 # Loop #5: Context-Aware Window Tuning - Design Sketch

 ## The Challenge
@@ -1,4 +1,11 @@
 <!-- Moved from docs/03-architecture/hal/README.md to docs/working/architecture/03-architecture/hal/README.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ TARGET HAL — NOT THE BUILT INTERFACE (flagged 2026-10-09).** This document family
+> describes a proposed `hal_*`-named interface and a `src/platform/<platform>/` layout that
+> was never adopted as written. The implemented kernel HAL lives in `src/starkernel/hal/`
+> with different (time-backend-style) naming. Treat all five documents here as design intent,
+> not the current API. For current architecture see `.claude/CLAUDE.md`.
+
 # Hardware Abstraction Layer (HAL) Documentation

 This directory contains comprehensive documentation for StarForth's Hardware Abstraction Layer (HAL), which enables the evolution from hosted VM to StarKernel to StarshipOS.
@@ -1,4 +1,10 @@
 <!-- Moved from docs/03-architecture/hal/interfaces.md to docs/working/architecture/03-architecture/hal/interfaces.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ TARGET HAL — NOT THE BUILT INTERFACE (flagged 2026-10-09).** This document defines the
+> proposed `hal_*` interface contract; it was never adopted as written. The implemented kernel
+> HAL is `src/starkernel/hal/` with different naming. See `README.md` in this directory and
+> `.claude/CLAUDE.md` for what is actually built.
+
 # HAL Interface Specifications

 ## Overview
@@ -1,4 +1,10 @@
 <!-- Moved from docs/03-architecture/hal/migration-plan.md to docs/working/architecture/03-architecture/hal/migration-plan.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ TARGET HAL — NOT THE BUILT INTERFACE (flagged 2026-10-09).** This migration plan targets
+> the proposed `hal_*` interface, which was never adopted as written. The kernel grew its own
+> HAL directly in `src/starkernel/hal/`. Kept for design rationale; see `.claude/CLAUDE.md`
+> for the built architecture.
+
 # HAL Migration Plan

 ## Overview
@@ -1,4 +1,12 @@
 <!-- Moved from docs/03-architecture/hal/platform-implementations.md to docs/working/architecture/03-architecture/hal/platform-implementations.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ OBSOLETE (flagged 2026-10-09).** Assumes a `src/platform/<platform>/hal_*.c` layout
+> whose platform names ("Linux", "L4Re", "StarKernel") and interface never matched the built
+> tree: the actual kernel HAL is `src/starkernel/hal/`, L4Re is no longer an active target,
+> and the kernel is well past a hypothetical "Boot + Serial Output" starting point. Do not use
+> as a platform porting guide. See the TARGET-HAL caveat in `README.md` and
+> `.claude/CLAUDE.md`.
+
 # HAL Platform Implementation Guide

 ## Overview
@@ -1,4 +1,10 @@
 <!-- Moved from docs/03-architecture/hal/starkernel-integration.md to docs/working/architecture/03-architecture/hal/starkernel-integration.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ OBSOLETE (flagged 2026-10-09).** Describes implementing `src/platform/kernel/` and a
+> "Milestone 1: Boot + Serial Output" starting point. True architecture is far ahead: the
+> kernel lives in `src/starkernel/` with M0–M7 complete and M7.1 live. Kept for historical
+> context; for the real boot/kernel story see `.claude/CLAUDE.md` and `docs/fabric/`.
+
 # StarKernel HAL Integration Guide

 ## Overview
@@ -1,4 +1,10 @@
 <!-- Moved from docs/03-architecture/heartbeat-system/implementation-plan.md to docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ SUPERSEDED (flagged 2026-10-09).** Superseded by `instrumentation-plan.md`. Proposes the
+> earlier `HeartbeatRateSample` design; the live target is `HeartbeatTickSnapshot`
+> (`include/vm.h`) with a `tick_buffer` and `heartbeat_export_csv()`. Kept for historical
+> record.
+
 # Implementation Plan: Heartbeat Rate Logging

 **Date:** November 20, 2025
@@ -1,4 +1,9 @@
 <!-- Moved from docs/03-architecture/physics-engine/feedback-loops-analysis.md to docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ SUPERSEDED (flagged 2026-10-09).** Precursor bug-hunt audit covering six feedback loops;
+> the canonical, current reference is `feedback-loops.md` (all seven loops, tuning knobs, and
+> source files). Kept for historical record.
+
 # StarForth Feedback Loops & Self-Optimization Analysis

 ## Executive Summary
@@ -1,4 +1,10 @@
 <!-- Moved from docs/03-architecture/physics-engine/steady-state-machine.md to docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ OBSOLETE (flagged 2026-10-09).** Conceptual precursor to the L8 Jacquard mode-selector
+> system; it never mentions Jacquard/L8, the attractor buckets, or the six named modes, and
+> was never reconciled with the implemented `ssm_jacquard.c` system. The canonical current
+> reference for the physics/feedback model is `feedback-loops.md`. Kept for historical record.
+
 # 1. Introduction

 A Steady State Machine (SSM) is a novel computational model in which the system’s operational state is defined not by discrete symbolic transitions, but by convergence to an optimal runtime equilibrium.
@@ -1,4 +1,9 @@
 <!-- Moved from docs/01-getting-started/quick-start/factorial-doe.md to docs/working/architecture/getting-started/quick-start/factorial-doe.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ OBSOLETE (flagged 2026-10-09).** Describes the retired per-loop `ENABLE_LOOP_1..6`
+> compile-time toggle architecture and hardcoded local paths; the physics adaptation is now
+> driven by the L8 Jacquard runtime mode selector. Kept for historical record.
+
 # Quick Start: Complete 2^6 Factorial DoE

 ## TL;DR
@@ -1,4 +1,9 @@
 <!-- Moved from docs/02-experiments/L8_WIRING_PLAN.md to docs/working/experiments/02-experiments/L8_WIRING_PLAN.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ SUPERSEDED (flagged 2026-10-09).** The wiring plan was executed; superseded by
+> `L8_WIRING_IMPLEMENTATION_SUMMARY.md` and `L8_WIRING_CODE_REVIEW_GUIDE.md`. Kept as a
+> record of the plan.
+
 # L8 Control Wiring Implementation Plan

 **Status**: Infrastructure exists but execution paths are not gated
@@ -1,4 +1,8 @@
 <!-- Moved from docs/02-experiments/factorial-doe/guide.md to docs/working/experiments/02-experiments/factorial-doe/guide.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ OBSOLETE (flagged 2026-10-09).** Describes the retired per-loop Makefile-toggle
+> architecture, replaced by the L8 Jacquard runtime mode selector. Kept for historical record.
+
 # StarForth Complete 2^6 Factorial Design of Experiments

 ## Overview
@@ -1,4 +1,8 @@
 <!-- Moved from docs/02-experiments/factorial-doe/incompatible-configs.md to docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ OBSOLETE (flagged 2026-10-09).** Build-time incompatibility handling for the retired 2^6
+> toggle experiment, replaced by the L8 Jacquard mode selector. Kept for historical record.
+
 # Handling Incompatible Configurations in Factorial DoE

 ## Overview
@@ -1,4 +1,8 @@
 <!-- Moved from docs/02-experiments/factorial-doe/index.md to docs/working/experiments/02-experiments/factorial-doe/index.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ OBSOLETE (flagged 2026-10-09).** Index for the retired 2^6 factorial toggle
+> architecture, replaced by the L8 Jacquard mode selector. Kept for historical record.
+
 # StarForth Complete 2^6 Factorial DoE - Documentation Index

 ## Overview
@@ -1,4 +1,9 @@
 <!-- Moved from docs/02-experiments/factorial-doe/workflow.md to docs/working/experiments/02-experiments/factorial-doe/workflow.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ HISTORICAL (flagged 2026-10-09).** Documents the completed 2025-11-19 factorial
+> campaign whose data informed the current L8 design; the toggle architecture it runs on is
+> retired. Kept as a record.
+
 # Factorial DoE Analysis Workflow

 ## End-to-End Process
@@ -1,4 +1,8 @@
 <!-- Moved from docs/02-experiments/heartbeat-doe/corrected-design.md to docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ SUPERSEDED (flagged 2026-10-09).** Superseded by `phase2-corrected.md` (the
+> "corrected and finalized" revision). Kept for historical record.
+
 # StarForth Heartbeat DoE – CORRECTED Design (Heartrate Focus)

 **Date:** November 20, 2025
@@ -1,4 +1,9 @@
 <!-- Moved from docs/02-experiments/heartbeat-doe/design.md to docs/working/experiments/02-experiments/heartbeat-doe/design.md on 2026-06-16 (docs reorg Phase 2) -->
+
+> **⚠ SUPERSEDED (flagged 2026-10-09).** Pre-correction draft; superseded first by
+> `corrected-design.md`, then by `phase2-corrected.md` (the finalized design). Kept for
+> historical record.
+
 # StarForth Factorial DoE with Heartbeat Integration

 **Date:** November 20, 2025