diff --git a/docs/INDEX.md b/docs/INDEX.md index e0bccd9e..32656a0a 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 04da37e7..bf00fc92 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/lithosananke/README.md b/docs/lithosananke/README.md index ca3c4223..24100b8c 100644 --- a/docs/lithosananke/README.md +++ b/docs/lithosananke/README.md @@ -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) --- diff --git a/docs/lithosananke/ROADMAP.md b/docs/lithosananke/ROADMAP.md index cbebe82f..b5e51b0a 100644 --- a/docs/lithosananke/ROADMAP.md +++ b/docs/lithosananke/ROADMAP.md @@ -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) ``` --- diff --git a/docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md b/docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md index 2f247c46..5df3f843 100644 --- a/docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md +++ b/docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md @@ -1,4 +1,9 @@ + +> **⚠ 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 diff --git a/docs/working/architecture/03-architecture/hal/README.md b/docs/working/architecture/03-architecture/hal/README.md index 0d0a4c8e..61e268e5 100644 --- a/docs/working/architecture/03-architecture/hal/README.md +++ b/docs/working/architecture/03-architecture/hal/README.md @@ -1,4 +1,11 @@ + +> **⚠ TARGET HAL — NOT THE BUILT INTERFACE (flagged 2026-10-09).** This document family +> describes a proposed `hal_*`-named interface and a `src/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. diff --git a/docs/working/architecture/03-architecture/hal/interfaces.md b/docs/working/architecture/03-architecture/hal/interfaces.md index e9ff3d2e..42b14f27 100644 --- a/docs/working/architecture/03-architecture/hal/interfaces.md +++ b/docs/working/architecture/03-architecture/hal/interfaces.md @@ -1,4 +1,10 @@ + +> **⚠ 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 diff --git a/docs/working/architecture/03-architecture/hal/migration-plan.md b/docs/working/architecture/03-architecture/hal/migration-plan.md index fa59cc15..47facc7c 100644 --- a/docs/working/architecture/03-architecture/hal/migration-plan.md +++ b/docs/working/architecture/03-architecture/hal/migration-plan.md @@ -1,4 +1,10 @@ + +> **⚠ 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 diff --git a/docs/working/architecture/03-architecture/hal/platform-implementations.md b/docs/working/architecture/03-architecture/hal/platform-implementations.md index 3ed5a160..d6da5c1b 100644 --- a/docs/working/architecture/03-architecture/hal/platform-implementations.md +++ b/docs/working/architecture/03-architecture/hal/platform-implementations.md @@ -1,4 +1,12 @@ + +> **⚠ OBSOLETE (flagged 2026-10-09).** Assumes a `src/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 diff --git a/docs/working/architecture/03-architecture/hal/starkernel-integration.md b/docs/working/architecture/03-architecture/hal/starkernel-integration.md index fb5bfa5d..ccd75766 100644 --- a/docs/working/architecture/03-architecture/hal/starkernel-integration.md +++ b/docs/working/architecture/03-architecture/hal/starkernel-integration.md @@ -1,4 +1,10 @@ + +> **⚠ 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 diff --git a/docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md b/docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md index dde3cd16..faaf98e3 100644 --- a/docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md +++ b/docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md @@ -1,4 +1,10 @@ + +> **⚠ 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 diff --git a/docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md b/docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md index 2a22cf52..fba29429 100644 --- a/docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md +++ b/docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md @@ -1,4 +1,9 @@ + +> **⚠ 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 diff --git a/docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md b/docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md index 830383e7..774112a4 100644 --- a/docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md +++ b/docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md @@ -1,4 +1,10 @@ + +> **⚠ 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. diff --git a/docs/working/architecture/getting-started/quick-start/factorial-doe.md b/docs/working/architecture/getting-started/quick-start/factorial-doe.md index 63a0d836..72c0f3ea 100644 --- a/docs/working/architecture/getting-started/quick-start/factorial-doe.md +++ b/docs/working/architecture/getting-started/quick-start/factorial-doe.md @@ -1,4 +1,9 @@ + +> **⚠ 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 diff --git a/docs/working/experiments/02-experiments/L8_WIRING_PLAN.md b/docs/working/experiments/02-experiments/L8_WIRING_PLAN.md index e343f694..aaf9e6bf 100644 --- a/docs/working/experiments/02-experiments/L8_WIRING_PLAN.md +++ b/docs/working/experiments/02-experiments/L8_WIRING_PLAN.md @@ -1,4 +1,9 @@ + +> **⚠ 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 diff --git a/docs/working/experiments/02-experiments/factorial-doe/guide.md b/docs/working/experiments/02-experiments/factorial-doe/guide.md index ca755858..8306ec0a 100644 --- a/docs/working/experiments/02-experiments/factorial-doe/guide.md +++ b/docs/working/experiments/02-experiments/factorial-doe/guide.md @@ -1,4 +1,8 @@ + +> **⚠ 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 diff --git a/docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md b/docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md index 78770ad5..94e0de68 100644 --- a/docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md +++ b/docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md @@ -1,4 +1,8 @@ + +> **⚠ 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 diff --git a/docs/working/experiments/02-experiments/factorial-doe/index.md b/docs/working/experiments/02-experiments/factorial-doe/index.md index d5e5b493..abac13f8 100644 --- a/docs/working/experiments/02-experiments/factorial-doe/index.md +++ b/docs/working/experiments/02-experiments/factorial-doe/index.md @@ -1,4 +1,8 @@ + +> **⚠ 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 diff --git a/docs/working/experiments/02-experiments/factorial-doe/workflow.md b/docs/working/experiments/02-experiments/factorial-doe/workflow.md index d0c3e1cc..2fa44b36 100644 --- a/docs/working/experiments/02-experiments/factorial-doe/workflow.md +++ b/docs/working/experiments/02-experiments/factorial-doe/workflow.md @@ -1,4 +1,9 @@ + +> **⚠ 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 diff --git a/docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md b/docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md index 574928d9..0bfbfe13 100644 --- a/docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md +++ b/docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md @@ -1,4 +1,8 @@ + +> **⚠ 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 diff --git a/docs/working/experiments/02-experiments/heartbeat-doe/design.md b/docs/working/experiments/02-experiments/heartbeat-doe/design.md index 579737fb..6d5184b1 100644 --- a/docs/working/experiments/02-experiments/heartbeat-doe/design.md +++ b/docs/working/experiments/02-experiments/heartbeat-doe/design.md @@ -1,4 +1,9 @@ + +> **⚠ 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