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>

docs/reference/hosted-acceptance-test/README.md

@@ -0,0 +1,178 @@
+# Hosted StarForth — 3-Architecture Acceptance Test
+
+**Date**: 2026-07-24 (original), corrected 2026-08-02
+**Branch**: `master`
+**Commits**: `edced063` (original block-subsystem fix), `4485c38` (doc +
+3 clang-surfaced bug fixes), `e287334` (asm register-reuse fix), this pass
+(`riscv64-clang` Makefile target)
+
+---
+
+## What this verifies
+
+The **hosted** StarForth VM (`make`, not `Makefile.starkernel`) is a static
+binary. This test confirms it starts cleanly — reaches the `ok>` REPL prompt
+with no errors — on all three architectures the project targets:
+
+- **amd64** — native execution on the build host
+- **aarch64** — cross-compiled, run under QEMU user-mode emulation
+- **riscv64** — cross-compiled, run under QEMU user-mode emulation
+
+This is distinct from the kernel (`Makefile.starkernel`) 3-arch acceptance
+test documented in
+[`../amd64-isr-fix/README.md`](../amd64-isr-fix/README.md), which boots a
+full UEFI bare-metal image under system-mode QEMU. This test only exercises
+the hosted Linux binary, using QEMU **user-mode** emulation to run a
+foreign-architecture static binary directly on the x86_64 host — no kernel,
+no UEFI firmware, no system emulation.
+
+---
+
+## Prerequisites
+
+Cross toolchains, QEMU user-mode emulation, and clang (needed for the
+riscv64 leg — see below):
+
+```bash
+sudo apt-get install -y \
+    gcc-aarch64-linux-gnu \
+    gcc-riscv64-linux-gnu \
+    clang-18 lld-18 \
+    qemu-user
+```
+
+`qemu-user` alone is enough — the binaries built below are statically
+linked (`-static`), so the non-static `qemu-<arch>` emulators run them
+directly with no sysroot. (The `qemu-user-static` package, if you see it
+referenced elsewhere, provides statically-linked *emulators*; it's not
+required just because the *guest* binary is static.)
+
+---
+
+## Invocation note
+
+None of the three binaries accept a `-c "<script>"` flag — earlier
+revisions of this doc showed one, but `src/cli.c`/`src/main.c` have never
+had one in this repo's history. Pipe the script via stdin with `-s`
+(script/silent mode) instead. Startup always runs the full internal POST
+test suite before the REPL takes stdin, so expect substantial test-suite
+output before your script's result appears at the very end.
+
+---
+
+## amd64 — native
+
+```bash
+make clean && make
+echo "1 2 + . BYE" | ./build/amd64/standard/starforth -s
+```
+
+Expect `3 Goodbye!` at the end of the output, then a clean exit. No
+emulation needed — this is the build host's native architecture.
+
+---
+
+## aarch64 — cross-compile + QEMU user-mode
+
+```bash
+make rpi4-cross
+echo "1 2 + . BYE" | qemu-aarch64 ./build/raspi/fastest/starforth -s
+```
+
+`make rpi4-cross` cross-compiles with `aarch64-linux-gnu-gcc`
+(`ARCH=raspi`, `TARGET=fastest`, `-static`); see `Makefile:547-554`. The
+output binary is statically linked, so `qemu-aarch64` can execute it
+directly with no sysroot.
+
+---
+
+## riscv64 — cross-compile + QEMU user-mode
+
+```bash
+make riscv64-clang
+echo "1 2 + . BYE" | qemu-riscv64 ./build/riscv64/fastest/starforth -s
+```
+
+`make riscv64-clang` cross-compiles with `clang-18` (`ARCH=riscv64`,
+`TARGET=fastest`, `-static`); see `Makefile:566-579`. **This leg must use
+clang, not GCC**: `riscv64-linux-gnu-gcc` fails to build this tree
+(`nanosleep` visibility failure under `-std=c99`, unrelated to any project
+change — root cause not yet chased down, see
+`docs/working/archive/session-logs/2026-07-24-punch-list.md` item #3). The
+target's `CFLAGS` deliberately does not reuse the Makefile's
+`$(BASE_CFLAGS)` (which hardcodes `-std=c99`) — clang needs `-std=c11
+-pthread` here instead, plus `-fuse-ld=lld` in `LDFLAGS` (folding it into
+`CC` makes clang reject it as an unused argument during `-c`/compile-only
+invocations under `-Werror`).
+
+---
+
+## Pass criteria
+
+For each architecture:
+
+1. Build completes with no errors.
+2. `blk_subsys_init` succeeds — no `"Failed to initialize block subsystem"`
+   error. (This was broken on every architecture, including amd64, prior to
+   `edced063` — see below.)
+3. The internal POST suite runs (substantial log output — expected, not a
+   failure by itself) and the piped `1 2 + . BYE` script prints `3 Goodbye!`
+   at the end.
+
+---
+
+## Background: the block-subsystem bug this depends on
+
+Before `edced063`, the hosted VM could not start on **any** architecture on
+this branch. `src/main.c` allocated a hardcoded `blk_ram[1024 * 1024]`
+buffer, stale relative to `BLK_RAM_BLOCKS=2080` (`include/block_subsystem.h`)
+— a deliberate redesign that moved the RAM/ramdrive boundary to physical
+block 2080 (user-visible LBN 2048), per `BLK_FORTH_SYS_RESERVED=32`. The
+kernel-side buffer in `src/starkernel/vm/bootstrap/sk_vm_bootstrap.c` already
+derived its size correctly from the shared constant; `main.c` was the one
+remaining hardcoded holdout. The fix:
+
+```c
+#include "block_subsystem.h"
+...
+static uint8_t blk_ram[BLK_RAM_BLOCKS * BLK_FORTH_SIZE];   /* was: blk_ram[1024 * 1024] */
+```
+
+This is why the acceptance test above is meaningful on this branch
+specifically: it did not pass before this fix, on any of the three
+architectures.
+
+---
+
+## Background: the riscv64 clang build (2026-08-02 correction)
+
+The riscv64 command above was broken in this doc from 2026-07-24 until this
+correction — `docs/working/archive/session-logs/2026-07-24-punch-list.md`
+(item #2) recorded that the working clang invocation had been found and
+fixed in the old pre-split monorepo's `master` branch's `.claude/CLAUDE.md`,
+but the correction was never copied into this doc. Verifying it end-to-end
+for this correction surfaced that the clang build also needs three small
+source fixes from that same punch list (item #1), previously ported to the
+old monorepo's `master` but not to this line:
+
+- `src/math_portable.c` — `-100LL << 16` is UB (shifting a negative value)
+  under `-Wshift-negative-value`; changed to `-(100LL << 16)`.
+- `src/physics_pipelining_metrics.c` — removed dead `q48_mul_q48()`
+  (`-Wunused-function` under clang; GCC doesn't catch this by default).
+- `src/word_source/editor_words.c` — removed dead `set_scr()` (same reason).
+
+The punch list's highest-priority item — a genuine SIGSEGV-causing
+register-reuse hazard in `include/vm_asm_opt_riscv64.h`'s `vm_pop_asm`/
+`vm_rpop_asm` (clang's register allocator can pick the same register for a
+memory operand referenced both before and after a write-back, corrupting
+the result; GCC happens not to hit it) was *not* required just to get this
+acceptance test's `-O3` build to compile and pass, but has since been
+fixed too (commit `e287334`) — and turned out not to be merely a latent
+risk: it was silently corrupting 10 `CASE.*` control-flow tests under this
+exact build (`955`/`10 failed` → `965`/`0 failed`, `ALL IMPLEMENTED TESTS
+PASSED!`, with nothing else changed).
+
+Item #3 of the same punch list — no `make` target for this leg, only the
+long manual invocation — is also resolved as of this pass: `make
+riscv64-clang` wires in the same recipe verified above directly into the
+Makefile.

docs/reference/kernel-args/README.md

@@ -0,0 +1,18 @@
+# docs/reference/kernel-args/
+
+Design doc for kernel command-line arguments (`KernelArgs`).
+
+- **[DESIGN.md](DESIGN.md)** — Design for runtime-configurable memory sizing
+  and behavior (heap size, stack depth, DoE self-start, log verbosity)
+  currently baked in as compile-time constants. Covers the UEFI
+  `EFI_LOADED_IMAGE_PROTOCOL->LoadOptions` mechanism, the `KernelArgs`
+  struct, `BootInfo` changes, the assembly trampoline
+  (`kernel_entry.S`), the `cmdline.c` parser, loader/`kernel_main.c`/
+  Makefile integration, passing args under QEMU, and the `REBOOT` FORTH
+  word (including its NVRAM one-shot mechanism and hosted-VM stub). Status:
+  design complete, awaiting implementation.
+
+## See also
+
+- [`docs/working/archive/historical/2026-10-lithosananke-orientation.md`](../README.md) — kernel branch overview.
+- [Project root](../../../README.md)

docs/reference/word-acl/README.md

@@ -0,0 +1,24 @@
+# docs/reference/word-acl/
+
+Design doc for the word-level ACL (access control) system.
+
+- **[DESIGN.md](DESIGN.md)** — Full design: three ACL dispositions per word
+  (`STRICT`, `TTL`, `PINNED`), the four `DictEntry` fields (`acl_ttl`,
+  `acl_allow`, `acl_mode`, `acl_pinned`), the two VM flags
+  (`emergency_console`, `zuse_session`), and the implementation split between
+  C infrastructure and the pure-FORTH policy capsule `capsules/ACL.4th`.
+  Status: implemented through Phase 6 on `master`; Phase 7 (LithosAnanke
+  parity) is next.
+
+Implementation files referenced by this design: `capsules/ACL.4th`,
+`capsules/zuse.4th`, `src/word_source/acl_words.c`,
+`src/test_runner/modules/acl_words_test.c`, and the ACL proof set in
+`proof/` (`ACL_Pin_Monotone.thy`, `ACL_Inherit_Clears_Pin.thy`,
+`ACL_TTL_Bounded.thy`, `ACL_Emergency_Bypass.thy`, `ACL_No_Escalation.thy`).
+
+## See also
+
+- [`proof/README.md`](../../../proof/README.md) — the ACL proof theory files.
+- [`capsules/README.md`](../../../capsules/README.md) — capsule files
+  including `ACL.4th` and `zuse.4th`.
+- [Project root](../../../README.md)