@holmes-lab/holmes-kit 0.14.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/approval-blockers.js

@@ -10,6 +10,7 @@ exports.unactionableCriteriaBlocker = unactionableCriteriaBlocker;
 const acceptance_quality_1 = require("./acceptance-quality");
 const validator_1 = require("./validator");
 const breaking_change_1 = require("./breaking-change");
+const compat_impact_1 = require("./compat-impact");
 const spec_digest_1 = require("./spec-digest");
 const spec_types_1 = require("./spec-types");
 const draft_1 = require("../reverse/draft");
@@ -204,6 +205,13 @@ function approvalBlockers(spec, resolve) {
     const breaking = (0, breaking_change_1.checkBreakingChangeDeclared)(candidate);
     if (breaking)
         out.push(breaking);
+    // @implements A-SPEC-565.1 — the compat duty pre-announced where breaking_change is: whatever the
+    // act refuses with, the gate must already have told the author (A-SPEC-182's parity). No file
+    // reader here — the gate context has no root — so the OS *content* cross-check stays act-only;
+    // the declaration syntax and the FtT harness-surface contradiction are fully pre-announced.
+    const compat = (0, compat_impact_1.checkCompatDeclared)(candidate);
+    if (compat)
+        out.push(compat);
     const stubs = placeholderSections(spec);
     if (stubs.length > 0) {
         out.push((0, exports.placeholderMessage)(stubs));

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

@@ -0,0 +1,31 @@
+import { Spec } from './spec-parser';
+/**
+ * REQ-565's enforcement device: the obligation to declare HARNESS (claude/codex/agy) and OS
+ * (windows/mac/linux) impact lives on the ACT of approval — the exact shape ADR-013 gave
+ * `breaking_change`, and for the same measured reason (a static `requiredFields` predicate turned
+ * 38 already-approved specs into ART-3 violations and bricked the harness; act-time converges
+ * instead: any spec that changes re-approves and acquires the fields, a spec that never changes
+ * can introduce no new incompatibility).
+ *
+ * WHY a gate and not a habit, measured twice in one day: an observability design came out
+ * Claude-biased (Stop hook + transcript_path is a Claude-only channel — the owner caught it), and
+ * the Stop hook's own header records that voluntarily-invoked discipline fired 0/143 times. Memory
+ * is rationale storage; control is a gate.
+ *
+ * WHAT THIS DOES NOT DO: verify the declarations are TRUE. Truth belongs to the layers that measure
+ * it — adapter parity (A-SPEC-336~338), doctor's wiring checks, on-device E2E. This gate makes
+ * skipping the thought impossible and makes a false declaration an auditable record.
+ */
+export declare const HARNESS_CELLS: readonly ["claude", "codex", "agy"];
+export declare const OS_CELLS: readonly ["windows", "mac", "linux"];
+export declare const CELL_VERDICTS: readonly ["supported", "unavailable", "n-a"];
+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

@@ -0,0 +1,141 @@
+"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
+ * (windows/mac/linux) impact lives on the ACT of approval — the exact shape ADR-013 gave
+ * `breaking_change`, and for the same measured reason (a static `requiredFields` predicate turned
+ * 38 already-approved specs into ART-3 violations and bricked the harness; act-time converges
+ * instead: any spec that changes re-approves and acquires the fields, a spec that never changes
+ * can introduce no new incompatibility).
+ *
+ * WHY a gate and not a habit, measured twice in one day: an observability design came out
+ * Claude-biased (Stop hook + transcript_path is a Claude-only channel — the owner caught it), and
+ * the Stop hook's own header records that voluntarily-invoked discipline fired 0/143 times. Memory
+ * is rationale storage; control is a gate.
+ *
+ * WHAT THIS DOES NOT DO: verify the declarations are TRUE. Truth belongs to the layers that measure
+ * it — adapter parity (A-SPEC-336~338), doctor's wiring checks, on-device E2E. This gate makes
+ * skipping the thought impossible and makes a false declaration an auditable record.
+ */
+exports.HARNESS_CELLS = ['claude', 'codex', 'agy'];
+exports.OS_CELLS = ['windows', 'mac', 'linux'];
+exports.CELL_VERDICTS = ['supported', 'unavailable', 'n-a'];
+/** Directory-or-file prefixes that ARE the harness surface. A trailing '/' is a directory boundary;
+ * without it the rule names a file stem (`cli/init` catches `cli/init.ts`), and the boundary test
+ * below keeps `hooks-util.ts` from matching `hooks/`. */
+const HARNESS_SURFACES = [
+    'src/holmes/hooks/',
+    'src/holmes/cli/init',
+    'src/holmes/cli/agents',
+    'src/holmes/cli/interactive-prompt',
+    'src/holmes/mcp/server',
+];
+/** Conservative OS-sensitivity signals — content properties, not directories. Grown by measurement,
+ * never by guess (the goal records this as an explicitly open list). */
+const OS_SIGNALS = ['process.platform', "'win32'", '"win32"', 'spawn(', 'spawnSync(', 'execFileSync(', '.ps1'];
+const FORMAT_HINT = (field, cells) => `${field} 형식: 'none: <실이유>' 또는 3셀 매핑 { ${cells.map((c) => `${c}: '<supported|unavailable|n-a>: <근거>'`).join(', ')} }`;
+/** A reason that says nothing is not a reason: empty, or still carrying the scaffold's TODO/TBD. */
+const emptyReason = (reason) => reason.trim() === '' || /\bTODO\b|\bTBD\b/i.test(reason);
+/**
+ * Validate one axis' declaration. Returns the refusal (naming the field) or the parsed shape:
+ * `none` (an irrelevance claim — cross-checkable) or `cells` (the axis was faced — exempt).
+ */
+function parseAxis(field, raw, cells) {
+    const err = (why) => ({ kind: 'error', message: `${field} ${why} — ${FORMAT_HINT(field, cells)}` });
+    if (raw === undefined || raw === null)
+        return err('선언이 없습니다 (REQ-565: 호환 고려는 봉인 의무)');
+    if (typeof raw === 'string') {
+        const i = raw.indexOf(':');
+        const grade = (i === -1 ? raw : raw.slice(0, i)).trim();
+        const reason = i === -1 ? '' : raw.slice(i + 1).trim();
+        if (grade !== 'none')
+            return err(`알 수 없는 문자열 선언 '${grade}'`);
+        if (emptyReason(reason))
+            return err('의 none 사유가 비었거나 placeholder(TODO/TBD)입니다');
+        return { kind: 'none' };
+    }
+    if (typeof raw === 'object' && !Array.isArray(raw)) {
+        const m = raw;
+        const keys = Object.keys(m);
+        for (const c of cells)
+            if (!(c in m))
+                return err(`매핑에 '${c}' 셀이 없습니다 (3셀 전부 필수)`);
+        for (const k of keys)
+            if (!cells.includes(k))
+                return err(`매핑에 알 수 없는 셀 '${k}'`);
+        for (const c of cells) {
+            const v = m[c];
+            if (typeof v !== 'string')
+                return err(`의 '${c}' 셀이 문자열이 아닙니다`);
+            const i = v.indexOf(':');
+            const verdict = (i === -1 ? v : v.slice(0, i)).trim();
+            const reason = i === -1 ? '' : v.slice(i + 1).trim();
+            if (!exports.CELL_VERDICTS.includes(verdict)) {
+                return err(`의 '${c}' 셀 어휘 '${verdict}' 는 supported|unavailable|n-a 가 아닙니다`);
+            }
+            if (emptyReason(reason))
+                return err(`의 '${c}' 셀 근거가 비었거나 placeholder 입니다`);
+        }
+        return { kind: 'cells' };
+    }
+    return err('의 형태가 문자열도 매핑도 아닙니다');
+}
+/** `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. */
+function filesToTouch(spec) {
+    const body = (spec.sections?.['Files to Touch'] ?? '')
+        .replace(/\\/g, '/')
+        .replace(/\/{2,}/g, '/'); // round-2: `src\\holmes` normalized to `src//holmes` and slid past the prefix
+    const out = [];
+    for (const m of body.matchAll(/src\/[\w./-]+/g))
+        out.push(m[0]);
+    return [...new Set(out)];
+}
+function checkCompatDeclared(spec, opts) {
+    if (spec.type !== 'A-SPEC')
+        return null;
+    const fm = (spec.frontmatter ?? {});
+    const harness = parseAxis('harness_impact', fm.harness_impact, exports.HARNESS_CELLS);
+    if (harness.kind === 'error')
+        return harness.message;
+    const os = parseAxis('os_impact', fm.os_impact, exports.OS_CELLS);
+    if (os.kind === 'error')
+        return os.message;
+    // Cross-checks apply ONLY to `none` — a 3-cell mapping already faced the axis, and re-litigating
+    // it here would punish exactly the declaration this gate exists to elicit (C1's lesson is that a
+    // DECLARATION must not be the only wall; an irrelevance CLAIM is what the machine can contradict).
+    const ftt = filesToTouch(spec);
+    if (harness.kind === 'none') {
+        for (const p of ftt) {
+            const hit = HARNESS_SURFACES.find((s) => (s.endsWith('/') ? p.startsWith(s) : p === s || p.startsWith(`${s}.`) || p.startsWith(`${s}/`)));
+            if (hit) {
+                return `harness_impact 는 none 인데 Files to Touch 의 '${p}' 는 하네스 표면(${hit})입니다 — 모순. 3셀 매핑으로 각 하네스의 영향을 기술하십시오.`;
+            }
+        }
+    }
+    if (os.kind === 'none' && opts?.readFile) {
+        for (const p of ftt) {
+            // round-2: an injected reader that THROWS (permissions, FIFO, anything) must degrade to
+            // "unreadable = skip", never crash the approval act — this check is a gate, not a hostage.
+            let text;
+            try {
+                text = opts.readFile(p);
+            }
+            catch {
+                text = null;
+            }
+            if (text === null || text === undefined)
+                continue; // a file that does not exist yet has no character
+            const sig = OS_SIGNALS.find((s) => text.includes(s));
+            if (sig) {
+                return `os_impact 는 none 인데 '${p}' 의 내용이 OS 신호 '${sig}' 를 담고 있습니다 — 모순. 3셀 매핑으로 각 OS 의 영향을 기술하십시오.`;
+            }
+        }
+    }
+    return null;
+}

package/dist/holmes/spec/spec-types.js

@@ -76,7 +76,9 @@ exports.SPEC_TYPES = {
         // blocked every turn, because all 38 governed A-SPECs are already approved. The duty belongs to
         // the ACT of approval (see spec/breaking-change.ts); this line exists so the field is visible
         // where someone looks up "what fields does an A-SPEC have", instead of hiding in a check.
-        stubOnlyFields: ['breaking_change'],
+        // @implements A-SPEC-565.1 — same shape, same reason: the compat duty (REQ-565) lives on the
+        // act of approval (spec/compat-impact.ts), and these lines exist for the reader, not the check.
+        stubOnlyFields: ['breaking_change', 'harness_impact', 'os_impact'],
         requiredSections: ['Objective', 'Inputs / Outputs', 'Behavior', 'Test Points', 'Files to Touch', 'Done When'],
     },
     'C-SPEC': {

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.14.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",