@holmes-lab/holmes-kit 0.2.1 → 0.3.0

package/dist/holmes/review/semantic-retrieval.d.ts

@@ -0,0 +1,55 @@
+import type { Spec } from '../spec/spec-parser';
+/**
+ * One token, reduced to the form two spellings of the same word share.
+ *
+ * Suffix stripping is conservative and applied once — an aggressive stemmer merges words that are
+ * genuinely different (`parse`/`parsing` should merge, `general`/`generate` must not), and a wrong
+ * merge is a false positive nobody can see in the output.
+ */
+export declare function normaliseTerm(term: string): string;
+export declare const normalisedTerms: (text: string) => string[];
+export interface RankedSpec {
+    id: string;
+    score: number;
+}
+/**
+ * BM25 over A-SPEC documents.
+ *
+ * `k1` bounds how much repetition can add and `b` controls the length correction — the standard
+ * 1.2/0.75, not tuned here, because tuning two constants on sixty cases fits noise and this arm has
+ * to answer a yes-or-no question about the idea rather than squeeze the last point out of it.
+ *
+ * A-SPEC only, as everywhere else: files anchor A-SPECs, so no other kind can pull a file through.
+ */
+export declare function retrieveSpecs(issueText: string, specs: readonly Spec[], topK: number): RankedSpec[];
+/**
+ * @implements A-SPEC-380
+ * The query, expanded with the vocabulary of the specs that the first search's best files anchor.
+ *
+ * Six mechanisms have been measured against uncited requests and none of them used the graph
+ * ACTIVELY: every one added a graph-derived score to a single retrieval pass. This is the other
+ * structure — retrieve, traverse, expand, retrieve again — which information retrieval calls
+ * pseudo-relevance feedback, and it is the only principled way a graph can close the gap between the
+ * words a reporter writes and the names the code uses. A bug report says "uploads are being rejected";
+ * the spec those files anchor says "quarantine of malformed payloads"; the code is named
+ * `sanitizeIngest`. No amount of matching the request against the code bridges that. Going through
+ * the spec does.
+ *
+ * Expansion terms are weighted BELOW the original query, and the reason is the failure mode: if the
+ * first pass ranked the wrong file, its spec's vocabulary is the wrong vocabulary, and an
+ * over-weighted expansion turns one mistake into a whole ranking of them.
+ */
+export interface ExpandedQuery {
+    /** Original request terms, normalised. */
+    base: string[];
+    /** Terms contributed by the specs reached through the top files, with their weight. */
+    expansion: Map<string, number>;
+}
+export declare function expandThroughGraph(issueText: string, topFiles: readonly {
+    file: string;
+    anchors: readonly string[];
+}[], specs: readonly Spec[], opts: {
+    seedFiles: number;
+    termsPerSpec: number;
+    weight: number;
+}): ExpandedQuery;

package/dist/holmes/review/semantic-retrieval.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalisedTerms = void 0;
+exports.normaliseTerm = normaliseTerm;
+exports.retrieveSpecs = retrieveSpecs;
+exports.expandThroughGraph = expandThroughGraph;
+const localize_1 = require("../rtm/localize");
+/**
+ * Ranked retrieval of specs for a request, instead of counting exact token matches.
+ *
+ * Five mechanisms have been measured against uncited requests and all five were negative — and all
+ * five were about TRAVERSAL: which neighbours to follow, how much bonus to pay, when to stop. The
+ * step none of them touched is the one that decides whether the request and a spec are about the
+ * same thing at all, and that step is still exact string equality over a bag of words.
+ *
+ * So `quarantine` and `quarantining` are different subjects, `config` and `cfg` are different
+ * subjects, and a two-line spec is compared to a request on the same footing as a forty-line one.
+ * That is string matching wearing the word "semantic".
+ *
+ * What replaces it here is the strongest thing available with no model and no network: BM25 with
+ * morphological normalisation. It is not embeddings, and calling it semantic search would overstate
+ * it — but it does handle inflection, the abbreviations this corpus actually uses, and document
+ * length, none of which the previous rule could.
+ */
+/**
+ * Abbreviations that genuinely occur in these corpora, checked rather than imagined.
+ *
+ * Deliberately short: every entry is a claim that two different words mean the same thing, and a
+ * wrong one silently merges unrelated subjects. Anything not observed here stays out.
+ */
+const ABBREVIATIONS = new Map(Object.entries({
+    cfg: 'config', config: 'config', configuration: 'config',
+    auth: 'auth', authentication: 'auth', authorization: 'auth',
+    msg: 'message', message: 'message',
+    req: 'request', request: 'request', requirement: 'requirement',
+    res: 'response', resp: 'response', response: 'response',
+    err: 'error', error: 'error',
+    init: 'init', initialize: 'init', initialise: 'init', initialization: 'init',
+    impl: 'impl', implement: 'impl', implementation: 'impl', implements: 'impl',
+    spec: 'spec', specification: 'spec',
+    doc: 'doc', docs: 'doc', documentation: 'doc',
+    repo: 'repo', repository: 'repo',
+    db: 'db', database: 'db',
+}));
+/**
+ * One token, reduced to the form two spellings of the same word share.
+ *
+ * Suffix stripping is conservative and applied once — an aggressive stemmer merges words that are
+ * genuinely different (`parse`/`parsing` should merge, `general`/`generate` must not), and a wrong
+ * merge is a false positive nobody can see in the output.
+ */
+function normaliseTerm(term) {
+    const abbreviated = ABBREVIATIONS.get(term);
+    if (abbreviated)
+        return abbreviated;
+    let t = term;
+    // `ers` is deliberately absent: it would take `handlers` to `handl` while `handler` stays whole,
+    // splitting a word from its own plural — the opposite of what normalisation is for. Plain `s`
+    // handles that pair correctly.
+    for (const [suffix, min] of [['ings', 6], ['ing', 5], ['ies', 5], ['ed', 4], ['es', 4], ['s', 4]]) {
+        if (t.length >= min && t.endsWith(suffix)) {
+            t = t.slice(0, -suffix.length);
+            break;
+        }
+    }
+    if (t.endsWith('i'))
+        t = `${t.slice(0, -1)}y`; // `ies` -> `i` -> `y`
+    // `quarantine` and `quarantining` must land on the same stem: stripping `ing` leaves `quarantin`
+    // while the base form keeps its silent `e`, so the `e` goes too. Length-guarded, or `file` and
+    // `code` would be mangled into stems that collide with unrelated short words.
+    if (t.length >= 5 && t.endsWith('e'))
+        t = t.slice(0, -1);
+    return ABBREVIATIONS.get(t) ?? t;
+}
+const normalisedTerms = (text) => (0, localize_1.significantTerms)(text).map(normaliseTerm);
+exports.normalisedTerms = normalisedTerms;
+/**
+ * BM25 over A-SPEC documents.
+ *
+ * `k1` bounds how much repetition can add and `b` controls the length correction — the standard
+ * 1.2/0.75, not tuned here, because tuning two constants on sixty cases fits noise and this arm has
+ * to answer a yes-or-no question about the idea rather than squeeze the last point out of it.
+ *
+ * A-SPEC only, as everywhere else: files anchor A-SPECs, so no other kind can pull a file through.
+ */
+function retrieveSpecs(issueText, specs, topK) {
+    const query = [...new Set((0, exports.normalisedTerms)(issueText))];
+    if (query.length === 0)
+        return [];
+    const docs = specs
+        .filter((s) => s.type === 'A-SPEC')
+        .map((s) => ({ id: s.id, terms: (0, exports.normalisedTerms)(`${s.title} ${Object.values(s.sections).join(' ')}`) }));
+    if (docs.length === 0)
+        return [];
+    const avgLen = docs.reduce((sum, d) => sum + d.terms.length, 0) / docs.length;
+    const df = new Map();
+    for (const d of docs)
+        for (const t of new Set(d.terms))
+            df.set(t, (df.get(t) ?? 0) + 1);
+    const k1 = 1.2, b = 0.75;
+    const scored = [];
+    for (const d of docs) {
+        const freq = new Map();
+        for (const t of d.terms)
+            freq.set(t, (freq.get(t) ?? 0) + 1);
+        let score = 0;
+        for (const q of query) {
+            const f = freq.get(q) ?? 0;
+            if (f === 0)
+                continue;
+            const n = df.get(q) ?? 0;
+            // Standard BM25 IDF, floored: a term in every document contributes nothing rather than
+            // subtracting, which would make a common word count AGAINST a spec that contains it.
+            const idf = Math.max(Math.log(1 + (docs.length - n + 0.5) / (n + 0.5)), 0);
+            score += idf * (f * (k1 + 1)) / (f + k1 * (1 - b + b * (d.terms.length / (avgLen || 1))));
+        }
+        if (score > 0)
+            scored.push({ id: d.id, score });
+    }
+    return scored.sort((a, b2) => b2.score - a.score || a.id.localeCompare(b2.id)).slice(0, topK);
+}
+function expandThroughGraph(issueText, topFiles, specs, opts) {
+    const base = [...new Set((0, exports.normalisedTerms)(issueText))];
+    const expansion = new Map();
+    if (opts.weight <= 0 || opts.seedFiles <= 0)
+        return { base, expansion };
+    const byId = new Map(specs.filter((s) => s.type === 'A-SPEC').map((s) => [s.id, s]));
+    const reached = new Set();
+    for (const f of topFiles.slice(0, opts.seedFiles))
+        for (const id of f.anchors)
+            if (byId.has(id))
+                reached.add(id);
+    if (reached.size === 0)
+        return { base, expansion };
+    // Rank the spec's own vocabulary by how distinctive it is within the reached set, so expansion
+    // contributes the words that make those specs different rather than the words every spec uses.
+    const df = new Map();
+    const perSpec = [];
+    for (const id of reached) {
+        const s = byId.get(id);
+        const terms = [...new Set((0, exports.normalisedTerms)(`${s.title} ${Object.values(s.sections).join(' ')}`))];
+        perSpec.push(terms);
+        for (const t of terms)
+            df.set(t, (df.get(t) ?? 0) + 1);
+    }
+    const baseSet = new Set(base);
+    for (const terms of perSpec) {
+        const ranked = terms
+            .filter((t) => !baseSet.has(t))
+            .sort((a, b) => (df.get(a) ?? 0) - (df.get(b) ?? 0) || a.localeCompare(b))
+            .slice(0, opts.termsPerSpec);
+        for (const t of ranked)
+            expansion.set(t, Math.max(expansion.get(t) ?? 0, opts.weight));
+    }
+    return { base, expansion };
+}

package/dist/holmes/review/spec-layer-stats.d.ts

@@ -0,0 +1,38 @@
+import type { ScannedFile } from '../cpg/cpg-scanner';
+import type { Spec } from '../spec/spec-parser';
+import type { LocalizationReport } from '../rtm/localize';
+/**
+ * What the spec layer is actually doing on a corpus.
+ *
+ * All of the harness's measured advantage lives in this layer (A-SPEC-362), and on the second corpus
+ * it delivers nothing — near-parity with plain word matching, ahead on two axes and behind on two.
+ * The density explanation was tested and retracted: that corpus resolves an anchor for every scanned
+ * file. So the layer is present, connected, and not paying, and the next honest step is to count what
+ * it does rather than to guess again.
+ *
+ * Every field is a count or a share, deliberately: a single "spec layer health" score would hide
+ * which of these differs, and it is the difference between corpora that carries the answer.
+ */
+export interface SpecLayerStats {
+    cases: number;
+    /** A-SPECs the request was taken to match, per case. */
+    matchedSpecs: number;
+    /** Files that received a spec bonus, per case. */
+    filesViaSpec: number;
+    /** Of those, the share that the commit actually changed — the layer's own precision. */
+    viaSpecPrecision: number | null;
+    /** Truth files reached ONLY through a spec — what the layer uniquely contributes. */
+    truthOnlyViaSpec: number;
+    /** Files anchoring each spec, and specs anchored by each file: the shape of the mapping. */
+    filesPerSpec: number | null;
+    specsPerFile: number | null;
+    /** Share of cases whose request text cited a spec outright — the strongest signal available. */
+    citingCases: number | null;
+}
+export interface CaseObservation {
+    report: LocalizationReport;
+    scanned: readonly ScannedFile[];
+    specs: readonly Spec[];
+    truthFiles: readonly string[];
+}
+export declare function specLayerStats(observations: readonly CaseObservation[]): SpecLayerStats;

package/dist/holmes/review/spec-layer-stats.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specLayerStats = specLayerStats;
+function specLayerStats(observations) {
+    if (observations.length === 0) {
+        return { cases: 0, matchedSpecs: 0, filesViaSpec: 0, viaSpecPrecision: null,
+            truthOnlyViaSpec: 0, filesPerSpec: null, specsPerFile: null, citingCases: null };
+    }
+    let matched = 0, viaFiles = 0, viaHits = 0, onlyVia = 0, citing = 0;
+    let fps = 0, spf = 0, shapeSamples = 0;
+    for (const o of observations) {
+        matched += o.report.matchedSpecs.length;
+        const truth = new Set(o.truthFiles);
+        const via = o.report.hits.filter((h) => h.viaSpecs.length > 0);
+        viaFiles += via.length;
+        viaHits += via.filter((h) => truth.has(h.file)).length;
+        // Reached only through a spec: no symbol matched and no path term did, so the lexical layer
+        // could not have produced it at any weighting.
+        onlyVia += via.filter((h) => truth.has(h.file) && h.matchedSymbols.length === 0).length;
+        if (o.report.hits.some((h) => h.why.some((w) => w.startsWith('request cites'))))
+            citing++;
+        const known = new Set(o.specs.map((s) => s.id));
+        const perSpec = new Map();
+        let anchorsTotal = 0, anchoredFiles = 0;
+        for (const f of o.scanned) {
+            const anchors = [...new Set(f.implementsSpecs ?? [])].filter((id) => known.has(id));
+            if (anchors.length === 0)
+                continue;
+            anchoredFiles++;
+            anchorsTotal += anchors.length;
+            for (const id of anchors)
+                perSpec.set(id, (perSpec.get(id) ?? 0) + 1);
+        }
+        if (anchoredFiles > 0) {
+            fps += [...perSpec.values()].reduce((a, b) => a + b, 0) / Math.max(1, perSpec.size);
+            spf += anchorsTotal / anchoredFiles;
+            shapeSamples++;
+        }
+    }
+    const n = observations.length;
+    return {
+        cases: n,
+        matchedSpecs: matched / n,
+        filesViaSpec: viaFiles / n,
+        // null, not zero: if the layer scored no file at all there is no precision to report.
+        viaSpecPrecision: viaFiles === 0 ? null : viaHits / viaFiles,
+        truthOnlyViaSpec: onlyVia / n,
+        filesPerSpec: shapeSamples === 0 ? null : fps / shapeSamples,
+        specsPerFile: shapeSamples === 0 ? null : spf / shapeSamples,
+        citingCases: citing / n,
+    };
+}

package/dist/holmes/review/temporal-prior.d.ts

@@ -0,0 +1,33 @@
+/**
+ * How recently and how often each file changed, as of a point in time.
+ *
+ * Every graph mechanism tried against uncited requests has been a spec-graph mechanism, and all five
+ * were negative. The Goal's Phase 3 names a second structure that has never been used for retrieval
+ * at all: the temporal graph — Commit nodes and `changed_by` edges. A file that changed recently and
+ * often is more likely to change again, which is one of the oldest findings in fault localization,
+ * and unlike everything tried so far it does not depend on the request naming anything.
+ *
+ * POINT-IN-TIME is the whole discipline here. Reading the answer commit, or anything after it, is
+ * reading the answer: the file the commit touched will look "recently changed" because it is about
+ * to be. The window ends at the parent, exactly as the rest of the replay does.
+ */
+export interface TemporalPrior {
+    /** Commits, within the window, that touched each file. */
+    frequency: Map<string, number>;
+    /** How many commits back the file was last touched; absent when it never was. */
+    recency: Map<string, number>;
+    /** Commits actually examined — 0 means the prior is UNMEASURED, not that nothing changed. */
+    commits: number;
+}
+export declare function temporalPrior(root: string, before: string, limit?: number): TemporalPrior;
+/**
+ * The multiplier a file's history earns.
+ *
+ * Multiplicative rather than additive: the prior says which of several plausible files is likelier,
+ * and it must not promote a file the request has no lexical connection to at all. A file with no
+ * history in the window scores 1 — unknown is not evidence against.
+ *
+ * `halfLife` is in commits. Recency decays geometrically; frequency enters through a log so that a
+ * file touched fifty times is not fifty times likelier than one touched once.
+ */
+export declare function priorFor(prior: TemporalPrior, file: string, halfLife: number, freqWeight: number): number;

package/dist/holmes/review/temporal-prior.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.temporalPrior = temporalPrior;
+exports.priorFor = priorFor;
+// @implements A-SPEC-377
+const node_child_process_1 = require("node:child_process");
+const maintenance_analyze_1 = require("../mcp/maintenance-analyze");
+function temporalPrior(root, before, limit = 200) {
+    let raw;
+    try {
+        raw = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'log', '--no-merges', `-${limit}`, '--format=%H', '--name-only', before], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    }
+    catch {
+        // A repository or revision this machine does not have is unmeasured, not empty.
+        return { frequency: new Map(), recency: new Map(), commits: 0 };
+    }
+    const frequency = new Map();
+    const recency = new Map();
+    let index = -1;
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (t.length === 0)
+            continue;
+        if (/^[0-9a-f]{40}$/.test(t)) {
+            index++;
+            continue;
+        }
+        const file = (0, maintenance_analyze_1.unquoteGitPath)(t);
+        frequency.set(file, (frequency.get(file) ?? 0) + 1);
+        if (!recency.has(file))
+            recency.set(file, index); // first sighting is the most recent commit
+    }
+    return { frequency, recency, commits: index + 1 };
+}
+/**
+ * The multiplier a file's history earns.
+ *
+ * Multiplicative rather than additive: the prior says which of several plausible files is likelier,
+ * and it must not promote a file the request has no lexical connection to at all. A file with no
+ * history in the window scores 1 — unknown is not evidence against.
+ *
+ * `halfLife` is in commits. Recency decays geometrically; frequency enters through a log so that a
+ * file touched fifty times is not fifty times likelier than one touched once.
+ */
+function priorFor(prior, file, halfLife, freqWeight) {
+    if (prior.commits === 0)
+        return 1;
+    const age = prior.recency.get(file);
+    const freq = prior.frequency.get(file) ?? 0;
+    const recencyTerm = age === undefined ? 0 : Math.pow(0.5, age / halfLife);
+    const freqTerm = Math.log1p(freq) / Math.log1p(10);
+    return 1 + recencyTerm + freqWeight * freqTerm;
+}

package/dist/holmes/review/test-runner.d.ts

@@ -60,6 +60,21 @@ export declare function parseExecutedCounts(stdout: string, cwd: string): Record
  * pending/skipped assertions are excluded. Errors and failures DO count: they executed.
  */
 export declare function parseJUnitXmlCounts(xml: string, ext?: string): Record<string, number>;
+/**
+ * @implements A-SPEC-466 — W-4. The TARGET repo's own jest entry, as its package declares it.
+ *
+ * Windows npm/npx are `.cmd` shims: execFileSync('npx') is ENOENT and naming the .cmd is EINVAL
+ * (Node's batch-file mitigation), so `test_run` could never produce ART-4 execution evidence there
+ * — measured by the Windows review with a suite that passes standalone. Running the resolved JS
+ * entry with THIS node binary (process.execPath) removes the shim from the path entirely.
+ *
+ * `require.resolve('jest/bin/jest.js')` is blocked by jest's `exports` (measured:
+ * ERR_PACKAGE_PATH_NOT_EXPORTED), so the package.json is resolved instead and its own `bin`
+ * declaration is read — the package names its entry, this code does not guess it. Any failure
+ * returns null and the caller keeps the npx spelling: POSIX behavior is unchanged (no .cmd problem
+ * there), and a repo with no local jest could never yield meaningful suite evidence anyway.
+ */
+export declare function jestEntry(cwd: string): string | null;
 /**
  * @implements A-SPEC-137.2
  * Executed-test count from `cargo test` text output. cargo prints one `test <name> ... ok|FAILED|

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

@@ -38,6 +38,7 @@ exports.ecosystemOf = ecosystemOf;
 exports.parseGoTestJson = parseGoTestJson;
 exports.parseExecutedCounts = parseExecutedCounts;
 exports.parseJUnitXmlCounts = parseJUnitXmlCounts;
+exports.jestEntry = jestEntry;
 exports.parseCargoTest = parseCargoTest;
 exports.runCargo = runCargo;
 exports.runGradle = runGradle;
@@ -75,7 +76,11 @@ function ecosystemOf(file) {
     // @implements A-SPEC-137.2 — Rust test files, matching the scanner's isTestFile convention:
     // tests/<x>.rs (integration), <x>_test(s).rs, <x>_unittest.rs, test_<x>.rs. A plain src/x.rs may
     // carry inline #[cfg(test)] unit tests but is a production source, not a selected test file.
-    if (/(^|\/)(tests\/[^/]*|[^/]*_(tests?|unittest)|test_[^/]*)\.rs$/i.test(file))
+    // @implements A-SPEC-466 — both separators. The Windows review (W-4 section) measured
+    // ecosystemOf('tests\it.rs') = null: this was the only ecosystem whose pattern names a DIRECTORY,
+    // and the directory separator was spelled '/' only. java/dotnet were unaffected — their `[^/]*`
+    // happens to accept a backslash — so only this line changes.
+    if (/(^|[\\/])(tests[\\/][^\\/]*|[^\\/]*_(tests?|unittest)|test_[^\\/]*)\.rs$/i.test(file))
         return 'rust';
     // @implements A-SPEC-137.3 — JUnit/xUnit naming (case-sensitive `Test` so Manifest.java is not a
     // test): Java `…Test(s|Case|Cases).java`, C# `…Test(s).cs`.
@@ -181,6 +186,34 @@ function parseJUnitXmlCounts(xml, ext = 'py') {
     }
     return out;
 }
+/**
+ * @implements A-SPEC-466 — W-4. The TARGET repo's own jest entry, as its package declares it.
+ *
+ * Windows npm/npx are `.cmd` shims: execFileSync('npx') is ENOENT and naming the .cmd is EINVAL
+ * (Node's batch-file mitigation), so `test_run` could never produce ART-4 execution evidence there
+ * — measured by the Windows review with a suite that passes standalone. Running the resolved JS
+ * entry with THIS node binary (process.execPath) removes the shim from the path entirely.
+ *
+ * `require.resolve('jest/bin/jest.js')` is blocked by jest's `exports` (measured:
+ * ERR_PACKAGE_PATH_NOT_EXPORTED), so the package.json is resolved instead and its own `bin`
+ * declaration is read — the package names its entry, this code does not guess it. Any failure
+ * returns null and the caller keeps the npx spelling: POSIX behavior is unchanged (no .cmd problem
+ * there), and a repo with no local jest could never yield meaningful suite evidence anyway.
+ */
+function jestEntry(cwd) {
+    try {
+        const pkgPath = require.resolve('jest/package.json', { paths: [cwd] });
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.jest;
+        if (!bin)
+            return null;
+        const entry = path.join(path.dirname(pkgPath), bin);
+        return fs.existsSync(entry) ? entry : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Run the jest half of a plan. */
 function runJest(files, mode, cwd) {
     // --runTestsByPath treats args as EXACT files (not testPathPattern REGEXes, which would over/mis-match
@@ -190,11 +223,15 @@ function runJest(files, mode, cwd) {
     // nothing has verified nothing. `full` mode runs the whole suite.
     const safeFiles = files.map((p) => (p.startsWith('-') ? `./${p}` : p));
     // --json yields per-file assertion results = EXECUTION evidence (see parseExecutedCounts).
+    // @implements A-SPEC-466 — resolved local jest via process.execPath when the target repo has one
+    // (structurally no .cmd shim to ENOENT on); the npx spelling only as the fallback.
+    const entry = jestEntry(cwd);
+    const [cmd, ...pre] = entry !== null ? [process.execPath, entry] : ['npx', 'jest'];
     const args = mode === 'scoped'
-        ? ['jest', '--silent', '--json', '--runTestsByPath', '--', ...safeFiles]
-        : ['jest', '--silent', '--json'];
+        ? [...pre, '--silent', '--json', '--runTestsByPath', '--', ...safeFiles]
+        : [...pre, '--silent', '--json'];
     try {
-        const out = (0, node_child_process_1.execFileSync)('npx', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+        const out = (0, node_child_process_1.execFileSync)(cmd, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
         return { passed: true, tail: tailOf(out), executed: parseExecutedCounts(out, cwd) };
     }
     catch (e) {

package/dist/holmes/review/test-selection-breadth.d.ts

@@ -0,0 +1,75 @@
+/**
+ * What the harness's test-selection recall is actually made of.
+ *
+ * The replay reports `testRecall` — 0.883 on this repository, 0.867 on the second — and this
+ * document has quoted those numbers repeatedly. What was never measured is HOW they are reached.
+ *
+ * They are reached by selecting most of the suite. A commit changes 2.2 test files on average here
+ * and 1.2 there; the harness names 131.0 and 89.9, which is 63.6% and 81.3% of every anchored test.
+ * Precision is 0.015 and 0.012. A recall figure computed over a selection that size is not evidence
+ * of discrimination — "run almost everything" scores well on recall by construction, and the whole
+ * value of intelligent test selection is running FEWER tests without losing the signal.
+ *
+ * For contrast, the crudest rule a person would use — run the test whose filename contains the
+ * changed file's stem — names 6.6 and 2.6 tests and still catches 49 of 67 and 14 of 36 answers.
+ * Lower recall, twenty to thirty times fewer tests.
+ *
+ * The selection is NOT narrowed here. Narrowing costs recall, where the right trade sits needs more
+ * measurement than this slice has, and tightening a gate on a hunch is a mistake this repository has
+ * already had to undo more than once. What this slice fixes is the reading: `testRecall` quoted
+ * alone reads as discrimination, and it is not.
+ */
+export interface TestSelectionSlice {
+    corpus: string;
+    cases: number;
+    /** Tests the harness named, averaged over cases. */
+    avgSelected: number;
+    /** Anchored tests that existed to choose from. */
+    avgUniverse: number;
+    /** Tests the commit actually changed. */
+    avgTruth: number;
+    recall: number;
+    precision: number;
+    /** The filename-stem rule, for contrast. */
+    naiveAvgSelected: number;
+    naiveHits: number;
+    truthTotal: number;
+}
+/** Measured 2026-08-29 through analyzeMaintenance on the newest 30 cases of each corpus. */
+export declare const TEST_SELECTION: readonly TestSelectionSlice[];
+/** How much of the available suite the selection covers. Near 1 means recall is uninformative. */
+export declare function selectionShare(s: TestSelectionSlice): number;
+/**
+ * Recall bought per test selected — the figure that separates discrimination from breadth. Selecting
+ * the whole suite drives this to its floor while `recall` reads 1.0.
+ */
+export declare function recallPerSelectedTest(s: TestSelectionSlice): number;
+/**
+ * How far the selection could be narrowed — asked because A-SPEC-424 left it open.
+ *
+ * The harness's own selection, reordered by how well each test's filename matches the stems of the
+ * ranked candidate files, then cut at K. On this repository that ordering works: twenty tests
+ * instead of a hundred and thirty-one keep 89% of the recall, forty keep 94%. On the second corpus
+ * the same ordering does almost nothing until eighty.
+ *
+ * So the headroom is real and the cut is not safe. Introducing K=40 would cost 0.05 of recall here
+ * and 0.53 there. Recorded as both facts at once, because either one alone is misleading.
+ */
+export interface NarrowingCurve {
+    corpus: string;
+    avgSelected: number;
+    /** recall at each K, and `full` when nothing is cut. */
+    at: ReadonlyArray<{
+        k: number;
+        recall: number;
+    }>;
+    full: number;
+}
+/** Measured 2026-08-29, newest 30 cases per corpus, through analyzeMaintenance. */
+export declare const NARROWING_CURVE: readonly NarrowingCurve[];
+export declare function recallAt(curve: NarrowingCurve, k: number): number;
+/**
+ * Whether cutting at K keeps most of the recall on EVERY corpus measured. One corpus agreeing is
+ * not evidence — that is the shape of mistake this repository keeps having to undo.
+ */
+export declare function narrowingIsSafe(curves: readonly NarrowingCurve[], k: number, keep?: number): boolean;

package/dist/holmes/review/test-selection-breadth.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NARROWING_CURVE = exports.TEST_SELECTION = void 0;
+exports.selectionShare = selectionShare;
+exports.recallPerSelectedTest = recallPerSelectedTest;
+exports.recallAt = recallAt;
+exports.narrowingIsSafe = narrowingIsSafe;
+/** Measured 2026-08-29 through analyzeMaintenance on the newest 30 cases of each corpus. */
+exports.TEST_SELECTION = [
+    {
+        corpus: 'holmes newest-30', cases: 30,
+        avgSelected: 131.0, avgUniverse: 206.1, avgTruth: 2.2,
+        recall: 0.883, precision: 0.015,
+        naiveAvgSelected: 6.6, naiveHits: 49, truthTotal: 67,
+    },
+    {
+        corpus: 'jarvis newest-30', cases: 30,
+        avgSelected: 89.9, avgUniverse: 110.6, avgTruth: 1.2,
+        recall: 0.867, precision: 0.012,
+        naiveAvgSelected: 2.6, naiveHits: 14, truthTotal: 36,
+    },
+];
+/** How much of the available suite the selection covers. Near 1 means recall is uninformative. */
+function selectionShare(s) {
+    return s.avgUniverse === 0 ? 0 : s.avgSelected / s.avgUniverse;
+}
+/**
+ * Recall bought per test selected — the figure that separates discrimination from breadth. Selecting
+ * the whole suite drives this to its floor while `recall` reads 1.0.
+ */
+function recallPerSelectedTest(s) {
+    return s.avgSelected === 0 ? 0 : s.recall / s.avgSelected;
+}
+/** Measured 2026-08-29, newest 30 cases per corpus, through analyzeMaintenance. */
+exports.NARROWING_CURVE = [
+    {
+        corpus: 'holmes newest-30', avgSelected: 131.0, full: 0.883,
+        at: [{ k: 1, recall: 0.318 }, { k: 3, recall: 0.434 }, { k: 5, recall: 0.451 },
+            { k: 10, recall: 0.668 }, { k: 20, recall: 0.789 }, { k: 40, recall: 0.833 }, { k: 80, recall: 0.883 }],
+    },
+    {
+        corpus: 'jarvis newest-30', avgSelected: 89.9, full: 0.867,
+        at: [{ k: 1, recall: 0.067 }, { k: 3, recall: 0.150 }, { k: 5, recall: 0.150 },
+            { k: 10, recall: 0.283 }, { k: 20, recall: 0.283 }, { k: 40, recall: 0.333 }, { k: 80, recall: 0.767 }],
+    },
+];
+function recallAt(curve, k) {
+    const point = curve.at.find((p) => p.k === k);
+    return point?.recall ?? curve.full;
+}
+/**
+ * Whether cutting at K keeps most of the recall on EVERY corpus measured. One corpus agreeing is
+ * not evidence — that is the shape of mistake this repository keeps having to undo.
+ */
+function narrowingIsSafe(curves, k, keep = 0.9) {
+    return curves.every((c) => recallAt(c, k) / c.full >= keep);
+}