docs: the 12 duplicates deleted; README rewritten to the system as it is

Captain Bob's rulings, 2026-10-14: "delete" -- the duplicates listed in DELETE-CANDIDATES.md are removed (the list stays as the record; the formal tier's provenance comments repointed at the maintained copies) -- and "rewrite" the README: v2.1.0, the Tripod as Hera/Artemis/Hestia, kernel-Hermes, identities on thumbdrives, the corrected ACL overhead, 1052-test POST and the current parity line, keyboards and storage, board images carrying both systems and how to switch, and docs/README.md as the way in. The book is left as it is, to be reworked later. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 16:45:39 -04:00
parent 776c89457e
commit f8fbc37698
23 changed files with 91 additions and 4932 deletions
@@ -1,6 +1,7 @@
-# LithosAnanke v2.0.1
+# LithosAnanke v2.1.0

-**UEFI-bootable FORTH microkernel.** Boots from firmware, initialises memory and interrupts, then runs the StarForth VM as its sole userspace runtime. No libc. No OS. Just stone and necessity.
+**UEFI-bootable FORTH microkernel.** Boots from firmware, initialises memory and interrupts, then
+runs StarForth as its sole userspace runtime. No libc. No OS. Just stone and necessity.

 *Lithos* (foundation) + *Ananke* (necessity) — the kernel under StarshipOS.

@@ -13,54 +14,52 @@ StarForth v4 moves the engine onto a 32-instruction core derived from Chuck Moor

 | Product | What it is |
 |---|---|
-| **Hosted StarForth F18** | The v4 engine as a native Linux build, for amd64, arm64 and riscv64, on real hardware. |
-| **FPGA StarForth F18** | A 32-bit build of the same engine loaded into the FPGA. It is the gateway to the rest: the foundation everything else is built up from. |
-| **StarshipOS** | The bare-metal product: LithosAnanke running the v4 F18 engine. |
+| **Hosted StarForth F18** | The v4 engine as a native Linux build, for amd64, arm64 and riscv64. |
+| **FPGA StarForth F18** | A 32-bit build of the same engine loaded into the FPGA: the gateway to the rest, the foundation everything else is built up from. |
+| **StarshipOS** | The bare-metal product: LithosAnanke running StarForth. |

 FORTH-79 is recomposed on the F18 engine and stored as a capsule; the StarshipOS-specific
-vocabulary gets the same treatment. The source tree will be reorganised around this split.
-
-v3 remains the reference system until v4 meets its acceptance criteria
-(`docs/v4.0.0/JUSTIFICATION.md` §16). Everything below describes v3 as it stands today.
+vocabulary gets the same treatment. v3 remains the reference system until v4 meets its
+acceptance criteria (`docs/v4.0.0/JUSTIFICATION.md` §16). **Both run on bare metal now:** every
+board image carries v3 and v4, and one word in its boot configuration chooses (see below).

 ---

-## Status — M7.1 (Capsule System · Multi-VM Fleet)
+## Status

 | Milestone | | Status |
 |---|---|---|
-| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console (v1.5.1-FINAL) | ✅ Complete |
+| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console | ✅ Complete |
 | M7 | StarForth VM integration + parity validation | ✅ Complete |
-| **M7.1** | **Capsule birth protocol · Mama FORTH vocabulary · Tripod multi-VM fleet (Hermes/Artemis) · Word-level ACL (Phases 1–7)** | 🔄 **In Progress** |
-| M8 | REPL — keyboard input, interactive Forth | Planned |
-| M9 | Block storage — AHCI driver | Planned |
+| M7.1 | Capsule birth · Mama FORTH vocabulary · the Tripod fleet · kernel-Hermes · word-level ACL | ✅ Live |
+| M8 | Keyboard input to the REPL — PS/2, virtio and **USB** keyboards (a full keyboard: Caps/Num Lock, keypad) | ✅ In QEMU, all three ISAs |
+| M9 | Block storage — Artemis's disk on virtio-blk; identity thumbdrives on USB mass storage | ✅ In QEMU · real disks: no driver yet (`boards/BRINGUP.md` A4) |
+| Bare metal | SER5 (amd64), Raspberry Pi 5 (aarch64), Milk-V Mars (riscv64); Zynq-7020 (ARMv7) not yet ported | Images build; first boots on the bench — `boards/BRINGUP.md` |

-POST at boot: **parity hash verified across amd64/aarch64/riscv64 · Mama capsule dictionary: 453 words**
+POST at boot, on all three ISAs: **1052 tests**, parity hash verified —
+`PARITY:M7.1a word_count=526 hash=0x82f4ae7cb2e2d424`. The v4 system's POST: 538 tests.

-### What's live in M7.1
+### What's live

- **Tripod** — a named multi-VM fleet (Hera the Mama VM, Artemis, two Hermes
-  instances) births, runs, and re-births independently, verified booting
-  live pre-REPL on all three architectures.
- **Hermes** — a 17-block inter-VM messaging/channel layer between fleet
-  members, with async delivery and channel negotiation.
- **Artemis** — a Block Allocation Map (BAM) storage subsystem with Q48.16
-  block-heat tracking and cooldown/reclamation (`ART-COOL`/`ART-REAP`).
- **Word-level ACL** — every dictionary entry carries a TTL/allow/mode/pin
-  access-control record. Strict, TTL, and pinned modes; two console layers
-  (emergency `ok>` and superuser `zuse)ok>`). Phases 1–7 complete (C
-  infrastructure, FORTH policy layer, `zuse` bootstrap superuser, Isabelle
-  proof stubs, kernel parity); Phase 8 (Ed25519 PKI / thumbdrive
-  challenge-response) is the only item remaining. Measured overhead once
-  active on every check: **+0.0054%–+0.0088%**, CV = **0.000%**, across a
-  3×3 Latin-square DoE campaign (architecture × seed × 30 replicates) —
-  three orders of magnitude below the measurement floor.
- **VM Fleet Attractor physics** — the L8 Jacquard mode selector now has a
-  real per-VM heat channel into fleet-wide tuning, replacing hardcoded
-  compudynamics constants with a dynamically-inferred rate.
- **Kconfig build configuration** — every physics/heartbeat/pipelining/
-  kernel-only tuning knob (~40 total) is now a discoverable, optional
-  Kconfig symbol shared with the hosted VM build. See **Quick Start** below.
+- **The Tripod** — a named multi-VM fleet: **Hera** (the Mama VM, the governor), **Artemis**
+  (block storage: a Block Allocation Map with Q48.16 block heat, cooldown and reclamation) and
+  **Hestia**, birthed, run and re-birthed independently on all three architectures.
+- **kernel-Hermes** — messaging moved into the kernel (the Hermes VM is gone,
+  `docs/fabric/FABRIC-3.5.md`): every VM takes its own messages on its own turn, under a
+  cooperative switcher that every VM takes part in.
+- **Identities on thumbdrives** — Zuse, the superuser, and every user is a minted USB
+  thumbdrive (Ed25519, Zuse-signed); plugging one in births that user's VMs, pulling it out
+  ends them. There is only the drive: no password, no PIN.
+- **Word-level ACL** — every dictionary entry carries a TTL/allow/mode/pin access-control
+  record; strict, TTL and pinned modes; two console layers (emergency `ok>` and superuser
+  `zuse)ok>`). Measured overhead of the live ACL-TTL mechanism: **+0.0603%**, CV 0.000%,
+  architecture-independent (`docs/fabric/FABRIC-1.md` §T).
+- **Logs that persist** — every VM's log records go to a ring on Artemis's disk (`LOG-FLUSH`,
+  `LOG-SHOW`).
+- **The physics-driven runtime** — seven feedback loops and the L8 Jacquard mode selector, with
+  a per-VM heat channel into fleet-wide tuning (VM Fleet Attractor).
+- **Kconfig build configuration** — about 40 physics, heartbeat, pipelining and kernel-only
+  knobs, shared with the hosted build.

 ---

@@ -71,45 +70,41 @@ POST at boot: **parity hash verified across amd64/aarch64/riscv64 · Mama capsul
 make boot_image TARGET=SER5       # Beelink SER5   -- GPT/ESP, BOOTX64.EFI
 make boot_image TARGET=RASPI      # Raspberry Pi 5 -- FAT, config.txt + kernel_2712.img + DTB
 make boot_image TARGET=MILKV      # Milk-V Mars    -- GPT/ESP, BOOTRISCV64.EFI (U-Boot bootefi)
-make boot_image TARGET=ZYNQ7020   # Zynq-7020      -- ARMv7 port in progress
-make boards                       # list boards
+make boards                       # list boards (the Zynq-7020 has no ARMv7 port yet)
+
+# Each image carries v3 and v4. As built it boots v3; to boot v4, change the one word
+#   system=v3  ->  system=v4
+# in starforth.cfg on the SER5's stick or the Mars's card, or cmdline.txt on the Pi 5's card.

 # The same TARGET drives all, docs and clean (make help)
 make                              # every board with a kernel port + hosted v3 + the book
-make TARGET=RASPI                 # one board's image + build/docs/LithosAnanke-raspi.pdf
 make docs                         # build/docs/LithosAnanke.pdf (LaTeX master: docs/book/main.tex)
 make clean TARGET=RASPI           # that board's outputs and build/aarch64/kernel
-make clean                        # all of build/ except build/cache/

-# Build kernel (requires cross-compilation toolchain, or native gcc)
-make -f kernel/Makefile ARCH=amd64
+# The kernel in QEMU (OVMF / AAVMF / EDK2), one architecture at a time
+make -f kernel/Makefile ARCH=amd64   clean qemu
+make -f kernel/Makefile ARCH=aarch64 clean qemu
+make -f kernel/Makefile ARCH=riscv64 clean qemu
+make -f kernel/Makefile ARCH=amd64 STARFORTH_V4=1 clean qemu    # the v4 system

-# Run in QEMU with OVMF
-make -f kernel/Makefile qemu
-
-# Other architectures
-make -f kernel/Makefile ARCH=aarch64 qemu
-make -f kernel/Makefile ARCH=riscv64 qemu
+# The Pi 5's native boot path, rehearsed on QEMU's virt machine at EL2
+make -f kernel/Makefile ARCH=aarch64 RPI5_NATIVE_BASE=0x40080000 rpi5-rehearsal
 ```

-Artifacts: `build/amd64/kernel/starkernel_loader.efi` · `build/amd64/kernel/starkernel_kernel.elf`
+Artifacts: `build/<arch>/kernel/starkernel_loader.efi` · `build/<arch>/kernel/starkernel_kernel.elf`

 Tree: `kernel/` (LithosAnanke: `Makefile`, `src/`, `include/starkernel/`, `linker/`),
-`v3/` (StarForth v3 engine and hosted build: `Makefile`, `src/`, `include/`),
-`v4/` (StarForth v4, see `docs/v4.0.0/`), `boards/<board>/` (`board.mk` + boot files).
-Every makefile runs from the repo root; the root `Makefile` forwards any other goal to
-`v3/Makefile` (hosted build).
+`v3/` (StarForth v3 engine and hosted build), `v4/` (StarForth v4, see `docs/v4.0.0/`),
+`boards/<board>/` (`board.mk` + boot files), `capsules/` (the FORTH capsules). Every makefile
+runs from the repo root; the root `Makefile` forwards any other goal to `v3/Makefile`.

-For the hosted VM by itself (Linux, no cross-compiler needed, no bare-metal tooling): see
-the separate **StarForth** repository — LithosAnanke used to be a branch inside that repo,
-now it's its own project with its own `master`.
+For the hosted v3 VM by itself, see the separate **StarForth** repository — LithosAnanke used to
+be a branch inside it, and is now its own project.

 ### Build configuration (optional)

-Every kernel-only knob (`STARFORTH_ENABLE_VM`, `PARITY_MODE`, the shared
-physics/heartbeat family, etc.) is an optional Kconfig symbol — a plain
-`make -f kernel/Makefile` uses the same defaults it always has unless
-you opt in:
+Every kernel-only knob is an optional Kconfig symbol; a plain `make -f kernel/Makefile` uses
+the defaults unless you opt in:

 ```bash
 make -f kernel/Makefile ARCH=amd64 menuconfig
@@ -120,15 +115,21 @@ make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig

 ## Documentation

+**Start at [docs/README.md](docs/README.md)** — the map: where each kind of document lives and
+which to believe. Among them:
+
 | | |
 |---|---|
-| [System Architecture](docs/working/archive/historical/2026-01-27-system-architecture-draft.md) | Full kernel + VM design |
-| [HAL Reference](kernel/src/hal/README.md) | Hardware abstraction layer, as built |
-| [Capsule System — M7.1](docs/reference/M7.1.md) | Capsule birth protocol design |
-| [VM Fleet Attractor design log](docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md) | Tripod/Hermes/Artemis physics + build-system history |
-| [Getting Started / Kconfig reference](docs/working/architecture/getting-started/DEVELOPER.md#build-configuration-kconfig) | Full symbol reference for both build targets |
+| [The FABRIC record](docs/fabric/) | Every design decision and the work as it happened (`FABRIC-3.md` is the living one) |
+| [StarForth v4](docs/v4.0.0/) | The F18-derived engine |
+| [Board bring-up](boards/BRINGUP.md) | Getting onto the SER5, the Pi 5 and the Mars |
+| [Roadmap and versioning](docs/reference/ROADMAP.md) | Milestone plan and release-versioning policy |
+| [Capsule System — M7.1](docs/reference/M7.1.md) | Capsule birth protocol |
+| [Word-level ACL](docs/reference/word-acl/DESIGN.md) | The access-control design |
+| [HAL, as built](kernel/src/hal/README.md) | Hardware abstraction layer |
+| [Developer guide / Kconfig reference](docs/working/architecture/getting-started/DEVELOPER.md#build-configuration-kconfig) | Full symbol reference for both builds |
+| [Dead ideas and revised claims](docs/DEAD-AND-REVISED.md) | What is no longer true, and since when |
 | [Changelog](CHANGELOG.md) | Milestone-level history |
-| [Roadmap](docs/reference/ROADMAP.md) | Milestone plan through self-hosting |

 ---

@@ -43,6 +43,7 @@ document is superseded or a claim corrected.
 | The old elevation path passed a raw cross-VM address | **it copied text** (the narrower real gap was a `"` in a name) | 2026-09-22 | `fabric/FABRIC-3.7.md` (its own correction) |
 | `.claude/ARTEMIS.md`, `HERMES.md`, `TRIPOD.md`, `CONSOLE.md` describe the system | **frozen as record**, superseded by FABRIC-3.5/3.6 | 2026-09-22 | `.claude/CLAUDE.md` (top) |

-**Open discrepancy, not decided here:** the top-level `README.md` is titled "LithosAnanke v2.0.1",
-but the kernel is 2.1.0, and the versioning policy reserves 2.0.1 for the SER5 hardware line
-(`reference/ROADMAP.md`). Captain Bob's call which it should say.
+**Resolved 2026-10-14:** the top-level `README.md` was titled "LithosAnanke v2.0.1" (the SER5
+hardware line's version) while the kernel is 2.1.0; Captain Bob ruled it rewritten -- it now
+describes the system as it is (Tripod Hera/Artemis/Hestia, kernel-Hermes, 1052-test POST, both
+systems on every board image).
@@ -1,7 +1,9 @@
 # docs/DELETE-CANDIDATES.md

-**Listed:** 2026-10-14 (docs triage). **Status:** awaiting Captain Bob's ruling -- nothing here has
-been deleted (docs/CLAUDE.md: never delete without confirmation).
+**Listed:** 2026-10-14 (docs triage). **Status: deleted 2026-10-14 on Captain Bob's ruling
+("delete").** The list is kept as the record of what was removed and why; nothing is awaiting a
+ruling now. The formal tier's `%% SOURCE:` comments that named two of these were repointed at
+the maintained copies.

 Every one is a duplicate: either byte-identical to another file in the same archive, or an older
 copy of a document whose maintained copy is named in the reason. Deleting them loses nothing.
@@ -24,4 +26,3 @@ an AI session note -- are no longer in the tree: they were removed at some point
 | `docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/03_EXPERIMENTAL_DATA/full_90_run_comprehensive/run_logs/test_matrix.txt` | Byte-identical to the same file in ../../../full_90_run_comprehensive/run_logs/. |
 | `docs/working/papers/ONTOLOGY.md` | Older copy (v1.0) of docs/reference/ONTOLOGY.md (v1.1, 2026-08-13). |

-To act: "delete the delete candidates", or name the ones to keep.
@@ -2,8 +2,8 @@

 Generated 2026-10-14 by the docs triage (docs/CLAUDE.md, Phase 1), from the tracked tree
 after the reorganisation. Start at **[README.md](README.md)** for the map; abandoned ideas and
-revised claims are in **[DEAD-AND-REVISED.md](DEAD-AND-REVISED.md)**; files awaiting a delete
-ruling are in **[DELETE-CANDIDATES.md](DELETE-CANDIDATES.md)**. Logs (`logs/`) and DoE run
+revised claims are in **[DEAD-AND-REVISED.md](DEAD-AND-REVISED.md)**; the duplicates deleted
+2026-10-14 are recorded in **[DELETE-CANDIDATES.md](DELETE-CANDIDATES.md)**. Logs (`logs/`) and DoE run
 CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
 `docs/formal/CLAUDE.md`), are listed one row per folder.

@@ -14,7 +14,7 @@ CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
 | HISTORICAL | Accurate for its time; kept as record | 90 |
 | SUPERSEDED | Replaced -- its header says by what | 26 |
 | DEAD | An idea or design that was abandoned or never adopted | 12 |
-| DELETE | Proposed for deletion, awaiting a ruling | 12 |
+| DELETE | Proposed for deletion, awaiting a ruling | 0 |
 | RECORD | Experiment data and results | 50 |
 | FORMAL | The press-ready LaTeX tier | 19 |
 | LEGAL HOLD | Patent-adjacent; not touched without Captain Bob | 57 |
@@ -81,7 +81,7 @@ CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
 |---|---|---|---|
 | docs/CLAUDE.md | CLAUDE.md — StarshipOS Documentation Root | CURRENT | Rules for documentation work. |
 | docs/DEAD-AND-REVISED.md | Dead ideas and revised claims | CURRENT | Register of abandoned ideas and revised claims. |
-| docs/DELETE-CANDIDATES.md | docs/DELETE-CANDIDATES.md | CURRENT | Awaiting Captain Bob's ruling. |
+| docs/DELETE-CANDIDATES.md | docs/DELETE-CANDIDATES.md | CURRENT | Record of the duplicates deleted 2026-10-14. |
 | docs/INDEX.md | docs/INDEX.md — every document, and its status | CURRENT | This index. |
 | docs/README.md | StarForth / LithosAnanke documentation — the map | CURRENT | The map: start here. |
 | docs/SSM_DARPA_Summary_Slide.pptx | SSM_DARPA_Summary_Slide.pptx | CURRENT |  |
@@ -133,17 +133,6 @@ CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
 | docs/formal/vol2-kernel/ | 8 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
 | docs/formal/vol3-research/ | 11 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |

-## docs/lithosananke
-
-| Path | Title | Status | Notes |
-|---|---|---|---|
-| docs/lithosananke/hal/README.md | LithosAnanke Hardware Abstraction Layer (HAL) | DELETE | Duplicate of docs/working/archive/dead/hal-target-contract/README.md, without that copy's 2026-10-09 "never adopted" flags. |
-| docs/lithosananke/hal/interfaces.md | HAL Interface Specifications | DELETE | Duplicate (older, unflagged) of docs/working/archive/dead/hal-target-contract/interfaces.md. |
-| docs/lithosananke/hal/lithosananke-integration.md | LithosAnanke HAL Integration Guide | DELETE | The same document as docs/working/archive/dead/hal-target-contract/starkernel-integration.md under the kernel's newer name, without its "obsolete" flag. |
-| docs/lithosananke/hal/migration-plan.md | HAL Migration Plan | DELETE | Duplicate (older, unflagged) of docs/working/archive/dead/hal-target-contract/migration-plan.md. |
-| docs/lithosananke/hal/overview.md | Hardware Abstraction Layer (HAL) Architecture | DELETE | Duplicate (older) of docs/working/archive/dead/hal-target-contract/overview.md. |
-| docs/lithosananke/hal/platform-implementations.md | HAL Platform Implementation Guide | DELETE | Duplicate (older, unflagged) of docs/working/archive/dead/hal-target-contract/platform-implementations.md. |
-
 ## docs/patent

 | Path | Title | Status | Notes |
@@ -270,7 +259,6 @@ CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
 | docs/working/architecture/03-architecture/pipelining/design.md | FORTH VM Pipelining & Speculative Execution Design | WORKING |  |
 | docs/working/architecture/03-architecture/pipelining/phase-1-instrumentation.md | Phase 1: Pipelining Instrumentation | WORKING |  |
 | docs/working/architecture/03-architecture/pipelining/wired-not-utilized.md | Pipelining Feedback Loop: WIRED BUT NOT UTILIZED (Critical Issue) | WORKING |  |
-| docs/working/architecture/03-architecture/word-acl/DESIGN.md | Word-Level ACL System | DELETE | Older copy (2026-06) of docs/reference/word-acl/DESIGN.md, which is the maintained one (status through Phase 7). |
 | docs/working/architecture/ARTEMIS-BAM-ACCEPTANCE-20260703.md | Artemis BAM — Phase 1 Acceptance Report | WORKING |  |
 | docs/working/architecture/ARTEMIS-BLOCK-PHYSICS-DESIGN-20260708.md | Artemis Block Heat Physics — Design Doc | WORKING |  |
 | docs/working/architecture/ARTEMIS-FREEMAP-CAPSULE-RESERVATION-GAP-20260710.md | Artemis Free-Map Doesn't Reserve Capsule-Claimed Blocks | WORKING |  |
@@ -352,10 +340,6 @@ CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
 | docs/working/archive/legacy/phase-1/Reference/codex_capa_list.md | StarForth Governance – CAPA Register (Fresh Audit) | HISTORICAL |  |
 | docs/working/archive/legacy/phase-1/Reference/github_backlog_items.md | GitHub Project Backlog Prep | HISTORICAL |  |
 | docs/working/archive/legacy/phase-1/Reference/physics_experiment/ | 35 files | HISTORICAL | Grouped: bulk data or a self-governed tree. |
-| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/FORMAL_CLAIMS_FOR_REVIEWERS.txt | 0% / 70% | DELETE | Byte-identical to ../../FORMAL_CLAIMS_FOR_REVIEWERS.txt in the same archive. |
-| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/QUICK_REFERENCE.txt | Before mitigations (baseline) | DELETE | Byte-identical to ../../QUICK_REFERENCE.txt in the same archive. |
-| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/03_EXPERIMENTAL_DATA/full_90_run_comprehensive/experiment_summary.txt | experiment_summary.txt | DELETE | Byte-identical to ../../../full_90_run_comprehensive/experiment_summary.txt in the same archive. |
-| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/03_EXPERIMENTAL_DATA/full_90_run_comprehensive/run_logs/test_matrix.txt | test_matrix.txt | DELETE | Byte-identical to the same file in ../../../full_90_run_comprehensive/run_logs/. |
 | docs/working/archive/legacy/phase-1/Reference/toolchain/ | 2 files | HISTORICAL | Grouped: bulk data or a self-governed tree. |
 | docs/working/archive/operations/README.md | Operations | HISTORICAL |  |
 | docs/working/archive/operations/backlog-gatekeeper.md | Backlog Gatekeeper Procedures | HISTORICAL |  |
@@ -456,7 +440,6 @@ CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
 | docs/working/papers/FORMAL_CLAIM_TABLE.md | Formal Claim Table: StarForth Adaptive Runtime | WORKING |  |
 | docs/working/papers/NEGATIVE_RESULTS.md | Negative Results: Where StarForth Fails | WORKING |  |
 | docs/working/papers/NULL_HYPOTHESIS.md | Null Hypothesis and Falsification Criteria | WORKING |  |
-| docs/working/papers/ONTOLOGY.md | StarForth Ontology, Taxonomy, and Lexicon | DELETE | Older copy (v1.0) of docs/reference/ONTOLOGY.md (v1.1, 2026-08-13). |
 | docs/working/papers/ONTOLOGY_README.md | StarForth Ontology Documentation | WORKING |  |
 | docs/working/papers/README.md | docs/working/papers/ | WORKING |  |
 | docs/working/papers/REPLICATION_INVITE.md | Invitation to Independent Replication | WORKING |  |
@@ -8,8 +8,8 @@ its own header.
 - **[INDEX.md](INDEX.md)** — every document in the repository, with its status.
 - **[DEAD-AND-REVISED.md](DEAD-AND-REVISED.md)** — the ideas that were abandoned, and the claims
  that were revised, each with the date and where the decision is recorded.
- **[DELETE-CANDIDATES.md](DELETE-CANDIDATES.md)** — duplicates proposed for deletion, awaiting a
-  ruling.
+- **[DELETE-CANDIDATES.md](DELETE-CANDIDATES.md)** — what was deleted as duplicate, and why
+  (2026-10-14).

 ## What to believe

@@ -60,8 +60,6 @@ Where two documents disagree, the one higher in this table wins, and code wins o
 - **[pptx/](pptx/)** — slide decks for different audiences.
 - **[patent/](patent/)** — provisional patent material. **Legal hold: ask Captain Bob before
  touching anything here** (also `formal/patent/`, `formal/scraps/legal/`, `working/legal/`).
- `lithosananke/hal/` — the last of the old `lithosananke/` folder: duplicates of the dead HAL
-  contract, listed in DELETE-CANDIDATES.md.

 ## Adding a document

@@ -100,7 +100,7 @@
 \part{Security and ACL Recipes}

 \chapter{Word-Level ACL Basics}
-%% SOURCE: docs/working/architecture/03-architecture/word-acl/DESIGN.md
+%% SOURCE: docs/reference/word-acl/DESIGN.md
 %% TODO(bob): promote ACL recipe: loading ACL.4th, granting/revoking modes,
 %% TTL-based expiry. Do NOT draft independent claim language.
 \input{../scraps/architecture/03-architecture/word-acl/DESIGN}
@@ -1,5 +1,5 @@
 %% SCRAP: architecture/03-architecture/word-acl/DESIGN
-%% SOURCE: docs/working/architecture/03-architecture/word-acl/DESIGN.md
+%% SOURCE: docs/reference/word-acl/DESIGN.md
 %% STATUS: CURRENT
 %% FITS: dev-guide/ch-acl, cookbook/ch-acl
 %% EDITORIAL: lifted — prose rewritten to press voice
@@ -1,5 +1,5 @@
 %% SCRAP: papers/ONTOLOGY
-%% SOURCE: docs/working/papers/ONTOLOGY.md
+%% SOURCE: docs/reference/ONTOLOGY.md
 %% STATUS: CURRENT
 %% FITS: ssrn/ch-ontology, vol3-research/ch-ontology
 %% EDITORIAL: lifted — prose rewritten to press voice; thermodynamic-as-metaphor framing preserved throughout
@@ -2,7 +2,7 @@
 %% SOURCE: docs/working/papers/published/James_Steady-State_Convergence_Adaptive_Runtime.pdf
 %%         docs/working/papers/SSRN_companion/Math_Companion_SSRN.tex
 %%         docs/working/papers/FORMAL_CLAIM_TABLE.md
-%%         docs/working/papers/ONTOLOGY.md
+%%         docs/reference/ONTOLOGY.md
 %% NOTE: The SSRN paper itself is a published PDF — it is NOT re-typeset here.
 %%       This volume collects the companion material: Math Companion (full LaTeX),
 %%       formal claim tables, ontology, and academic wording guidelines.
@@ -84,7 +84,7 @@ The canonical paper PDF is at:
 \part{Ontology of Terms}

 \chapter{Thermodynamic Metaphor Ontology}
-%% SOURCE: docs/working/papers/ONTOLOGY.md
+%% SOURCE: docs/reference/ONTOLOGY.md
 %% NOTE: Thermodynamic terms are modeling tools, not physics claims.
 %% Always introduce with domain qualifier: "using X as a proxy for Y, …"
 \input{../scraps/papers/ONTOLOGY}
@@ -1,5 +1,5 @@
 %% Vol II, Chapter 3 — ACL and Security Model
-%% SOURCE: docs/working/architecture/03-architecture/word-acl/DESIGN.md
+%% SOURCE: docs/reference/word-acl/DESIGN.md
 %%         .claude/CLAUDE.md (Word-Level ACL System section)
 %%         capsules/ACL.4th, capsules/zuse.4th

@@ -19,7 +19,7 @@
 \section{Two-Console Model}
 \label{vol2:sec:acl:consoles}

-%% SOURCE: docs/working/architecture/03-architecture/word-acl/DESIGN.md
+%% SOURCE: docs/reference/word-acl/DESIGN.md
 %% TODO(bob): describe the two permanent console layers:
 %%   - emergency console (ok>) — fault handler active
 %%   - zuse console (zuse)ok>) — superuser authenticated
@@ -1,5 +1,5 @@
 %% Vol III, Chapter 6 — Ontology of Thermodynamic Terms
-%% SOURCE: docs/working/papers/ONTOLOGY.md
+%% SOURCE: docs/reference/ONTOLOGY.md
 %%         docs/working/papers/ONTOLOGY_README.md

 \chapter{Ontology of Thermodynamic Terms}
@@ -1,84 +0,0 @@
-# LithosAnanke Hardware Abstraction Layer (HAL)
-
-This directory contains HAL documentation for the LithosAnanke kernel branch.
-
-> **HISTORICAL — L4Re/Fiasco.OC**: L4Re references throughout this directory's docs describe a target that was a supported platform through mid-2026. L4Re support has since been removed as an active target — `src/platform/l4re/time.c` and related `#ifdef __l4__` code are retained for reference but no longer wired into any build.
-
---
-
-## Document Overview
-
-| Document | Purpose |
-|----------|---------|
-| [overview.md](overview.md) | HAL architecture and design principles |
-| [interfaces.md](interfaces.md) | HAL function specifications and contracts |
-| [lithosananke-integration.md](lithosananke-integration.md) | Kernel-specific HAL implementation |
-| [platform-implementations.md](platform-implementations.md) | How to implement HAL for a platform |
-| [migration-plan.md](migration-plan.md) | Migration from hosted to kernel |
-
---
-
-## Reading Order
-
-1. **overview.md** — Understand why HAL exists
-2. **interfaces.md** — Learn the contracts
-3. **lithosananke-integration.md** — See kernel implementation
-4. **platform-implementations.md** — Reference implementations
-
---
-
-## HAL Subsystems
-
-```
-hal_time.h       — Monotonic time, timers
-hal_interrupt.h  — IRQ management, ISR registration
-hal_memory.h     — Allocation, page mapping
-hal_console.h    — Character I/O (UART, framebuffer)
-hal_cpu.h        — CPU ID, relax/halt, SMP
-hal_panic.h      — Fatal error handling
-```
-
---
-
-## Current State (lithosananke branch)
-
-The HAL is **partially implemented** in LithosAnanke:
-
-| Subsystem | Status | Location |
-|-----------|--------|----------|
-| Time | Implemented | `src/starkernel/arch/amd64/timer.c` |
-| Interrupts | Implemented | `src/starkernel/arch/amd64/interrupts.c` |
-| Memory | Implemented | `src/starkernel/memory/` |
-| Console | Implemented | `src/starkernel/hal/console.c` |
-| CPU | Partial | `src/starkernel/arch/amd64/apic.c` |
-| Panic | Implemented | `src/starkernel/hal/hal.c` |
-
---
-
-## Relationship to Hosted StarForth
-
-The HAL enables the same VM code to run on:
-
- **Linux** (hosted, POSIX)
- **LithosAnanke** (freestanding, bare metal)
- **L4Re** (microkernel, optional)
-
-```
-┌─────────────────────────────────────┐
-│  StarForth VM + Physics Subsystems  │
-│         (platform-agnostic)         │
-├─────────────────────────────────────┤
-│              HAL Layer              │
-├──────────┬──────────┬───────────────┤
-│  Linux   │  L4Re    │  LithosAnanke │
-│ (POSIX)  │ (micro)  │   (kernel)    │
-└──────────┴──────────┴───────────────┘
-```
-
---
-
-## See Also
-
- [../README.md](../README.md) — LithosAnanke overview
- [../ROADMAP.md](../ROADMAP.md) — Milestone roadmap
- [../M7.1.md](../M7.1.md) — Init Capsule Architecture
@@ -1,179 +0,0 @@
-================================================================================
-PHYSICS ENGINE VALIDATION - QUICK REFERENCE GUIDE
-================================================================================
-
-EXPERIMENTS COMPLETED:
-✓ 90-run comprehensive validation (3 configs × 30 runs each)
-✓ CPU thermal monitoring (captured temperature & frequency)
-✓ Data integrity validation (all 90 rows clean)
-✓ Thermal hypothesis testing (REFUTED - no thermal noise)
-✓ Variance source analysis (identified OS scheduling + memory latency)
-
-CURRENT STATE:
-Location: /home/rajames/CLionProjects/StarForth/physics_experiment/full_90_run_comprehensive/
-Results: experiment_results.csv (90 runs, all data validated)
-Analysis Files:
-  - analyze_thermal_hypothesis.py (thermal analysis)
-  - analyze_variance_sources.py (variance decomposition)
-  - VARIANCE_ANALYSIS_SUMMARY.md (comprehensive findings)
-
-================================================================================
-KEY FINDINGS AT A GLANCE
-================================================================================
-
-THERMAL HYPOTHESIS: ✗ REFUTED
-  - CPU remained at exactly 27°C throughout all 90 runs
-  - No thermal drift, no frequency throttling
-  - Conclusion: Thermal noise is NOT a factor in your measurements
-
-VARIANCE SOURCE RANKING (Coefficient of Variation):
-
-1. OS SCHEDULING NOISE (PRIMARY) - 60-70% CV ⚠️
-   A_BASELINE: 69.58% (range: 3.34-17.67ms, 305% span!)
-   C_FULL:     60.23% (range: 6.56-33.15ms, 299% span!)
-   B_CACHE:    32.35% (range: 6.27-19.26ms, 167% span)
-
-   → This is the DOMINANT source of variance
-   → Simple configs are WORSE (more sensitive to preemption)
-   → Caused by: context switching, interrupts, page faults
-
-2. MEMORY LATENCY VARIABILITY (SECONDARY) - 54-103% CV ⚠️
-   B_CACHE cache hit latency: 40.1 ns ± 41.4 ns (103.3% CV)
-   C_FULL cache hit latency:  37.9 ns ± 20.5 ns (54.0% CV)
-
-   → Extreme variability in L1/L2 hit times
-   → Indicates cache coherency misses, NUMA effects
-   → 80ns swings in what should be 40ns hits
-
-3. CACHE HIT RATE (EXCELLENT) - 0% CV ✓
-   B_CACHE: 17.39% ± 0.00%
-   C_FULL:  17.39% ± 0.00%
-
-   → Perfect consistency! Cache behavior is deterministic
-   → Variance NOT from unpredictable cache misses
-   → Working set is stable across all runs
-
-4. WARMUP EFFECTS (INTERESTING) - -25% to +6%
-   A_BASELINE: +6.4% slower (degradation over time)
-   B_CACHE:    +0.5% stable (excellent warmup)
-   C_FULL:     -25.4% FASTER (improves significantly!)
-
-   → C_FULL benefits from warming caches
-   → A_BASELINE shows slight system degradation
-
-================================================================================
-QUICK FIXES (DO THIS NOW)
-================================================================================
-
-STEP 1: CPU PINNING (Expected improvement: -30-40% variance)
-  Run your benchmark pinned to a single CPU core:
-  $ taskset -c 0 ./build/starforth ...
-
-  Or for the experiment:
-  $ taskset -c 0 scripts/run_comprehensive_physics_experiment.sh ...
-
-STEP 2: SET PERFORMANCE MODE (Expected improvement: -10-15% variance)
-  Disable frequency scaling:
-  $ echo performance | sudo tee /sys/devices/system/cpu/*/cpufreq/scaling_governor
-
-  Verify:
-  $ cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
-
-STEP 3: USE ROBUST STATISTICS (Immediate improvement)
-  Don't use mean ± stdev when you have 69% CV!
-
-  Instead, use trimmed mean:
-    - Sort runtimes
-    - Remove top/bottom 10%
-    - Average the middle 80%
-
-  Or use median + IQR (interquartile range)
-
-  Python example:
-    runtimes = [4.5, 4.7, 5.2, 17.6]  # 17.6 is outlier
-    sorted_rt = sorted(runtimes)
-    trimmed = sorted_rt[1:-1]  # Remove min and max
-    mean = sum(trimmed) / len(trimmed)
-
-COMBINED EXPECTED IMPROVEMENT:
-  Current:  A_BASELINE ~70% CV
-  After Step 1+2: ~30-40% CV
-  After Step 3: Statistics properly account for outliers
-
-  Result: Much clearer performance comparisons!
-
-================================================================================
-DETAILED MITIGATION PRIORITY
-================================================================================
-
-IMMEDIATE (This week):
-  [1] CPU pinning with taskset
-  [2] Performance governor setting
-  [3] Rerun experiment with CPU pinning
-  [4] Switch to trimmed mean analysis
-
-SHORT TERM (Next 1-2 weeks):
-  [1] Disable SMT (hyper-threading)
-  [2] Increase warmup phase (5 runs instead of current)
-  [3] Use perf to measure cache misses
-      $ perf stat -e cache-references,cache-misses \
-          taskset -c 0 ./build/starforth ...
-
-MEDIUM TERM (If variance still >30%):
-  [1] Try SCHED_FIFO real-time scheduling (requires root)
-  [2] NUMA binding with numactl
-  [3] Isolate CPU cores (kernel parameter isolcpus)
-  [4] Profile with perf-record to find hotspots
-
-LONG TERM (For production benchmarks):
-  [1] Use real-time kernel (RT_PREEMPT)
-  [2] Dedicated measurement system
-  [3] Disable all background services
-
-================================================================================
-FILES TO READ
-================================================================================
-
-DETAILED ANALYSIS:
-  → /home/rajames/CLionProjects/StarForth/physics_experiment/VARIANCE_ANALYSIS_SUMMARY.md
-    (Full findings, root cause analysis, mitigation strategies)
-
-DATA FILES:
-  → /home/rajames/CLionProjects/StarForth/physics_experiment/full_90_run_comprehensive/
-    experiment_results.csv (90 rows of clean data, all metrics)
-
-ANALYSIS SCRIPTS:
-  → analyze_thermal_hypothesis.py (thermal analysis)
-  → analyze_variance_sources.py (variance decomposition - rerun anytime)
-
-================================================================================
-QUICK TEST: VALIDATE IMPROVEMENTS
-================================================================================
-
-After applying mitigations, rerun and compare:
-
-# Before mitigations (baseline)
-$ ./scripts/run_comprehensive_physics_experiment.sh before_fix
-$ python3 analyze_variance_sources.py \
-    before_fix/experiment_results.csv
-
-# After mitigations
-$ taskset -c 0 ./scripts/run_comprehensive_physics_experiment.sh after_fix
-$ python3 analyze_variance_sources.py \
-    after_fix/experiment_results.csv
-
-Expected: Coefficient of Variation drops from 60-70% to <40%
-
-================================================================================
-BOTTOM LINE
-================================================================================
-
-Your data collection script: ✓ PERFECT (no issues found)
-Your thermal hypothesis:    ✗ NOT CONFIRMED (system is cool)
-Your actual problem:        → OS scheduling noise (expected, solvable)
-
-Next action: Pin to CPU + set performance mode, then rerun.
-Expected result: Variance cut by 40% or more.
-
-For questions, see VARIANCE_ANALYSIS_SUMMARY.md for full technical details.
-================================================================================
@@ -1,16 +0,0 @@
-
-Experiment Start: 2025-11-07T06:40:43
-Output Directory: physics_experiment/full_90_run_comprehensive
-Runs per Configuration: 30
-Total Runs: 90
-Benchmark Iterations: 100000
-Build Profile: fastest
-Execution: Randomized order (eliminates temporal bias)
-
-
-Experiment End: 2025-11-07T06:49:08
-Total Runtime: 8 minutes (505 seconds)
-Results CSV: physics_experiment/full_90_run_comprehensive/experiment_results.csv
-Run Logs: physics_experiment/full_90_run_comprehensive/run_logs/
-Test Matrix: physics_experiment/full_90_run_comprehensive/run_logs/test_matrix.txt
-
@@ -1,90 +0,0 @@
-A_BASELINE,0,0,8
-B_CACHE,1,0,21
-A_BASELINE,0,0,17
-B_CACHE,1,0,25
-C_FULL,1,1,23
-B_CACHE,1,0,7
-B_CACHE,1,0,16
-B_CACHE,1,0,13
-B_CACHE,1,0,30
-C_FULL,1,1,26
-A_BASELINE,0,0,28
-C_FULL,1,1,16
-B_CACHE,1,0,22
-A_BASELINE,0,0,24
-A_BASELINE,0,0,18
-B_CACHE,1,0,8
-C_FULL,1,1,12
-A_BASELINE,0,0,19
-C_FULL,1,1,4
-A_BASELINE,0,0,3
-C_FULL,1,1,14
-B_CACHE,1,0,9
-A_BASELINE,0,0,11
-A_BASELINE,0,0,10
-C_FULL,1,1,22
-B_CACHE,1,0,1
-B_CACHE,1,0,28
-C_FULL,1,1,15
-C_FULL,1,1,1
-C_FULL,1,1,30
-A_BASELINE,0,0,13
-C_FULL,1,1,29
-B_CACHE,1,0,11
-B_CACHE,1,0,3
-A_BASELINE,0,0,29
-C_FULL,1,1,6
-A_BASELINE,0,0,20
-A_BASELINE,0,0,15
-B_CACHE,1,0,14
-B_CACHE,1,0,5
-C_FULL,1,1,20
-A_BASELINE,0,0,16
-C_FULL,1,1,3
-A_BASELINE,0,0,23
-B_CACHE,1,0,6
-A_BASELINE,0,0,30
-A_BASELINE,0,0,7
-C_FULL,1,1,19
-C_FULL,1,1,5
-B_CACHE,1,0,15
-B_CACHE,1,0,29
-C_FULL,1,1,13
-C_FULL,1,1,9
-C_FULL,1,1,25
-A_BASELINE,0,0,4
-B_CACHE,1,0,17
-C_FULL,1,1,21
-C_FULL,1,1,17
-B_CACHE,1,0,20
-B_CACHE,1,0,26
-C_FULL,1,1,11
-A_BASELINE,0,0,27
-B_CACHE,1,0,18
-B_CACHE,1,0,12
-C_FULL,1,1,2
-A_BASELINE,0,0,25
-A_BASELINE,0,0,14
-C_FULL,1,1,24
-C_FULL,1,1,8
-B_CACHE,1,0,27
-B_CACHE,1,0,4
-C_FULL,1,1,7
-A_BASELINE,0,0,9
-A_BASELINE,0,0,2
-C_FULL,1,1,18
-B_CACHE,1,0,19
-A_BASELINE,0,0,21
-A_BASELINE,0,0,22
-C_FULL,1,1,28
-A_BASELINE,0,0,12
-A_BASELINE,0,0,26
-B_CACHE,1,0,24
-B_CACHE,1,0,10
-B_CACHE,1,0,2
-B_CACHE,1,0,23
-A_BASELINE,0,0,6
-A_BASELINE,0,0,5
-C_FULL,1,1,10
-C_FULL,1,1,27
-A_BASELINE,0,0,1