@henols/vice-mcp 0.2.1 → 0.2.2

package/{r2000-memmap-render.ts → anno-memmap-render.ts}

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-// r2000-memmap-render.ts -- the ONE authoritative place in this repo that
-// renders the human-readable Markdown memory map from the r2000 annotation
-// store (D-24) plus a validated run-scoped provenance sidecar (D-27's
-// reconciliation, recorded in 11-10-PLAN.md's objective).
+// 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).
 //
 // WHY THIS MODULE EXISTS (D-24): 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
 // downstream of this module may hand-author an address row: every row in
-// the Range/Contents/Confidence/Evidence table comes from
-// `r2000_get_blocks`/`r2000_get_symbols`/`r2000_get_comments`, never from a
+// the Range/Contents/Confidence/Evidence table comes from the store's own
+// `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
@@ -66,49 +66,65 @@
 import { existsSync, readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 
-import { runR2000Tool } from "./r2000-tools.ts";
-import { CONFIDENCE_GRADES, parseConfidencePrefix } from "./r2000-confidence.ts";
-import type { ConfidenceGrade } from "./r2000-confidence.ts";
-
-function errMsg(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
+import { CONFIDENCE_GRADES, parseConfidencePrefix } from "./anno-confidence.ts";
+import type { ConfidenceGrade } from "./anno-confidence.ts";
+import { openStore, closeStore, listRanges, listLabels, listComments } from "./anno-store.ts";
+import { COMMENT_TYPES, workspaceRelativePath } from "./anno-types.ts";
+import type { CommentRow, LabelRow, RangeRow } from "./anno-types.ts";
+import { blockClassAt } from "./block-class.ts";
 
 // ---------------------------------------------------------------------------
-// The r2000 query result shapes this renderer consumes, measured live
-// against a real regenerator2000-core-0.9.20 `--mcp-server-stdio` child
-// (never transcribed from a document): `r2000_get_blocks` returns
-// `{start_address, end_address, type}`; `r2000_get_symbols` returns
-// `{address, name, kind, type}`; `r2000_get_comments` returns
-// `{address, comment, type}`.
+// WHAT THE VERSION-2 DIGEST HASHED -- the provenance of a lineage this
+// renderer no longer reads. Version 2 hashed three wire result shapes
+// measured LIVE against a real external-analyser-core-0.9.20
+// `--mcp-server-stdio` child, never transcribed from a document:
+// `anno_get_blocks` returned `{start_address, end_address, type}`,
+// `anno_get_symbols` returned `{address, name, kind, type}`, and
+// `anno_get_comments` returned `{address, comment, type}`.
+//
+// THIS PARAGRAPH IS THE RECORD, not a pointer at one. The three `interface`
+// declarations it used to sit above went with the queries, so the spellings
+// are carried here inline rather than left as a comment above a hole. It
+// survives because `RENDERER_VERSION`'s "2" -> "3" bump is a statement about
+// TWO KNOWN input shapes -- version 3 canonicalises this store's own
+// `RangeRow`/`LabelRow`/`CommentRow` -- and that statement is only true
+// while the older one is on the record. Delete this and the bump names one
+// known input shape and one assumed one.
 // ---------------------------------------------------------------------------
 
-interface R2000Block {
-  start_address: number;
-  end_address: number;
-  type: string;
-}
-
-interface R2000Symbol {
-  address: number;
-  name: string;
-  kind: string;
-  type: string;
+function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
 }
 
-interface R2000Comment {
-  address: number;
-  comment: string;
-  type: "line" | "side";
+/**
+ * The ONE piece of a `JSON.parse` failure that is safe to report: the byte
+ * 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
+ * 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.
+ *
+ * Returns `""` rather than guessing when no position is present (`Unexpected
+ * end of JSON input` carries none) -- an absent offset is reported by absence,
+ * never by a fabricated zero.
+ */
+function jsonParsePosition(err: unknown): string {
+  const match = /\bat position (\d+)\b/.exec(errMsg(err));
+  return match ? ` (at byte offset ${match[1]})` : "";
 }
 
-async function queryR2000Json<T>(name: string, args: Record<string, unknown>): Promise<T> {
-  const result = await runR2000Tool(name, args);
-  if (result.isError) {
-    throw new Error(`${name} failed: ${result.content[0]?.text ?? "(no message)"}`);
-  }
-  return JSON.parse(result.content[0]!.text) as T;
-}
+/** The store's own spelling for a comment placed on its own line before the
+ * instruction, read out of `COMMENT_TYPES` -- the ONE home of that
+ * vocabulary -- rather than re-typed as a literal here. The pre-store
+ * renderer passed `type: "line"` to its comment query; this is that filter,
+ * moved to the read boundary. */
+const [LINE_COMMENT] = COMMENT_TYPES;
 
 // ---------------------------------------------------------------------------
 // The provenance sidecar schema.
@@ -159,14 +175,14 @@ const REQUIRED_STRING_KEYS: readonly (keyof ProvenanceHeader)[] = [
  * copied into a sidecar by accident. */
 const PLACEHOLDER_PATTERN = /^<.*>$/;
 
-export class R2000ProvenanceHeaderError extends Error {
+export class AnnoProvenanceHeaderError extends Error {
   /** Every problem found, one entry per offending key -- a caller filling a
    * sidecar wants the whole list, not one problem at a time. */
   problems: readonly string[];
 
   constructor(message: string, problems: readonly string[]) {
     super(message);
-    this.name = "R2000ProvenanceHeaderError";
+    this.name = "AnnoProvenanceHeaderError";
     this.problems = problems;
   }
 }
@@ -175,14 +191,14 @@ export class R2000ProvenanceHeaderError extends Error {
  * Parses and validates a provenance sidecar. Collects EVERY problem (a
  * missing key, a non-string value, a template placeholder, a malformed
  * `captureSha256`, an invalid `videoStandard`, a malformed
- * `rasterPositions`) into one list and throws `R2000ProvenanceHeaderError`
+ * `rasterPositions`) into one list and throws `AnnoProvenanceHeaderError`
  * naming all of them at once -- never one at a time.
  */
 export function parseProvenanceHeader(json: unknown): ProvenanceHeader {
   const problems: string[] = [];
 
   if (typeof json !== "object" || json === null || Array.isArray(json)) {
-    throw new R2000ProvenanceHeaderError(
+    throw new AnnoProvenanceHeaderError(
       `provenance sidecar must be a JSON object, got ${Array.isArray(json) ? "an array" : typeof json}`,
       ["<root>: must be a JSON object"],
     );
@@ -225,7 +241,7 @@ export function parseProvenanceHeader(json: unknown): ProvenanceHeader {
   }
 
   if (problems.length > 0) {
-    throw new R2000ProvenanceHeaderError(
+    throw new AnnoProvenanceHeaderError(
       `provenance sidecar has ${problems.length} problem(s):\n` + problems.map((p) => `  - ${p}`).join("\n"),
       problems,
     );
@@ -250,8 +266,8 @@ export function parseProvenanceHeader(json: unknown): ProvenanceHeader {
 // ---------------------------------------------------------------------------
 // The render digest -- documented exactly, because a digest whose inputs are
 // unclear is a digest nobody trusts. It covers, in order: a canonical JSON
-// serialisation of the SORTED `r2000_get_blocks`/`r2000_get_symbols`/
-// `r2000_get_comments` results (so a store-side change, e.g. a comment's
+// serialisation of the SORTED `listRanges()`/`listLabels()`/
+// `listComments()` store rows (so a store-side change, e.g. a comment's
 // confidence grade, changes the digest even with the rendered file
 // untouched), the raw provenance sidecar BYTES (not the parsed object, so
 // even whitespace-only sidecar edits are covered), and this renderer's own
@@ -259,20 +275,28 @@ export function parseProvenanceHeader(json: unknown): ProvenanceHeader {
 // hand edit).
 // ---------------------------------------------------------------------------
 
-/** Bumped whenever this renderer's OUTPUT SHAPE changes, so a re-render
- * under a new renderer version is distinguishable from drift under the same
- * one. Version 2 (this plan, 260821-a86) escapes Markdown table cells via
- * `escapeMarkdownCell()` -- WR-04. */
-export const RENDERER_VERSION = "2";
+/** Bumped whenever this renderer's OUTPUT SHAPE **or its digest's canonical
+ * INPUT** changes, so a re-render under a new renderer version is
+ * distinguishable from drift under the same one.
+ *
+ * Version 2 (260821-a86) escaped Markdown table cells via
+ * `escapeMarkdownCell()` -- WR-04, an output-shape change.
+ *
+ * Version 3 (D-17) 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
+ * boundary would let two incompatible renderings compare as ordinary drift. */
+export const RENDERER_VERSION = "3";
 
 /**
  * Escapes `text` for safe interpolation into a Markdown table cell or list
  * item: every `|` becomes `\|`, and every `\r\n`/`\n`/bare `\r` collapses to
  * `<br>` (a single-line-safe line break inside a table cell). This control
  * ESCAPES and never REJECTS -- unlike the label-name policy
- * (`r2000-acme-ident.ts`'s `assertLegalAcmeIdentifier()`, T-11-NAME-INJECT's
+ * (`anno-acme-ident.ts`'s `assertLegalAcmeIdentifier()`, T-11-NAME-INJECT's
  * other leg), because comment `evidence` legitimately contains `|` and
- * embedded newlines (`r2000_set_comment`'s own schema documents multi-line
+ * 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
  * store text used to be able to inject an extra table cell or split a row
@@ -283,9 +307,9 @@ export function escapeMarkdownCell(text: string): string {
 }
 
 function computeRenderDigest(
-  blocks: readonly R2000Block[],
-  symbols: readonly R2000Symbol[],
-  comments: readonly R2000Comment[],
+  blocks: readonly RangeRow[],
+  symbols: readonly LabelRow[],
+  comments: readonly CommentRow[],
   sidecarBytes: string,
 ): string {
   const canonical = JSON.stringify({ blocks, symbols, comments }) + "" + sidecarBytes + "" + RENDERER_VERSION;
@@ -307,8 +331,31 @@ interface GradedComment {
 // ---------------------------------------------------------------------------
 
 export interface RenderMemoryMapOptions {
-  projectPath: string;
+  /** The annotation store to render. The CALLER confines it through
+   *  `storePathWithinWorkspace()` and `openStore()` below confines it again
+   *  against the same `workspaceRoot`, so both answers agree by construction
+   *  rather than by a second rule (T-29-51). */
+  storePath: string;
+  /** The provenance sidecar to render from. The CALLER confines it through
+   *  `storePathWithinWorkspace()` before entering this module -- today that
+   *  caller is `anno-cli.ts`'s `cmdRenderMemmap()`. THIS MODULE PERFORMS NO
+   *  CONFINEMENT OF ITS OWN, and must never be handed a path that has not
+   *  been through that seam.
+   *
+   *  THIS FIELD WAS DOCUMENTED BY SILENCE, and the silence is what the review
+   *  names as the mechanism. `storePath` one line above carried four lines
+   *  stating who confines it; this field, an equally caller-supplied path
+   *  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
+   *  beside a present one is a claim, and this one was false. */
   provenancePath: string;
+  /** The workspace root both confinement checks are taken against. REQUIRED
+   *  rather than defaulted: `openStore()`'s default behaviour is to CREATE
+   *  the file, so an unconfined store path is a store file created wherever
+   *  the caller's argument pointed. */
+  workspaceRoot: string;
 }
 
 export interface RenderMemoryMapResult {
@@ -321,11 +368,14 @@ export interface RenderMemoryMapResult {
 }
 
 /**
- * Renders the memory map from the r2000 store plus a validated provenance
- * sidecar. Queries `r2000_get_blocks`/`r2000_get_symbols`/`r2000_get_comments`
- * through `r2000-tools.ts`'s curated, allow-listed `runR2000Tool()` -- never
- * `r2000-mcp-client.ts` directly (mirrors every other consumer's discipline
- * in this repo).
+ * Renders the memory map from an annotation store plus a validated
+ * provenance sidecar. Reads the store DIRECTLY -- `listRanges()`,
+ * `listLabels()` and `listComments()` on ONE handle, opened once per render
+ * and closed in a `finally` -- with no child process anywhere on this path.
+ *
+ * The store's block-kind spelling is interpreted in exactly one place,
+ * `block-class.ts`'s `blockClassAt()`; nothing below compares a
+ * `dataType` string itself.
  *
  * A malformed confidence prefix inside a store comment (a typo that survived
  * whatever wrote it) THROWS through `parseConfidencePrefix()` -- this
@@ -333,7 +383,7 @@ export interface RenderMemoryMapResult {
  * must be fixed in the store, not hidden in the rendered view.
  */
 export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<RenderMemoryMapResult> {
-  const { projectPath, provenancePath } = opts;
+  const { storePath, provenancePath, workspaceRoot } = opts;
 
   let sidecarBytes: string;
   try {
@@ -346,23 +396,57 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
   try {
     sidecarJson = JSON.parse(sidecarBytes);
   } catch (err) {
-    throw new Error(`renderMemoryMap: provenance sidecar at "${provenancePath}" is not valid JSON: ${errMsg(err)}`);
+    // NEVER INTERPOLATE THE UNDERLYING PARSE ERROR HERE (CR-03). 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
+    // matters here specifically because this argument arrives from an
+    // agent-composed Bash invocation: the shipped playbooks tell an LLM to
+    // compose this path, so the error text is read by whatever composed it.
+    //
+    // What survives is everything a caller legitimately needs to fix the
+    // problem: WHICH file, and THAT it is not JSON. The byte OFFSET is
+    // included where Node exposes one, because a position is a fact about
+    // 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).",
+    );
   }
   const provenance = parseProvenanceHeader(sidecarJson);
 
-  const blocks = await queryR2000Json<R2000Block[]>("r2000_get_blocks", { project: projectPath });
-  const symbols = await queryR2000Json<R2000Symbol[]>("r2000_get_symbols", { project: projectPath });
-  const comments = await queryR2000Json<R2000Comment[]>("r2000_get_comments", {
-    project: projectPath,
-    type: "line",
-  });
+  // ONE handle for the whole render, closed in a `finally`. `mustExist` is
+  // what makes "the annotations are gone" and "there are no annotations"
+  // refuse differently (T-29-52): without it a mistyped path would CREATE an
+  // empty store and render as an empty memory map indistinguishable from a
+  // real one.
+  const handle = openStore(storePath, { workspaceRoot, mustExist: true });
+  let ranges: RangeRow[];
+  let labels: LabelRow[];
+  let lineComments: CommentRow[];
+  try {
+    ranges = listRanges(handle);
+    labels = listLabels(handle);
+    lineComments = listComments(handle).filter((c) => c.commentType === LINE_COMMENT);
+  } finally {
+    closeStore(handle);
+  }
 
-  const sortedBlocks = [...blocks].sort((a, b) => a.start_address - b.start_address);
-  const sortedSymbols = [...symbols].sort((a, b) => a.address - b.address);
-  const sortedComments = [...comments].sort((a, b) => a.address - b.address);
+  const sortedBlocks = [...ranges].sort((a, b) => a.start - b.start);
+  const sortedSymbols = [...labels].sort((a, b) => a.address - b.address);
+  const sortedComments = [...lineComments].sort((a, b) => a.address - b.address);
+
+  // The block listing in `block-class.ts`'s own entry shape. The `dataType`
+  // column is copied VERBATIM and never compared here -- that module is the
+  // one place in this tree allowed to interpret it.
+  const blockEntries = sortedBlocks.map((row) => ({
+    start_address: row.start,
+    end_address: row.endInclusive,
+    type: row.dataType as string,
+  }));
 
   const gradedComments: GradedComment[] = sortedComments.map((c) => {
-    const parsed = parseConfidencePrefix(c.comment);
+    const parsed = parseConfidencePrefix(c.text);
     return { address: c.address, grade: parsed.grade, evidence: parsed.rest };
   });
 
@@ -372,20 +456,46 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
 
   const renderDigest = computeRenderDigest(sortedBlocks, sortedSymbols, sortedComments, sidecarBytes);
 
+  // The two recorded locations are WORKSPACE-RELATIVE, and that is the
+  // 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
+  // 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.
+  const storeLocation = workspaceRelativePath(storePath, workspaceRoot);
+  const sidecarLocation = workspaceRelativePath(provenancePath, workspaceRoot);
+
   const lines: string[] = [];
 
   lines.push("<!--");
-  lines.push("  GENERATED by `vice-mcp r2000 render-memmap` -- do not hand-edit; re-run the generator.");
-  lines.push(`  store: ${projectPath}`);
-  lines.push(`  sidecar: ${provenancePath}`);
+  lines.push("  GENERATED by `vice-mcp anno render-memmap` -- do not hand-edit; re-run the generator.");
+  lines.push(`  store: ${storeLocation}`);
+  lines.push(`  sidecar: ${sidecarLocation}`);
   lines.push(`  render_digest: ${renderDigest}`);
   lines.push(
-    "  The digest covers the sorted r2000_get_blocks/r2000_get_symbols/r2000_get_comments results, the",
+    "  The digest covers the sorted listRanges/listLabels/listComments results, the raw provenance",
   );
   lines.push(
-    "  raw provenance sidecar bytes, and this renderer's version constant -- so either a hand edit or a",
+    "  sidecar bytes, and this renderer's version constant. `render-memmap --check` reports drift when, and",
   );
-  lines.push("  store-side change (e.g. a comment's confidence grade) is detected by `render-memmap --check`.");
+  lines.push(
+    "  only when, one of these changed: this file was hand-edited; a store row changed (a range, a label, a",
+  );
+  lines.push(
+    "  comment, or a comment's confidence grade); the provenance sidecar's bytes changed; the store or the",
+  );
+  lines.push(
+    "  sidecar moved to a different location RELATIVE TO THE WORKSPACE ROOT; or the renderer changed.",
+  );
+  lines.push(
+    "  Relocating the checkout is NOT drift -- the same tree at a different absolute path renders these same",
+  );
+  lines.push(
+    "  bytes, because the two locations above are workspace-relative. That matters because this file is meant",
+  );
+  lines.push("  to be committed and read on a machine that did not produce it.");
   lines.push("-->");
   lines.push("");
   lines.push(`# Memory map — ${provenance.capturePath}`);
@@ -403,12 +513,12 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
   lines.push("");
   lines.push("| Range | Contents | Confidence | Evidence |");
   lines.push("|---|---|---|---|");
-  for (const block of sortedBlocks) {
-    const match = findGradeInRange(block.start_address, block.end_address);
-    const range = `\`${hex4(block.start_address)}-${hex4(block.end_address)}\``;
+  for (const row of sortedBlocks) {
+    const match = findGradeInRange(row.start, row.endInclusive);
+    const range = `\`${hex4(row.start)}-${hex4(row.endInclusive)}\``;
     const grade = match?.grade ? match.grade.phrase.toUpperCase() : "";
     const evidence = match ? escapeMarkdownCell(match.evidence) : "";
-    lines.push(`| ${range} | ${block.type} | ${grade} | ${evidence} |`);
+    lines.push(`| ${range} | ${row.dataType} | ${grade} | ${evidence} |`);
   }
   lines.push("");
   lines.push("Confidence vocabulary — the project's HIGH / MEDIUM / LOW scale, applied to classification:");
@@ -443,10 +553,8 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
   lines.push("");
   lines.push("| Address | Provisional name | Confirmed by | Confidence |");
   lines.push("|---|---|---|---|");
-  const codeBlocks = sortedBlocks.filter((b) => b.type === "Code");
   for (const sym of sortedSymbols) {
-    const inCode = codeBlocks.some((b) => sym.address >= b.start_address && sym.address <= b.end_address);
-    if (!inCode) continue;
+    if (blockClassAt(blockEntries, sym.address) !== "code") continue;
     const match = gradedComments.find((c) => c.address === sym.address);
     const grade = match?.grade ? match.grade.phrase.toUpperCase() : "";
     const confirmedBy = match ? escapeMarkdownCell(match.evidence) : "";
@@ -474,9 +582,21 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
 // ---------------------------------------------------------------------------
 
 export interface CheckRenderedMemoryMapOptions {
-  projectPath: string;
+  /** See `RenderMemoryMapOptions.storePath`. */
+  storePath: string;
+  /** 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). */
   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). */
   renderedPath: string;
+  /** See `RenderMemoryMapOptions.workspaceRoot`. */
+  workspaceRoot: string;
 }
 
 export type CheckRenderedMemoryMapResult =
@@ -492,21 +612,42 @@ export type CheckRenderedMemoryMapResult =
  *   - `{status:"in-sync"}` when the freshly rendered text is byte-identical
  *     to the file on disk;
  *   - `{status:"drifted", line, expected, actual}` naming the first
- *     differing line otherwise -- reached by EITHER a hand edit to the file
- *     OR a store-side change (a label, a comment, a block) since the file
- *     was last rendered, because both change what a fresh render produces.
+ *     differing line otherwise.
+ *
+ * WHAT REACHES `drifted`, enumerated from what the compared bytes are a
+ * function of rather than from a remembered summary -- the fresh render is a
+ * function of the store rows, the sidecar bytes, `RENDERER_VERSION` and the
+ * two WORKSPACE-RELATIVE locations, and nothing else:
+ *   - a hand edit to the rendered file;
+ *   - a store-side change (a range, a label, a comment, or a comment's
+ *     confidence grade);
+ *   - a change to the provenance sidecar's bytes;
+ *   - a move of the store or the sidecar to a different location RELATIVE TO
+ *     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
+ * 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
+ * store, sidecar and rendered file while `renderMemoryMap()` printed the SAME
+ * `render_digest` in both trees, so the gate contradicted its own artifact.
+ * That matters here specifically because the rendered file is a committed
+ * artifact and this repository runs its phases in worktrees, which makes a
+ * differing checkout path the normal case rather than an edge.
  */
 export async function checkRenderedMemoryMap(
   opts: CheckRenderedMemoryMapOptions,
 ): Promise<CheckRenderedMemoryMapResult> {
-  const { projectPath, provenancePath, renderedPath } = opts;
+  const { storePath, provenancePath, renderedPath, workspaceRoot } = opts;
 
   if (!existsSync(renderedPath)) {
     return { status: "missing", path: renderedPath };
   }
 
   const onDisk = readFileSync(renderedPath, "utf8");
-  const { markdown } = await renderMemoryMap({ projectPath, provenancePath });
+  const { markdown } = await renderMemoryMap({ storePath, provenancePath, workspaceRoot });
 
   if (onDisk === markdown) {
     return { status: "in-sync" };

package/{r2000-regbits-gen.ts → anno-regbits-gen.ts}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// r2000-regbits-gen.ts -- the ONE authoritative place in this repo that turns
+// 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
-// r2000-enum-gen.ts decodes register values against (D-22, R2000-13).
+// anno-enum-gen.ts decodes register values against (D-22, ANNO-13).
 //
 // WHY THIS EXISTS (D-22): neither register the phase's own pinned criterion-3
 // target needs ($D011) nor the registers a real game writes to constantly
@@ -18,8 +18,8 @@
 // WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR: reading memmap.json's 29
 // structured `bits` entries, normalising each `bits[].bit` range string into
 // `{mask, shift}`, deriving (or overriding) a legal ACME identifier for every
-// field, and emitting the committed, banner-marked `r2000-regbits.json`
-// artifact `r2000-enum-gen.ts` decodes against. No other module may read
+// field, and emitting the committed, banner-marked `anno-regbits.json`
+// artifact `anno-enum-gen.ts` decodes against. No other module may read
 // memmap.json for this purpose or hand-maintain a second bit-name table.
 //
 // KEY-SHAPE DECISION: table keys are `$XXXX` (uppercase, 4-hex-digit,
@@ -31,11 +31,11 @@
 // numeric-sort step is needed to keep the emitted JSON diff-stable.
 //
 // WHAT NOT TO DO, named concretely:
-//   - Never hand-edit r2000-regbits.json. It is a generated-but-committed
+//   - Never hand-edit anno-regbits.json. It is a generated-but-committed
 //     artifact (ENGINEERING_RULES.md Sec 11), the same shape
 //     `resources-sync.test.ts` already established for compiled `.mjs`
-//     build output -- re-run `node r2000-regbits-gen.ts` and let the drift
-//     guard in r2000-regbits.test.ts confirm the result matches.
+//     build output -- re-run `node anno-regbits-gen.ts` and let the drift
+//     guard in anno-regbits.test.ts confirm the result matches.
 //   - Never silently skip or placeholder an unmappable bit description.
 //     `buildRegBits()` THROWS, naming the address, the bit range and the
 //     offending description, when mechanical derivation fails AND no
@@ -53,12 +53,17 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 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). */
-const MEMMAP_PATH = join(HERE, "..", "..", "skills", "c64-memory-mapping", "memmap.json");
+ * 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/`
+ * (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. */
+const MEMMAP_PATH = join(HERE, "..", "..", "..", "src", "skills", "c64-memory-mapping", "memmap.json");
 
 /** Where the generated, committed artifact lives -- always a sibling of this
  * generator, never a caller-supplied path. */
-const OUTPUT_PATH = join(HERE, "r2000-regbits.json");
+const OUTPUT_PATH = join(HERE, "anno-regbits.json");
 
 export type FieldKind = "flag" | "numeric" | "enum";
 
@@ -186,7 +191,7 @@ function spriteBitFields(suffix: string): RegBitsField[] {
 
 // ---------------------------------------------------------------------------
 // OVERRIDES -- every entry carries its own WHY comment immediately above it
-// (r2000-regbits.test.ts's own non-vacuity check counts these two things
+// (anno-regbits.test.ts's own non-vacuity check counts these two things
 // against each other, so removing a comment without removing its entry, or
 // vice versa, fails a test rather than silently drifting).
 // ---------------------------------------------------------------------------
@@ -395,9 +400,9 @@ export function buildRegBitsDocument(): RegBitsDocument {
   const table = buildRegBits();
   const doc: RegBitsDocument = {
     _generated: {
-      generator: "r2000-regbits-gen.ts",
+      generator: "anno-regbits-gen.ts",
       memmapSha256: memmapSha256(),
-      warning: "GENERATED FILE -- do not hand-edit. Regenerate via `node r2000-regbits-gen.ts` from .claude/mcp/vice.",
+      warning: "GENERATED FILE -- do not hand-edit. Regenerate via `node anno-regbits-gen.ts` from src/mcp/vice.",
     },
   };
   for (const key of Object.keys(table).sort()) {
@@ -407,10 +412,10 @@ export function buildRegBitsDocument(): RegBitsDocument {
 }
 
 // Run-as-script: regenerate the committed artifact. Guarded so importing this
-// module (e.g. from r2000-regbits.test.ts) never has a write side effect.
+// module (e.g. from anno-regbits.test.ts) never has a write side effect.
 const isMain = process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url;
 if (isMain) {
   const doc = buildRegBitsDocument();
   writeFileSync(OUTPUT_PATH, `${JSON.stringify(doc, null, 2)}\n`);
-  console.log(`r2000-regbits-gen: wrote ${OUTPUT_PATH} (${Object.keys(doc).length - 1} registers)`);
+  console.log(`anno-regbits-gen: wrote ${OUTPUT_PATH} (${Object.keys(doc).length - 1} registers)`);
 }

package/{r2000-regbits.json → anno-regbits.json}

@@ -1,8 +1,8 @@
 {
   "_generated": {
-    "generator": "r2000-regbits-gen.ts",
+    "generator": "anno-regbits-gen.ts",
     "memmapSha256": "60a517c1833a44e6dc1a99a949554fa39834b558371d9f1e98531499fe3642fe",
-    "warning": "GENERATED FILE -- do not hand-edit. Regenerate via `node r2000-regbits-gen.ts` from .claude/mcp/vice."
+    "warning": "GENERATED FILE -- do not hand-edit. Regenerate via `node anno-regbits-gen.ts` from src/mcp/vice."
   },
   "$0001": {
     "label": "MOS 6510 Micro-Processor On-Chip I/O Port",