diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 9775217..13676c6 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -10,12 +10,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co > **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-0.md` and `FABRIC-1.md` (both design history/archival as of 2026-08-25) 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-0.md`/`FABRIC-1.md`/`FABRIC-2.md`. +> `FABRIC-0.md`, `FABRIC-1.md`, and `FABRIC-2.md` (all design history/archival as of +> 2026-09-04) and `FABRIC-3.md` (current/living, topic: bare metal boot, 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-0.md`/`FABRIC-1.md`/`FABRIC-2.md`/ +> `FABRIC-3.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/FABRIC-2.md b/FABRIC-2.md index 2d938a6..75188df 100644 --- a/FABRIC-2.md +++ b/FABRIC-2.md @@ -1,10 +1,14 @@ # FABRIC-2.md — the Stadium, continued again -**Status:** Living working document, opened 2026-08-25 as the successor to `FABRIC-1.md` -(now closed/archival — see its own header). This document does not repeat `FABRIC-1.md`'s -design argument or history; it restates only outcomes, with pointers back to the section -that derived them. Read `FABRIC-0.md` for the original "why," `FABRIC-1.md` for everything -derived through 2026-08-25, this document for what's left as of that date onward. +**Status: CLOSED/ARCHIVAL as of 2026-09-04.** Was the living working document, opened +2026-08-25 as the successor to `FABRIC-1.md`. Closed after §I (the full consolidated punch +list) was worked through to completion — every item either closed with a dated note or +correctly left open pending a physical machine (§I.6). `FABRIC-3.md` is the new living +document, topic **bare metal boot** — read that one first. This document does not repeat +`FABRIC-1.md`'s design argument or history; it restates only outcomes, with pointers back to +the section that derived them. Read `FABRIC-0.md` for the original "why," `FABRIC-1.md` for +everything derived through 2026-08-25, this document for everything from 2026-08-25 through +2026-09-04. **Provenance.** Everything in Section A below is a full, non-sampled carry-forward of every open (`- [ ]`) item in `FABRIC-1.md` as of 2026-08-25 — 51 items, confirmed by diff --git a/FABRIC-3.md b/FABRIC-3.md new file mode 100644 index 0000000..12da9c1 --- /dev/null +++ b/FABRIC-3.md @@ -0,0 +1,59 @@ +# FABRIC-3.md — bare metal boot + +**Status:** Living working document, opened 2026-09-04 as the successor to `FABRIC-2.md` +(now closed/archival — see its own header). Topic for this document, per direct instruction: +**bare metal boot** — getting LithosAnanke to actually boot on real hardware, not just QEMU. +`FABRIC-2.md` §I.6 (Milestone 8) already named this as the one item that pass couldn't close +from a coding session at all, for exactly this reason — it needs a real machine and a human +physically present. This document is where that work, and everything downstream of it, gets +tracked. + +**How to use this document going forward.** New findings, new punch-list items, and new +decisions for bare-metal-boot work get added here, not to `FABRIC-2.md`. Same discipline every +prior document in this series used: write the decision and its reasoning down before building, +close items with a dated note citing real evidence, never silently drop a stale claim. + +--- + +## I.1 — Task 1: merge `v2.0.1` into `master`, verify build/function equivalence + +**Written up before executing**, per direct instruction and this series' own standing +discipline. + +**Why this is task 1.** `FABRIC-2.md`'s entire 7-step closure pass (§I.1–§I.5, §I.7, plus +today's FABRIC-series rename) happened on the `v2.0.1` branch, not `master`. Before any real +bare-metal-boot work starts, that work needs to land where `.claude/CLAUDE.md` says the +project's sole production line actually lives: `master`. Doing this first, cleanly, before +starting new work avoids ever having two divergent lines to reconcile later. + +**Investigated before writing this up, not assumed:** +- `git merge-base --is-ancestor master v2.0.1` — **true**. `master` (local HEAD `d2a0305`) is + a strict ancestor of `v2.0.1` (HEAD `b031b80`) — `v2.0.1` is exactly `master` plus 47 commits + forward, no divergent history on either side. This means the "merge" is a pure **fast-forward**, + not a real three-way merge — nothing to resolve, no conflict possible. +- `origin/master` carries exactly one commit beyond local `master` (`58c59e8`, "Initial + commit") that local `master` hadn't fetched yet — confirmed already contained in `v2.0.1`'s + own history (`git merge-base --is-ancestor 58c59e8 v2.0.1` — true), so it introduces no + discrepancy either. +- `master`'s own tree still has the *old* `FABRIC.md`/`FABRIC-2.md`/`FABRIC-3.md` naming + (unrenamed) — expected, since today's rename commit (`b031b80`) only exists on `v2.0.1` so + far. The fast-forward brings the rename to `master` along with everything else; nothing + separate needs doing for it. + +**Plan:** +1. Fast-forward `master` to `v2.0.1`'s tip (`git checkout master && git merge --ff-only v2.0.1`) + — refuses loudly instead of silently doing a real merge if the ancestor relationship somehow + isn't what the investigation above found, so this step re-verifies its own precondition. +2. Push `master` to `origin`. +3. **Verify build/function equivalence on a genuinely clean tree**, not by inference: `git clean` + (after confirming nothing untracked-but-wanted is present), then the full acceptance sequence + `.claude/CLAUDE.md` already mandates for any kernel change — `clean qemu` on all three + architectures, in the foreground, one at a time, each reaching `ok>` and shutting down + cleanly. Since the tree is byte-identical to `v2.0.1`'s post-fast-forward, this is expected + to reproduce exactly what `v2.0.1`'s own last acceptance pass already showed — the point of + re-running it here is to confirm that expectation holds on `master` itself, not to assume it + from the fast-forward alone. +4. Return to `v2.0.1` as the working branch afterward (`.claude/CLAUDE.md`'s own rule: always + return to the correct working branch after any out-of-branch work), unless told otherwise. + +**Not yet done — this section will be updated with results once execution completes.** diff --git a/FABRIC-4.md b/FABRIC-4.md index a60f739..0e65eae 100644 --- a/FABRIC-4.md +++ b/FABRIC-4.md @@ -1,13 +1,14 @@ # FABRIC-4.md — forward-looking design notes -**Status:** Not a successor to `FABRIC-2.md` and not a punch-list document. `FABRIC-2.md` is -still the living document — nothing here supersedes it, and this file doesn't follow the -close-and-carry-forward discipline `FABRIC-0.md` → `FABRIC-1.md` → `FABRIC-2.md` used (that -chain triggers on *closing* a document; `FABRIC-2.md` isn't closed). This is a separate, -lower-discipline scratchpad for design ideas caught early — theory-stage, pre-punch-list, -often missing a stated "why" on purpose (captured as raised, not fully justified yet). An idea -graduates out of here into `FABRIC-2.md` §I (or wherever `FABRIC-2.md` is by then) once it has -a real scope, not before. +**Status:** Not a successor to `FABRIC-3.md` and not a punch-list document. `FABRIC-3.md` is +the current living document (bare metal boot, opened 2026-09-04, successor to the now-closed +`FABRIC-2.md`) — nothing here supersedes it, and this file doesn't follow the +close-and-carry-forward discipline `FABRIC-0.md` → `FABRIC-1.md` → `FABRIC-2.md` → `FABRIC-3.md` +used (that chain triggers on *closing* a document; `FABRIC-3.md` isn't closed). This is a +separate, lower-discipline scratchpad for design ideas caught early — theory-stage, +pre-punch-list, often missing a stated "why" on purpose (captured as raised, not fully +justified yet). An idea graduates out of here into `FABRIC-3.md` (or wherever the living +document is by then) once it has a real scope, not before. ---