@holmes-lab/holmes-kit 0.15.0 → 0.17.0

package/dist/holmes/rtm/anchor-density.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_ANCHORS = void 0;
+exports.anchorDensityFindings = anchorDensityFindings;
+exports.appendAnchorDensity = appendAnchorDensity;
+exports.readAnchorDensity = readAnchorDensity;
+// @implements A-SPEC-569.5
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const replica_id_1 = require("../governance/replica-id");
+/** Files below this live-anchor count are never flagged, whatever the distribution — a floor. */
+exports.MIN_ANCHORS = 8;
+/**
+ * FtT files whose live anchor count sits at or above max(MIN_ANCHORS, p90 of the distribution).
+ * p90 is the value at index ceil(0.9·n)-1 of the ascending counts — deterministic, no interpolation.
+ * Pure: same inputs, same findings, in sorted path order.
+ */
+function anchorDensityFindings(fttFiles, counts) {
+    if (counts.length === 0 || fttFiles.length === 0)
+        return [];
+    const sorted = counts.map((c) => c.anchors).sort((a, b) => a - b);
+    const p90 = sorted[Math.ceil(0.9 * sorted.length) - 1];
+    const threshold = Math.max(exports.MIN_ANCHORS, p90);
+    const byPath = new Map(counts.map((c) => [c.sourcePath, c.anchors]));
+    const out = [];
+    for (const f of [...new Set(fttFiles.map((p) => p.replace(/\\/g, '/')))].sort()) {
+        const anchors = byPath.get(f);
+        if (anchors !== undefined && anchors >= threshold)
+            out.push({ path: f, anchors, p90 });
+    }
+    return out;
+}
+const DENSITY_FILE_RE = /^anchor-density\.([^.]+)\.jsonl$/;
+function appendAnchorDensity(root, rec) {
+    try {
+        if (!fs.existsSync(path.join(root, '.ax')))
+            return false;
+        let replica = 'local';
+        try {
+            replica = (0, replica_id_1.resolveReplicaId)(root) || 'local';
+        }
+        catch { /* keep the fallback */ }
+        const file = path.join(root, '.ax', 'ledger', `anchor-density.${replica}.jsonl`);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify({ ...rec, replica })}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readAnchorDensity(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => DENSITY_FILE_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r === 'object' && typeof r.aspec === 'string' && Array.isArray(r.files) && typeof r.ts === 'string') {
+                    out.push(r);
+                }
+            }
+            catch { /* a corrupt line never breaks the read */ }
+        }
+    }
+    return out;
+}

package/dist/holmes/rtm/impact-advisory.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The impact advisory: what the Files-to-Touch declaration MISSES, computed from the call graph at
+ * the moment of sealing. jarvis proposal #1, admitted on our own measured record — of fourteen
+ * graph mechanisms, the only win was the IMPACT axis (PPR, three corpora), and REQ-565 established
+ * the "declaration vs machine" gate pattern this extends.
+ *
+ * ONE HOP, NEVER CLOSURE: caller closure measured 59 extra files and zero answers across twelve
+ * commits ("closure is impact, not localization"). ADVISORY, NEVER VERDICT: nothing here can change
+ * ok/refuse/grant (Judgments must not be budgeted). NO GUESSING: an unreadable graph yields null,
+ * not an estimate.
+ */
+export interface GraphLike {
+    nodeIdsInFile(relPath: string): string[];
+    callersOf(id: string): string[];
+    /** @implements A-SPEC-568.2 — the node's intent sentence, or null; information only, never a verdict input. */
+    summaryOf(id: string): string | null;
+}
+export interface ImpactAdvisory {
+    files: Array<{
+        path: string;
+        anchors: Array<{
+            id: string;
+            summary: string | null;
+        }>;
+        /** @implements A-SPEC-569.3 — anchors beyond ANCHOR_CAP, counted rather than silently dropped. */
+        anchorsOmitted?: number;
+    }>;
+    more: number;
+    graphAsOf?: string;
+}
+export declare const ADVISORY_CAP = 10;
+/** @implements A-SPEC-569.3 — anchors annotated per advisory file; a prose constant, never a verdict input. */
+export declare const ANCHOR_CAP = 10;
+export declare function declaredImpactGap(fttFiles: string[], graph: GraphLike, readFile: (rel: string) => string | null, opts?: {
+    cap?: number;
+}): ImpactAdvisory | null;
+/**
+ * @implements A-SPEC-566.2
+ * The observation ledger: every advisory the act produced, so its false-positive rate can be
+ * MEASURED before anyone proposes promoting it to a hard gate (the August rtm_reindex lesson).
+ * Repo-relative paths, spec ids and integers only — nothing else has a field.
+ */
+export interface AdvisoryRecord {
+    aspec: string;
+    files: string[];
+    more: number;
+    graphAsOf?: string;
+    ts: string;
+    replica?: string;
+}
+export declare function appendImpactAdvisory(root: string, rec: AdvisoryRecord): boolean;
+export declare function readImpactAdvisories(root: string): AdvisoryRecord[];

package/dist/holmes/rtm/impact-advisory.js

@@ -0,0 +1,182 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANCHOR_CAP = exports.ADVISORY_CAP = void 0;
+exports.declaredImpactGap = declaredImpactGap;
+exports.appendImpactAdvisory = appendImpactAdvisory;
+exports.readImpactAdvisories = readImpactAdvisories;
+// @implements A-SPEC-566.1
+// @implements A-SPEC-566.2
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const replica_id_1 = require("../governance/replica-id");
+exports.ADVISORY_CAP = 10;
+/** @implements A-SPEC-569.3 — anchors annotated per advisory file; a prose constant, never a verdict input. */
+exports.ANCHOR_CAP = 10;
+/** The ONLY shape allowed into the ledger: `seg/seg/…` of word characters, dots and dashes —
+ * no leading slash, no drive letter, no backslash, no empty or `..` segment. */
+function isRepoRelative(p) {
+    if (p === '' || p.includes('\\') || p.includes(':'))
+        return false;
+    const segs = p.split('/');
+    // Round-4: '.' segments made `src/./b.ts` dodge a declared `src/b.ts`, and the ASCII-only \w
+    // silently dropped findings in non-ASCII filenames (the 한글파일 evidence discipline of 563.3).
+    // Unicode letters/digits are leak-safe; dot-segments are not path characters, they are aliases.
+    return segs.every((s) => /^[\p{L}\p{N}_.-]+$/u.test(s) && s !== '..' && s !== '.');
+}
+/** `@implements <spec-id>` ids out of a file's text — the anchor idiom, read-only. */
+function anchorsIn(text) {
+    const out = [];
+    for (const m of text.matchAll(/@implements\s+((?:A|T|H|C)-SPEC-[\d.]+|REQ-\d+)/g)) {
+        if (!out.includes(m[1]))
+            out.push(m[1]);
+    }
+    return out;
+}
+function declaredImpactGap(fttFiles, graph, readFile, opts) {
+    try {
+        const cap = opts?.cap ?? exports.ADVISORY_CAP;
+        const declared = new Set(fttFiles.map((f) => f.replace(/\\/g, '/')));
+        const outside = new Set();
+        for (const ftt of declared) {
+            for (const nodeId of graph.nodeIdsInFile(ftt)) {
+                for (const caller of graph.callersOf(nodeId)) {
+                    const at = caller.lastIndexOf('@');
+                    if (at === -1)
+                        continue; // a node without a file cannot be a finding
+                    const file = caller.slice(at + 1);
+                    // Adversarial rounds 2-3: the record's no-secret contract says REPO-RELATIVE ONLY. A deny
+                    // list (round-2: '/', 'C:', '..') let UNC paths through one round later — so this is an
+                    // ALLOW list: plain slash-separated word segments, no '..' segment, nothing else. What
+                    // does not look like an in-repo relative path is dropped, never normalized into one.
+                    if (!isRepoRelative(file))
+                        continue;
+                    if (!declared.has(file))
+                        outside.add(file);
+                }
+            }
+        }
+        if (outside.size === 0)
+            return null;
+        const sorted = [...outside].sort();
+        const shown = sorted.slice(0, cap);
+        return {
+            files: shown.map((path) => {
+                let ids = [];
+                try {
+                    const text = readFile(path);
+                    if (typeof text === 'string')
+                        ids = anchorsIn(text);
+                }
+                catch { /* anchors stay [] */ }
+                // @implements A-SPEC-569.3 — capped BEFORE the summary lookups, so the omitted tail costs
+                // no SELECTs either; the omission is counted, never silent.
+                const shownIds = ids.slice(0, exports.ANCHOR_CAP);
+                const anchorsOmitted = ids.length - shownIds.length;
+                // @implements A-SPEC-568.2 — the anchor's intent sentence rides BESIDE the id, read from the
+                // graph S1 built. Information only: nothing below this line feeds files/more/ordering, and a
+                // failing lookup downgrades to null rather than killing the finding (an advisory never guesses).
+                return {
+                    path,
+                    anchors: shownIds.map((id) => {
+                        let summary = null;
+                        try {
+                            summary = graph.summaryOf(`SPEC:${id}`);
+                        }
+                        catch { /* summary stays null */ }
+                        return { id, summary };
+                    }),
+                    ...(anchorsOmitted > 0 ? { anchorsOmitted } : {}),
+                };
+            }),
+            more: sorted.length - shown.length,
+        };
+    }
+    catch {
+        return null;
+    } // an advisory never guesses
+}
+const ADVISORY_FILE_RE = /^impact-advisories\.([^.]+)\.jsonl$/;
+function appendImpactAdvisory(root, rec) {
+    try {
+        if (!fs.existsSync(path.join(root, '.ax')))
+            return false;
+        let replica = 'local';
+        try {
+            replica = (0, replica_id_1.resolveReplicaId)(root) || 'local';
+        }
+        catch { /* keep the fallback */ }
+        const file = path.join(root, '.ax', 'ledger', `impact-advisories.${replica}.jsonl`);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify({ ...rec, replica })}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readImpactAdvisories(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => ADVISORY_FILE_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r === 'object' && typeof r.aspec === 'string' && Array.isArray(r.files) && typeof r.ts === 'string') {
+                    out.push(r);
+                }
+            }
+            catch { /* a corrupt line never breaks the read */ }
+        }
+    }
+    return out;
+}

package/dist/holmes/rtm/localize.js

@@ -223,6 +223,13 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
     for (const id of citations.cited)
         if (!matchedSpecs.includes(id))
             matchedSpecs.push(id);
+    // A spec-intent-vector injection was wired here (REQ-568 S3) and REVERTED on its pre-registered
+    // replay: over 441 held-out traceability cases the assist was byte-identical to this lexical
+    // path — long queries already match ~371 specs lexically (the semantic top-3 was a subset in
+    // 23/23 samples), and in the lexical-zero segment the A-SPEC-399 reorder-not-admit rule forbids
+    // exactly the admission recovery would need. The S-491 embedding win belongs to direct
+    // query→file ranking, not to this layer. Do not re-add without a NEW pre-registered corpus of
+    // short uncited requests AND an admission rule of its own.
     const matchedSpecSet = new Set(matchedSpecs);
     // Vendored/mirrored trees (review D4): an identical copy under reference/vendor must not outrank —
     // or lexically tie-break above — the live source. Their scores are halved and ties break toward

package/dist/holmes/rtm/rtm-builder.d.ts

@@ -57,6 +57,14 @@ export interface BuildRtmOptions {
      */
     fileDigest?: (sourcePath: string) => string | undefined;
 }
+/**
+ * @implements A-SPEC-568.1
+ * `"<title> — <intent first sentence>"`, EXTRACTED — never generated. Same spec store, same bytes:
+ * the whole function is whitespace folding, one regex, one slice. A missing, blank or still-TODO
+ * intent section degrades to the title alone (spec_create stubs sections as `TODO`, and "TODO" as
+ * an intent sentence would be noise wearing a dash).
+ */
+export declare function specSummary(s: Spec): string;
 /**
  * Adds one scanned file's CODE nodes and `implements` edges to the graph,
  * tagged with that file's sourcePath so RtmGraph.removeBySource(f.sourcePath)

package/dist/holmes/rtm/rtm-builder.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_IMPACT = void 0;
+exports.specSummary = specSummary;
 exports.buildFileSubgraph = buildFileSubgraph;
 exports.buildRtm = buildRtm;
 exports.addCallEdges = addCallEdges;
@@ -62,6 +63,52 @@ function fact(opts, sourceLocation, derivation, confidence, evidenceDigest = nul
         derivation,
     };
 }
+/**
+ * @implements A-SPEC-568.1
+ * Which section states a spec's INTENT, per kind. Only the three kinds whose required sections
+ * carry a prose intent are mapped; every other kind (T-SPEC's quadrants, C-SPEC) summarizes as its
+ * title alone — a rule deferred until a consumer measures the lack (H-SPEC-568 Open Questions).
+ */
+const INTENT_SECTION = {
+    'REQ': 'Problem / Need',
+    'H-SPEC': 'Intent',
+    'A-SPEC': 'Objective',
+};
+/** Longest intent sentence carried into the graph — a bound, applied deterministically. */
+const SUMMARY_SENTENCE_CAP = 200;
+/**
+ * @implements A-SPEC-568.1
+ * `"<title> — <intent first sentence>"`, EXTRACTED — never generated. Same spec store, same bytes:
+ * the whole function is whitespace folding, one regex, one slice. A missing, blank or still-TODO
+ * intent section degrades to the title alone (spec_create stubs sections as `TODO`, and "TODO" as
+ * an intent sentence would be noise wearing a dash).
+ */
+function specSummary(s) {
+    // The Spec type promises strings, but runtime records disagree (test fixtures without a title;
+    // 20 legacy store documents with title ''). Extraction is fail-open: it degrades, never throws.
+    const title = String(s.title ?? '').trim();
+    const section = INTENT_SECTION[s.type];
+    const text = (section ? (s.sections?.[section] ?? '') : '').replace(/\s+/g, ' ').trim();
+    // Measured 2026-09-07 on this store: 20 legacy specs carry title '' — the summary falls back to
+    // the sentence alone, then to the id, because SC1 admits no empty summary on any path.
+    let result;
+    if (text === '' || text === 'TODO')
+        result = title !== '' ? title : s.id;
+    else {
+        // First sentence: up to the first . ! or ? that ends a word — the lookahead keeps `A-SPEC-129.2`
+        // whole, because its dot is followed by a digit, not by whitespace or the end.
+        const m = /^(.*?[.!?])(?=\s|$)/.exec(text);
+        let sentence = m ? m[1] : text;
+        if (sentence.length > SUMMARY_SENTENCE_CAP)
+            sentence = `${sentence.slice(0, SUMMARY_SENTENCE_CAP)}…`;
+        result = title !== '' ? `${title} — ${sentence}` : sentence;
+    }
+    // @implements A-SPEC-569.1 — the WHOLE summary folds, title included. The first cut normalized
+    // only the sentence, and a YAML double-quoted title carried \n/\t straight into dumpCanonical,
+    // where graphViewOf parsed the forged row as a real call edge (0.16.0 adversarial reproduction).
+    // Prose must never carry the dump's structural characters.
+    return result.replace(/\s+/g, ' ').trim();
+}
 /**
  * Adds one scanned file's CODE nodes and `implements` edges to the graph,
  * tagged with that file's sourcePath so RtmGraph.removeBySource(f.sourcePath)
@@ -96,7 +143,9 @@ function buildRtm(specs, scanned, graph, opts) {
         // Add spec nodes and dependencies
         for (const s of specs) {
             const sourcePath = opts?.specSourcePath?.(s.id);
-            graph.addNode(`SPEC:${s.id}`, s.type, sourcePath, fact(opts, sourcePath ?? null, 'spec-store', 1));
+            // @implements A-SPEC-568.1 — the intent property rides in with the node; CODE/FILE/COMMIT/
+            // DECISION nodes pass nothing and stay null.
+            graph.addNode(`SPEC:${s.id}`, s.type, sourcePath, fact(opts, sourcePath ?? null, 'spec-store', 1), specSummary(s));
             // DECLARED in frontmatter.
             for (const p of s.dependsOn) {
                 graph.addEdge(`SPEC:${s.id}`, `SPEC:${p}`, 'depends_on', sourcePath, fact(opts, sourcePath ?? null, 'frontmatter', 1));

package/dist/holmes/rtm/rtm-graph.d.ts

@@ -51,8 +51,19 @@ export declare class RtmGraph {
     constructor(dbPath?: string);
     private nodeStmt?;
     private edgeStmt?;
-    addNode(id: string, kind: string, sourcePath?: string, provenance?: Provenance): void;
+    addNode(id: string, kind: string, sourcePath?: string, provenance?: Provenance, summary?: string | null): void;
+    /**
+     * @implements A-SPEC-568.1
+     * The node's intent sentence, extracted from the spec store at build time — or null: for a CODE
+     * node (no prose was extracted), for a node written before rtm-graph/3, for an unknown id. The
+     * summary is INFORMATION, never a verdict input (REQ-568 c6 rule) — nothing in this class or its
+     * consumers ranks, gates or filters on it.
+     */
+    summaryOf(id: string): string | null;
     addEdge(src: string, dst: string, rel: string, sourcePath?: string, provenance?: Provenance): void;
+    /** @implements A-SPEC-569.1 — does the graph hold this node? SELECT 1, no row materialization:
+     * the approved-only channel filter (A-SPEC-569.2) asks exactly this and nothing more. */
+    hasNode(id: string): boolean;
     /** @implements A-SPEC-281 — how this node got here, or null if the node is unknown. */
     provenanceOfNode(id: string): Provenance | null;
     /** @implements A-SPEC-281 — how this edge got here, or null if the edge is unknown. */
@@ -72,6 +83,13 @@ export declare class RtmGraph {
      * this and not `incoming`, which would also drag in `implements` and `depends_on` and turn a
      * "who calls me" question into "what is attached to me in any way at all".
      */
+    /**
+     * @implements A-SPEC-566.1
+     * Every node the graph holds for one source file — the impact advisory's entry point. Exact
+     * `source_path` equality on the indexed column (idx_nodes_source): no LIKE, so % and _ in a path
+     * are literal by construction and `a.ts` can never absorb `xa.ts`.
+     */
+    nodeIdsInFile(relPath: string): string[];
     callersOf(id: string): string[];
     /**
      * @implements A-SPEC-288
@@ -197,6 +215,15 @@ export declare class RtmGraph {
     clear(): void;
     /** @implements A-SPEC-283 — the journal mode actually in force, so the pragma can be asserted. */
     journalMode(): string;
+    /**
+     * @implements A-SPEC-569.5
+     * Live anchors per source file — distinct SPEC targets of `implements` edges, one GROUP BY.
+     * Feeds the anchor-density OBSERVATION at sealing time; nothing reads it into a verdict.
+     */
+    implementsAnchorCounts(): Array<{
+        sourcePath: string;
+        anchors: number;
+    }>;
     nodeCount(): number;
     edgeCount(): number;
     close(): void;

package/dist/holmes/rtm/rtm-graph.js

@@ -75,7 +75,7 @@ class RtmGraph {
             this.db.pragma('journal_mode = WAL');
             this.db.pragma('busy_timeout = 5000');
         }
-        this.db.exec(`CREATE TABLE IF NOT EXISTS nodes (id TEXT PRIMARY KEY, kind TEXT NOT NULL, source_path TEXT);
+        this.db.exec(`CREATE TABLE IF NOT EXISTS nodes (id TEXT PRIMARY KEY, kind TEXT NOT NULL, source_path TEXT, summary TEXT);
       CREATE TABLE IF NOT EXISTS edges (src TEXT NOT NULL, dst TEXT NOT NULL, rel TEXT NOT NULL, source_path TEXT, PRIMARY KEY (src,dst,rel));
       -- The PK covers src-prefixed lookups; nothing covered dst or source_path, so every reverse
       -- traversal and every removeBySource was a full table scan. Measured on a 240k-node graph:
@@ -103,6 +103,11 @@ class RtmGraph {
                 const type = column === 'confidence' ? 'REAL' : 'TEXT';
                 this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
             }
+            // @implements A-SPEC-568.1 — same in-place migration rule as provenance: an rtm-graph/2 file
+            // must keep OPENING (openReusableGraph decides reuse; an unreadable file would look corrupt).
+            if (table === 'nodes' && !present.has('summary')) {
+                this.db.exec('ALTER TABLE nodes ADD COLUMN summary TEXT');
+            }
         }
     }
     // @implements A-SPEC-139
@@ -113,14 +118,34 @@ class RtmGraph {
     // Semantics are unchanged: same signatures, same INSERT OR IGNORE idempotence, same columns.
     nodeStmt;
     edgeStmt;
-    addNode(id, kind, sourcePath, provenance) {
-        this.nodeStmt ??= this.db.prepare(`INSERT OR IGNORE INTO nodes (id,kind,source_path,${PROVENANCE_COLUMNS.join(',')}) VALUES (?,?,?,?,?,?,?,?,?,?,?)`);
-        this.nodeStmt.run(id, kind, sourcePath ?? null, ...provenanceRow(provenance));
+    addNode(id, kind, sourcePath, provenance, summary) {
+        this.nodeStmt ??= this.db.prepare(`INSERT OR IGNORE INTO nodes (id,kind,source_path,summary,${PROVENANCE_COLUMNS.join(',')}) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`);
+        // @implements A-SPEC-569.1 — the STORAGE boundary folds structural characters too, so a future
+        // caller that never went through specSummary still cannot forge dumpCanonical rows. Second,
+        // independent face of the seal (each face is verified alone).
+        const foldedSummary = summary == null ? null : summary.replace(/\s+/g, ' ').trim();
+        this.nodeStmt.run(id, kind, sourcePath ?? null, foldedSummary, ...provenanceRow(provenance));
+    }
+    /**
+     * @implements A-SPEC-568.1
+     * The node's intent sentence, extracted from the spec store at build time — or null: for a CODE
+     * node (no prose was extracted), for a node written before rtm-graph/3, for an unknown id. The
+     * summary is INFORMATION, never a verdict input (REQ-568 c6 rule) — nothing in this class or its
+     * consumers ranks, gates or filters on it.
+     */
+    summaryOf(id) {
+        const row = this.db.prepare('SELECT summary FROM nodes WHERE id = ?').get(id);
+        return row?.summary ?? null;
     }
     addEdge(src, dst, rel, sourcePath, provenance) {
         this.edgeStmt ??= this.db.prepare(`INSERT OR IGNORE INTO edges (src,dst,rel,source_path,${PROVENANCE_COLUMNS.join(',')}) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`);
         this.edgeStmt.run(src, dst, rel, sourcePath ?? null, ...provenanceRow(provenance));
     }
+    /** @implements A-SPEC-569.1 — does the graph hold this node? SELECT 1, no row materialization:
+     * the approved-only channel filter (A-SPEC-569.2) asks exactly this and nothing more. */
+    hasNode(id) {
+        return this.db.prepare('SELECT 1 FROM nodes WHERE id = ?').get(id) !== undefined;
+    }
     /** @implements A-SPEC-281 — how this node got here, or null if the node is unknown. */
     provenanceOfNode(id) {
         return provenanceOf(this.db.prepare('SELECT * FROM nodes WHERE id = ?').get(id));
@@ -149,6 +174,15 @@ class RtmGraph {
      * this and not `incoming`, which would also drag in `implements` and `depends_on` and turn a
      * "who calls me" question into "what is attached to me in any way at all".
      */
+    /**
+     * @implements A-SPEC-566.1
+     * Every node the graph holds for one source file — the impact advisory's entry point. Exact
+     * `source_path` equality on the indexed column (idx_nodes_source): no LIKE, so % and _ in a path
+     * are literal by construction and `a.ts` can never absorb `xa.ts`.
+     */
+    nodeIdsInFile(relPath) {
+        return this.db.prepare('SELECT id FROM nodes WHERE source_path = ? ORDER BY id ASC').all(relPath).map((x) => x.id);
+    }
     callersOf(id) {
         return this.db.prepare("SELECT DISTINCT src FROM edges WHERE dst=? AND rel='calls' ORDER BY src ASC").all(id).map(x => x.src);
     }
@@ -339,12 +373,21 @@ class RtmGraph {
         // @implements A-SPEC-281 — provenance is part of the value, so a provenance-only divergence
         // between a full rebuild and an incremental update is caught rather than passing as equal.
         const cols = PROVENANCE_COLUMNS.join(', ');
-        const prov = (r) => PROVENANCE_COLUMNS.map((c) => (r[c] === null || r[c] === undefined ? '' : String(r[c]))).join('\t');
-        const nodes = this.db.prepare(`SELECT id, kind, source_path, ${cols} FROM nodes ORDER BY id`).all();
+        // @implements A-SPEC-569.1 (revision) — EVERY text column folds at emission. Sealing columns
+        // one at a time (title → summary) was whack-a-mole: high-effort review found id/depends_on
+        // carrying tabs into these rows and shifting columns under graphViewOf. The dump's structural
+        // characters are the dump's own concern, so this is the single choke point; the row-shape
+        // invariant (exactly 13 cells, structural-char-free) is pinned by test.
+        const fold = (v) => (v === null || v === undefined ? '' : String(v).replace(/[\t\n\r]+/g, ' '));
+        const prov = (r) => PROVENANCE_COLUMNS.map((c) => fold(r[c])).join('\t');
+        const nodes = this.db.prepare(`SELECT id, kind, source_path, summary, ${cols} FROM nodes ORDER BY id`).all();
         const edges = this.db.prepare(`SELECT src, dst, rel, source_path, ${cols} FROM edges ORDER BY src, dst, rel`).all();
         return [
-            ...nodes.map((n) => `N\t${n.id}\t${n.kind}\t${n.source_path ?? ''}\t${prov(n)}`),
-            ...edges.map((e) => `E\t${e.src}\t${e.dst}\t${e.rel}\t${e.source_path ?? ''}\t${prov(e)}`),
+            // @implements A-SPEC-568.1 — summary is part of the VALUE (appended last so every positional
+            // consumer of the earlier columns is untouched); a summary-only divergence between two builds
+            // must fail the convergence comparison rather than pass as equal.
+            ...nodes.map((n) => `N\t${fold(n.id)}\t${fold(n.kind)}\t${fold(n.source_path)}\t${prov(n)}\t${fold(n.summary)}`),
+            ...edges.map((e) => `E\t${fold(e.src)}\t${fold(e.dst)}\t${fold(e.rel)}\t${fold(e.source_path)}\t${prov(e)}`),
         ].join('\n');
     }
     /**
@@ -388,6 +431,16 @@ class RtmGraph {
     journalMode() {
         return String(this.db.pragma('journal_mode', { simple: true }) ?? '');
     }
+    /**
+     * @implements A-SPEC-569.5
+     * Live anchors per source file — distinct SPEC targets of `implements` edges, one GROUP BY.
+     * Feeds the anchor-density OBSERVATION at sealing time; nothing reads it into a verdict.
+     */
+    implementsAnchorCounts() {
+        return this.db.prepare(`SELECT source_path AS sourcePath, COUNT(DISTINCT dst) AS anchors FROM edges
+        WHERE rel='implements' AND source_path IS NOT NULL GROUP BY source_path ORDER BY source_path ASC`)
+            .all();
+    }
     nodeCount() { return this.db.prepare('SELECT COUNT(*) AS c FROM nodes').get().c; }
     edgeCount() { return this.db.prepare('SELECT COUNT(*) AS c FROM edges').get().c; }
     close() { this.db.close(); }

package/dist/holmes/spec/compat-impact.d.ts

@@ -23,4 +23,9 @@ export interface CompatCheckOpts {
     /** Repo-relative reader for the OS cross-check; null = file absent (skip, fail-open). */
     readFile?: (rel: string) => string | null;
 }
+/** `src/…` path tokens out of the Files to Touch section — backticks, bullets and commas tolerated.
+ * Backslashes normalize to `/` FIRST (adversarial round-1): a Windows author legitimately writes
+ * `src\holmes\hooks\stop.ts`, and un-normalized it walked straight past the surface prefixes —
+ * an OS-compat gate defeated by an OS path convention would be its own counterexample. */
+export declare function filesToTouch(spec: Spec): string[];
 export declare function checkCompatDeclared(spec: Spec, opts?: CompatCheckOpts): string | null;

package/dist/holmes/spec/compat-impact.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CELL_VERDICTS = exports.OS_CELLS = exports.HARNESS_CELLS = void 0;
+exports.filesToTouch = filesToTouch;
 exports.checkCompatDeclared = checkCompatDeclared;
 /**
  * REQ-565's enforcement device: the obligation to declare HARNESS (claude/codex/agy) and OS

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",