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
+- **[03-architecture/](03-architecture/)** — Tripod VM architecture constraints and the
-  (Hera/Hermes/Artemis) and the word-level ACL system design.
+  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
+  milestone roadmap, system architecture, HAL reference, kernel command-line argument
-  argument design, and the amd64 APIC-timer ISR postmortem.
+  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.
+> **⚠ `INDEX.md` is a dated triage snapshot (2026-06-16) and is stale.** The authoritative
-  See `lithosananke/README.md` and `lithosananke/M7.1.md`.
+> current status lives in `.claude/CLAUDE.md` and `docs/fabric/FABRIC-2.md` /
- **Word-level ACL system** — Phase 6 complete on `master`; Phase 7 (LithosAnanke
+> `FABRIC-3.md` / `FABRIC-3.5.md` / `FABRIC-3.6.md` — not in the status tags in `INDEX.md`.
-  parity) is the next step. See `03-architecture/word-acl/README.md`.
+
- **Tripod VMs** — Hera (governor), Hermes (messenger), Artemis (memory/block
+- **LithosAnanke M7.1 — live** — init capsules, the Tripod fleet, Stadium physics-economy,
-  storage). See `03-architecture/tripod/README.md` and `birthing/`.
+  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`
+> **⚠ PARTIALLY STALE (flagged 2026-10-09).** This page predates the repo split and the
-**Status:** M7 Complete (VM Parity Validation)
+> Tripod/kernel reshuffle. There is no `lithosananke` branch in this repo — `master` is the
-**Parent:** `master` (hosted StarForth)
+> 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 |
+| **M7.1** | **Capsules · Tripod · Stadium · ACL** | **Live** (see FABRIC docs) |
-| M8 | REPL + Interactive Forth | Planned |
+| M8 | REPL (keyboard input) | Superseded — see FABRIC-0 §25.5 item 4.4 |
-| M9 | Block Storage | Planned |
+| M9 | Block Storage / Block I/O | Live (virtio-blk + block subsystem) |
 ---
 ## Build & Run
 ```bash
-# Build kernel with VM integration
+# Build kernel with VM integration (loader + kernel)
-make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1
+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
+2. Pass the three-arch QEMU boot test (`ARCH={amd64,aarch64,riscv64}`)
-3. Not break hosted StarForth (master branch)
+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)
+master (post-split: sole LithosAnanke production line — the old
-    │
+lithosananke/master two-branch topology no longer exists in this repo)
-    ├── lithosananke (kernel branch)
+    └── M0–M7 complete, M7.1 live (capsules / Tripod / Stadium / ACL)
    │       │
    │       └── M7 complete, M7.1 design complete
    │
    └── starkernel-junkyard (legacy, can delete)
 ```
 ---
@@ -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