diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index de3f16c1..49ce982a 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -119,9 +119,8 @@ about "which line am I on." ## Word-Level ACL System — Complete through Phase 7 (independently verified) -**Design doc:** `docs/03-architecture/word-acl/DESIGN.md` (this repo kept the old-style -`docs/03-architecture/` tree alongside the newer `docs/formal/`/`docs/working/` restructure — -both exist here; this path is still current for ACL specifically). +**Design doc:** `docs/reference/word-acl/DESIGN.md` (moved there from the old +`docs/03-architecture/` tree in the 2026-10-14 docs reorganisation). The word-level ACL system is fully implemented, including kernel parity. Key constraints: @@ -501,7 +500,7 @@ mistakenly invoke). ## Roadmap -`ROADMAP.md` and `docs/lithosananke/ROADMAP.md` contain real, LithosAnanke-specific phase +`ROADMAP.md` and `docs/reference/ROADMAP.md` contain real, LithosAnanke-specific phase content (e.g. "PHASE 2: STARKERNEL (Months 3-5)", "StarKernel boots to 'ok' on QEMU ✅") — not a copy of the standalone StarForth repo's roadmap. Prefer these when citing roadmap status for kernel work. @@ -575,25 +574,28 @@ capsule and compare dict hashes. Zero-deviation means 0% algorithmic variance. ## Documentation -Key files (this repo has both the older `docs/03-architecture/` tree — still current for -ACL/Tripod specifically — and the newer restructured `docs/formal/`/`docs/working/`/ -`docs/patent/` trees, plus a repo-specific `docs/lithosananke/` tree): +**Start at `docs/README.md`** -- the map: where each kind of document lives and which one is +authoritative for what. `docs/INDEX.md` lists every document with its status; +`docs/DEAD-AND-REVISED.md` is the register of abandoned ideas and revised claims. (Reorganised +2026-10-14: the old `docs/03-architecture/` and `docs/lithosananke/` trees are gone -- their +current parts are in `docs/reference/`, the rest in `docs/working/archive/`.) -- `README.md` — project overview and quick start -- `docs/lithosananke/SYSTEM_ARCHITECTURE.md` — full kernel + VM design -- `docs/lithosananke/hal/` — HAL reference -- `docs/lithosananke/M7.1.md` — capsule birth protocol design -- `docs/lithosananke/ROADMAP.md` — milestone plan through self-hosting -- `docs/lithosananke/hosted-acceptance-test/README.md` — the hosted-VM acceptance test - writeup referenced from the standalone StarForth repo's own docs -- `docs/03-architecture/tripod/`, `docs/03-architecture/word-acl/DESIGN.md` -- `docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md` — Tripod/Hermes/Artemis - physics + build-system history -- `docs/working/architecture/getting-started/DEVELOPER.md` — dev setup, Kconfig reference -- `ROADMAP.md`, `CHANGELOG.md` -- `experiments/bare_metal/README.md` — **mandatory read before touching capsules** (block +- `README.md` -- project overview and quick start +- `docs/fabric/` -- the design and work record (`FABRIC-3.md` living; the others closed) +- `docs/v4.0.0/` -- StarForth v4 design +- `docs/reference/` -- current reference: `ROADMAP.md` (roadmap and versioning policy), + `M7.1.md` (capsule birth protocol), `word-acl/DESIGN.md` (word-level ACL), `kernel-args/`, + `hosted-acceptance-test/`, `DICTIONARY.md`, `STARFORTH_PRIMITIVES.md`, `ONTOLOGY.md` +- `boards/BRINGUP.md` -- bare-metal bring-up checklist and blockers +- `kernel/src/hal/README.md` -- the HAL as built (the proposed `hal_*` contract was never + adopted; it is archived as dead) +- `docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md` -- fleet physics and + build-system history (pre-reshuffle: it still names the Hermes VM) +- `docs/working/architecture/getting-started/DEVELOPER.md` -- dev setup, Kconfig reference +- `CHANGELOG.md` +- `experiments/bare_metal/README.md` -- **mandatory read before touching capsules** (block namespace rules, see ACL section above) -- `experiments/bare_metal/analysis/report/bare_metal_doe_report.pdf` — DoE campaign report +- `experiments/bare_metal/analysis/report/bare_metal_doe_report.pdf` -- DoE campaign report - `sbom.spdx` / `sbom.spdx.json` --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e6eca75..f41a906d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ Thank you for your interest in contributing to StarForth! This document provides 3. **Run tests**: `make test` (all 780+ tests must pass) 4. **Read** [ONTOLOGY.md](ONTOLOGY.md) for formal definitions and terminology 5. **Read** `docs/CLAUDE.md` for project overview -6. **Explore** `docs/03-architecture/` for architecture details +6. **Explore** `docs/README.md` (the documentation map) for architecture details **Important:** All contributors must use terminology from [ONTOLOGY.md](ONTOLOGY.md) in code comments and documentation. This ensures precise, academically rigorous language throughout the project. @@ -36,7 +36,7 @@ void function_name(VM *vm) { ### Platform Abstraction - **Never** call platform-specific APIs directly from VM code - **Always** use HAL interfaces (`hal_time.h`, `hal_memory.h`, etc.) -- See `docs/03-architecture/hal/` for HAL documentation +- See `kernel/src/hal/README.md` for the HAL as built ### Memory Safety - Use `vaddr_t` for VM addresses (not C pointers) diff --git a/README.md b/README.md index 58957de6..11fd7db7 100644 --- a/README.md +++ b/README.md @@ -122,13 +122,13 @@ make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig | | | |---|---| -| [System Architecture](docs/lithosananke/SYSTEM_ARCHITECTURE.md) | Full kernel + VM design | -| [HAL Reference](docs/lithosananke/hal/) | Hardware abstraction layer interfaces | -| [Capsule System — M7.1](docs/lithosananke/M7.1.md) | Capsule birth protocol design | +| [System Architecture](docs/working/archive/historical/2026-01-27-system-architecture-draft.md) | Full kernel + VM design | +| [HAL Reference](kernel/src/hal/README.md) | Hardware abstraction layer, as built | +| [Capsule System — M7.1](docs/reference/M7.1.md) | Capsule birth protocol design | | [VM Fleet Attractor design log](docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md) | Tripod/Hermes/Artemis physics + build-system history | | [Getting Started / Kconfig reference](docs/working/architecture/getting-started/DEVELOPER.md#build-configuration-kconfig) | Full symbol reference for both build targets | | [Changelog](CHANGELOG.md) | Milestone-level history | -| [Roadmap](docs/lithosananke/ROADMAP.md) | Milestone plan through self-hosting | +| [Roadmap](docs/reference/ROADMAP.md) | Milestone plan through self-hosting | --- diff --git a/docs/INDEX.md b/docs/INDEX.md index 32656a0a..369ebc54 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -71,8 +71,8 @@ | docs/working/papers/ANTI_CLAIMS.md | Explicit boundary statements for SSRN/peer-review defensibility | CURRENT | Directly supports published SSRN paper; no code references that have drifted. | | ./docs/CLAUDE.md | Docs-root instructions for Claude Code; two-tier doc model plan | WORKING | Describes a `docs/formal/` + `docs/working/` restructure not yet executed; active planning doc, not authoritative state ref (`.claude/CLAUDE.md` is). | | docs/working/archive/COMPUTATIONAL_PHYSICS_FRAMEWORK.md | Expansive "physics of computation" claims framework | HISTORICAL | Contains strong over-claims ("This is not metaphor") that contradict `ANTI_CLAIMS.md` and `ACADEMIC_WORDING_GUIDELINES.md`; dates from earlier draft thinking (2025-12-10). | -| ./docs/DARPA_SSM_Proposal_James.docx | DARPA SSM grant proposal (Word format) | WORKING | Active proposal document; companion to the PDF version. | -| ./docs/DARPA_SSM_Proposal_James.pdf | DARPA SSM grant proposal (PDF) | WORKING | Active funding proposal; filename indicates a working/submission-ready draft. | +| ./docs/working/papers/proposals/DARPA_SSM_Proposal_James.docx | DARPA SSM grant proposal (Word format) | WORKING | Active proposal document; companion to the PDF version. | +| ./docs/working/papers/proposals/DARPA_SSM_Proposal_James.pdf | DARPA SSM grant proposal (PDF) | WORKING | Active funding proposal; filename indicates a working/submission-ready draft. | | docs/working/archive/DOCUMENTATION_AUDIT.md | Docs audit from 2025-12-14; gap/inconsistency findings | HISTORICAL | Audit from a past triage pass; most findings have since changed; useful historical record. | | docs/working/papers/EXECUTIVE_SUMMARY.md | Plain-English summary of StarForth results for non-specialists | CURRENT | Accurate, well-calibrated summary with correct metaphor framing; audience: journalists, admins, reviewers. | | docs/working/papers/FINAL_REPORT/appendix_glossary.adoc | AsciiDoc glossary appendix for multi-chapter report | CURRENT | Formal, math-precise definitions consistent with current ontology; intended for book/report compilation. | @@ -87,7 +87,7 @@ | docs/working/papers/REPRODUCIBILITY.md | One-command reproduction protocol with exact expected output | CURRENT | References valid build commands and `--doe` flag; expected output values consistent with published claims. | | docs/working/papers/SCIENTIFIC_DEFENSE_CHECKLIST.md | Checklist of attack vectors and defenses for peer review | WORKING | Many "missing defenses" (GPG signing, Zenodo DOI, R/Python scripts) not yet addressed; still actively relevant. | | docs/working/papers/SENSITIVITY_ANALYSIS.md | Parameter sweep design: robustness of 0% CV claim | CURRENT | Documents planned sensitivity experiments; scientifically sound framing; supports SSRN defensibility. | -| ./docs/SSM_DARPA_Complete_Proposal_James_FINAL.docx | DARPA SSM complete/final proposal (Word, FINAL) | WORKING | "FINAL" in name suggests submission-ready; likely supersedes `DARPA_SSM_Proposal_James.docx` but keep both until confirmed. | +| ./docs/working/papers/proposals/SSM_DARPA_Complete_Proposal_James_FINAL.docx | DARPA SSM complete/final proposal (Word, FINAL) | WORKING | "FINAL" in name suggests submission-ready; likely supersedes `DARPA_SSM_Proposal_James.docx` but keep both until confirmed. | | docs/working/papers/SSRN_companion/Math_Companion_SSRN.pdf | Compiled PDF of math companion to SSRN paper | CURRENT | Rendered output of the `.tex` source; companion to the published SSRN paper. | | docs/working/papers/SSRN_companion/Math_Companion_SSRN.tex | LaTeX source for math companion document | CURRENT | Source of record for comprehensive math/engineering structures reference; cross-references implementation. | | docs/working/papers/SSRN_companion/figures/fig1_snake_trajectory.pdf | Figure asset: snake/phase trajectory | CURRENT | Figure asset for the SSRN math companion. | @@ -97,31 +97,31 @@ | docs/working/papers/SSRN_companion/figures/fig5_bimodal_distributions.pdf | Figure asset: bimodal distributions | CURRENT | Figure asset for the SSRN math companion. | | docs/working/papers/SSRN_companion/figures/fig6_performance_vs_k.pdf | Figure asset: performance vs K | CURRENT | Figure asset for the SSRN math companion. | | docs/working/papers/SSRN_companion/figures/fig7_performance_by_regime.pdf | Figure asset: performance by regime | CURRENT | Figure asset for the SSRN math companion. | -| ./docs/SYSTEM_NARRATIVE.pdf | Compiled PDF of system narrative | CURRENT | Rendered output of `SYSTEM_NARRATIVE.tex`; technical story for patent counsel and reviewers. | -| ./docs/SYSTEM_NARRATIVE.tex | LaTeX source: technical narrative for patent/research review | CURRENT | Well-framed, correctly calibrated narrative; accurate description of the adaptive runtime and 90-run experiment. | +| ./docs/working/papers/SYSTEM_NARRATIVE.pdf | Compiled PDF of system narrative | CURRENT | Rendered output of `SYSTEM_NARRATIVE.tex`; technical story for patent counsel and reviewers. | +| ./docs/working/papers/SYSTEM_NARRATIVE.tex | LaTeX source: technical narrative for patent/research review | CURRENT | Well-framed, correctly calibrated narrative; accurate description of the adaptive runtime and 90-run experiment. | | docs/working/scratch/TASK_LIST.md | AI/human task list with working rules and incremental tasks | WORKING | All tasks are unchecked; likely predates recent physics work; rules section is evergreen but specific tasks may be stale or partially done. | | docs/working/archive/artifacts/kanban-workflow/MANIFEST.adoc | Artifact manifest for kanban workflow validation scripts | HISTORICAL | Tracks process-tooling artifacts from a past workflow setup session; no ongoing relevance to VM or kernel. | | docs/working/scratch/assets/README.md | Binary assets holding area README | WORKING | Correctly flags `book-FIXED.docx` etc. as misplaced; the guidance (move to LFS/external) is still actionable. | | docs/working/scratch/assets/book-FIXED.docx | Book/report Word document | WORKING | Binary asset misplaced in docs/assets; should move to LFS per assets/README.md guidance. | | docs/working/architecture/heartbeat_csv_export.md | Heartbeat CSV export design: format, columns, TODO status | WORKING | Several columns marked `⚠️ TODO`; matches CLAUDE.md note that `heartbeat_export_csv()` is not yet implemented; active design/tracking doc. | -| ./docs/ontology.pdf | Compiled PDF of `ontology.tex` | CURRENT | Rendered output of `ontology.tex`; self-contained reference for academic inclusion. | -| ./docs/ontology.tex | LaTeX source for formal ontology | CURRENT | Source of record matching `ONTOLOGY.md` content; used for journal/conference paper inclusion. | +| ./docs/working/papers/ontology.pdf | Compiled PDF of `ontology.tex` | CURRENT | Rendered output of `ontology.tex`; self-contained reference for academic inclusion. | +| ./docs/working/papers/ontology.tex | LaTeX source for formal ontology | CURRENT | Source of record matching `ONTOLOGY.md` content; used for journal/conference paper inclusion. | | docs/working/archive/prog-prove.pdf | Unknown — likely Isabelle/HOL or proof-assistant tutorial PDF | HISTORICAL | Filename suggests a proof-programming reference; not authored by this project; reference material only. | | docs/working/architecture/getting-started/DEVELOPER.md | Dev environment setup, Isabelle install | CURRENT | Generic setup instructions still match current build system. | | docs/working/architecture/getting-started/README.md | Getting-started index/TOC | CURRENT | Navigation page; links resolve to existing files. | -| docs/working/architecture/getting-started/quick-start/factorial-doe.md | Quick-start for 2^6 per-loop factorial DoE | OBSOLETE | Describes retired `ENABLE_LOOP_1..6` compile-time toggles; replaced by L8 Jacquard runtime mode selector. Hardcoded `/home/rajames/...` paths. | +| docs/working/archive/superseded/factorial-doe/quick-start.md | Quick-start for 2^6 per-loop factorial DoE | OBSOLETE | Describes retired `ENABLE_LOOP_1..6` compile-time toggles; replaced by L8 Jacquard runtime mode selector. Hardcoded `/home/rajames/...` paths. | | docs/working/architecture/getting-started/quick-start/heartbeat-doe.md | Quick-start for heartbeat DoE run | HISTORICAL | Dated 2025-11-20, references a specific completed run directory and hardcoded user paths. | | docs/working/architecture/getting-started/quick-start/optimization-doe.md | Quick-start for 5-opportunity optimization DoE | HISTORICAL | References dated result dirs from a completed tuning campaign; superseded conceptually by L8's data-driven design. | | docs/working/experiments/02-experiments/L8_WIRING_CODE_REVIEW_GUIDE.md | Code review guide for L8 wiring (L2/L3/L5/L6) | HISTORICAL | Dated 2025-12-05; matches current `physics_metadata.c` — completed, accurate review record. | | docs/working/experiments/02-experiments/L8_WIRING_IMPLEMENTATION_SUMMARY.md | Summary of L8 gating implementation | HISTORICAL | Dated 2025-12-05, marked complete; verified consistent with current source. | -| docs/working/experiments/02-experiments/L8_WIRING_PLAN.md | Plan for wiring loops to L8 mode selector | SUPERSEDED | Superseded by L8_WIRING_IMPLEMENTATION_SUMMARY.md and L8_WIRING_CODE_REVIEW_GUIDE.md (plan was executed and reviewed). | +| docs/working/archive/superseded/L8_WIRING_PLAN.md | Plan for wiring loops to L8 mode selector | SUPERSEDED | Superseded by L8_WIRING_IMPLEMENTATION_SUMMARY.md and L8_WIRING_CODE_REVIEW_GUIDE.md (plan was executed and reviewed). | | docs/working/experiments/02-experiments/README.md | Experiments directory index | CURRENT | Accurately lists existing subdirectories. | -| docs/working/experiments/02-experiments/factorial-doe/guide.md | Full 2^6 factorial DoE guide | OBSOLETE | Describes retired per-loop Makefile-toggle architecture, replaced by L8 Jacquard. | -| docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md | Handling incompatible factorial loop configs | OBSOLETE | Build-time incompatibility handling for the retired 2^6 toggle experiment. | -| docs/working/experiments/02-experiments/factorial-doe/index.md | Index for factorial DoE docs | OBSOLETE | Points to stale doc paths; describes retired architecture. | -| docs/working/experiments/02-experiments/factorial-doe/workflow.md | Factorial DoE data pipeline workflow | HISTORICAL | Documents completed 2025-11-19 factorial campaign that produced data behind current L8 design; toggle architecture retired. | -| docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md | Heartbeat DoE corrected metric design | SUPERSEDED | Superseded by phase2-corrected.md ("corrected and finalized" version). | -| docs/working/experiments/02-experiments/heartbeat-doe/design.md | Original Phase 2 heartbeat DoE design | SUPERSEDED | Pre-correction draft; superseded by corrected-design.md / phase2-corrected.md. | +| docs/working/archive/superseded/factorial-doe/guide.md | Full 2^6 factorial DoE guide | OBSOLETE | Describes retired per-loop Makefile-toggle architecture, replaced by L8 Jacquard. | +| docs/working/archive/superseded/factorial-doe/incompatible-configs.md | Handling incompatible factorial loop configs | OBSOLETE | Build-time incompatibility handling for the retired 2^6 toggle experiment. | +| docs/working/archive/superseded/factorial-doe/index.md | Index for factorial DoE docs | OBSOLETE | Points to stale doc paths; describes retired architecture. | +| docs/working/archive/superseded/factorial-doe/workflow.md | Factorial DoE data pipeline workflow | HISTORICAL | Documents completed 2025-11-19 factorial campaign that produced data behind current L8 design; toggle architecture retired. | +| docs/working/archive/superseded/heartbeat-doe-corrected-design.md | Heartbeat DoE corrected metric design | SUPERSEDED | Superseded by phase2-corrected.md ("corrected and finalized" version). | +| docs/working/archive/superseded/heartbeat-doe-design.md | Original Phase 2 heartbeat DoE design | SUPERSEDED | Pre-correction draft; superseded by corrected-design.md / phase2-corrected.md. | | docs/working/experiments/02-experiments/heartbeat-doe/execution-guide.md | How to run Phase 2 heartbeat DoE | HISTORICAL | Dated 2025-11-20, hardcoded stale path; describes running the now-superseded design. | | docs/working/experiments/02-experiments/heartbeat-doe/implementation-summary.md | Deliverables summary for heartbeat DoE | HISTORICAL | Point-in-time "complete" status snapshot dated 2025-11-20 for pre-correction design. | | docs/working/experiments/02-experiments/heartbeat-doe/phase2-corrected.md | Final corrected heartbeat DoE design | WORKING | Latest version in the revision chain; still describes not-yet-fully-implemented work. | @@ -134,27 +134,27 @@ | docs/working/architecture/03-architecture/OVERVIEW.md | Top-level architecture overview (3-layer model, physics loops, boot sequence) | WORKING | Header says "Status: Complete, 2025-12-14" but roadmap still frames StarKernel as "PLANNED"/HAL migration "IN PROGRESS," lagging CLAUDE.md's actual M0-M6-done/M7-in-progress state; needs a refresh pass. | | docs/working/architecture/03-architecture/README.md | Directory index/landing page for 03-architecture/ | WORKING | Shorter duplicate of OVERVIEW.md's roadmap; same staleness (treats StarKernel as not-yet-started); functions as nav index, content needs sync with CLAUDE.md. | | docs/working/architecture/03-architecture/adaptive-systems/adaptive-window-and-decay.md | Root-cause investigation: rolling-window shrink + decay_slope placeholder bugs | HISTORICAL | Dated 2025-11-08, "Root Cause Analysis Complete." Diagnostic/incident report; trigger doc for window-inference-redesign.md. | -| docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md | Alternate Loop #5 proposal: prefetch-accuracy-driven binary-chop window tuning | SUPERSEDED | Superseded by window-inference-redesign.md. Undated draft ending in an open question to the user (never approved); the shipped Loop #5 uses Levene's test, not this mechanism. | +| docs/working/archive/superseded/loop-5-sketch.md | Alternate Loop #5 proposal: prefetch-accuracy-driven binary-chop window tuning | SUPERSEDED | Superseded by window-inference-redesign.md. Undated draft ending in an open question to the user (never approved); the shipped Loop #5 uses Levene's test, not this mechanism. | | docs/working/architecture/03-architecture/adaptive-systems/multivariate-dynamics.md | Phase 2 DoE experiment design: multivariate stability fingerprinting across 7 metrics | WORKING | Dated 2025-11-20, "Status: Design Phase." Forward-looking proposal tied to still-unimplemented heartbeat instrumentation. | | docs/working/architecture/03-architecture/adaptive-systems/window-inference-redesign.md | Redesign of window-width inference using Levene's test on disjoint chunks | CURRENT | Dated 2025-11-19, "DESIGN (approved for implementation)." Matches the Loop #5/#6 mechanism CLAUDE.md/OVERVIEW.md describe as actually implemented (inference_engine.c). | -| docs/working/architecture/03-architecture/hal/README.md | Index/reading-order guide for HAL doc set | WORKING | Status table claims all 5 HAL docs "Complete, 2025-12-14," but describes target architecture per overview.md's own disclaimer, not built code; misleading without that caveat. | -| docs/working/architecture/03-architecture/hal/interfaces.md | hal_* C interface contract spec (time, interrupt, memory, console, cpu, panic) | WORKING | Normative target API design; current codebase uses sf_time_backend_t-style naming per overview.md — this HAL layer is not yet built as specified. | -| docs/working/architecture/03-architecture/hal/migration-plan.md | 7-phase plan to migrate codebase to hal_* interfaces | WORKING | Forward plan ("Phase 2 IN PROGRESS" per roadmap); CLAUDE.md's current source tree shows this migration not yet executed. | -| docs/working/architecture/03-architecture/hal/overview.md | HAL rationale/design-principles doc | WORKING | Contains the key disclaimer: "current codebase uses sf_time_backend_t... different naming" — explicitly flags the whole HAL doc family as target/aspirational, not current. | -| docs/working/architecture/03-architecture/hal/platform-implementations.md | Example hal_* implementations for Linux and kernel platforms | OBSOLETE | Assumes src/platform//hal_*.c layout; actual built StarKernel tree (per CLAUDE.md) uses src/starkernel/{arch,boot,capsule,hal,memory,...} — a different, already-implemented structure. | -| docs/working/architecture/03-architecture/hal/starkernel-integration.md | Kernel HAL integration guide, src/platform/kernel/ layout, milestone roadmap to "ok" prompt | OBSOLETE | Describes Milestone 1 "Boot + Serial Output" as a starting point; LithosAnanke is actually at v1.0.8 with M0-M6 complete, M7 in progress, using a wholly different src/starkernel/ directory structure. | +| docs/working/archive/dead/hal-target-contract/README.md | Index/reading-order guide for HAL doc set | WORKING | Status table claims all 5 HAL docs "Complete, 2025-12-14," but describes target architecture per overview.md's own disclaimer, not built code; misleading without that caveat. | +| docs/working/archive/dead/hal-target-contract/interfaces.md | hal_* C interface contract spec (time, interrupt, memory, console, cpu, panic) | WORKING | Normative target API design; current codebase uses sf_time_backend_t-style naming per overview.md — this HAL layer is not yet built as specified. | +| docs/working/archive/dead/hal-target-contract/migration-plan.md | 7-phase plan to migrate codebase to hal_* interfaces | WORKING | Forward plan ("Phase 2 IN PROGRESS" per roadmap); CLAUDE.md's current source tree shows this migration not yet executed. | +| docs/working/archive/dead/hal-target-contract/overview.md | HAL rationale/design-principles doc | WORKING | Contains the key disclaimer: "current codebase uses sf_time_backend_t... different naming" — explicitly flags the whole HAL doc family as target/aspirational, not current. | +| docs/working/archive/dead/hal-target-contract/platform-implementations.md | Example hal_* implementations for Linux and kernel platforms | OBSOLETE | Assumes src/platform//hal_*.c layout; actual built StarKernel tree (per CLAUDE.md) uses src/starkernel/{arch,boot,capsule,hal,memory,...} — a different, already-implemented structure. | +| docs/working/archive/dead/hal-target-contract/starkernel-integration.md | Kernel HAL integration guide, src/platform/kernel/ layout, milestone roadmap to "ok" prompt | OBSOLETE | Describes Milestone 1 "Boot + Serial Output" as a starting point; LithosAnanke is actually at v1.0.8 with M0-M6 complete, M7 in progress, using a wholly different src/starkernel/ directory structure. | | docs/working/architecture/03-architecture/heartbeat-system/architecture.md | Proposes vm_tick() dispatcher centralizing Loop #3/#5 heartbeat logic | HISTORICAL | No date; ends in an open question, never confirmed adopted. Foundational rationale doc; superseded in specifics by instrumentation-plan.md's HeartbeatTickSnapshot design. | | docs/working/architecture/03-architecture/heartbeat-system/critical-insight.md | Discovery memo: heartbeat tick rate is variable, not fixed; Stage 1 DoE baseline was flawed | HISTORICAL | Dated 2025-11-20, "Game-changer for Phase 2 DoE." Point-in-time investigation memo that directly motivated implementation-plan.md. | -| docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md | Plan for HeartbeatRateSample logging to capture variable tick rate | SUPERSEDED | Superseded by instrumentation-plan.md. Same date (2025-11-20) and goal, but proposes an earlier/different struct (HeartbeatRateSample) than the HeartbeatTickSnapshot design CLAUDE.md cites as the live target. | +| docs/working/archive/superseded/heartbeat-rate-logging-plan.md | Plan for HeartbeatRateSample logging to capture variable tick rate | SUPERSEDED | Superseded by instrumentation-plan.md. Same date (2025-11-20) and goal, but proposes an earlier/different struct (HeartbeatRateSample) than the HeartbeatTickSnapshot design CLAUDE.md cites as the live target. | | docs/working/architecture/03-architecture/heartbeat-system/instrumentation-plan.md | Per-tick instrumentation plan: HeartbeatTickSnapshot, tick_buffer, heartbeat_export_csv() | WORKING | Explicitly the doc CLAUDE.md cites as current ("declared in include/vm.h, but heartbeat_export_csv() is not yet implemented"). Checklist entirely unchecked. | | docs/working/architecture/03-architecture/heartbeat-system/segfault-analysis.md | Root-cause analysis of heartbeat-thread/main-thread race on RollingWindowOfTruth | HISTORICAL | Dated 2025-11-19, "Identified & Ready for Fix," includes a past-tense commit-message template implying the tuning_lock fix was applied. No current doc mentions this race as open. | -| docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md | Investigative bug-hunt audit of 6 feedback loops (precursor to the 7-loop model) | SUPERSEDED | Superseded by feedback-loops.md. Dated 2025-11-08, full of strikethrough "FIXED" headers; covers only 6 loops, unlike the polished current 7-loop reference. | +| docs/working/archive/superseded/feedback-loops-analysis.md | Investigative bug-hunt audit of 6 feedback loops (precursor to the 7-loop model) | SUPERSEDED | Superseded by feedback-loops.md. Dated 2025-11-08, full of strikethrough "FIXED" headers; covers only 6 loops, unlike the polished current 7-loop reference. | | docs/working/architecture/03-architecture/physics-engine/feedback-loops.md | Canonical reference: all 7 feedback loops, tuning knobs, related source files | CURRENT | Matches CLAUDE.md's explicit citation ("all 7 loops detailed") verbatim; clean finished reference table covering Loops #1-7 including #5/#6 inference. | -| docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md | Gap-analysis backlog of metrics not yet collected (stack depth, bucket histograms, etc.) | WORKING | Explicitly self-titled "GAPS ONLY"; prioritized TODO backlog, not a current-state description; some gaps may have since been filled. | +| docs/working/archive/dead/metrics-and-knobs.md | Gap-analysis backlog of metrics not yet collected (stack depth, bucket histograms, etc.) | WORKING | Explicitly self-titled "GAPS ONLY"; prioritized TODO backlog, not a current-state description; some gaps may have since been filled. | | docs/working/architecture/03-architecture/physics-engine/monitoring-principles.md | Doctrinal rules for non-perturbative monitoring instrumentation | CURRENT | Presents itself as binding/evergreen ("canonical rules for ALL AI assistants"); uses an older "four core loops (FL1-FL4)" framing that should be reconciled with the current 7-loop model, but the doctrine itself remains in force. | | docs/working/architecture/03-architecture/physics-engine/ssm-equations.md | Exploratory mathematical modeling of SSM via physics analogies for patent/DARPA strategy | HISTORICAL | Dated 2025-11-29, self-labeled "Status: Research Analysis - Exploratory." Predates Jacquard naming; speculates generically about future "L8" without Jacquard/attractor-bucket/mode-name vocabulary. | | docs/working/architecture/03-architecture/physics-engine/ssm-raw-data-analysis.md | Raw experimental data analysis from a specific Nov 22-27 2025 DoE campaign (51,840 runs) | HISTORICAL | Dated 2025-11-29; tied to specific named CSV files and a calendar-based "Next Steps" plan. Uses "L8" and 4 of 6 Jacquard mode names but never "Jacquard" — an early/transitional naming stage. | -| docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md | Formal theoretical definition of SSM as a computational model (attractor basins, axioms) | OBSOLETE | Zero mentions of "Jacquard," "L8," "attractor bucket," or the six named modes from CLAUDE.md; reads as a conceptual precursor never reconciled with the concrete ssm_jacquard.c system. | +| docs/working/archive/superseded/steady-state-machine.md | Formal theoretical definition of SSM as a computational model (attractor basins, axioms) | OBSOLETE | Zero mentions of "Jacquard," "L8," "attractor bucket," or the six named modes from CLAUDE.md; reads as a conceptual precursor never reconciled with the concrete ssm_jacquard.c system. | | docs/working/architecture/03-architecture/pipelining/context-window-and-binary-chop.md | Context-window infrastructure (Knob #6) + planned binary-chop tuning for Loop #4 | WORKING | Dated 2025-11-06, "Phase 1 Extension Complete," but binary-chop decision logic explicitly a doubling-rule stub with "Phase 2 (Next session)" unchecked; corroborated as still-unutilized by wired-not-utilized.md. | | docs/working/architecture/03-architecture/pipelining/design.md | Master architectural design for pipelining/speculative execution (Loop #4) | HISTORICAL | No date/status stamp; entirely aspirational ("Goal:", "Hypothesis"); Phase 3+ (actual prefetching/speculation) roadmap items remain unchecked and appear unrealized per wired-not-utilized.md. | | docs/working/architecture/03-architecture/pipelining/phase-1-instrumentation.md | Completed-checkpoint record of Phase 1 transition-tracking instrumentation | HISTORICAL | Dated 2025-11-06, "Phase 1 Complete," 731 tests passing — accurate closed record of one sub-phase; its Phase 2-4 TODOs were never closed per wired-not-utilized.md. | @@ -229,7 +229,7 @@ | ./docs/patent/final_provisional/sb0016.pdf | USPTO form SB0016 — filed copy | CURRENT | Differs from root `sb0016.pdf` (577171 vs 557654 bytes); this larger copy is the filed/submitted version and is the more complete document. | | ./docs/patent/final_provisional/ssm_RAJ_v1_patent_application.pdf | Compiled patent application PDF — filed copy | SUPERSEDED | Byte-identical to root `ssm_RAJ_v1_patent_application.pdf` (1735085 bytes); root copy is the working canonical version. | | docs/working/scratch/src/INTEGRATION_NOTES.adoc | StarForth↔StarshipOS sync scripts (integrator.sh) | HISTORICAL | Describes ad-hoc integrator.sh scripts and one-day debugging session; superseded by formal capsule/build pipeline in current CLAUDE.md. Worth keeping as record of integration approach. | -| docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc | L4Re integration checklist, hardcoded local paths | OBSOLETE | References absolute local dev paths (`/home/rajames/CLionProjects/...`) and a TODO checklist for copying platform files; current architecture has moved on. | +| docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc | L4Re integration checklist, hardcoded local paths | OBSOLETE | References absolute local dev paths (`/home/rajames/CLionProjects/...`) and a TODO checklist for copying platform files; current architecture has moved on. | | docs/working/scratch/src-index.adoc | docs/src documentation index | WORKING | Active index/TOC for the docs/src tree, but contains multiple dead links (ABI.adoc, BLOCK_STORAGE_GUIDE.adoc, WORD_DEVELOPMENT.adoc, TESTING.adoc, BREAK_ME_REPORT.adoc, GAP_ANALYSIS.adoc) — needs pruning/repair. | | docs/working/architecture/architecture-internals/INIT_SYSTEM.adoc | INIT system / conf/init.4th boot mechanism | CURRENT | Describes init.4th, INIT word, dictionary fence — matches current capsule/init architecture described in CLAUDE.md. | | docs/working/architecture/architecture-internals/MESSAGING.adoc | Thermodynamic "Message Field" model for StarshipOS IPC | WORKING | Forward-looking design doc for a not-yet-implemented StarshipOS messaging subsystem; consistent with physics/thermodynamic metaphor language. | @@ -270,11 +270,11 @@ | docs/working/hardware/performance-profiling/ARM64_OPTIMIZATIONS.adoc | ARM64 assembly optimization summary | CURRENT | Referenced headers (`include/vm_asm_opt_arm64.h`, `vm_inner_interp_arm64.h`, `arch_detect.h`) all confirmed present in current `include/` tree. | | docs/working/hardware/performance-profiling/ASM_OPTIMIZATIONS.adoc | x86_64 assembly optimization guide | CURRENT | Referenced headers (`vm_asm_opt.h`, `vm_inner_interp_asm.h`) confirmed present; consistent with `USE_ASM_OPT=1` build flag in current CLAUDE.md. | | docs/working/hardware/performance-profiling/PROFILER.adoc | Built-in word-execution profiler guide | CURRENT | Describes profiler integrated with PGO pipeline; consistent with `make test PROFILE=1` and `profiler.c` present in current src tree. | -| docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc | Dictionary allocation strategy proposal for L4Re | WORKING | References `src/dictionary_management.c:228` (`vm_create_word()` malloc) and `defining_words.c:554` (`FORGET` free) — both locations exist; malloc/free dependency has likely not yet been replaced with L4Re-native allocator. | -| docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc | General L4Re integration guide (IPC, dataspaces, package structure) | WORKING | Broad integration guide; L4Re remains a supported platform per CLAUDE.md tech stack diagram. | +| docs/working/archive/dead/l4re/L4RE_DICTIONARY_ALLOCATION.adoc | Dictionary allocation strategy proposal for L4Re | WORKING | References `src/dictionary_management.c:228` (`vm_create_word()` malloc) and `defining_words.c:554` (`FORGET` free) — both locations exist; malloc/free dependency has likely not yet been replaced with L4Re-native allocator. | +| docs/working/archive/dead/l4re/L4RE_INTEGRATION.adoc | General L4Re integration guide (IPC, dataspaces, package structure) | WORKING | Broad integration guide; L4Re remains a supported platform per CLAUDE.md tech stack diagram. | | docs/working/hardware/platform-integration/PLATFORM_ABSTRACTION.adoc | Platform abstraction layer (vtable pattern for POSIX/L4Re) | CURRENT | Matches actual `platform/linux/time.c` and `platform/l4re/time.c` files present in current src tree per CLAUDE.md source tree listing. | | docs/working/hardware/platform-integration/RASPBERRY_PI_BUILD.adoc | Raspberry Pi 4 / ARM64 build guide | CURRENT | Matches `rpi4-cross` Makefile target and ARM64 architecture support (`ARCH=raspi`) listed in current CLAUDE.md build targets. | -| docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc | Block I/O L4Re porting endpoints (blkio vtable mapping) | CURRENT | Describes `blkio_open/close/read` vtable API; matches `blkio_*.c` backend files listed in current CLAUDE.md source tree. | +| docs/working/archive/dead/l4re/l_4_re_blkio_endpoints.adoc | Block I/O L4Re porting endpoints (blkio vtable mapping) | CURRENT | Describes `blkio_open/close/read` vtable API; matches `blkio_*.c` backend files listed in current CLAUDE.md source tree. | | docs/working/scratch/testing-quality/KANBAN-WORKFLOW-VALIDATION.adoc | Validation procedure for GitHub Projects Kanban automation (CAPA-032) | CURRENT | Dated 2025-11-02 with explicit source commit hash; references `.github/workflows/capa-kanban-sync.yml` which is a concrete CI artifact. | | docs/working/archive/legacy/OPTIMIZATION_OPPORTUNITIES.md | Physics engine optimization opportunity ranking dated 2025-11-19 | SUPERSEDED | Superseded by docs/03-architecture/physics-engine/ and Loop #5/#6 implementations | | docs/working/archive/legacy/README.md | Index and usage guide for the docs/archive directory | CURRENT | Self-referential; accurately describes the archive's purpose and sub-structure | @@ -290,7 +290,7 @@ | docs/working/archive/legacy/phase-1/Reference/PHASE_1_TESTING_RESULTS.md | Phase 1 testing results summary | HISTORICAL | Test results from Phase 1 CI/governance work | | docs/working/archive/legacy/phase-1/Reference/PHYSICS_EXPERIMENT_README.md | README for the 90-run physics validation experiment | HISTORICAL | Companion README to the experiment data in physics_experiment/ | | docs/working/archive/legacy/phase-1/Reference/RULE_1_GATES_IMPLEMENTATION.md | Implementation notes for Rule 1 CI gating | HISTORICAL | CI gate design decisions from Phase 1 | -| docs/working/archive/legacy/phase-1/Reference/SECURITY.md | Security notes predating the ACL system | HISTORICAL | Pre-ACL security model; superseded by docs/03-architecture/word-acl/DESIGN.md | +| docs/working/archive/legacy/phase-1/Reference/SECURITY.md | Security notes predating the ACL system | HISTORICAL | Pre-ACL security model; superseded by docs/reference/word-acl/DESIGN.md | | docs/working/archive/legacy/phase-1/Reference/SESSION_SUMMARY.md | Transient AI session summary | HISTORICAL | Session-level notes; limited long-term value | | docs/working/archive/legacy/phase-1/Reference/TEST-CAPA-TEMPLATE.md | CAPA test case template | HISTORICAL | Template used during Phase 1 CAPA process | | docs/working/archive/legacy/phase-1/Reference/codex_audit_report.md | Codex audit report of the codebase | HISTORICAL | Point-in-time static analysis or review; may be stale | diff --git a/docs/book/Makefile b/docs/book/Makefile index 43481d7c..99ff1eae 100644 --- a/docs/book/Makefile +++ b/docs/book/Makefile @@ -30,8 +30,8 @@ PANDOC_FLAGS := -f gfm -t latex --top-level-division=chapter --wrap=preserve \ # fragment name : Markdown source. The order of \input lines is main.tex's. CHAPTERS := \ - ontology:docs/ONTOLOGY.md \ - roadmap:docs/ROADMAP.md \ + ontology:docs/reference/ONTOLOGY.md \ + roadmap:docs/working/archive/superseded/2025-12-14-starforth-roadmap.md \ boards:boards/README.md \ justification:docs/v4.0.0/JUSTIFICATION.md \ decomposition:docs/v4.0.0/DECOMPOSITION.md \ diff --git a/docs/book/main.tex b/docs/book/main.tex index 5435e9dc..cbce2066 100644 --- a/docs/book/main.tex +++ b/docs/book/main.tex @@ -122,8 +122,8 @@ are reproduced as written, including their struck-through corrections. Chapter & Source \\ \midrule \endhead -Ontology & \texttt{docs/ONTOLOGY.md} \\ -Roadmap & \texttt{docs/ROADMAP.md} \\ +Ontology & \texttt{docs/reference/ONTOLOGY.md} \\ +Roadmap & \texttt{docs/working/archive/superseded/2025-12-14-starforth-roadmap.md} \\ Boot targets & \texttt{boards/README.md} \\ v4 justification & \texttt{docs/v4.0.0/JUSTIFICATION.md} \\ v4 decomposition & \texttt{docs/v4.0.0/DECOMPOSITION.md} \\ diff --git a/docs/fabric/FABRIC-0.md b/docs/fabric/FABRIC-0.md index 0035e950..f91b4f35 100644 --- a/docs/fabric/FABRIC-0.md +++ b/docs/fabric/FABRIC-0.md @@ -34,7 +34,7 @@ an unrelated structure. The document has been swept; "arena" now survives only i quotes that reproduce an earlier section verbatim, and in §12's preserved question list, which several sections quote. -**On `docs/lithosananke/ROADMAP.md`.** As of 2026-08-11, Captain Bob stated this document +**On `docs/reference/ROADMAP.md`.** As of 2026-08-11, Captain Bob stated this document superseded ROADMAP.md entirely. That still holds, transitively, through `FABRIC-1.md` now. --- @@ -4425,7 +4425,7 @@ document and committing that amendment as its own item.* > `#ifdef __STARKERNEL__`, or elsewhere is an open question for that later item, not > decided here. > - > **Now scoped, 2026-08-11 — resolved in `docs/lithosananke/ROADMAP.md`'s M8 section, + > **Now scoped, 2026-08-11 — resolved in `docs/reference/ROADMAP.md`'s M8 section, > not here.** M8 is "tracked outside Stadium" per §27.5, and its console-facing pieces > don't change this document's own scope, so the resolution lives there rather than as > new 4.3.x items. Short answer to the open question above: `io_words.c` under @@ -4999,7 +4999,7 @@ document and committing that amendment as its own item.* > decision #4 -- both text paths coexist. Per this item's own posture (matching 4.3.6g), > stopping here before scoping REPL wiring (M8). > - > **M8 scoped 2026-08-11 in `docs/lithosananke/ROADMAP.md`, not here** -- per §27.5, M8 is + > **M8 scoped 2026-08-11 in `docs/reference/ROADMAP.md`, not here** -- per §27.5, M8 is > tracked outside Stadium, so its design decisions live in that roadmap's own M8 section > rather than as new 4.3.x items. Key finding from that scoping pass, worth recording in > this document too since it bears on §27.6's CANVAS/REPL-strip framing: the REPL's @@ -5939,7 +5939,7 @@ document and committing that amendment as its own item.* exactly that — no scancode-to-ASCII translation table exists, and no code path connects the keyboard ring buffer to the REPL's line-read loop. The hardware/interrupt layer is done; the bridge from that layer into text the REPL can act on is not. This is the same conclusion - `docs/lithosananke/ROADMAP.md`'s M8 section and this document's own 4.3.5-series entries + `docs/reference/ROADMAP.md`'s M8 section and this document's own 4.3.5-series entries already recorded ("no keyboard path into the VM on any architecture, confirmed by reading the code") — restated here specifically so 4.4u's TAB-toggle has an accurate prerequisite, not because the earlier conclusion was in doubt. @@ -5957,7 +5957,7 @@ document and committing that amendment as its own item.* keyboard event injected via QEMU's own input-send-event monitor command (not socat/serial), screendump showing the typed text landed in the REPL strip; three-arch QEMU boot + logs per CLAUDE.md. - *Refs:* §27.8, 4.3.5 series, 4.4r, 4.4u, `docs/lithosananke/ROADMAP.md` M8 section. + *Refs:* §27.8, 4.3.5 series, 4.4r, 4.4u, `docs/reference/ROADMAP.md` M8 section. > **DONE 2026-08-12.** Reused item 4.3.5f's `KEY-EVENT` convergence work rather than building > two per-arch tables from scratch (`kbw_key_event`'s FORTH-word logic was refactored into a @@ -7549,7 +7549,7 @@ direct-arena reference — 4.3.7b's own call) behind that lookup. ### 27.8 REPL: prompt, text path, CANVAS geometry (4.4–4.4s) -Scoped 2026-08-11, in conversation with Captain Bob, replacing `docs/lithosananke/ROADMAP.md`'s +Scoped 2026-08-11, in conversation with Captain Bob, replacing `docs/reference/ROADMAP.md`'s M8 section entirely (marked OBSOLETE there, kept for history only). Original visual reference: [`repl-mockup.png`](repl-mockup.png). diff --git a/docs/fabric/FABRIC-1.md b/docs/fabric/FABRIC-1.md index 17dde731..1a668f66 100644 --- a/docs/fabric/FABRIC-1.md +++ b/docs/fabric/FABRIC-1.md @@ -1425,14 +1425,14 @@ evidence nothing regressed. `docs/CLAUDE.md`'s own correction, made in the same pass, for the doc-toolchain findings — `doxygen` installed, `docs/Makefile` pointer corrected — and this section's own proof-count reconciliation above for the Isabelle/HOL findings): -- [ ] `docs/lithosananke/ROADMAP.md` and `M7.1.md` — stale `Branch: lithosananke` (no such +- [ ] `docs/reference/ROADMAP.md` and `M7.1.md` — stale `Branch: lithosananke` (no such branch exists post-split), `M7.1.md`'s "Status: Design Complete" (shipped and live, not just designed), `ROADMAP.md`'s self-contradiction (M8 marked OBSOLETE in one place, still a live success criterion in another), and its stale "AHCI driver" claim for M9 (real implementation is `virtio_blk.c`) — not fixed this pass, flagged. - [ ] Top-level `ROADMAP.md` (StarForth-era, "Phase 0 Complete... Phase 1 Starting," dated 2025-12-14) — badly stale, no historical/superseded banner to warn a reader. Not fixed. -- [ ] `docs/03-architecture/word-acl/DESIGN.md` says ACL Phase 7 (LithosAnanke kernel parity) +- [ ] `docs/reference/word-acl/DESIGN.md` says ACL Phase 7 (LithosAnanke kernel parity) is still "remaining" — direct contradiction with `.claude/CLAUDE.md`, which states Phase 7 is independently verified complete. Not fixed. - [ ] `VM-FLEET-ATTRACTOR-DESIGN-20260705.md` claims `doe-campaign.4th` is "broken and being diff --git a/docs/fabric/FABRIC-2.md b/docs/fabric/FABRIC-2.md index 96dee3e0..4fee444d 100644 --- a/docs/fabric/FABRIC-2.md +++ b/docs/fabric/FABRIC-2.md @@ -102,7 +102,7 @@ decisions get added here, not to `FABRIC-1.md`. Follow the same discipline `FABR ### From FABRIC-1.md §J — Maintainability sweep (2026-08-18) - [x] **Fixed 2026-08-26 (commit `cbe7b49`), stale carry-forward closed 2026-08-28.** - `docs/lithosananke/ROADMAP.md` and `M7.1.md` — stale `Branch: lithosananke` (no such + `docs/reference/ROADMAP.md` and `M7.1.md` — stale `Branch: lithosananke` (no such branch exists post-split), `M7.1.md`'s "Status: Design Complete" (shipped and live, not just designed), `ROADMAP.md`'s self-contradiction (M8 marked OBSOLETE in one place, still a live success criterion in another), and its stale "AHCI driver" claim for M9 (real @@ -112,10 +112,10 @@ decisions get added here, not to `FABRIC-1.md`. Follow the same discipline `FABR - [x] **Fixed 2026-08-26 (commit `cbe7b49`), stale carry-forward closed 2026-08-28.** Top-level `ROADMAP.md` (StarForth-era, "Phase 0 Complete... Phase 1 Starting," dated 2025-12-14) — marked OBSOLETE by `cbe7b49` (Captain Bob's call: more than stale), pointing - to `docs/lithosananke/ROADMAP.md` and `FABRIC*.md` for current status. + to `docs/reference/ROADMAP.md` and `FABRIC*.md` for current status. - [x] **Fixed 2026-08-26 (commit `cbe7b49`), stale carry-forward closed 2026-08-28.** - `docs/03-architecture/word-acl/DESIGN.md` says ACL Phase 7 (LithosAnanke kernel parity) + `docs/reference/word-acl/DESIGN.md` says ACL Phase 7 (LithosAnanke kernel parity) is still "remaining" — direct contradiction with `.claude/CLAUDE.md`, which states Phase 7 is independently verified complete. Phase 7 restated as independently-verified complete and the stale lithosananke-branch-parity framing removed by `cbe7b49`. @@ -3434,7 +3434,7 @@ hardware), the **release-gate recommendation**, and the **punch lists to complet each. **The versioning split, decided 2026-08-28 — now standing policy, see -`docs/lithosananke/ROADMAP.md` "Release Versioning Policy" for the authoritative form.** +`docs/reference/ROADMAP.md` "Release Versioning Policy" for the authoritative form.** v2.0.0 is the **QEMU release** — the point where the QEMU-only story is complete and defensible on its own terms. v2.5.0 is the **real-hardware release** — the point where the same story transfers to bare metal on a real diff --git a/docs/fabric/FABRIC-3.5.md b/docs/fabric/FABRIC-3.5.md index 3b047e31..8cc4765c 100644 --- a/docs/fabric/FABRIC-3.5.md +++ b/docs/fabric/FABRIC-3.5.md @@ -2489,13 +2489,13 @@ describe are stripped** (§XXII.5), so the manifest never describes a file that **Superseded subsystem docs** — `.claude/TRIPOD.md`, `HERMES.md`, `ARTEMIS.md`, `CONSOLE.md` already carry superseded headers, but after this reshuffle they describe a fleet that no longer -exists. Same for `docs/03-architecture/tripod/{TRIPOD,HERMES,ARTEMIS,README}.md`, which +exists. Same for `docs/working/archive/superseded/2026-08-tripod/{TRIPOD,HERMES,ARTEMIS,README}.md`, which `.claude/CLAUDE.md` still lists as current for Tripod. **Decide deliberately: update, or mark archival and point at `FABRIC-3.5.md`.** Not a silent edit either way. **Also in scope:** `capsules/README.md` (lists `hermes/init.4th` as a live personality), -`ROADMAP.md` / `docs/lithosananke/ROADMAP.md`, `CHANGELOG.md`, `README.md`, -`docs/lithosananke/SYSTEM_ARCHITECTURE.md` and `M7.1.md`, and `proof/COVERAGE.md` (after the +`ROADMAP.md` / `docs/reference/ROADMAP.md`, `CHANGELOG.md`, `README.md`, +`docs/working/archive/historical/2026-01-27-system-architecture-draft.md` and `M7.1.md`, and `proof/COVERAGE.md` (after the §XXV pass — and per §XXV.3 its *boundary* statement matters more than its file count). `capsules/BLOCK_MAP.md` is a generated artifact; regenerate, don't hand-edit. @@ -2705,7 +2705,7 @@ the version number (§XXVI.3).** No code is authorized. table in `Makefile.starkernel` itself (lines ~74–82), which is more specific: ``` -# Roadmap (per docs/lithosananke/ROADMAP.md "Release Versioning Policy" and +# Roadmap (per docs/reference/ROADMAP.md "Release Versioning Policy" and # FABRIC-2.md §G — X.0.0 = QEMU release, X.5.0 = hardware bare-metal release): # v1.0.x — serial-only production (released) # v1.5.x — framebuffer VT100 terminal/console milestone (released) @@ -2736,7 +2736,7 @@ will step 2.0.1 → 2.2.0 with a released `v2.1.0` tag sitting in a gap the tabl mention. **Add the line wherever the table lives:** 1. `Makefile.starkernel` (the copy above, beside the `LITHOS_VERSION` edit itself). -2. `docs/lithosananke/ROADMAP.md`, "Release Versioning Policy" — the comment names it as the +2. `docs/reference/ROADMAP.md`, "Release Versioning Policy" — the comment names it as the upstream source. 3. `FABRIC-2.md` §G is the origin of the scheme but is **CLOSED/ARCHIVAL** — **cite it, do not edit it.** Amending a closed document to match a later decision is exactly what this series' @@ -3011,7 +3011,7 @@ removed 2026-08-15 as non-functional and must not be resurrected. - ✅ **Versioning policy — CLOSED** (§XXX). All three §XXIX.3 conflicts resolved; LTS criteria ratified; engine `VERSION` closed as a rule. - ✅ **This release is `2.1.0`** (§XXVIII), even major, working line. -- ⬜ **Carry §XXX.1–XXX.6 into `Makefile.starkernel` and `docs/lithosananke/ROADMAP.md`** +- ⬜ **Carry §XXX.1–XXX.6 into `Makefile.starkernel` and `docs/reference/ROADMAP.md`** (§XXVIII.2), replacing the old roadmap table. `FABRIC-2.md` §G is cited, never edited. - ⬜ Engine `VERSION` applied at tag time per §XXX.6's rule. diff --git a/docs/fabric/FABRIC-3.6.md b/docs/fabric/FABRIC-3.6.md index 4409bddc..0944b091 100644 --- a/docs/fabric/FABRIC-3.6.md +++ b/docs/fabric/FABRIC-3.6.md @@ -1484,7 +1484,7 @@ opposite of what per-task commits are for. Tasks 5.5–5.7 return to one-commit- `PLOT`/`FB-*` relocated to Hestia; no FORTH-79 word semantics changed). The stale version-comment block in `Makefile.starkernel` (which still said "even major = LTS" — backwards relative to the ratified §XXX.1 odd/even rule — and had no `v2.1.0` entry) - replaced with the real ladder. `docs/lithosananke/ROADMAP.md`'s own "Release Versioning + replaced with the real ladder. `docs/reference/ROADMAP.md`'s own "Release Versioning Policy" section (the second of the two live places) was still the full retired 2026-08-28 policy, not just a stale table — replaced with the ratified §XXX policy text, the old text kept struck-through in a `
` block for traceability, and the diff --git a/docs/fabric/FABRIC-3.md b/docs/fabric/FABRIC-3.md index a5a597f5..dfbd4e9f 100644 --- a/docs/fabric/FABRIC-3.md +++ b/docs/fabric/FABRIC-3.md @@ -5499,7 +5499,7 @@ device it was minted on. - Build a **new, blank 1 GiB `disk/artemis.img`** from scratch -- not a resize of the current file. No migration code written or needed. - **Zuse re-minted fresh** on the new image (genesis marker, root CA placement, per - `docs/03-architecture/word-acl/DESIGN.md`'s Phase 8 design and + `docs/reference/word-acl/DESIGN.md`'s Phase 8 design and `project_phase8_milestone6_complete.md`'s already-verified entropy/signing/block-fence chain -- same mechanism, new device, not new code). - **All 8 thumbdrive identities re-minted** (`project_thumbdrive_identities_minted_20260906.md`: diff --git a/docs/formal/experiments/main.tex b/docs/formal/experiments/main.tex index 101dde4b..b5b5961c 100644 --- a/docs/formal/experiments/main.tex +++ b/docs/formal/experiments/main.tex @@ -48,7 +48,7 @@ \part{$2^7$ Factorial Campaign} \chapter{Campaign Design} -%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/guide.md +%% SOURCE: docs/working/archive/superseded/factorial-doe/guide.md %% docs/working/experiments/campaigns/doe_2x7/README.md \input{../scraps/experiments/02-experiments/factorial-doe/guide} \input{../scraps/experiments/02-experiments/factorial-doe/workflow} @@ -57,7 +57,7 @@ \input{../scraps/experiments/campaigns/shape_validation/README} \chapter{Incompatible Configurations} -%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md +%% SOURCE: docs/working/archive/superseded/factorial-doe/incompatible-configs.md \input{../scraps/experiments/02-experiments/factorial-doe/incompatible-configs} \chapter{Campaign Results — 90 Runs} @@ -146,8 +146,8 @@ \part{Supplementary Campaigns} \chapter{Heartbeat DoE} -%% SOURCE: docs/working/experiments/02-experiments/heartbeat-doe/design.md -%% docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md +%% SOURCE: docs/working/archive/superseded/heartbeat-doe-design.md +%% docs/working/archive/superseded/heartbeat-doe-corrected-design.md \input{../scraps/experiments/02-experiments/heartbeat-doe/design} \input{../scraps/experiments/02-experiments/heartbeat-doe/corrected-design} \input{../scraps/experiments/02-experiments/heartbeat-doe/implementation-summary} diff --git a/docs/formal/scraps/architecture/03-architecture/adaptive-systems/loop-5-sketch.tex b/docs/formal/scraps/architecture/03-architecture/adaptive-systems/loop-5-sketch.tex index d396addd..90b5c9a7 100644 --- a/docs/formal/scraps/architecture/03-architecture/adaptive-systems/loop-5-sketch.tex +++ b/docs/formal/scraps/architecture/03-architecture/adaptive-systems/loop-5-sketch.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/adaptive-systems/loop-5-sketch -%% SOURCE: docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md +%% SOURCE: docs/working/archive/superseded/loop-5-sketch.md %% STATUS: WORKING %% FITS: dev-guide/ch-physics %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/hal/README.tex b/docs/formal/scraps/architecture/03-architecture/hal/README.tex index df8bf8ea..86d96c5e 100644 --- a/docs/formal/scraps/architecture/03-architecture/hal/README.tex +++ b/docs/formal/scraps/architecture/03-architecture/hal/README.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/hal/README -%% SOURCE: docs/working/architecture/03-architecture/hal/README.md +%% SOURCE: docs/working/archive/dead/hal-target-contract/README.md %% STATUS: WORKING %% FITS: dev-guide/ch-platform %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/hal/interfaces.tex b/docs/formal/scraps/architecture/03-architecture/hal/interfaces.tex index 43c0eea3..469ff2dd 100644 --- a/docs/formal/scraps/architecture/03-architecture/hal/interfaces.tex +++ b/docs/formal/scraps/architecture/03-architecture/hal/interfaces.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/hal/interfaces -%% SOURCE: docs/working/architecture/03-architecture/hal/interfaces.md +%% SOURCE: docs/working/archive/dead/hal-target-contract/interfaces.md %% STATUS: WORKING %% FITS: dev-guide/ch-platform %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/hal/migration-plan.tex b/docs/formal/scraps/architecture/03-architecture/hal/migration-plan.tex index d93ae4c3..640017a5 100644 --- a/docs/formal/scraps/architecture/03-architecture/hal/migration-plan.tex +++ b/docs/formal/scraps/architecture/03-architecture/hal/migration-plan.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/hal/migration-plan -%% SOURCE: docs/working/architecture/03-architecture/hal/migration-plan.md +%% SOURCE: docs/working/archive/dead/hal-target-contract/migration-plan.md %% STATUS: WORKING %% FITS: dev-guide/ch-platform %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/hal/overview.tex b/docs/formal/scraps/architecture/03-architecture/hal/overview.tex index 5b451b45..e2355866 100644 --- a/docs/formal/scraps/architecture/03-architecture/hal/overview.tex +++ b/docs/formal/scraps/architecture/03-architecture/hal/overview.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/hal/overview -%% SOURCE: docs/working/architecture/03-architecture/hal/overview.md +%% SOURCE: docs/working/archive/dead/hal-target-contract/overview.md %% STATUS: WORKING %% FITS: dev-guide/ch-platform %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/hal/platform-implementations.tex b/docs/formal/scraps/architecture/03-architecture/hal/platform-implementations.tex index ca249953..b05f8619 100644 --- a/docs/formal/scraps/architecture/03-architecture/hal/platform-implementations.tex +++ b/docs/formal/scraps/architecture/03-architecture/hal/platform-implementations.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/hal/platform-implementations -%% SOURCE: docs/working/architecture/03-architecture/hal/platform-implementations.md +%% SOURCE: docs/working/archive/dead/hal-target-contract/platform-implementations.md %% STATUS: WORKING %% FITS: dev-guide/ch-platform %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/hal/starkernel-integration.tex b/docs/formal/scraps/architecture/03-architecture/hal/starkernel-integration.tex index 4514ec8c..543fe7fd 100644 --- a/docs/formal/scraps/architecture/03-architecture/hal/starkernel-integration.tex +++ b/docs/formal/scraps/architecture/03-architecture/hal/starkernel-integration.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/hal/starkernel-integration -%% SOURCE: docs/working/architecture/03-architecture/hal/starkernel-integration.md +%% SOURCE: docs/working/archive/dead/hal-target-contract/starkernel-integration.md %% STATUS: WORKING %% FITS: dev-guide/ch-platform %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/heartbeat-system/implementation-plan.tex b/docs/formal/scraps/architecture/03-architecture/heartbeat-system/implementation-plan.tex index 23680fb0..ea57eacd 100644 --- a/docs/formal/scraps/architecture/03-architecture/heartbeat-system/implementation-plan.tex +++ b/docs/formal/scraps/architecture/03-architecture/heartbeat-system/implementation-plan.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/heartbeat-system/implementation-plan -%% SOURCE: docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md +%% SOURCE: docs/working/archive/superseded/heartbeat-rate-logging-plan.md %% STATUS: HISTORICAL %% FITS: dev-guide/ch-heartbeat %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/physics-engine/feedback-loops-analysis.tex b/docs/formal/scraps/architecture/03-architecture/physics-engine/feedback-loops-analysis.tex index 31115cc2..c9ac7da6 100644 --- a/docs/formal/scraps/architecture/03-architecture/physics-engine/feedback-loops-analysis.tex +++ b/docs/formal/scraps/architecture/03-architecture/physics-engine/feedback-loops-analysis.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/physics-engine/feedback-loops-analysis -%% SOURCE: docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md +%% SOURCE: docs/working/archive/superseded/feedback-loops-analysis.md %% STATUS: HISTORICAL %% FITS: dev-guide/ch-physics %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/physics-engine/metrics-and-knobs.tex b/docs/formal/scraps/architecture/03-architecture/physics-engine/metrics-and-knobs.tex index f8edfdb5..1affe266 100644 --- a/docs/formal/scraps/architecture/03-architecture/physics-engine/metrics-and-knobs.tex +++ b/docs/formal/scraps/architecture/03-architecture/physics-engine/metrics-and-knobs.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/physics-engine/metrics-and-knobs -%% SOURCE: docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md +%% SOURCE: docs/working/archive/dead/metrics-and-knobs.md %% STATUS: WORKING %% FITS: dev-guide/ch-physics, cookbook/ch-physics %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/03-architecture/physics-engine/steady-state-machine.tex b/docs/formal/scraps/architecture/03-architecture/physics-engine/steady-state-machine.tex index 800160a4..2bc06c41 100644 --- a/docs/formal/scraps/architecture/03-architecture/physics-engine/steady-state-machine.tex +++ b/docs/formal/scraps/architecture/03-architecture/physics-engine/steady-state-machine.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/03-architecture/physics-engine/steady-state-machine -%% SOURCE: docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md +%% SOURCE: docs/working/archive/superseded/steady-state-machine.md %% STATUS: CURRENT %% FITS: dev-guide/ch-physics %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/architecture/getting-started/quick-start/factorial-doe.tex b/docs/formal/scraps/architecture/getting-started/quick-start/factorial-doe.tex index 49844148..26c3042f 100644 --- a/docs/formal/scraps/architecture/getting-started/quick-start/factorial-doe.tex +++ b/docs/formal/scraps/architecture/getting-started/quick-start/factorial-doe.tex @@ -1,5 +1,5 @@ %% SCRAP: architecture/getting-started/quick-start/factorial-doe -%% SOURCE: docs/working/architecture/getting-started/quick-start/factorial-doe.md +%% SOURCE: docs/working/archive/superseded/factorial-doe/quick-start.md %% STATUS: CURRENT %% FITS: cookbook/ch-doe %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/archive/DOCUMENTATION_AUDIT.tex b/docs/formal/scraps/archive/DOCUMENTATION_AUDIT.tex index dd394e39..67084bd9 100644 --- a/docs/formal/scraps/archive/DOCUMENTATION_AUDIT.tex +++ b/docs/formal/scraps/archive/DOCUMENTATION_AUDIT.tex @@ -36,7 +36,7 @@ The audit assigned priority as follows. \begin{itemize} \item Add missing \texttt{README} files to all numbered directories. \item Update \texttt{CLAUDE.md} to reflect HAL and StarKernel vision. - \item Create \texttt{docs/03-architecture/README.md} as a system overview. + \item Create \texttt{docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md} as a system overview. \end{itemize} \textbf{Medium priority:} diff --git a/docs/formal/scraps/experiments/02-experiments/L8_WIRING_PLAN.tex b/docs/formal/scraps/experiments/02-experiments/L8_WIRING_PLAN.tex index ae15d61f..ae85273c 100644 --- a/docs/formal/scraps/experiments/02-experiments/L8_WIRING_PLAN.tex +++ b/docs/formal/scraps/experiments/02-experiments/L8_WIRING_PLAN.tex @@ -1,5 +1,5 @@ %% SCRAP: experiments/02-experiments/L8_WIRING_PLAN -%% SOURCE: docs/working/experiments/02-experiments/L8_WIRING_PLAN.md +%% SOURCE: docs/working/archive/superseded/L8_WIRING_PLAN.md %% STATUS: HISTORICAL %% FITS: experiments/ch-l8 %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/experiments/02-experiments/factorial-doe/guide.tex b/docs/formal/scraps/experiments/02-experiments/factorial-doe/guide.tex index 6038bfa5..58aa18fa 100644 --- a/docs/formal/scraps/experiments/02-experiments/factorial-doe/guide.tex +++ b/docs/formal/scraps/experiments/02-experiments/factorial-doe/guide.tex @@ -1,5 +1,5 @@ %% SCRAP: experiments/02-experiments/factorial-doe/guide -%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/guide.md +%% SOURCE: docs/working/archive/superseded/factorial-doe/guide.md %% STATUS: CURRENT %% FITS: experiments/ch-factorial, cookbook/ch-doe %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/experiments/02-experiments/factorial-doe/incompatible-configs.tex b/docs/formal/scraps/experiments/02-experiments/factorial-doe/incompatible-configs.tex index 60ca13ca..cb1816db 100644 --- a/docs/formal/scraps/experiments/02-experiments/factorial-doe/incompatible-configs.tex +++ b/docs/formal/scraps/experiments/02-experiments/factorial-doe/incompatible-configs.tex @@ -1,5 +1,5 @@ %% SCRAP: experiments/02-experiments/factorial-doe/incompatible-configs -%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md +%% SOURCE: docs/working/archive/superseded/factorial-doe/incompatible-configs.md %% STATUS: CURRENT %% FITS: experiments/ch-factorial %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/experiments/02-experiments/factorial-doe/index.tex b/docs/formal/scraps/experiments/02-experiments/factorial-doe/index.tex index f069aeff..c929e46e 100644 --- a/docs/formal/scraps/experiments/02-experiments/factorial-doe/index.tex +++ b/docs/formal/scraps/experiments/02-experiments/factorial-doe/index.tex @@ -1,5 +1,5 @@ %% SCRAP: experiments/02-experiments/factorial-doe/index -%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/index.md +%% SOURCE: docs/working/archive/superseded/factorial-doe/index.md %% STATUS: CURRENT %% FITS: experiments/ch-factorial %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/experiments/02-experiments/factorial-doe/workflow.tex b/docs/formal/scraps/experiments/02-experiments/factorial-doe/workflow.tex index ea4b0047..490c662a 100644 --- a/docs/formal/scraps/experiments/02-experiments/factorial-doe/workflow.tex +++ b/docs/formal/scraps/experiments/02-experiments/factorial-doe/workflow.tex @@ -1,5 +1,5 @@ %% SCRAP: experiments/02-experiments/factorial-doe/workflow -%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/workflow.md +%% SOURCE: docs/working/archive/superseded/factorial-doe/workflow.md %% STATUS: CURRENT %% FITS: experiments/ch-factorial, cookbook/ch-doe %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/experiments/02-experiments/heartbeat-doe/corrected-design.tex b/docs/formal/scraps/experiments/02-experiments/heartbeat-doe/corrected-design.tex index badf9b48..c8fd9016 100644 --- a/docs/formal/scraps/experiments/02-experiments/heartbeat-doe/corrected-design.tex +++ b/docs/formal/scraps/experiments/02-experiments/heartbeat-doe/corrected-design.tex @@ -1,5 +1,5 @@ %% SCRAP: experiments/02-experiments/heartbeat-doe/corrected-design -%% SOURCE: docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md +%% SOURCE: docs/working/archive/superseded/heartbeat-doe-corrected-design.md %% STATUS: WORKING %% FITS: experiments/ch-heartbeat %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/experiments/02-experiments/heartbeat-doe/design.tex b/docs/formal/scraps/experiments/02-experiments/heartbeat-doe/design.tex index f6a5e256..8825f23f 100644 --- a/docs/formal/scraps/experiments/02-experiments/heartbeat-doe/design.tex +++ b/docs/formal/scraps/experiments/02-experiments/heartbeat-doe/design.tex @@ -1,5 +1,5 @@ %% SCRAP: experiments/02-experiments/heartbeat-doe/design -%% SOURCE: docs/working/experiments/02-experiments/heartbeat-doe/design.md +%% SOURCE: docs/working/archive/superseded/heartbeat-doe-design.md %% STATUS: WORKING %% FITS: experiments/ch-heartbeat %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.tex b/docs/formal/scraps/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.tex index cb68c6ba..de0098a8 100644 --- a/docs/formal/scraps/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.tex +++ b/docs/formal/scraps/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.tex @@ -1,5 +1,5 @@ %% SCRAP: hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION -%% SOURCE: docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc +%% SOURCE: docs/working/archive/dead/l4re/L4RE_DICTIONARY_ALLOCATION.adoc %% STATUS: WORKING %% FITS: dev-guide/ch-l4re %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/hardware/platform-integration/L4RE_INTEGRATION.tex b/docs/formal/scraps/hardware/platform-integration/L4RE_INTEGRATION.tex index 793a5c41..82a7fae8 100644 --- a/docs/formal/scraps/hardware/platform-integration/L4RE_INTEGRATION.tex +++ b/docs/formal/scraps/hardware/platform-integration/L4RE_INTEGRATION.tex @@ -1,5 +1,5 @@ %% SCRAP: hardware/platform-integration/L4RE_INTEGRATION -%% SOURCE: docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc +%% SOURCE: docs/working/archive/dead/l4re/L4RE_INTEGRATION.adoc %% STATUS: WORKING %% FITS: dev-guide/ch-l4re %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/hardware/platform-integration/l_4_re_blkio_endpoints.tex b/docs/formal/scraps/hardware/platform-integration/l_4_re_blkio_endpoints.tex index 99d31116..f095ed1a 100644 --- a/docs/formal/scraps/hardware/platform-integration/l_4_re_blkio_endpoints.tex +++ b/docs/formal/scraps/hardware/platform-integration/l_4_re_blkio_endpoints.tex @@ -1,5 +1,5 @@ %% SCRAP: hardware/platform-integration/l_4_re_blkio_endpoints -%% SOURCE: docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc +%% SOURCE: docs/working/archive/dead/l4re/l_4_re_blkio_endpoints.adoc %% STATUS: WORKING %% FITS: dev-guide/ch-l4re %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/scraps/legal/README.tex b/docs/formal/scraps/legal/README.tex index 0c5a3d28..d222f041 100644 --- a/docs/formal/scraps/legal/README.tex +++ b/docs/formal/scraps/legal/README.tex @@ -40,7 +40,7 @@ They are deferred to a later, build-verified pass. \toprule Path & Description \\ \midrule -\texttt{docs/ontology.tex} / \texttt{.pdf} & Formal ontology source and compiled PDF; candidate for \texttt{formal/}. \\ +\texttt{docs/working/papers/ontology.tex} / \texttt{.pdf} & Formal ontology source and compiled PDF; candidate for \texttt{formal/}. \\ \texttt{docs/ontology\_diagrams.dot} & Graphviz source for ontology diagrams. \\ \texttt{docs/fig\_*.png} / \texttt{.svg} & Shared figure assets referenced by ontology and system narrative LaTeX. \\ \bottomrule diff --git a/docs/formal/scraps/scratch/src/L4RE_INTEGRATION_TODO.tex b/docs/formal/scraps/scratch/src/L4RE_INTEGRATION_TODO.tex index 6d0e3c21..bbe32dcf 100644 --- a/docs/formal/scraps/scratch/src/L4RE_INTEGRATION_TODO.tex +++ b/docs/formal/scraps/scratch/src/L4RE_INTEGRATION_TODO.tex @@ -1,5 +1,5 @@ %% SCRAP: scratch/src/L4RE_INTEGRATION_TODO -%% SOURCE: docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc +%% SOURCE: docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc %% STATUS: HISTORICAL %% FITS: dev-guide/ch-l4re %% EDITORIAL: lifted — prose rewritten to press voice diff --git a/docs/formal/vol2-kernel/README.md b/docs/formal/vol2-kernel/README.md index aede5115..631bcb6f 100644 --- a/docs/formal/vol2-kernel/README.md +++ b/docs/formal/vol2-kernel/README.md @@ -22,7 +22,7 @@ Built via `make -C docs/formal vol2`; output lands at ## See also -- [`docs/lithosananke/README.md`](../../lithosananke/README.md) — the +- [`docs/working/archive/historical/2026-10-lithosananke-orientation.md`](../../lithosananke/README.md) — the living kernel-branch documentation this volume draws from. - [`docs/formal/README.md`](../README.md) — the three research volumes this belongs to (with `vol1-vm-physics/` and `vol3-research/`). diff --git a/docs/formal/vol2-kernel/ch04-platform-support.tex b/docs/formal/vol2-kernel/ch04-platform-support.tex index 623b29c8..633a8d68 100644 --- a/docs/formal/vol2-kernel/ch04-platform-support.tex +++ b/docs/formal/vol2-kernel/ch04-platform-support.tex @@ -1,6 +1,6 @@ %% Vol II, Chapter 4 — Platform Support %% SOURCE: docs/working/scratch/src/platform-integration/ (multiple .adoc files) -%% docs/working/architecture/03-architecture/hal/ (HAL design — aspirational) +%% docs/working/archive/dead/hal-target-contract/ (HAL design — aspirational) %% .claude/CLAUDE.md (Platform abstraction, build targets) \chapter{Platform Support} @@ -43,7 +43,7 @@ \section{Platform Abstraction Layer (HAL Target)} \label{vol2:sec:platforms:hal} -%% SOURCE: docs/working/architecture/03-architecture/hal/overview.md +%% SOURCE: docs/working/archive/dead/hal-target-contract/overview.md %% IMPORTANT: the hal_* API described in the hal/ doc family is the TARGET %% design, not the current codebase. Current code uses sf_time_backend_t-style %% naming. This section describes the planned migration. diff --git a/docs/lithosananke/DICTIONARY.md b/docs/reference/DICTIONARY.md similarity index 100% rename from docs/lithosananke/DICTIONARY.md rename to docs/reference/DICTIONARY.md diff --git a/docs/L8_ADAPTIVE_CONFIG_TABLE.md b/docs/reference/L8_ADAPTIVE_CONFIG_TABLE.md similarity index 100% rename from docs/L8_ADAPTIVE_CONFIG_TABLE.md rename to docs/reference/L8_ADAPTIVE_CONFIG_TABLE.md diff --git a/docs/lithosananke/M7.1.md b/docs/reference/M7.1.md similarity index 100% rename from docs/lithosananke/M7.1.md rename to docs/reference/M7.1.md diff --git a/docs/ONTOLOGY.md b/docs/reference/ONTOLOGY.md similarity index 100% rename from docs/ONTOLOGY.md rename to docs/reference/ONTOLOGY.md diff --git a/docs/lithosananke/ROADMAP.md b/docs/reference/ROADMAP.md similarity index 100% rename from docs/lithosananke/ROADMAP.md rename to docs/reference/ROADMAP.md diff --git a/docs/STARFORTH_PRIMITIVES.md b/docs/reference/STARFORTH_PRIMITIVES.md similarity index 100% rename from docs/STARFORTH_PRIMITIVES.md rename to docs/reference/STARFORTH_PRIMITIVES.md diff --git a/docs/lithosananke/hosted-acceptance-test/README.md b/docs/reference/hosted-acceptance-test/README.md similarity index 100% rename from docs/lithosananke/hosted-acceptance-test/README.md rename to docs/reference/hosted-acceptance-test/README.md diff --git a/docs/lithosananke/kernel-args/DESIGN.md b/docs/reference/kernel-args/DESIGN.md similarity index 100% rename from docs/lithosananke/kernel-args/DESIGN.md rename to docs/reference/kernel-args/DESIGN.md diff --git a/docs/lithosananke/kernel-args/README.md b/docs/reference/kernel-args/README.md similarity index 83% rename from docs/lithosananke/kernel-args/README.md rename to docs/reference/kernel-args/README.md index 02a5a442..23f79bb3 100644 --- a/docs/lithosananke/kernel-args/README.md +++ b/docs/reference/kernel-args/README.md @@ -1,4 +1,4 @@ -# docs/lithosananke/kernel-args/ +# docs/reference/kernel-args/ Design doc for kernel command-line arguments (`KernelArgs`). @@ -14,5 +14,5 @@ Design doc for kernel command-line arguments (`KernelArgs`). ## See also -- [`docs/lithosananke/README.md`](../README.md) — kernel branch overview. +- [`docs/working/archive/historical/2026-10-lithosananke-orientation.md`](../README.md) — kernel branch overview. - [Project root](../../../README.md) diff --git a/docs/03-architecture/word-acl/DESIGN.md b/docs/reference/word-acl/DESIGN.md similarity index 100% rename from docs/03-architecture/word-acl/DESIGN.md rename to docs/reference/word-acl/DESIGN.md diff --git a/docs/03-architecture/word-acl/README.md b/docs/reference/word-acl/README.md similarity index 97% rename from docs/03-architecture/word-acl/README.md rename to docs/reference/word-acl/README.md index 1ccf2bc1..05f34d00 100644 --- a/docs/03-architecture/word-acl/README.md +++ b/docs/reference/word-acl/README.md @@ -1,4 +1,4 @@ -# docs/03-architecture/word-acl/ +# docs/reference/word-acl/ Design doc for the word-level ACL (access control) system. diff --git a/docs/v4.0.0/JUSTIFICATION.md b/docs/v4.0.0/JUSTIFICATION.md index 24ae5735..fa780087 100644 --- a/docs/v4.0.0/JUSTIFICATION.md +++ b/docs/v4.0.0/JUSTIFICATION.md @@ -253,5 +253,5 @@ accepted. The existing acceptance tests keep their force and their rules: the three-architecture QEMU boot for anything bare metal (`.claude/CLAUDE.md`), and the hosted three-architecture test -(`docs/lithosananke/hosted-acceptance-test/README.md`). Passing `make -C v4 test` is a development +(`docs/reference/hosted-acceptance-test/README.md`). Passing `make -C v4 test` is a development check on the golden model, not acceptance. diff --git a/docs/working/architecture/03-architecture/README.md b/docs/working/architecture/03-architecture/README.md index 3e8de454..f531c02b 100644 --- a/docs/working/architecture/03-architecture/README.md +++ b/docs/working/architecture/03-architecture/README.md @@ -1,4 +1,4 @@ - + # Architecture This directory contains system architecture documentation for StarForth's core subsystems and the path to StarKernel and StarshipOS. diff --git a/docs/working/architecture/03-architecture/word-acl/DESIGN.md b/docs/working/architecture/03-architecture/word-acl/DESIGN.md index 429321c2..4eb50dec 100644 --- a/docs/working/architecture/03-architecture/word-acl/DESIGN.md +++ b/docs/working/architecture/03-architecture/word-acl/DESIGN.md @@ -1,4 +1,4 @@ - + # Word-Level ACL System **Status:** Implemented through Phase 6 — Phase 7 (LithosAnanke parity) remaining diff --git a/docs/working/architecture/README.md b/docs/working/architecture/README.md index 4ac1662e..4754a865 100644 --- a/docs/working/architecture/README.md +++ b/docs/working/architecture/README.md @@ -34,7 +34,7 @@ source material that `docs/formal/scraps/architecture/` is generated from. ## See also -- [`docs/03-architecture/README.md`](../../03-architecture/README.md) — the +- [`docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md`](../../03-architecture/README.md) — the *binding-constraint* Tripod/ACL docs, distinct from this design-notes tree. - [`docs/formal/scraps/README.md`](../../formal/scraps/README.md) — the press-ready fragment tier this material feeds. diff --git a/docs/working/archive/DOCUMENTATION_AUDIT.md b/docs/working/archive/DOCUMENTATION_AUDIT.md index 4760ab60..206de666 100644 --- a/docs/working/archive/DOCUMENTATION_AUDIT.md +++ b/docs/working/archive/DOCUMENTATION_AUDIT.md @@ -148,7 +148,7 @@ This directory contains experimental designs, execution guides, and results for - Results for publication: `06-research/results-for-publication.md` ``` -#### `docs/03-architecture/README.md` +#### `docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md` ```markdown # Architecture @@ -427,7 +427,7 @@ This document provides **kernel-specific implementation details**... #### Incomplete Documents -**`docs/ONTOLOGY.md`:** +**`docs/reference/ONTOLOGY.md`:** - Appears to be high-level conceptual framework - Could benefit from linking to specific implementation docs - Should reference HAL as part of platform layer @@ -510,7 +510,7 @@ The `archive/` directory preserves historical context without cluttering active - Mention StarKernel/StarshipOS vision - **Effort:** 15 minutes -4. **Create `docs/03-architecture/README.md`** +4. **Create `docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md`** - Big picture of how subsystems fit together - Roadmap (StarForth → StarKernel → StarshipOS) - **Effort:** 1 hour @@ -581,7 +581,7 @@ The `archive/` directory preserves historical context without cluttering active 1. Create 6 missing README files for numbered directories 2. Update `docs/CLAUDE.md` with HAL section 3. Update `docs/README.md` with current work -4. Create `docs/03-architecture/README.md` +4. Create `docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md` ### Short-term Actions (1-2 weeks) diff --git a/docs/working/architecture/03-architecture/hal/README.md b/docs/working/archive/dead/hal-target-contract/README.md similarity index 95% rename from docs/working/architecture/03-architecture/hal/README.md rename to docs/working/archive/dead/hal-target-contract/README.md index 61e268e5..1bfec135 100644 --- a/docs/working/architecture/03-architecture/hal/README.md +++ b/docs/working/archive/dead/hal-target-contract/README.md @@ -1,4 +1,7 @@ - +> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/). +> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/README.md`. + + > **⚠ 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 diff --git a/docs/working/architecture/03-architecture/hal/interfaces.md b/docs/working/archive/dead/hal-target-contract/interfaces.md similarity index 97% rename from docs/working/architecture/03-architecture/hal/interfaces.md rename to docs/working/archive/dead/hal-target-contract/interfaces.md index 42b14f27..6936bad1 100644 --- a/docs/working/architecture/03-architecture/hal/interfaces.md +++ b/docs/working/archive/dead/hal-target-contract/interfaces.md @@ -1,4 +1,7 @@ - +> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/). +> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/interfaces.md`. + + > **⚠ 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 diff --git a/docs/working/architecture/03-architecture/hal/migration-plan.md b/docs/working/archive/dead/hal-target-contract/migration-plan.md similarity index 97% rename from docs/working/architecture/03-architecture/hal/migration-plan.md rename to docs/working/archive/dead/hal-target-contract/migration-plan.md index 47facc7c..e4654fe6 100644 --- a/docs/working/architecture/03-architecture/hal/migration-plan.md +++ b/docs/working/archive/dead/hal-target-contract/migration-plan.md @@ -1,4 +1,7 @@ - +> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/). +> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/migration-plan.md`. + + > **⚠ 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 diff --git a/docs/working/architecture/03-architecture/hal/overview.md b/docs/working/archive/dead/hal-target-contract/overview.md similarity index 97% rename from docs/working/architecture/03-architecture/hal/overview.md rename to docs/working/archive/dead/hal-target-contract/overview.md index 4df98ef9..c22b735b 100644 --- a/docs/working/architecture/03-architecture/hal/overview.md +++ b/docs/working/archive/dead/hal-target-contract/overview.md @@ -1,4 +1,7 @@ - +> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/). +> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/overview.md`. + + # Hardware Abstraction Layer (HAL) Architecture > **⚠️ Important Note**: This document describes the **target HAL architecture** with standardized `hal_*` function naming. The current codebase uses `sf_time_backend_t` and similar abstractions with different naming conventions. See [migration-plan.md](migration-plan.md) for the refactoring steps to migrate existing platform code to the HAL interfaces described here. diff --git a/docs/working/architecture/03-architecture/hal/platform-implementations.md b/docs/working/archive/dead/hal-target-contract/platform-implementations.md similarity index 97% rename from docs/working/architecture/03-architecture/hal/platform-implementations.md rename to docs/working/archive/dead/hal-target-contract/platform-implementations.md index d6da5c1b..467fe396 100644 --- a/docs/working/architecture/03-architecture/hal/platform-implementations.md +++ b/docs/working/archive/dead/hal-target-contract/platform-implementations.md @@ -1,4 +1,7 @@ - +> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/). +> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/platform-implementations.md`. + + > **⚠ OBSOLETE (flagged 2026-10-09).** Assumes a `src/platform//hal_*.c` layout > whose platform names ("Linux", "L4Re", "StarKernel") and interface never matched the built diff --git a/docs/working/architecture/03-architecture/hal/starkernel-integration.md b/docs/working/archive/dead/hal-target-contract/starkernel-integration.md similarity index 98% rename from docs/working/architecture/03-architecture/hal/starkernel-integration.md rename to docs/working/archive/dead/hal-target-contract/starkernel-integration.md index ccd75766..2b6c8092 100644 --- a/docs/working/architecture/03-architecture/hal/starkernel-integration.md +++ b/docs/working/archive/dead/hal-target-contract/starkernel-integration.md @@ -1,4 +1,7 @@ - +> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/). +> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/starkernel-integration.md`. + + > **⚠ 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 diff --git a/docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc b/docs/working/archive/dead/l4re/L4RE_DICTIONARY_ALLOCATION.adoc similarity index 96% rename from docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc rename to docs/working/archive/dead/l4re/L4RE_DICTIONARY_ALLOCATION.adoc index 75c4b182..24f948dc 100644 --- a/docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc +++ b/docs/working/archive/dead/l4re/L4RE_DICTIONARY_ALLOCATION.adoc @@ -1,3 +1,5 @@ +// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc. + // Moved from docs/src/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc to docs/working/scratch/src/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc on 2026-06-16 (docs reorg Phase 2) == Dictionary Allocation Strategy for L4Re :toc: left diff --git a/docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc b/docs/working/archive/dead/l4re/L4RE_INTEGRATION.adoc similarity index 99% rename from docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc rename to docs/working/archive/dead/l4re/L4RE_INTEGRATION.adoc index 8ff7103f..df66ea86 100644 --- a/docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc +++ b/docs/working/archive/dead/l4re/L4RE_INTEGRATION.adoc @@ -1,3 +1,5 @@ +// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc. + // Moved from docs/src/platform-integration/L4RE_INTEGRATION.adoc to docs/working/scratch/src/platform-integration/L4RE_INTEGRATION.adoc on 2026-06-16 (docs reorg Phase 2) == StarForth L4Re Integration Guide :toc: left diff --git a/docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc b/docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc similarity index 96% rename from docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc rename to docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc index b7347598..67b1457f 100644 --- a/docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc +++ b/docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc @@ -1,4 +1,6 @@ -// Moved from docs/src/L4RE_INTEGRATION_TODO.adoc to docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc on 2026-06-16 (docs reorg Phase 2) +// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc. + +// Moved from docs/src/L4RE_INTEGRATION_TODO.adoc to docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc on 2026-06-16 (docs reorg Phase 2) == L4Re Integration TODO :toc: left :toc-title: Contents diff --git a/docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc b/docs/working/archive/dead/l4re/l_4_re_blkio_endpoints.adoc similarity index 95% rename from docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc rename to docs/working/archive/dead/l4re/l_4_re_blkio_endpoints.adoc index f30cd58e..2eeb778a 100644 --- a/docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc +++ b/docs/working/archive/dead/l4re/l_4_re_blkio_endpoints.adoc @@ -1,3 +1,5 @@ +// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc. + // Moved from docs/src/platform-integration/l_4_re_blkio_endpoints.adoc to docs/working/scratch/src/platform-integration/l_4_re_blkio_endpoints.adoc on 2026-06-16 (docs reorg Phase 2) == StarForth Block I/O — L4Re Porting Endpoints :toc: left diff --git a/docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md b/docs/working/archive/dead/metrics-and-knobs.md similarity index 96% rename from docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md rename to docs/working/archive/dead/metrics-and-knobs.md index 639679b5..c33ae8b2 100644 --- a/docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md +++ b/docs/working/archive/dead/metrics-and-knobs.md @@ -1,4 +1,7 @@ - +> **DEAD (docs triage 2026-10-14).** Already marked dead in its own header. +> Instead: its own header. Moved here from `docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md`. + + # StarForth Metrics & Knobs: GAPS ONLY ## What's NOT Wired (Things to Add) diff --git a/docs/lithosananke/SYSTEM_ARCHITECTURE.md b/docs/working/archive/historical/2026-01-27-system-architecture-draft.md similarity index 99% rename from docs/lithosananke/SYSTEM_ARCHITECTURE.md rename to docs/working/archive/historical/2026-01-27-system-architecture-draft.md index 0016b310..994258e8 100644 --- a/docs/lithosananke/SYSTEM_ARCHITECTURE.md +++ b/docs/working/archive/historical/2026-01-27-system-architecture-draft.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** Draft 0.1 of the system vision ("everything is a VM, everything is a capsule"), 2026-01-27; the design that was built is recorded in the FABRIC documents. +> Instead: docs/fabric/ (FABRIC-3.5.md for the Tripod and kernel-Hermes, FABRIC-3.md for bare metal). Moved here from `docs/lithosananke/SYSTEM_ARCHITECTURE.md`. + # LithosAnanke System Architecture **Version**: 0.1 (Draft) diff --git a/docs/TEST_GAPS.md b/docs/working/archive/historical/2026-06-03-test-gap-audit.md similarity index 97% rename from docs/TEST_GAPS.md rename to docs/working/archive/historical/2026-06-03-test-gap-audit.md index dad65278..0b5076d2 100644 --- a/docs/TEST_GAPS.md +++ b/docs/working/archive/historical/2026-06-03-test-gap-audit.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** A test-coverage audit of StarForth v3.0.3 / LithosAnanke v1.0.8, 2026-06-03; POST has grown since (1052 tests). +> Instead: v3/src/test_runner/ and the POST line of any current boot. Moved here from `docs/TEST_GAPS.md`. + # StarForth Dictionary Test Coverage — Gap Audit **Branch:** `lithosananke` | **StarForth v3.0.3 / LithosAnanke v1.0.8** **Audited:** 2026-06-03 diff --git a/docs/NEXT_SESSION.md b/docs/working/archive/historical/2026-06-10-next-session-plan.md similarity index 94% rename from docs/NEXT_SESSION.md rename to docs/working/archive/historical/2026-06-10-next-session-plan.md index c48cb097..f0571c67 100644 --- a/docs/NEXT_SESSION.md +++ b/docs/working/archive/historical/2026-06-10-next-session-plan.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** A session hand-off plan from 2026-06-10, on the pre-split `lithosananke` branch; every item in it is long done or overtaken. +> Instead: .claude/CLAUDE.md and docs/fabric/FABRIC-3.md for current status. Moved here from `docs/NEXT_SESSION.md`. + # Next Session Plan Generated at end of session `cdcb1844` (2026-06-10). @@ -15,7 +18,7 @@ Branch at close: `lithosananke` (merged and pushed; all three arches boot to `ok - Added framebuffer host render test (`tools/fbtest.c`) and QEMU screendump (`scripts/qemu_screenshot.sh`) to the amd64 `qemu` target - CLAUDE.md: one-process-at-a-time build rule -- Design doc: `docs/lithosananke/kernel-args/DESIGN.md` — UEFI +- Design doc: `docs/reference/kernel-args/DESIGN.md` — UEFI command-line argument system (KernelArgs) --- @@ -73,7 +76,7 @@ tight. Document findings in `docs/lithosananke/memory-audit.md`. ## Task 3 — Implement KernelArgs -Design doc: `docs/lithosananke/kernel-args/DESIGN.md` +Design doc: `docs/reference/kernel-args/DESIGN.md` Implementation order (one commit per step): @@ -198,7 +201,7 @@ This is a general VM feature — not kernel or capsule specific. ## Task 8 — Word-level ACL system (existing design, next to implement) -Design doc: `docs/03-architecture/word-acl/DESIGN.md` +Design doc: `docs/reference/word-acl/DESIGN.md` This is already designed. It is the policy engine that makes Tasks 5–7 safe. Implement before or alongside Task 5 (`REBOOT`) since `REBOOT` diff --git a/docs/BREAK_ME_REPORT.md b/docs/working/archive/historical/2026-06-30-break-me-report.md similarity index 92% rename from docs/BREAK_ME_REPORT.md rename to docs/working/archive/historical/2026-06-30-break-me-report.md index afa0145b..fb244f72 100644 --- a/docs/BREAK_ME_REPORT.md +++ b/docs/working/archive/historical/2026-06-30-break-me-report.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** A generated diagnostic report from one test run, 2026-06-30. +> Instead: the boot POST in any current logs/ run. Moved here from `docs/BREAK_ME_REPORT.md`. + # 🔥 STARFORTH BREAK-ME DIAGNOSTIC REPORT 🔥 ## Executive Summary diff --git a/docs/lithosananke/amd64-isr-fix/README.md b/docs/working/archive/historical/2026-07-amd64-isr-fix/README.md similarity index 94% rename from docs/lithosananke/amd64-isr-fix/README.md rename to docs/working/archive/historical/2026-07-amd64-isr-fix/README.md index a9b2afb7..bdff560f 100644 --- a/docs/lithosananke/amd64-isr-fix/README.md +++ b/docs/working/archive/historical/2026-07-amd64-isr-fix/README.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** The write-up of one fix (APIC timer ISR, amd64), done. +> Instead: the code itself (kernel/src/arch/amd64/). Moved here from `docs/lithosananke/amd64-isr-fix/README.md`. + # APIC Timer ISR Fix — amd64 **Date**: 2026-06-03 diff --git a/docs/birthing/PLAN.md b/docs/working/archive/historical/2026-07-birthing/PLAN.md similarity index 98% rename from docs/birthing/PLAN.md rename to docs/working/archive/historical/2026-07-birthing/PLAN.md index e992b538..8bfbd4d7 100644 --- a/docs/birthing/PLAN.md +++ b/docs/working/archive/historical/2026-07-birthing/PLAN.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1). +> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/PLAN.md`. + # Birthing Plan: Child VMs Born of Hera **Status:** DRAFT — requires Captain Bob approval before any implementation begins diff --git a/docs/birthing/README.md b/docs/working/archive/historical/2026-07-birthing/README.md similarity index 63% rename from docs/birthing/README.md rename to docs/working/archive/historical/2026-07-birthing/README.md index 35ab7839..59082949 100644 --- a/docs/birthing/README.md +++ b/docs/working/archive/historical/2026-07-birthing/README.md @@ -1,8 +1,11 @@ -# docs/birthing/ +> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1). +> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/README.md`. + +# docs/working/archive/historical/2026-07-birthing/ Design and status for VM "birthing" — the mechanism by which Hera (the Tripod governor) spawns Hermes and Artemis as child VMs at boot. See -`docs/03-architecture/tripod/TRIPOD.md` for the architectural contract this +`docs/working/archive/superseded/2026-08-tripod/TRIPOD.md` for the architectural contract this work implements. - **[PLAN.md](PLAN.md)** — Birthing plan for the initial three-VM constellation @@ -18,5 +21,5 @@ work implements. ## See also -- [`docs/03-architecture/tripod/README.md`](../03-architecture/tripod/README.md) +- [`docs/working/archive/superseded/2026-08-tripod/README.md`](../03-architecture/tripod/README.md) - [Project root](../../README.md) diff --git a/docs/birthing/STATUS.md b/docs/working/archive/historical/2026-07-birthing/STATUS.md similarity index 94% rename from docs/birthing/STATUS.md rename to docs/working/archive/historical/2026-07-birthing/STATUS.md index c618749f..d6e53bb2 100644 --- a/docs/birthing/STATUS.md +++ b/docs/working/archive/historical/2026-07-birthing/STATUS.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1). +> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/STATUS.md`. + # Birthing — Work Status and Context **Branch:** `birthing` (off `lithosananke`) @@ -128,9 +131,9 @@ Stub `init.4th` files must be written before the kernel build runs `mkcapsule`. ### Phase 0 — Design and Approval - [x] `birthing` branch created off `lithosananke` HEAD -- [x] `docs/birthing/PLAN.md` written +- [x] `docs/working/archive/historical/2026-07-birthing/PLAN.md` written - [x] All seven decisions resolved with Captain Bob -- [x] `docs/birthing/STATUS.md` created (this file) +- [x] `docs/working/archive/historical/2026-07-birthing/STATUS.md` created (this file) - [x] **Captain Bob approves plan — gate for Phase 1** --- @@ -251,7 +254,7 @@ selection is a separate task before Phase 4 (mkcapsule flag update) can proceed. - [ ] `S" Hera" USE` switches back — interactive test (requires Captain Bob) - [ ] KILL + re-BIRTH a VM in the same session — interactive test (requires Captain Bob) -**Logs:** `docs/birthing/acceptance-logs/` — kernel QEMU serial logs for all three architectures +**Logs:** `docs/working/archive/historical/2026-07-birthing/acceptance-logs/` — kernel QEMU serial logs for all three architectures --- @@ -259,8 +262,8 @@ selection is a separate task before Phase 4 (mkcapsule flag update) can proceed. | File | Purpose | |------|---------| -| `docs/birthing/PLAN.md` | Full architectural plan | -| `docs/birthing/STATUS.md` | This file — living checklist | +| `docs/working/archive/historical/2026-07-birthing/PLAN.md` | Full architectural plan | +| `docs/working/archive/historical/2026-07-birthing/STATUS.md` | This file — living checklist | | `tools/mkcapsule.c` | Build-time capsule packager | | `capsules/init.4th` | Hera's init (root, exclusive) | | `capsules/hermes/init.4th` | Hermes stub (to be written) | diff --git a/docs/birthing/acceptance-logs/README.md b/docs/working/archive/historical/2026-07-birthing/acceptance-logs/README.md similarity index 65% rename from docs/birthing/acceptance-logs/README.md rename to docs/working/archive/historical/2026-07-birthing/acceptance-logs/README.md index 50ec2f82..39f7a6c2 100644 --- a/docs/birthing/acceptance-logs/README.md +++ b/docs/working/archive/historical/2026-07-birthing/acceptance-logs/README.md @@ -1,4 +1,7 @@ -# docs/birthing/acceptance-logs/ +> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1). +> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/acceptance-logs/README.md`. + +# docs/working/archive/historical/2026-07-birthing/acceptance-logs/ Kernel QEMU acceptance test results for the VM lifecycle words (`BIRTH KILL START STOP USE`) and the `."` compile-mode fix, run across all three @@ -15,5 +18,5 @@ supported architectures. ## See also -- [`docs/birthing/README.md`](../README.md) +- [`docs/working/archive/historical/2026-07-birthing/README.md`](../README.md) - [Project root](../../../README.md) diff --git a/docs/birthing/acceptance-logs/SUMMARY.md b/docs/working/archive/historical/2026-07-birthing/acceptance-logs/SUMMARY.md similarity index 91% rename from docs/birthing/acceptance-logs/SUMMARY.md rename to docs/working/archive/historical/2026-07-birthing/acceptance-logs/SUMMARY.md index 0d218d9d..562e731b 100644 --- a/docs/birthing/acceptance-logs/SUMMARY.md +++ b/docs/working/archive/historical/2026-07-birthing/acceptance-logs/SUMMARY.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1). +> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/acceptance-logs/SUMMARY.md`. + # Birthing — Kernel QEMU Acceptance Test Summary **Date:** 2026-05-27 diff --git a/docs/birthing/acceptance-logs/amd64.log b/docs/working/archive/historical/2026-07-birthing/acceptance-logs/amd64.log similarity index 100% rename from docs/birthing/acceptance-logs/amd64.log rename to docs/working/archive/historical/2026-07-birthing/acceptance-logs/amd64.log diff --git a/docs/birthing/acceptance-logs/arm64.log b/docs/working/archive/historical/2026-07-birthing/acceptance-logs/arm64.log similarity index 100% rename from docs/birthing/acceptance-logs/arm64.log rename to docs/working/archive/historical/2026-07-birthing/acceptance-logs/arm64.log diff --git a/docs/birthing/acceptance-logs/riscv64.log b/docs/working/archive/historical/2026-07-birthing/acceptance-logs/riscv64.log similarity index 100% rename from docs/birthing/acceptance-logs/riscv64.log rename to docs/working/archive/historical/2026-07-birthing/acceptance-logs/riscv64.log diff --git a/docs/lithosananke/riscv64-stack-fix/README.md b/docs/working/archive/historical/2026-08-riscv64-stack-fix/README.md similarity index 97% rename from docs/lithosananke/riscv64-stack-fix/README.md rename to docs/working/archive/historical/2026-08-riscv64-stack-fix/README.md index fd7d4e84..498a769c 100644 --- a/docs/lithosananke/riscv64-stack-fix/README.md +++ b/docs/working/archive/historical/2026-08-riscv64-stack-fix/README.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** The write-up of one fix (kernel stack trampoline, riscv64), done. +> Instead: the code itself (kernel/src/arch/riscv64/). Moved here from `docs/lithosananke/riscv64-stack-fix/README.md`. + # Kernel Stack Trampoline Fix — riscv64 **Date**: 2026-08-02 diff --git a/docs/lithosananke/README.md b/docs/working/archive/historical/2026-10-lithosananke-orientation.md similarity index 96% rename from docs/lithosananke/README.md rename to docs/working/archive/historical/2026-10-lithosananke-orientation.md index 24100b8c..41055d24 100644 --- a/docs/lithosananke/README.md +++ b/docs/working/archive/historical/2026-10-lithosananke-orientation.md @@ -1,3 +1,6 @@ +> **HISTORICAL (docs triage 2026-10-14).** An orientation page for the old docs/lithosananke/ folder, flagged partly stale on 2026-10-09; the folder is gone (its parts are in docs/reference/ and this archive). +> Instead: docs/README.md. Moved here from `docs/lithosananke/README.md`. + # LithosAnanke — StarForth Kernel Branch > **⚠ PARTIALLY STALE (flagged 2026-10-09).** This page predates the repo split and the diff --git a/docs/working/archive/session-logs/2026-07-24-punch-list.md b/docs/working/archive/session-logs/2026-07-24-punch-list.md index 6549d3d0..1f073fdc 100644 --- a/docs/working/archive/session-logs/2026-07-24-punch-list.md +++ b/docs/working/archive/session-logs/2026-07-24-punch-list.md @@ -47,7 +47,7 @@ that actually matters). ## 2. Fix the broken riscv64 command in this branch's acceptance-test doc -`docs/lithosananke/hosted-acceptance-test/README.md` still documents the +`docs/reference/hosted-acceptance-test/README.md` still documents the riscv64 leg using `riscv64-linux-gnu-gcc`, which cannot build this tree (`nanosleep` visibility failure under `-std=c99`, unrelated to any project change). This was already fixed in `master`'s `.claude/CLAUDE.md` (the @@ -152,6 +152,6 @@ now — just flagging. open item if anyone wants to chase it down. - Today's aarch64/riscv64 `.hidden` ISR hardening (commit `5fe188bd`) only has a CHANGELOG entry, not a dedicated writeup the way - `docs/lithosananke/amd64-isr-fix/README.md` documents the original amd64 + `docs/working/archive/historical/2026-07-amd64-isr-fix/README.md` documents the original amd64 fix. Not urgent — the CHANGELOG entry covers it — but noting the asymmetry in case someone later wants doc parity. diff --git a/docs/ROADMAP.md b/docs/working/archive/superseded/2025-12-14-starforth-roadmap.md similarity index 98% rename from docs/ROADMAP.md rename to docs/working/archive/superseded/2025-12-14-starforth-roadmap.md index 91ab0fac..f935eb6e 100644 --- a/docs/ROADMAP.md +++ b/docs/working/archive/superseded/2025-12-14-starforth-roadmap.md @@ -1,3 +1,6 @@ +> **SUPERSEDED (docs triage 2026-10-14).** The StarForth-era VM -> kernel -> OS -> FPGA plan of 2025-12-14, flagged obsolete 2026-08-26. +> Instead: docs/reference/ROADMAP.md (the LithosAnanke roadmap and versioning policy). Moved here from `docs/ROADMAP.md`. + # StarForth Roadmap: VM → Kernel → OS → FPGA > **OBSOLETE (flagged 2026-08-26, Captain Bob's call — this is more than "stale," the @@ -5,7 +8,7 @@ > StarForth-era plan dated 2025-12-14, written before the repo split, before > Tripod/Stadium/word-level ACL existed, and before "Phase 1 Starting (HAL)" had any of the > meaning it has now. Kept for historical record only. For current status, see -> `docs/lithosananke/ROADMAP.md` (repo-specific, LithosAnanke roadmap) and +> `docs/reference/ROADMAP.md` (repo-specific, LithosAnanke roadmap) and > `FABRIC-0.md`/`FABRIC-1.md`/`FABRIC-2.md` (design history and current work) — not this > document. diff --git a/docs/working/architecture/HERMES-MESSAGE-BLOCK-STORAGE-DESIGN-20260708.md b/docs/working/archive/superseded/2026-07-08-hermes-message-block-storage-design.md similarity index 98% rename from docs/working/architecture/HERMES-MESSAGE-BLOCK-STORAGE-DESIGN-20260708.md rename to docs/working/archive/superseded/2026-07-08-hermes-message-block-storage-design.md index d19c32c8..a48ad8f7 100644 --- a/docs/working/architecture/HERMES-MESSAGE-BLOCK-STORAGE-DESIGN-20260708.md +++ b/docs/working/archive/superseded/2026-07-08-hermes-message-block-storage-design.md @@ -1,3 +1,6 @@ +> **SUPERSEDED (docs triage 2026-10-14).** Storage design for the Hermes VM's messages and channels; the Hermes VM no longer exists -- messages are kernel-Hermes's. +> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/working/architecture/HERMES-MESSAGE-BLOCK-STORAGE-DESIGN-20260708.md`. + # Hermes Message/Channel Block-Backed Storage — Design Doc **Date:** 2026-07-08 (rev 2026-07-09d) **Branch:** `lithosananke` diff --git a/docs/working/architecture/HERMES-MESSAGE-CHANNEL-PHYSICS-DESIGN-20260708.md b/docs/working/archive/superseded/2026-07-08-hermes-message-channel-physics-design.md similarity index 98% rename from docs/working/architecture/HERMES-MESSAGE-CHANNEL-PHYSICS-DESIGN-20260708.md rename to docs/working/archive/superseded/2026-07-08-hermes-message-channel-physics-design.md index 57a4b56c..e2d88791 100644 --- a/docs/working/architecture/HERMES-MESSAGE-CHANNEL-PHYSICS-DESIGN-20260708.md +++ b/docs/working/archive/superseded/2026-07-08-hermes-message-channel-physics-design.md @@ -1,3 +1,6 @@ +> **SUPERSEDED (docs triage 2026-10-14).** Heat physics for the Hermes VM's messages and channels; the Hermes VM no longer exists. +> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/working/architecture/HERMES-MESSAGE-CHANNEL-PHYSICS-DESIGN-20260708.md`. + # Hermes Message/Channel Heat Physics — Design Doc **Date:** 2026-07-08 (rev 2026-07-08a) **Branch:** `lithosananke` diff --git a/docs/working/architecture/ARTEMIS-COMPUDYNAMICS-IMPLEMENTATION-PLAN-20260802.md b/docs/working/archive/superseded/2026-08-02-artemis-hermes-compudynamics-plan.md similarity index 98% rename from docs/working/architecture/ARTEMIS-COMPUDYNAMICS-IMPLEMENTATION-PLAN-20260802.md rename to docs/working/archive/superseded/2026-08-02-artemis-hermes-compudynamics-plan.md index fb4ebc7a..dfeedd8b 100644 --- a/docs/working/architecture/ARTEMIS-COMPUDYNAMICS-IMPLEMENTATION-PLAN-20260802.md +++ b/docs/working/archive/superseded/2026-08-02-artemis-hermes-compudynamics-plan.md @@ -1,3 +1,6 @@ +> **SUPERSEDED (docs triage 2026-10-14).** An implementation plan for Artemis and the Hermes VM; the Hermes half is gone with the VM, the Artemis half was carried by the FABRIC work. +> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/working/architecture/ARTEMIS-COMPUDYNAMICS-IMPLEMENTATION-PLAN-20260802.md`. + # Artemis (and Hermes) Compudynamics — Implementation Plan **Date:** 2026-08-02 **Branch:** `master` diff --git a/docs/03-architecture/README.md b/docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md similarity index 61% rename from docs/03-architecture/README.md rename to docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md index de647b92..37cdf679 100644 --- a/docs/03-architecture/README.md +++ b/docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md @@ -1,3 +1,6 @@ +> **SUPERSEDED (docs triage 2026-10-14).** The index of the old docs/03-architecture/ folder; its parts moved (word-acl to docs/reference/, tripod here). +> Instead: docs/README.md. Moved here from `docs/03-architecture/README.md`. + # docs/03-architecture/ Architecture-constraint documents for LithosAnanke subsystems that are still @@ -12,8 +15,8 @@ Claude Code) touching the affected code, not general background reading. ## See also -- [`docs/birthing/`](../birthing/) — VM birthing plan/status that implements +- [`docs/working/archive/historical/2026-07-birthing/`](../birthing/) — VM birthing plan/status that implements the Tripod contract described in `tripod/TRIPOD.md`. -- [`docs/lithosananke/README.md`](../lithosananke/README.md) — kernel-branch +- [`docs/working/archive/historical/2026-10-lithosananke-orientation.md`](../lithosananke/README.md) — kernel-branch overview these designs build on. - [Project root](../../README.md) diff --git a/docs/03-architecture/tripod/ARTEMIS.md b/docs/working/archive/superseded/2026-08-tripod/ARTEMIS.md similarity index 95% rename from docs/03-architecture/tripod/ARTEMIS.md rename to docs/working/archive/superseded/2026-08-tripod/ARTEMIS.md index a50ac816..6fec91e5 100644 --- a/docs/03-architecture/tripod/ARTEMIS.md +++ b/docs/working/archive/superseded/2026-08-tripod/ARTEMIS.md @@ -1,3 +1,6 @@ +> **SUPERSEDED (docs triage 2026-10-14).** The Tripod as Hera/Hermes/Artemis; the Hermes VM was removed (messaging moved into the kernel as kernel-Hermes) and the Tripod is Hera/Artemis/Hestia. +> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/03-architecture/tripod/ARTEMIS.md`. + # ARTEMIS.md — Artemis VM Architecture # StarshipOS / StarForth — Captain Bob (Robert Allan James) # This document constrains Claude Code behavior. Read it completely before touching Artemis. diff --git a/docs/03-architecture/tripod/HERMES.md b/docs/working/archive/superseded/2026-08-tripod/HERMES.md similarity index 96% rename from docs/03-architecture/tripod/HERMES.md rename to docs/working/archive/superseded/2026-08-tripod/HERMES.md index b151967a..dd0433fb 100644 --- a/docs/03-architecture/tripod/HERMES.md +++ b/docs/working/archive/superseded/2026-08-tripod/HERMES.md @@ -1,3 +1,6 @@ +> **SUPERSEDED (docs triage 2026-10-14).** The Tripod as Hera/Hermes/Artemis; the Hermes VM was removed (messaging moved into the kernel as kernel-Hermes) and the Tripod is Hera/Artemis/Hestia. +> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/03-architecture/tripod/HERMES.md`. + # HERMES.md — Hermes VM Architecture # StarshipOS / StarForth — Captain Bob (Robert Allan James) # This document constrains Claude Code behavior. Read it completely before touching Hermes. diff --git a/docs/03-architecture/tripod/README.md b/docs/working/archive/superseded/2026-08-tripod/README.md similarity index 73% rename from docs/03-architecture/tripod/README.md rename to docs/working/archive/superseded/2026-08-tripod/README.md index 09dbde02..df33221e 100644 --- a/docs/03-architecture/tripod/README.md +++ b/docs/working/archive/superseded/2026-08-tripod/README.md @@ -1,4 +1,7 @@ -# docs/03-architecture/tripod/ +> **SUPERSEDED (docs triage 2026-10-14).** The Tripod as Hera/Hermes/Artemis; the Hermes VM was removed (messaging moved into the kernel as kernel-Hermes) and the Tripod is Hera/Artemis/Hestia. +> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/03-architecture/tripod/README.md`. + +# docs/working/archive/superseded/2026-08-tripod/ Architectural constraints for the three StarForth VMs that make up the Tripod. These documents are binding — read the relevant one in full before @@ -23,6 +26,6 @@ permission for that specific construct. ## See also -- [`docs/birthing/`](../../birthing/) — birthing plan and QEMU acceptance +- [`docs/working/archive/historical/2026-07-birthing/`](../../birthing/) — birthing plan and QEMU acceptance logs for the Hera-spawns-Hermes/Artemis constellation described here. - [Project root](../../../README.md) diff --git a/docs/03-architecture/tripod/TRIPOD.md b/docs/working/archive/superseded/2026-08-tripod/TRIPOD.md similarity index 95% rename from docs/03-architecture/tripod/TRIPOD.md rename to docs/working/archive/superseded/2026-08-tripod/TRIPOD.md index a9fda555..4f2abba6 100644 --- a/docs/03-architecture/tripod/TRIPOD.md +++ b/docs/working/archive/superseded/2026-08-tripod/TRIPOD.md @@ -1,3 +1,6 @@ +> **SUPERSEDED (docs triage 2026-10-14).** The Tripod as Hera/Hermes/Artemis; the Hermes VM was removed (messaging moved into the kernel as kernel-Hermes) and the Tripod is Hera/Artemis/Hestia. +> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/03-architecture/tripod/TRIPOD.md`. + # TRIPOD.md — Architectural Constraints for the Tripod VMs # StarshipOS / StarForth — Captain Bob (Robert Allan James) # This document constrains Claude Code behavior. Read it completely before touching any Tripod code. diff --git a/docs/working/experiments/02-experiments/L8_WIRING_PLAN.md b/docs/working/archive/superseded/L8_WIRING_PLAN.md similarity index 96% rename from docs/working/experiments/02-experiments/L8_WIRING_PLAN.md rename to docs/working/archive/superseded/L8_WIRING_PLAN.md index aaf9e6bf..ebb6efb0 100644 --- a/docs/working/experiments/02-experiments/L8_WIRING_PLAN.md +++ b/docs/working/archive/superseded/L8_WIRING_PLAN.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09: the plan for wiring L8, since built. +> Instead: docs/working/experiments/02-experiments/L8_WIRING_IMPLEMENTATION_SUMMARY.md. Moved here from `docs/working/experiments/02-experiments/L8_WIRING_PLAN.md`. + + > **⚠ 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 diff --git a/docs/working/experiments/02-experiments/factorial-doe/guide.md b/docs/working/archive/superseded/factorial-doe/guide.md similarity index 96% rename from docs/working/experiments/02-experiments/factorial-doe/guide.md rename to docs/working/archive/superseded/factorial-doe/guide.md index 8306ec0a..475e6869 100644 --- a/docs/working/experiments/02-experiments/factorial-doe/guide.md +++ b/docs/working/archive/superseded/factorial-doe/guide.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** The 2^6 factorial DoE guide, flagged obsolete 2026-10-09. +> Instead: experiments/bare_metal/README.md for the DoE as it runs now. Moved here from `docs/working/experiments/02-experiments/factorial-doe/guide.md`. + + > **⚠ 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. diff --git a/docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md b/docs/working/archive/superseded/factorial-doe/incompatible-configs.md similarity index 96% rename from docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md rename to docs/working/archive/superseded/factorial-doe/incompatible-configs.md index 94e0de68..0dd788a7 100644 --- a/docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md +++ b/docs/working/archive/superseded/factorial-doe/incompatible-configs.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** The 2^6 factorial DoE guide, flagged obsolete 2026-10-09. +> Instead: experiments/bare_metal/README.md for the DoE as it runs now. Moved here from `docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md`. + + > **⚠ 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. diff --git a/docs/working/experiments/02-experiments/factorial-doe/index.md b/docs/working/archive/superseded/factorial-doe/index.md similarity index 95% rename from docs/working/experiments/02-experiments/factorial-doe/index.md rename to docs/working/archive/superseded/factorial-doe/index.md index abac13f8..7237f7c8 100644 --- a/docs/working/experiments/02-experiments/factorial-doe/index.md +++ b/docs/working/archive/superseded/factorial-doe/index.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** The 2^6 factorial DoE guide, flagged obsolete 2026-10-09. +> Instead: experiments/bare_metal/README.md for the DoE as it runs now. Moved here from `docs/working/experiments/02-experiments/factorial-doe/index.md`. + + > **⚠ 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. diff --git a/docs/working/architecture/getting-started/quick-start/factorial-doe.md b/docs/working/archive/superseded/factorial-doe/quick-start.md similarity index 93% rename from docs/working/architecture/getting-started/quick-start/factorial-doe.md rename to docs/working/archive/superseded/factorial-doe/quick-start.md index 72c0f3ea..7458f2c6 100644 --- a/docs/working/architecture/getting-started/quick-start/factorial-doe.md +++ b/docs/working/archive/superseded/factorial-doe/quick-start.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** Quick start for the same 2^6 factorial DoE, flagged obsolete 2026-10-09. +> Instead: experiments/bare_metal/README.md. Moved here from `docs/working/architecture/getting-started/quick-start/factorial-doe.md`. + + > **⚠ 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 diff --git a/docs/working/experiments/02-experiments/factorial-doe/workflow.md b/docs/working/archive/superseded/factorial-doe/workflow.md similarity index 96% rename from docs/working/experiments/02-experiments/factorial-doe/workflow.md rename to docs/working/archive/superseded/factorial-doe/workflow.md index 2fa44b36..01bc8859 100644 --- a/docs/working/experiments/02-experiments/factorial-doe/workflow.md +++ b/docs/working/archive/superseded/factorial-doe/workflow.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** The 2^6 factorial DoE guide, flagged obsolete 2026-10-09. +> Instead: experiments/bare_metal/README.md for the DoE as it runs now. Moved here from `docs/working/experiments/02-experiments/factorial-doe/workflow.md`. + + > **⚠ 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 diff --git a/docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md b/docs/working/archive/superseded/feedback-loops-analysis.md similarity index 97% rename from docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md rename to docs/working/archive/superseded/feedback-loops-analysis.md index fba29429..a86a8358 100644 --- a/docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md +++ b/docs/working/archive/superseded/feedback-loops-analysis.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09. +> Instead: its own header. Moved here from `docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md`. + + > **⚠ 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 diff --git a/docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md b/docs/working/archive/superseded/heartbeat-doe-corrected-design.md similarity index 97% rename from docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md rename to docs/working/archive/superseded/heartbeat-doe-corrected-design.md index 0bfbfe13..ba8723c2 100644 --- a/docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md +++ b/docs/working/archive/superseded/heartbeat-doe-corrected-design.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09. +> Instead: its own header. Moved here from `docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md`. + + > **⚠ SUPERSEDED (flagged 2026-10-09).** Superseded by `phase2-corrected.md` (the > "corrected and finalized" revision). Kept for historical record. diff --git a/docs/working/experiments/02-experiments/heartbeat-doe/design.md b/docs/working/archive/superseded/heartbeat-doe-design.md similarity index 98% rename from docs/working/experiments/02-experiments/heartbeat-doe/design.md rename to docs/working/archive/superseded/heartbeat-doe-design.md index 6d5184b1..c3160593 100644 --- a/docs/working/experiments/02-experiments/heartbeat-doe/design.md +++ b/docs/working/archive/superseded/heartbeat-doe-design.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09. +> Instead: its own header. Moved here from `docs/working/experiments/02-experiments/heartbeat-doe/design.md`. + + > **⚠ SUPERSEDED (flagged 2026-10-09).** Pre-correction draft; superseded first by > `corrected-design.md`, then by `phase2-corrected.md` (the finalized design). Kept for diff --git a/docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md b/docs/working/archive/superseded/heartbeat-rate-logging-plan.md similarity index 98% rename from docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md rename to docs/working/archive/superseded/heartbeat-rate-logging-plan.md index faaf98e3..a649311c 100644 --- a/docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md +++ b/docs/working/archive/superseded/heartbeat-rate-logging-plan.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09. +> Instead: its own header. Moved here from `docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md`. + + > **⚠ SUPERSEDED (flagged 2026-10-09).** Superseded by `instrumentation-plan.md`. Proposes the > earlier `HeartbeatRateSample` design; the live target is `HeartbeatTickSnapshot` diff --git a/docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md b/docs/working/archive/superseded/loop-5-sketch.md similarity index 96% rename from docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md rename to docs/working/archive/superseded/loop-5-sketch.md index 5df3f843..01ad80c3 100644 --- a/docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md +++ b/docs/working/archive/superseded/loop-5-sketch.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09 (an early design sketch of Loop #5). +> Instead: its own header; Loop #5 as built is v3/src/inference_engine.c. Moved here from `docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md`. + + > **⚠ 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 diff --git a/docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md b/docs/working/archive/superseded/steady-state-machine.md similarity index 95% rename from docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md rename to docs/working/archive/superseded/steady-state-machine.md index 774112a4..676a3a9d 100644 --- a/docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md +++ b/docs/working/archive/superseded/steady-state-machine.md @@ -1,4 +1,7 @@ - +> **SUPERSEDED (docs triage 2026-10-14).** Flagged obsolete 2026-10-09. +> Instead: its own header. Moved here from `docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md`. + + > **⚠ 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 diff --git a/docs/working/legal/README.md b/docs/working/legal/README.md index a13a5537..f34fc037 100644 --- a/docs/working/legal/README.md +++ b/docs/working/legal/README.md @@ -12,12 +12,12 @@ reorganization. They remain in `docs/` exactly where they were. | Path (unchanged) | What it is | |------------------|------------| | docs/patent/ (entire tree) | USPTO provisional patent: `main.tex` + `sections/`, compiled PDFs, USPTO forms (sb0015a/sb0016), `final_provisional/`, revision logs. | -| docs/DARPA_SSM_Proposal_James.docx | DARPA SSM grant proposal (Word). | -| docs/DARPA_SSM_Proposal_James.pdf | DARPA SSM grant proposal (PDF). | -| docs/SSM_DARPA_Complete_Proposal_James_FINAL.docx | DARPA SSM complete/final proposal (Word, "FINAL"). | +| docs/working/papers/proposals/DARPA_SSM_Proposal_James.docx | DARPA SSM grant proposal (Word). | +| docs/working/papers/proposals/DARPA_SSM_Proposal_James.pdf | DARPA SSM grant proposal (PDF). | +| docs/working/papers/proposals/SSM_DARPA_Complete_Proposal_James_FINAL.docx | DARPA SSM complete/final proposal (Word, "FINAL"). | | docs/SSM_DARPA_Summary_Slide.pptx | DARPA SSM summary slide deck. | -| docs/SYSTEM_NARRATIVE.tex | Technical narrative written for patent counsel and reviewers. | -| docs/SYSTEM_NARRATIVE.pdf | Compiled system narrative. | +| docs/working/papers/SYSTEM_NARRATIVE.tex | Technical narrative written for patent counsel and reviewers. | +| docs/working/papers/SYSTEM_NARRATIVE.pdf | Compiled system narrative. | ## Also deferred this pass (not legal, but left in place for safety) @@ -26,7 +26,7 @@ risks breaking `\includegraphics`. Deferred to a later, build-verified pass. | Path (unchanged) | What it is | |------------------|------------| -| docs/ontology.tex / docs/ontology.pdf | Formal ontology LaTeX source + compiled PDF (strong `formal/` candidate). | +| docs/working/papers/ontology.tex / docs/working/papers/ontology.pdf | Formal ontology LaTeX source + compiled PDF (strong `formal/` candidate). | | docs/ontology_diagrams.dot | Graphviz source for ontology diagrams. | | docs/fig_*.png / docs/fig_*.svg | Shared figure assets referenced by the ontology and/or system-narrative LaTeX. | diff --git a/docs/working/papers/ONTOLOGY.md b/docs/working/papers/ONTOLOGY.md index eeec6d2a..79069cbd 100644 --- a/docs/working/papers/ONTOLOGY.md +++ b/docs/working/papers/ONTOLOGY.md @@ -1,4 +1,4 @@ - + # StarForth Ontology, Taxonomy, and Lexicon **Version**: 1.0 diff --git a/docs/SYSTEM_NARRATIVE.pdf b/docs/working/papers/SYSTEM_NARRATIVE.pdf similarity index 100% rename from docs/SYSTEM_NARRATIVE.pdf rename to docs/working/papers/SYSTEM_NARRATIVE.pdf diff --git a/docs/SYSTEM_NARRATIVE.tex b/docs/working/papers/SYSTEM_NARRATIVE.tex similarity index 100% rename from docs/SYSTEM_NARRATIVE.tex rename to docs/working/papers/SYSTEM_NARRATIVE.tex diff --git a/docs/ontology.pdf b/docs/working/papers/ontology.pdf similarity index 100% rename from docs/ontology.pdf rename to docs/working/papers/ontology.pdf diff --git a/docs/ontology.tex b/docs/working/papers/ontology.tex similarity index 100% rename from docs/ontology.tex rename to docs/working/papers/ontology.tex diff --git a/docs/DARPA_SSM_Proposal_James.docx b/docs/working/papers/proposals/DARPA_SSM_Proposal_James.docx similarity index 100% rename from docs/DARPA_SSM_Proposal_James.docx rename to docs/working/papers/proposals/DARPA_SSM_Proposal_James.docx diff --git a/docs/DARPA_SSM_Proposal_James.pdf b/docs/working/papers/proposals/DARPA_SSM_Proposal_James.pdf similarity index 100% rename from docs/DARPA_SSM_Proposal_James.pdf rename to docs/working/papers/proposals/DARPA_SSM_Proposal_James.pdf diff --git a/docs/SSM_DARPA_Complete_Proposal_James_FINAL.docx b/docs/working/papers/proposals/SSM_DARPA_Complete_Proposal_James_FINAL.docx similarity index 100% rename from docs/SSM_DARPA_Complete_Proposal_James_FINAL.docx rename to docs/working/papers/proposals/SSM_DARPA_Complete_Proposal_James_FINAL.docx diff --git a/docs/working/specifications/README.md b/docs/working/specifications/README.md index cf00fce5..521242e2 100644 --- a/docs/working/specifications/README.md +++ b/docs/working/specifications/README.md @@ -14,7 +14,7 @@ extracted here. ## See also -- [`docs/03-architecture/word-acl/README.md`](../../03-architecture/word-acl/README.md) +- [`docs/reference/word-acl/README.md`](../../03-architecture/word-acl/README.md) — the ACL spec, which has not been moved into this directory. - [`docs/working/README.md`](../README.md) — the full `working/` layout. - [Project root](../../../README.md) diff --git a/kernel/include/starkernel/capsule.h b/kernel/include/starkernel/capsule.h index f9d9d852..883c85e5 100644 --- a/kernel/include/starkernel/capsule.h +++ b/kernel/include/starkernel/capsule.h @@ -24,7 +24,7 @@ * capsule.h - Init Capsule Architecture (M7.1) * * Content-addressed, immutable init capsules for VM birth. - * See docs/lithosananke/M7.1.md for full specification. + * See docs/reference/M7.1.md for full specification. * * Key invariants: * - Exactly ONE production (p) INIT defines a baby VM diff --git a/v3/Makefile b/v3/Makefile index 930d6253..60a011a3 100644 --- a/v3/Makefile +++ b/v3/Makefile @@ -564,7 +564,7 @@ rpi4-fastest: # RISC-V 64 - cross-compile via clang (GCC fails to build this tree under # -std=c99: a nanosleep visibility failure, not yet root-caused — see -# docs/lithosananke/hosted-acceptance-test/README.md and +# docs/reference/hosted-acceptance-test/README.md and # docs/working/archive/session-logs/2026-07-24-punch-list.md item #3). # CFLAGS deliberately does NOT reuse $(BASE_CFLAGS): BASE_CFLAGS hardcodes # -std=c99, and clang needs -std=c11 -pthread here. This mirrors the exact