admin/LithosAnanake
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki 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
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,
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).
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 —
`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
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)
- [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
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`
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.
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
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 `<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
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`: