From ab96a9f2bec32f10d78cc7f3b42d88caa87198e3 Mon Sep 17 00:00:00 2001 From: rajames Date: Fri, 9 Oct 2026 19:34:30 -0400 Subject: [PATCH] docs: fix stale path references in .claude/CLAUDE.md Re-root stale references to actual locations: (shared engine/hosted) and (LithosAnanke). Update source tree diagram accordingly, correct / counts, and remove the obsolete bullet. Also fix include paths (, ). Surgical correction only; no behavioral changes. --- .claude/CLAUDE.md | 126 +++++++++++++++++++++++++--------------------- 1 file changed, 69 insertions(+), 57 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 5e76a959..8610b1a7 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -26,7 +26,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co > track a codebase it no longer describes would defeat its purpose as a record. > **Tripod/kernel reshuffle — Phases 0–4 COMPLETE (2026-09-22); Phase 5 close-out in -> progress.** Hermes moved into the kernel as kernel-Hermes (`src/starkernel/vm/kernel_ +> progress.** Hermes moved into the kernel as kernel-Hermes (`kernel/src/vm/kernel_ > hermes.c`); the Tripod is now **Hera / Artemis / Hestia** — **the Hermes VM, `capsules/ > hermes/init.4th`, and `capsules/common/messaging.4th` no longer exist in this codebase.** > Design is complete and ruled in **`FABRIC-3.5.md`** (authoritative); execution is tracked in @@ -39,10 +39,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co > **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 -> now. This repo vendors a full copy of the shared VM source (`src/vm.c`, `src/word_source/`, -> `capsules/`, `proof/`) because LithosAnanke embeds it as its execution engine — that vendored -> code is not a leftover or a second production target, it's load-bearing here. Kernel-specific -> code lives in `src/starkernel/`. +> now. This repo vendors a full copy of the shared VM source (`v3/src/vm.c`, +> `v3/src/word_source/`, `capsules/`, `proof/`) because LithosAnanke embeds it as its +> execution engine — that vendored code is not a leftover or a second production target, it's +> load-bearing here. Kernel-specific code lives in `kernel/src/`. --- @@ -81,21 +81,24 @@ about "which line am I on." - **`' BIRTH` in shared capsules breaks the hosted build** — BIRTH is kernel-only. `capsules/ACL.4th` itself documents this exclusion in a comment (line ~64) — it deliberately omits `BIRTH`/`CAPSULE-BIRTH` even though this IS the kernel repo, because `ACL.4th` is meant to stay portable/shared. ### On the Embedded VM vs. the Kernel -- **`src/vm.c`, `include/vm.h`, `capsules/`, `src/word_source/` are the shared/vendored VM - source.** They must compile and behave correctly both standalone (bare `make` here still - produces a plain hosted `starforth` binary for quick local sanity checks) and embedded in - the kernel build. Gate kernel-only code with `#ifdef __STARKERNEL__` or +- **`v3/src/vm.c`, `v3/include/vm.h`, `capsules/`, `v3/src/word_source/` are the + shared/vendored VM source.** They must compile and behave correctly both standalone (bare + `make` here still produces a plain hosted `starforth` binary for quick local sanity checks) + and embedded in the kernel build. Gate kernel-only code with `#ifdef __STARKERNEL__` or `#ifdef STARFORTH_ENABLE_VM`. - **The vendored VM source has diverged from the standalone StarForth repo's copy** — it is - not a byte-identical mirror. This repo's `src/word_source/` has 31 files (StarForth's has - 26); the extras (`defer_words.c`, `inference_words.c`, `lifecycle_words_hosted.c`, - `log_words.c`, `q48_words.c`) are kernel-side-only additions. Don't assume a fix made in - the StarForth repo needs to be, or even can be cleanly, ported here — check first. - Similarly `src/starkernel/` here is real and load-bearing (~74 files across arch/boot/ + not a byte-identical mirror. This repo's `v3/src/word_source/` has 35 files (StarForth's + has 26; the count was 31 in an earlier revision of this file — corrected 2026-10-09); the + extras (`defer_words.c`, `inference_words.c`, `lifecycle_words_hosted.c`, `log_words.c`, + `q48_words.c`) are kernel-side-only additions, as are the console/input words + (`framebuffer_words.c`, `keyboard_words.c`, `scroll_words.c`, `ttf_words.c`). Don't assume + a fix made in the StarForth repo needs to be, or even can be cleanly, ported here — check + first. Similarly `kernel/src/` here is real and load-bearing (~74 files across arch/boot/ capsule/hal/memory/math/hash/pci/virtio/vm subtrees) — much larger than older docs claimed. -- **`src/*.c.bak` files (`vm.c.bak`, `doe_metrics.c.bak`, `inference_engine.c.bak`) are - tracked in git at the `src/` top level.** This looks like repo hygiene debt, not - intentional. Report it if it comes up; don't delete unprompted. +- **The `*.c.bak` files are gone.** `vm.c.bak`, `doe_metrics.c.bak`, and + `inference_engine.c.bak` — previously tracked at the `v3/src/` top level per an older revision + of this file — no longer exist anywhere in the tree (verified 2026-10-09 via `git ls-files` + and a filesystem scan). The hygiene debt was cleaned up; nothing to report. - **There is no `make test` target in this repo's hosted `Makefile`** (unlike the standalone StarForth repo, which has one). Don't invent one. The only acceptance authority for kernel changes is the three-arch QEMU boot (see below); bare `make` here is for quick compile @@ -140,10 +143,10 @@ The word-level ACL system is fully implemented, including kernel parity. Key con 6. ✅ `EMERGENCY_CONSOLE_ENABLED` build flag + `vm_fault_handler` extension point 7. ✅ LithosAnanke kernel parity — **independently verified present in current `master`**: `acl_recheck()`/`zuse_session`/`emergency_console` wiring confirmed in - `src/starkernel/vm/vm_core.c` (~lines 549, 608–633, 747–749, 906–908); the + `kernel/src/vm/vm_core.c` (~lines 549, 608–633, 747–749, 906–908); the per-iteration `emergency_console = zuse_session ? 0 : 1` assignment confirmed in - `src/starkernel/repl.c` (~lines 174, 219); the old `!vm->zuse_session` ACL-check bypass - confirmed **absent** from `src/vm.c`. (The `feature/acl-rwt` branch this work was + `kernel/src/repl.c` (~lines 174, 219); the old `!vm->zuse_session` ACL-check bypass + confirmed **absent** from `v3/src/vm.c`. (The `feature/acl-rwt` branch this work was apparently done on is not traceable in `git log --all` — likely squash-merged without preserving the ref. The code is real and verified; the branch name is not.) 8. ⬜ PKI / thumbdrive — Ed25519 challenge-response; user minting by zuse. **This is the open @@ -209,7 +212,7 @@ changes with any new C word registration). produces a new capsule - **Tripod** — a named multi-VM fleet (Hera the Mama VM, Artemis, Hestia) that births, runs, and re-births independently; verified booting live pre-REPL on all three architectures. - Hermes moved into the kernel as kernel-Hermes (`src/starkernel/vm/kernel_hermes.c`) and is + Hermes moved into the kernel as kernel-Hermes (`kernel/src/vm/kernel_hermes.c`) and is no longer a Tripod VM — see `FABRIC-3.5.md`/`FABRIC-3.6.md`, not the archived `.claude/TRIPOD.md`/`.claude/HERMES.md`/`.claude/ARTEMIS.md`. - Word-level ACL security system with kernel parity (see above) — measured overhead three @@ -342,41 +345,45 @@ it ships a raw disk image instead). No QEMU boot step in CI — artifact packagi ### Source Tree ``` -src/ -├── main.c, vm.c, vm_api.c, vm_bootstrap.c, vm_debug.c, vm_time.c # Vendored VM core (see below) -├── repl.c, cli.c, io.c, log.c # Vendored VM core -├── memory_management.c, dictionary_management.c, block_subsystem.c, blkio_*.c -├── stack_management.c, math_portable.c, profiler.c, compudynamics.c -├── heartbeat_export.c, ssm_jacquard.c, doe_metrics.c -├── physics_runtime.c, physics_hotwords_cache.c, physics_metadata.c, -│ physics_pipelining_metrics.c, physics_execution_hooks.c, -│ rolling_window_of_truth.c, inference_engine.c # 7 feedback loops -├── vm.c.bak, doe_metrics.c.bak, inference_engine.c.bak # tracked but stale — flag, don't delete unprompted -│ -├── word_source/ # 31 files (vendored StarForth word_source PLUS -│ │ # kernel-side-only additions) -│ ├── (all of StarForth's 26: arithmetic, stack, control, defining, memory, -│ │ return_stack, double, logical, io, string, block, editor, format, system, -│ │ dictionary, dictionary_manipulation, dictionary_heat_diagnostic, vocabulary, -│ │ q48_16, starforth, acl, physics_benchmark, physics_diagnostic, -│ │ physics_freeze, physics_pipelining_diagnostic, mixed_arithmetic) -│ └── kernel-only additions: defer_words.c, inference_words.c, -│ lifecycle_words_hosted.c, log_words.c, q48_words.c -│ -├── test_runner/ # 23 test module files (matches StarForth's count) -│ -├── platform/ # Platform abstraction (hosted build) -│ -└── starkernel/ # ~74 files — the real, load-bearing kernel tree - ├── kernel_main.c # Kernel entry point (M0–M9 milestones) - │ # NOTE: this file's own header comment claims - │ # "M7: Not started" — that comment is STALE; - │ # M7/M7.1/M7.pre logic is present and functional - │ # (kernel_main.c ~lines 481–517). Don't propagate - │ # the stale comment. +v3/ # hosted StarForth product AND the shared engine source +├── Makefile # hosted build (bare `make` at the repo root forwards here) +├── include/ # vm.h, version.h — the only VM headers (no top-level `include/`) +└── src/ + ├── main.c, vm.c, vm_api.c, vm_bootstrap.c, vm_debug.c, vm_time.c # Shared VM core (see below) + ├── repl.c, cli.c, io.c, log.c # Shared VM core + ├── memory_management.c, dictionary_management.c, block_subsystem.c, blkio_*.c + ├── stack_management.c, math_portable.c, profiler.c, compudynamics.c + ├── heartbeat_export.c, ssm_jacquard.c, doe_metrics.c + ├── physics_runtime.c, physics_hotwords_cache.c, physics_metadata.c, + │ physics_pipelining_metrics.c, physics_execution_hooks.c, + │ rolling_window_of_truth.c, inference_engine.c # 7 feedback loops + ├── word_source/ # 35 files (StarForth word_source PLUS + │ │ # kernel-side-only additions) + │ ├── (StarForth's ~26: arithmetic, stack, control, defining, memory, + │ │ return_stack, double, logical, io, string, block, editor, format, system, + │ │ dictionary, dictionary_manipulation, dictionary_heat_diagnostic, vocabulary, + │ │ q48_16, starforth, acl, physics_benchmark, physics_diagnostic, + │ │ physics_freeze, physics_pipelining_diagnostic, mixed_arithmetic) + │ ├── kernel-side-only additions: defer_words.c, inference_words.c, + │ │ lifecycle_words_hosted.c, log_words.c, q48_words.c + │ └── console/input words: framebuffer_words.c, keyboard_words.c, + │ scroll_words.c, ttf_words.c + ├── test_runner/ # 26 test module files + └── platform/ # Platform abstraction (hosted build) + +kernel/ # LithosAnanke — the real, load-bearing kernel tree +├── Makefile # UEFI loader + kernel ELF + QEMU; embeds a subset of v3/src +├── include/starkernel/ # kernel-only headers +└── src/ + ├── kernel_main.c # Kernel entry point (M0–M9 milestones) + │ # NOTE: this file's own header comment claims + │ # "M7: Not started" — that comment is STALE; + │ # M7/M7.1/M7.pre logic is present and functional + │ # (kernel_main.c ~lines 481–517). Don't propagate + │ # the stale comment. ├── repl.c # Kernel REPL ├── arch/{amd64,aarch64,riscv64}/ # Per-arch: arch.c apic.c timer.c interrupts.c boot.S isr.S - ├── boot/ # uefi_loader.c elf_loader.c reloc_stub.c reloc.S + ├── boot/ # uefi_loader.c elf_loader.c cmdline.c reloc_stub.c reloc.S ├── capsule/ # capsule_birth.c capsule_run.c capsule_loader.c │ # capsule_find.c capsule_validate.c capsule_vm_hooks.c │ # capsule_vm_physics.c mama_forth_words.c @@ -391,10 +398,15 @@ src/ ├── math/q48_16.c # Q48.16 fixed-point (kernel build) ├── hash/xxhash64.c # XXHash64 (content addressing) ├── doe_log.c + ├── artemis_sig.c homeblocks_sig.c heartbeat.c log_region.c # kernel services + ├── crypto/ rng/ usb/ # PKI (Ed25519), entropy, USB + ├── v4/sk_v4.c # bare-metal embed of the v4 engine (STARFORTH_V4=1) └── vm/ # Kernel VM subsystem ├── bootstrap/sk_vm_bootstrap.c ├── host/shim.c ├── vm_core.c vm_runtime.c vm_bootstrap.c q48_stubs.c + ├── kernel_hermes.c # kernel-Hermes (post-reshuffle) + ├── session.c stadium.c stadium_blocks.c stadium_words.c switch.c ├── parity.c # Birth/execution parity logging ├── arena.c # Capsule arena allocator └── alloc_kernel.c @@ -503,7 +515,7 @@ status for kernel work. warnings) but deliberately downgraded from fatal, everything else is. The previous version of this line claimed `-Wmissing-field-initializers` was isolated to one file (`vocabulary_words_test.c`) — that was never accurate; a full audit found it systemic - across 20 files in `src/test_runner/modules/` (all missing the same later-added + across 20 files in `v3/src/test_runner/modules/` (all missing the same later-added `TestCase.contract`/`WordTestSuite.suite_contract` trailing field, ~3,010 instances). Fixed in place across all 20 files (mechanical: added the missing `{0}` initializer, semantically a no-op since C99 already zero-fills unlisted trailing fields — the fix only silences the @@ -535,14 +547,14 @@ status for kernel work. ### DoE CSV Output Suppression -Intentionally suppressed as of 2025-12-08. See `src/main.c:390-396`: +Intentionally suppressed as of 2025-12-08. See `v3/src/main.c:390-396`: - Metrics still collected via `metrics_from_vm()` - CSV row was redundant with internal VM metrics - To re-enable: add a `--csv-export` flag or write to a file ### Heartbeat Instrumentation (Planned) -`HeartbeatTickSnapshot` and `tick_buffer` are declared in `include/vm.h`, +`HeartbeatTickSnapshot` and `tick_buffer` are declared in `v3/include/vm.h`, but `heartbeat_export_csv()` is **not yet implemented**. ### Word Statistics Output