@holmes-lab/holmes-kit 0.17.0 → 0.19.0

package/dist/holmes/mcp/handlers.d.ts

@@ -1,6 +1,9 @@
 import { SpecStore } from '../spec/spec-store';
+import { Spec } from '../spec/spec-parser';
 import { MaintenanceGroundTruth, MaintenanceAnalysis } from './maintenance-analyze';
 import { Action } from '../guardrail/phase';
+import { ScannedFile } from '../cpg/cpg-scanner';
+import { type DecisionRecord, type DecisionCitation } from '../rtm/rtm-builder';
 import { Basis } from './basis';
 import { Finding } from '../review/findings';
 import { Approval, Enforcement } from '../guardrail/risk-gate';
@@ -53,6 +56,16 @@ export declare function makeHandlers(store: SpecStore, opts?: ElicitOpts): RawHa
     }>;
 };
 type RawHandlers = ReturnType<typeof makeRawHandlers>;
+/**
+ * @implements A-SPEC-293
+ * Read `.ax/decisions/*.md` and find who cites them. Citation is the link, chosen by measurement:
+ * `governs` resolves 9 of 65 names to symbols while 37 source files and 71 spec files cite an ADR.
+ * Failure here is never fatal — a project with no decisions directory simply has no decisions.
+ */
+export declare function collectDecisions(root: string, scanned: readonly ScannedFile[], specs: readonly Spec[]): {
+    decisions: DecisionRecord[];
+    citations: DecisionCitation[];
+};
 declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
     spec_create(a: any): Promise<{
         ok: boolean;
@@ -207,6 +220,16 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         ok: boolean;
         reason: string;
     } | {
+        graphPreview?: {
+            impact?: import("../rtm/impact-advisory").ImpactAdvisory;
+            density?: import("../rtm/anchor-density").AnchorDensityFinding[];
+            cycles?: {
+                findings: import("../cpg/cycle-detect").CycleFinding[];
+                note: string;
+            };
+            architecture?: import("../cpg/arch-observe").ArchObservation[];
+            graphAsOf?: string;
+        } | undefined;
         id: string;
         type?: string;
         status: string;

package/dist/holmes/mcp/handlers.js

@@ -37,6 +37,7 @@ exports.HandlerRefusal = void 0;
 exports.isHandlerRefusal = isHandlerRefusal;
 exports.unreadableAmong = unreadableAmong;
 exports.makeHandlers = makeHandlers;
+exports.collectDecisions = collectDecisions;
 // @implements A-SPEC-293
 // @implements A-SPEC-292
 // @implements A-SPEC-290
@@ -44,6 +45,8 @@ exports.makeHandlers = makeHandlers;
 // @implements A-SPEC-277
 // @implements A-SPEC-269
 // @implements A-SPEC-267
+// @implements A-SPEC-573.4 — shared with the benchmark so the two cannot drift.
+const defuse_bound_1 = require("./defuse-bound");
 const fs = __importStar(require("node:fs"));
 const http = __importStar(require("node:http"));
 const assoc_arm_1 = require("../assoc/assoc-arm");
@@ -204,6 +207,8 @@ const ledger_timeline_1 = require("../governance/ledger-timeline");
 const version_conflict_1 = require("../spec/version-conflict");
 const ledger_store_1 = require("../governance/ledger-store");
 const provenance_chain_1 = require("../governance/provenance-chain");
+// @implements A-SPEC-574.3 — the caller owns the store and hands the chain the question.
+const ledger_store_2 = require("../governance/ledger-store");
 const ledger_lock_1 = require("../governance/ledger-lock");
 const decision_ledger_1 = require("../guardrail/decision-ledger");
 const cspec_change_1 = require("../guardrail/cspec-change");
@@ -699,8 +704,24 @@ function collectDecisions(root, scanned, specs) {
             });
         }
     }
-    catch {
-        return { decisions: [], citations: [] };
+    catch { /* @implements A-SPEC-571.2 — no legacy .ax/decisions dir is not "no decisions": store
+      ADRs below are still a source. An unreadable dir degrades to the empty legacy set, not an early
+      return that would skip the store population. */
+    }
+    // @implements A-SPEC-571.2 — store ADRs JOIN the decisions population, so the existing consumers
+    // (DECISION nodes, constrained_by citations, supersedes) light up with no new edge kind. A store
+    // ADR is the canon: same id in legacy .ax/decisions is replaced (store wins).
+    for (const spec of specs) {
+        if (spec.type !== 'ADR')
+            continue;
+        const sup = spec.frontmatter?.supersedes;
+        const supersedes = typeof sup === 'string' && sup.trim() && sup.trim() !== 'null' ? sup.trim() : null;
+        const idx = decisions.findIndex((d) => d.id === spec.id);
+        const rec = { id: spec.id, title: spec.title, status: spec.status, supersedes };
+        if (idx >= 0)
+            decisions[idx] = rec;
+        else
+            decisions.push(rec);
     }
     const ids = new Set(decisions.map((d) => d.id));
     // @implements A-SPEC-546.1 — recognise ADR-\d{3,} (4-digit ADRs no longer invisible), via a pure fn.
@@ -1330,7 +1351,117 @@ function makeRawHandlers(store, opts) {
                 const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
                 return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
             }
-            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, resolver(all)) };
+            // @implements A-SPEC-572.1
+            // The graph advisory, delivered at DESIGN time. Measured on our own work: A-SPEC-571.1's
+            // sealing advisory named the exact cluster three regressions then landed in — and by then
+            // the design was done. The calculation was never the gap; the delivery time was. So the
+            // read-only "what is blocking this right now" tool also answers "what will this scope leak,
+            // and where is it dense" — using the SAME functions spec_approve calls, so the preview can
+            // never disagree with the seal. Read-only stays read-only: no scan, no build, no ledger
+            // append (a query must not pollute the observation denominator), and every failure degrades
+            // to an absent field on an otherwise identical response.
+            let graphPreview;
+            try {
+                if (cur.spec.type === 'A-SPEC' && a.root) {
+                    const dbPath = path.join(a.root, '.ax', 'rtm.sqlite');
+                    if (fs.existsSync(dbPath)) {
+                        const { declaredImpactGap } = require('../rtm/impact-advisory');
+                        const { anchorDensityFindings } = require('../rtm/anchor-density');
+                        const { filesToTouch } = require('../spec/compat-impact');
+                        const { RtmGraph } = require('../rtm/rtm-graph');
+                        const graph = new RtmGraph(dbPath);
+                        try {
+                            const ftt = filesToTouch(cur.spec);
+                            const impact = declaredImpactGap(ftt, graph, (rel) => { try {
+                                return fs.readFileSync(path.join(a.root, rel), 'utf8');
+                            }
+                            catch {
+                                return null;
+                            } });
+                            const density = anchorDensityFindings(ftt, graph.implementsAnchorCounts());
+                            // @implements A-SPEC-574.2 — the computation lives in cycle-detect; this file holds
+                            // the wiring only (measured: 85 anchors here against a p90 of 7).
+                            const { cycleAdvisory, classifyEdgeByTarget, CYCLE_ADVISORY_NOTE } = require('../cpg/cycle-detect');
+                            const readCache = new Map();
+                            const readSource = (rel) => {
+                                const hit = readCache.get(rel);
+                                if (hit !== undefined)
+                                    return hit;
+                                // A read failure degrades to the conservative kind rather than losing the finding.
+                                let text = '';
+                                try {
+                                    text = fs.readFileSync(path.join(a.root, rel), 'utf8');
+                                }
+                                catch {
+                                    text = '';
+                                }
+                                readCache.set(rel, text);
+                                return text;
+                            };
+                            const cycleFindings = cycleAdvisory(ftt, graph.importEdges().map((edge) => ({
+                                ...edge,
+                                kind: classifyEdgeByTarget(readSource(edge.from), edge.from, edge.to),
+                            })));
+                            // @implements A-SPEC-574.5 — the same import edges the cycle pass already read, plus
+                            // the parent-time symbol spans the graph already holds. No new scan, no new parse.
+                            const { architectureObservation } = require('../cpg/arch-observe');
+                            const { TreeSitterTsParser } = require('../cpg/language-parser');
+                            const { langForPath } = require('../cpg/cpg-scanner');
+                            // Bounded to the DECLARED files, whose text is read once and used for both numbers.
+                            const archParser = new TreeSitterTsParser();
+                            const archText = new Map();
+                            const readArch = (f) => {
+                                if (!archText.has(f)) {
+                                    try {
+                                        archText.set(f, fs.readFileSync(path.join(a.root, f), 'utf8'));
+                                    }
+                                    catch {
+                                        archText.set(f, null);
+                                    }
+                                }
+                                return archText.get(f) ?? null;
+                            };
+                            const spans = new Map(ftt.map((f) => {
+                                const text = readArch(f);
+                                if (text === null)
+                                    return [f, []];
+                                try {
+                                    return [f, archParser.extractSymbols(text, langForPath(f))
+                                            .filter((sy) => sy.kind !== 'class')
+                                            .map((sy) => ({ startLine: sy.startLine, endLine: sy.endLine }))];
+                                }
+                                catch {
+                                    return [f, []];
+                                }
+                            }));
+                            const arch = architectureObservation(ftt, spans, graph.importEdges(), (f) => { const t = readArch(f); return t === null ? null : t.split('\n').length; });
+                            if (impact || density.length > 0 || cycleFindings.length > 0 || arch.length > 0) {
+                                const graphAsOf = (() => { try {
+                                    return fs.statSync(dbPath).mtime.toISOString();
+                                }
+                                catch {
+                                    return undefined;
+                                } })();
+                                graphPreview = {
+                                    ...(impact ? { impact } : {}),
+                                    ...(density.length > 0 ? { density } : {}),
+                                    ...(cycleFindings.length > 0
+                                        ? { cycles: { findings: cycleFindings, note: CYCLE_ADVISORY_NOTE } } : {}),
+                                    ...(arch.length > 0 ? { architecture: arch } : {}),
+                                    ...(graphAsOf ? { graphAsOf } : {}),
+                                };
+                            }
+                        }
+                        finally {
+                            graph.close();
+                        }
+                    }
+                }
+            }
+            catch {
+                graphPreview = undefined;
+            }
+            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, resolver(all)), ...(graphPreview ? { graphPreview } : {}) };
         },
         /**
          * @implements A-SPEC-538.3
@@ -2447,7 +2578,7 @@ function makeRawHandlers(store, opts) {
                             commitTextBoost[hit.file] = hit.score / top;
                 }
                 catch { /* no history, no boost — the ranking falls back to lexical evidence alone */ }
-                const analysis = (0, maintenance_analyze_1.analyzeMaintenance)({
+                const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
                     semantic,
                     ...common,
                     coverage: { ...common.coverage, historyStatus },
@@ -2456,7 +2587,43 @@ function makeRawHandlers(store, opts) {
                     commitTextBoost,
                     contextBundle,
                     groundTruth: a.groundTruth,
+                    defUse,
                 });
+                // @implements A-SPEC-573.4 — def-use for the TOP CANDIDATES ONLY. Extracting it for the whole
+                // repository costs +88.8% (measured 2026-09-08), well past this slice's budget; the first pass
+                // says which handful of files are worth parsing, and the second pass reads their data flow.
+                // Every step is fail-open: a parse failure, an unsupported language or a missing file leaves
+                // the candidate's symbols exactly as the first pass produced them.
+                const firstPass = analyzeWith();
+                const analysis = (() => {
+                    const targets = firstPass.candidates.slice(0, defuse_bound_1.DEFUSE_TOP_FILES).map((c) => c.file);
+                    if (targets.length === 0)
+                        return firstPass;
+                    const defUse = {};
+                    try {
+                        const { TreeSitterTsParser, hasDataFlowWalk } = require('../cpg/language-parser');
+                        const { langForPath } = require('../cpg/cpg-scanner');
+                        const parser = new TreeSitterTsParser();
+                        for (const file of targets) {
+                            try {
+                                // The LANGUAGE matters: the first wiring omitted it and parsed Python as TypeScript,
+                                // which produced wrong facts and cost the second corpus 0.2376 -> 0.1741 on the
+                                // symbol axis. A language with no walk is skipped rather than guessed at.
+                                const lang = langForPath(file);
+                                if (!hasDataFlowWalk(lang))
+                                    continue;
+                                const facts = parser.extractDataFlow(fs.readFileSync(path.join(root, file), 'utf8'), lang);
+                                if (facts !== undefined)
+                                    defUse[file] = facts;
+                            }
+                            catch { /* one unreadable or unparseable file must not cost the other nine */ }
+                        }
+                    }
+                    catch {
+                        return firstPass;
+                    }
+                    return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
+                })();
                 // @implements A-SPEC-268 — persistence is OPT-IN. The tool is advertised read-only, and a
                 // regression pins that a cold project gains no `.ax/cpg_cache`; writing evidence by default
                 // would break that contract for every caller who only wanted to look.
@@ -3024,7 +3191,7 @@ function makeRawHandlers(store, opts) {
                             summary: `consumed single-use approval for: review-resolve ${envLiftedCriticals.join(', ')}`.slice(0, 200),
                             inputs: [(0, provenance_chain_1.nonceFingerprint)(String(approval.nonce))], rationale: approval.rationale,
                             authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token),
-                        });
+                        }, { isNonceConsumed: (0, ledger_store_2.nonceConsumedIn)(ledgerFile) });
                         if (!won) {
                             throw new HandlerRefusal(`review_record: 단일 사용 승인(nonce)이 이미 소비되었습니다 — 재사용은 거부됩니다. 새 승인을 발급받으십시오`);
                         }
@@ -3154,7 +3321,7 @@ function makeRawHandlers(store, opts) {
                         summary: `consumed single-use approval for: ${coverTarget.kind} ${(0, provenance_chain_1.redactTarget)('command', coverTarget.target)}`.slice(0, 200),
                         inputs: [(0, provenance_chain_1.nonceFingerprint)(String(a.approval.nonce))], rationale: a.approval.rationale,
                         authorization: (0, provenance_chain_1.authorizationRef)(a.approval.actor, a.approval.token),
-                    });
+                    }, { isNonceConsumed: (0, ledger_store_2.nonceConsumedIn)(ledgerFile) });
                 }
                 catch {
                     won = false;

package/dist/holmes/mcp/history-admission.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Narrow history-derived candidates to files that could be source at all.
+ *
+ * The predicate is the SCANNER's, not the replay corpus's truth predicate — scoring against a
+ * filter copied from the metric would be gaming it. Deliberately NOT membership in the scanned
+ * set: a file a commit CREATES does not exist in the parent-time scan, and admitting exactly such
+ * files is A-SPEC-388's boundary contract. Every offender measured above is excluded by the
+ * extension test alone (.jsonl / .json / .md), so the stronger predicate would have cost that
+ * contract and bought nothing.
+ *
+ * Order is preserved because the downstream RRF lists are position-indexed.
+ */
+export declare function admitHistoryFiles(historyFiles: readonly string[]): string[];
+/** The lexical path's predicate (localize.ts), restated so both channels demote the same trees. */
+export declare const isVendorPath: (p: string) => boolean;

package/dist/holmes/mcp/history-admission.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isVendorPath = void 0;
+exports.admitHistoryFiles = admitHistoryFiles;
+// @implements A-SPEC-573.1
+// The commit-prose channel (A-SPEC-388) lets files the lexical layer never scored ENTER the
+// candidate pool — that is where its measured gain comes from (Top-10 recall 0.393 -> 0.601). But
+// its keys come from git history, so it also admits files that CANNOT be the answer: this
+// repository's ledger JSONL, the last-green baseline, CHANGELOG.md. Measured 2026-09-08 over 12
+// real commit-subject requests: 76 of 120 emitted candidate slots (63.3%) went to such files, and
+// one took the emission head. The channel is not the problem; its POPULATION is.
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+/**
+ * Narrow history-derived candidates to files that could be source at all.
+ *
+ * The predicate is the SCANNER's, not the replay corpus's truth predicate — scoring against a
+ * filter copied from the metric would be gaming it. Deliberately NOT membership in the scanned
+ * set: a file a commit CREATES does not exist in the parent-time scan, and admitting exactly such
+ * files is A-SPEC-388's boundary contract. Every offender measured above is excluded by the
+ * extension test alone (.jsonl / .json / .md), so the stronger predicate would have cost that
+ * contract and bought nothing.
+ *
+ * Order is preserved because the downstream RRF lists are position-indexed.
+ */
+function admitHistoryFiles(historyFiles) {
+    const admitted = historyFiles.filter((file) => !file.endsWith('.d.ts') && cpg_scanner_1.SCANNABLE_EXTENSIONS.some((ext) => file.endsWith(ext)));
+    // @implements A-SPEC-573.2 — the lexical path halves a vendored file's score AND orders vendored
+    // last (localize.ts). Entering at score 0, this channel bypassed both: measured 2026-09-08, the
+    // only two non-source candidates the extension test let through were vendored files and BOTH held
+    // the emission head. Demote, never drop — vendored code is the answer in some projects, which is
+    // why the lexical path orders rather than filters. Stable within each group: the downstream RRF
+    // lists are position-indexed.
+    return [...admitted.filter((f) => !(0, exports.isVendorPath)(f)), ...admitted.filter(exports.isVendorPath)];
+}
+/** The lexical path's predicate (localize.ts), restated so both channels demote the same trees. */
+const isVendorPath = (p) => /(^|\/)(reference|vendor|vendors|third_party|third-party|external)\//i.test(p);
+exports.isVendorPath = isVendorPath;

package/dist/holmes/mcp/maintenance-analyze.d.ts

@@ -3,6 +3,7 @@ import type { Spec } from '../spec/spec-parser';
 import type { RtmGraph } from '../rtm/rtm-graph';
 import type { ContextBundle } from '../context/bundler';
 import { type TestScope } from '../rtm/test-scope';
+import { type DecisionContextEntry } from '../rtm/decision-context';
 import type { ResolutionReport } from '../rtm/rtm-builder';
 import { type TestEvidence } from '../review/test-evidence';
 import { type LanguageGap } from '../cpg/language-capability';
@@ -116,6 +117,14 @@ export interface MaintenanceAnalysisInput {
      * that is the whole result.
      */
     commitTextBoost?: Record<string, number>;
+    /**
+     * @implements A-SPEC-573.4
+     * Def-use facts for a BOUNDED set of files — the caller extracts them, because this core does no
+     * I/O. Extracting them for the whole repository costs +88.8% (measured 2026-09-08, 2572ms ->
+     * 4857ms), which is why the callers pass the top candidates only. Absent means "not extracted",
+     * and the symbols then read exactly as they did before this existed.
+     */
+    defUse?: Record<string, import('../cpg/language-parser').DataFlowFacts>;
     contextBundle?: ContextBundle | null;
     /**
      * @implements A-SPEC-290
@@ -212,6 +221,8 @@ export interface MaintenanceAnalysis {
         score: number;
         symbols: string[];
         evidence: string[];
+        /** @implements A-SPEC-572.3 — decisions constraining this candidate; information only. */
+        decisionContext?: DecisionContextEntry[];
     }>;
     /**
      * @implements A-SPEC-494 — the semantic ALTERNATES: top-3 cached-vector cosines among files

package/dist/holmes/mcp/maintenance-analyze.js

@@ -26,9 +26,16 @@ const scope_1 = require("../review/scope");
 // the measured numbers transfer to the shipped surface.
 const assoc_arm_1 = require("../assoc/assoc-arm");
 const acceptance_quality_1 = require("../spec/acceptance-quality");
+// @implements A-SPEC-572.3 — the decision lookup lives in its own pure module: this file
+// already carries 35 anchors (p90 is 7), and the design-time density advisory said so BEFORE
+// this slice fixed its Files-to-Touch. Adding logic here would have made the file denser; the
+// call site is one line, the logic is next door.
+const decision_context_1 = require("../rtm/decision-context");
 const taint_1 = require("../rtm/taint");
 const test_evidence_1 = require("../review/test-evidence");
 const language_capability_1 = require("../cpg/language-capability");
+const history_admission_1 = require("./history-admission");
+const defuse_symbols_1 = require("../rtm/defuse-symbols");
 // @implements A-SPEC-409 — the SHAPE gained a field (`rerankPool`), so a consumer can detect it.
 // @implements A-SPEC-405 A-SPEC-407 — the EXTRACTOR changed too: the same request now returns a
 // differently ordered candidate list (keep-head rank fusion, then the graph-hop list), so two
@@ -176,10 +183,12 @@ function analyzeMaintenance(input) {
     // Files the commit prose names but the lexical layer never scored have to be able to ENTER, or the
     // fusion can only reorder what lexical already found — and reaching what it missed is where the
     // measured gain came from (Top-10 recall 0.393 -> 0.601 on the second corpus).
+    // @implements A-SPEC-573.1 — but only files that could be source at all. The keys come from git
+    // history, so without this the pool also admits ledger JSONL and build artifacts that cannot be
+    // the answer (measured: 63.3% of emitted slots). The lexical hits are untouched, and a file the
+    // scan has never seen still enters — that is the boundary contract directly above.
     const seeded = hasBoost
-        ? [...localization.hits, ...Object.keys(boost)
-                .filter((file) => !localization.hits.some((h) => h.file === file))
-                .map((file) => ({ file, score: 0, matchedSymbols: [], viaSpecs: [], why: ['reached through commit history'] }))]
+        ? [...localization.hits, ...(0, history_admission_1.admitHistoryFiles)(Object.keys(boost).filter((file) => !localization.hits.some((h) => h.file === file))).map((file) => ({ file, score: 0, matchedSymbols: [], viaSpecs: [], why: ['reached through commit history'] }))]
         : localization.hits;
     const reranked = !hasPrior && !hasBoost
         ? localization.hits
@@ -197,7 +206,13 @@ function analyzeMaintenance(input) {
                 // than prose spread evenly. Kept, with the cost named rather than defended.
                 + (hasBoost ? COMMIT_TEXT_WEIGHT * (boost[hit.file] ?? 0) * Math.max(1, hit.score) : 0),
         }))
-            .sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+            // @implements A-SPEC-573.2 — vendored last, exactly as the lexical path orders it
+            // (localize.ts). A history-seeded file scores 0 lexically, so the boost term alone can carry
+            // it to 2.0 and hand it the head — measured, a vendored file took the head in 2 of 12 real
+            // requests. This is the ordering rule that path already applies; the channel was bypassing
+            // it. Demotion, not exclusion: vendored code is the answer in some projects.
+            .sort((a, b) => Number((0, history_admission_1.isVendorPath)(a.file)) - Number((0, history_admission_1.isVendorPath)(b.file))
+            || b.score - a.score || a.file.localeCompare(b.file));
     // @implements A-SPEC-405
     // S-405 decomposed the recall loss measured in S-404: on the eight blind cases 18 of 18 truth
     // files were already in this pool and 7 sat at ranks 12-93, so widening retrieval could not have
@@ -289,7 +304,10 @@ function analyzeMaintenance(input) {
         ;
         const lists = [
             desc((f) => byFile.get(f).score),
-            hasBoost ? desc((f) => boost[f] ?? 0) : [],
+            // @implements A-SPEC-573.2 — vendored last inside this list. Ordering `seeded` was not enough:
+            // measured, the head is decided HERE, and a vendored file with a high boost took it twice in
+            // twelve requests. The boost VALUES are untouched, so the lexical scoring above is unchanged.
+            hasBoost ? desc((f) => boost[f] ?? 0).sort((a, b) => Number((0, history_admission_1.isVendorPath)(a)) - Number((0, history_admission_1.isVendorPath)(b))) : [],
             hasPrior ? desc((f) => (prior[f] ?? 1) - 1) : [],
             cited.length > 0 ? [] : hops,
         ];
@@ -340,10 +358,23 @@ function analyzeMaintenance(input) {
     // @implements A-SPEC-486 — the S-502/503 calibration point for gemini cosines. Display only:
     // nothing in this module compares against it to drop or reorder anything.
     const SEM_VERIFY_TAU = 0.65;
+    // @implements A-SPEC-573.4 — def-use rides BEHIND the lexical match, never in front of it: the
+    // symbols the request actually named keep the front, and the data-flow neighbours are appended.
+    const defUseTerms = input.defUse === undefined ? [] : (0, localize_1.significantTerms)(input.request);
+    const symbolsByFile = new Map(scanned.map((f) => [f.sourcePath, f.symbols.map((sy) => sy.qualifiedName)]));
+    const symbolsOf = (file, matched) => {
+        const facts = input.defUse?.[file];
+        if (facts === undefined)
+            return matched;
+        const inFile = symbolsByFile.get(file) ?? [];
+        if (inFile.length === 0)
+            return matched;
+        return (0, defuse_symbols_1.enrichCandidateSymbols)(matched, (0, defuse_symbols_1.rankSymbolsByDefUse)(facts, defUseTerms, inFile));
+    };
     const shape = (hit) => ({
         file: hit.file,
         score: hit.score,
-        symbols: sortedUnique(hit.matchedSymbols),
+        symbols: symbolsOf(hit.file, sortedUnique(hit.matchedSymbols)),
         evidence: hit.why,
     });
     // @implements A-SPEC-428
@@ -371,12 +402,32 @@ function analyzeMaintenance(input) {
     const rescuedFiles = new Set(rescued.map((h) => h.file));
     const rerankPool = [...rescued, ...exposedTail.filter((h) => !rescuedFiles.has(h.file))]
         .slice(0, RERANK_POOL_N).map(shape);
+    const lexicalSymbolsOf = new Map(ordered.slice(0, LOCALIZATION_TOP_N).map((hit) => [hit.file, sortedUnique(hit.matchedSymbols)]));
     const candidates = ordered.slice(0, LOCALIZATION_TOP_N).map((hit) => ({
         file: hit.file,
         score: hit.score,
-        symbols: sortedUnique(hit.matchedSymbols),
+        // @implements A-SPEC-573.4 — the emitted list, which is what a caller reads and what the
+        // benchmark scores on the symbol axis. `shape` above serves the rerank pool only; wiring the
+        // enrichment there and not here would have enriched a surface nobody grades (caught by the
+        // symbol axis reporting NO movement — the instrument earned its keep on its first use).
+        symbols: symbolsOf(hit.file, sortedUnique(hit.matchedSymbols)),
         evidence: [...hit.why],
     }));
+    // @implements A-SPEC-572.3
+    // "What broke" then "why is it this way" — the order a person diagnoses in. The decisions are
+    // already in the graph (REQ-571 put store ADRs there; A-SPEC-293 builds `constrained_by` from
+    // citations), so this is a lookup, not a new mechanism. Information only: it rides beside a
+    // candidate and never enters the score or the ordering above.
+    {
+        const anchorsOf = new Map(scanned.map((f) => [f.sourcePath, f.implementsSpecs ?? []]));
+        const ctx = (0, decision_context_1.decisionContextFor)(candidates.map((c) => c.file), (file) => anchorsOf.get(file) ?? [], input.graph);
+        for (const candidate of candidates) {
+            const entries = ctx.get(candidate.file);
+            if (entries && entries.length > 0) {
+                candidate.decisionContext = entries;
+            }
+        }
+    }
     // @implements A-SPEC-478 — the uncited semantic head rerank, exactly the arm S-495 measured:
     // same math (cosine over cached doc vectors, pool FIXED), same gate (the request cited no
     // spec). The gate is load-bearing both ways — uncited corpora gained +26%/+93% at the head,
@@ -440,7 +491,12 @@ function analyzeMaintenance(input) {
             .flatMap((f) => f.symbols.map((sym) => sym.qualifiedName));
     // A file you edited is not unaffected by your edit, so these are direct impact and not merely a
     // traversal starting point.
-    const direct = sortedUnique([...candidates.flatMap((candidate) => candidate.symbols), ...changedSymbols]);
+    // @implements A-SPEC-573.4 — the impact axis seeds from what the LEXICAL layer matched, not from
+    // the def-use symbols appended for emission. Measured: seeding the enriched list moved the union
+    // axis on both corpora (precision 0.1667->0.2075 / 0.1476->0.1689, recall 0.8755->0.8698 /
+    // 0.8302->0.7996) — a different axis than this slice targets, and axis transfer is exactly what
+    // this repository's record forbids. The emitted symbols stay enriched; the seeds do not.
+    const direct = sortedUnique([...lexicalSymbolsOf.values()].flat().concat(changedSymbols));
     const transitiveIds = new Set();
     const maxCallDepth = 3;
     const hubInDegree = 12;

package/dist/holmes/mcp/spec-id-guard.d.ts

@@ -15,12 +15,4 @@ export type IdVerdict = {
     reason: string;
     nextAvailable: number;
 };
-/**
- * 새 id 의 base 가 코퍼스 max base 를 한 칸 넘게 뛰면 거부한다.
- *
- * - 빈 코퍼스, 또는 base 를 못 뽑는 id → 통과(비교 대상이 없거나, 형태 검증은 별도 소관이라 한 결함에
- *   두 이름을 주지 않는다).
- * - base ≤ maxBase(갭 메우기·체인 완성) 또는 base == maxBase+1(새 체인) → 통과.
- * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
- */
 export declare function sequentialIdVerdict(newId: string, existingIds: string[]): IdVerdict;

package/dist/holmes/mcp/spec-id-guard.js

@@ -30,11 +30,20 @@ function specIdBase(id) {
  * - base ≤ maxBase(갭 메우기·체인 완성) 또는 base == maxBase+1(새 체인) → 통과.
  * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
  */
+/** The id's number SPACE. @implements A-SPEC-571.1 — ADR keeps its own sequence so a decision
+ * (jarvis's ADR-0001) neither blocks nor is blocked by the functional chain's max. Everything
+ * else shares one space, exactly as before. */
+function idSpaceOf(id) {
+    return /^ADR-/.test(id.trim()) ? 'ADR' : 'functional';
+}
 function sequentialIdVerdict(newId, existingIds) {
     const base = specIdBase(newId);
     if (base === null)
         return { ok: true };
-    const bases = (existingIds ?? []).map(specIdBase).filter((n) => n !== null);
+    // @implements A-SPEC-571.1 — compare only within the same number space.
+    const space = idSpaceOf(newId);
+    const bases = (existingIds ?? []).filter((id) => idSpaceOf(id) === space)
+        .map(specIdBase).filter((n) => n !== null);
     if (bases.length === 0)
         return { ok: true };
     const maxBase = Math.max(...bases);

package/dist/holmes/review/evaluation-metrics.d.ts

@@ -20,6 +20,10 @@ export interface ReplayOutcome {
     truthFiles: string[];
     selectedTests: string[];
     truthTests: string[];
+    /** Symbols the change actually touched (parent-time ranges ∩ changed lines). */
+    truthSymbols?: string[];
+    /** Predicted symbols, best first — the qualified names the emitted candidates carried. */
+    rankedSymbols?: string[];
 }
 export interface CutMetrics {
     /** Share of cases where at least one truth file appears in the first K. */
@@ -33,6 +37,8 @@ export interface EvaluationMetrics {
     scorableCases: number;
     topK: Record<number, CutMetrics>;
     testRecall: number | null;
+    symbolTopK: Record<number, CutMetrics>;
+    symbolCases: number;
 }
 export declare function evaluationMetrics(outcomes: readonly ReplayOutcome[]): EvaluationMetrics;
 /**

package/dist/holmes/review/evaluation-metrics.js

@@ -42,7 +42,24 @@ function evaluationMetrics(outcomes) {
     }
     const testScorable = outcomes.filter((o) => o.truthTests.length > 0);
     const testRecall = mean(testScorable.map((o) => o.truthTests.filter((t) => o.selectedTests.includes(t)).length / o.truthTests.length));
-    return { cases: outcomes.length, scorableCases: scorable.length, topK, testRecall };
+    // @implements A-SPEC-573.3
+    const symbolScorable = outcomes.filter((o) => (o.truthSymbols?.length ?? 0) > 0);
+    const symbolTopK = {};
+    for (const k of exports.TOP_K) {
+        const hits = [];
+        const recalls = [];
+        const precisions = [];
+        for (const o of symbolScorable) {
+            const cut = (o.rankedSymbols ?? []).slice(0, k);
+            const found = cut.filter((s2) => o.truthSymbols.includes(s2)).length;
+            hits.push(found > 0 ? 1 : 0);
+            recalls.push(found / o.truthSymbols.length);
+            precisions.push(cut.length === 0 ? 0 : found / cut.length);
+        }
+        symbolTopK[k] = { hitRate: mean(hits), recall: mean(recalls), precision: mean(precisions) };
+    }
+    return { cases: outcomes.length, scorableCases: scorable.length, topK, testRecall,
+        symbolTopK, symbolCases: symbolScorable.length };
 }
 /**
  * Impact had no benchmark until this existed, so an impact regression could not fail anything.

package/dist/holmes/review/paired-power.d.ts

@@ -0,0 +1,14 @@
+/** F1 over the SET of files, which is the edit set a caller actually acts on. */
+export declare function editSetF1(predicted: readonly string[], truth: readonly string[]): number;
+export interface PairedPower {
+    n: number;
+    meanDiff: number | null;
+    /** Sample standard deviation of the paired differences (n-1). Null below two observations. */
+    sdDiff: number | null;
+    sem: number | null;
+    /** Smallest difference detectable at 80% power, two-sided alpha 0.05. */
+    mde80: number | null;
+    /** True when the degrees of freedom fell outside the table and the normal approximation was used. */
+    approx: boolean;
+}
+export declare function pairedPower(diffs: readonly number[]): PairedPower;