@henols/c64-re-tools 0.2.2 → 0.2.4

package/skills/c64-program-recon/SKILL.md

@@ -23,6 +23,17 @@ node $D sprites --dd00 3E --d018 18 --d015 0F --ptrs 20,21,22,23,FF,FF,FF,FF
 The script does only the arithmetic that a lookup table cannot — register bits to concrete
 addresses — over values **you** fetched through `mcp__plugin_c64-re-tools_vice__*`. It contacts nothing.
 
+## Before disassembling anything
+
+Two adjacent jobs belong to other skills, and pointing at their owners is cheaper than re-deriving
+either one here:
+
+- **A file still sitting inside a `.d64` image** — its directory, block allocation map, sector
+  chain, or raw bytes — is `c64-disk-access`'s job. Get the file out of the image there first.
+- **A tokenized BASIC stub rather than raw machine code** — detokenizing it and finding where it
+  hands over to machine code, including the named decline when no static handover address exists —
+  is `c64-petcat`'s job. See below for the one thing it does not also do.
+
 ## The order
 
 Each step is a read whose answer rules something out. Do not skip ahead: step 6 is cheap once the
@@ -100,13 +111,20 @@ script measures it from the file. It prints one JSON object. Read the `verdict`:
 | `unknown` | No route produced an answer. `unavailableReason` always says why. | Continue, but record the unknown. Never write it up as "not packed". |
 
 **A name is reported only when an external oracle stated one, and this project does not guess.**
-No first-party route on this project's surface reports a packer name at all — the dated
-investigation that established this, four independent ways, is written out in
-`.planning/phases/19-absorbed-procedures-and-the-coverage-instrument/19-RESEARCH.md` §2, and the
-dated decision that fixes the acceptance bar and its re-open trigger is recorded under
-`19-DECISIONS.md` in that same directory (SURF-03). So there is no code path here that can write a packer name from entropy, from a
-decompression address, or from a byte pattern. If you want a name and the finding does not give
-you one, install an external identifier and point `UNP64` or `UNP64_PATH` at it — do not infer it.
+No first-party route on this project's surface reports a packer name at all — that was
+established four independent ways, and the acceptance bar a future first-party identifier would
+have to clear was fixed at the same time. So there is no code path here that can write a packer
+name from entropy, from a decompression address, or from a byte pattern. If you want a name and the finding does not give
+you one, install an external identifier on the **host** and point `UNP64` or `UNP64_PATH` at it in
+the environment the host broker process sees — do not infer it. `packer-finding.mjs` never spawns
+that identifier itself: it reaches it only through the host-tool execution
+seam (`src/mcp/vice/host-tool.mts`'s `oracle.probe`/`oracle.run` allowlist entries), because this
+script runs container-side and there is no container PATH to a host binary on. **The container-side
+environment is not consulted at all**: setting `UNP64`/`UNP64_PATH` in
+this script's own (container-side) environment adds only a diagnostic hint to an absent result —
+it can never select what the host executes. The oracle's location is host-side configuration
+only, and the configured path's file name must be the oracle binary's own name (`unp64`) or the
+seam treats it as absent.
 
 **The entropy gate answers packedness, not identity.** High entropy tells you the bytes are
 compressed (or encrypted, or genuinely random); it does not tell you by what. And the way a packed
@@ -154,7 +172,7 @@ The method reproduces a known-good result from a static image with no emulator r
 ## Writing findings into the annotation store
 
 Recon's findings are not memory-map prose written once and left to rot — they are entries in a
-queryable annotation store, and the Markdown memory map is a *generated view* of that store (D-24),
+queryable annotation store, and the Markdown memory map is a *generated view* of that store,
 not something you hand-edit yourself.
 
 **There is no bootstrap step, and no bootstrap verb.** The store is created by the first write to
@@ -163,7 +181,7 @@ it: name a `.annostore` path on any mutating call — `anno_set_label_name`, `an
 A read-only call against a path that does not exist yet is REFUSED by name rather than answering
 against an empty store, so "I read nothing" and "there is nothing to read" stay distinguishable.
 
-Every `anno_*` tool takes an explicit `store` path (D-19) — there is no ambient session state
+Every `anno_*` tool takes an explicit `store` path — there is no ambient session state
 naming the store, so which store a call touched is always visible in the transcript. Every call
 that derives its answer from the program's **bytes** rather than from the annotations takes an
 `image` path as well — `anno_get_binary_info`, `anno_read_region`, `anno_disassemble`,
@@ -189,7 +207,7 @@ bracket tokens (quoted verbatim from `anno-confidence.ts`, the parser's own sour
 (confirmed data), `[probable-data]` (probable data), `[unknown]` (unknown).
 
 A typo in the bracket token — wrong case, an underscore, a plural, stray whitespace — **fails
-loudly**; it does not silently degrade into an ungraded comment. As with `RE-FINDINGS.md`, do not
+loudly**; it does not silently degrade into an ungraded comment. Do not
 promote a row by editing its grade in place: re-verify and restate the evidence with a fresh
 `anno_set_comment` call, so the record of when something stopped being a guess survives.
 
@@ -233,7 +251,7 @@ error and no explanation of why.
 The **loop itself is not withdrawn**, only its two automated legs, and the discipline it encodes is
 what to keep doing by hand for as long as they stay gone:
 
-1. **The store is the merge point (D-29), not your own notes.** A name discovered live —
+1. **The store is the merge point, not your own notes.** A name discovered live —
    disassembling the running machine, a checkpoint hit — is written into the store with
    `anno_set_label_name` *first*, before it is carried anywhere else.
 2. **`vice_symbols_load` REPLACES the machine's symbol table rather than merging into it.** Call it
@@ -273,7 +291,7 @@ other generated artifact in this repo and never hand-edit it.
 existed.** Before gap-closure round 2 the banner recorded the store and the sidecar by their
 ABSOLUTE paths, so the checkout's own location was a silent third cause: an identical store,
 sidecar and rendered file reported `drifted` the moment the tree sat at a different absolute path,
-while `render-memmap` printed the same `render_digest` in both. Plan 29-18 removed that cause by
+while `render-memmap` printed the same `render_digest` in both. That cause was removed by
 recording workspace-relative locations, so the cause set above is the one the shipped verb has. The
 old two-cause wording is superseded rather than merely reworded, and this note says so because a
 reader meeting it in history needs to know which claim was live when.
@@ -293,8 +311,8 @@ shipped tree run the sync before they scan it, so a change made only in the twin
 is ever measured. A change made here is SHIPPED only once that sync has run.
 
 **Dated correction, 2026-08-30 — `render-memmap` reads the annotation store directly, and the note
-that used to stand here was WRONG when it shipped.** Phase 29 plan 29-12 rebuilt this verb over the
-Phase 28 annotation store on `D-17`'s authority: its positional is an EXISTING `.annostore`, opened
+that used to stand here was WRONG when it shipped.** This verb was rebuilt over the annotation
+store: its positional is an EXISTING `.annostore`, opened
 with `mustExist` — an absent store is refused by name rather than created — and nothing on the path
 it reaches consults the retired external analyser. The pre-store project file the earlier note named
 has no producer left in this repository, so there is no route back to the old spelling. That earlier
@@ -302,6 +320,29 @@ note asserted in the PRESENT TENSE that this verb still read a project file; it
 when it shipped, and it is DELETED here rather than amended, so a reader comparing two dated claims
 can tell which one to believe.
 
+**Importing a Ghidra export, and the mechanical join that follows it.** When a Ghidra harness run
+(a separate, host-side capability) has produced a transfer file, two calls land its findings in the
+store — in this order, and each is one mechanical call, not an agent turn:
+
+1. **`anno_import_ghidra_export`** reads the transfer file, writes one cross-reference row per
+   surviving reference, and DELETES the transfer file once every write has durably committed. It reports
+   `referencesSeen`, `xrefsWritten`, `xrefsAlreadyPresent` (a duplicate reference is deduplicated, not
+   double-counted) and `kindsSeenNotImported` — reference kinds outside this store's four-member
+   vocabulary, dropped and counted rather than guessed or refused. A malformed, truncated or
+   digest-mismatched export is refused by name, naming the section and the offending line, and writes
+   nothing.
+2. **`anno_join_memmap`** then reads every cross-reference target the store already holds, skips
+   addresses inside the program's own loaded image (those are code/data addresses, not hardware
+   features), and annotates everything else with the narrowest `c64-memory-mapping/memmap.json` entry
+   containing it. It reports `addressesConsidered`, `annotated`, `skippedInImage`,
+   `skippedNoMapEntry`, `declined` and `commentsChanged`, plus a per-address decision naming the
+   outcome and, for every skip, why.
+
+Both calls are **mechanical**: there is no agent invocation, no queue walk and no skill invocation
+anywhere inside either one, checked structurally over the two modules' own source rather than
+asserted in prose. Run the import call once per Ghidra export, then the join call once per updated
+image; neither call takes an agent turn to complete.
+
 ## Static disassembly
 
 **Dated withdrawal 2026-08-29, dated return 2026-08-31 — whole-program ACME export was WITHDRAWN
@@ -314,14 +355,17 @@ against the input** — never by an exit code and never by a string match on the
 output.
 
 ```bash
-npx -y @henols/vice-mcp anno export-asm game.prg --store game.annostore --out game.a
+npx -y @henols/vice-mcp anno export-asm game.prg --store game.annostore --out game-src
 node <plugin-root>/src/mcp/vice/vice-proxy.ts anno export-asm game.prg --store game.annostore
 ```
 
 `<image>` and `--store` are **two separate arguments and neither is derived from the other**: the
-image supplies the bytes, the store supplies the names, typed ranges and comments. `--out` defaults
-to a `.a` beside the **store** rather than beside the image, and an existing destination is refused
-rather than overwritten unless you pass `--force`.
+image supplies the bytes, the store supplies the names, typed ranges and comments. `--out` names a
+**directory** the whole export is written into, defaulting to the image's basename stem beside the
+**store** rather than beside the image, and a non-empty destination is refused rather than
+overwritten unless you pass `--force`. The directory holds a root file that sources the rest, one
+file per annotation scope, and an `unscoped.a` for any block that lies inside no scope — open the
+root file first to see how the tree fits together.
 
 **It writes source and runs no assembler**, and says so in its own second output line
 (`this file has NOT been assembled`). The real-ACME byte-diff is a **test-only** oracle in this
@@ -347,7 +391,7 @@ The two are complementary — reach for the static reads before the emulator is
 Extracting a program from a `.d64` image is a separate capability that this repository still does
 not have, and — correcting an earlier note that assigned it to the same numbered phase as the ACME
 export oracle — **no phase currently owns it**. Whenever it is built it must name the file inside
-the image explicitly and refuse rather than guess (D-02), because a guess could analyse a cracktro
+the image explicitly and refuse rather than guess, because a guess could analyse a cracktro
 or loader stub instead of the game.
 
 ## Before you touch the emulator
@@ -474,9 +518,9 @@ up a pointer or a vector does it with a pair of immediate loads — `LDA #<targe
 / STA ptr`, `LDA #>target / STA ptr+1`. Upstream calls `set_immediate_format`
 on each of the two instruction addresses, with `low_byte` / `high_byte` and the
 target, so the pair renders as one symbol reference. **That call is not exposed
-on this project's surface.** `BUILD-03` ("every branch, `JSR`/`JMP` and data
-reference goes through a symbol, so code can move") is the requirement that
-supplies its criterion, and the per-call disposition sits in the manifest named
+on this project's surface.** The rule it would serve — "every branch, `JSR`/`JMP`
+and data reference goes through a symbol, so code can move" — still supplies
+its criterion, and the per-call disposition sits in the manifest named
 in the attribution header above. Until then, recombine the two bytes yourself
 and put the reconstructed target in a side comment on both instructions, so the
 vector setup is readable even though the store cannot format it.
@@ -529,19 +573,26 @@ documented earlier on this page.
 | Disassembly appears to break mid-routine | Undocumented opcodes. Check the binary-info hint and keep reading. |
 | Zero-page usage contradicts the main program's | The routine runs from the IRQ. Its context is IRQ-relative. |
 
-## REFERENCE-ONLY: decoding Commodore BASIC tokens
-
-**This capability is DEFERRED under `FUT-01` and this skill does not claim
-it.** The reason is empirical, not a shortage of effort: a commercial C64 title
-captured after its loader has run almost universally reduces to a one-line
-`SYS` stub, so a token decoder would spend its life decoding `10 SYS 2064` and
-nothing else. The material below is carried as **reference text only** — read
-it if you hit the rare program that really does carry a tokenised BASIC
-program, and note that none of its trigger phrases appear in any skill's
-`description:` frontmatter, so it cannot fire on its own.
-
-If a future milestone lifts `FUT-01`, this section is the starting point rather
-than a fresh research task.
+## A tokenized BASIC stub: detokenize with c64-petcat, don't hand-decode it
+
+**Detokenizing a `SYS` stub and resolving its machine-code handover address is
+`c64-petcat`'s job, not this skill's.** Reach for its `decode` verb before
+reading tokenized bytes by hand: it wraps VICE's own `petcat` to produce the
+readable listing and to report the handover address — or a *named decline*
+(`entrypoint: null` with a reason) when the `SYS` argument is not a static
+value, which is a resolved answer, never a guess to spend a disassembler on.
+Corrected here: an earlier note claimed none of `c64-petcat`'s trigger phrases
+overlapped this skill's frontmatter; that was true only because the skill did
+not exist yet, and it is superseded now that it does.
+
+The material below stays as **reference text only**, narrowed to what
+`c64-petcat` does NOT do — write the tokenized bytes' typed ranges and
+comments into this project's annotation store. That is rare in practice: a
+commercial C64 title captured after its loader has run almost universally
+reduces to a one-line `SYS` stub, so most sessions never reach this section at
+all. When one does, use `c64-petcat`'s resolved listing and handover address
+as the source of truth rather than re-deriving them by hand from the byte
+layout below.
 
 ### Line anatomy
 
@@ -610,6 +661,8 @@ This one is the route between the stations. It does not restate what the others
 
 | Need | Go to |
 |---|---|
+| A disk image's directory, BAM, sector chains, or a named file's raw bytes | `c64-disk-access` |
+| Detokenizing a BASIC stub, or its machine-code handover address | `c64-petcat` |
 | A verified 64K image, or comparing two captures | `c64-ram-capture` |
 | What a specific address or bit means | `c64-memory-mapping` — `node … lookup '$D018'` |
 | Assembling | `acme-build` |
@@ -630,9 +683,10 @@ This one is the route between the stations. It does not restate what the others
 | `references/reconstruction.md` | Binary inclusion, behavioural-equivalence correctness bar, SMC labels, label vocabulary |
 | `templates/memory-map.template.md` | `render-memmap`'s provenance sidecar schema and the confidence vocabulary — the rendered map itself is generated, not hand-authored |
 
-Findings that make RE faster go in `.planning/RE-FINDINGS.md` **at the moment you find them**,
-graded with `Evidence:` and `Confidence:`. Promote by re-logging with the new evidence, never by
-editing a grade in place. File-changing work enters through a GSD command (`/gsd-quick`).
+Record findings that make RE faster in your own project notes **at the moment you find them**,
+graded with `Evidence:` and `Confidence:`. Promote a finding by re-logging it with the new
+evidence, never by editing an old grade in place — the grade is only worth anything if it says
+what was actually known when it was written.
 
 ## Troubleshooting
 
@@ -644,5 +698,5 @@ editing a grade in place. File-changing work enters through a GSD command (`/gsd
 | A sprite decodes as noise | Check `$D015` first; a disabled sprite's registers are stale. Then check MCM — multicolor decoded as hires comes out twice as wide. |
 | Computed mode is "INVALID — screen goes black" | You caught the registers mid-update inside a raster split. Re-read. |
 | The emulator looks dead | Enumerate armed checkpoints before anything else. See hazard 2. |
-| `vice_keyboard_type` does nothing | The game polls `$DC00`/`$DC01` directly. Use `vice_keyboard_matrix` (**requires the fork backend** — see `references/observation-hazards.md` § 4 for the stock route). |
+| `vice_keyboard_type` does nothing | The game polls `$DC00`/`$DC01` directly. `vice_keyboard_matrix` is **permanently unavailable** — see `references/observation-hazards.md` § 4 for the reason and the available alternative. |
 | Two captures of the same checkpoint differ | Expected. Full-64K identity is impossible in principle; use `c64-ram-capture`'s drift rules. |

package/skills/c64-program-recon/references/control-flow.md

@@ -1,7 +1,6 @@
 # Control flow: entry point → vectors → IRQ source → main loop → structure
 
-Source: `.planning/RE-FINDINGS.md` § Control-flow discovery method (2026-08-01, **MEDIUM**,
-doc-derived) except where a line says otherwise. The vector-table step was confirmed against
+Graded 2026-08-01, **MEDIUM**, doc-derived, except where a line says otherwise. The vector-table step was confirmed against
 this project's own captures on 2026-08-04 — see the bottom of this file.
 
 ## 1. Entry point — three routes, and post-depack is a different question
@@ -31,7 +30,7 @@ it prints the IRQ/BRK/NMI and hardware blocks by default and takes `--all` for t
 | Hardware vectors | `$FFFA-$FFFF` | NMI, RESET, IRQ/BRK. Live when the KERNAL is banked out |
 
 **The hardware pairs are only live when the ROMs are banked out via `$01`.** The deciding bit is
-HIRAM, `$01` bit 1 (RE-FINDINGS 2026-08-02). HIRAM = 1 ⇒ KERNAL ROM is in and `$0314/$0315` is
+HIRAM, `$01` bit 1 (observed 2026-08-02). HIRAM = 1 ⇒ KERNAL ROM is in and `$0314/$0315` is
 live. HIRAM = 0 ⇒ RAM at `$E000-$FFFF` and `$FFFE/$FFFF` is live.
 
 Why LOAD and STOP earn their own callout on this project: both releases use custom raw-sector
@@ -82,15 +81,13 @@ Run over all six committed captures of one title (two releases, runs 1-3 each):
 
 NMI and RESET sharing one entry is the shape of an anti-tamper trap: RESTORE and reset are the two
 ways a user perturbs a running game, and both land in the same place. `$1116` is therefore the
-address to checkpoint when the emulator is next available — press RESTORE with
-`mcp__plugin_c64-re-tools_vice__vice_keyboard_restore` (it is *not* in the keyboard matrix, and NMI will not retrigger
-until the line is released, so it is a press→release **edge**), then `vice_machine_reset` soft and
-hard, and record where the PC actually lands.
-
-**`vice_keyboard_restore` requires the fork backend.** The RESTORE key pulses the NMI line
-directly and is not part of the keyboard matrix, so stock's `KEYBOARD_FEED` (which only injects
-PETSCII text into the buffer) cannot produce it. Calling it on the stock backend returns an error
-naming the reason and the fork backend, rather than pulsing RESTORE.
+address to checkpoint when the emulator is next available. Testing the RESTORE half of that
+experiment is not currently possible: **`vice_keyboard_restore` is permanently unavailable.** The
+RESTORE key pulses the NMI line directly and is not part of the keyboard matrix, so `KEYBOARD_FEED`
+(which only injects PETSCII text into the buffer) cannot produce it; calling the tool returns an
+error naming the reason, rather than pulsing RESTORE. No client-side substitute exists — see
+`docs/stock-hard-losses.md`. The reset half of the experiment remains testable: arm the checkpoint,
+call `vice_machine_reset` soft and hard, and record where the PC actually lands.
 
 **Evidence:** derived mechanically from six three-run-verified captures; every value identical
 across all three runs of its release, so none of it is drift.
@@ -161,9 +158,9 @@ at a title screen and again in gameplay, diff the two captures, and look for a s
 changed in zero page or low RAM. `vice_memory_compare` narrows this; `c64-ram-capture` § Compare
 two captures gives the volatility rules that stop you chasing drift.
 
-On stock, only `mode: 'ranges'` is served — capture the two states at different points in time and
+Only `mode: 'ranges'` is served — capture the two states at different points in time and
 compare two live ranges. `mode: 'snapshot'` is refused with an explanatory message; there is no
-memory-only snapshot producer on either backend.
+memory-only snapshot producer at all.
 
 ## Verified against this project — 2026-08-04
 
@@ -173,7 +170,7 @@ holding **`$1103`**, while `$0314/$0315` holds `$0101` — nothing meaningful, e
 dormant-block rule predicts.
 
 `$1103` is the same IRQ-handler entry that phase-01 live work independently established, with the
-raster-split chain `$1103 → $1574 → $152C` (RE-FINDINGS 2026-08-02, checkpoint-trap entry). The
+raster-split chain `$1103 → $1574 → $152C` (observed 2026-08-02, on a checkpoint trap). The
 method reproduces a known-good result from a static image with no emulator running. The widened
 sweep's own results, including two facts this table never surfaced, are in §2 above.
 

package/skills/c64-program-recon/references/graphics.md

@@ -1,6 +1,6 @@
 # VIC-II: locating every displayed byte
 
-Source: `.planning/RE-FINDINGS.md` § VIC-II discovery (2026-08-01, **MEDIUM**, doc-derived).
+Graded 2026-08-01, **MEDIUM**, doc-derived.
 
 **Graphics data is computed, not searched.** Every pointer the VIC follows derives from two
 registers plus a bank. Read the bank, read `$D018`, read the mode bits, read `$D015` and the

package/skills/c64-program-recon/references/observation-hazards.md

@@ -5,7 +5,8 @@ this project at real cost. A wrong answer from a register table is cheap; a wron
 machine that changed *because you looked at it* discredits a whole session without announcing
 itself.
 
-Full provenance in `.planning/RE-FINDINGS.md`. Log new hazards there at the moment you hit one.
+Log a new hazard in your own project notes at the moment you hit one — the cost of rediscovering
+one is a whole discredited session.
 
 ## 1. Agent think-time runs the emulator at full speed
 
@@ -59,8 +60,7 @@ bracket, and comes back `wedged`. **The response to `wedged` is recycle, and rec
 instance is the exact loss both the tool and this hazard exist to prevent.** So when a `wedged`
 verdict arrives with any checkpoint still armed, do the two reads by hand before recycling:
 `vice_checkpoint_list`, then resolve the live handler (`$0314/$0315`, or `$FFFE/$FFFF` when `$01`
-has the ROMs banked out). Filed as
-`.planning/todos/pending/2026-08-04-vice-diagnose-checkpoint-trap-shapes-miss-mid-handler-arming.md`.
+has the ROMs banked out). Observed 2026-08-04, and still open.
 
 **Counter-evidence, and why this is MEDIUM:** in one incident, deleting the checkpoint did *not*
 unfreeze the machine, and neither did a soft reset, a hard reset, nor a single step. A checkpoint
@@ -80,19 +80,20 @@ Prefer the whole-chip reads — `vice_vicii_get_state`, `vice_cia_get_state`, `v
 — over raw register reads. Whether the VICE monitor's own read path is side-effect-free is
 **unverified**: treat it as verify-don't-assume rather than taking it on faith.
 
-On the stock backend, `vice_vicii_get_state`/`vice_cia_get_state` reads are `sidefx: false` with
+`vice_vicii_get_state`/`vice_cia_get_state` reads are `sidefx: false` with
 no argument able to override it — **VERIFIED**, asserted on the wire body by a regression test.
 Whether the emulator's own `MEM_GET` read path actually honours that flag for
 `$D01E`/`$D01F`/`$DC0D`/`$DD0D` — i.e. whether it truly cannot clear them — is **ASSUMED**, with
-no probe recorded in this repo; treat it as no worse than the fork's own unverified path, not as
-a proven guarantee. `vice_sid_get_state` is **fork-only**, since SID `$D400-$D418` is write-only
-in hardware and the binary monitor has no SID command. Also: on stock, an internal field the
-register map cannot expose is marked `{ available: false, reason }` in the answer, never a bare
-`0` — do not record a stock `0` from one of these fields as a measurement; check `available`
-first. A stock chip-state or sprite answer also **names the memory view it read** (`bank`, or
+no probe recorded in this repo; treat it as unverified, not as a proven guarantee.
+`vice_sid_get_state` read-back is **permanently unavailable**: SID `$D400-$D418` is write-only
+in hardware and the binary monitor has no SID command, so there is no route to recover it.
+Writes to those addresses still work fine. See `docs/stock-hard-losses.md`. Also: an internal
+field the register map cannot expose is marked `{ available: false, reason }` in the answer, never
+a bare `0` — do not record a `0` from one of these fields as a measurement; check `available`
+first. A chip-state or sprite answer also **names the memory view it read** (`bank`, or
 `registerBank`/`dataBank`), read through the emulator's own `io`/`ram` banks, so it stays valid
 even while the program has I/O banked out ($01 driving the RAM/ROM/I-O switch). An answer with
-**no** bank field — an older transcript, or the fork backend — is suspect whenever `$01` may not
+**no** bank field — an older transcript — is suspect whenever `$01` may not
 have been `$37`: those bytes may be the RAM underneath the I/O area, not registers.
 
 ## 4. The keyboard buffer is not how games read keys
@@ -103,13 +104,14 @@ Games and cracks poll the `$DC00`/`$DC01` matrix directly, bypassing the KERNAL
 `vice_keyboard_type` is invisible to them. Use `vice_keyboard_matrix`, and hold a key across a
 gate by releasing it at the trigger checkpoint, never earlier.
 
-**`vice_keyboard_matrix` requires the fork backend.** The binary monitor's `KEYBOARD_FEED` (0x72)
+**`vice_keyboard_matrix` is permanently unavailable.** The binary monitor's `KEYBOARD_FEED` (0x72)
 only injects PETSCII text into the KERNAL keyboard buffer; the emulator recomputes CIA port B from
 its own keyboard array on every read, so there is no wire command that can drive the raw matrix —
-this is unrecoverable on stock, not merely unbuilt. On stock, use `vice_keyboard_type` /
-`vice_keyboard_petscii` when the gate reads the KERNAL buffer, or `vice_joystick_set` when it polls
-the matrix directly instead; either way, buffer injection is invisible to a program polling
-`$DC00`/`$DC01` itself, so a matrix-polling gate must be driven by the joystick or not at all.
+this is unrecoverable, not merely unbuilt. See `docs/stock-hard-losses.md`. Use
+`vice_keyboard_type` / `vice_keyboard_petscii` when the gate reads the KERNAL buffer, or
+`vice_joystick_set` when it polls the matrix directly instead; either way, buffer injection is
+invisible to a program polling `$DC00`/`$DC01` itself, so a matrix-polling gate must be driven by
+the joystick or not at all.
 
 ## 5. Most state reads pause the emulator and do not resume it
 

package/skills/c64-program-recon/references/reconstruction.md

@@ -43,8 +43,7 @@ at a checkpoint is not verified** — the constraint's own conclusion, and the r
 design is part of the reconstruction work rather than something to bolt on afterwards.
 
 **That bar is what buys you the freedom to rename routines, reorganise files, replace constants
-with symbols and add macros** (`.planning/REQUIREMENTS.md` § Out of Scope makes the same
-argument). **But** reorganising changes addresses, which breaks self-modifying code and
+with symbols and add macros**. **But** reorganising changes addresses, which breaks self-modifying code and
 timing-sensitive raster routines. Replay through the checkpoint set after EACH reorganisation, not
 at the end of several: one changed address per failing replay is a short diagnosis, ten is a
 bisect.

package/skills/c64-program-recon/references/sound-and-input.md

@@ -1,7 +1,6 @@
 # SID and CIA: music, effects, the RNG, input, timing
 
-Source: `.planning/RE-FINDINGS.md` § SID discovery and § CIA 6526 discovery (2026-08-01,
-**MEDIUM**, doc-derived) except where marked. Per-register bit detail lives in
+Graded 2026-08-01, **MEDIUM**, doc-derived, except where marked. Per-register bit detail lives in
 `c64-memory-mapping`; this file carries the idioms and the order.
 
 ## SID — separating the player from the game logic
@@ -61,12 +60,11 @@ One that programs `$DC04-$DC07` and enables timer A runs its own timebase.
 - **Direct `$DC00`/`$DC01` polling is the norm, and it defeats `vice_keyboard_type`.**
   **Evidence: live, established on this project during recovery work. Confidence: HIGH. Cost: an
   afternoon.** Games and cracks bypass the KERNAL keyboard buffer and read the matrix directly.
-  Assume it until shown otherwise, and drive input with `vice_keyboard_matrix` or the joystick
-  tools instead. **`vice_keyboard_matrix` requires the fork backend** — the binary monitor's
-  `KEYBOARD_FEED` only injects PETSCII buffer text and cannot drive the raw matrix. On stock, use
-  `vice_keyboard_type` / `vice_keyboard_petscii` when the gate reads the KERNAL buffer, or
-  `vice_joystick_set` when it polls the matrix directly; buffer injection stays invisible to a
-  program polling `$DC00`/`$DC01` itself.
+  Assume it until shown otherwise. **`vice_keyboard_matrix` is permanently unavailable** — the
+  binary monitor's `KEYBOARD_FEED` only injects PETSCII buffer text and cannot drive the raw
+  matrix; see `docs/stock-hard-losses.md`. Use `vice_keyboard_type` / `vice_keyboard_petscii` when
+  the gate reads the KERNAL buffer, or `vice_joystick_set` when it polls the matrix directly;
+  buffer injection stays invisible to a program polling `$DC00`/`$DC01` itself.
 
 ## Finding input handling from the observable side
 

package/skills/c64-program-recon/references/tool-selection.md

@@ -4,8 +4,7 @@
 call; read parameters off those. What the schemas cannot tell you is *which call to reach for
 first*, and that ordering is the whole value here.
 
-Curated from `.planning/RE-FINDINGS.md`'s tool-to-question entry (2026-08-01, doc-derived,
-**Confidence: MEDIUM** — the mapping is reasoned from the tool surface and this project's own
+Curated 2026-08-01, doc-derived, **Confidence: MEDIUM** — the mapping is reasoned from the tool surface and this project's own
 usage, not measured). Individual rows that have since been exercised live are marked.
 
 | Question | Call |
@@ -14,13 +13,13 @@ usage, not measured). Individual rows that have since been exercised live are ma
 | What does the handler at this vector do? | `vice_disassemble` — the emulator's own decoder, not a dead listing |
 | Is this really the main loop? | `vice_checkpoint_add` + `vice_run_until` + `vice_registers_get` — fires once per frame ⇒ proven |
 | What code writes this? | `vice_watch_add` — finds **writers**. Best targets: `$D018`, VM+`$03F8`, `$D404` |
-| Whole-chip VIC-II/CIA state without the read hazards | `vice_vicii_get_state` / `vice_cia_get_state` (**both backends**) — prefer these over raw register reads |
-| Whole-chip SID state without the read hazards | `vice_sid_get_state` (**requires the fork** — SID `$D400-$D418` is write-only in hardware and the binary monitor has no SID command; unrecoverable on stock) |
-| Decode sprite data | `vice_sprite_get` / `vice_sprite_inspect` (**both backends**) |
-| Find a known byte pattern | `vice_memory_search` (**both backends**) |
-| Carry labels across sessions | `vice_symbols_load` / `vice_symbols_lookup` (**both backends**) — ACME `--vicelabels` emits the format they consume. The annotation store's own export into that format is **withdrawn as of 2026-08-29, and no phase currently owns its return** — an earlier forecast naming a numbered phase for it is superseded |
-| Is the machine wedged, or did it stop itself? | `vice_diagnose` — five-state verdict with its evidence (the two backends' verdict sets differ by one; see `docs/stock-vice-parity.md` D-03). **Reachable and proxy-intercepted as of 2026-08-04** (verified live). Triage tree: `vice-wedge-triage` |
-| Replace a wedged instance | `vice_recycle` — destructive, requires a `reason`, and that reason is written into `.planning/incidents/` **before** anything is killed. The reason *is* the evidence record |
+| Whole-chip VIC-II/CIA state without the read hazards | `vice_vicii_get_state` / `vice_cia_get_state` — prefer these over raw register reads |
+| Whole-chip SID state without the read hazards | `vice_sid_get_state` — **permanently unavailable**: SID `$D400-$D418` is write-only in hardware and the binary monitor has no SID command, so read-back cannot be recovered. Writes to those addresses still work fine over the memory-set primitive. See `docs/stock-hard-losses.md` |
+| Decode sprite data | `vice_sprite_get` / `vice_sprite_inspect` |
+| Find a known byte pattern | `vice_memory_search` |
+| Carry labels across sessions | `vice_symbols_load` / `vice_symbols_lookup` — ACME `--vicelabels` emits the format they consume. The annotation store's own export into that format is **withdrawn as of 2026-08-29, and no phase currently owns its return** — an earlier forecast naming a numbered phase for it is superseded |
+| Is the machine wedged, or did it stop itself? | `vice_diagnose` — five-state verdict with its evidence (one state is `monitor_held_elsewhere`, because this monitor serves exactly one client at a time). **Reachable and proxy-intercepted as of 2026-08-04** (verified live). Triage tree: `vice-wedge-triage` |
+| Replace a wedged instance | `vice_recycle` — destructive, requires a `reason`, and that reason is written into `.c64-re-tools/incidents/` **before** anything is killed. The reason *is* the evidence record |
 | Read the restart epoch | **No tool does.** The proxy compares it around every forwarded call and raises drift itself; a value comes from that error or from `vice_diagnose` |
 
 ## Delegate rather than restate
@@ -32,16 +31,36 @@ usage, not measured). Individual rows that have since been exercised live are ma
 | A verified 64K image, or comparing two captures | the `c64-ram-capture` skill |
 | Whole-program static disassembly with code/data separation | **`anno export-asm`** — withdrawn 2026-08-29, returned 2026-08-31, settled by assembling the output with a real ACME and diffing the bytes against the input. That oracle is test-only, so the verb itself writes source and runs no assembler. For a single routine, read one explicit range at a time with `anno_read_region` / `anno_disassemble` (4096-byte cap per call, refused rather than truncated above it) and record what you verified with `anno_set_data_type` |
 
+## Runtime evidence versus the byte-derived guess
+
+| Question | Call |
+|---|---|
+| Where the store's byte-derived block table (`anno_set_data_type`'s own ranges) disagrees with what the emulator was actually observed executing | **`anno evid-disagreements`** (also `anno_evid_disagreements`) — joins the typed ranges against the runtime-observed rows an `anno_evid_ingest` call already wrote, reporting disagreements first, agreement as a count only, and a never-observed count that is explicitly NOT evidence the address holds data |
+| What evidence a store already holds, without re-running the program | `anno_evid_runs` — every run identity's observation count beside its denominator |
+| Reset one run identity's evidence for a fresh re-measurement | `anno_evid_reset` — clears only that run identity's rows; pair it with `vice_memmap_zap` on the emulator side |
+
+## What blocks this program's code from being moved
+
+| Question | Call |
+|---|---|
+| Which constructions block relocating, rebasing or stripping part of this program | **`anno hazard-report`** (also `anno_hazard_report`) — enumerates movement-hazard findings derived from decoded bytes alone (for example, a store or read-modify-write instruction whose literal target lands on another instruction's opcode or operand byte, changing what runs or what value is read on a later pass). Each finding carries its own detection mechanism and a detection-strength token. Reports and changes NOTHING: it never relocates, strips or rebases anything, and it never emits a flag a caller could act on as an automatic relocation |
+
+**A region this report does not flag is undecided or unflagged, never certified safe to move.** Every checked
+region reports one of exactly three outcomes, and only one of them means a construction was actually found
+there — the other two both mean "nothing this report knows how to look for fired here," which is a fact about
+the detectors, not a guarantee about the bytes. A store through a runtime-computed pointer into the code range
+is a known, named miss: this report cannot see it, and its absence from the findings is not evidence that no
+such construction exists. Use this alongside, never instead of, the runtime-evidence and provenance-diff
+routes above and in the sibling skills — a region with no finding still needs a human decision before it is
+moved.
+
 ## Three traps in this table
 
-**`vice_run_until`'s timeout is backend-qualified — it has none on the fork, but stock bounds it
-(Phase 7, D-02).** On the fork, `cycles` is documented as *"not yet implemented"* and there is no
-`timeout_ms` either, so a run to an address the program never reaches has nothing to bound it and
-looks exactly like a wedged emulator; prefer `vice_checkpoint_add` + a bounded poll when the
-address is a hypothesis rather than a certainty. **Confidence: MEDIUM on the fork** — read off the
-schema, not reproduced. On stock, `timeout_ms` (default 30000, ceiling 600000) bounds the wait, and
-a timed-out answer says the machine is left halted rather than looking like a wedge — see
-`vice-wedge-triage` for the full triage judgement and its live evidence; do not restate it here.
+**`vice_run_until`'s `timeout_ms` bounds the wait.** `timeout_ms` (default 30000, ceiling 600000)
+bounds a run to an address the program never reaches, and a timed-out answer says the machine is
+left halted rather than looking like a wedged emulator; prefer `vice_checkpoint_add` + a bounded
+poll when the address is a hypothesis rather than a certainty — see `vice-wedge-triage` for the
+full triage judgement and its live evidence; do not restate it here.
 
 **`vice_diagnose` leaves the machine paused.** When it measures a cycle bracket it resumes the
 machine once or twice and then leaves it **paused** — resuming is your own next call. And a