@henols/c64-re-tools 0.2.1 → 0.2.3

package/skills/c64-program-recon/templates/memory-map.template.md

@@ -1,28 +1,42 @@
 # Memory map generation
 
-**The memory map is GENERATED, not hand-authored (D-24).** The store — labels, comments, block
-types and scopes written through the `r2000_*` tools described in `../SKILL.md` — is canonical. This
+**The memory map is GENERATED, not hand-authored.** The store — labels, comments, block
+types and scopes written through the `anno_*` tools described in `../SKILL.md` — is canonical. This
 file used to be a fill-in-the-rows document; it is now the schema for the one input the generator
 needs beyond the store itself, plus the confidence vocabulary that store comments carry.
 
 Run the generator once findings are in the store:
 
 ```bash
-npx -y @henols/vice-mcp r2000 render-memmap game.regen2000proj --provenance sidecar.json
-node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 render-memmap game.regen2000proj --provenance sidecar.json
+npx -y @henols/vice-mcp anno render-memmap game.annostore --provenance sidecar.json
+node <plugin-root>/src/mcp/vice/vice-proxy.ts anno render-memmap game.annostore --provenance sidecar.json
 ```
 
 Add `--check` to compare the rendered file on disk against a fresh render — it exits non-zero and
-prints the first differing line on **either** a hand edit to the rendered file **or** a store change
-since it was last rendered. There is no way to "fix" drift by editing the rendered file directly:
-the fix is always to re-run the generator (or, if the sidecar itself is stale, correct it and
-re-run). The generated file carries a banner naming the store, the sidecar and a content digest —
-do not strip it.
+prints the first differing line. Drift is reported when, and only when, one of these changed: the
+rendered file itself (a hand edit); a store row (a range, a label, a comment, or a comment's
+confidence grade); the provenance sidecar's bytes; the location of the store or the sidecar
+**relative to the workspace root**; or the renderer. **Relocating the checkout is not drift** — the
+same tree at a different absolute path renders the same bytes, because the banner records
+workspace-relative locations rather than absolute ones.
+
+There is no way to "fix" drift by editing the rendered file directly: the fix is always to re-run
+the generator (or, if the sidecar itself is stale, correct it and re-run). That remedy is safe to
+follow on any machine — because the banner records workspace-relative locations, re-running in a
+different checkout or in a worktree does not rewrite the file with that machine's absolute paths.
+The generated file carries a banner naming the store, the sidecar and a content digest — do not
+strip it.
+
+**One-time drift after upgrading, 2026-08-30.** A memory map rendered *before* 2026-08-30 will
+report `drifted` on its first `--check` after this change, exactly once: the banner's `store:` and
+`sidecar:` lines moved from absolute to workspace-relative spellings. Re-run the generator once and
+commit the new banner, after which the file is stable across machines and worktrees. This is a
+one-time, self-clearing banner correction — not a bug, and not a migration.
 
 ## The provenance sidecar
 
 Some facts belong to the **run** (which capture, which `$01`, which video standard) rather than to
-any address, and the store has no address-keyed shape for them (D-27). They are supplied to the
+any address, and the store has no address-keyed shape for them. They are supplied to the
 renderer as a small JSON sidecar, hand-authored from `c64-ram-capture`'s and `derive.mjs`'s own
 outputs and validated by the renderer — a missing or malformed key is a named error listing every
 problem at once, never a `<placeholder>` silently rendered into a published document.
@@ -64,8 +78,8 @@ literal values:
 
 ## Confidence vocabulary
 
-Every comment written into the store through `r2000_set_comment` that grades a finding leads with
-one of these five bracket tokens (the parser in `r2000-confidence.ts` throws on anything that is
+Every comment written into the store through `anno_set_comment` that grades a finding leads with
+one of these five bracket tokens (the parser in `anno-confidence.ts` throws on anything that is
 close but not exact — a typo never silently degrades into an ungraded comment):
 
 | Grade | Bracket token | Means |
@@ -80,4 +94,4 @@ Do not force an unknown range through a disassembler and record the output as co
 decode of data is silently wrong and contaminates everything downstream.
 
 **Do not promote a row by editing its grade.** Re-verify and restate the evidence with a fresh
-`r2000_set_comment` call, so the record of when something stopped being a guess survives.
+`anno_set_comment` call, so the record of when something stopped being a guess survives.

package/skills/c64-provenance-diff/SKILL.md

@@ -15,7 +15,7 @@ either proves its own precondition or refuses to emit.
 `ledger` will not write a verdict the earlier stages did not earn.
 
 ```bash
-D=.claude/skills/c64-provenance-diff/scripts/diff-images.mjs   # from the repo root
+D=src/skills/c64-provenance-diff/scripts/diff-images.mjs   # from the repo root
 
 node $D anchor-search                        # 1. prove the per-release offset  [WRITES]
 node $D diff                                 # 2. N-way byte diff at that offset
@@ -25,7 +25,7 @@ node $D ledger                                # 4. regenerate recovery/PROVENANC
 node $D diff --json                          # machine-readable, with per-range reasons
 node $D diff --gap-tolerance 16              # coalescing width (default shown)
 node $D anchor-search --reference <id>       # pick the reference release
-node .claude/skills/c64-provenance-diff/scripts/releases.mjs list                 # the release ids in play
+node src/skills/c64-provenance-diff/scripts/releases.mjs list                 # the release ids in play
 ```
 
 Pure Node over committed files — the `.bin` dumps, their `.map.json` manifests, and
@@ -126,9 +126,44 @@ The two seeds are where this goes wrong, and both failure modes are on record:
 `io` (`$D000-$DFFF`) and `unused` (contiguous `$00`/`$FF` power-on runs) are
 assigned at capture time and kept verbatim. Everything the trace reaches is `game`.
 
-Per D-05 the `.bin` files are **never** edited or zeroed. Classification lives in
+The `.bin` files are **never** edited or zeroed. Classification lives in
 the manifests; the bytes stay verbatim evidence.
 
+## Carrying the verdict into the rebuild
+
+A verdict recorded here does not stay here. `anno export-asm`'s `--ledger` flag
+reads THIS skill's generated `recovery/PROVENANCE.md` — never
+re-deriving anything — and carries every covered range's Verdict and Confidence
+into the exported ACME source as an inline comment on the block that range
+overlaps:
+
+```
+anno export-asm game.prg --store game.annostore --ledger recovery/PROVENANCE.md
+```
+
+The `<image>` positional wants one of `.prg`/`.raw`/`.bin`, `--store` an
+`.annostore`/`.store` file, and `--ledger` the `.md` this skill's own `ledger`
+verb writes.
+
+**The flag makes the verdict VISIBLE and decides nothing.** Every byte in
+scope is still emitted, whatever the verdict says — a `CRACKER-PATCH` row does
+not drop, filter or alter a single byte, it only makes the evidence readable
+at the point of use. What gets reversed, kept or left out remains the
+end-user's decision, never the tool's. `--ledger` is optional: omitting it
+exports exactly as before, with no provenance comment anywhere in the output.
+
+**When the operator, reading the ledger, decides a range genuinely should be
+left out of the rebuild output** — a trainer patch, a cracktro block, anything
+they choose — the round trip runs entirely on the `anno_*` MCP surface, never
+by editing the ledger or the export: `anno_exclude_range` records the span
+WITH the reason the operator gave, and `anno_include_range` takes the record
+back if the decision changes. Recording an exclusion changes nothing about
+which bytes the export emits — the exported block still carries every byte
+of that span, now with a visible marker naming the exclusion and its reason,
+so nothing is removed and no gap appears in the output. The ledger's verdict
+is information the operator reads at this point; it is never wired as an
+input to an automatic exclusion, here or anywhere else on this surface.
+
 ## A `CRACKER-PATCH` in `game` code is a trainer until proven otherwise
 
 `count-patches` counts exactly one intersection — verdict `CRACKER-PATCH`, kind
@@ -234,10 +269,10 @@ addresses.
 | Assembling | `acme-build` |
 | **Whether a byte is original, cracker-changed, or unknown** | here |
 
-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
 
@@ -254,4 +289,4 @@ through a GSD command (`/gsd-quick`).
 | A range's `kind` looks wrong past its start | You resolved `kind` from `start`. Use `splitRangeByManifestKind`; coalescing does not respect kind boundaries. |
 | A loader range disagrees with `NOTES.md` | `RELEASES.json`'s `loader_ranges` wins — it is earned from disassembly. Prose is how `$08F5` got misclassified. |
 | Title-screen text shows up as cracktro | You used a bare printable-run scan. The vocabulary scan exists because `$4771-$4779` is the game's own text. |
-| `unknown release "x" -- known releases: …` | `node .claude/skills/c64-provenance-diff/scripts/releases.mjs list` for the valid ids. |
+| `unknown release "x" -- known releases: …` | `node src/skills/c64-provenance-diff/scripts/releases.mjs list` for the valid ids. |

package/skills/c64-provenance-diff/scripts/diff-images.mjs

@@ -5,7 +5,7 @@
 // an already-committed file (a release's primary `.bin` dump, its
 // `.map.json` range manifest, and `recovery/RELEASES.json`) and every tool
 // is pure Node over those files -- nothing in this module contacts the
-// emulator, ever (D-18: zero third-party dependencies, `Buffer.indexOf` and
+// emulator, ever (zero third-party dependencies, `Buffer.indexOf` and
 // `node:crypto` are sufficient).
 //
 // This is the step the objective calls "the one most able to produce
@@ -373,7 +373,7 @@ export function diffRanges(images, { gapTolerance = 16 } = {}) {
         // one address's value would be both wrong for the range and would
         // silently defeat collapsing (no two addresses would ever compare
         // equal on evidence text, discovered live while running this tool
-        // against the real dumps -- see .planning/RE-FINDINGS.md).
+        // against the real dumps).
         rec = {
           verdict: "ORIGINAL",
           agreeing_releases: available.length,
@@ -519,7 +519,7 @@ function mergeGroup(group) {
   // `swallowedGap` below. Deduplicated (via Set) so a coalesced range with
   // many same-reason singleton addresses doesn't repeat identical
   // boilerplate once per address -- found live while running this against
-  // the real dumps (see .planning/RE-FINDINGS.md).
+  // the real dumps.
   const constituentNotes = [...new Set(nonOriginal.map((r) => r.evidence || r.reason).filter(Boolean))];
   const swallowedGap = group.length > nonOriginal.length;
   const note =
@@ -599,11 +599,11 @@ export function splitRangeByManifestKind(range, manifestRanges) {
 
 /**
  * Promote one manifest from `ranges-only` to `bucketed`: `unused`/`io`
- * ranges are kept verbatim (D-02's byte-level classification already
+ * ranges are kept verbatim (the byte-level classification already
  * stands); every `unclassified` range is re-partitioned against the
  * release's earned `loader_ranges` (never NOTES.md prose) and this image's
  * own cracktro printable-run scan, with the remainder -- reached by the
- * trace/entry point -- bucketed `game`. Per D-05 the underlying bytes are
+ * trace/entry point -- bucketed `game`. The underlying bytes are
  * never edited; only the manifest's own `kind` field changes.
  */
 export function bucketManifest(image, manifest, { loaderRanges, cracktroMinLength = 8 } = {}) {
@@ -614,7 +614,7 @@ export function bucketManifest(image, manifest, { loaderRanges, cracktroMinLengt
     note: lr.note ?? "",
     evidence: lr.evidence ?? "",
   }));
-  // Keep every already-classified range verbatim (unused/io from D-02's
+  // Keep every already-classified range verbatim (unused/io from the
   // byte-level pass, or -- on a re-run of an already-bucketed manifest --
   // game/loader/cracktro from a prior run of this same function). Only
   // "unclassified" is ever re-partitioned. Filtering "kept" down to just
@@ -693,6 +693,9 @@ export function renderLedger({ generatedRanges, gapTolerance, prose }) {
     throw new Error(`renderLedger: refusing to emit -- generated tier stops at ${hex4(expected - 1)}, does not reach $FFFF`);
   }
 
+  // NOTE: the embedded invocation path below is deliberately the
+  // CONSUMER's installed location (`.claude/skills/...`), not this repository's
+  // source-tree location (`src/skills/...`) -- pinned by diff-images.test.mjs and skill-consumer-paths.test.ts.
   let generated = `<!-- GENERATED, DO NOT HAND-EDIT. Regenerate with: node .claude/skills/c64-provenance-diff/scripts/diff-images.mjs ledger --gap-tolerance ${gapTolerance} -->\n\n`;
   generated += `| Start | End | Kind | Verdict | Confidence | Agreeing releases | Evidence / Reason |\n`;
   generated += `|---|---|---|---|---|---|---|\n`;

package/skills/c64-provenance-diff/scripts/recovery-schema.mjs

@@ -4,7 +4,7 @@
 // Node/filesystem checks over `recovery/RELEASES.json` and the files it
 // references, run entirely offline.
 //
-// This is the mechanical enforcement of 01-01-PLAN.md's assumption_delta
+// This is the mechanical enforcement of the assumption_delta
 // decision: the registry is release-CENTRIC (N releases, each a full field
 // set, `canonical` demoted to a boolean on one entry), never
 // canonical-image-centric again. A future plan that quietly reintroduces a
@@ -25,17 +25,29 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = projectRoot();
 const RECOVERY_DIR = dataRoot();
 const DISKS_DIR = disksRoot();
+
+const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
+
 // The parameterisation gate must cover EVERY module of the recovery pipeline, not
 // just the ones sitting next to this file. When the six modules moved out of
 // `tools/` into the two skills that use them (2026-08-04), a `HERE`-only scan
-// silently stopped covering `d64-parse.mjs` and `dump-artifacts.mjs` -- a static
-// guard that keeps passing while checking less is worse than one that fails.
+// silently stopped covering the disk-image reader that used to live in the
+// sibling skill's `scripts/` directory (since deleted)
+// and `dump-artifacts.mjs` -- a static guard that keeps passing while
+// checking less is worse than one that fails.
+// 2026-08-22: the second entry used to be built project-root-relative,
+// naming the skills tree's pre-relocation auto-discovery location by hand -- which
+// stopped resolving the moment the skills tree moved to its current source-tree
+// location. Rebuilt `HERE`-relative instead -- correct in both this dev checkout
+// and a consumer's install, since a sibling skill's `scripts/` directory is always
+// one level up and back down from this file's own location either way.
 const SCAN_DIRS = [
-  HERE, // .claude/skills/c64-provenance-diff/scripts
-  resolve(REPO_ROOT, ".claude", "skills", "c64-ram-capture", "scripts"),
+  HERE, // src/skills/c64-provenance-diff/scripts
+  resolve(HERE, "..", "..", "c64-ram-capture", "scripts"),
 ];
-
-const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
+for (const dir of SCAN_DIRS) {
+  if (!existsSync(dir)) die(`SCAN_DIRS entry does not exist: ${dir} -- a guard that keeps passing while checking less is worse than one that fails`);
+}
 
 function sha256File(path) {
   return createHash("sha256").update(readFileSync(path)).digest("hex");
@@ -131,7 +143,7 @@ function runBaseChecks(registry) {
       for (const field of REQUIRED_DUMP_FILE_FIELDS) {
         const value = d[field];
         if (!value) {
-          errors.push(`release "${r.id}" dump "${d.label}": field "${field}" is not set (a dump is a four-file set, per D-04/D-02)`);
+          errors.push(`release "${r.id}" dump "${d.label}": field "${field}" is not set (a dump is a four-file set)`);
           continue;
         }
         const filePath = join(REPO_ROOT, value);

package/skills/c64-ram-capture/RELEASES.json.example

@@ -0,0 +1,17 @@
+{
+  "schema_version": "1.0",
+  "schema_notes": "Adding a release is one releases[] entry plus one invocation of tools/recover.mjs -- see c64-ram-capture/SKILL.md '## Release registry shape'.",
+  "releases": [
+    {
+      "id": "example-release",
+      "canonical": true,
+      "disk_image": "disks/example-release.d64",
+      "dumps": [
+        {
+          "label": "example-label",
+          "range_manifest": "recovery/example-release/dumps/example-release-example-label.map.json"
+        }
+      ]
+    }
+  ]
+}

package/skills/c64-ram-capture/SKILL.md

@@ -14,12 +14,12 @@ failure and it is invisible in a hex dump. Two committed modules do that byte wo
 and name the offending address when it is wrong.
 
 ```bash
-S=.claude/skills/c64-ram-capture/scripts    # from the repo root
-P=$S/d64-parse.mjs   A=$S/dump-artifacts.mjs
+S=src/skills/c64-ram-capture/scripts    # from the repo root
+A=$S/dump-artifacts.mjs
 C=$S/compare.mjs     L=$S/releases.mjs
+T=$S/derive-transients.mjs               V=$S/vsf-slice.mjs
+TD=src/skills/c64-ram-capture/transients # the derived allow-lists live here
 
-node $P directory --image path/to/image.d64      # what's on the disk (--json flags faked entries)
-node $P bam       --image path/to/image.d64      # disk name, DOS type, occupied track ranges
 node $A assemble  --chunks chunks.json           # size + digest, writes nothing
 node $A write-set --release <id> --label <label> \
                   --chunks chunks.json --raw raw.json    # the four committed artifacts
@@ -28,10 +28,22 @@ node $L list                                     # the valid --release ids
 node $C digest  dump.bin                         # sha256 + size, for the capture record
 node $C compare a.bin b.bin                      # classify every difference, exit 1 on FAIL
 node $C floor   a.bin b.bin c.bin                # drift floor across a capture set
+
+node $T derive --release <id> --out $TD/<id>.json a.bin b.bin c.bin
+node $T check  --allow-list $TD/<id>.json a.bin b.bin
+
+node $V slice  run1.vsf --out run1.bin           # flat 64K image from a .vsf snapshot
+node $V digest run1.vsf                          # sha256 + size, writing no file
 ```
 
-All three modules read only committed files and the JSON **you** wrote from your
-own `mcp__plugin_c64-re-tools_vice__*` calls. They contact nothing.
+Every module above reads only committed files and the JSON **you** wrote from
+your own `mcp__plugin_c64-re-tools_vice__*` calls. They contact nothing.
+
+**Prerequisite: a resolvable project root.** `scripts/project-paths.mjs` uses
+`C64RE_PROJECT_ROOT` when it is set, and otherwise walks up from the toolkit's
+own location for the nearest ancestor directory containing a `.git` entry. A
+scratch project has neither by default, so `git init` it first or set the
+variable — the thrown error names both when this fails.
 
 ## The order
 
@@ -45,31 +57,9 @@ own `mcp__plugin_c64-re-tools_vice__*` calls. They contact nothing.
 
 ## Read the disk first
 
-`scripts/d64-parse.mjs` parses `.d64` bytes directly, so it answers what is on the
-disk whether or not the emulator is up:
-
-```bash
-$ node $P directory --image demo.d64
-PRG "DEMO GAME" first=5/0 blocks=5
-
-$ node $P bam --image demo.d64
-disk name: "DEMO DISK"  id: 38  dos type: 2A
-first dir sector: 18/1
-occupied track ranges: 5
-```
-
-Do not eyeball the directory for fakery — `--json` decides it. Every entry carries
-`suspicious` plus `suspicious_reasons`, set when the block count is 0, when the
-first track/sector falls outside the image, or when it points into a track the BAM
-reports as entirely free. That last case is the signature of an entry claiming a
-file never written to disk.
-
-`scripts/d64-parse.test.mjs` proves the detector both **fires** on a synthetic
-faked entry and stays silent on a well-formed one — a guard proven only silent is
-not a guard. It also sweeps whatever real `.d64` corpus the project ships,
-skipping when there is none. A non-null `chain_error` is the separate failure: a
-directory chain that leaves the image or loops, reported instead of hanging.
-**Confidence: HIGH** (synthetic fire-and-silence tests, plus a corpus sweep).
+Disk-image structure — the directory, the block allocation map, a named file's
+sector chain or raw bytes, and directory-fakery detection — is
+`c64-disk-access`'s job now. Read the disk with it before booting anything.
 
 ## Boot a disk
 
@@ -78,6 +68,9 @@ directory chain that leaves the image or loops, reported instead of hanging.
 3. `mcp__plugin_c64-re-tools_vice__vice_execution_run`.
 4. `mcp__plugin_c64-re-tools_vice__vice_registers_get` and confirm the program counter has moved.
 
+The broker sets the drive type at launch for every stock instance, so no drive setup
+is needed before attaching.
+
 If the program counter has not moved, type `LOAD"*",8,1` with
 `mcp__plugin_c64-re-tools_vice__vice_keyboard_type`, run it, then type `RUN` and run it.
 
@@ -119,6 +112,17 @@ Read state before you resume, and resume exactly once at the end.
 Hold keys down across a gate by releasing them at the trigger checkpoint in
 step 3, never earlier.
 
+**Fill the record's reproducibility key in the same step.**
+`templates/capture-record.template.md`'s Identity table carries three rows that
+are one key, not three facts: `binary sha256`, `argv digest` and `seed`. The
+seed alone is **not** the key — measured, the same seed with a reordered argv
+yielded a 76-byte-different image, so two captures whose argv digests differ are
+different keys and must not be compared as a pair. A record with any of those
+three blank is not a reproducible capture and the void protocol applies. The
+table also carries a `capture route` row (`memory-read` or `snapshot`), and
+**on the snapshot route the `$D000-$DFFF` volatility rule below does not
+apply** — a difference there is a real difference.
+
 `assemble` runs the same assertions and writes nothing, so it is the cheap check
 on a set of chunks before committing them.
 
@@ -155,12 +159,12 @@ only after the provenance diff partitions loader from cracktro from game — see
 
 ## Find an entry point
 
-1. Press past any "hit any key" gate with `mcp__plugin_c64-re-tools_vice__vice_keyboard_matrix`.
-   **This call requires the fork backend** — the binary monitor's `KEYBOARD_FEED` only injects
-   PETSCII text into the KERNAL buffer 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.
+1. Press past any "hit any key" gate. **`vice_keyboard_matrix` is permanently unavailable** — the
+   binary monitor's `KEYBOARD_FEED` only injects PETSCII text into the KERNAL buffer 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.
 2. Step forward in batches with `mcp__plugin_c64-re-tools_vice__vice_execution_step`, reading
    `mcp__plugin_c64-re-tools_vice__vice_registers_get` after each batch.
 3. Stop when the program counter and the stack pointer both settle into a
@@ -247,8 +251,8 @@ were guaranteed. Region first, bit-count second.
 `$E000-$FFFF` (RAM under KERNAL ROM when HIRAM = 0) is deliberately **not**
 excluded. `$FAD8` and `$FC51` do differ across captures, but only two addresses
 out of 8192 — too few for power-on garbage, and unexplained. They still fail, and
-what writes them is an open question. Evidence and grading:
-`.planning/RE-FINDINGS.md`, 2026-08-04.
+what writes them is an open question. Observed 2026-08-04; graded MEDIUM,
+structural, not reproduced against a second release.
 
 **Establish a drift floor** with `floor` across every capture of one checkpoint.
 It reports each address that differed in any pairing, with the distinct values
@@ -262,9 +266,79 @@ Capture the power-on image as the very first action against a fresh machine, the
 idle-capture twice more and run `floor` over the set. State the result as a
 floor, not a complete set — more captures can only widen it.
 
+## Derive a per-release transient allow-list
+
+`scripts/derive-transients.mjs` is the named, repeatable derivation. **The
+method is what carries forward between releases; no address set ever does.** Two
+verbs:
+
+```bash
+node $T derive --release <id> --out $TD/<id>.json run1.bin run2.bin run3.bin
+node $T check  --allow-list $TD/<id>.json runA.bin runB.bin
+```
+
+`derive` takes **N ≥ 3** runs of the same release under the same protocol at the
+same stop and writes the **union of addresses differing across every pairwise
+comparison** — one entry per address, carrying which pairings it differed in,
+the distinct bytes seen, and an empty attribution line for you to fill. Fewer
+than three images is refused naming the count and the minimum; an image that is
+not exactly 65536 bytes is refused naming the path and the length. It prints
+`TRANSIENT_COUNT: <n>` at column 0, so a measurement gets transcribed rather
+than paraphrased.
+
+**Over the cap of 64 addresses the derivation is VOID:** non-zero exit, **no
+artifact written**, and the message says what the overflow means — the stop is
+not frame-exact. That is a fact to record, not a threshold to raise. `--cap`
+only ever *narrows*; a value above 64 is refused by name, and the union is never
+truncated to fit, because a truncated list makes every later comparison pass on
+bytes nobody vetted. Overflow is a **measured** outcome: 0 differing addresses
+at a frame-exact `READY` stop, 66 at a frame-anchored autostarted stop at
+jitter 4000 ms, 300 at a wall-clock autostarted stop on a real release, 1242 at
+a wall-clock `READY` stop with the determinism block applied.
+
+Re-deriving over an existing artifact is **refused without `--force`**, with the
+no-inheritance rule in the message: an inherited list cannot be distinguished
+afterwards from an honestly derived one.
+
+`check` re-checks one pair against an already-committed derivation without
+re-deriving it, printing `CHECK_VERDICT: equivalent | not-equivalent` and exiting
+1 when not equivalent. Note what it does **not** carry: no address range is a
+volatile span, and there is no bit-count tolerance at any address — a one-bit
+difference outside the list fails. Those two rules belong to `compare.mjs` and
+are deliberately not inherited. `src/skills/c64-ram-capture/transients/README.md`
+holds the artifact shape, the committed method and the cap's reasoning.
+
+## Slice the image out of a snapshot instead of transcribing it
+
+`scripts/vsf-slice.mjs` produces the flat 64K image by slicing a VICE `.vsf`
+snapshot's memory module body. Two verbs:
+
+```bash
+node $V slice  run1.vsf --out run1.bin   # writes exactly 65536 bytes
+node $V digest run1.vsf                 # sha256 + size, writing no file
+```
+
+Add `--json` to either for the same summary as one JSON object — it carries the
+snapshot's memory-module minor, the observed body length, and the three CPU port
+read-back values.
+
+**The one thing that matters operationally: this route has no transcription
+step, so the `$D000-$DFFF` volatility rule above does *not* apply to an image
+produced this way.** That rule exists because `vice_memory_read` samples live
+I/O. The snapshot array is RAM *under* I/O, not the register read view, so those
+4096 addresses are ordinary RAM in a sliced image and a difference there is a
+real difference. Do not carry the exclusion across from the memory-read route.
+
+A malformed snapshot is **refused**, by name, naming the offending value and the
+valid range — it is never truncated into a plausible short image. The `.vsf`
+byte layout lives in exactly one place, `vsf-slice.ts` on the MCP side; this
+script resolves it via `VICE_MCP_DIR`, the in-repo path, or the
+`@henols/vice-mcp` package, and refuses naming every path it tried when no rung
+resolves rather than falling back to a second copy of the layout.
+
 ## Feeding the memory map's provenance sidecar
 
-`c64-program-recon`'s generated memory map (`vice-mcp r2000 render-memmap`) takes a small provenance
+`c64-program-recon`'s generated memory map (`vice-mcp anno render-memmap`) takes a small provenance
 sidecar as input, and this skill supplies one of its fields: `scripts/compare.mjs digest`'s `sha256`
 and `size` become the sidecar's `captureSha256`, proving which image the rendered map describes. The
 sidecar's other run-scoped keys (`port01`, `dd00`, `vicBank`, `screenRam`, `charsetOrBitmap`, `mode`,
@@ -279,6 +353,7 @@ This one owns the image and its identity. It does not restate what the others ca
 
 | Need | Go to |
 |---|---|
+| A disk image's directory, BAM, sector chains, or directory-fakery detection | `c64-disk-access` |
 | Which address to read next, and what the answer rules out | `c64-program-recon` |
 | Every way a live read gives a wrong answer | `c64-program-recon` — `references/observation-hazards.md`. **Read before driving.** |
 | What a specific address or bit means | `c64-memory-mapping` — `node … lookup '$D018'` |
@@ -287,6 +362,28 @@ This one owns the image and its identity. It does not restate what the others ca
 | Whether the emulator is wedged, and whether it is safe to recycle | `vice-wedge-triage` |
 | **A verified 64K image, or proving two captures equivalent** | here |
 
+## Release registry shape
+
+`scripts/releases.mjs` is the only module that reads a release id out of the
+registry — every other module takes the id as an argument. Its shape:
+
+| Field | Level | Required | For |
+|---|---|---|---|
+| `schema_version` | top-level | — | The registry format version. |
+| `schema_notes` | top-level | — | Free-text stating the registry's N-readiness claim (`node $L schema-notes`). |
+| `releases` | top-level | yes | The array of release entries below. |
+| `id` | per-release | yes | The `--release` argument every other script takes. |
+| `canonical` | per-release | — | A boolean on one entry, not "the canonical image" — there are N releases. |
+| `disk_image` | per-release | yes | Project-relative path to the release's `.d64`. |
+| `dumps` | per-release | **yes, as an array** | Per-capture records written by `write-set`. **Must be an array, never omitted** — `releases.mjs`'s `list` command reads `r.dumps.length` with no guard (`releases.mjs:98`), so a missing `dumps` throws `TypeError: Cannot read properties of undefined` instead of listing anything. An empty array (`[]`) is fine; an absent key is not. `releases.mjs` itself imposes no per-entry shape; `scripts/watch-loads.mjs` (a different reader) looks up an entry by `label` and reads its `range_manifest`, which the example below follows. |
+
+The registry lives at `<project root>/recovery/RELEASES.json` by default —
+override the whole path with `C64RE_REGISTRY`, or just the containing
+directory with `C64RE_DATA_DIR`.
+
+`src/skills/c64-ram-capture/RELEASES.json.example` is a copyable starting
+point with every field above populated with placeholder values.
+
 ## References
 
 What this skill ships, and the committed modules it leans on. No `references/`
@@ -295,14 +392,17 @@ split: the workflow fits in one file, which is the right call when it does.
 | Path | Covers |
 |---|---|
 | `scripts/compare.mjs` | Difference classification and the drift floor. Pure logic over captures you already have — `node $C` with no arguments prints the rules. |
-| `templates/capture-record.template.md` | The per-capture record: identity, machine state read in the same paused window, the void checklist, and the per-pairing comparison table. |
-| `scripts/d64-parse.mjs` | `.d64` directory, BAM, and `--json` fakery detection. Fixture-tested against both real images by `scripts/d64-parse.test.mjs`. |
+| `scripts/vsf-slice.mjs` | `slice` / `digest` — the flat 64K image sliced out of a `.vsf` snapshot with no transcription step. The layout lives in `vsf-slice.ts` on the MCP side; this wrapper resolves it and refuses by name when it cannot. Covered by `scripts/vsf-slice.test.mjs`. |
+| `scripts/derive-transients.mjs` | `derive` / `check` — the per-release transient allow-list, derived from N ≥ 3 runs as the pairwise union, under a committed cap of 64 that **voids** rather than warns. Covered by `scripts/derive-transients.test.mjs`. |
+| `transients/README.md` | The committed derivation method, the artifact shape, the cap's reasoning with its four measured reference points, and the rule that no address set is inherited between releases. Its `.gitignore` refuses every image byte form. |
+| `templates/capture-record.template.md` | The per-capture record: identity including the three-row reproducibility key and the `capture route` row, machine state read in the same paused window, the void checklist, and the per-pairing comparison table. |
 | `scripts/dump-artifacts.mjs` | `assemble` / `chip-state` / `manifest` / `write-set` — the guarded byte work, and the source of every `assembleImage:` message in the table below. |
+| `RELEASES.json.example` | A copyable release-registry shape — see `## Release registry shape` above. |
 
-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
 
@@ -320,3 +420,4 @@ through a GSD command (`/gsd-quick`).
 | `--limit 0` printed nothing | Fixed 2026-08-04 — it now means unlimited. Re-pull the script if you see the old behaviour. |
 | An epoch-drift error appeared mid-capture | The machine restarted under you. Void the run; do not salvage the artifacts. The next call succeeding does not undo it. |
 | The emulator looks dead | `vice-wedge-triage` — and enumerate your own armed checkpoints before concluding anything. |
+| `` `project-paths: could not locate the project root -- no `.git` found above ...` `` | No `.git` ancestor and no `C64RE_PROJECT_ROOT`. `git init` the project, or set the variable to its root. |

package/skills/c64-ram-capture/scripts/compare.mjs

@@ -17,7 +17,7 @@
 //
 // $D000-$DFFF is this module's one departure from what SKILL.md said when it was
 // written: that range is I/O, not RAM, so it can never be stable. See the VOLATILE
-// table below and .planning/RE-FINDINGS.md (2026-08-04) for the evidence.
+// table below for the evidence (observed 2026-08-04).
 
 import { readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
@@ -36,7 +36,7 @@ const VOLATILE = [
   // live hardware and two captures can never agree here. Added 2026-08-04 after
   // every divergence across all six committed gameentry pairings landed either
   // here ($D344, $D625, $D628) or in RAM under KERNAL ROM -- see
-  // .planning/RE-FINDINGS.md, 2026-08-04. Confidence HIGH: structural.
+  // Observed 2026-08-04. Confidence HIGH: structural.
   [0xd000, 0xdfff],
 ];