@henols/c64-re-tools 0.2.1 → 0.2.3

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.
@@ -122,7 +121,13 @@ stream across full gameplay coverage is data, whatever the tracer guessed.
 
 ## Labels round-trip through VICE
 
-ACME's `--vicelabels` output and regenerator2000's exported label files share one format, which
-`vice_symbols_load` / `vice_symbols_lookup` consume. Labels therefore flow
-disassembler → source → build → debugger without translation. `acme-build` emits the `.vs` file on
-every build; load it after each one and your checkpoints carry real names.
+ACME's `--vicelabels` output is the `al C:xxxx .Name` format `vice_symbols_load` /
+`vice_symbols_lookup` consume, so labels flow source → build → debugger without translation.
+`acme-build` emits the `.vs` file on every build; load it after each one and your checkpoints carry
+real names.
+
+**The other direction — exporting the annotation store into that same 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: that phase covered the ACME export oracle only). So a name discovered live
+goes into the store with `anno_set_label_name` first (the store is the merge point) and reaches the
+emulator only through a `.lbl` you produce yourself.

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` and regenerator2000 output share this channel |
-| 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
@@ -30,18 +29,38 @@ usage, not measured). Individual rows that have since been exercised live are ma
 | What does address X mean? | the `c64-memory-mapping` skill — `node … lookup '$D018'`. **Do not restate its tables.** |
 | Is this byte original or cracker-changed? | the `c64-provenance-diff` skill |
 | A verified 64K image, or comparing two captures | the `c64-ram-capture` skill |
-| Traced disassembly with code/data separation | regenerator2000, via `vice-mcp r2000 export-asm` — a recursive-descent disassembler with an auto-analyzer; verified live: its `--verify` run reassembled byte-identically through a real ACME for both a `.prg` and a flat 64K image (`.planning/phases/10-adoption-boundaries-automated-bootstrap-and-the-removal/evidence/10-verify-transcript.txt`) |
+| 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