@holmes-lab/holmes-kit 0.15.0 → 0.16.0

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,44 @@ 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.
+    if (text === '' || text === 'TODO')
+        return title !== '' ? title : s.id;
+    // 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)}…`;
+    return title !== '' ? `${title} — ${sentence}` : sentence;
+}
 /**
  * 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 +135,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,7 +51,15 @@ 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-281 — how this node got here, or null if the node is unknown. */
     provenanceOfNode(id: string): Provenance | null;
@@ -72,6 +80,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

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,9 +118,20 @@ 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 (?,?,?,?,?,?,?,?,?,?,?,?)`);
+        this.nodeStmt.run(id, kind, sourcePath ?? null, summary ?? null, ...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 (?,?,?,?,?,?,?,?,?,?,?,?)`);
@@ -149,6 +165,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);
     }
@@ -340,10 +365,13 @@ class RtmGraph {
         // 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();
+        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)}`),
+            // @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${n.id}\t${n.kind}\t${n.source_path ?? ''}\t${prov(n)}\t${n.summary ?? ''}`),
             ...edges.map((e) => `E\t${e.src}\t${e.dst}\t${e.rel}\t${e.source_path ?? ''}\t${prov(e)}`),
         ].join('\n');
     }

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.16.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",