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,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