docs: mark TRIPOD/HERMES/ARTEMIS/CONSOLE.md superseded by FABRIC.md/FABRIC-2.md

Captain Bob ruled directly: all four subsystem docs are superseded, not
individually assessed for partial staleness case-by-case. FABRIC.md
(design history) and FABRIC-2.md (current/living) are the sole
design-of-record for Tripod/Hermes/Artemis/Console work now.

Added a superseded-header banner to the top of all four .claude/*.md
files, pointing to FABRIC.md/FABRIC-2.md. Corrected .claude/CLAUDE.md's
own pointer paragraph, which previously claimed these four were
individually "authoritative" for their subsystems - that's now wrong.

Closes FABRIC-2.md's three open documentation questions (CONSOLE.md's
fate, HERMES.md's stale block map, 5.3's larger shrink-the-docs ask) at
once: the header approach makes reconciling a superseded document's
internal accuracy moot, and accomplishes what "shrink to a pointer" was
already trying to do.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-15 09:26:59 -04:00
co-authored by Claude Sonnet 5
parent 00e657019e
commit c5442c8377
6 changed files with 78 additions and 41 deletions
+9
View File
@@ -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 ## Language Constraint — Non-Negotiable
All Artemis implementation is in StarForth dialect ONLY. All Artemis implementation is in StarForth dialect ONLY.
+7 -3
View File
@@ -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 > if you're touching documentation build tooling. This file at `.claude/CLAUDE.md` is the
> authoritative reference for everything else. > 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. > **Superseded subsystem docs (Captain Bob, 2026-08-15):** `.claude/TRIPOD.md`,
> **Hermes:** `.claude/HERMES.md` is authoritative for all Hermes VM work. Read before touching Hermes. > `.claude/HERMES.md`, `.claude/ARTEMIS.md`, and `.claude/CONSOLE.md` are all superseded —
> **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. > `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 > **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 > directly on hardware. StarForth (the hosted FORTH-79 VM) has its own separate repository
+11
View File
@@ -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 ## 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 Console was first framed as "wrap the existing bitmap/VT100 framebuffer driver in a 4th Tripod VM." That framing is
+9
View File
@@ -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 ## Language Constraint — Non-Negotiable
All Hermes implementation is in StarForth dialect ONLY. All Hermes implementation is in StarForth dialect ONLY.
+8
View File
@@ -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 ## The Tripod: What It Is
Three StarForth VMs constitute the Tripod. They are not generic workers. Each holds a Three StarForth VMs constitute the Tripod. They are not generic workers. Each holds a
+34 -38
View File
@@ -249,9 +249,11 @@ and recorded.
> done: the vocabulary-chain mechanics, the block-window cache, the hot-words cache — > done: the vocabulary-chain mechanics, the block-window cache, the hot-words cache —
> each flagged as its own project, not started. > 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. `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 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. 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. - [x] `tools/README.md`'s stale `fbtest.c` row → `ttftest.c`. Doc-only, no build impact.
Commit `b9e8fdc`. 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 - [x] ~~`CONSOLE.md`'s fate~~ — superseded header added, no rewrite. Its architectural
Console code in the tree yet" — no longer true in two ways: (1) its central design premise reversal (VM-per-patron vs. direct-C-utility) is fully described in `FABRIC.md` §17.5,
(Console as a 4th Tripod VM, "Quadrupod not Tripod") was superseded by `FABRIC.md` §17.5's which is now the pointer target — no need to re-derive that content into `CONSOLE.md`
later, decided ruling — framebuffer is a utility, not a patron, confirmed by grepping the itself.
fleet machinery for a Console VM kind (zero hits); (2) its "explicitly out of scope" list - [x] ~~`HERMES.md`'s stale block map and cell-count table~~ — moot now that the document is
(no keyboard driver) is now false — `i8042.c` and `virtio_input.c` both exist and a historical-only, not living: reconciling a superseded document's internal accuracy is not
keyboard-to-REPL bridge is live (item 4.4v). Some content is still accurate (the Y-up useful work. The real, current block map lives in `capsules/hermes/init.4th` itself
coordinate flip, stroke-font/TrueType glyph work) but was not re-verified line-by-line. (`grep '^Block '`), which is authoritative by construction — no document needed to restate
**Question for Bob:** full rewrite against `FABRIC.md` §17.5/§27 as the design-of-record, it.
or an explicit "superseded, kept for history" header on the existing document? - [x] ~~5.3's larger ask (shrinking the four documents)~~ — superseded by the header
- [ ] **`HERMES.md`'s stale block map and cell-count table** (item 5.3). Its "Message approach: a one-paragraph banner accomplishes what "shrink to a pointer" was already
node — 8 cells" layout table contradicts the shipped capsule's own `9 CONSTANT MSG-CELLS` trying to do, without touching the historical content underneath. No further line-count
(`capsules/hermes/init.4th`) — the real layout stores a Stadium cell index at offset 5 (not reduction planned.
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 41004128; the actual capsule also has
4142, 41444159, 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.
### F.2 — Code & actionable-work track ### F.2 — Code & actionable-work track
@@ -804,11 +800,10 @@ unreachable NULL-write, `m5_time_trust`/`m5_variance` dead fields.
### F.3 — Punch list ### F.3 — Punch list
**Documentation — pending Captain Bob's call, one at a time:** **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.
- [ ] `CONSOLE.md` — full rewrite against §17.5/§27, or a "superseded" header? Superseded-header banners added to all four; `.claude/CLAUDE.md`'s own pointer corrected to
- [ ] `HERMES.md` — reconcile block map + cell-count table now, or defer until after Artemis? redirect to `FABRIC.md`/`FABRIC-2.md`. Nothing left pending in this track.
- [ ] 5.3 — shrink `ARTEMIS.md`/`HERMES.md`/`CONSOLE.md`/`TRIPOD.md` (blocked on the two above)
**Code / actionable — pending Captain Bob's call or Artemis landing:** **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 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)? - [ ] 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 **Net result:** F.1 (documentation) is fully closed. F.2 has four closed items (three from
closed items, four sequencing-blocked items (no ruling needed, just not startable yet), and the original pass plus the RAM-derived Stadium VM-count fix, Section G), four
one code question. Nothing in either track's open half is closeable without either Artemis or sequencing-blocked items (no ruling needed, just not startable yet), and one open code
an explicit decision from Captain Bob — which is the state this pass was asked to produce. question (§12 Q5). Nothing left open is closeable without either Artemis or an explicit
decision from Captain Bob on §12 Q5.
--- ---