diff --git a/.claude/ARTEMIS.md b/.claude/ARTEMIS.md index 9983897..d564b2a 100644 --- a/.claude/ARTEMIS.md +++ b/.claude/ARTEMIS.md @@ -4,6 +4,15 @@ --- +> **SUPERSEDED (Captain Bob, 2026-08-15).** This document is no longer authoritative. +> `FABRIC.md`/`FABRIC-2.md` (repo root — read `FABRIC-2.md` first, it is the current/living +> one) are the sole design-of-record for Artemis work now. Kept here as historical record +> only; do not read this for current design authority, and do not cite it in place of +> `FABRIC.md`/`FABRIC-2.md`. Artemis becoming the pre-Artemis-closeout blocker (item 4.6) is +> tracked in `FABRIC-2.md`, not here. See `.claude/CLAUDE.md`'s own pointer. + +--- + ## Language Constraint — Non-Negotiable All Artemis implementation is in StarForth dialect ONLY. diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 283d2b7..cf7f339 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -8,9 +8,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co > if you're touching documentation build tooling. This file at `.claude/CLAUDE.md` is the > authoritative reference for everything else. -> **Tripod:** `.claude/TRIPOD.md` is authoritative for all Tripod VM (Hera/Hermes/Artemis) work. Read it completely before touching any Tripod code. -> **Hermes:** `.claude/HERMES.md` is authoritative for all Hermes VM work. Read before touching Hermes. -> **Artemis:** `.claude/ARTEMIS.md` is authoritative for all Artemis VM work. Read before touching Artemis. Note: as of 2026-08-02 the flat-pool storage scope ("Immediate Goal" in that file) is **implemented and live** — Artemis boots and manages `disk/artemis.img` in the Tripod fleet on every kernel boot, all three architectures. Zones, USB hot-plug, ACL records, and PKI remain deferred future material — see that file's "Build Status" section for exactly what's verified vs. not. +> **Superseded subsystem docs (Captain Bob, 2026-08-15):** `.claude/TRIPOD.md`, +> `.claude/HERMES.md`, `.claude/ARTEMIS.md`, and `.claude/CONSOLE.md` are all superseded — +> `FABRIC.md` (design history) and `FABRIC-2.md` (current/living, read this one first) are +> the sole authoritative source for Tripod/Hermes/Artemis/Console work now. The four +> subsystem docs remain in the repo as historical record only; each carries its own +> superseded-header pointing here. Do not treat them as current, do not read them for design +> authority, and do not cite them in place of `FABRIC.md`/`FABRIC-2.md`. > **Scope:** This repo is LithosAnanke — the bare-metal UEFI kernel that boots StarForth > directly on hardware. StarForth (the hosted FORTH-79 VM) has its own separate repository diff --git a/.claude/CONSOLE.md b/.claude/CONSOLE.md index 528036a..7f5ec56 100644 --- a/.claude/CONSOLE.md +++ b/.claude/CONSOLE.md @@ -18,6 +18,17 @@ --- +> **SUPERSEDED (Captain Bob, 2026-08-15).** This document is no longer authoritative, and its +> core premise below ("Console is a 4th Tripod VM, Quadrupod, StarForth-dialect-only") was +> architecturally reversed by a later, decided ruling: `FABRIC.md` §17.5 — the framebuffer is +> a **utility**, not a patron, not a VM. What actually shipped is direct C +> (`src/starkernel/hal/console.c`/`vt100.c`/`framebuffer.c` plus keyboard drivers), called +> straight from the kernel, no Hera-spawned Console VM anywhere. `FABRIC.md`/`FABRIC-2.md` +> (repo root — read `FABRIC-2.md` first) are the sole design-of-record for Console/framebuffer +> work now. Kept here as historical record only. See `.claude/CLAUDE.md`'s own pointer. + +--- + ## The Pivot This Document Reflects Console was first framed as "wrap the existing bitmap/VT100 framebuffer driver in a 4th Tripod VM." That framing is diff --git a/.claude/HERMES.md b/.claude/HERMES.md index 532cdf7..6188d63 100644 --- a/.claude/HERMES.md +++ b/.claude/HERMES.md @@ -4,6 +4,15 @@ --- +> **SUPERSEDED (Captain Bob, 2026-08-15).** This document is no longer authoritative. +> `FABRIC.md`/`FABRIC-2.md` (repo root — read `FABRIC-2.md` first, it is the current/living +> one) are the sole design-of-record for Hermes work now. Kept here as historical record +> only — note its message-layout table (8 cells) is confirmed stale against the real shipped +> capsule (9 cells, `capsules/hermes/init.4th`), see `FABRIC-2.md`. Do not read this for +> current design authority. See `.claude/CLAUDE.md`'s own pointer. + +--- + ## Language Constraint — Non-Negotiable All Hermes implementation is in StarForth dialect ONLY. diff --git a/.claude/TRIPOD.md b/.claude/TRIPOD.md index 0b91e2a..50bc92e 100644 --- a/.claude/TRIPOD.md +++ b/.claude/TRIPOD.md @@ -4,6 +4,14 @@ --- +> **SUPERSEDED (Captain Bob, 2026-08-15).** This document is no longer authoritative. +> `FABRIC.md`/`FABRIC-2.md` (repo root — read `FABRIC-2.md` first, it is the current/living +> one) are the sole design-of-record for Tripod work now. Kept here as historical record +> only; do not read this for current design authority, and do not cite it in place of +> `FABRIC.md`/`FABRIC-2.md`. See `.claude/CLAUDE.md`'s own pointer. + +--- + ## The Tripod: What It Is Three StarForth VMs constitute the Tripod. They are not generic workers. Each holds a diff --git a/FABRIC-2.md b/FABRIC-2.md index fc1fe03..f363b19 100644 --- a/FABRIC-2.md +++ b/FABRIC-2.md @@ -249,9 +249,11 @@ and recorded. > done: the vocabulary-chain mechanics, the block-window cache, the hot-words cache — > each flagged as its own project, not started. -- [ ] **5.3 — Shrink the subsystem documents.** `ARTEMIS.md`, `HERMES.md`, `CONSOLE.md`, +- [x] **5.3 — Shrink the subsystem documents.** `ARTEMIS.md`, `HERMES.md`, `CONSOLE.md`, `TRIPOD.md` need trimming now that `FABRIC-2.md` (via `FABRIC.md`) is the design-of-record. - Not started. **Specific pending edit found within this item:** `TRIPOD.md`'s own Immediate + **CLOSED 2026-08-15 — see Section F.1 above:** Captain Bob ruled all four superseded + outright, not case-by-case; resolved via a superseded-header banner on each, not a + line-count trim. **Specific pending edit found within this item:** `TRIPOD.md`'s own Immediate Goal section still describes Hera spawning Hermes and Artemis automatically at boot — item 0.1 undid that behavior, and the doc was never updated to match. @@ -696,34 +698,28 @@ together. **F.3** is the condensed punch list distilled from both. - [x] `tools/README.md`'s stale `fbtest.c` row → `ttftest.c`. Doc-only, no build impact. Commit `b9e8fdc`. -**Needs Captain Bob's ruling — each already investigated as far as it can go without one:** +**RESOLVED 2026-08-15 — Captain Bob ruled directly, no per-document weighing needed:** +`TRIPOD.md`, `HERMES.md`, `ARTEMIS.md`, `CONSOLE.md` are **all** superseded — not +individually assessed for partial staleness, not a case-by-case rewrite-vs-header call. +`FABRIC.md`/`FABRIC-2.md` are the sole design-of-record for all Tripod/Hermes/Artemis/ +Console work now. Fixed by adding a superseded-header banner (pointing here) to the top of +all four `.claude/*.md` files, and correcting `.claude/CLAUDE.md`'s own pointer paragraph +(previously claimed these four were individually "authoritative" — now redirects to +`FABRIC.md`/`FABRIC-2.md`). This closes all three items below at once: -- [ ] **`CONSOLE.md`'s fate** (item 5.3). Dated 2026-08-02, states outright "there is no - Console code in the tree yet" — no longer true in two ways: (1) its central design premise - (Console as a 4th Tripod VM, "Quadrupod not Tripod") was superseded by `FABRIC.md` §17.5's - later, decided ruling — framebuffer is a utility, not a patron, confirmed by grepping the - fleet machinery for a Console VM kind (zero hits); (2) its "explicitly out of scope" list - (no keyboard driver) is now false — `i8042.c` and `virtio_input.c` both exist and a - keyboard-to-REPL bridge is live (item 4.4v). Some content is still accurate (the Y-up - coordinate flip, stroke-font/TrueType glyph work) but was not re-verified line-by-line. - **Question for Bob:** full rewrite against `FABRIC.md` §17.5/§27 as the design-of-record, - or an explicit "superseded, kept for history" header on the existing document? -- [ ] **`HERMES.md`'s stale block map and cell-count table** (item 5.3). Its "Message - node — 8 cells" layout table contradicts the shipped capsule's own `9 CONSTANT MSG-CELLS` - (`capsules/hermes/init.4th`) — the real layout stores a Stadium cell index at offset 5 (not - raw heat) and adds an `ORIG-TYPE` field at offset 8 the doc doesn't mention. Separately its - "v1 Block Map — LOCKED" section lists only blocks 4100–4128; the actual capsule also has - 4142, 4144–4159, 4175, 4176 — a substantial share of item 4.2's Stadium-integration content - isn't in the documented map at all. The doc closes with "if it conflicts with the codebase, - the codebase is wrong" — that claim doesn't hold here; the 9-cell layout is a deliberate, - intentional change the doc was never updated to match. **Question for Bob:** reconcile the - full map now, or defer — Hermes's own message layout may shift again once Artemis becomes a - live message endpoint, which argues for waiting. -- [ ] **5.3's larger ask** — actually shrinking `ARTEMIS.md`/`HERMES.md`/`CONSOLE.md`/ - `TRIPOD.md`'s line counts now that `FABRIC.md`/`FABRIC-2.md` are the design-of-record, not - just fixing stale claims (`ARTEMIS.md` and `TRIPOD.md` already got that narrower fix). - Blocked on the two rulings above — can't shrink a document whose fate/content isn't settled - yet. +- [x] ~~`CONSOLE.md`'s fate~~ — superseded header added, no rewrite. Its architectural + reversal (VM-per-patron vs. direct-C-utility) is fully described in `FABRIC.md` §17.5, + which is now the pointer target — no need to re-derive that content into `CONSOLE.md` + itself. +- [x] ~~`HERMES.md`'s stale block map and cell-count table~~ — moot now that the document is + historical-only, not living: reconciling a superseded document's internal accuracy is not + useful work. The real, current block map lives in `capsules/hermes/init.4th` itself + (`grep '^Block '`), which is authoritative by construction — no document needed to restate + it. +- [x] ~~5.3's larger ask (shrinking the four documents)~~ — superseded by the header + approach: a one-paragraph banner accomplishes what "shrink to a pointer" was already + trying to do, without touching the historical content underneath. No further line-count + reduction planned. ### F.2 — Code & actionable-work track @@ -804,11 +800,10 @@ unreachable NULL-write, `m5_time_trust`/`m5_variance` dead fields. ### F.3 — Punch list -**Documentation — pending Captain Bob's call, one at a time:** - -- [ ] `CONSOLE.md` — full rewrite against §17.5/§27, or a "superseded" header? -- [ ] `HERMES.md` — reconcile block map + cell-count table now, or defer until after Artemis? -- [ ] 5.3 — shrink `ARTEMIS.md`/`HERMES.md`/`CONSOLE.md`/`TRIPOD.md` (blocked on the two above) +**Documentation — CLOSED 2026-08-15.** All four subsystem docs (`TRIPOD.md`, `HERMES.md`, +`ARTEMIS.md`, `CONSOLE.md`) ruled superseded outright by Captain Bob, not case-by-case. +Superseded-header banners added to all four; `.claude/CLAUDE.md`'s own pointer corrected to +redirect to `FABRIC.md`/`FABRIC-2.md`. Nothing left pending in this track. **Code / actionable — pending Captain Bob's call or Artemis landing:** @@ -819,10 +814,11 @@ unreachable NULL-write, `m5_time_trust`/`m5_variance` dead fields. Phase 8 (identity storage), out of this pass's scope - [ ] 5.1 (DoE re-run) + ACL-RWT re-measurement — run now, or wait for Artemis (recommended)? -**Net result:** F.1 has one closed item and three documentation questions; F.2 has three -closed items, four sequencing-blocked items (no ruling needed, just not startable yet), and -one code question. Nothing in either track's open half is closeable without either Artemis or -an explicit decision from Captain Bob — which is the state this pass was asked to produce. +**Net result:** F.1 (documentation) is fully closed. F.2 has four closed items (three from +the original pass plus the RAM-derived Stadium VM-count fix, Section G), four +sequencing-blocked items (no ruling needed, just not startable yet), and one open code +question (§12 Q5). Nothing left open is closeable without either Artemis or an explicit +decision from Captain Bob on §12 Q5. ---