docs: reorganise -- current reference gathered, finished work archived, superseded and dead ideas marked as such

docs/CLAUDE.md Phase 2, 2026-10-14. All moves by git mv; every archived file carries a header saying what it is, why, and where to look instead. - docs/reference/ (new): roadmap and versioning policy, M7.1, word-ACL design, kernel args, hosted acceptance test, dictionary, primitives, ontology, L8 table -- previously spread over docs/, docs/lithosananke/ and docs/03-architecture/. - docs/working/archive/historical/: finished work (session plan, test-gap audit, birthing plan, fix write-ups, the January architecture draft). - docs/working/archive/superseded/: the Hermes-VM Tripod docs and July Hermes designs (-> FABRIC-3.5/3.6), the StarForth roadmap, every working doc already flagged superseded or obsolete. - docs/working/archive/dead/: the hal_* target contract (never adopted), L4Re, metrics-and-knobs. - Papers and proposals into docs/working/papers/. - References rewritten across the repo (not logs/, not docs/patent/); CLAUDE.md's documentation section rewritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 16:03:56 -04:00
parent 1a4b163861
commit 7aed588f78
116 changed files with 305 additions and 175 deletions
@@ -1,22 +0,0 @@
-# docs/birthing/
-
-Design and status for VM "birthing" — the mechanism by which Hera (the Tripod
-governor) spawns Hermes and Artemis as child VMs at boot. See
-`docs/03-architecture/tripod/TRIPOD.md` for the architectural contract this
-work implements.
-
- **[PLAN.md](PLAN.md)** — Birthing plan for the initial three-VM constellation
-  (Hera/Hermes/Artemis). Marked DRAFT, requires Captain Bob approval before
-  implementation.
- **[STATUS.md](STATUS.md)** — Current work status: execution model (single
-  OS process, no threads/fork, VMs share one heap and address space, the C
-  call stack doubles as the execution stack), the birth-graph vs.
-  execution-stack distinction, and phase completion tracking.
- **[acceptance-logs/](acceptance-logs/)** — Three-architecture QEMU
-  acceptance test logs and summary for the lifecycle words (`BIRTH KILL
-  START STOP USE`).
-
-## See also
-
- [`docs/03-architecture/tripod/README.md`](../03-architecture/tripod/README.md)
- [Project root](../../README.md)
@@ -1,19 +0,0 @@
-# docs/birthing/acceptance-logs/
-
-Kernel QEMU acceptance test results for the VM lifecycle words (`BIRTH KILL
-START STOP USE`) and the `."` compile-mode fix, run across all three
-supported architectures.
-
- **[SUMMARY.md](SUMMARY.md)** — Consolidated results table (800 tests run,
-  734 passed, 0 failed/errored on amd64/aarch64/riscv64), key serial-log
-  evidence, list of source files changed, and the remaining interactive
-  tests that require Captain Bob (`S" Hermes" USE`, KILL + re-BIRTH in the
-  same session).
- **[amd64.log](amd64.log)** — Raw QEMU serial log, amd64.
- **[arm64.log](arm64.log)** — Raw QEMU serial log, aarch64.
- **[riscv64.log](riscv64.log)** — Raw QEMU serial log, riscv64.
-
-## See also
-
- [`docs/birthing/README.md`](../README.md)
- [Project root](../../../README.md)
@@ -1,63 +0,0 @@
-# Birthing — Kernel QEMU Acceptance Test Summary
-
-**Date:** 2026-05-27
-**Branch:** `birthing`
-**Feature:** Lifecycle words (BIRTH KILL START STOP USE) + `."` compile-mode fix
-
-## Scope
-
-These logs cover the **kernel UEFI build** (`make -f Makefile.starkernel ARCH=<arch> clean qemu`).
-All three architectures booted to `ok>`, ran POST, and executed `capsules/init.4th` successfully.
-
-## Kernel QEMU Results
-
-| Arch | Tests | Passed | Failed | Errors | BIRTH Hermes | BIRTH Artemis | `."` |
-|------|-------|--------|--------|--------|-------------|---------------|------|
-| amd64   | 800 | 734 | 0 | 0 | `[Hermes] Hermes Up` / live | `[Artemis] Artimis Up` / live | PASS |
-| aarch64 | 800 | 734 | 0 | 0 | `[Hermes] Hermes Up` / live | `[Artemis] Artimis Up` / live | PASS |
-| riscv64 | 800 | 734 | 0 | 0 | `[Hermes] Hermes Up` / live | `[Artemis] Artimis Up` / live | PASS |
-
-## Key Evidence (all three architectures identical)
-
-```
-[Hera] POST: PASSED
-[Hera] Init: loading init.4th...
-[Hermes] Hermes UpBIRTH: Hermes live
-[Artemis] Artimis UpBIRTH: Artemis live
-[Hera] Init: init.4th OK
-```
-
-`."` in compile mode now uses the `(do-string)` inline runtime — string bytes live
-inside the threaded code body, not at `body_addr`. The previous LIT-addr-LIT-len-TYPE
-approach overwrote the start of the word body with string bytes, causing a triple fault
-when `execute_colon_word` read them as DictEntry pointers.
-
-## What Changed
-
- `src/word_source/io_words.c` — `."` compile mode replaced with `(do-string)` inline
-  approach; `(do-string)` runtime word reads inline string via return-stack IP, prints,
-  advances IP past padded block
- `src/starkernel/capsule/mama_forth_words.c` — BIRTH KILL START STOP USE kernel
-  implementations; fixed caddr+1 offset bug to align with FORTH-79 S"
- `src/word_source/string_words.c` — S" fixed to FORTH-79 standard ( -- c-addr u )
- `src/word_source/lifecycle_words_hosted.c` — hosted Linux stubs (guarded #ifndef __STARKERNEL__)
- `src/main.c` — register_lifecycle_words(&vm) wired in for hosted build
- `capsules/init.4th` — S" Hermes" BIRTH + S" Artemis" BIRTH
- `capsules/hermes/init.4th` — stub: `: UP ." Hermes Up" ; UP`
- `capsules/artemis/init.4th` — stub: `: UP ." Artimis Up" ; UP`
-
-## Serial Logs
-
-| Arch | Log file |
-|------|----------|
-| amd64   | `logs/qemu-amd64-20260526-234957.log` |
-| aarch64 | `logs/qemu-aarch64-20260526-235056.log` |
-| riscv64 | `logs/qemu-riscv64-20260527-000127.log` |
-
-(`logs/` is gitignored — run locally to reproduce)
-
-## Remaining Interactive Tests (require Captain Bob)
-
- `S" Hermes" USE` — switches system console to Hermes
- `S" Hera" USE` — switches back
- KILL + re-BIRTH a VM in the same session
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:2dbe1a4abd9342a0ec96fbd4c4c15ab039385b2af9639c7489eda6fe9dfc6fa4
-size 10216
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:25dc9dcce2403f30ef6b2c0d14e5462d7e17e42070c1afa443f92cf85985cd99
-size 9889
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:2af00462812d21a44807da17be38ad5fb5e97ca56b4c2b883cf192b7ef1778db
-size 9885