@holmes-lab/holmes-kit 0.19.0 → 0.19.2

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

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

package/dist/holmes/review/run-replay.d.ts

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

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

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.uncitedDiffs = uncitedDiffs;
 exports.runReplay = runReplay;
 exports.semanticCaseRanking = semanticCaseRanking;
 // @implements A-SPEC-346
@@ -41,6 +42,7 @@ exports.semanticCaseRanking = semanticCaseRanking;
 // @implements A-SPEC-349
 // @implements A-SPEC-378
 // @implements A-SPEC-402
+const baseline_arm_1 = require("./baseline-arm");
 const fs = __importStar(require("node:fs"));
 const node_child_process_1 = require("node:child_process");
 const os = __importStar(require("node:os"));
@@ -79,6 +81,17 @@ const dense_retrieval_1 = require("./dense-retrieval");
 const explore_1 = require("../assoc/explore");
 const temporal_prior_1 = require("./temporal-prior");
 const commit_text_1 = require("./commit-text");
+/**
+ * @implements A-SPEC-578.7
+ * The paired differences on the UNCITED axis, ready for `pairedPower`.
+ *
+ * Filtering here rather than while measuring is deliberate: observation records every case, and the
+ * axis is chosen at analysis time. A harness that only recorded what it currently cares about could
+ * never answer a question asked later.
+ */
+function uncitedDiffs(rows) {
+    return rows.filter((r) => r.uncited).map((r) => r.productRecall10 - r.baselineRecall10);
+}
 /**
  * Run the point-in-time replay against ANY corpus.
  *
@@ -258,6 +271,23 @@ async function runReplay(corpus, limit, opts = {}) {
                     return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
                 })();
                 const ranked = result.candidates.map((x) => x.file);
+                // @implements A-SPEC-578.7 — the power arm. Both recalls come from what already exists:
+                // the product's from `ranked` (never recomputed — recomputing is how a benchmark ends up
+                // scoring a pipeline the product does not ship, measured once already in A-SPEC-573.3),
+                // the baseline's from `rankBaseline`, the no-graph floor built in A-SPEC-356 and never
+                // called until now. The `uncited` predicate is the PRODUCT'S — `citationsIn` — so the axis
+                // is defined the same way here and there.
+                if (opts.pairedDump !== undefined && c.files.length > 0) {
+                    const truth = new Set(c.files);
+                    const recallOf = (files) => files.slice(0, 10).filter((f) => truth.has(f)).length / truth.size;
+                    opts.pairedDump({
+                        commit: c.commit,
+                        uncited: (0, localize_1.citationsIn)(c.subject, new Set(specs.map((sp) => sp.id))).cited.length === 0,
+                        productRecall10: recallOf(ranked),
+                        baselineRecall10: recallOf((0, baseline_arm_1.rankBaseline)(c.subject, scanned, 10).map((h) => h.file)),
+                        truth: truth.size,
+                    });
+                }
                 // @implements A-SPEC-469 — the union scores what a caller actually RECEIVES as the impact
                 // answer, and that surface is now the graded rankedImpact (the closure stays gate-facing).
                 const impacted = (result.impacts?.rankedImpact ?? []).map((r) => r.file);

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

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

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

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

package/docs/install-guide.md

@@ -91,19 +91,63 @@ Your npm metadata cache predates the release — measured minutes after publishi
 registry already listed the version while a default-cache install still refused it. Add
 `--prefer-online`, or retry in a few minutes.
 
+### npm 12: `better-sqlite3` has no binary and nothing failed
+
+npm 12 (and npm ≥ 11.19) **blocks dependency install scripts by default** and skips them
+silently: `npm ci` exits 0, `better-sqlite3` never runs `prebuild-install`, and the first
+`require` dies with "Could not locate the bindings file". Measured 2026-09-09 (Windows 11,
+npm 12.0.1, Node 24.19.0). `npx holmes-kit doctor` names this cause as `scripts-blocked` and prints
+the commands below; do not reinstall — a reinstall reproduces the same state.
+
+Only **one** package needs its script: `better-sqlite3`. The 8 tree-sitter packages are also
+listed as blocked, but they load from their shipped `prebuilds/` without the script (measured on
+all 8), so they are deliberately NOT approved. This repository's `package.json` therefore carries
+
+```json
+"allowScripts": { "better-sqlite3@12.11.1": true }
+```
+
+pinned to the lockfile version, so a dependency bump forces a fresh review (a test fails until the
+pin is updated). Recovery, by how you installed — on Windows use the `.cmd` spellings (see below):
+
+| Layout | Commands |
+|---|---|
+| A project that depends on holmes-kit | `npm install-scripts approve better-sqlite3@12.11.1` then `npm rebuild better-sqlite3 --foreground-scripts` (from the project root; this writes the pin into YOUR package.json) |
+| This repository checkout | already approved — `npm rebuild better-sqlite3 --foreground-scripts` if the binary is missing |
+| Global (`npm install -g`) | `npm rebuild -g better-sqlite3 --foreground-scripts --allow-scripts=better-sqlite3` — a per-command flag scoped to one package; no npm config is changed. Target the dependency: `rebuild -g @holmes-lab/holmes-kit` re-links the bin and dies `EEXIST` under npm 12 (measured). If this fails `EPERM` under `C:\Program Files\nodejs`, your prefix is protected — see "Before `npm install -g`" above |
+| Bare `npx` | not repairable in place — do a local install and use the first row |
+
+Never use `--dangerously-allow-all-scripts` or a global `allow-scripts` config: the point of the
+policy is that only the reviewed package runs code at install time. Older npm 11 (measured 11.6.2)
+ignores the `allowScripts` field and runs scripts as before; npm 11.19 honours it exactly like 12.
+
+### Windows: `npm`/`npx` are blocked by the PowerShell execution policy
+
+`npm`, `npx` and `holmes-kit` resolve to `.ps1` shims first, and a `Restricted`/`AllSigned`
+policy refuses them (PSSecurityException). The `.cmd` shims always run: `npm.cmd`, `npx.cmd`.
+doctor emits `.cmd` commands on Windows and appends the policy note when it can observe a
+blocking policy. Do not change the execution policy to fix this.
+
 ### `better-sqlite3` fails to build
 
 The one dependency that may need a toolchain. The 8 tree-sitter grammars ship prebuilt binaries
 (`darwin-arm64`, `darwin-x64`, `linux-x64`, `win32-x64`) and compile nothing; `better-sqlite3`
 downloads a prebuild at install time and **falls back to compiling** when none matches your
-platform and Node ABI. If it compiles, you need:
+platform and Node ABI. doctor reports this as `build-failed` — with the approval in place, the
+script ran and left no binary — and names what it can observe on Windows (Python on PATH, Visual
+Studio C++ Build Tools, a space in the install path). It cannot observe a failed prebuild
+download; rerun with `--foreground-scripts` to see the script's own output. If it compiles, you
+need:
 
 | Platform | Toolchain |
 |---|---|
-| Windows | Visual Studio Build Tools (C++ workload) |
+| Windows | Visual Studio Build Tools (C++ workload) + Python 3 on PATH; prefer an install path without spaces |
 | macOS | Xcode Command Line Tools (`xcode-select --install`) |
 | Alpine | `apk add --no-cache python3 make g++` |
 
+A binary that exists but fails with `NODE_MODULE_VERSION` was built for another Node — doctor
+calls that `abi-mismatch`; rebuild against the Node you run.
+
 ### `spawn sh ENOENT` during a git-URL install
 
 `npm i -g git+ssh://…` is not a supported path: npm 11 clones the repository into its cache and
@@ -117,15 +161,20 @@ npx holmes-kit doctor        # local install
 holmes-kit doctor            # global install
 ```
 
-Expect `10 pass, 1 warn, 0 fail` on a healthy install. The lines that matter most:
+Expect `0 fail` on a healthy install (a few `warn` lines are normal — measured `12 pass, 4 warn,
+0 fail` on a Windows source checkout). The lines that matter most:
 
 - `global prefix` — whether `-g` would work on this machine, and the remedy if not
-- `tree-sitter grammars` / `better-sqlite3` — whether the native modules actually load
+- `tree-sitter grammars` — every grammar actually PARSES in a fresh process (`8 grammars parse`)
+- `better-sqlite3` — loads and runs a `:memory:` query; on FAIL the detail names the cause
+  (`scripts-blocked`, `abi-mismatch`, `build-failed`, or `unknown` with the raw error) and the fix
+  is the exact command for your install layout
 
 ## What we deliberately do NOT do
 
 | Idea | Why not |
 |---|---|
-| A `postinstall` script that prints guidance | Triggers npm 11's `allow-scripts` warning and forfeits this package's current property of running no install scripts at all |
+| A `postinstall` script that prints guidance | Under npm 12 it would be blocked like any other install script, and it forfeits this package's property of running no install scripts of its own |
+| Approving the tree-sitter grammars in `allowScripts` | Measured unnecessary — they load from shipped prebuilds — and every extra approval is code that runs at install time |
 | Recommending `npx @holmes-lab/holmes-kit init` with no install | `init` writes wiring with absolute paths; under bare `npx` those point into the npx cache and break when it is pruned |
 | Fixing your npm prefix from inside the package | A package rewriting your npm configuration is exactly the supply-chain behaviour this guide warns about |

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",
@@ -85,5 +85,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.11.1": true
   }
 }