docs: the map, a fresh index, and a register of dead ideas and revised claims

docs/CLAUDE.md Phase 1 output, after the reorganisation.

- docs/README.md: rewritten as the map -- where each kind of document
  lives, which one to believe (CLAUDE.md, FABRIC, v4.0.0, reference/,
  BRINGUP, code), how to retire a document.
- docs/INDEX.md: regenerated from the tracked tree, 489 rows, every
  document with a status (the 2026-06-16 snapshot was stale).
- docs/DEAD-AND-REVISED.md (new): what was abandoned (L4Re, the hal_*
  contract, ACL RWT, the Hermes VM, elevation, the knowledge factor, ...)
  and what was corrected (ACL overhead, versions, block rules, parity
  baseline, ...), each with its date and record.
- docs/DELETE-CANDIDATES.md: 12 duplicates, awaiting a ruling; nothing
  deleted.
- CLAUDE.md: versions corrected (3.2.0 / 2.1.0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-14 16:06:59 -04:00
co-authored by Claude Opus 5.5
parent 7aed588f78
commit 776c89457e
9 changed files with 812 additions and 407 deletions
+6 -5
View File
@@ -247,12 +247,13 @@ make -f kernel/Makefile clean
Output: `build/<arch>/kernel/starkernel_loader.efi` + `build/<arch>/kernel/starkernel_kernel.elf`.
Two independently tracked version strings flow into the generated `include/version.h`:
`VERSION` (`kernel/Makefile` — the embedded StarForth engine version, currently `3.1.0`;
`VERSION` (`kernel/Makefile` — the embedded StarForth engine version, currently `3.2.0`;
note this does **not** auto-sync with the standalone StarForth repo's own version) and
`LITHOS_VERSION` (`kernel/Makefile` — the kernel version, currently **`2.0.0`**;
corrected 2026-09-19 — this file said `2.0.1`, but `FABRIC-3.md` §I.2 rolled it back to
`2.0.0` on 2026-09-04 because `2.0.1` names the SER5 hardware-track line and claims hardware
progress not yet verified. The versioning policy is **semantic, not sequential** — see the
`LITHOS_VERSION` (`kernel/Makefile` — the kernel version, currently **`2.1.0`**, bumped at
the `v2.1.0` tag that closed FABRIC-3.6; corrected 2026-10-14 -- this file said `3.1.0` /
`2.0.0`. History: it said `2.0.1` until 2026-09-19, but `FABRIC-3.md` §I.2 had rolled that
back to `2.0.0` on 2026-09-04 because `2.0.1` names the SER5 hardware-track line and claims
hardware progress not yet verified. The versioning policy is **semantic, not sequential** — see the
roadmap table in `kernel/Makefile` before choosing any version).
### Build configuration (Kconfig — real, wired, not vestigial)
+1 -1
View File
@@ -104,7 +104,7 @@ on both branches, plus the now-orphaned `scripts/pgo-workload.sh`. Verified
Also proved out and documented, for the first time, that the hosted VM
starts cleanly not just on amd64 but on aarch64 and riscv64 too (cross-built,
run under `qemu-{aarch64,riscv64}-static` user-mode emulation) —
`docs/lithosananke/hosted-acceptance-test/README.md`. This is what surfaced
`docs/reference/hosted-acceptance-test/README.md`. This is what surfaced
the `blk_ram` sizing bug above.
## 2026-07-07 – 2026-07-08 — Kconfig build-configuration system (both, committed on `lithosananke`)
+1 -1
View File
@@ -34,6 +34,6 @@ Each block is limited to 1024 bytes. Verify with `wc -c` before committing.
## See also
- [`experiments/bare_metal/README.md`](../experiments/bare_metal/README.md) — DoE protocols and block namespace rules
- [`docs/03-architecture/word-acl/DESIGN.md`](../docs/03-architecture/word-acl/DESIGN.md) — ACL system design
- [`docs/reference/word-acl/DESIGN.md`](../docs/reference/word-acl/DESIGN.md) — ACL system design
- [`tools/mkcapsule.c`](../tools/mkcapsule.c) — assembles capsules into `capsule_generated.c`
- [Project root](../README.md)
+48
View File
@@ -0,0 +1,48 @@
# Dead ideas and revised claims
A register, started 2026-10-14 by the docs triage. An idea that was abandoned, or a claim that
turned out wrong, keeps its documents (archived, with a header) — this page says, in one place,
what is no longer true, since when, and where the decision is recorded. Add to it whenever a
document is superseded or a claim corrected.
## Dead — abandoned, removed, or never adopted
| Idea | Since | What happened | Recorded in |
|---|---|---|---|
| L4Re / Fiasco.OC as a platform target | mid-2026 | Removed as an active target; LithosAnanke is its own kernel. | `.claude/CLAUDE.md` (Project Overview); docs archived in `working/archive/dead/l4re/` |
| The `hal_*` interface contract and its migration plan | flagged 2026-10-09 | Never adopted; the kernel grew its own HAL. | `working/archive/dead/hal-target-contract/`; the HAL as built: `kernel/src/hal/README.md` |
| ACL "Rolling Window of Truth" (`ACL-RECHECK-RW`) | removed 2026-07-08 | Dead code from the start: `acl_recheck()` only ever looked up `ACL-RECHECK`. | `fabric/FABRIC-1.md` §M–T |
| The Hermes VM and FORTH messaging (`messaging.4th`, `MSG-TICK`) | 2026-09-22 | Messaging moved into the kernel as kernel-Hermes; the Tripod is Hera / Artemis / Hestia. | `fabric/FABRIC-3.5.md`, `FABRIC-3.6.md`; old docs in `working/archive/superseded/2026-08-tripod/` and `.claude/HERMES.md` (frozen) |
| Running a VM's messages from Hera's idle loop (a second delivery path) | 2026-10-14 | One path: a VM takes its own messages on its own turn. | `fabric/FABRIC-3.md` §XXXVI |
| Word-ACL elevation on request (`ELEVATE-GRANT`, `KH-ELEVATE-SEND`) and Zuse's eligibility list | 2026-10-14 | Ruled not needed: privilege comes from the drive. Removed, with the hole it carried; the list's disk area is reserved, unused. | `fabric/FABRIC-3.md` §XXXVII; `fabric/FABRIC-3.7.md` (closed) |
| A knowledge factor for identity (PIN, passphrase) | 2026-09-23 | Built, tested, reverted: "there's only the drive." | `fabric/FABRIC-3.7.md` §4 |
| Defending against a byte-for-byte cloned identity drive | 2026-09-23 | Accepted by design, not a gap. (Copying from *within* StarshipOS is blocked.) | `fabric/FABRIC-3.7.md` §4 |
| The StarForth-era roadmap (VM -> kernel -> OS -> FPGA, 2025-12) | flagged 2026-08-26 | Overtaken; the architecture and terms it uses no longer exist. | `working/archive/superseded/2025-12-14-starforth-roadmap.md`; now `reference/ROADMAP.md` |
| The complete 2^6 factorial DoE | flagged 2026-10-09 | Obsolete. | `working/archive/superseded/factorial-doe/` |
| "Everything is a VM" system architecture, draft 0.1 | 2026-01-27 | A vision draft; what was built is in the FABRIC record. | `working/archive/historical/2026-01-27-system-architecture-draft.md` |
**Deferred, not dead:**
- **The multiuser/multitasking DoE campaign** (`fabric/FABRIC-3.md` §XXXIII–XXXV). Deferred past
bare metal, 2026-10-14. Its original 30-reps-per-cell design (about 10.3 days) had already been
replaced, in §XXXIV.4, by a segmented per-ISA design.
- **Keyboard VMs.** A concept only (2026-10-14), not designed.
## Revised — claims that were corrected
| Was | Is | Since | Recorded in |
|---|---|---|---|
| ACL overhead "+0.0054%–+0.0088%" (the "ACL-RWT" campaign) | **+0.0603%**, the live ACL-TTL mechanism, CV 0.000% | 2026-08-21 | `fabric/FABRIC-1.md` §T |
| Kernel version 2.0.1 | rolled back to 2.0.0 on 2026-09-04 (2.0.1 names the SER5 hardware line), now **2.1.0** (tag `v2.1.0`) | 2026-09-22 | `fabric/FABRIC-3.md` §I.2; `kernel/Makefile` |
| Capsule blocks must be in `[2048, 5120)` | **2048 or more**, no upper bound | 2026-10-05 | `v4.0.0/NUCLEUS.md` §5.2 |
| A capsule block is a 1024-byte budget | **64 characters x 16 lines** (`mkcapsule --lint`) | 2026-09-19 | `.claude/CLAUDE.md` (block format) |
| Parity baseline: 530 words, hash `0x08873e0f44b7cb2a` | **526 words, `0x82f4ae7cb2e2d424`** (elevation words out, `LOG-FLUSH`/`LOG-SHOW` in) | 2026-10-14 | `fabric/FABRIC-3.md` §XXXVII, §XXXVIII |
| Identity drives attached together are dropped (§XIV) | **no longer reproduces**, all three ISAs | 2026-10-14 | `fabric/FABRIC-3.md` §XIV |
| `THRU`/`LOAD` lose the rest of their line | **fixed** | 2026-10-14 | `fabric/FABRIC-3.md` §XXXIV.1 |
| The log ring's growth is "safe regardless of wrap state" | **it was not**; fixed | 2026-10-14 | `fabric/FABRIC-3.md` §XXXVIII |
| The Pi 5's GIC is under `/axi` with two-cell addresses; its framebuffer address needs `& 0x3FFFFFFF` | **under `/soc`, one cell**, read through `ranges`; the address **goes through `dma-ranges`** | 2026-10-14 | `fabric/FABRIC-3.md` §XXXIX |
| 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.
+22 -15
View File
@@ -1,20 +1,27 @@
# docs/DELETE-CANDIDATES.md
**Generated:** 2026-06-16 (docs reorg Phase 2)
**Status:** Awaiting Bob's explicit confirmation. Nothing here has been deleted.
**Listed:** 2026-10-14 (docs triage). **Status:** awaiting Captain Bob's ruling -- nothing here has
been deleted (docs/CLAUDE.md: never delete without confirmation).
These files were tagged `DELETE` during Phase 1 triage (see `docs/INDEX.md`).
Per the ground rules in `docs/CLAUDE.md`, they are listed here and left in place
until Bob confirms removal. They were relocated with their parent trees during
the Phase 2 reorganization but otherwise left unmodified (no provenance header
was inserted into them).
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.
| Path (current) | Original path | Reason |
|----------------|---------------|--------|
| docs/working/archive/quality/validation/break-me-report.md | docs/04-quality/validation/break-me-report.md | Empty (0 bytes); never written despite `break_me_tests.c` existing. |
| docs/working/scratch/src/bug_report.adoc | docs/src/bug_report.adoc | Generic GitHub bug-report template (smartphone/browser/OS fields) auto-converted to AsciiDoc; irrelevant to a CLI FORTH VM. |
| docs/working/scratch/src/feature_request.adoc | docs/src/feature_request.adoc | Generic GitHub feature-request template, garbled by AsciiDoc conversion; no project-specific content. |
| docs/working/scratch/src/internal/SHARED_CLAUDE.adoc | docs/src/internal/SHARED_CLAUDE.adoc | Dated 2025-10-19 ad-hoc AI session notes/chat log; pure transient working notes. |
(The four candidates listed 2026-06-16 -- an empty break-me report, two GitHub issue templates and
an AI session note -- are no longer in the tree: they were removed at some point since.)
To approve deletion, tell Claude "delete the DELETE candidates" (or list specific
ones to keep).
| Path | Why |
|---|---|
| `docs/lithosananke/hal/README.md` | 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` | Duplicate (older, unflagged) of docs/working/archive/dead/hal-target-contract/interfaces.md. |
| `docs/lithosananke/hal/lithosananke-integration.md` | 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` | Duplicate (older, unflagged) of docs/working/archive/dead/hal-target-contract/migration-plan.md. |
| `docs/lithosananke/hal/overview.md` | Duplicate (older) of docs/working/archive/dead/hal-target-contract/overview.md. |
| `docs/lithosananke/hal/platform-implementations.md` | Duplicate (older, unflagged) of docs/working/archive/dead/hal-target-contract/platform-implementations.md. |
| `docs/working/architecture/03-architecture/word-acl/DESIGN.md` | Older copy (2026-06) of docs/reference/word-acl/DESIGN.md, which is the maintained one (status through Phase 7). |
| `docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/FORMAL_CLAIMS_FOR_REVIEWERS.txt` | 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` | 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` | 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` | 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.
+652 -331
View File
File diff suppressed because it is too large Load Diff
+67 -53
View File
@@ -1,59 +1,73 @@
# StarForth / LithosAnanke Documentation
# StarForth / LithosAnanke documentation — the map
This is the `lithosananke` branch: the bare-metal StarKernel side of the project
(contrast `master`, which is the hosted-VM-only side). Documentation follows the
two-tier model described in `docs/CLAUDE.md`: **`formal/`** is the polished,
citable LaTeX tier; **`working/`** is living design notes and drafts that feed it.
Everything else in this directory is branch- or subsystem-specific material that
doesn't fit either tier.
Start here. This page says where each kind of document lives and which one to believe.
Reorganised 2026-10-14 (the docs triage): one place for current reference, one archive for
everything kept as record, and every superseded or abandoned document labelled as such in
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.
## What to believe
| For | Authoritative | Where |
|---|---|---|
| How to work in this repo, and current status | `.claude/CLAUDE.md` | repo root |
| What was decided, and why; work as it happened | the FABRIC record | [fabric/](fabric/) — `FABRIC-3.md` is the living one |
| StarForth v4 (the F18-derived engine) | the v4 design | [v4.0.0/](v4.0.0/) and `../v4/README.md` |
| Roadmap and release-versioning policy | `ROADMAP.md` | [reference/](reference/) |
| Getting onto the boards | the bring-up checklist | `../boards/BRINGUP.md` |
| A word, a primitive, a term | the dictionaries and the ontology | [reference/](reference/) |
| What the code does | the code, and its folder's `README.md` | `../kernel/`, `../v3/`, `../v4/` |
Where two documents disagree, the one higher in this table wins, and code wins over all.
## Layout
- **[formal/](formal/)** — Three-volume LaTeX documentation set (research volumes,
practitioner books, standalone reports) plus the `scraps/` fragment library it's
assembled from. Audience: patent counsel, SSRN reviewers, licensees, hobbyists
with hardware in hand. See `formal/CLAUDE.md` for authoring conventions.
- **[working/](working/)** — Living documents: architecture design notes, DoE
experiment logs, hardware/platform notes, draft specs, academic-paper source
material, and an archive of superseded docs. Source material for `formal/`.
- **[03-architecture/](03-architecture/)** — Tripod VM architecture constraints and the
word-level ACL system design. (Note: the fleet is now **Hera/Artemis/Hestia** post-
reshuffle; the old Hera/Hermes/Artemis framing in older docs is historical. The older,
triaged copy of this tree is `working/architecture/03-architecture/`.)
- **[lithosananke/](lithosananke/)** — LithosAnanke kernel branch documentation:
milestone roadmap, system architecture, HAL reference, kernel command-line argument
design, and the amd64 APIC-timer ISR postmortem.
- **[birthing/](birthing/)** — VM birthing plan and status for the Hera-spawns-
Hermes/Artemis constellation, plus three-architecture QEMU acceptance logs.
- **[patent/](patent/)** — Provisional patent application source. **Legal hold —
ask Bob before touching anything in this directory.**
- **[api/](api/)** — Generated Doxygen tag file and warnings log (gitignored;
not part of the tracked doc tree).
- **[pptx/](pptx/)** — Elevator-pitch and deep-dive slide decks for different
audiences (technical, non-technical, academic, PhD-level).
- **[fabric/](fabric/)** — the design and work record, numbered in order. `FABRIC-3.md`
(bare-metal boot and everything since) is open; the others are closed:
- FABRIC-0, -1 and -2 are history;
- FABRIC-3.5 and -3.6 are the Tripod/kernel reshuffle, still authoritative for what they ruled;
- FABRIC-3.7 (elevation) is closed as not needed;
- FABRIC-4 holds ideas caught early, not yet scoped.
- **[v4.0.0/](v4.0.0/)** — StarForth v4: justification, engine, decomposition, nucleus, mesh,
parity with v3. `plans/` holds the step plans, all executed.
- **[reference/](reference/)** — current reference material:
- `ROADMAP.md` (roadmap and the ratified versioning policy);
- `M7.1.md` (init capsules and birth);
- `word-acl/` (the word-level ACL design);
- `kernel-args/` (the boot command line);
- `hosted-acceptance-test/`;
- `DICTIONARY.md` and `STARFORTH_PRIMITIVES.md` (the words);
- `ONTOLOGY.md` (the lexicon);
- `L8_ADAPTIVE_CONFIG_TABLE.md`.
- **[working/](working/)** — living material and the source for `formal/`:
- `architecture/` (design notes and HOWTOs);
- `experiments/` (DoE designs and campaign data);
- `papers/` (academic sources, the system narrative, proposals);
- `hardware/`, `specifications/` and `scratch/`;
- **`archive/`**, which has four parts:
- `historical/`: finished work, kept as record;
- `superseded/`: replaced, and each file's header names what replaced it;
- `dead/`: abandoned or never adopted;
- the older `legacy/`, `quality/`, `operations/`, `research/` and `session-logs/`.
- **[formal/](formal/)** — the press-ready LaTeX tier (three volumes, books, standalone
reports). Governed by `formal/CLAUDE.md`.
- **[book/](book/)** — the LithosAnanke and StarForth book build.
- **[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.
## Current Active Work
## Adding a document
> **⚠ `INDEX.md` is a dated triage snapshot (2026-06-16) and is stale.** The authoritative
> current status lives in `.claude/CLAUDE.md` and `docs/fabric/FABRIC-2.md` /
> `FABRIC-3.md` / `FABRIC-3.5.md` / `FABRIC-3.6.md` — not in the status tags in `INDEX.md`.
- **LithosAnanke M7.1 — live** — init capsules, the Tripod fleet, Stadium physics-economy,
and word-level ACL (Phases 1–7 complete; Phase 8 Ed25519 PKI pending). See
`lithosananke/ROADMAP.md` and the FABRIC documents above.
- **Tripod VMs (post-reshuffle)** — Hera (governor), Artemis (memory/block storage),
Hestia; the Hermes VM was removed and messaging moved into the kernel as kernel-Hermes.
See `.claude/CLAUDE.md`.
- **StarForth v4** — the F18-derived 32-opcode engine with the node/mesh design. See
`v4.0.0/` and `../v4/README.md`.
- **Word-level ACL system** — see `03-architecture/word-acl/` and `lithosananke/ROADMAP.md`.
## Contributing
- Place new material in `working/` first; promote to `formal/` only when it's
ready to be cited (see `formal/CLAUDE.md` for promotion criteria).
- Never touch `patent/`, `formal/patent/`, `formal/scraps/legal/`, or
`working/legal/` without Bob's explicit instruction.
- Add a `README.md` to any new category-level subdirectory, following the
format used throughout this tree: orientation paragraph + bullet list of
real files with one-line descriptions.
- Draft in `working/`; promote to `formal/` when it is ready to be cited (`formal/CLAUDE.md`).
Reference material that describes the system as it is goes in `reference/`.
- When a document is overtaken, do not delete it: `git mv` it into `working/archive/superseded/`
or `dead/` with a header saying why and what replaces it, and add a line to
`DEAD-AND-REVISED.md`.
- Rules for documentation work: [CLAUDE.md](CLAUDE.md).
+14
View File
@@ -4,6 +4,20 @@ Historical, superseded, and obsolete records — kept for reference, not for
current guidance. Each subdirectory carries a provenance comment noting its
pre-reorg path and already has its own `README.md`.
Since the 2026-10-14 docs triage, three folders sort what is filed here by *why* it is no
longer current; each file in them starts with a header saying what it is and where to look
instead (and `docs/DEAD-AND-REVISED.md` keeps the register):
- **[historical/](historical/)** — finished work, accurate for its time: session plans, audits,
fix write-ups, the birthing plan, the January architecture draft. Dated names.
- **[superseded/](superseded/)** — replaced by something named in its header: the Hermes-VM
Tripod docs and designs (now FABRIC-3.5/3.6), the StarForth-era roadmap, documents already
flagged superseded or obsolete.
- **[dead/](dead/)** — ideas abandoned or never adopted: the `hal_*` target contract, L4Re,
the metrics-and-knobs gap list.
The older folders, from the 2026-06-16 reorganisation:
- **[legacy/](legacy/)** — The former top-level `docs/archive/` tree,
including `phase-1/` peer-review submission material.
- **[operations/](operations/)** — The former `docs/05-operations/`: CI/CD,
+1 -1
View File
@@ -31,7 +31,7 @@ matching test module in `src/test_runner/modules/`.
- `q48_16_words.c`, `q48_words.c` — Q48.16 fixed-point word bindings.
- `starforth_words.c` — StarForth-specific extensions.
- `acl_words.c` — word-level ACL system's FORTH-callable primitives (see
`docs/03-architecture/word-acl/`).
`docs/reference/word-acl/`).
- `lifecycle_words_hosted.c` — hosted-build VM lifecycle words (birth/run
primitives on the hosted side; kernel-only primitives live in
`src/starkernel/capsule/mama_forth_words.c`).