@henols/vice-mcp 0.2.3 → 0.2.4

package/anno-memmap-render.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 // anno-memmap-render.ts -- the ONE authoritative place in this repo that
 // renders the human-readable Markdown memory map from this project's own
-// annotation store (D-24) plus a validated run-scoped provenance sidecar
-// (D-27's reconciliation, recorded in 11-10-PLAN.md's objective).
+// annotation store plus a validated run-scoped provenance sidecar, using
+// the reconciliation between those two sources this file implements.
 //
-// WHY THIS MODULE EXISTS (D-24): the store is canonical; the Markdown memory
+// WHY THIS MODULE EXISTS: the store is canonical; the Markdown memory
 // map becomes a rendered VIEW. Criterion 1 says findings must be queryable
 // "instead of re-deriving from Markdown prose" -- that is only true by
 // construction if the prose is GENERATED from the queryable thing. Nothing
@@ -13,7 +13,8 @@
 // `listRanges()`/`listLabels()`/`listComments()` readers, never from a
 // human editing the output file directly.
 //
-// THE D-24/D-27 RECONCILIATION THIS FILE IMPLEMENTS: run-scoped facts (the
+// THE RECONCILIATION THIS FILE IMPLEMENTS, BETWEEN THE STORE AND THE
+// RUN-SCOPED SIDECAR: run-scoped facts (the
 // capture's SHA-256, `$01`, `$DD00`, the derived graphics chain, the video
 // standard, the live vector pair, observed raster positions) are facts about
 // a RUN, not about an address -- the store is address-keyed and has no shape
@@ -24,8 +25,8 @@
 // `<placeholder>` for one.
 //
 // WHY THE LAYOUT IS EMBEDDED IN TYPESCRIPT RATHER THAN READ FROM A TEMPLATE
-// FILE AT RUNTIME (the second decision this plan records): Phase 10's D-06
-// established that `.claude/mcp/vice/*.ts` exists as files on disk only
+// FILE AT RUNTIME (the second decision this plan records): an earlier
+// finding established that `.claude/mcp/vice/*.ts` exists as files on disk only
 // under the Claude Code plugin route -- both npm-installer routes launch via
 // `npx`. A renderer that resolved a template path into the skills tree at
 // runtime would silently fail to resolve for an npm-installed user. The
@@ -41,7 +42,7 @@
 //   - drift detection (`checkRenderedMemoryMap()`) -- the one place a
 //     rendered file on disk is compared against what the store (plus the
 //     sidecar) would produce right now;
-//   - Markdown-cell escaping (`escapeMarkdownCell()`, WR-04, closed) --
+//   - Markdown-cell escaping (`escapeMarkdownCell()`) --
 //     every store-derived text interpolation in the generated document
 //     (comment evidence, symbol names) is escaped through this one
 //     function, never a second ad hoc `.replace()` at a call site.
@@ -50,7 +51,7 @@
 //   - Never hand-edit the rendered output. The banner exists precisely so a
 //     human editor is caught by `checkRenderedMemoryMap()` -- see the
 //     `render_digest` comment below for exactly what it covers.
-//   - Never read the layout from the skills tree at runtime (Phase 10 D-06).
+//   - Never read the layout from the skills tree at runtime (see the module header for why).
 //     This module's own non-vacuity test asserts a zero-count grep for the
 //     recon skill's template filename -- if you are tempted to add a
 //     `readFileSync()` call reaching into `.claude/skills/`, don't; the
@@ -101,14 +102,14 @@ function errMsg(err: unknown): string {
  * offset at which parsing stopped, as ` (at byte offset N)`, or `""` when the
  * runtime did not name one.
  *
- * WHY THIS IS A DIGIT EXTRACTOR AND NOT A MESSAGE PASS-THROUGH (CR-03). V8's
+ * WHY THIS IS A DIGIT EXTRACTOR AND NOT A MESSAGE PASS-THROUGH. V8's
  * JSON `SyntaxError` embeds a SNIPPET OF THE INPUT in its own message --
  * `Unexpected token 'Q', "QQZZORACLE"... is not valid JSON` -- so any code
  * that forwards `err.message` from a JSON parse over caller-supplied bytes is
  * a content-disclosure oracle. The capture group here is `(\d+)` and nothing
  * else, so no byte of the parsed file can reach the returned string however
  * the runtime words its message. Widening this regex to capture anything but
- * digits reopens CR-03.
+ * digits reopens the same content-disclosure risk.
  *
  * Returns `""` rather than guessing when no position is present (`Unexpected
  * end of JSON input` carries none) -- an absent offset is reported by absence,
@@ -280,9 +281,9 @@ export function parseProvenanceHeader(json: unknown): ProvenanceHeader {
  * distinguishable from drift under the same one.
  *
  * Version 2 (260821-a86) escaped Markdown table cells via
- * `escapeMarkdownCell()` -- WR-04, an output-shape change.
+ * `escapeMarkdownCell()`, an output-shape change.
  *
- * Version 3 (D-17) is an INPUT change: `computeRenderDigest()` canonicalises
+ * Version 3 is an INPUT change: `computeRenderDigest()` canonicalises
  * this store's own `RangeRow`/`LabelRow`/`CommentRow` instead of the three
  * wire shapes recorded above, so the same underlying annotations hash
  * differently either side of it. Leaving the version at "2" across that
@@ -298,7 +299,7 @@ export const RENDERER_VERSION = "3";
  * other leg), because comment `evidence` legitimately contains `|` and
  * embedded newlines (`anno_set_comment`'s own schema documents multi-line
  * support) -- refusing here would refuse valid data, not an attack. Closes
- * WR-04 / T-11-NAME-INJECT's render leg: an unescaped `|` or newline in
+ * this control's own render leg of T-11-NAME-INJECT: an unescaped `|` or newline in
  * store text used to be able to inject an extra table cell or split a row
  * across lines in the generated Markdown. A plain string or an empty string
  * is returned unchanged. */
@@ -348,7 +349,7 @@ export interface RenderMemoryMapOptions {
    *  reaching an equally real `readFileSync`, carried nothing -- so a reader
    *  comparing the two would reasonably conclude the difference was
    *  deliberate. It was not: the CLI read this argument raw, making it an
-   *  arbitrary-file read oracle (`29-REVIEW.md` CR-03). An absent comment
+   *  arbitrary-file read oracle. An absent comment
    *  beside a present one is a claim, and this one was false. */
   provenancePath: string;
   /** The workspace root both confinement checks are taken against. REQUIRED
@@ -396,7 +397,7 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
   try {
     sidecarJson = JSON.parse(sidecarBytes);
   } catch (err) {
-    // NEVER INTERPOLATE THE UNDERLYING PARSE ERROR HERE (CR-03). Node's
+    // NEVER INTERPOLATE THE UNDERLYING PARSE ERROR HERE. Node's
     // SyntaxError quotes a snippet of the input it choked on -- e.g.
     // `Unexpected token 'Q', "QQZZORACLE"... is not valid JSON` -- so passing
     // it through turns a read refusal into a CONTENT-DISCLOSURE ORACLE. That
@@ -410,7 +411,7 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
     // where parsing stopped and not about what the file contains.
     throw new Error(
       `renderMemoryMap: provenance sidecar at "${provenancePath}" is not valid JSON${jsonParsePosition(err)}. ` +
-        "The underlying parser message is deliberately NOT included -- it quotes the file's own bytes (CR-03).",
+        "The underlying parser message is deliberately NOT included -- it quotes the file's own bytes.",
     );
   }
   const provenance = parseProvenanceHeader(sidecarJson);
@@ -460,7 +461,7 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
   // load-bearing detail rather than a formatting preference: every byte below
   // is re-rendered and compared BYTE FOR BYTE by `checkRenderedMemoryMap()`,
   // so an absolute path here would make the drift verdict a function of where
-  // the checkout sits (CR-01). `workspaceRelativePath()` is the one definition
+  // the checkout sits. `workspaceRelativePath()` is the one definition
   // of that spelling; it computes a location and refuses one that escapes the
   // root. It is NOT a confinement check -- this module still performs no
   // confinement of its own, exactly as `RenderMemoryMapOptions` documents.
@@ -587,13 +588,13 @@ export interface CheckRenderedMemoryMapOptions {
   /** See `RenderMemoryMapOptions.provenancePath` -- same argument, one layer
    *  up. The CALLER (`anno-cli.ts`'s `cmdRenderMemmap()`) confines it through
    *  `storePathWithinWorkspace()`; this module performs no confinement of its
-   *  own (CR-03). */
+   *  own. */
   provenancePath: string;
   /** The rendered file to compare against, read RAW by `readFileSync` below.
    *  The CALLER confines it through `storePathWithinWorkspace()` -- the SAME
    *  resolution that produces the write path on the non-`--check` branch, so
    *  the drift check and the write are one confined value rather than two
-   *  rules. This module performs no confinement of its own (CR-02). */
+   *  rules. This module performs no confinement of its own. */
   renderedPath: string;
   /** See `RenderMemoryMapOptions.workspaceRoot`. */
   workspaceRoot: string;
@@ -626,8 +627,8 @@ export type CheckRenderedMemoryMapResult =
  *     the workspace root;
  *   - a renderer change (output shape, or a `RENDERER_VERSION` bump).
  *
- * AND THE NEGATIVE, which is the defect this list was corrected for (CR-01,
- * `29-VERIFICATION.md` gap 1): relocating the checkout -- the same tree at a
+ * AND THE NEGATIVE, which is the defect this list was corrected for: relocating
+ * the checkout -- the same tree at a
  * different absolute path -- does NOT drift. The banner records
  * workspace-relative locations, so no compared byte is a function of where the
  * checkout sits. Before that fix this returned `drifted` for a byte-identical

package/anno-provenance-ledger.ts

@@ -1,14 +1,14 @@
 // anno-provenance-ledger.ts -- the ONE place `recovery/PROVENANCE.md`'s
-// generated tier is turned back into typed rows (BUILD-05, phase 46 plan 01).
+// generated tier is turned back into typed rows.
 //
 // ---------------------------------------------------------------------------
 // WHY THIS FILE EXISTS
 // ---------------------------------------------------------------------------
 // Nothing in this repository has ever READ the provenance ledger. It has one
 // writer -- `renderLedger()` in `src/skills/c64-provenance-diff/scripts/
-// diff-images.mjs` -- and zero readers, because BUILD-05's own text requires
-// the verdict be READ from the existing ledger, "never re-derived"
-// (assumption A2, `46-01-PLAN.md`). Recomputing it in-process would force the
+// diff-images.mjs` -- and zero readers, because the requirement governing this
+// module requires the verdict be READ from the existing ledger, "never
+// re-derived". Recomputing it in-process would force the
 // exporter to import a registry-resolution path it has no other reason to
 // know about, and would make "ledger absent" ambiguous between three
 // different missing things. This module exists so "read" has an implementation

package/anno-regbits-gen.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // anno-regbits-gen.ts -- the ONE authoritative place in this repo that turns
 // c64-memory-mapping's memmap.json into the curated address->bit-name table
-// anno-enum-gen.ts decodes register values against (D-22, ANNO-13).
+// anno-enum-gen.ts decodes register values against.
 //
-// WHY THIS EXISTS (D-22): neither register the phase's own pinned criterion-3
+// WHY THIS EXISTS: neither register the phase's own pinned criterion-3
 // target needs ($D011) nor the registers a real game writes to constantly
 // ($D015/$D017/$D01A-$D01D) can be named from memmap.json's own `bits` prose
 // alone -- some of that prose is OCR-damaged ("O = Blank" uses a letter O for
@@ -54,11 +54,11 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 
 /** The sole read of c64-memory-mapping's own memmap.json -- this generator is
  * its only consumer for this purpose (per this plan's key_links entry).
- * 2026-08-22 (plan 16-01): the skills tree moved from `.claude/skills/`
+ * 2026-08-22: the skills tree moved from `.claude/skills/`
  * (two levels up from `.claude/mcp/vice`) to `src/skills/` (three levels up,
  * since `src/` sits directly under the repo root rather than under `.claude/`).
- * This literal was not in plan 16-01's own enumerated consumer list and its
- * test failures caught the gap live -- see 16-01-SUMMARY.md deviations. */
+ * This literal was not in the original enumerated consumer list, and a
+ * test failure caught the gap live. */
 const MEMMAP_PATH = join(HERE, "..", "..", "..", "src", "skills", "c64-memory-mapping", "memmap.json");
 
 /** Where the generated, committed artifact lives -- always a sibling of this
@@ -163,14 +163,14 @@ export interface RegbitsRegisterOverride {
    * entries by their `bit` string. */
   fields?: readonly RegbitsFieldOverride[];
   /** A COMPLETE field list for an address memmap.json's `io` parser produced
-   * no `bits` entry for at all (D-22's known gap) -- used only when no
+   * no `bits` entry for at all -- used only when no
    * memmap entry exists for this address, never to replace one that does. */
   synthetic?: readonly RegBitsField[];
 }
 
 /** Builds the 8 independent "bit N = sprite N" flag fields the five VIC
  * sprite-plane registers ($D015/$D017/$D01B/$D01C/$D01D) all share the same
- * shape for (D-22's named gap) -- each bit is silent (empty token) when
+ * shape for -- each bit is silent (empty token) when
  * clear and names the specific sprite when set, so a typical enum (most
  * sprites off, one or two on) renders as a short, readable name instead of
  * naming all eight sprites' negative state every time.
@@ -236,15 +236,15 @@ export const OVERRIDES: readonly RegbitsRegisterOverride[] = [
     label: "CIA Interrupt Control Register (Read NMIs/Write Mask)",
   },
   {
-    // WHY: memmap.json's `io` parser produced no `bits` entry at all for this address (D-22's
-    // named gap) even though a real game writes to it constantly -- sprite enable, one flag bit
+    // WHY: memmap.json's `io` parser produced no `bits` entry at all for this address,
+    // even though a real game writes to it constantly -- sprite enable, one flag bit
     // per sprite, is trivially regular and does not need memmap's own prose to describe correctly.
     address: 53269, // $D015 -- Sprite Enable
     label: "Sprite Enable",
     synthetic: spriteBitFields("EN"),
   },
   {
-    // WHY: same D-22 gap as $D015 -- Sprite Y-Expand, one flag bit per sprite.
+    // WHY: same missing-`bits`-entry gap as $D015 -- Sprite Y-Expand, one flag bit per sprite.
     address: 53271, // $D017 -- Sprite Y-Expand
     label: "Sprite Y-Expand",
     synthetic: spriteBitFields("YEXP"),
@@ -264,20 +264,20 @@ export const OVERRIDES: readonly RegbitsRegisterOverride[] = [
     ],
   },
   {
-    // WHY: same D-22 gap as $D015 -- Sprite Priority (behind/in-front of background), one flag bit
+    // WHY: same missing-`bits`-entry gap as $D015 -- Sprite Priority (behind/in-front of background), one flag bit
     // per sprite.
     address: 53275, // $D01B -- Sprite Data Priority
     label: "Sprite Data Priority",
     synthetic: spriteBitFields("BG"),
   },
   {
-    // WHY: same D-22 gap as $D015 -- Sprite Multicolor, one flag bit per sprite.
+    // WHY: same missing-`bits`-entry gap as $D015 -- Sprite Multicolor, one flag bit per sprite.
     address: 53276, // $D01C -- Sprite Multicolor
     label: "Sprite Multicolor",
     synthetic: spriteBitFields("MC"),
   },
   {
-    // WHY: same D-22 gap as $D015 -- Sprite X-Expand, one flag bit per sprite.
+    // WHY: same missing-`bits`-entry gap as $D015 -- Sprite X-Expand, one flag bit per sprite.
     address: 53277, // $D01D -- Sprite X-Expand
     label: "Sprite X-Expand",
     synthetic: spriteBitFields("XEXP"),

package/anno-store-export.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // anno-store-export.ts
 //
-// Phase 45, plan 45-02 (D-02): the general JSON export/import module for a
+// The general JSON export/import module for a
 // per-fixture `.annostore` -- NOT Ghidra-shaped (that is `anno-import.ts`'s
 // job, and it writes cross-references only). No general store-JSON round
 // trip exists anywhere else in this tree today (RESEARCH.md Section 5,
@@ -16,7 +16,7 @@
 //
 // WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR:
 //   - The JSON schema for a full store export: typed ranges, labels,
-//     comments (tagged `provenance: "derived" | "authored"` per D-03),
+//     comments (tagged `provenance: "derived" | "authored"`),
 //     project enums and their usage bindings, cross-references, and
 //     runtime-execution-observation rows.
 //   - The three decline/provenance comment-text conventions
@@ -33,7 +33,7 @@
 //     successfully (`anno-import.ts`'s own rule, copied deliberately: a
 //     partial import must never leave the store in a state that is neither
 //     the old nor the new content).
-//   - Never collapse the derived/authored provenance tag (D-03) -- the
+//   - Never collapse the derived/authored provenance tag -- the
 //     export schema exists specifically so a diff shows an authored
 //     purpose-comment change, which a binary `.annostore` cannot.
 //   - Never resolve a workspace path here -- the caller does, through
@@ -41,11 +41,11 @@
 //   - Never persist `provenance` as a real store column. It is NOT one:
 //     `RangeRow`/`CommentRow` (`anno-types.ts`) carry no such field, and
 //     `setDataType()`/`setComment()` accept no such argument. Ranges are
-//     ALWAYS the derived half (D-03: "block types ... regenerate
+//     ALWAYS the derived half ("block types ... regenerate
 //     deterministically from the bytes") -- there is no per-row fact in the
 //     schema that could ever make one authored instead, so `"derived"` is a
 //     constant for every exported range, not a per-row classification.
-//     Comments are ALWAYS the authored half (D-03, confirmed again by
+//     Comments are ALWAYS the authored half (confirmed again by
 //     RESEARCH.md Section 5: "labels/comments/(and ... decline-comments) are
 //     the authored half") -- `provenanceForComment()` is written as a
 //     function of the comment's own text (rather than a bare constant) only
@@ -123,7 +123,7 @@ import type { DataType, CommentType, LabelKind, XrefAccessKind, EvidSourceBank }
  * standing decline-by-name pattern), never best-effort imported. */
 export const STORE_EXPORT_SCHEMA_VERSION = 1;
 
-/** The two provenance classes D-03 splits the store into. See this file's
+/** The two provenance classes the store is split into (derived vs authored). See this file's
  * own header for why this is never a real store column. */
 export type RowProvenance = "derived" | "authored";
 
@@ -137,7 +137,7 @@ export const DECLINE_COMMENT_PREFIX = "DECLINED:";
  * reviewed and chose to accept rather than reclassify. */
 export const DISAGREEMENT_ACCEPTED_COMMENT_PREFIX = "DISAGREEMENT-ACCEPTED:";
 
-/** D-10's per-range authored marker: an explicit statement that a range's
+/** The per-range authored marker: an explicit statement that a range's
  * typing rests on authored judgement rather than derivation or runtime
  * observation. */
 export const AUTHORED_PROVENANCE_COMMENT_PREFIX = "PROVENANCE: authored";
@@ -227,7 +227,7 @@ export interface StoreExportXrefRow {
  * and no `provenance`: `ScopeRow` (`anno-types.ts`) is a bare `{id, start,
  * endInclusive}` -- a lexical region, not a memory view, and not itself
  * derived from or authored over bytes the way a range or a comment is. Added
- * for the multi-file export path (Phase 47): `exportAsmTree()` reads scopes
+ * for the multi-file export path: `exportAsmTree()` reads scopes
  * straight off an open store handle via `listScopes()`, never from this
  * document, so a scope this generic export omitted would silently vanish the
  * moment a committed export got re-imported into a fresh store ahead of that
@@ -314,7 +314,7 @@ function assertRowProvenance(value: unknown, what: string): RowProvenance {
 }
 
 /**
- * 45-REVIEW WR-01's fix: `bank` is exported faithfully by `exportStoreDocument()`
+ * This fix: `bank` is exported faithfully by `exportStoreDocument()`
  * for every row kind (`StoreExportRangeRow.bank`, `StoreExportLabelRow.bank`,
  * `StoreExportCommentRow.bank`, `StoreExportEnumUsageRow.bank`,
  * `StoreExportXrefRow.bank`), but no write call on `anno-store.ts`'s current
@@ -322,8 +322,8 @@ function assertRowProvenance(value: unknown, what: string): RowProvenance {
  * accepts a `bank` argument -- every fresh insert hard-codes `bank: null`
  * (`anno-store.ts:1890`). Threading a real value through five write calls with
  * no bank-carrying writer anywhere in the codebase to prove it against would be
- * exactly the kind of speculative widening this project's other modules refuse
- * (D-10's "narrower than the review's own sketch" pattern). Refusing a non-null
+ * exactly the kind of speculative widening this project's other modules refuse.
+ * Refusing a non-null
  * `bank` BY NAME instead -- this project's standing "refuse by name, never
  * silently drop" convention (`enumUsage[i]` naming an undefined enum, above, is
  * the same shape) -- means the moment a real writer starts producing a