@holmes-lab/holmes-kit 0.18.0 → 0.19.2

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

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PRIMARY_TIER_WIDTH = exports.EVIDENCE_DIMENSIONS = exports.MAINTENANCE_ANALYSIS_EXTRACTOR = exports.MAINTENANCE_ANALYSIS_SCHEMA = void 0;
+exports.ANALYZE_TEXT_CAP = exports.ANALYZE_LIST_CAP = exports.PRIMARY_TIER_WIDTH = exports.EVIDENCE_DIMENSIONS = exports.MAINTENANCE_ANALYSIS_EXTRACTOR = exports.MAINTENANCE_ANALYSIS_SCHEMA = void 0;
 exports.unquoteGitPath = unquoteGitPath;
 exports.analyzeMaintenance = analyzeMaintenance;
+exports.boundAnalysis = boundAnalysis;
 // @implements A-SPEC-295
 // @implements A-SPEC-294
 // @implements A-SPEC-293
@@ -34,6 +35,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 +184,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 +207,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 +305,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 +359,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 +403,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 +492,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;
@@ -1012,3 +1049,74 @@ function buildAblation(a) {
     ], truth, a.primaryTier, a.impactedTier, a.importedByTier);
     return { graphOff, current, enhanced };
 }
+// @implements A-SPEC-578.5
+/**
+ * Items a response lists before it starts counting instead.
+ *
+ * TEN, because that is the unit this product is measured in: localization emits Top-10 and every
+ * recall figure in this repository is recall@10. Aligning the response cap with the emission unit
+ * is a reason; picking a number that happens to hit a size target is a knob. Measured on the real
+ * 187,174-character response: cap 20 gave 34,811 with `intent` alone at 11,037 (32%), cap 10 fits.
+ */
+exports.ANALYZE_LIST_CAP = 10;
+/** Characters one listed item keeps. */
+exports.ANALYZE_TEXT_CAP = 400;
+/** Dropped whole: another tool answers this question, and it is 41,619 characters of the answer. */
+const DROPPED_FIELDS = ['contextBundle'];
+/**
+ * @implements A-SPEC-578.5
+ * The RESPONSE-EDGE projection. The artifact on disk keeps everything.
+ *
+ * Measured 2026-09-09: one `maintenance_analyze` call returns 187,174 characters (~47k tokens) and
+ * the harness refuses it outright. AGENTS.md step 3 instructs every agent to make that call before
+ * editing source — and across 2,779 spec approvals `persist:true` had never been used once. An
+ * instruction nobody can afford to follow is not an instruction.
+ *
+ * The cap is applied RECURSIVELY, which the first cut got wrong. Capping only the top level took
+ * the response from 187,174 to 142,701 and no further, because the weight is in NESTED DUPLICATES:
+ * `impacts.test` and `testScope.impactedTestFiles` carry the same 158 paths, and `impacts.contract`
+ * and `testScope.impactedSpecs` the same 160 spec ids. A cap that stops at depth one caps the
+ * cheapest arrays in the document.
+ *
+ * NEVER CALLED FROM `analyzeMaintenance`. The design-time advisory named the replay benchmark
+ * (`run-replay.ts`, `replay-corpus.ts`, `commit-text.ts`, `temporal-prior.ts`) as readers of this
+ * type, and among their anchors sits A-SPEC-402 — "the numbers reported are not what the product
+ * does". Bounding inside the analysis would make every pinned benchmark score a truncated
+ * pipeline, which is the most expensive instrument failure this repository has recorded. The
+ * benchmark keeps seeing exactly what it sees today; only the conversation gets the short form.
+ *
+ * What is dropped is COUNTED, at whatever depth it was dropped. A response that quietly shrank
+ * would be a worse lie than a long one.
+ */
+function boundAnalysis(a) {
+    const src = a;
+    const out = boundValue(src, 0);
+    for (const field of DROPPED_FIELDS)
+        delete out[field];
+    return out;
+}
+/** Depth bound: deep enough for the shapes measured, shallow enough to terminate on any input. */
+const BOUND_MAX_DEPTH = 6;
+function boundValue(value, depth) {
+    if (depth > BOUND_MAX_DEPTH || value === null || typeof value !== 'object')
+        return trimItem(value);
+    if (Array.isArray(value)) {
+        return value.slice(0, exports.ANALYZE_LIST_CAP).map((v) => boundValue(v, depth + 1));
+    }
+    const src = value;
+    const out = {};
+    for (const [k, v] of Object.entries(src)) {
+        out[k] = boundValue(v, depth + 1);
+        // The counter sits BESIDE the array it describes, at the depth it was cut, so a nested trim is
+        // as visible as a top-level one.
+        if (Array.isArray(v) && v.length > exports.ANALYZE_LIST_CAP)
+            out[`${k}Omitted`] = v.length - exports.ANALYZE_LIST_CAP;
+    }
+    return out;
+}
+/** Trim one listed item. A long item is CUT, never discarded — the item's existence is information. */
+function trimItem(item) {
+    if (typeof item !== 'string' || item.length <= exports.ANALYZE_TEXT_CAP)
+        return item;
+    return `${item.slice(0, exports.ANALYZE_TEXT_CAP)}… [+${item.length - exports.ANALYZE_TEXT_CAP}]`;
+}

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

@@ -100,8 +100,49 @@ export interface OutcomeInput {
 /**
  * Attach what actually happened to a prediction that was actually made. An unknown digest is
  * refused: inventing the prediction alongside the outcome would let the record score itself.
+ *
+ * @implements A-SPEC-578.6
+ * MERGES into any outcome already there. It used to REPLACE, and the defect was found by following
+ * this repository's own instruction: A-SPEC-578.4 made `test_run` attach the 12 files a slice
+ * actually changed, AGENTS.md then said "call maintenance_outcome yourself only to add a judged
+ * classification" — and that call left `actualFiles: []`. The documented workflow destroyed the
+ * data it existed to complete.
+ *
+ * Omission and erasure are DIFFERENT ACTS: a field left out keeps its value, a field given as an
+ * empty array is cleared. Without the second, a wrong record could never be corrected; without the
+ * first, completing a record destroys it.
  */
 export declare function recordOutcome(dir: string, digest: string, outcome: OutcomeInput, recordedAt: string): EvidenceArtifact;
+/**
+ * Predictions still waiting to be scored — the loop's missing second half.
+ *
+ * `since` bounds the window: an analysis recorded before the previous evidence run belonged to a
+ * previous slice, and attributing today's changes to it would be contamination rather than
+ * measurement. The boundary is EXCLUSIVE (`> since`) because the previous run already saw that
+ * instant.
+ */
+export declare function openArtifacts(dir: string, since?: string): EvidenceArtifact[];
+/**
+ * @implements A-SPEC-578.4
+ * Attach what a slice ACTUALLY touched to the predictions it made.
+ *
+ * Measured 2026-09-09: `maintenance_calibration` had reported `n:0, artifacts:0` since the loop was
+ * built, because `maintenance_analyze({persist:true})` is instructed (AGENTS.md step 3) while
+ * `maintenance_outcome` is instructed nowhere at all. The write path was healthy the whole time —
+ * one call produced an artifact immediately. What was missing was the call.
+ *
+ * TWO REFUSALS make this a measurement rather than a self-graded exam:
+ *  - `actualClassification` is never filled in. That is a judgement, and a loop that supplies its
+ *    own judgement scores itself; the bins stay `insufficient-data` and only the objective half —
+ *    file-level false positives and negatives — accrues.
+ *  - An empty change set closes nothing. Attributing "nothing changed" would turn every prediction
+ *    into a false positive: a measurement of nothing, recorded as a failure of everything.
+ */
+export declare function closeOpenArtifacts(dir: string, actual: {
+    files: string[];
+}, recordedAt: string, since?: string): {
+    closed: string[];
+};
 export interface CalibrationBin {
     lower: number;
     upper: number;

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

@@ -39,6 +39,8 @@ exports.artifactFrom = artifactFrom;
 exports.writeArtifact = writeArtifact;
 exports.readArtifacts = readArtifacts;
 exports.recordOutcome = recordOutcome;
+exports.openArtifacts = openArtifacts;
+exports.closeOpenArtifacts = closeOpenArtifacts;
 exports.computeCalibration = computeCalibration;
 // @implements A-SPEC-271
 // @implements A-SPEC-268
@@ -170,6 +172,17 @@ function readArtifacts(dir) {
 /**
  * Attach what actually happened to a prediction that was actually made. An unknown digest is
  * refused: inventing the prediction alongside the outcome would let the record score itself.
+ *
+ * @implements A-SPEC-578.6
+ * MERGES into any outcome already there. It used to REPLACE, and the defect was found by following
+ * this repository's own instruction: A-SPEC-578.4 made `test_run` attach the 12 files a slice
+ * actually changed, AGENTS.md then said "call maintenance_outcome yourself only to add a judged
+ * classification" — and that call left `actualFiles: []`. The documented workflow destroyed the
+ * data it existed to complete.
+ *
+ * Omission and erasure are DIFFERENT ACTS: a field left out keeps its value, a field given as an
+ * empty array is cleared. Without the second, a wrong record could never be corrected; without the
+ * first, completing a record destroys it.
  */
 function recordOutcome(dir, digest, outcome, recordedAt) {
     const file = path.join(dir, digestFilename(digest));
@@ -177,19 +190,73 @@ function recordOutcome(dir, digest, outcome, recordedAt) {
         throw new Error(`Refusing to record an outcome for an unknown analysis digest: ${digest}`);
     }
     const artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const prev = artifact.outcome;
+    const merged = (given, before) => given === undefined ? (before ?? []) : sortedUnique(given);
+    const classification = outcome.actualClassification ?? prev?.actualClassification;
     const updated = {
         ...artifact,
         outcome: {
             recordedAt,
-            actualFiles: sortedUnique(outcome.actualFiles ?? []),
-            actualSymbols: sortedUnique(outcome.actualSymbols ?? []),
-            actualTests: sortedUnique(outcome.actualTests ?? []),
-            ...(outcome.actualClassification ? { actualClassification: outcome.actualClassification } : {}),
+            actualFiles: merged(outcome.actualFiles, prev?.actualFiles),
+            actualSymbols: merged(outcome.actualSymbols, prev?.actualSymbols),
+            actualTests: merged(outcome.actualTests, prev?.actualTests),
+            ...(classification ? { actualClassification: classification } : {}),
         },
     };
     writeAtomic(file, `${JSON.stringify(updated, null, 2)}\n`);
     return updated;
 }
+// @implements A-SPEC-578.4
+/**
+ * Predictions still waiting to be scored — the loop's missing second half.
+ *
+ * `since` bounds the window: an analysis recorded before the previous evidence run belonged to a
+ * previous slice, and attributing today's changes to it would be contamination rather than
+ * measurement. The boundary is EXCLUSIVE (`> since`) because the previous run already saw that
+ * instant.
+ */
+function openArtifacts(dir, since) {
+    const { artifacts } = readArtifacts(dir);
+    return artifacts.filter((a) => {
+        if (a.outcome !== undefined)
+            return false;
+        if (since === undefined)
+            return true;
+        const t = Date.parse(a.recordedAt);
+        const s = Date.parse(since);
+        return !Number.isFinite(t) || !Number.isFinite(s) ? true : t > s;
+    });
+}
+/**
+ * @implements A-SPEC-578.4
+ * Attach what a slice ACTUALLY touched to the predictions it made.
+ *
+ * Measured 2026-09-09: `maintenance_calibration` had reported `n:0, artifacts:0` since the loop was
+ * built, because `maintenance_analyze({persist:true})` is instructed (AGENTS.md step 3) while
+ * `maintenance_outcome` is instructed nowhere at all. The write path was healthy the whole time —
+ * one call produced an artifact immediately. What was missing was the call.
+ *
+ * TWO REFUSALS make this a measurement rather than a self-graded exam:
+ *  - `actualClassification` is never filled in. That is a judgement, and a loop that supplies its
+ *    own judgement scores itself; the bins stay `insufficient-data` and only the objective half —
+ *    file-level false positives and negatives — accrues.
+ *  - An empty change set closes nothing. Attributing "nothing changed" would turn every prediction
+ *    into a false positive: a measurement of nothing, recorded as a failure of everything.
+ */
+function closeOpenArtifacts(dir, actual, recordedAt, since) {
+    const files = Array.isArray(actual?.files) ? actual.files : [];
+    if (files.length === 0)
+        return { closed: [] };
+    const closed = [];
+    for (const a of openArtifacts(dir, since)) {
+        try {
+            recordOutcome(dir, a.digest, { actualFiles: files }, recordedAt);
+            closed.push(a.digest);
+        }
+        catch { /* an artifact we cannot write is not a reason to abandon the rest */ }
+    }
+    return { closed };
+}
 const BIN_EDGES = [0, 0.2, 0.4, 0.6, 0.8, 1];
 /**
  * Reliability bins plus a Brier score. `minSamples` is the honesty knob: below it a bin reports

package/dist/holmes/project/install-scripts-policy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @implements A-SPEC-579
+ * npm 12 blocks dependency install scripts unless the ROOT package.json's `allowScripts` covers
+ * them ("Install commands silently skip lifecycle scripts for any dependency that does not have a
+ * matching entry" — npm docs, cli/v12/commands/npm-install-scripts). Measured 2026-09-09 on
+ * Windows (npm 12.0.1, Node 24.19.0): `npm ci` succeeded, nine install scripts were skipped, and
+ * better-sqlite3 had no binary — while the eight tree-sitter packages still loaded, because their
+ * `node-gyp-build` runtime loader finds `prebuilds/<platform>-<arch>` without the script ever
+ * running. So the minimum approval this repository needs is ONE package, pinned to the lockfile
+ * version so a dependency bump forces a fresh review.
+ *
+ * This module is the pure re-statement of that rule: no I/O, no process, no platform — the same
+ * verdict on every OS, shared by the test that pins package.json and by doctor (A-SPEC-580).
+ */
+/** Dependencies whose install script must actually RUN for the module to load. */
+export declare const NATIVE_INSTALL_SCRIPT_DEPS: readonly ["better-sqlite3"];
+/** Native dependencies that ship prebuilds and load with the script blocked (measured). */
+export declare const PREBUILT_NATIVE_DEPS: readonly ["tree-sitter", "tree-sitter-typescript", "tree-sitter-python", "tree-sitter-c-sharp", "tree-sitter-java", "tree-sitter-go", "tree-sitter-rust", "tree-sitter-cpp"];
+export type AllowScripts = Record<string, boolean>;
+export type Coverage = 'approved-pinned' | 'approved-unpinned' | 'denied' | 'uncovered';
+export interface LockLike {
+    packages?: Record<string, {
+        version?: string;
+        hasInstallScript?: boolean;
+    }>;
+}
+export type PolicyProblem = {
+    kind: 'reapproval-required';
+    name: string;
+    lockVersion: string;
+    approved: string[];
+    fix: string;
+} | {
+    kind: 'unpinned';
+    name: string;
+    fix: string;
+} | {
+    kind: 'denied';
+    name: string;
+    fix: string;
+} | {
+    kind: 'beyond-minimum';
+    key: string;
+    fix: string;
+} | {
+    kind: 'missing-from-lock';
+    name: string;
+};
+/** The exact command npm 12 documents for a pinned approval. */
+export declare function approveCommand(name: string, version: string, npmBin?: string): string;
+/**
+ * How `allowScripts` covers one package at one version, under npm 12's rules: a pinned `true`
+ * covers that version only, a bare `true` covers every version, and a `false` on either key is
+ * a denial that survives any approval (npm: deny "survives `approve --all`").
+ */
+export declare function allowScriptsCoverage(allow: AllowScripts | undefined, name: string, version: string): Coverage;
+/**
+ * What `npm install-scripts ls` would list: every lock entry with an install script that
+ * `allowScripts` does not approve. The root entry (`""`) is the project itself, never a dependency.
+ */
+export declare function blockedInstallScripts(lock: LockLike, allow: AllowScripts | undefined): {
+    name: string;
+    version: string;
+}[];
+/**
+ * This repository's policy, judged: every script-requiring dependency approved AND pinned to the
+ * lock version, and nothing else approved. Pure; never throws.
+ */
+export declare function policyVerdict(pkg: {
+    allowScripts?: AllowScripts;
+}, lock: LockLike, opts?: {
+    npmBin?: string;
+}): {
+    ok: boolean;
+    problems: PolicyProblem[];
+};

package/dist/holmes/project/install-scripts-policy.js

@@ -0,0 +1,131 @@
+"use strict";
+// @implements A-SPEC-579
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREBUILT_NATIVE_DEPS = exports.NATIVE_INSTALL_SCRIPT_DEPS = void 0;
+exports.approveCommand = approveCommand;
+exports.allowScriptsCoverage = allowScriptsCoverage;
+exports.blockedInstallScripts = blockedInstallScripts;
+exports.policyVerdict = policyVerdict;
+/**
+ * @implements A-SPEC-579
+ * npm 12 blocks dependency install scripts unless the ROOT package.json's `allowScripts` covers
+ * them ("Install commands silently skip lifecycle scripts for any dependency that does not have a
+ * matching entry" — npm docs, cli/v12/commands/npm-install-scripts). Measured 2026-09-09 on
+ * Windows (npm 12.0.1, Node 24.19.0): `npm ci` succeeded, nine install scripts were skipped, and
+ * better-sqlite3 had no binary — while the eight tree-sitter packages still loaded, because their
+ * `node-gyp-build` runtime loader finds `prebuilds/<platform>-<arch>` without the script ever
+ * running. So the minimum approval this repository needs is ONE package, pinned to the lockfile
+ * version so a dependency bump forces a fresh review.
+ *
+ * This module is the pure re-statement of that rule: no I/O, no process, no platform — the same
+ * verdict on every OS, shared by the test that pins package.json and by doctor (A-SPEC-580).
+ */
+/** Dependencies whose install script must actually RUN for the module to load. */
+exports.NATIVE_INSTALL_SCRIPT_DEPS = ['better-sqlite3'];
+/** Native dependencies that ship prebuilds and load with the script blocked (measured). */
+exports.PREBUILT_NATIVE_DEPS = [
+    'tree-sitter', 'tree-sitter-typescript', 'tree-sitter-python', 'tree-sitter-c-sharp',
+    'tree-sitter-java', 'tree-sitter-go', 'tree-sitter-rust', 'tree-sitter-cpp',
+];
+/** The exact command npm 12 documents for a pinned approval. */
+function approveCommand(name, version, npmBin = 'npm') {
+    return `${npmBin} install-scripts approve ${name}@${version}`;
+}
+/** Split an allowScripts key into its package name and optional pinned version (scopes kept). */
+function splitKey(key) {
+    const at = key.lastIndexOf('@');
+    if (at <= 0)
+        return { name: key }; // '@scope/pkg' or 'pkg'
+    return { name: key.slice(0, at), version: key.slice(at + 1) };
+}
+/**
+ * How `allowScripts` covers one package at one version, under npm 12's rules: a pinned `true`
+ * covers that version only, a bare `true` covers every version, and a `false` on either key is
+ * a denial that survives any approval (npm: deny "survives `approve --all`").
+ */
+function allowScriptsCoverage(allow, name, version) {
+    if (!allow)
+        return 'uncovered';
+    const pinned = allow[`${name}@${version}`];
+    const bare = allow[name];
+    if (pinned === false || bare === false)
+        return 'denied';
+    if (pinned === true)
+        return 'approved-pinned';
+    if (bare === true)
+        return 'approved-unpinned';
+    return 'uncovered';
+}
+/** The package name of a lockfile `packages` key: the segment after its LAST `node_modules/`. */
+function lockEntryName(key) {
+    const idx = key.lastIndexOf('node_modules/');
+    if (idx < 0)
+        return null;
+    const name = key.slice(idx + 'node_modules/'.length);
+    return name === '' ? null : name;
+}
+/**
+ * What `npm install-scripts ls` would list: every lock entry with an install script that
+ * `allowScripts` does not approve. The root entry (`""`) is the project itself, never a dependency.
+ */
+function blockedInstallScripts(lock, allow) {
+    const out = [];
+    for (const [key, entry] of Object.entries(lock.packages ?? {})) {
+        if (!entry?.hasInstallScript)
+            continue;
+        const name = lockEntryName(key);
+        if (name === null)
+            continue;
+        const version = entry.version ?? '';
+        const cov = allowScriptsCoverage(allow, name, version);
+        if (cov !== 'approved-pinned' && cov !== 'approved-unpinned')
+            out.push({ name, version });
+    }
+    return out;
+}
+/** The top-level lock version of a dependency (`node_modules/<name>`), if present. */
+function lockVersionOf(lock, name) {
+    return lock.packages?.[`node_modules/${name}`]?.version;
+}
+/**
+ * This repository's policy, judged: every script-requiring dependency approved AND pinned to the
+ * lock version, and nothing else approved. Pure; never throws.
+ */
+function policyVerdict(pkg, lock, opts) {
+    const npmBin = opts?.npmBin ?? 'npm';
+    const allow = pkg.allowScripts;
+    const problems = [];
+    for (const name of exports.NATIVE_INSTALL_SCRIPT_DEPS) {
+        const lockVersion = lockVersionOf(lock, name);
+        if (lockVersion === undefined) {
+            problems.push({ kind: 'missing-from-lock', name });
+            continue;
+        }
+        const fix = approveCommand(name, lockVersion, npmBin);
+        switch (allowScriptsCoverage(allow, name, lockVersion)) {
+            case 'approved-pinned': break;
+            case 'approved-unpinned':
+                problems.push({ kind: 'unpinned', name, fix });
+                break;
+            case 'denied':
+                problems.push({ kind: 'denied', name, fix });
+                break;
+            case 'uncovered': {
+                const approved = Object.entries(allow ?? {})
+                    .filter(([k, v]) => v === true && splitKey(k).name === name && splitKey(k).version !== undefined)
+                    .map(([k]) => splitKey(k).version);
+                problems.push({ kind: 'reapproval-required', name, lockVersion, approved, fix });
+                break;
+            }
+        }
+    }
+    const minimum = new Set(exports.NATIVE_INSTALL_SCRIPT_DEPS);
+    for (const [key, value] of Object.entries(allow ?? {})) {
+        if (value !== true)
+            continue; // a denial is never "beyond" the minimum
+        if (!minimum.has(splitKey(key).name)) {
+            problems.push({ kind: 'beyond-minimum', key, fix: `Remove "${key}" from allowScripts in package.json — it loads from its shipped prebuilds without an install script.` });
+        }
+    }
+    return { ok: problems.length === 0, problems };
+}

package/dist/holmes/project/npx-bin.d.ts

@@ -8,3 +8,9 @@
  * platform must never flip a POSIX hint to a Windows-only form.
  */
 export declare function npxBin(platform?: string): string;
+/**
+ * @implements A-SPEC-580
+ * The npm twin: the recovery commands doctor emits (`npm install-scripts approve`, `npm rebuild`)
+ * hit the same `.ps1` shim on Windows (measured 2026-09-09: npm.ps1 blocked, npm.cmd runs).
+ */
+export declare function npmBin(platform?: string): string;

package/dist/holmes/project/npx-bin.js

@@ -1,7 +1,9 @@
 "use strict";
 // @implements A-SPEC-542.1
+// @implements A-SPEC-580
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.npxBin = npxBin;
+exports.npmBin = npmBin;
 /**
  * @implements A-SPEC-542.1
  * The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
@@ -14,3 +16,11 @@ exports.npxBin = npxBin;
 function npxBin(platform = process.platform) {
     return platform === 'win32' ? 'npx.cmd' : 'npx';
 }
+/**
+ * @implements A-SPEC-580
+ * The npm twin: the recovery commands doctor emits (`npm install-scripts approve`, `npm rebuild`)
+ * hit the same `.ps1` shim on Windows (measured 2026-09-09: npm.ps1 blocked, npm.cmd runs).
+ */
+function npmBin(platform = process.platform) {
+    return platform === 'win32' ? 'npm.cmd' : 'npm';
+}

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/failed-test-names.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+/** How many names a refusal lists before it counts the rest. */
+export declare const FAILED_NAME_CAP = 10;
+/**
+ * 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.
+ */
+export declare function failedTestNames(output: string): string[];