@henols/c64-re-tools 0.2.1 → 0.2.2

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

@@ -1,23 +1,37 @@
 # 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
+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
 
@@ -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
@@ -254,4 +254,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

@@ -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 (plans 16-01, 16-10): 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 (16-REVIEW.md CR-01).
   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

@@ -25,17 +25,27 @@ 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.
+// 2026-08-22 (plan 16-01): 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");

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,7 +14,7 @@ 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
+S=src/skills/c64-ram-capture/scripts    # from the repo root
 P=$S/d64-parse.mjs   A=$S/dump-artifacts.mjs
 C=$S/compare.mjs     L=$S/releases.mjs
 
@@ -33,6 +33,12 @@ node $C floor   a.bin b.bin c.bin                # drift floor across a capture
 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.
 
+**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
 
 | # | Phase | Settles |
@@ -78,6 +84,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.
 
@@ -264,7 +273,7 @@ floor, not a complete set — more captures can only widen it.
 
 ## 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`,
@@ -287,6 +296,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/`
@@ -298,6 +329,7 @@ split: the workflow fits in one file, which is the right call when it does.
 | `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/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
@@ -320,3 +352,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/project-paths.mjs

@@ -6,7 +6,7 @@
 //
 //   1. The project root is found by walking UP for a `.git` marker. Counting
 //      hops from `import.meta.url` breaks the moment the toolkit is installed
-//      somewhere other than `.claude/skills/<skill>/scripts/`, and it breaks
+//      somewhere other than `src/skills/<skill>/scripts/`, and it breaks
 //      silently -- paths resolve to a plausible wrong place rather than erroring.
 //   2. Every data location is overridable by environment variable, so a project
 //      that does not use this repo's `recovery/` + `disks/` layout can point the

package/skills/c64-ram-capture/scripts/watch-loads.mjs

@@ -445,6 +445,12 @@ function renderReleaseSection(id, log) {
  * string templating over already-fetched data -- nothing here reads a file
  * or contacts anything; the CLI `render` verb below is what reads the
  * hit-log files and writes the result.
+ *
+ * The two script paths named in the output below are deliberately the
+ * consumer's installed location, not this repository's source tree -- this
+ * string is written into a `recovery/LOADING.md` a consumer keeps. Plan
+ * 16-04's blanket sweep rewrote them once (16-REVIEW.md CR-01 class); pinned
+ * by the test below plus the class-level registry in skill-consumer-paths.test.ts.
  */
 export function renderLoading(entries) {
   let out = "# `recovery/LOADING.md` -- the on-demand-load detection record\n\n";

package/skills/routine-queue-walker/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: routine-queue-walker
+description: Drive an existing C64 annotation store's backlog of undocumented routines and auto-named symbols to closure — build the candidate queue from labels and comments, work it one entry at a time against explicit addresses, rebuild it after every pass, and report every leftover. Use when asked to annotate every remaining routine in a project, document all undocumented subroutines left in an annotation project, rename the leftover auto-generated labels, clear a backlog of unnamed symbols, drive an annotation pass to completion, or list what is still unannotated after a pass.
+---
+
+# Walking the routine and symbol queue to closure
+
+**Do not start annotating whatever is in front of you.** The expensive failure
+here is not slow work — it is a pass that *looks* finished while a hundred
+`p_XXXX` labels are still nameless and nobody wrote down which ones. Build the
+queue first, from data, then walk it to the end.
+
+This playbook assumes block classification has already happened and an
+annotation store already exists. If you do not yet know what the program is —
+where it starts, which vector is live, which regions are code — stop and run
+`c64-program-recon` first. That skill answers *what is this program*; this one
+answers *what is still undocumented in it, and how do I finish*.
+
+## The one rule that makes this different from upstream's version
+
+**Work the queue one entry at a time.** Not as a throughput compromise — as an
+accurate model of the store underneath. One `.annostore` is one writer: every
+mutating call opens it, commits and closes inside the call, and every one of
+them accepts an optional `base_revision` compare-and-swap that REFUSES a write
+computed against a revision the store has already moved past. Fanning several
+writers at one store therefore buys **zero** extra throughput and costs
+correctness: the losers come back as named stale-revision refusals you then
+have to re-derive and replay. Reading fan-out — several agents *thinking* over
+already-fetched answers — is fine, and its value is reasoning bandwidth, never
+I/O.
+
+**Every call names its own store.** There is no ambient "current store" on this
+surface: pass `store` (a `.annostore` path) on every call, and pass `image` as
+well on every call that derives its answer from the program's bytes rather than
+from the annotations — `anno_get_binary_info`, `anno_read_region`,
+`anno_disassemble`, `anno_get_cross_references`, `anno_search` and
+`anno_get_address_details`. The store holds annotations and never bytes, so an
+omitted image would read as a plausible success against whatever was recorded
+last.
+
+## Phase 0 — context, and the packed-binary gate
+
+1. Call `anno_get_binary_info`. Keep `origin`, `size`, `system`, `filename`,
+   `description` and `may_contain_undocumented_opcodes` — every later step
+   quotes them.
+2. Read the returned `entropy` against the threshold of **7.5** carried in that
+   tool's own description. At or above it, the bytes are very likely packed.
+3. If the binary looks packed, **stop and say so.** Do not annotate a packed
+   image: you would be documenting a decruncher, and every label you write is
+   thrown away the moment the real image is recovered. This project's route to
+   an unpacked image is `c64-ram-capture` — run the program in the emulator and
+   capture RAM at a checkpoint past the decrunch — plus the packer-identity
+   finding in `c64-program-recon`, which names the packer when an oracle can.
+   Come back with the captured image and start again at Phase 0.
+
+Upstream's in-place `unpack_binary` step is deliberately not carried: it is
+destructive (it clears the comments, labels and blocks already in the store)
+and this project has a non-destructive route to the same answer.
+
+## Phase 1 — make sure blocks are classified
+
+Region classification is a prerequisite for everything below: a routine
+candidate is only meaningful once the bytes around it are known to be code.
+
+1. Follow `src/skills/c64-memory-mapping/SKILL.md` for the classification pass
+   and for what each region type means.
+2. Do that pass yourself, in one sitting. It is a single long walk over the
+   whole binary, not a queue of independent items.
+
+## Phase 2 — the routine queue
+
+### 2.1 Build the candidate list
+
+A routine counts as **already documented** when its entry address carries a
+line comment. That is the only test; do not guess from the label name.
+
+1. Call `anno_get_symbols` for all labels — user, system and external, with
+   an explicit `max_results` above the program's label count (`max_results` is
+   REQUIRED on this surface and has no default, so a truncated answer is always
+   a ceiling you chose). Keep the answer; Phase 3 reuses it.
+2. Call `anno_get_comments`, again with an explicit `max_results`. Keep that
+   too — the true match count rides beside the list, so truncation is a fact
+   you are told rather than one you infer.
+3. Keep a label as a routine candidate when any of these holds:
+   - its name starts with `s_` (an auto-generated subroutine label);
+   - it sits in a code region and is the target of at least one `JSR`
+     cross-reference (`anno_get_cross_references`);
+   - it is a `p_XXXX` label sitting **inside a code region**. These come from
+     split lo/hi immediate loads and from address tables, and they are almost
+     always chained raster-IRQ handlers, hardware- or shadow-vector handlers,
+     or jump-table and callback targets. Treat every one of them as a
+     candidate rather than pattern-matching specific vector addresses;
+   - it is the label named exactly `start`.
+4. Drop every candidate that already carries a line comment.
+5. What is left is the routine queue.
+6. **Order it with `start` first** when `start` is in it. The entry point sets
+   the context every other routine is read against.
+
+### 2.2 Walk it
+
+- **Always work from an explicit address** — `$XXXX`, or the decimal
+  equivalent. Never from "wherever we are"; there is no editor cursor in this
+  project's route, and upstream's own text forbids relying on one anyway. Read
+  the routine's bytes with `anno_read_region` over the explicit range.
+- Take **one** entry at a time, to completion, before starting the next.
+- For each entry, do the full job: rename the label (`anno_set_label_name`),
+  add a header line comment describing what the routine does and what it
+  leaves in the registers and memory, add side comments on the instructions
+  that carry the meaning (`anno_set_comment`), and record anything you are
+  unsure about rather than smoothing it over.
+- Record per entry: the address, the old label, the new label, a one-line
+  summary, and any uncertainty. That record is the report in Phase 4.
+
+### 2.3 Refresh point
+
+When the queue is empty, read the store's revision with `anno_save_project`.
+**It performs no write, and it exists to say so:** every mutating verb on this
+surface has already committed and fsynced its own write by the time it
+returned, so there is nothing for an explicit save to flush. Record the
+revision — it is the checkpoint this pass is measured from, and the
+`base_revision` a later compare-and-swap write would quote. Everything after
+this point re-reads the store, because Phase 2 has just changed the label names
+Phase 3 filters on.
+
+## Phase 3 — the symbol queue
+
+### 3.1 Build the candidate list
+
+A symbol counts as **already documented** when it has a name a human chose, or
+when it is a well-known system address (hardware register, KERNAL entry point,
+OS variable).
+
+1. Call `anno_get_symbols` **again** — Phase 2 renamed things.
+2. Keep every label whose name still matches an auto-generated pattern:
+   `zpp_XX`, `zpf_XX`, `zpa_XX` in the zero page; `p_XXXX`, `f_XXXX`, `a_XXXX`
+   and `e_XXXX` outside it.
+3. Exclude: `s_XXXX` (Phase 2 handled those), `b_XXXX` (branch targets, not
+   data symbols), and any `p_XXXX` inside a code region (also Phase 2's).
+4. What is left is the symbol queue.
+
+### 3.2 Walk it
+
+Same discipline as Phase 2: explicit address, one entry at a time, to
+completion. For each symbol, use `anno_get_cross_references` to find who
+touches it — a symbol's meaning is what its callers do with it — then rename it
+and comment it. Classify it plainly: flag, counter, pointer, state variable,
+buffer, table.
+
+**No premature halting.** The symbol queue is routinely far larger than the
+routine queue — fifty, a hundred entries is normal. Do not truncate it, do not
+skip "secondary" symbols, and do not stop early because it is long. Feeding the
+whole queue through is the job. Stopping early and labelling the remainder
+"skipped for review" is a failed pass, not a completed one — unless the
+remainder is reported explicitly, in full, under Phase 4's leftovers table.
+
+For naming conventions and for what any given hardware or KERNAL address
+means, follow `src/skills/c64-memory-mapping/SKILL.md` rather than guessing.
+
+### 3.3 Refresh point
+
+Read the revision again with `anno_save_project` and record it. No write is
+performed; the writes already landed.
+
+## Phase 4 — save and report
+
+1. Read the revision one last time with `anno_save_project` and quote it in
+   the report, so the pass is attributable to an exact store state.
+2. Write the report. Four sections, all of them required:
+
+**Regions.** How many regions are classified, grouped by type, plus anything
+notable — text at a fixed address, a jump table, a sprite block.
+
+**Routines.**
+
+| Address | Old label | New label | What it does |
+| ------- | --------- | --------- | ------------ |
+| `$C000` | `s_C000`  | `init_screen` | Clears screen RAM, sets the border colour |
+
+**Symbols.**
+
+| Address | Old label | New label | Classification |
+| ------- | --------- | --------- | -------------- |
+| `$02`   | `zpp_02`  | `ptr_screen` | Zero-page indirect pointer |
+
+**Leftovers — uncertain, skipped, or still unannotated.** This section is not
+optional and it is not allowed to be empty when the queues were not emptied.
+List every routine and every symbol that was left undone, with its address and
+the reason. Never report "no uncertain areas" or "nothing left" while a single
+`f_XXXX` or `a_XXXX` label is still auto-named or a queued routine is still
+uncommented — those must be listed by name for a human to pick up.
+
+## Phase 5 — measure the pass instead of asserting it finished
+
+A report that says "all routines documented" is a claim about the report, not
+about the program. Measure it. From the repository root:
+
+```
+node src/mcp/vice/vice-proxy.ts anno coverage game.prg --store game.annostore
+```
+
+**`--store` is REQUIRED and is a second path, not a spelling of the first.**
+`<program>` supplies the payload bytes and the load origin; `--store` names the
+annotation store holding the labels, comments and typed ranges. The store holds
+annotations and never bytes, so the verb refuses to guess either path from the
+other.
+
+**Dated note, 2026-08-30 — the positional is a program IMAGE, and the command
+above is now correct against the shipped verb.** `<program>` is a `.prg` (a
+2-byte little-endian load address followed by the payload) or an
+**exactly-65536-byte** flat capture with a `.raw` or `.bin` extension — the two
+forms every other verb and tool on this surface already reads, and the two
+`c64-ram-capture` produces. The intermediate project-file format this verb
+previously required has **no producer left in this repo**; it is still accepted
+so an existing project file keeps working, but nothing here writes one, so do
+not go looking for a step that produces it.
+
+Dispatch is by **file extension first, length second**. A short flat capture is
+therefore refused by name — `a flat 64K capture must be exactly 65536 bytes` —
+rather than misread as a `.prg` whose first two payload bytes become the load
+address. If you get that refusal, the capture is truncated; re-capture it, do
+not rename it.
+
+Add `--out coverage.json` to keep the machine-readable report, `--force` to
+overwrite one, and `--sample N` to widen the reproducibility sample. The verb
+reads the same store every call in this playbook writes to, and exits **0 even
+when the numbers are bad** — a low measurement is a result, not a failure.
+Non-zero means a caller error, an image it could not read, or a store it could
+not read at all.
+
+**Run it three times:** once before Phase 2, so the pass has a starting point
+to be compared against; once at Phase 2.3's refresh point; and once at the end,
+after Phase 4's final save. The last run is what goes in the report.
+
+**Read the three numbers against each other. Never quote one of them alone.**
+There is deliberately no single "percent documented" figure, because one
+combined number lets a weak measure hide behind a strong one and makes the
+claim unfalsifiable:
+
+- **A high user fraction beside a large unreached count means the wrong things
+  were named.** Every label got a human name, but most of the image was never
+  reached by the descent walk from any seed — the queue was worked over the
+  easily-visible part of the program and the rest was never entered. Go back to
+  Phase 0 and find more entry points (chained IRQ vectors, dispatch tables),
+  not more labels.
+- **A large divergence means the store and the bytes disagree about what is
+  code.** Bytes the census reached as instructions that the store does not call
+  `Code` are places where Phase 1's classification is behind the actual control
+  flow. The reverse direction (the store calls it `Code`, the census never
+  reached it) is ordinary on an image with unreachable filler — read it, do not
+  chase it.
+- **A low distinct-comment ratio means the comments are filler.** Fifty
+  addresses carrying the same sentence counts once, not fifty times. That is
+  the number that catches a pass which renamed everything and explained
+  nothing.
+
+Anything the per-measure findings list names belongs in Phase 4's leftovers
+table, by address. A finding is a named defect in one named measure — it is
+never a rating, and there is no number to report as "the coverage".
+
+## When something fails
+
+- A failed call is not a reason to drop a queue entry. Log the address, the
+  call and the error, put the entry back on the queue, and carry on with the
+  next one. Report every one of those in the leftovers table.
+- A refused write is not silent and must not be treated as one. A
+  stale-revision refusal (a `base_revision` that the store has moved past), an
+  illegal label name, or a scope that overlaps an existing one all come back
+  REFUSED and named, with nothing written. Re-read, re-derive and replay that
+  one entry; never widen the range or drop the `base_revision` to make the
+  refusal go away.
+- Never invent an answer to make a queue entry go away. An honest "this looks
+  like a table, callers unclear" in the leftovers table is worth more than a
+  confident wrong label that the next reader has to un-learn.

package/skills/vice-wedge-triage/SKILL.md

@@ -167,14 +167,14 @@ connection but never answers is contention, not a hung emulator — and the brok
 knows whether it holds a lease on that port, which is the thing a human or agent can actually go
 check instead of guessing. Named causes, so a reader knows where to look: a hand-run `nc` session
 left open against the port, a second Claude Code session driving the same instance, VICE's own
-`-remotemonitor`, and any other 6502 debugger that dials in — including regenerator2000's own
-`--vice` flag. **This plugin's own regenerator2000 route can never be one of them:** the launch
-path refuses `--vice` by construction (no caller-supplied argv passthrough exists to inject it in
-the first place) *and* by a scan that throws if the flag is ever present in the final argv — not by
-documentation alone (`R2000-01`, plan 10-01) — so a user chasing a silent emulator can rule this
-project's own r2000 integration out immediately, rather than suspecting it. The standing advice
-does not change: contention is **never** a reason to recycle — the instance is healthy, merely
-claimed elsewhere.
+`-remotemonitor`, and any other 6502 debugger that dials in. **This plugin's own annotation route
+can never be one of them:** the `anno_*` tool surface and the `anno` CLI are pure store-and-image
+readers — they open a SQLite annotation store and decode bytes out of a file on disk, and there is
+no emulator connection anywhere on that path to contend for the port. That is a structural
+property of what those calls do, not a documented promise, so a user chasing a silent emulator can
+rule this project's own annotation tooling out immediately rather than suspecting it. The standing
+advice does not change: contention is **never** a reason to recycle — the instance is healthy,
+merely claimed elsewhere.
 
 ## The manual fallback, when `vice_diagnose` cannot answer