@holmes-lab/holmes-kit 0.19.0 → 0.19.2

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

@@ -490,6 +490,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
             survivors: import("../spec/kills").Mutation[];
         };
     } | {
+        calibrationClosed?: string[] | undefined;
         baselineRecorded?: string | undefined;
         scopeFallback?: "full" | undefined;
         tier: import("../rtm/test-scope").RegressionTier;
@@ -518,6 +519,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         changedFiles?: string[];
     }): Promise<MaintenanceAnalysis & {
         persistedTo?: string;
+        bounded?: boolean;
     }>;
     maintenance_outcome(a: {
         root: string;

package/dist/holmes/mcp/handlers.js

@@ -2367,6 +2367,9 @@ function makeRawHandlers(store, opts) {
             // Record ONLY an actually-executed, GREEN run (review C4/C7): a red suite must not stand as
             // coverage evidence at the moment the code is broken, and a no-op run must not overwrite a real
             // record with a dishonest `passed: true` over an empty result.
+            // @implements A-SPEC-578.4 — read BEFORE the write below replaces it: the calibration window
+            // is "since the previous evidence run", and this line is the only moment that value exists.
+            const previousEvidenceTs = (0, test_evidence_1.readTestEvidence)(root)?.ts;
             const verified = (0, baseline_1.shouldRecordBaseline)(result);
             if (verified) {
                 (0, test_evidence_1.writeTestEvidence)(root, { ts: new Date().toISOString(), head, tier: testScope.tier, passed: true, executedByAspec });
@@ -2382,6 +2385,19 @@ function makeRawHandlers(store, opts) {
             // actually executed and passed. A red or skipped run must never become the reference point for
             // "since the last verified state" — that would silently narrow every later scope against a
             // state nobody verified.
+            // @implements A-SPEC-578.4 — close the calibration loop on real work.
+            // The window is the PREVIOUS evidence run's timestamp, read before this run overwrote it —
+            // an analysis older than that belonged to a previous slice, and attributing today's changes
+            // to it would be contamination rather than measurement. Its own try: an observation that
+            // could change `passed` would be a gate wearing another name.
+            let calibrationClosed;
+            try {
+                const closed = (0, maintenance_evidence_1.closeOpenArtifacts)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), { files: changedFiles }, new Date().toISOString(), previousEvidenceTs).closed;
+                if (closed.length > 0)
+                    calibrationClosed = closed;
+            }
+            catch { /* the loop is observation; it never touches the verdict */ }
+            // @implements A-SPEC-128
             let baseline;
             if (verified) {
                 baseline = a.mark ?? DEFAULT_BASELINE;
@@ -2393,7 +2409,8 @@ function makeRawHandlers(store, opts) {
                 ranFiles: result.ranFiles, executedByAspec, tail: result.tail,
                 // @implements A-SPEC-130 — the remediation rides in the answer: these are the files to anchor.
                 unresolvedFiles: testScope.unresolvedFiles,
-                changeSource, ...(scopeFallback ? { scopeFallback } : {}), ...(baseline ? { baselineRecorded: baseline } : {}) };
+                changeSource, ...(scopeFallback ? { scopeFallback } : {}), ...(baseline ? { baselineRecorded: baseline } : {}),
+                ...(calibrationClosed ? { calibrationClosed } : {}) };
         },
         async issue_localize(a) {
             assertSpecStoreReachable('issue_localize', store, a.root); // @implements A-SPEC-419
@@ -2643,9 +2660,19 @@ function makeRawHandlers(store, opts) {
                         if (digest)
                             fileDigests[file] = digest;
                     }
+                    // The artifact takes the WHOLE analysis, never the bounded one below: a file has no
+                    // context window, and the calibration that scores this prediction must score what the
+                    // product actually predicted.
                     result.persistedTo = (0, maintenance_evidence_1.writeArtifact)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), (0, maintenance_evidence_1.artifactFrom)(analysis, new Date().toISOString(), fileDigests));
                 }
-                return result;
+                // @implements A-SPEC-578.5 — the response, and only the response, is bounded. Measured
+                // 2026-09-09: the full shape is 187,174 characters (~47k tokens) and the harness refuses
+                // it, which is why AGENTS.md step 3 had never once been obeyed with `persist: true`.
+                // `persistedTo` rides along so the caller knows where the whole thing is.
+                const bounded = (0, maintenance_analyze_1.boundAnalysis)(result);
+                if (JSON.stringify(bounded).length !== JSON.stringify(result).length)
+                    bounded.bounded = true;
+                return bounded;
             }
             finally {
                 graph.close();

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

@@ -444,3 +444,40 @@ export declare function unquoteGitPath(line: string): string;
  * reproduce and compare an analysis from the exact same captured inputs.
  */
 export declare function analyzeMaintenance(input: MaintenanceAnalysisInput): MaintenanceAnalysis;
+/**
+ * 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.
+ */
+export declare const ANALYZE_LIST_CAP = 10;
+/** Characters one listed item keeps. */
+export declare const ANALYZE_TEXT_CAP = 400;
+/**
+ * @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.
+ */
+export declare function boundAnalysis(a: MaintenanceAnalysis): MaintenanceAnalysis;

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
@@ -1048,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/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[];