@holmes-lab/holmes-kit 0.17.0 → 0.19.0

package/dist/holmes/review/paired-power.js

@@ -0,0 +1,57 @@
+"use strict";
+// @implements A-SPEC-573.6
+// Every verdict in REQ-573 — S1 adopted, S2 held at 60, S3 conditional, S4 rejected — was reached
+// without asking whether the observed difference was large enough to be detectable at all. A
+// rejection that a study could never have detected is not evidence of absence, and an adoption of
+// a difference smaller than the noise is not evidence of presence. This computes both, from paired
+// observations, with no dependency and no randomness.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editSetF1 = editSetF1;
+exports.pairedPower = pairedPower;
+/** F1 over the SET of files, which is the edit set a caller actually acts on. */
+function editSetF1(predicted, truth) {
+    const p = new Set(predicted);
+    const t = new Set(truth);
+    if (p.size === 0 || t.size === 0)
+        return 0;
+    let hit = 0;
+    for (const f of p)
+        if (t.has(f))
+            hit++;
+    if (hit === 0)
+        return 0;
+    const precision = hit / p.size;
+    const recall = hit / t.size;
+    return (2 * precision * recall) / (precision + recall);
+}
+// Two-sided 0.975 and one-sided 0.80 critical values, by degrees of freedom. Small and explicit
+// rather than a dependency: the numbers a verdict rests on should be readable in the file that uses
+// them. Anything past the table is close enough to normal that the approximation is honest — and it
+// is reported as such rather than passed off as exact.
+const T975 = {
+    1: 12.706, 2: 4.303, 3: 3.182, 4: 2.776, 5: 2.571, 6: 2.447, 7: 2.365, 8: 2.306, 9: 2.262,
+    10: 2.228, 11: 2.201, 12: 2.179, 13: 2.160, 14: 2.145, 15: 2.131, 16: 2.120, 17: 2.110,
+    18: 2.101, 19: 2.093, 20: 2.086, 25: 2.060, 30: 2.042, 40: 2.021, 60: 2.000, 120: 1.980,
+};
+const T80 = {
+    1: 1.376, 2: 1.061, 3: 0.978, 4: 0.941, 5: 0.920, 6: 0.906, 7: 0.896, 8: 0.889, 9: 0.883,
+    10: 0.879, 11: 0.876, 12: 0.873, 13: 0.870, 14: 0.868, 15: 0.866, 16: 0.865, 17: 0.863,
+    18: 0.862, 19: 0.861, 20: 0.860, 25: 0.856, 30: 0.854, 40: 0.851, 60: 0.848, 120: 0.845,
+};
+const NORMAL_975 = 1.96;
+const NORMAL_80 = 0.8416;
+function pairedPower(diffs) {
+    const n = diffs.length;
+    if (n === 0)
+        return { n: 0, meanDiff: null, sdDiff: null, sem: null, mde80: null, approx: false };
+    const meanDiff = diffs.reduce((s, x) => s + x, 0) / n;
+    if (n < 2)
+        return { n, meanDiff, sdDiff: null, sem: null, mde80: null, approx: false };
+    const variance = diffs.reduce((s, x) => s + (x - meanDiff) ** 2, 0) / (n - 1);
+    const sdDiff = Math.sqrt(variance);
+    const sem = sdDiff / Math.sqrt(n);
+    const df = n - 1;
+    const exact = T975[df] !== undefined && T80[df] !== undefined;
+    const [tAlpha, tBeta] = exact ? [T975[df], T80[df]] : [NORMAL_975, NORMAL_80];
+    return { n, meanDiff, sdDiff, sem, mde80: (tAlpha + tBeta) * sem, approx: !exact };
+}

package/dist/holmes/review/replay-corpus.d.ts

@@ -44,6 +44,17 @@ export interface ReplayCase {
     /** Test files the commit changed. */
     tests: string[];
 }
+/**
+ * The PARENT-side line numbers a commit changed in one file.
+ *
+ * Parent-side, not head-side, because the symbol ranges these are intersected with come from the
+ * parent-time scan — the tree the analysis actually saw. Reading head-side numbers would line up
+ * the diff against a file the analyzer never had.
+ *
+ * Returns an empty list rather than throwing: a file the parent did not have (the commit created
+ * it) has no parent lines, and that is an answer, not a failure.
+ */
+export declare function changedParentLines(root: string, commit: string, file: string): number[];
 export declare const HOLMES_CORPUS: ReplayCorpus;
 /**
  * The second corpus. Measured 2026-08-29: 269 source files, 329 commits, 251 eligible cases, 959

package/dist/holmes/review/replay-corpus.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GEMINI_CLI_MEASUREMENT = exports.GEMINI_CLI_CORPUS = exports.JARVIS_CORPUS = exports.HOLMES_CORPUS = void 0;
+exports.changedParentLines = changedParentLines;
 exports.casesFor = casesFor;
 exports.thinSpecs = thinSpecs;
 exports.casesAvoidingRecent = casesAvoidingRecent;
@@ -44,6 +45,39 @@ const path = __importStar(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const maintenance_analyze_1 = require("../mcp/maintenance-analyze");
 const TS_FAMILY = (f) => f.endsWith('.ts') && !f.endsWith('.d.ts');
+// @implements A-SPEC-573.3
+/**
+ * The PARENT-side line numbers a commit changed in one file.
+ *
+ * Parent-side, not head-side, because the symbol ranges these are intersected with come from the
+ * parent-time scan — the tree the analysis actually saw. Reading head-side numbers would line up
+ * the diff against a file the analyzer never had.
+ *
+ * Returns an empty list rather than throwing: a file the parent did not have (the commit created
+ * it) has no parent lines, and that is an answer, not a failure.
+ */
+function changedParentLines(root, commit, file) {
+    let raw;
+    try {
+        raw = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'show', '--unified=0', '--format=', commit, '--', file], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+    }
+    catch {
+        return [];
+    }
+    const lines = [];
+    for (const line of raw.split('\n')) {
+        // `@@ -12,3 +12,4 @@` — the old-side start and count. A count of 0 marks a pure insertion, which
+        // touched no existing line and therefore no existing symbol.
+        const m = /^@@ -(\d+)(?:,(\d+))? /.exec(line);
+        if (m === null)
+            continue;
+        const start = Number(m[1]);
+        const count = m[2] === undefined ? 1 : Number(m[2]);
+        for (let i = 0; i < count; i++)
+            lines.push(start + i);
+    }
+    return lines;
+}
 exports.HOLMES_CORPUS = {
     root: path.resolve(__dirname, '../../..'),
     // @implements A-SPEC-443 — pinned so the floors stay floors. Our own repository moves too; the

package/dist/holmes/review/run-replay.js

@@ -46,6 +46,9 @@ const node_child_process_1 = require("node:child_process");
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const language_parser_1 = require("../cpg/language-parser");
+// @implements A-SPEC-573.4 — same bound as the handler, one constant so the two cannot drift.
+const defuse_bound_1 = require("../mcp/defuse-bound");
 const rtm_builder_1 = require("../rtm/rtm-builder");
 const rtm_graph_1 = require("../rtm/rtm-graph");
 const test_scope_1 = require("../rtm/test-scope");
@@ -55,6 +58,7 @@ const maintenance_analyze_1 = require("../mcp/maintenance-analyze");
 const point_in_time_replay_1 = require("./point-in-time-replay");
 const evaluation_metrics_1 = require("./evaluation-metrics");
 const replay_corpus_1 = require("./replay-corpus");
+const symbol_truth_1 = require("./symbol-truth");
 const semantic_arm_1 = require("./semantic-arm");
 // @implements A-SPEC-479 — pre-emission verification of the union answer (measurement only).
 // @implements A-SPEC-488 — lexPoverty drives the gate simulation ("uncited ∨ lexically poor").
@@ -212,25 +216,77 @@ async function runReplay(corpus, limit, opts = {}) {
                 // reported from it understated what a caller actually gets — a benchmark measuring something
                 // adjacent to the product is worse than one measuring nothing, because it reads as if it
                 // measured the product.
-                const known = new Set(scanned.map((f) => f.sourcePath));
+                // @implements A-SPEC-573.3 — and the boost is handed over UNFILTERED. This benchmark used to
+                // narrow it to the scanned set on its own, which is a filter the product did not have: the
+                // pipeline being scored was not the pipeline that shipped, so a defect worth 63.3% of the
+                // product's emitted slots read as six-decimal NO MOVEMENT here (measured, S1). Admission is
+                // the product's business now (A-SPEC-573.1/573.2), and the bench inherits whatever it does.
                 const profile = (0, commit_text_1.commitTextProfile)(corpus.root, parent, 400);
-                const ct = (0, commit_text_1.rankByCommitText)(c.subject, profile, 300).filter((h) => known.has(h.file));
+                const ct = (0, commit_text_1.rankByCommitText)(c.subject, profile, 300);
                 const top = ct[0]?.score ?? 0;
                 const commitTextBoost = {};
                 if (top > 0)
                     for (const h of ct)
                         commitTextBoost[h.file] = h.score / top;
-                const result = (0, maintenance_analyze_1.analyzeMaintenance)({
+                const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
                     request: c.subject, scanned, specs, graph, testAnchors: anchors, history: [], changePrior, commitTextBoost,
                     groundTruth: { files: c.files, tests: c.tests },
                     basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
                     coverage: { scannedFiles: scanned.length, skippedFiles: [], unsupportedLanguages: [] },
+                    defUse,
                 });
+                // @implements A-SPEC-573.4 — the same two-pass the handler runs, for the same reason the
+                // bench stopped filtering the boost on its own: what is measured has to be what ships.
+                const firstPass = analyzeWith();
+                const result = (() => {
+                    const targets = firstPass.candidates.slice(0, defuse_bound_1.DEFUSE_TOP_FILES).map((x) => x.file);
+                    if (targets.length === 0)
+                        return firstPass;
+                    const defUse = {};
+                    const parser = new language_parser_1.TreeSitterTsParser();
+                    for (const file of targets) {
+                        try {
+                            const lang = (0, cpg_scanner_1.langForPath)(file);
+                            if (!(0, language_parser_1.hasDataFlowWalk)(lang))
+                                continue;
+                            const facts = parser.extractDataFlow(fs.readFileSync(path.join(dest, file), 'utf8'), lang);
+                            if (facts !== undefined)
+                                defUse[file] = facts;
+                        }
+                        catch { /* fail-open, per file */ }
+                    }
+                    return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
+                })();
                 const ranked = result.candidates.map((x) => x.file);
                 // @implements A-SPEC-469 — the union scores what a caller actually RECEIVES as the impact
                 // answer, and that surface is now the graded rankedImpact (the closure stays gate-facing).
                 const impacted = (result.impacts?.rankedImpact ?? []).map((r) => r.file);
-                outcomes.push({ ranked, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests });
+                // @implements A-SPEC-573.3 — the function axis, derived from what this loop already holds:
+                // the commit's parent-side changed lines and the parent-time scan's symbol ranges. A case
+                // whose change fell outside every symbol contributes no truth and drops out of that
+                // denominator; it is not scored zero.
+                const byPathScanned = new Map(scanned.map((f) => [f.sourcePath, f]));
+                const truthSymbols = [];
+                for (const file of c.files) {
+                    const sf = byPathScanned.get(file);
+                    if (sf === undefined)
+                        continue;
+                    const ranges = sf.symbols.map((sy) => ({ name: sy.qualifiedName, startLine: sy.startLine, endLine: sy.endLine }));
+                    for (const name of (0, symbol_truth_1.symbolsTouched)(ranges, (0, replay_corpus_1.changedParentLines)(corpus.root, c.commit, file))) {
+                        if (!truthSymbols.includes(name))
+                            truthSymbols.push(name);
+                    }
+                }
+                // The prediction is the symbols the emitted candidates carried, in candidate order — the
+                // same list a caller reads, never a separately computed one.
+                const rankedSymbols = [];
+                for (const cand of result.candidates) {
+                    for (const sy of cand.symbols)
+                        if (!rankedSymbols.includes(sy))
+                            rankedSymbols.push(sy);
+                }
+                outcomes.push({ ranked, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests,
+                    truthSymbols, rankedSymbols });
                 // @implements A-SPEC-487 — the dump: 2-pass with semantic injected when asked (vectors
                 // only for the files the 1-pass surfaced — the hot-path lookup contract holds), 1-pass
                 // otherwise. Nothing here feeds outcomes or any pin.

package/dist/holmes/review/symbol-truth.d.ts

@@ -0,0 +1,14 @@
+export interface SymbolRange {
+    name: string;
+    startLine: number;
+    endLine: number;
+}
+/**
+ * The symbols a commit's changed lines fall inside, in symbol-list order, deduped.
+ *
+ * A change that lands outside every symbol (an import line, a top-level constant) yields nothing —
+ * and a case with no symbol truth drops OUT of the symbol denominator rather than scoring zero. An
+ * unanswerable case is not a failed one, which is the same rule `evaluationMetrics` already applies
+ * to files.
+ */
+export declare function symbolsTouched(symbols: readonly SymbolRange[], changedLines: readonly number[]): string[];

package/dist/holmes/review/symbol-truth.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.symbolsTouched = symbolsTouched;
+/**
+ * The symbols a commit's changed lines fall inside, in symbol-list order, deduped.
+ *
+ * A change that lands outside every symbol (an import line, a top-level constant) yields nothing —
+ * and a case with no symbol truth drops OUT of the symbol denominator rather than scoring zero. An
+ * unanswerable case is not a failed one, which is the same rule `evaluationMetrics` already applies
+ * to files.
+ */
+function symbolsTouched(symbols, changedLines) {
+    if (symbols.length === 0 || changedLines.length === 0)
+        return [];
+    const out = [];
+    for (const s of symbols) {
+        // Both ends inclusive: the signature line and the closing line are part of the symbol.
+        if (changedLines.some((line) => line >= s.startLine && line <= s.endLine) && !out.includes(s.name)) {
+            out.push(s.name);
+        }
+    }
+    return out;
+}

package/dist/holmes/rtm/decision-context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The DECISION context of a candidate — "why is this the way it is?".
+ *
+ * A person diagnosing a defect asks two questions in order: what broke (the candidates), and then
+ * why this code was left this way (the decision). The graph already answers the second — REQ-571
+ * put store ADRs into the decision population and A-SPEC-293 already builds `constrained_by` from
+ * citations — so this is a lookup, not a new mechanism: no new edge kind, no new tool.
+ *
+ * OBSERVATION ONLY. The context rides beside a candidate; nothing here enters the ranking, the
+ * score, or any gate (the c6 rule — prose informs, it never adjudicates).
+ */
+export interface DecisionContextEntry {
+    adr: string;
+    /** The decision's own sentence, or null when the store carries no summary for it (id stays). */
+    decision: string | null;
+}
+export interface DecisionGraphLike {
+    decisionsConstraining(nodeIds: readonly string[]): string[];
+    summaryOf(id: string): string | null;
+}
+/** How many decisions ride beside one candidate. A prose constant — never a verdict input. */
+export declare const MAX_DECISIONS = 3;
+export declare function decisionContextFor(files: readonly string[], specIdsOf: (file: string) => readonly string[], graph: DecisionGraphLike): Map<string, DecisionContextEntry[]>;

package/dist/holmes/rtm/decision-context.js

@@ -0,0 +1,47 @@
+"use strict";
+// @implements A-SPEC-572.3
+/**
+ * The DECISION context of a candidate — "why is this the way it is?".
+ *
+ * A person diagnosing a defect asks two questions in order: what broke (the candidates), and then
+ * why this code was left this way (the decision). The graph already answers the second — REQ-571
+ * put store ADRs into the decision population and A-SPEC-293 already builds `constrained_by` from
+ * citations — so this is a lookup, not a new mechanism: no new edge kind, no new tool.
+ *
+ * OBSERVATION ONLY. The context rides beside a candidate; nothing here enters the ranking, the
+ * score, or any gate (the c6 rule — prose informs, it never adjudicates).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DECISIONS = void 0;
+exports.decisionContextFor = decisionContextFor;
+/** How many decisions ride beside one candidate. A prose constant — never a verdict input. */
+exports.MAX_DECISIONS = 3;
+function decisionContextFor(files, specIdsOf, graph) {
+    const out = new Map();
+    for (const file of files) {
+        let adrs = [];
+        try {
+            // The file itself AND the specs it anchors: a person chasing "why" follows both, and the
+            // constraint is often recorded one level up, on the spec rather than on the file.
+            adrs = graph.decisionsConstraining([
+                `FILE:${file}`,
+                ...specIdsOf(file).map((id) => `SPEC:${id}`),
+            ]);
+        }
+        catch {
+            continue;
+        } // an unreadable graph yields no context, never a throw
+        const shown = [...new Set(adrs)].sort().slice(0, exports.MAX_DECISIONS);
+        if (shown.length === 0)
+            continue; // no entry rather than an invented empty list
+        out.set(file, shown.map((adr) => {
+            let decision = null;
+            try {
+                decision = graph.summaryOf(`SPEC:${adr}`);
+            }
+            catch { /* id stays, prose does not */ }
+            return { adr, decision };
+        }));
+    }
+    return out;
+}

package/dist/holmes/rtm/defuse-symbols.d.ts

@@ -0,0 +1,17 @@
+import type { DataFlowFacts } from '../cpg/language-parser';
+/**
+ * Order a file's function names by how close they sit, in def-use terms, to what the request says.
+ *
+ * Three tiers, stable within each so the result is deterministic (the downstream lists are
+ * position-indexed): functions the request names directly, functions one def-use step from those,
+ * then everything else in its original order. A term matching nothing leaves the order untouched —
+ * an empty first tier must not shuffle the list.
+ */
+export declare function rankSymbolsByDefUse(facts: DataFlowFacts, terms: readonly string[], order: readonly string[]): string[];
+/**
+ * Append what def-use suggested behind what the lexical layer matched.
+ *
+ * Never in front: this repository has already measured a re-ranker deleting the lexical answer, so
+ * a second signal rides behind the first rather than replacing it.
+ */
+export declare function enrichCandidateSymbols(lexical: readonly string[], suggested: readonly string[]): string[];

package/dist/holmes/rtm/defuse-symbols.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rankSymbolsByDefUse = rankSymbolsByDefUse;
+exports.enrichCandidateSymbols = enrichCandidateSymbols;
+/** Names a function mentions anywhere the walk recovered them: params, defs, and call arguments. */
+function surfaceOf(facts) {
+    const out = new Map();
+    const push = (fn, ...words) => {
+        const bucket = out.get(fn) ?? out.set(fn, []).get(fn);
+        for (const w of words)
+            if (w !== '' && !bucket.includes(w))
+                bucket.push(w);
+    };
+    for (const p of facts.params)
+        push(p.fn, p.name);
+    for (const d of facts.defs)
+        push(d.fn, d.name, ...d.expr.refs, ...d.expr.callees);
+    for (const c of facts.calls) {
+        push(c.fn, c.callee);
+        for (const a of c.args)
+            push(c.fn, ...a.refs, ...a.callees);
+    }
+    for (const r of facts.returns)
+        push(r.fn, ...r.expr.refs, ...r.expr.callees);
+    return out;
+}
+/**
+ * Order a file's function names by how close they sit, in def-use terms, to what the request says.
+ *
+ * Three tiers, stable within each so the result is deterministic (the downstream lists are
+ * position-indexed): functions the request names directly, functions one def-use step from those,
+ * then everything else in its original order. A term matching nothing leaves the order untouched —
+ * an empty first tier must not shuffle the list.
+ */
+function rankSymbolsByDefUse(facts, terms, order) {
+    if (order.length === 0)
+        return [];
+    const lowered = terms.map((t) => t.toLowerCase()).filter((t) => t !== '');
+    if (lowered.length === 0)
+        return [...order];
+    const surface = surfaceOf(facts);
+    // A function is "named" when a request term appears in its own name or in any identifier its
+    // body touches. Substring, not equality: `config` has to reach `configPath`.
+    const names = (fn) => [fn, ...(surface.get(fn) ?? [])];
+    const direct = new Set();
+    for (const fn of new Set([...order, ...surface.keys()])) {
+        if (names(fn).some((n) => lowered.some((t) => n.toLowerCase().includes(t))))
+            direct.add(fn);
+    }
+    if (direct.size === 0)
+        return [...order];
+    // One def-use step: a function that reads what a direct one defined, or that sits on either end
+    // of a call with it. Call adjacency counts BOTH ways — the caller of a named function is as
+    // relevant as its callee, and a one-directional rule would silently favour one.
+    const definedByDirect = new Set();
+    for (const d of facts.defs)
+        if (direct.has(d.fn))
+            definedByDirect.add(d.name);
+    const near = new Set();
+    const mark = (fn) => { if (!direct.has(fn))
+        near.add(fn); };
+    for (const d of facts.defs)
+        if (d.expr.refs.some((r) => definedByDirect.has(r)))
+            mark(d.fn);
+    for (const c of facts.calls) {
+        if (c.args.some((a) => a.refs.some((r) => definedByDirect.has(r))))
+            mark(c.fn);
+        if (direct.has(c.fn))
+            mark(c.callee);
+        if (direct.has(c.callee))
+            mark(c.fn);
+    }
+    for (const r of facts.returns)
+        if (r.expr.refs.some((x) => definedByDirect.has(x)))
+            mark(r.fn);
+    const tier = (fn) => (direct.has(fn) ? 0 : near.has(fn) ? 1 : 2);
+    return [...order].sort((a, b) => tier(a) - tier(b) || order.indexOf(a) - order.indexOf(b));
+}
+/**
+ * Append what def-use suggested behind what the lexical layer matched.
+ *
+ * Never in front: this repository has already measured a re-ranker deleting the lexical answer, so
+ * a second signal rides behind the first rather than replacing it.
+ */
+function enrichCandidateSymbols(lexical, suggested) {
+    const out = [...lexical];
+    for (const s of suggested)
+        if (!out.includes(s))
+            out.push(s);
+    return out;
+}

package/dist/holmes/rtm/incremental.js

@@ -56,7 +56,12 @@ function applyIncremental(graph, changes, ctx) {
     }
     if (!ctx.allScanned)
         return { callEdgesResolved: false };
+    // @implements A-SPEC-573.5 — `calls_ambiguous` is rebuilt by the same pass, so it must be cleared
+    // by the same pass. Missing it left a stale candidate edge behind when an ambiguity RESOLVED
+    // (the second definer was deleted), and incremental stopped converging with a full rebuild —
+    // caught by A-SPEC-280's convergence property, which is exactly what it is for.
     graph.removeEdgesByRel('calls');
+    graph.removeEdgesByRel('calls_ambiguous');
     (0, rtm_builder_1.addCallEdges)(ctx.allScanned(), graph, ctx.buildOptions);
     return { callEdgesResolved: true };
 }

package/dist/holmes/rtm/localize.js

@@ -10,8 +10,10 @@ exports.localizeIssue = localizeIssue;
  * repository's `S-<n>` slice shorthand (which names the whole REQ->T-SPEC chain at that number).
  * The prefix is REQUIRED — a bare `262` in "262 files were rewritten" is a number, not a citation.
  */
-const CITATION = /\b(?:(A-SPEC|H-SPEC|T-SPEC|C-SPEC|REQ)-(\d+(?:\.\d+)?)|S-(\d+(?:\.\d+)?))\b/gi;
-const CITABLE_KINDS = ['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC', 'C-SPEC'];
+// @implements A-SPEC-571.2 — ADR is citable like any governed id (recognition only; the match
+// SCORING population stays A-SPEC-limited below, so an ADR never admits or reorders a file).
+const CITATION = /\b(?:(A-SPEC|H-SPEC|T-SPEC|C-SPEC|ADR|REQ)-(\d+(?:\.\d+)?)|S-(\d+(?:\.\d+)?))\b/gi;
+const CITABLE_KINDS = ['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC', 'C-SPEC', 'ADR'];
 /**
  * @implements A-SPEC-273
  * How much a citation is worth, normalized by the file's anchor count exactly as the lexical spec

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

@@ -16,6 +16,14 @@ import { ScannedFile } from '../cpg/cpg-scanner';
  */
 export interface ResolutionReport {
     resolved: number;
+    /**
+     * @implements A-SPEC-573.5
+     * Candidate edges kept for a call whose name is defined in more than one place. Census on this
+     * repository (2026-09-08): 102 qualified-name and 590 last-segment collisions were being dropped
+     * against 3,067 resolved edges — 22.6% of the call graph, at a mean fan-out of 2.29. They ride on
+     * the `calls_ambiguous` relation, which every certainty-requiring reader filters out by name.
+     */
+    ambiguousEdges: number;
     /** Callee defined in several files: precision-over-recall refused to guess. A real miss. */
     ambiguous: number;
     /** Callee defined nowhere in the scan — usually an external package or runtime builtin. */

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

@@ -73,6 +73,8 @@ const INTENT_SECTION = {
     'REQ': 'Problem / Need',
     'H-SPEC': 'Intent',
     'A-SPEC': 'Objective',
+    // @implements A-SPEC-571.2 — a decision's intent IS its Decision line.
+    'ADR': 'Decision',
 };
 /** Longest intent sentence carried into the graph — a bound, applied deterministically. */
 const SUMMARY_SENTENCE_CAP = 200;
@@ -137,7 +139,7 @@ function buildRtm(specs, scanned, graph, opts) {
     // on a 56k-insert graph (216 ms -> 173 ms with a transaction; 88 -> 52 ms with cached statements).
     // It also makes a failed build atomic — no half-graph that could be mistaken for a complete one.
     let resolution = {
-        resolved: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
+        resolved: 0, ambiguousEdges: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
     };
     graph.transaction(() => {
         // Add spec nodes and dependencies
@@ -183,7 +185,7 @@ function buildRtm(specs, scanned, graph, opts) {
  */
 function addCallEdges(scanned, graph, opts) {
     const report = {
-        resolved: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
+        resolved: 0, ambiguousEdges: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
     };
     // @implements A-SPEC-300
     // Indexes are built PER LANGUAGE FAMILY. Resolution used to look across the whole scan, so a Java
@@ -245,11 +247,37 @@ function addCallEdges(scanned, graph, opts) {
             }
             const family = familyOf(f.sourcePath);
             const table = definedIn.get(family);
+            // @implements A-SPEC-573.5 — an ambiguous target is a CANDIDATE SET, not a dead end. Both
+            // shapes of ambiguity keep every candidate on `calls_ambiguous`; `calls` still means "one
+            // place, certain", so nothing that reads certainty changes. Emitting nothing was buying
+            // precision at the cost of 22.6% of the call graph.
+            const ambiguousCandidates = (qn, paths) => {
+                for (const p of paths) {
+                    const to = `CODE:${qn}@${p}`;
+                    if (to === fromId)
+                        continue; // self-recursion carries no impact, ambiguous or not
+                    graph.addEdge(fromId, to, 'calls_ambiguous', f.sourcePath, fact(opts, `${f.sourcePath}`, 'name-resolution', null));
+                    report.ambiguousEdges++;
+                }
+            };
             let target = null;
             if (table?.has(e.to))
                 target = { qn: e.to, paths: table.get(e.to) };
-            else
-                target = byLastSegment.get(family)?.get(e.to) ?? null;
+            else {
+                const byLast = byLastSegment.get(family);
+                const hit = byLast?.get(e.to);
+                if (hit === null) {
+                    // The last segment is owned by several qualified names — keep every owner as a candidate.
+                    for (const [qn, paths] of table ?? []) {
+                        const last = qn.includes('.') ? qn.slice(qn.lastIndexOf('.') + 1) : qn;
+                        if (last === e.to)
+                            ambiguousCandidates(qn, paths);
+                    }
+                    report.unknownTarget++;
+                    continue;
+                }
+                target = hit ?? null;
+            }
             if (!target) {
                 report.unknownTarget++;
                 continue;
@@ -257,9 +285,10 @@ function addCallEdges(scanned, graph, opts) {
             const sameFile = target.paths.includes(f.sourcePath);
             const path = sameFile ? f.sourcePath : (target.paths.length === 1 ? target.paths[0] : null);
             if (!path) {
+                ambiguousCandidates(target.qn, target.paths);
                 report.ambiguous++;
                 continue;
-            } // defined in several files — emit nothing
+            }
             const toId = `CODE:${target.qn}@${path}`;
             if (toId === fromId) {
                 report.selfReference++;

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

@@ -136,6 +136,17 @@ export declare class RtmGraph {
          */
         maxCalleeInDegree?: number;
     }): string[];
+    /**
+     * Every resolved FILE->FILE `imports` edge, as repo-relative path pairs.
+     *
+     * Exists because cycle detection needs the whole import graph at once, and the alternative —
+     * parsing `dumpCanonical()` — builds a multi-megabyte string on every call to answer a question
+     * one query answers.
+     */
+    importEdges(): Array<{
+        from: string;
+        to: string;
+    }>;
     /**
      * @implements A-SPEC-289
      * Repo-relative paths of the files that import this one, via resolved FILE->FILE `imports` edges.

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

@@ -224,6 +224,19 @@ class RtmGraph {
             : this.callees(id).filter((callee) => this.callerCount(callee) <= limit);
         return [...new Set([...this.impactSourcesOf(id), ...downstream])].sort();
     }
+    // @implements A-SPEC-574.2
+    /**
+     * Every resolved FILE->FILE `imports` edge, as repo-relative path pairs.
+     *
+     * Exists because cycle detection needs the whole import graph at once, and the alternative —
+     * parsing `dumpCanonical()` — builds a multi-megabyte string on every call to answer a question
+     * one query answers.
+     */
+    importEdges() {
+        return this.db.prepare("SELECT DISTINCT src, dst FROM edges WHERE rel='imports' ORDER BY src ASC, dst ASC")
+            .all()
+            .map((r) => ({ from: r.src.replace(/^FILE:/, ''), to: r.dst.replace(/^FILE:/, '') }));
+    }
     /**
      * @implements A-SPEC-289
      * Repo-relative paths of the files that import this one, via resolved FILE->FILE `imports` edges.

package/dist/holmes/spec/legacy-fields.d.ts

@@ -0,0 +1,2 @@
+/** Frontmatter key that carries a pre-migration `depends_on` value. */
+export declare const LEGACY_DEPENDS_FIELD = "legacy_depends_on";

package/dist/holmes/spec/legacy-fields.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_DEPENDS_FIELD = void 0;
+// @implements A-SPEC-574.3
+// One constant, in a module neither side owns. `spec-parser` needed the field name and `legacy-format`
+// needed the parser's `Spec` type, so each imported the other — a cycle held up by a single string.
+// Shared things belong to a third module; that is the whole rule.
+/** Frontmatter key that carries a pre-migration `depends_on` value. */
+exports.LEGACY_DEPENDS_FIELD = 'legacy_depends_on';

package/dist/holmes/spec/legacy-format.d.ts

@@ -48,7 +48,7 @@ export declare const LEGACY_STATUS_FIELD = "legacy_status";
  * computation — asserting it anyway is the fabrication this repository keeps removing. Verbatim
  * preservation leaves the judgement to a person who can actually make it.
  */
-export declare const LEGACY_DEPENDS_FIELD = "legacy_depends_on";
+export { LEGACY_DEPENDS_FIELD } from './legacy-fields';
 /**
  * Classify a document by FORMAT, not by validity.
  *

package/dist/holmes/spec/legacy-format.js

@@ -21,7 +21,10 @@ exports.LEGACY_STATUS_FIELD = 'legacy_status';
  * computation — asserting it anyway is the fabrication this repository keeps removing. Verbatim
  * preservation leaves the judgement to a person who can actually make it.
  */
-exports.LEGACY_DEPENDS_FIELD = 'legacy_depends_on';
+// @implements A-SPEC-574.3 — moved to `legacy-fields` and re-exported, so existing importers
+// keep working while the cycle it created is gone.
+var legacy_fields_1 = require("./legacy-fields");
+Object.defineProperty(exports, "LEGACY_DEPENDS_FIELD", { enumerable: true, get: function () { return legacy_fields_1.LEGACY_DEPENDS_FIELD; } });
 /**
  * Classify a document by FORMAT, not by validity.
  *