@isaacriehm/cairn-core 0.1.10 → 0.3.0

package/dist/ground/scope-index.js

@@ -2,20 +2,50 @@
  * Scope index — forward map from every file path in the repo to the decisions
  * and invariants that apply to that file.
  *
- * Built at init by the Tier-2 mapper LLM, maintained by the daemon. Read by
- * the read-enricher / write-guardian hooks (via cached accessor in
+ * Built at init by the Tier-2 mapper LLM, maintained by the GC sweep + the
+ * MCP record-decision tool when scope edits land. Read by the read-enricher
+ * / write-guardian hooks (via cached accessor in
  * `hooks/post-tool-use/ledger-cache.ts`) and by the GC scope-coverage pass.
  *
- * Spec: docs/DOCS_SPEC.md §3.8.
+ * Spec: docs/FILESYSTEM_LAYOUT.md §2.1.
  */
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-import { detectAll } from "../init/detect.js";
-import { buildMapperUserPrompt, MAPPER_OUTPUT_SCHEMA, MAPPER_SYSTEM_PROMPT, validateMapperOutput, } from "../init/mapper.js";
-import { buildRepoSummary } from "../init/walker.js";
 import { logger } from "../logger.js";
-import { runClaude } from "../claude/index.js";
+const DEC_ID_RE = /\bDEC-\d{4,}\b/;
+const INV_ID_RE = /\bINV-\d{4,}\b/;
+/**
+ * Mapper LLMs occasionally emit ledger-entry PROSE ("HTTP layer is the only
+ * public surface…") into `decisions[]` / `invariants[]` instead of bare IDs,
+ * because the user prompt lists them as `${id} — ${title}` and the JSON-mode
+ * schema only constrains the type to `string`. This coercer extracts the
+ * first ID-shaped token from each string and silently drops anything that
+ * doesn't match — IDs only, deduplicated, order preserved.
+ */
+export function coerceDecisionIds(raw) {
+    return coerceIds(raw, DEC_ID_RE);
+}
+export function coerceInvariantIds(raw) {
+    return coerceIds(raw, INV_ID_RE);
+}
+function coerceIds(raw, re) {
+    const out = [];
+    const seen = new Set();
+    for (const s of raw) {
+        if (typeof s !== "string")
+            continue;
+        const m = s.match(re);
+        if (m === null)
+            continue;
+        if (seen.has(m[0]))
+            continue;
+        seen.add(m[0]);
+        out.push(m[0]);
+    }
+    return out;
+}
 export function scopeIndexPath(repoRoot) {
     return join(repoRoot, ".cairn", "ground", "scope-index.yaml");
 }
@@ -68,53 +98,193 @@ export function writeScopeIndex(repoRoot, index) {
     writeFileSync(path, stringifyYaml(index), "utf8");
 }
 const log = logger("ground.scope-index");
+/* -------------------------------------------------------------------------- */
+/* Deterministic citation rescan                                              */
+/* -------------------------------------------------------------------------- */
+const CITATION_RE = /§(?:INV|DEC)-\d{4,}/g;
+const RESCAN_SOURCE_EXT_RE = /\.(?:ts|tsx|cts|mts|js|jsx|cjs|mjs|py|rb|go|rs|java|kt|swift|c|cc|cpp|h|hpp|cs|php|sql|sh|bash)$/i;
+const RESCAN_SKIP_DIR_RE = /(?:^|\/)(?:node_modules|dist|build|out|\.next|\.turbo|\.cache|coverage|\.cairn|\.archive|\.git)(?:\/|$)/;
 /**
- * Re-run the init mapper LLM scoped to the scope-index field of its output and
- * write the result to `.cairn/ground/scope-index.yaml`. Used by the
- * `cairn scope rebuild` CLI subcommand to populate scope coverage after
- * decisions/invariants land — the init-time skeleton ships empty.
+ * Deterministic regex sweep — walk every git-tracked source file, parse
+ * `§INV-NNNN` / `§DEC-NNNN` cite tokens, and sync the scope-index so the
+ * in-scope tools never lag behind source-cite reality. No LLM, no
+ * incremental tracking complexity. Cheap enough to run on every
+ * SessionStart (~100ms on 50k files).
  *
- * Throws if the LLM call fails. Caller (CLI) catches and prints a user-facing
- * error.
+ * Honors `unscoped: true` entries — never touches them. Skips files with
+ * no citations and no prior entry to avoid polluting the index. When a
+ * file's cite set differs from its scope-index entry (added, removed, or
+ * stale ids), the entry is rewritten with the deterministically-sorted
+ * current set.
  */
-export async function rebuildScopeIndex(opts) {
-    const detection = await detectAll(opts.repoRoot);
-    const summary = buildRepoSummary({ repoRoot: opts.repoRoot });
-    const userPrompt = buildMapperUserPrompt({ detection, summary });
-    log.info({
-        slug: detection.project_slug,
-        total_files: summary.total_files,
-    }, "scope rebuild — mapper dispatch");
-    const result = await runClaude({
-        tier: "sonnet",
-        prompt: userPrompt,
-        system: MAPPER_SYSTEM_PROMPT,
-        jsonSchema: MAPPER_OUTPUT_SCHEMA,
-        timeoutMs: opts.timeoutMs ?? 300_000,
-    });
-    const mapperOutput = validateMapperOutput(result.parsed);
-    const scopeIndex = mapperOutput.scope_index;
-    // Coerce mapper-shape `unscoped: boolean` → ground-shape `unscoped: true`.
-    const files = {};
-    for (const [path, e] of Object.entries(scopeIndex.files)) {
-        const entry = {
-            decisions: e.decisions,
-            invariants: e.invariants,
+export function rescanScopeIndex(repoRoot) {
+    const sourceFiles = listGitTrackedSourceFiles(repoRoot);
+    const existing = readScopeIndex(repoRoot) ?? {
+        generated: new Date().toISOString(),
+        files: {},
+    };
+    let entriesAdded = 0;
+    let entriesUpdated = 0;
+    let entriesUnchanged = 0;
+    let dirty = false;
+    for (const rel of sourceFiles) {
+        const prior = existing.files[rel];
+        if (prior?.unscoped === true)
+            continue;
+        const found = scanFileCitations(join(repoRoot, rel));
+        if (found === null)
+            continue;
+        if (found.decisions.length === 0 &&
+            found.invariants.length === 0 &&
+            prior === undefined) {
+            continue;
+        }
+        if (prior === undefined) {
+            existing.files[rel] = {
+                decisions: found.decisions,
+                invariants: found.invariants,
+            };
+            entriesAdded += 1;
+            dirty = true;
+            continue;
+        }
+        const sameDecs = prior.decisions.length === found.decisions.length &&
+            prior.decisions.every((d, i) => d === found.decisions[i]);
+        const sameInvs = prior.invariants.length === found.invariants.length &&
+            prior.invariants.every((v, i) => v === found.invariants[i]);
+        if (sameDecs && sameInvs) {
+            entriesUnchanged += 1;
+            continue;
+        }
+        existing.files[rel] = {
+            decisions: found.decisions,
+            invariants: found.invariants,
         };
-        if (e.unscoped === true)
-            entry.unscoped = true;
-        files[path] = entry;
+        entriesUpdated += 1;
+        dirty = true;
+    }
+    if (dirty) {
+        writeScopeIndex(repoRoot, {
+            generated: new Date().toISOString(),
+            files: existing.files,
+        });
+    }
+    return {
+        filesScanned: sourceFiles.length,
+        entriesAdded,
+        entriesUpdated,
+        entriesUnchanged,
+        dirty,
+    };
+}
+function scanFileCitations(absPath) {
+    let body;
+    try {
+        body = readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null;
     }
-    const next = {
+    return parseCitations(body);
+}
+function parseCitations(body) {
+    const decs = new Set();
+    const invs = new Set();
+    for (const m of body.matchAll(CITATION_RE)) {
+        const tok = m[0].slice(1);
+        if (tok.startsWith("DEC-"))
+            decs.add(tok);
+        else if (tok.startsWith("INV-"))
+            invs.add(tok);
+    }
+    return {
+        decisions: [...decs].sort(),
+        invariants: [...invs].sort(),
+    };
+}
+/**
+ * Single-file scope-index sync from in-memory content. Called by the
+ * PostToolUse(Write/Edit) hook so an agent's writes don't leave the
+ * scope-index stale until the next SessionStart rescan. Same regex
+ * parser as `rescanScopeIndex`, but bounded to one file — O(1) cost,
+ * no walker.
+ *
+ * Honors `unscoped: true` entries (skips them). Honors the same skip
+ * rule the rescan does: file with no citations and no prior entry is
+ * a no-op so we don't pollute the index with empty rows.
+ */
+export function syncFileScopeFromContent(repoRoot, repoRelPath, content) {
+    const found = parseCitations(content);
+    const existing = readScopeIndex(repoRoot) ?? {
         generated: new Date().toISOString(),
-        files,
+        files: {},
+    };
+    const prior = existing.files[repoRelPath];
+    if (prior?.unscoped === true)
+        return { dirty: false };
+    if (found.decisions.length === 0 &&
+        found.invariants.length === 0 &&
+        prior === undefined) {
+        return { dirty: false };
+    }
+    if (prior !== undefined) {
+        const sameDecs = prior.decisions.length === found.decisions.length &&
+            prior.decisions.every((d, i) => d === found.decisions[i]);
+        const sameInvs = prior.invariants.length === found.invariants.length &&
+            prior.invariants.every((v, i) => v === found.invariants[i]);
+        if (sameDecs && sameInvs)
+            return { dirty: false };
+    }
+    existing.files[repoRelPath] = {
+        decisions: found.decisions,
+        invariants: found.invariants,
     };
-    writeScopeIndex(opts.repoRoot, next);
+    writeScopeIndex(repoRoot, {
+        generated: new Date().toISOString(),
+        files: existing.files,
+    });
+    return { dirty: true };
+}
+function listGitTrackedSourceFiles(repoRoot) {
+    let out;
+    try {
+        out = execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], { cwd: repoRoot, maxBuffer: 100 * 1024 * 1024 }).toString("utf8");
+    }
+    catch {
+        return [];
+    }
+    const acc = [];
+    for (const path of out.split("\0")) {
+        if (path.length === 0)
+            continue;
+        if (RESCAN_SKIP_DIR_RE.test(path))
+            continue;
+        if (!RESCAN_SOURCE_EXT_RE.test(path))
+            continue;
+        acc.push(path);
+    }
+    return acc;
+}
+/**
+ * `cairn scope rebuild` — full deterministic resync of `.cairn/ground/
+ * scope-index.yaml` from current source-cite reality. Used to be a
+ * Sonnet call (`runMapper`-style) that re-classified files via the
+ * Tier-2 mapper, but classification was always the wrong abstraction
+ * — bare-symbol citations in source are the canonical source of truth,
+ * `rescanScopeIndex` parses them deterministically, and the result
+ * matches what the read-enricher legend actually shows.
+ *
+ * No LLM. No tokens. No mapper. Just a regex sweep over git-tracked
+ * source files and an atomic write.
+ */
+export async function rebuildScopeIndex(opts) {
+    log.info({ repo_root: opts.repoRoot }, "scope rebuild — deterministic rescan");
+    const startedAt = Date.now();
+    const result = rescanScopeIndex(opts.repoRoot);
     return {
         path: scopeIndexPath(opts.repoRoot),
-        filesClassified: Object.keys(files).length,
-        mapperDurationMs: result.durationMs,
-        model: result.model,
+        filesClassified: result.entriesAdded + result.entriesUpdated + result.entriesUnchanged,
+        durationMs: Date.now() - startedAt,
     };
 }
 //# sourceMappingURL=scope-index.js.map

package/dist/ground/scope-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"scope-index.js","sourceRoot":"","sources":["../../src/ground/scope-index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scope-index.js","sourceRoot":"","sources":["../../src/ground/scope-index.ts"],"names":[],"mappings":"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"}

package/dist/hooks/bypass-detection.js

@@ -16,6 +16,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 const HEAD_LOOKBACK = 5;
+const NUL = "\x00";
 export function scanBypassedCommits(repoRoot) {
     if (!existsSync(join(repoRoot, ".git"))) {
         return { bypassed: [], inspected: 0, attestedFileExists: false };
@@ -39,24 +40,16 @@ export function scanBypassedCommits(repoRoot) {
 }
 export function renderBypassHint(bypassed) {
     const lines = [];
-    lines.push(`## Bypass detection — ${bypassed.length} commit${bypassed.length === 1 ? "" : "s"} not attested`);
+    const noun = bypassed.length === 1 ? "commit" : "commits";
+    lines.push(`## Cairn — ${bypassed.length} ${noun} not attested`);
     lines.push("");
-    lines.push("The following HEAD commit" +
-        (bypassed.length === 1 ? " was" : "s were") +
-        " not recorded by cairn's post-commit hook. Likely cause: " +
-        "`git commit --no-verify` (or the hook ran before `cairn join` " +
-        "set `core.hooksPath`).");
+    lines.push("Likely a `--no-verify` commit or a missing per-clone bootstrap.");
     lines.push("");
     for (const c of bypassed) {
         lines.push(`- \`${c.shortSha}\` — ${c.subject}`);
     }
     lines.push("");
-    lines.push("Surface inline to the operator now:");
-    lines.push("");
-    lines.push("> Some recent commits weren't attested by cairn. Pick one:");
-    lines.push("> `[a]` backfill — run `cairn sweep` to attest sensors retroactively");
-    lines.push("> `[b]` accept — record a DEC noting the bypass + reason");
-    lines.push("> `[c]` defer — keep the warning, address later");
+    lines.push("Invoke the `cairn-attention` skill on the next turn so the operator can pick record bypass / acknowledge / defer through `AskUserQuestion`.");
     return lines.join("\n");
 }
 /* -------------------------------------------------------------------------- */
@@ -64,16 +57,20 @@ export function renderBypassHint(bypassed) {
 /* -------------------------------------------------------------------------- */
 function readRecentHead(repoRoot) {
     try {
-        const out = execFileSync("git", ["log", `-n${HEAD_LOOKBACK}`, "--format=%H%x09%s"], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        // NUL (%x00) as the SHA/subject separator. Tabs and any other
+        // printable byte can legitimately appear inside a commit subject;
+        // NUL cannot. Records are newline-separated; the subject (`%s`) is
+        // a single line by definition, so split("\n") is safe.
+        const out = execFileSync("git", ["log", `-n${HEAD_LOOKBACK}`, "--format=%H%x00%s"], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
         const result = [];
         for (const line of out.split("\n")) {
             if (line.length === 0)
                 continue;
-            const tabIdx = line.indexOf("\t");
-            if (tabIdx === -1)
+            const sepIdx = line.indexOf(NUL);
+            if (sepIdx === -1)
                 continue;
-            const sha = line.slice(0, tabIdx);
-            const subject = line.slice(tabIdx + 1);
+            const sha = line.slice(0, sepIdx);
+            const subject = line.slice(sepIdx + 1);
             if (sha.length < 7)
                 continue;
             result.push({ sha, shortSha: sha.slice(0, 7), subject });

package/dist/hooks/bypass-detection.js.map

@@ -1 +1 @@
-{"version":3,"file":"bypass-detection.js","sourceRoot":"","sources":["../../src/hooks/bypass-detection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bypass-detection.js","sourceRoot":"","sources":["../../src/hooks/bypass-detection.ts"],"names":[],"mappings":"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"}

package/dist/hooks/defer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Stop-hook signal debounce.
+ *
+ * Per-kind defer file: when the operator picks `[c]` defer on the
+ * inline A/B/C, cairn_resolve_attention writes
+ * `.cairn/.{bypass,review}-deferred-until` with the snapshot of
+ * SHAs / task-ids that were flagged. Subsequent Stop hooks suppress
+ * the warning while:
+ *   1. now < deferred_at + deferred_for_hours, AND
+ *   2. the current scan's flagged set ⊆ the deferred set
+ *      (anything new shows up).
+ *
+ * Pure read/write/check helpers — no side effects beyond filesystem.
+ */
+export type DeferKind = "bypass" | "review";
+export interface DeferState {
+    /** ISO timestamp when the operator chose defer. */
+    deferred_at: string;
+    /** Hours from `deferred_at` until the suppression window expires. */
+    deferred_for_hours: number;
+    /** Bypass commit SHAs at the time of defer (full SHAs, not short). */
+    flagged_shas: string[];
+    /** Reviewer-pending task ids at the time of defer. */
+    flagged_task_ids: string[];
+}
+export declare function deferStatePath(repoRoot: string, kind: DeferKind): string;
+export declare function readDeferState(repoRoot: string, kind: DeferKind): DeferState | null;
+export declare function writeDeferState(repoRoot: string, kind: DeferKind, snapshot: {
+    flagged_shas?: string[];
+    flagged_task_ids?: string[];
+    /** Override defer window. Default 24h. */
+    hours?: number;
+    /** ISO timestamp; defaults to new Date().toISOString(). */
+    nowIso?: string;
+}): DeferState;
+export declare function clearDeferState(repoRoot: string, kind: DeferKind): void;
+/**
+ * Returns true when `state` is still suppressing — within the time
+ * window AND every currently-flagged item is in the deferred snapshot
+ * (no new bypasses / new pending reviews have appeared).
+ *
+ * If anything new appears, the suppression breaks and the Stop hook
+ * surfaces the warning again — which is the right behavior, because
+ * "defer for 24h" was a promise about the items the operator saw,
+ * not a blanket mute.
+ */
+export declare function isDeferActive(state: DeferState, now: Date, currentItems: {
+    kind: "shas" | "task_ids";
+    values: string[];
+}): boolean;

package/dist/hooks/defer.js

@@ -0,0 +1,87 @@
+/**
+ * Stop-hook signal debounce.
+ *
+ * Per-kind defer file: when the operator picks `[c]` defer on the
+ * inline A/B/C, cairn_resolve_attention writes
+ * `.cairn/.{bypass,review}-deferred-until` with the snapshot of
+ * SHAs / task-ids that were flagged. Subsequent Stop hooks suppress
+ * the warning while:
+ *   1. now < deferred_at + deferred_for_hours, AND
+ *   2. the current scan's flagged set ⊆ the deferred set
+ *      (anything new shows up).
+ *
+ * Pure read/write/check helpers — no side effects beyond filesystem.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const DEFAULT_DEFER_HOURS = 24;
+export function deferStatePath(repoRoot, kind) {
+    return join(repoRoot, ".cairn", `.${kind}-deferred-until`);
+}
+export function readDeferState(repoRoot, kind) {
+    const path = deferStatePath(repoRoot, kind);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!isDeferState(parsed))
+        return null;
+    return parsed;
+}
+export function writeDeferState(repoRoot, kind, snapshot) {
+    const state = {
+        deferred_at: snapshot.nowIso ?? new Date().toISOString(),
+        deferred_for_hours: snapshot.hours ?? DEFAULT_DEFER_HOURS,
+        flagged_shas: [...(snapshot.flagged_shas ?? [])],
+        flagged_task_ids: [...(snapshot.flagged_task_ids ?? [])],
+    };
+    const path = deferStatePath(repoRoot, kind);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2), "utf8");
+    return state;
+}
+export function clearDeferState(repoRoot, kind) {
+    rmSync(deferStatePath(repoRoot, kind), { force: true });
+}
+/**
+ * Returns true when `state` is still suppressing — within the time
+ * window AND every currently-flagged item is in the deferred snapshot
+ * (no new bypasses / new pending reviews have appeared).
+ *
+ * If anything new appears, the suppression breaks and the Stop hook
+ * surfaces the warning again — which is the right behavior, because
+ * "defer for 24h" was a promise about the items the operator saw,
+ * not a blanket mute.
+ */
+export function isDeferActive(state, now, currentItems) {
+    const deferredAt = Date.parse(state.deferred_at);
+    if (Number.isNaN(deferredAt))
+        return false;
+    const expiresAt = deferredAt + state.deferred_for_hours * 60 * 60 * 1000;
+    if (now.getTime() >= expiresAt)
+        return false;
+    const snapshotSet = new Set(currentItems.kind === "shas" ? state.flagged_shas : state.flagged_task_ids);
+    for (const item of currentItems.values) {
+        if (!snapshotSet.has(item))
+            return false;
+    }
+    return true;
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function isDeferState(x) {
+    if (x === null || typeof x !== "object")
+        return false;
+    const o = x;
+    return (typeof o["deferred_at"] === "string" &&
+        typeof o["deferred_for_hours"] === "number" &&
+        isStringArray(o["flagged_shas"]) &&
+        isStringArray(o["flagged_task_ids"]));
+}
+//# sourceMappingURL=defer.js.map

package/dist/hooks/defer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defer.js","sourceRoot":"","sources":["../../src/hooks/defer.ts"],"names":[],"mappings":"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"}

package/dist/hooks/post-tool-use/citation-scanner.d.ts

@@ -1,7 +1,9 @@
 /**
  * Scans the visible body of a Read tool's content for cairn citation
- * patterns: §V invariants, TODO(TSK-...) linked todos, and (banned)
- * DEC-id references.
+ * patterns: §INV invariants, §DEC decisions, and TODO(TSK-...) linked
+ * todos. Both `§INV-NNNN` and `§DEC-NNNN` are the canonical bare-symbol
+ * citation forms produced by the strip-replace phase and resolved by
+ * the read-enricher into the legend.
  *
  * Per READ_ENRICHER_SPEC §3 — line numbers in the legend should reflect
  * the original source line, so when content is `cat -n`-prefixed
@@ -9,7 +11,7 @@
  * number as the reported line. The body text itself is NEVER mutated.
  */
 export interface CitationMatch {
-    /** Citation id, e.g. "V0023" or "TSK-auth-refactor" or "DEC-0042". */
+    /** Citation id, e.g. "INV-0023" or "TSK-auth-refactor" or "DEC-0042". */
     id: string;
     /** 1-indexed line number from cat -n prefix, or iteration index. */
     line: number;
@@ -17,7 +19,7 @@ export interface CitationMatch {
 export interface ScannedCitations {
     invariants: CitationMatch[];
     todos: CitationMatch[];
-    /** Banned DEC-N citations — for the policy-violation legend. */
-    decIds: CitationMatch[];
+    /** §DEC-NNNN citations resolved against the decisions ledger. */
+    decisions: CitationMatch[];
 }
 export declare function scanCitations(content: string): ScannedCitations;

package/dist/hooks/post-tool-use/citation-scanner.js

@@ -1,23 +1,29 @@
 /**
  * Scans the visible body of a Read tool's content for cairn citation
- * patterns: §V invariants, TODO(TSK-...) linked todos, and (banned)
- * DEC-id references.
+ * patterns: §INV invariants, §DEC decisions, and TODO(TSK-...) linked
+ * todos. Both `§INV-NNNN` and `§DEC-NNNN` are the canonical bare-symbol
+ * citation forms produced by the strip-replace phase and resolved by
+ * the read-enricher into the legend.
  *
  * Per READ_ENRICHER_SPEC §3 — line numbers in the legend should reflect
  * the original source line, so when content is `cat -n`-prefixed
  * (`<num>\t<line>`), strip the prefix for matching but use the prefix
  * number as the reported line. The body text itself is NEVER mutated.
  */
-const INVARIANT_RE = /§V(\d+)/g;
+const INVARIANT_RE = /§INV-(\d+)/g;
 const TODO_RE = /TODO\(TSK-([^)]+)\)/g;
-const DEC_RE = /DEC-(\d+)/g;
+// Require `§` prefix so plain `DEC-NNNN` strings (URL fragments, prose
+// citations in markdown bodies, GitHub-style refs) don't false-match.
+// The strip-replace phase ALWAYS emits the `§` prefix on accepted
+// decision tokens (per LENS_SPEC + CLAUDE.md "bare symbols only").
+const DEC_RE = /§DEC-(\d+)/g;
 const CAT_N_PREFIX_RE = /^(\d+)\t/;
 export function scanCitations(content) {
     const invariants = [];
     const todos = [];
-    const decIds = [];
+    const decisions = [];
     if (content.length === 0) {
-        return { invariants, todos, decIds };
+        return { invariants, todos, decisions };
     }
     const lines = content.split(/\r?\n/);
     for (let i = 0; i < lines.length; i++) {
@@ -39,7 +45,7 @@ export function scanCitations(content) {
             const digits = m[1];
             if (digits === undefined)
                 continue;
-            invariants.push({ id: `V${digits}`, line: lineNumber });
+            invariants.push({ id: `INV-${digits}`, line: lineNumber });
         }
         for (const m of lineText.matchAll(TODO_RE)) {
             const tail = m[1];
@@ -51,9 +57,9 @@ export function scanCitations(content) {
             const digits = m[1];
             if (digits === undefined)
                 continue;
-            decIds.push({ id: `DEC-${digits}`, line: lineNumber });
+            decisions.push({ id: `DEC-${digits}`, line: lineNumber });
         }
     }
-    return { invariants, todos, decIds };
+    return { invariants, todos, decisions };
 }
 //# sourceMappingURL=citation-scanner.js.map