@holmes-lab/holmes-kit 0.18.0 → 0.19.2

package/dist/holmes/review/failed-test-names.js

@@ -0,0 +1,43 @@
+"use strict";
+// @implements A-SPEC-582.1
+/**
+ * The names behind a red release gate.
+ *
+ * Measured 2026-09-10: `npm publish` refused with "스위트가 붉습니다" and nothing else, and finding
+ * out which test had failed cost two more full-suite runs. `test_run` learned to name its failures
+ * in REQ-577; the release gate had not. A gate that says "red" without saying what is a gate that
+ * makes the next person guess.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAILED_NAME_CAP = void 0;
+exports.failedTestNames = failedTestNames;
+/** How many names a refusal lists before it counts the rest. */
+exports.FAILED_NAME_CAP = 10;
+/** Jest's summary marks each failure with `● <suite> › <test>`. */
+const SUMMARY_LINE = /^\s*●\s+(.+?)\s*$/;
+/**
+ * Pull the failing test names out of a jest run's output.
+ *
+ * PURE, and forgiving: output it cannot read yields an empty list so the caller keeps its existing
+ * refusal rather than replacing a working message with an empty one. Jest prints the summary block
+ * twice on some configurations, so names are de-duplicated — the same failure listed twice is one
+ * failure.
+ */
+function failedTestNames(output) {
+    const seen = [];
+    for (const line of String(output ?? '').split('\n')) {
+        const m = SUMMARY_LINE.exec(line);
+        if (m === null)
+            continue;
+        const name = m[1];
+        // A `●` line that is not a test name (jest uses the bullet for Console blocks too).
+        if (name === '' || name === 'Console' || !name.includes('›'))
+            continue;
+        if (!seen.includes(name))
+            seen.push(name);
+    }
+    if (seen.length <= exports.FAILED_NAME_CAP)
+        return seen;
+    const rest = seen.length - exports.FAILED_NAME_CAP;
+    return [...seen.slice(0, exports.FAILED_NAME_CAP), `… and ${rest} more`];
+}

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.d.ts

@@ -1,6 +1,23 @@
 import { evaluationMetrics, impactMetrics, ceilingMetrics } from './evaluation-metrics';
 import { type ReplayCorpus } from './replay-corpus';
 import { type PprArmConfig } from '../assoc/assoc-arm';
+/** One case, scored by both arms. Measurement only — never read by a pin. */
+export interface PairedRow {
+    commit: string;
+    uncited: boolean;
+    productRecall10: number;
+    baselineRecall10: number;
+    truth: number;
+}
+/**
+ * @implements A-SPEC-578.7
+ * The paired differences on the UNCITED axis, ready for `pairedPower`.
+ *
+ * Filtering here rather than while measuring is deliberate: observation records every case, and the
+ * axis is chosen at analysis time. A harness that only recorded what it currently cares about could
+ * never answer a question asked later.
+ */
+export declare function uncitedDiffs(rows: readonly PairedRow[]): number[];
 export interface ReplayResult {
     corpus: string;
     cases: number;
@@ -231,6 +248,12 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
         /** @implements A-SPEC-567.2 — present only when judgementBundle was asked. */
         judgementBundle?: import('./judgement-bundle').JudgementBundle;
     }) => void;
+    /**
+     * @implements A-SPEC-578.7 — the power arm: one row per case, both arms scored, so the caller
+     * can compute an MDE with `pairedPower`. Same idiom as `caseDump` — a callback, never a change
+     * to `ReplayResult`, so a pin cannot move because a measurement was asked for.
+     */
+    pairedDump?: (row: PairedRow) => void;
     /** @implements A-SPEC-487 — 2-pass semantic injection for the dump only, never the pins. */
     productSemantic?: {
         embedBatch: (texts: string[], kind: 'query' | 'doc') => Promise<number[][]>;

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

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.uncitedDiffs = uncitedDiffs;
 exports.runReplay = runReplay;
 exports.semanticCaseRanking = semanticCaseRanking;
 // @implements A-SPEC-346
@@ -41,11 +42,15 @@ exports.semanticCaseRanking = semanticCaseRanking;
 // @implements A-SPEC-349
 // @implements A-SPEC-378
 // @implements A-SPEC-402
+const baseline_arm_1 = require("./baseline-arm");
 const fs = __importStar(require("node:fs"));
 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 +60,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").
@@ -75,6 +81,17 @@ const dense_retrieval_1 = require("./dense-retrieval");
 const explore_1 = require("../assoc/explore");
 const temporal_prior_1 = require("./temporal-prior");
 const commit_text_1 = require("./commit-text");
+/**
+ * @implements A-SPEC-578.7
+ * The paired differences on the UNCITED axis, ready for `pairedPower`.
+ *
+ * Filtering here rather than while measuring is deliberate: observation records every case, and the
+ * axis is chosen at analysis time. A harness that only recorded what it currently cares about could
+ * never answer a question asked later.
+ */
+function uncitedDiffs(rows) {
+    return rows.filter((r) => r.uncited).map((r) => r.productRecall10 - r.baselineRecall10);
+}
 /**
  * Run the point-in-time replay against ANY corpus.
  *
@@ -212,25 +229,94 @@ 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-578.7 — the power arm. Both recalls come from what already exists:
+                // the product's from `ranked` (never recomputed — recomputing is how a benchmark ends up
+                // scoring a pipeline the product does not ship, measured once already in A-SPEC-573.3),
+                // the baseline's from `rankBaseline`, the no-graph floor built in A-SPEC-356 and never
+                // called until now. The `uncited` predicate is the PRODUCT'S — `citationsIn` — so the axis
+                // is defined the same way here and there.
+                if (opts.pairedDump !== undefined && c.files.length > 0) {
+                    const truth = new Set(c.files);
+                    const recallOf = (files) => files.slice(0, 10).filter((f) => truth.has(f)).length / truth.size;
+                    opts.pairedDump({
+                        commit: c.commit,
+                        uncited: (0, localize_1.citationsIn)(c.subject, new Set(specs.map((sp) => sp.id))).cited.length === 0,
+                        productRecall10: recallOf(ranked),
+                        baselineRecall10: recallOf((0, baseline_arm_1.rankBaseline)(c.subject, scanned, 10).map((h) => h.file)),
+                        truth: truth.size,
+                    });
+                }
                 // @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/review/test-runner.d.ts

@@ -190,6 +190,18 @@ export declare function runGo(files: string[], mode: TestRunPlan['mode'], cwd: s
  * gate that ran part of its scope has verified less than it reports.
  */
 export declare function runTestScope(scope: TestScope, cwd: string): TestRunResult;
+/**
+ * The last few lines of a runner's output, bounded by SIZE as well as by line count.
+ *
+ * A line budget is only a size budget while the lines are short, and jest `--json` breaks that
+ * assumption completely: it emits one line. Measured 2026-09-02 — a GREEN `test_run` returned
+ * 1,432,092 characters, of which this field was 1,421,327 (99.2%) across "6 lines" whose longest
+ * was 1,420,959. The usefulness was inverted: a red run gave six clean lines of stderr summary,
+ * and a green run gave the whole document.
+ *
+ * The END is what survives a cut. A runner's conclusion is always at the bottom.
+ */
+export declare const TAIL_MAX_CHARS = 4000;
 export declare function tailOf(s: string, opts?: number | {
     lines?: number;
     maxChars?: number;
@@ -204,4 +216,19 @@ export declare function tailOf(s: string, opts?: number | {
  * Returns null on anything it cannot read, and the caller falls back to the truncated original:
  * a failed summary must not turn partial information into none.
  */
+/**
+ * What failed, by name — the red counterpart to `summarizeJestJson`.
+ *
+ * Measured 2026-09-09: a red `test_run` reported "1 failed" three times running and never said
+ * which test. The failing file had to be recovered from the outcome ledger's A-SPEC list, because
+ * the red path's tail is the tail of a JSON DOCUMENT — bytes, not a name. Counts tell you a run
+ * went red; only a name tells you what to look at.
+ *
+ * The payload is located by the SAME rule `summarizeJestJson` uses (the first `{`), because a suite
+ * that logs anything prints it before the JSON — this repository's does — and two rules for one
+ * string is how the two quietly disagree.
+ *
+ * Only the FIRST line of a failure message: one failure, one look. The rest is in the file.
+ */
+export declare function failedTestSummary(stdout: string, limit?: number): string | null;
 export declare function summarizeJestJson(stdout: string): string | null;

package/dist/holmes/review/test-runner.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAIL_MAX_CHARS = void 0;
 exports.planTestRun = planTestRun;
 exports.ecosystemOf = ecosystemOf;
 exports.parseGoTestJson = parseGoTestJson;
@@ -49,6 +50,7 @@ exports.runDotnet = runDotnet;
 exports.runGo = runGo;
 exports.runTestScope = runTestScope;
 exports.tailOf = tailOf;
+exports.failedTestSummary = failedTestSummary;
 exports.summarizeJestJson = summarizeJestJson;
 // @implements A-SPEC-102.1
 const node_child_process_1 = require("node:child_process");
@@ -304,7 +306,11 @@ function runJest(files, mode, cwd) {
         const err = e;
         // A failing suite still emits --json on stdout, so execution evidence — and the red/green outcome
         // classification (A-SPEC-534.1) — survives a red run.
-        return { passed: false, tail: tailOf(`${err.stdout ?? ''}\n${err.stderr ?? err.message ?? ''}`), executed: parseExecutedCounts(err.stdout ?? '', cwd), outcomes: classifyJestOutcomes(err.stdout ?? '', cwd) };
+        // @implements A-SPEC-577.1 — the names first, then jest's own summary from stderr. Without the
+        // first half this tail was the tail of a JSON document: it said how many failed and never which.
+        const named = failedTestSummary(err.stdout ?? '');
+        const tail = tailOf(`${named === null ? (err.stdout ?? '') : named}\n${err.stderr ?? err.message ?? ''}`, { lines: named === null ? 6 : 40 });
+        return { passed: false, tail, executed: parseExecutedCounts(err.stdout ?? '', cwd), outcomes: classifyJestOutcomes(err.stdout ?? '', cwd) };
     }
 }
 /**
@@ -703,11 +709,11 @@ function runTestScope(scope, cwd) {
  *
  * The END is what survives a cut. A runner's conclusion is always at the bottom.
  */
-const TAIL_MAX_CHARS = 4000;
+exports.TAIL_MAX_CHARS = 4000;
 function tailOf(s, opts = {}) {
     // The numeric spelling is the one the go adapter uses (`tailOf(err.stderr, 2)`); keeping it means
     // this change cannot silently alter a caller that only ever wanted fewer lines.
-    const { lines = 6, maxChars = TAIL_MAX_CHARS } = typeof opts === 'number' ? { lines: opts } : opts;
+    const { lines = 6, maxChars = exports.TAIL_MAX_CHARS } = typeof opts === 'number' ? { lines: opts } : opts;
     const picked = s.trim().split('\n').slice(-lines).join('\n');
     if (picked.length <= maxChars)
         return picked;
@@ -725,6 +731,56 @@ function tailOf(s, opts = {}) {
  * Returns null on anything it cannot read, and the caller falls back to the truncated original:
  * a failed summary must not turn partial information into none.
  */
+// @implements A-SPEC-577.1
+/**
+ * What failed, by name — the red counterpart to `summarizeJestJson`.
+ *
+ * Measured 2026-09-09: a red `test_run` reported "1 failed" three times running and never said
+ * which test. The failing file had to be recovered from the outcome ledger's A-SPEC list, because
+ * the red path's tail is the tail of a JSON DOCUMENT — bytes, not a name. Counts tell you a run
+ * went red; only a name tells you what to look at.
+ *
+ * The payload is located by the SAME rule `summarizeJestJson` uses (the first `{`), because a suite
+ * that logs anything prints it before the JSON — this repository's does — and two rules for one
+ * string is how the two quietly disagree.
+ *
+ * Only the FIRST line of a failure message: one failure, one look. The rest is in the file.
+ */
+function failedTestSummary(stdout, limit = 5) {
+    const start = stdout.indexOf('{');
+    if (start < 0)
+        return null;
+    let j;
+    try {
+        j = JSON.parse(stdout.slice(start));
+    }
+    catch {
+        return null;
+    }
+    if (j === null || typeof j !== 'object' || !Array.isArray(j.testResults))
+        return null;
+    const failures = [];
+    for (const file of j.testResults) {
+        const base = typeof file?.name === 'string' ? file.name.split(/[\\/]/).pop() ?? file.name : '(unknown file)';
+        for (const a of Array.isArray(file?.assertionResults) ? file.assertionResults : []) {
+            if (a?.status !== 'failed')
+                continue;
+            const msg = Array.isArray(a.failureMessages) ? a.failureMessages.find((m) => typeof m === 'string' && m.trim() !== '') : undefined;
+            failures.push({
+                where: `${base} \u203a ${String(a.title ?? '(untitled)')}`,
+                first: typeof msg === 'string' ? (msg.trim().split('\n')[0] ?? '') : '',
+            });
+        }
+    }
+    if (failures.length === 0)
+        return null;
+    const shown = failures.slice(0, Math.max(0, limit));
+    const lines = shown.flatMap((f) => (f.first === '' ? [f.where] : [f.where, `    ${f.first}`]));
+    const rest = failures.length - shown.length;
+    if (rest > 0)
+        lines.push(`    \u2026 \uc678 ${rest}\uac74`);
+    return lines.join('\n');
+}
 function summarizeJestJson(stdout) {
     // The payload is not the whole of stdout. A suite that logs anything prints it BEFORE the JSON,
     // and this repository's own suite does: measured, the first live run after this function landed

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;
+}