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

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
+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).