rajames/LithosAnanke
1
1
Fork 0
Code Issues 83 Pull Requests 1 Actions Packages Projects 1 Releases 6 Activity

docs: reorganise -- current reference gathered, finished work archived, superseded and dead ideas marked as such

Browse Source 
docs/CLAUDE.md Phase 2, 2026-10-14.  All moves by git mv; every archived
file carries a header saying what it is, why, and where to look instead.

- docs/reference/ (new): roadmap and versioning policy, M7.1, word-ACL
  design, kernel args, hosted acceptance test, dictionary, primitives,
  ontology, L8 table -- previously spread over docs/, docs/lithosananke/
  and docs/03-architecture/.
- docs/working/archive/historical/: finished work (session plan, test-gap
  audit, birthing plan, fix write-ups, the January architecture draft).
- docs/working/archive/superseded/: the Hermes-VM Tripod docs and July
  Hermes designs (-> FABRIC-3.5/3.6), the StarForth roadmap, every working
  doc already flagged superseded or obsolete.
- docs/working/archive/dead/: the hal_* target contract (never adopted),
  L4Re, metrics-and-knobs.
- Papers and proposals into docs/working/papers/.
- References rewritten across the repo (not logs/, not docs/patent/);
  CLAUDE.md's documentation section rewritten.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-14 16:03:56 -04:00
co-authored by Claude Opus 5.5
parent 1a4b163861
commit 7aed588f78
116 changed files with 305 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/CLAUDE.md
+23 -21
View File
@@ -119,9 +119,8 @@ about "which line am I on."
## Word-Level ACL System — Complete through Phase 7 (independently verified) ## 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 **Design doc:** `docs/reference/word-acl/DESIGN.md` (moved there from the old
`docs/03-architecture/` tree alongside the newer `docs/formal/`/`docs/working/` restructure — `docs/03-architecture/` tree in the 2026-10-14 docs reorganisation).
both exist here; this path is still current for ACL specifically).
The word-level ACL system is fully implemented, including kernel parity. Key constraints: The word-level ACL system is fully implemented, including kernel parity. Key constraints:
@@ -501,7 +500,7 @@ mistakenly invoke).
## Roadmap ## 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 ✅") — 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 not a copy of the standalone StarForth repo's roadmap. Prefer these when citing roadmap
status for kernel work. status for kernel work.
@@ -575,25 +574,28 @@ capsule and compare dict hashes. Zero-deviation means 0% algorithmic variance.
## Documentation ## Documentation
Key files (this repo has both the older `docs/03-architecture/` tree — still current for **Start at `docs/README.md`** -- the map: where each kind of document lives and which one is
ACL/Tripod specifically — and the newer restructured `docs/formal/`/`docs/working/`/ authoritative for what. `docs/INDEX.md` lists every document with its status;
`docs/patent/` trees, plus a repo-specific `docs/lithosananke/` tree): `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 - `README.md` -- project overview and quick start
- `docs/lithosananke/SYSTEM_ARCHITECTURE.md` — full kernel + VM design - `docs/fabric/` -- the design and work record (`FABRIC-3.md` living; the others closed)
- `docs/lithosananke/hal/` — HAL reference - `docs/v4.0.0/` -- StarForth v4 design
- `docs/lithosananke/M7.1.md` — capsule birth protocol design - `docs/reference/` -- current reference: `ROADMAP.md` (roadmap and versioning policy),
- `docs/lithosananke/ROADMAP.md` — milestone plan through self-hosting `M7.1.md` (capsule birth protocol), `word-acl/DESIGN.md` (word-level ACL), `kernel-args/`,
- `docs/lithosananke/hosted-acceptance-test/README.md` — the hosted-VM acceptance test `hosted-acceptance-test/`, `DICTIONARY.md`, `STARFORTH_PRIMITIVES.md`, `ONTOLOGY.md`
writeup referenced from the standalone StarForth repo's own docs - `boards/BRINGUP.md` -- bare-metal bring-up checklist and blockers
- `docs/03-architecture/tripod/`, `docs/03-architecture/word-acl/DESIGN.md` - `kernel/src/hal/README.md` -- the HAL as built (the proposed `hal_*` contract was never
- `docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md` — Tripod/Hermes/Artemis adopted; it is archived as dead)
physics + build-system history - `docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md` -- fleet physics and
- `docs/working/architecture/getting-started/DEVELOPER.md` — dev setup, Kconfig reference build-system history (pre-reshuffle: it still names the Hermes VM)
- `ROADMAP.md`, `CHANGELOG.md` - `docs/working/architecture/getting-started/DEVELOPER.md` -- dev setup, Kconfig reference
- `experiments/bare_metal/README.md` — **mandatory read before touching capsules** (block - `CHANGELOG.md`
- `experiments/bare_metal/README.md` -- **mandatory read before touching capsules** (block
namespace rules, see ACL section above) 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` - `sbom.spdx` / `sbom.spdx.json`
--- ---
CONTRIBUTING.md
+2 -2
View File
@@ -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) 3. **Run tests**: `make test` (all 780+ tests must pass)
4. **Read** [ONTOLOGY.md](ONTOLOGY.md) for formal definitions and terminology 4. **Read** [ONTOLOGY.md](ONTOLOGY.md) for formal definitions and terminology
5. **Read** `docs/CLAUDE.md` for project overview 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. **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 ### Platform Abstraction
- **Never** call platform-specific APIs directly from VM code - **Never** call platform-specific APIs directly from VM code
- **Always** use HAL interfaces (`hal_time.h`, `hal_memory.h`, etc.) - **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 ### Memory Safety
- Use `vaddr_t` for VM addresses (not C pointers) - Use `vaddr_t` for VM addresses (not C pointers)
README.md
+4 -4
View File
@@ -122,13 +122,13 @@ make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
| | | | | |
|---|---| |---|---|
| [System Architecture](docs/lithosananke/SYSTEM_ARCHITECTURE.md) | Full kernel + VM design | | [System Architecture](docs/working/archive/historical/2026-01-27-system-architecture-draft.md) | Full kernel + VM design |
| [HAL Reference](docs/lithosananke/hal/) | Hardware abstraction layer interfaces | | [HAL Reference](kernel/src/hal/README.md) | Hardware abstraction layer, as built |
| [Capsule System — M7.1](docs/lithosananke/M7.1.md) | Capsule birth protocol design | | [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 | | [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 | | [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 | | [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 |
--- ---
docs/INDEX.md
+31 -31
View File
@@ -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/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/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/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/working/papers/proposals/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.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/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/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. | | 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/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/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/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.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/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. | | 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/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/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/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/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/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.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/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/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/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/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/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/working/papers/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.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/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/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/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/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/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_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_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/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/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/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/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/experiments/02-experiments/factorial-doe/index.md | Index for factorial DoE docs | OBSOLETE | Points to stale doc paths; describes retired architecture. | | docs/working/archive/superseded/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/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/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/archive/superseded/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/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/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/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. | | 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/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/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/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/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/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/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/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/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/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/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/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/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/architecture/03-architecture/hal/platform-implementations.md | Example hal_* implementations for Linux and kernel platforms | OBSOLETE | Assumes src/platform/<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/platform-implementations.md | Example hal_* implementations for Linux and kernel platforms | OBSOLETE | Assumes src/platform/<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/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/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/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/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/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/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/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-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/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/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/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. | | 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/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/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/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/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/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. | | 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/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/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/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/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/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_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/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/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/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/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 | | 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/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/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/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/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/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 | | 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 |
docs/book/Makefile
+2 -2
View File
@@ -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. # fragment name : Markdown source. The order of \input lines is main.tex's.
CHAPTERS := \ CHAPTERS := \
ontology:docs/ONTOLOGY.md \ ontology:docs/reference/ONTOLOGY.md \
roadmap:docs/ROADMAP.md \ roadmap:docs/working/archive/superseded/2025-12-14-starforth-roadmap.md \
boards:boards/README.md \ boards:boards/README.md \
justification:docs/v4.0.0/JUSTIFICATION.md \ justification:docs/v4.0.0/JUSTIFICATION.md \
decomposition:docs/v4.0.0/DECOMPOSITION.md \ decomposition:docs/v4.0.0/DECOMPOSITION.md \
docs/book/main.tex
+2 -2
View File
@@ -122,8 +122,8 @@ are reproduced as written, including their struck-through corrections.
Chapter & Source \\ Chapter & Source \\
\midrule \midrule
\endhead \endhead
Ontology & \texttt{docs/ONTOLOGY.md} \\ Ontology & \texttt{docs/reference/ONTOLOGY.md} \\
Roadmap & \texttt{docs/ROADMAP.md} \\ Roadmap & \texttt{docs/working/archive/superseded/2025-12-14-starforth-roadmap.md} \\
Boot targets & \texttt{boards/README.md} \\ Boot targets & \texttt{boards/README.md} \\
v4 justification & \texttt{docs/v4.0.0/JUSTIFICATION.md} \\ v4 justification & \texttt{docs/v4.0.0/JUSTIFICATION.md} \\
v4 decomposition & \texttt{docs/v4.0.0/DECOMPOSITION.md} \\ v4 decomposition & \texttt{docs/v4.0.0/DECOMPOSITION.md} \\
docs/fabric/FABRIC-0.md
+6 -6
View File
@@ -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, quotes that reproduce an earlier section verbatim, and in §12's preserved question list,
which several sections quote. 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. 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 > `#ifdef __STARKERNEL__`, or elsewhere is an open question for that later item, not
> decided here. > 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 > 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 > 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 > 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), > decision #4 -- both text paths coexist. Per this item's own posture (matching 4.3.6g),
> stopping here before scoping REPL wiring (M8). > 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 > 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 > 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 > 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 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 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 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 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, the code") — restated here specifically so 4.4u's TAB-toggle has an accurate prerequisite,
not because the earlier conclusion was in doubt. 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), 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 screendump showing the typed text landed in the REPL strip; three-arch QEMU boot + logs per
CLAUDE.md. 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 > **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 > 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) ### 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: M8 section entirely (marked OBSOLETE there, kept for history only). Original visual reference:
[`repl-mockup.png`](repl-mockup.png). [`repl-mockup.png`](repl-mockup.png).
docs/fabric/FABRIC-1.md
+2 -2
View File
@@ -1425,14 +1425,14 @@ evidence nothing regressed.
`docs/CLAUDE.md`'s own correction, made in the same pass, for the doc-toolchain findings — `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 `doxygen` installed, `docs/Makefile` pointer corrected — and this section's own proof-count
reconciliation above for the Isabelle/HOL findings): 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 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, 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 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. (real implementation is `virtio_blk.c`) — not fixed this pass, flagged.
- [ ] Top-level `ROADMAP.md` (StarForth-era, "Phase 0 Complete... Phase 1 Starting," dated - [ ] 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. 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 is still "remaining" — direct contradiction with `.claude/CLAUDE.md`, which states
Phase 7 is independently verified complete. Not fixed. Phase 7 is independently verified complete. Not fixed.
- [ ] `VM-FLEET-ATTRACTOR-DESIGN-20260705.md` claims `doe-campaign.4th` is "broken and being - [ ] `VM-FLEET-ATTRACTOR-DESIGN-20260705.md` claims `doe-campaign.4th` is "broken and being
docs/fabric/FABRIC-2.md
+4 -4
View File
@@ -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) ### From FABRIC-1.md §J — Maintainability sweep (2026-08-18)
- [x] **Fixed 2026-08-26 (commit `cbe7b49`), stale carry-forward closed 2026-08-28.** - [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 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 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 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 - [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 `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 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.** - [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 still "remaining" — direct contradiction with `.claude/CLAUDE.md`, which states Phase 7
is independently verified complete. Phase 7 restated as independently-verified complete and is independently verified complete. Phase 7 restated as independently-verified complete and
the stale lithosananke-branch-parity framing removed by `cbe7b49`. 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. each.
**The versioning split, decided 2026-08-28 — now standing policy, see **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 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 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 **real-hardware release** — the point where the same story transfers to bare metal on a real
docs/fabric/FABRIC-3.5.md
+6 -6
View File
@@ -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` **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 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 `.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. 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), **Also in scope:** `capsules/README.md` (lists `hermes/init.4th` as a live personality),
`ROADMAP.md` / `docs/lithosananke/ROADMAP.md`, `CHANGELOG.md`, `README.md`, `ROADMAP.md` / `docs/reference/ROADMAP.md`, `CHANGELOG.md`, `README.md`,
`docs/lithosananke/SYSTEM_ARCHITECTURE.md` and `M7.1.md`, and `proof/COVERAGE.md` (after the `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). §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. `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: 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): # FABRIC-2.md §G — X.0.0 = QEMU release, X.5.0 = hardware bare-metal release):
# v1.0.x — serial-only production (released) # v1.0.x — serial-only production (released)
# v1.5.x — framebuffer VT100 terminal/console milestone (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:** mention. **Add the line wherever the table lives:**
1. `Makefile.starkernel` (the copy above, beside the `LITHOS_VERSION` edit itself). 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. upstream source.
3. `FABRIC-2.md` §G is the origin of the scheme but is **CLOSED/ARCHIVAL** — **cite it, do not 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' 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 - ✅ **Versioning policy — CLOSED** (§XXX). All three §XXIX.3 conflicts resolved; LTS criteria
ratified; engine `VERSION` closed as a rule. ratified; engine `VERSION` closed as a rule.
- ✅ **This release is `2.1.0`** (§XXVIII), even major, working line. - ✅ **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. (§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. - ⬜ Engine `VERSION` applied at tag time per §XXX.6's rule.
docs/fabric/FABRIC-3.6.md
+1 -1
View File
@@ -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 `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" — 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) 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 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, 2026-08-28 policy, not just a stale table — replaced with the ratified §XXX policy text,
the old text kept struck-through in a `<details>` block for traceability, and the the old text kept struck-through in a `<details>` block for traceability, and the
docs/fabric/FABRIC-3.md
+1 -1
View File
@@ -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 - Build a **new, blank 1 GiB `disk/artemis.img`** from scratch -- not a resize of the current
file. No migration code written or needed. file. No migration code written or needed.
- **Zuse re-minted fresh** on the new image (genesis marker, root CA placement, per - **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 -- `project_phase8_milestone6_complete.md`'s already-verified entropy/signing/block-fence chain --
same mechanism, new device, not new code). same mechanism, new device, not new code).
- **All 8 thumbdrive identities re-minted** (`project_thumbdrive_identities_minted_20260906.md`: - **All 8 thumbdrive identities re-minted** (`project_thumbdrive_identities_minted_20260906.md`:
docs/formal/experiments/main.tex
+4 -4
View File
@@ -48,7 +48,7 @@
\part{$2^7$ Factorial Campaign} \part{$2^7$ Factorial Campaign}
\chapter{Campaign Design} \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 %% docs/working/experiments/campaigns/doe_2x7/README.md
\input{../scraps/experiments/02-experiments/factorial-doe/guide} \input{../scraps/experiments/02-experiments/factorial-doe/guide}
\input{../scraps/experiments/02-experiments/factorial-doe/workflow} \input{../scraps/experiments/02-experiments/factorial-doe/workflow}
@@ -57,7 +57,7 @@
\input{../scraps/experiments/campaigns/shape_validation/README} \input{../scraps/experiments/campaigns/shape_validation/README}
\chapter{Incompatible Configurations} \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} \input{../scraps/experiments/02-experiments/factorial-doe/incompatible-configs}
\chapter{Campaign Results — 90 Runs} \chapter{Campaign Results — 90 Runs}
@@ -146,8 +146,8 @@
\part{Supplementary Campaigns} \part{Supplementary Campaigns}
\chapter{Heartbeat DoE} \chapter{Heartbeat DoE}
%% SOURCE: docs/working/experiments/02-experiments/heartbeat-doe/design.md %% SOURCE: docs/working/archive/superseded/heartbeat-doe-design.md
%% docs/working/experiments/02-experiments/heartbeat-doe/corrected-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/design}
\input{../scraps/experiments/02-experiments/heartbeat-doe/corrected-design} \input{../scraps/experiments/02-experiments/heartbeat-doe/corrected-design}
\input{../scraps/experiments/02-experiments/heartbeat-doe/implementation-summary} \input{../scraps/experiments/02-experiments/heartbeat-doe/implementation-summary}
docs/formal/scraps/architecture/03-architecture/adaptive-systems/loop-5-sketch.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/adaptive-systems/loop-5-sketch %% 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 %% STATUS: WORKING
%% FITS: dev-guide/ch-physics %% FITS: dev-guide/ch-physics
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/README.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/README %% 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 %% STATUS: WORKING
%% FITS: dev-guide/ch-platform %% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/interfaces.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/interfaces %% 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 %% STATUS: WORKING
%% FITS: dev-guide/ch-platform %% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/migration-plan.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/migration-plan %% 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 %% STATUS: WORKING
%% FITS: dev-guide/ch-platform %% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/overview.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/overview %% 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 %% STATUS: WORKING
%% FITS: dev-guide/ch-platform %% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/platform-implementations.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/platform-implementations %% 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 %% STATUS: WORKING
%% FITS: dev-guide/ch-platform %% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/starkernel-integration.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/starkernel-integration %% 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 %% STATUS: WORKING
%% FITS: dev-guide/ch-platform %% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/heartbeat-system/implementation-plan.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/heartbeat-system/implementation-plan %% 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 %% STATUS: HISTORICAL
%% FITS: dev-guide/ch-heartbeat %% FITS: dev-guide/ch-heartbeat
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/physics-engine/feedback-loops-analysis.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/physics-engine/feedback-loops-analysis %% 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 %% STATUS: HISTORICAL
%% FITS: dev-guide/ch-physics %% FITS: dev-guide/ch-physics
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/physics-engine/metrics-and-knobs.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/physics-engine/metrics-and-knobs %% 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 %% STATUS: WORKING
%% FITS: dev-guide/ch-physics, cookbook/ch-physics %% FITS: dev-guide/ch-physics, cookbook/ch-physics
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/physics-engine/steady-state-machine.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/physics-engine/steady-state-machine %% 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 %% STATUS: CURRENT
%% FITS: dev-guide/ch-physics %% FITS: dev-guide/ch-physics
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/getting-started/quick-start/factorial-doe.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/getting-started/quick-start/factorial-doe %% 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 %% STATUS: CURRENT
%% FITS: cookbook/ch-doe %% FITS: cookbook/ch-doe
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/archive/DOCUMENTATION_AUDIT.tex
+1 -1
View File
@@ -36,7 +36,7 @@ The audit assigned priority as follows.
\begin{itemize} \begin{itemize}
\item Add missing \texttt{README} files to all numbered directories. \item Add missing \texttt{README} files to all numbered directories.
\item Update \texttt{CLAUDE.md} to reflect HAL and StarKernel vision. \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} \end{itemize}
\textbf{Medium priority:} \textbf{Medium priority:}
docs/formal/scraps/experiments/02-experiments/L8_WIRING_PLAN.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/L8_WIRING_PLAN %% 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 %% STATUS: HISTORICAL
%% FITS: experiments/ch-l8 %% FITS: experiments/ch-l8
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/experiments/02-experiments/factorial-doe/guide.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/factorial-doe/guide %% 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 %% STATUS: CURRENT
%% FITS: experiments/ch-factorial, cookbook/ch-doe %% FITS: experiments/ch-factorial, cookbook/ch-doe
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/experiments/02-experiments/factorial-doe/incompatible-configs.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/factorial-doe/incompatible-configs %% 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 %% STATUS: CURRENT
%% FITS: experiments/ch-factorial %% FITS: experiments/ch-factorial
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/experiments/02-experiments/factorial-doe/index.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/factorial-doe/index %% 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 %% STATUS: CURRENT
%% FITS: experiments/ch-factorial %% FITS: experiments/ch-factorial
%% EDITORIAL: lifted — prose rewritten to press voice %% EDITORIAL: lifted — prose rewritten to press voice

Some files were not shown because too many files have changed in this diff Show More