@holmes-lab/holmes-kit 0.18.0 → 0.19.0

package/dist/holmes/mcp/handlers.js

@@ -45,6 +45,8 @@ exports.collectDecisions = collectDecisions;
 // @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");
@@ -205,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");
@@ -1375,7 +1379,63 @@ function makeRawHandlers(store, opts) {
                                 return null;
                             } });
                             const density = anchorDensityFindings(ftt, graph.implementsAnchorCounts());
-                            if (impact || density.length > 0) {
+                            // @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();
                                 }
@@ -1385,6 +1445,9 @@ function makeRawHandlers(store, opts) {
                                 graphPreview = {
                                     ...(impact ? { impact } : {}),
                                     ...(density.length > 0 ? { density } : {}),
+                                    ...(cycleFindings.length > 0
+                                        ? { cycles: { findings: cycleFindings, note: CYCLE_ADVISORY_NOTE } } : {}),
+                                    ...(arch.length > 0 ? { architecture: arch } : {}),
                                     ...(graphAsOf ? { graphAsOf } : {}),
                                 };
                             }
@@ -2515,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 },
@@ -2524,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.
@@ -3092,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)이 이미 소비되었습니다 — 재사용은 거부됩니다. 새 승인을 발급받으십시오`);
                         }
@@ -3222,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

@@ -117,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

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

@@ -34,6 +34,8 @@ 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
@@ -181,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
@@ -202,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
@@ -294,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,
         ];
@@ -345,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
@@ -376,10 +402,15 @@ 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
@@ -460,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/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;

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.