@henols/c64-re-tools 0.1.4

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

@@ -0,0 +1,172 @@
+---
+name: c64-program-recon
+description: Work out how an unknown C64 program is structured at runtime — entry point, interrupt handlers, main loop, game states, graphics and sound — in a fixed order, before disassembling anything. Use when asked to reverse engineer a C64 game, find the main loop, entry point or IRQ handler, locate the player sprite, charset or music player, identify a game state machine, work out which memory regions are code versus data, or decide where to start on a depacked image.
+---
+
+# Reconnaissance on an unknown C64 program
+
+**Do not disassemble the whole program first.** The structure hangs off a small fixed set of
+well-known addresses: read them in order and the answer falls out. Treated as a search problem it
+costs an hour every session; written down it is minutes.
+
+Build a network of confirmed facts. Once the vectors, the IRQ handler, the main loop and the major
+tables are known, everything else classifies far more easily.
+
+```bash
+D=.claude/skills/c64-program-recon/scripts/derive.mjs   # from the repo root
+
+node $D vectors dump.bin                                # $01 + six vectors, which pair is live
+node $D vic --dd00 3E --d018 18 --d011 1B --d016 C8     # bank, screen, charset, mode
+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.
+
+## The order
+
+Each step is a read whose answer rules something out. Do not skip ahead: step 6 is cheap once the
+handler is known, because that is where most chip writes happen.
+
+| # | Question | Read | What the answer settles |
+|---|---|---|---|
+| 0 | Which of these bytes are even the game? | The manifest's buckets — `c64-provenance-diff` | Tracing a depacker's IRQ handler is wasted work. Scope before you trace |
+| 1 | Where does execution start? | Post-depack: wherever the PC sits at the decrunch checkpoint. There is no BASIC stub to find. | The one address everything else hangs off |
+| 2 | Which vector is live? | `$01`, then `$0314/$0315` **or** `$FFFE/$FFFF` | HIRAM (`$01` bit 1) decides. KERNAL out ⇒ the RAM vectors are meaningless |
+| 3 | What drives the frame? | `$D01A`, `$D012`, `$DC0D` | `$DC0D` untouched ⇒ raster IRQ; programmed ⇒ the game runs its own timebase |
+| 4 | Where is the main loop? | Checkpoint a suspected loop head, run one frame | Two shapes only: a real loop, or a two-instruction spin with the IRQ doing everything |
+| 5 | Code or data? | What the PC actually visits across full coverage | A range never executed is data, whatever a tracer guessed |
+| 6 | Where is the graphics? | `$DD00` → `$D018` → mode bits → `$D015` → VM+`$03F8` | Every displayed byte, computed. Nothing to search for |
+| 7 | Where is the music? | Watch `$D404` | `init` runs once from main code; `play` runs once per frame from the IRQ |
+| 8 | Where is the input? | Reads of `$DC00`/`$DC01` | Games poll the matrix directly and ignore the KERNAL buffer |
+
+## Step 0 in full: only the game is in scope
+
+Every image taken from a cracked release carries three layers that are **not the game**, and no
+original master exists to strip them for you:
+
+| Layer | What it is | Dead when |
+|---|---|---|
+| **loader** | The custom raw-sector routine that bypasses the KERNAL | The payload is in RAM |
+| **cruncher / depacker** | The decompression stub | It has run once |
+| **cracktro** | The group's intro, scroller, credits, and the keypress gate that dismisses it | Dismissed |
+
+**The rule: a byte with nothing to do with the game is out of scope — always, not case by case.**
+It is not annotated, not reconstructed, and not traced. This is a standing default, not a
+per-session decision.
+
+**The evidence bar runs both ways, and this project has been burned in both directions.**
+
+- Removal needs *positive* evidence of the bucket: a crack-credit vocabulary match, a
+  `RELEASES.json` `loader_ranges` entry earned from live disassembly, or a depacker stub provably
+  dead after first run. A bare printable-ASCII scan classified **the game's own title text** as
+  cracktro credit and would have shipped a confidently-wrong `CRACKER-PATCH` verdict.
+- Absence of evidence records `UNKNOWN` and **keeps the bytes**. The
+  a real title-screen text divergence was found sitting in a region that is neither loader nor
+  cracktro — a cracker edit inside the game's own data. Stripping only the obvious intro screen
+  leaves crack residue behind.
+
+`c64-provenance-diff` owns the machinery and the five kinds; do not re-derive them here. What
+belongs here is the ordering: **bucket first, then trace only what survives.**
+
+Then work **backwards from observable effects** rather than reading code sequentially — it is
+consistently faster. Watch writes to the sprite coordinates to find movement; watch `$D018` to find
+the room loader; watch VM+`$03F8` to find the animation driver. `vice_watch_add` finds *writers*,
+and that is its real leverage.
+
+Differential experiments close the loop: patch a routine to `RTS` and see what stops. If enemies
+freeze and nothing else does, the routine's purpose is confirmed — far stronger evidence than
+reading the listing.
+
+## Worked example — a real capture
+
+```
+$ node $D vectors capture.bin
+$01 = $40 %01000000
+  bit 0 LORAM  = 0  BASIC ROM  out (RAM at $A000-$BFFF)
+  bit 1 HIRAM  = 0  KERNAL ROM out (RAM at $E000-$FFFF)
+  bit 2 CHAREN = 0  character ROM at $D000-$DFFF
+
+LIVE VECTOR PAIR: $FFFE/$FFFF (KERNAL banked OUT — the hardware vectors are live)
+CBM80 SIGNATURE:  absent — nothing catches a reset here
+
+## KERNAL IRQ/BRK/NMI ($0314-$0319)
+   DORMANT: KERNAL ROM banked out — nothing maintains these. Read it, do not act on it.
+vector        value   default   status
+$0314/$0315  $0101   $EA31   *** RETARGETED ***
+              CINV  — KERNAL IRQ (RAM, indirect)
+…
+## Hardware vectors ($FFFA-$FFFF) — live when the KERNAL is banked out
+$FFFA/$FFFB  $1116     --     no default
+$FFFC/$FFFD  $1116     --     no default
+$FFFE/$FFFF  $1103     --     no default
+
+Non-default bytes in DORMANT blocks: 17. These are NOT diverted
+vectors. …
+```
+
+Read it as: the KERNAL is banked out, so the whole `$0300-$0333` range is **dormant** and `$0314`'s
+`$0101` is residue, not a retargeted vector — ignore it. The live handler is `$1103`, and that is
+where to arm the first checkpoint. `$FFFA` and `$FFFC` both holding `$1116` says the game installs
+its own NMI *and* RESET handlers, at one shared address.
+
+Both cracked releases give the same answers across all three of their captures, and `$1103` is the
+same IRQ entry that phase-01 live work established independently (chain `$1103 → $1574 → $152C`).
+The method reproduces a known-good result from a static image with no emulator running, and the
+`$1116` pair is new — see `references/control-flow.md` § 2. **Confidence: HIGH** for steps 1-2.
+
+## Before you touch the emulator
+
+Two hazards cost this project real sessions. Both are in `references/observation-hazards.md`; these
+two lines are the part you cannot afford to load lazily.
+
+- **Pause after every observation.** Agent think-time runs the emulator at full speed — 258 million
+  cycles (~262 emulated seconds) elapsed across a handful of reads with zero input sent, which was
+  enough to reach `GAME OVER` and to invalidate an earlier finding. Never leave the machine running
+  across a reasoning step.
+- **When the machine looks frozen, enumerate your own checkpoints first.** An armed *stopping*
+  checkpoint on the live IRQ path reproduces the entire "dead emulator" signature — zero cycles,
+  `ping` still reporting `running`, an identical PC — because the machine genuinely never moved.
+  Two cheap reads settle it, and neither needs `vice_execution_run`.
+
+## Which skill does what
+
+This one is the route between the stations. It does not restate what the others carry.
+
+| Need | Go to |
+|---|---|
+| 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, or a first-pass dead listing | `acme-build` |
+| Whether a byte is original or cracker-changed | `c64-provenance-diff` |
+| The emulator stopped moving — wedged, self-trapped, or respawned | `vice-wedge-triage` |
+| **Which address to read next, and what the answer rules out** | here |
+
+## References
+
+| File | Covers |
+|---|---|
+| `references/control-flow.md` | Entry point, the six vectors, IRQ source, main-loop shapes, state machines |
+| `references/graphics.md` | The VIC derivation chain, the char-ROM shadow trap, sprites, watch targets |
+| `references/sound-and-input.md` | SID player vs `$D41B`-as-RNG vs digi; CIA#1 vs CIA#2 |
+| `references/observation-hazards.md` | Every way a live read gives a wrong answer. **Read before driving.** |
+| `references/tool-selection.md` | Which `mcp__plugin_c64-re-tools_vice__*` call answers which question, and what to delegate |
+| `references/reconstruction.md` | Binary inclusion, behavioural-equivalence correctness bar, SMC labels, label vocabulary |
+| `templates/memory-map.template.md` | Region map with per-row confidence grading |
+
+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`).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `$0314` holds something that is not a plausible address | Check HIRAM. With the KERNAL banked out the RAM vectors are uninitialised; read `$FFFE/$FFFF`. |
+| Every graphics pointer is wrong, with no error | `$DD00` bits 0-1 are **inverted**. Re-derive the bank first; everything else hangs off it. |
+| The charset at the computed address is garbage | CB may resolve into the char-ROM shadow (`$1000`/`$9000`, banks 0/2). `derive.mjs vic` flags it — there is no charset in RAM to extract. |
+| 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`. |
+| 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

@@ -0,0 +1,174 @@
+# 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
+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
+
+| Situation | Where the entry point is |
+|---|---|
+| BASIC stub at `$0801` | A tokenized `SYS <addr>` line. The address is plain PETSCII digits in the stub, so it reads straight out of the load image with no interpretation. |
+| Autostart / non-BASIC | The `.prg` load address (first two bytes), the RESET vector at `$FFFC/$FFFD`, or a cartridge CBM80 signature at `$8000`. |
+| **Post-depack — this project's case** | Wherever the PC sits when the decrunch checkpoint fires. A different question with a different answer. |
+
+For a depacked image there is no BASIC stub to find. Do not spend time looking for one.
+`c64-ram-capture` § Find an entry point gives the live procedure: step in batches until PC and
+SP settle into a repeating range across three consecutive batches.
+
+## 2. Vectors — sweep every block, and `$01` decides which are live
+
+Six pairs is not "all vectors". `node derive.mjs vectors <image.bin>` sweeps all six blocks below;
+it prints the IRQ/BRK/NMI and hardware blocks by default and takes `--all` for the rest.
+
+| Block | Range | Why it matters |
+|---|---|---|
+| BASIC indirects | `$0300-$030B` | IERROR, IMAIN, ICRNCH, IQPLOP, IGONE, IEVAL — a program returning to a modified BASIC prompt hooks these |
+| KERNAL IRQ/BRK/NMI | `$0314-$0319` | CINV `$EA31`, CBINV `$FE66`, NMINV `$FE47`. The per-frame handler, and the pair music players retarget |
+| KERNAL I/O indirects | `$031A-$0333` | OPEN…SAVE. **`$0328` STOP and `$0330`/`$0332` LOAD/SAVE are where a cracker hooks** |
+| Autostart / cartridge | `$8000` cold, `$8002` warm, `$8004` `CBM80` | The standard survive-a-reset trick. Without the signature the KERNAL ignores both words |
+| BASIC ROM entry | `$A000/$A002` | Only meaningful with BASIC banked in — check `$01` LORAM first |
+| 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
+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
+loaders that bypass the KERNAL, so a diverted `$0330` is a provenance signal, and a diverted
+`$0328` is anti-tamper. Neither was being looked for before 2026-08-04.
+
+The second tell is the handler's own first instruction: the KERNAL's register-save preamble means
+the KERNAL path is in use; a jump straight into game code means it is not.
+
+### A non-default value in a dormant block is not a hook
+
+**A garbage-looking `$0314` is not a bug when HIRAM = 0.** With the KERNAL banked out, nothing
+maintains the RAM vectors and they hold whatever was last there — usually the KERNAL's own
+boot-time values, partly overwritten. `derive.mjs` labels each such block `DORMANT` and reports
+its non-default bytes as *residue*, never as a divert, because reading a hook into residue is the
+fastest way to a confidently-wrong structural claim.
+
+A residue byte that **differs between two releases** is still worth something — but it is a
+provenance question, not a structural one. Take it to `c64-provenance-diff`.
+
+### A target in a ROM window is unresolved until you read it twice
+
+A vector target in `$A000-$BFFF`, `$D000-$DFFF` or `$E000-$FFFF` is *either* ROM *or* the RAM
+underneath, decided by `$01` at the moment the vector is taken. `derive.mjs` marks these
+`bank-ambiguous` and stops there, because a static image cannot settle it.
+
+Live, it is one extra call: read the target with `mcp__plugin_c64-re-tools_vice__vice_memory_read`'s default bank,
+then again with `bank: "ram"`, and compare (`vice_memory_banks` lists what is available). Agreeing
+with stock ROM bytes ⇒ the vector genuinely lands in ROM and the KERNAL path is in use. Differing
+⇒ **the program has its own code hidden under ROM**, which is a large structural finding and is
+otherwise not looked for at all. Record the stock bytes you compared against, so the check is
+reproducible.
+
+This supersedes the weaker "check `$01` and read the handler's preamble" tell, which silently
+reads whichever bank happens to be mapped.
+
+### What the widened sweep found here — 2026-08-04
+
+Run over all six committed captures of one title (two releases, runs 1-3 each):
+
+| Vector | release-a | release-b | Reading |
+|---|---|---|---|
+| `$FFFE/$FFFF` IRQ | `$1103` | `$1103` | Known; matches the live-established handler chain |
+| `$FFFA/$FFFB` NMI | `$1116` | `$1116` | **New.** The game installs its own NMI handler under KERNAL ROM |
+| `$FFFC/$FFFD` RESET | `$1116` | `$1116` | **New.** RESET funnels to the *same* address as NMI |
+| `$0328/$0329` ISTOP | `$F6FC` | `$F6ED` (stock) | **New, and a divergence.** Residue — the block is dormant |
+| `$8004` `CBM80` | absent | absent | Nothing catches a reset via the cartridge route |
+
+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.
+
+**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.
+**Confidence:** HIGH for the values and for the cross-release divergence. The *interpretation* of
+`$1116` as anti-tamper is **LOW** — unexercised, and the perturbation experiment above is exactly
+what would settle it.
+
+## 3. IRQ source — two enable masks close the question
+
+- **Raster IRQ** — `$D012` (raster compare), `$D011` bit 7 (raster bit 8), `$D01A` (IRQ enable
+  mask), `$D019` (latch, which the handler must acknowledge). **A handler that writes a new
+  `$D012` on its way out is a split raster chain**, and each such write is one more IRQ position
+  to enumerate.
+- **CIA timer IRQ** — `$DC0D` (CIA#1, drives IRQ) and `$DD0D` (CIA#2, drives NMI), with
+  `$DC04-$DC07` / `$DD04-$DD07` for the periods.
+
+A game that never touches `$DC0D` is on a raster IRQ. One that programs `$DC04-$DC07` and enables
+timer A has its own timebase. Read the two enable registers before reading any handler code.
+
+## 4. Main loop — decide the shape before hunting
+
+- **Real main loop** — an unconditional backward branch or `JMP` to a nearby earlier address that
+  never returns, usually preceded by a frame-sync wait: polling `$D012` for a fixed raster line, or
+  spinning on a flag the IRQ handler sets.
+- **IRQ-does-everything** — the main loop is a two-instruction spin and all logic hangs off the
+  raster IRQ. Common enough that assuming the first shape wastes the search.
+
+**The honest test is live, not static.** The address that repeats exactly once per frame in an
+execution trace is the main loop, whatever the listing suggests.
+
+## 5. Four structural features a linear disassembler gets wrong
+
+- **Jump tables and dispatch** — `JMP ($xxxx)` and `JSR` into an indexed table. This is where game
+  state machines live, and exactly what a linear decoder mis-decodes.
+- **Self-modifying code** — writes into `$0800-$CFFF` from code that also executes there. Common
+  for animation frame pointers.
+- **Zero page** — the game's hot variables. The highest-frequency ZP addresses in a trace are the
+  state worth naming first.
+- **Code/data separation** — the project's standing rule (`.claude/CLAUDE.md` § Stack Patterns): a
+  range never hit as an instruction stream across full gameplay coverage is data, regardless of
+  what the tracer guessed. The provenance diff between the two cracked releases is the second check
+  on the same question.
+
+## Finding the state machine
+
+Most games have one even when it is not explicit. Two shapes:
+
+```asm
+    LDA GameState        ; indexed dispatch — the common shape, and the one
+    ASL                  ; a linear disassembler turns into nonsense
+    TAX
+    LDA StateTable,X
+    STA JumpVector+1
+    LDA StateTable+1,X
+    STA JumpVector+2
+JumpVector:
+    JMP $FFFF            ; operand is patched at runtime
+```
+
+```asm
+    LDA GameState        ; compare chain — easier to read, easier to find
+    CMP #STATE_TITLE
+    BEQ TitleState
+```
+
+Finding the state variable gives a high-level map of the whole program. A practical route: pause
+at a title screen and again in gameplay, diff the two captures, and look for a single byte that
+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.
+
+## Verified against this project — 2026-08-04
+
+Running `derive.mjs vectors` cold on both releases' `*-gameentry-run1.bin` returns `$01` = `$40`
+(LORAM 0, HIRAM 0, CHAREN 0 — KERNAL and BASIC banked out), so the live pair is `$FFFE/$FFFF`,
+holding **`$1103`**, while `$0314/$0315` holds `$0101` — nothing meaningful, exactly as the
+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
+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.
+
+**Evidence:** derived mechanically from three-run-verified captures, cross-checked against a live
+finding recorded independently.
+**Confidence:** HIGH for the vector-table step, the HIRAM rule, and the dormant-block rule. The
+remaining steps in this file stay MEDIUM until exercised the same way.

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

@@ -0,0 +1,73 @@
+# VIC-II: locating every displayed byte
+
+Source: `.planning/RE-FINDINGS.md` § VIC-II discovery (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
+sprite pointer block, and you have located every byte of graphics on screen. Searching memory for
+something the hardware will tell you the address of is the single largest time sink in graphics RE.
+
+`node derive.mjs vic` and `node derive.mjs sprites` do the arithmetic. For what any individual bit
+*means*, use `c64-memory-mapping` — it carries the full `$D018` and `$DD00` value tables, and this
+file deliberately does not restate them.
+
+## The order, and why it is this order
+
+1. **`$DD00` bits 0-1 — the VIC bank. Read this first, every time.** The bits are **inverted**
+   (`%11` → bank 0 at `$0000`, `%00` → bank 3 at `$C000`). Every other pointer is relative to this
+   base, so getting it wrong corrupts the whole chain **silently, with no error to signal it**.
+   This is the most common source of a wrong answer in C64 graphics RE.
+2. **`$D018` — two pointers in one byte.** Bits 4-7 = VM (screen RAM = bank + VM × `$0400`);
+   bits 1-3 = CB (charset = bank + CB × `$0800`). In bitmap mode only bit 3 matters: which 8K half
+   of the bank the bitmap occupies, and the video matrix then holds colour pairs rather than
+   character codes.
+3. **The mode bits** — `$D011` bit 6 (ECM), `$D011` bit 5 (BMM), `$D016` bit 4 (MCM). These decide
+   what the bytes *mean*; decoding a multicolor sprite as hires produces garbage twice as wide as
+   it should be. ECM combined with BMM or MCM is invalid and blanks the screen — if you compute
+   that, you probably caught the registers mid-update inside a raster split, so re-read.
+4. **`$D015` — the sprite enable mask. Start here, not at the sprite data.** A disabled sprite's
+   other registers are stale and decoding them yields noise.
+5. **Sprite pointers at video matrix + `$03F8`**, 8 bytes. Each pointer × 64 = the sprite's data
+   address *within the current bank*. 63 bytes used of the 64 allocated.
+
+## The hazard that costs an hour
+
+**The character ROM shadow.** The VIC sees character ROM at `$1000-$1FFF` (bank 0) and
+`$9000-$9FFF` (bank 2) **regardless of the `$01` banking the CPU sees**. If CB resolves into
+either window, the game is using ROM characters and there is no charset in RAM to extract.
+`derive.mjs vic` flags this explicitly. Check it before dumping anything.
+
+## Colour is not banked
+
+Colour RAM is fixed at `$D800-$DBFF` and does **not** move with the VIC bank. Only the low nybble
+of each byte exists. `$D020` is the border, `$D021-$D024` backgrounds 0-3 (2 and 3 used only in
+ECM). Looking for colour data at a bank-relative address finds something else entirely.
+
+## Two watch targets that find the two highest-value routines
+
+`vice_watch_add` finds **writers**, and that is its real leverage in RE — it is under-used relative
+to reading memory.
+
+| Watch | Finds |
+|---|---|
+| `$D018` | The screen-setup routine. In a room- or level-based game this is usually the room loader — one of the highest-value routines to locate early. |
+| video matrix + `$03F8` | The animation driver. Rewriting sprite pointers frame to frame is exactly what it does. |
+
+## Reading collision registers changes the game
+
+`$D01E` (sprite-sprite) and `$D01F` (sprite-background) **clear when read**. Reading them while the
+game runs steals the collision the game was about to act on — the worst class of observation bug,
+because it discredits the capture without announcing itself. Prefer `vice_vicii_get_state`.
+
+Whether the VICE monitor's own read is side-effect-free is **unverified** — treat it as
+verify-don't-assume, not as a settled fact.
+
+Many games do software collision anyway: look for coordinate subtraction, comparisons against
+width and height, tile lookups, mask tables and bounding-box arithmetic before concluding the
+hardware registers are what the game uses.
+
+## Sprite decoding
+
+`vice_sprite_get` / `vice_sprite_inspect` do the pointer arithmetic and the multicolor bit-pair
+unpacking. Verify what they return once against a hand-resolved pointer — `derive.mjs sprites`
+gives you that hand resolution — then trust them.

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

@@ -0,0 +1,118 @@
+# Hazards: how observing a running C64 gives you the wrong answer
+
+The entries here are graded higher than the method files, because most were established live on
+this project at real cost. A wrong answer from a register table is cheap; a wrong answer from a
+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.
+
+## 1. Agent think-time runs the emulator at full speed
+
+**Evidence: live, 01-04 attempt 5. Confidence: HIGH (measured, then reproduced with a control).**
+
+Between one screenshot and the next — a handful of memory/register reads, **zero input sent** —
+a game ran through an interstitial to `GAME OVER`. `vice_cycles_stopwatch` read **258,504,308**
+cycles since the previous action: roughly **262 seconds of emulated PAL time**, all of it real
+unattended execution while the agent composed tool calls.
+
+This invalidated a previously recorded gameplay-hazard conclusion. A "counter that depletes per
+input event" was really a counter depleting during the agent's own reasoning latency, and the
+earlier finding had no way to rule that out because it never paused either.
+
+**The discipline:** call `vice_execution_pause` immediately after every observation that is not
+immediately followed by a deliberate scripted input. Resume only for the bounded duration of that
+input. **Never leave the machine running across a reasoning step.**
+
+Two confirmations from the same session: a pause takes effect only once actually processed (the
+counter climbed another ~20M cycles before settling), but once landed it holds solidly — two
+consecutive stopwatch reads returned an identical value. And with the discipline held from the
+first frame, a room previously judged impassable across six attempts was crossed on the next try.
+
+## 2. An armed stopping checkpoint can look exactly like a dead emulator
+
+**Evidence: cross-read of three recorded incidents, 3/3 correlation. Confidence: MEDIUM — the
+mechanism is consistent with every symptom and testable in minutes, but has not been reproduced.**
+
+The common factor across three "silent stall" incidents was not an address. It was: **a stopping
+exec checkpoint was armed, and execution was resumed.**
+
+The signature is complete and self-consistent — the cycle bracket reads exactly `0`, `vice_ping`
+answers `execution: "running"` because VICE's flag flips before the trap fires, and
+`vice_registers_get` returns a byte-identical PC every time **because the machine genuinely never
+moved.** The strongest single tell: in one incident `vice_checkpoint_list` reported the checkpoint
+at `hit_count: 0` after multiple resume/poll cycles, on an IRQ-driven screen where its address
+*must* execute every frame.
+
+**`mcp__plugin_c64-re-tools_vice__vice_diagnose` now performs this check for you** (2026-08-04): it enumerates armed
+checkpoints, reads the PC, resolves the live IRQ handler through `$01`, and returns a
+`checkpoint_trap` verdict — with **no resume and no stopwatch call**, which matters because
+`vice_execution_run` is this project's leading crash suspect. Call it before anything else. The
+triage decision tree around it is `vice-wedge-triage`.
+
+**Know the two shapes it matches, because a trap outside them reads as a wedge.** It fires when an
+enabled stopping exec checkpoint sits *exactly* at the current PC, or at the resolved handler
+entry with `hit_count` exactly `0`. This hazard's own evidence describes the PC as pinned "at or
+just past" the checkpoint — *just past* is not *exactly at*. A checkpoint armed mid-handler rather
+than at its entry, with a non-zero hit count, matches neither shape, falls through to the cycle
+bracket, and comes back `wedged`. **The response to `wedged` is recycle, and recycling a healthy
+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`.
+
+**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
+trap may be the *onset* without being the whole story. Do not assume delete-and-resume recovers it.
+`vice_diagnose`'s own `checkpoint_trap` report states this too, and cites the same incident.
+
+**This is not a reason to stop arming checkpoints on IRQ handlers** — that is core technique. It
+is a reason to enumerate what you armed *first* whenever the machine looks frozen, before
+concluding the emulator died.
+
+## 3. Registers that clear when you read them
+
+`$D01E`, `$D01F` (VIC collisions) and `$DC0D`, `$DD0D` (CIA interrupt flags) clear on read.
+Reading one while the game runs steals the event the game was about to service.
+
+Prefer the whole-chip reads — `vice_vicii_get_state`, `vice_cia_get_state`, `vice_sid_get_state`
+— 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.
+
+## 4. The keyboard buffer is not how games read keys
+
+**Evidence: live. Confidence: HIGH. Cost: an afternoon.**
+
+Games and cracks poll the `$DC00`/`$DC01` matrix directly, bypassing the KERNAL buffer, so
+`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.
+
+## 5. Most state reads pause the emulator and do not resume it
+
+Read all state first, poll with `vice_ping` (the non-pausing poll), and resume **exactly once** at
+the end. `vice_ping`'s `execution` field is **not** a liveness signal — see hazard 2 for why it
+reports `running` on a machine that is not moving. The only trustworthy liveness test is a cycle
+bracket.
+
+## 6. The machine can be replaced under you
+
+A crash-and-respawn mid-session means the run is void — `c64-ram-capture` § Void a run gives the
+procedure. A successful retry after an auto-restart may be talking to a blank machine.
+
+**You do not poll for this, and no exposed tool reads the epoch.** The proxy compares it before and
+*after* every forwarded call and raises a loud error naming both values, then re-baselines so the
+session stays usable. The two recorded incidents surfaced exactly that way and self-healed on the
+next call. Where an epoch value is needed for a record, it comes from that error text or from
+`vice_diagnose`'s `restarted` report — there is no `vice_epoch_get`.
+
+What is still yours to do: **treat every post-drift read as a fresh machine, never as a resume
+point.** Reboot from `vice_disk_attach`. Two crashes in ~20 minutes of continuous live work is a
+real measured rate, so plan a live session to tolerate re-deriving a boot sequence more than once.
+
+## 7. Full-64K byte-identity is impossible in principle
+
+Never-written RAM drifts continuously, so two captures of the same checkpoint will not match
+across all 64K. The recovery procedure is deterministic **for the program image**, not for 64K.
+`c64-ram-capture` § Compare two captures carries the volatility regions and the drift
+discriminator; use them rather than treating any difference as a divergence.

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

@@ -0,0 +1,128 @@
+# Turning findings into ACME source
+
+Do not wait until everything is understood. Stand up a buildable tree early, include the
+unidentified bulk as binary, and replace regions with real source as they are confirmed. The tree
+stays assemblable at every commit, so a regression has a small blast radius.
+
+`acme-build` covers assembling; this file covers the shape of the source and what makes a
+reconstruction correct.
+
+## Start with binary inclusion
+
+```asm
+* = $4000
+!binary "unknown_4000_5fff.bin"
+```
+
+Then replace piece by piece, keeping the addresses fixed:
+
+```asm
+* = $4200
+
+UpdatePlayer:
+    ; reconstructed code
+```
+
+A layout that keeps this workable:
+
+```
+src/
+  main.a          zeropage.a      irq.a
+  input.a         player.a        enemies.a
+  collision.a     graphics.a      music.a
+  data/
+    sprites.a     levels.a        text.a
+```
+
+## Behavioural equivalence is this project's definition of correctness
+
+**Correctness here means scripted replay plus comparison at checkpoints — nothing else**
+(`.claude/CLAUDE.md` § Constraints). A reconstruction is right when driving it through the
+checkpoint set produces the same observable behaviour as the original. **Anything not observable
+at a checkpoint is not verified** — the constraint's own conclusion, and the reason checkpoint
+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
+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.
+
+A full 64K RAM capture is not a comparison surface: never-written RAM drifts continuously, so
+full-64K identity is impossible in principle (`observation-hazards.md` § 7).
+
+## Self-modifying code needs explicit labels
+
+A static disassembler sees `LDA $FFFF,X` and cannot know the operand is written at runtime:
+
+```asm
+    LDA SourceAddress
+    STA CopyLoop+1
+    LDA SourceAddress+1
+    STA CopyLoop+2
+CopyLoop:
+    LDA $FFFF,X
+    STA $0400,X
+```
+
+Name the patched location so the intent survives:
+
+```asm
+CopySource = CopyLoop + 1
+```
+
+Look for writes to the byte after an opcode, the two bytes after a `JMP`/`JSR`, branch operands
+and immediate constants — `STA Routine+1`, `STX Routine+2`, `INC Routine+1`.
+
+## Label vocabulary: name from evidence, promote on confirmation
+
+Provisional names that carry their own uncertainty beat confident names that turn out wrong:
+
+| Prefix | Means |
+|---|---|
+| `ZP_` | unknown zero-page variable |
+| `State_` | state variable |
+| `Flag_` | boolean or bit field |
+| `Counter_` | counter |
+| `Ptr_` | pointer |
+| `Table_` | lookup table |
+| `IRQ_` | interrupt routine |
+| `Maybe_` | plausible but unconfirmed |
+| `Unknown_` | no reliable interpretation yet |
+
+`Routine_43A2` → `Maybe_UpdatePlayer` → `UpdatePlayerPosition`, promoted only when behaviour is
+confirmed. Avoid `AmazingCollisionRoutine`-style names entirely; they encode a guess as a fact.
+
+Record the confidence next to the thing, in the same grammar the project uses everywhere else:
+
+```asm
+; Confirmed: decremented once per frame while the player is invulnerable.
+; Evidence: live, watch on $D015 during damage. Confidence: HIGH.
+PlayerInvulnerabilityTimer:
+    !byte 0
+```
+
+## Data tables a linear disassembler destroys
+
+The split low/high address table is the classic:
+
+```asm
+AddressLo:  !byte <Room0, <Room1, <Room2
+AddressHi:  !byte >Room0, >Room1, >Room2
+```
+
+Without recognising the pair, a disassembler shows meaningless instructions. Other data tells:
+referenced through indexed loads, repeated byte patterns, valid PETSCII or screen codes,
+sprite-sized 64-byte blocks, values matching VIC-II coordinates.
+
+Code tells: reachable through `JSR`/`JMP`/branches/vectors, **executes during tracing**, plausible
+control flow. The project's standing rule settles ties — a range never hit as an instruction
+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.