@holmes-lab/holmes-kit 0.19.0 → 0.19.3

package/CHANGELOG.md

@@ -5,6 +5,126 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.19.3] - 2026-09-10
+
+`doctor` told every third-party install its SQLite binding was missing while it sat on disk. No API change.
+
+### Fixed
+- **A false FAIL on the default install layout** (REQ-583). `gatherNativeEvidence` located
+  `better-sqlite3` by joining `packageRoot/node_modules/better-sqlite3`, and npm HOISTS
+  dependencies to the project root — so for a normal install at
+  `<proj>/node_modules/@holmes-lab/holmes-kit` the joined path never existed. Measured against the
+  published 0.19.2: the binding was present, `require('better-sqlite3')` executed a `:memory:`
+  query, and `doctor` still reported `no binary`. Hoisting is npm's default, which made this the
+  default experience of a correct install. The package directory is now RESOLVED
+  (`require.resolve('<name>/package.json', { paths: [root] })`) — Node's own rule, so hoisted,
+  nested and linked layouts all answer correctly, and a genuinely absent dependency still fails.
+  Its sibling — the `node version` check reading `engines.node` — carried the same join and moved
+  with it; it had been reporting `engines.node=(unknown)` for the same reason.
+- **The release gate ran the suite in the operator's environment** (REQ-582). `npm publish`
+  refused a green tree: `verify-release.js` called `npm test` with the shell's `HOLMES_APPROVAL`,
+  which the spawned-hook parity test (A-SPEC-338) legitimately reacts to — the spawned child
+  inherits the token while its in-process twin is handed `{approval: undefined}`. The gate now runs
+  under `cleanTestEnv`, the same scrub `test_run` uses (borrowed, never copied), and refuses to
+  proceed unscrubbed if it cannot load it. It also names the failing tests instead of saying only
+  "red" — finding out which test had failed previously cost two extra full-suite runs.
+
+- **A live session could block its own publish** (REQ-583). The `APPEND_ONLY_GOVERNANCE` list that
+  tells the release gate which dirty files are governance churn rather than unshipped code held
+  only the approval queue and provenance — while REQ-564/566/569/578 added `session-context`,
+  `impact-advisories`, `anchor-density` and `cycle-observations`, and `test-outcomes` was promoted
+  to tracking. Measured: `npm publish` refused because one `session-context` line was appended
+  between two `git status` snapshots inside the tree-untouched assertion, and the same list guards
+  the dirty-tree check a user meets first. The list now follows the ledgers, and a test pins that
+  nothing which ships (`src/`, `dist/`, the manifest, specs) is ever excused.
+
+### Verified against the published package
+- Installed `@holmes-lab/holmes-kit@0.19.2` from the registry into a clean project, applied this
+  fix, and re-diagnosed from an unrelated working directory: **0 FAIL**, three-harness handshakes
+  (claude / codex / antigravity) all PASS on the version-pinned npx wiring, `target wiring — 3
+  holmes hook(s) resolve to this install`, and `better-sqlite3 — loads and executes against
+  :memory:`.
+
+## [0.19.2] - 2026-09-10
+
+Wiring diagnosis no longer depends on where you run it. No API change.
+
+### Fixed
+- **`doctor` gave opposite verdicts for the same wiring depending on the directory it was run
+  from** (REQ-581). A relative executable path in a wiring file is resolved by Node against
+  `process.cwd()`, and a relative path is the CONVENTION here — `.mcp.json` has always carried
+  `bin/holmes-mcp.js`. Measured: the same project under the same `--target` read
+  `PASS codex wiring` from the repository root and `FAIL — points at a missing file` from `/tmp`,
+  with the fix line telling the operator to re-init a wiring that was never wrong. All four
+  affected checks (`mcp wiring spawn`, `codex wiring`, and the `wiringHandshakeChecks` that cover
+  all three harnesses) now resolve against the TARGET project, and the handshake launches the
+  server FROM that project — the way a harness actually starts it. Absolute wirings (antigravity's)
+  are returned untouched, and a path that is genuinely missing still fails. The message keeps the
+  string exactly as written in the wiring file: what an operator must fix is that string, not our
+  arithmetic.
+- **The same wiring could read PASS from one check and FAIL from its sibling.** Measured on a
+  third-party tarball install: `claude wiring handshake` passed while `mcp wiring spawn` failed on
+  the identical `npx` command, because only one of the two spawn paths had been moved. Both now
+  launch from the target.
+
+### Verified on a third-party install (macOS, npm 11.17.0, Node 26.5.1)
+- Tarball installed into a clean project: `better-sqlite3` binding present, `:memory:` query ok.
+- With install scripts blocked (`--ignore-scripts`, the npm 12 condition): the CLI still starts,
+  `init` still wires, the MCP server still answers — and `doctor` names the cause and prints a
+  recovery command that works verbatim (`npm rebuild better-sqlite3 --foreground-scripts`).
+- Diagnosed from an unrelated working directory with the consumer's own CLI: claude / codex /
+  antigravity handshakes 3/3 PASS, `target wiring — 3 holmes hook(s) resolve to this install`.
+
+### Corrected from 0.19.1's notes
+- 0.19.1 recorded that `codexMcpBlock` "writes Windows backslash paths into `config.toml`
+  unescaped". Re-measured: it does not. `tomlStr` escapes `\` correctly and the write→read
+  round-trip returns `C:\Users\name\proj\bin\holmes-mcp.js` byte-identical (pure functions, so
+  the result is platform-independent). The `doctor-wiring-handshake` failure seen on a Windows
+  checkout is therefore unexplained by escaping — and is a candidate instance of the cwd defect
+  fixed above, which is a HYPOTHESIS for the next Windows run, not a conclusion.
+
+## [0.19.1] - 2026-09-10
+
+Windows install hardening, measured on Windows 11 / npm 12.0.1 / Node 24.19.0. No API change.
+
+### Fixed
+- **npm 12 skipped `better-sqlite3`'s install script and nothing said so** (REQ-579). npm ≥ 12
+  (and npm 11.19+) blocks dependency install scripts unless the root `package.json` approves
+  them; `npm ci` then succeeds with no `better_sqlite3.node`, and every SQLite-backed feature
+  fails on first use. `package.json` now declares `allowScripts: { "better-sqlite3@12.11.1": true }`
+  — the ONE dependency that needs its script, pinned to the lockfile version so a bump forces a
+  fresh review (a test goes red until the pin is updated). The 8 tree-sitter packages are
+  deliberately not approved: measured, they load from their shipped `prebuilds/` with the script
+  blocked. Older npm 11 ignores the field.
+- **doctor misdiagnosed every missing SQLite binary as an ABI mismatch** (REQ-580). The
+  `better-sqlite3` check now judges from evidence — binary present or not, the load error's
+  wording, the npm major, the governing `allowScripts`, the install layout (repository / project
+  dependency / global / npx), and on Windows the toolchain and a spaced path — and names the
+  cause: `scripts-blocked`, `abi-mismatch`, `build-failed`, or `unknown` with the raw error. A
+  prebuilt-download failure is stated as unobservable, never asserted. The fix line is the exact
+  command for that layout; for a global install it targets the dependency
+  (`npm rebuild -g better-sqlite3 --foreground-scripts --allow-scripts=better-sqlite3`), because
+  `rebuild -g @holmes-lab/holmes-kit` dies `EEXIST` re-linking the bin under npm 12 (measured).
+- **doctor's grammar check only resolved packages.** It now parses a source with all 8 grammars
+  (typescript, tsx, python, c-sharp, java, go, rust, cpp) in a fresh child process — in-process
+  parsing is unreliable after another module registry has loaded tree-sitter's native addon.
+- **Windows recovery commands are runnable.** npm commands are emitted as `npm.cmd` on win32
+  (`npmBin`, the twin of `npxBin`), and when a `Restricted`/`AllSigned` PowerShell execution policy
+  is observed the verdict says the `.ps1` shims are blocked and the `.cmd` ones are not.
+
+### Docs
+- `docs/install-guide.md`: npm 12 section, per-layout recovery table, PowerShell policy note,
+  build-failed evidence. `docs/windows-test-plan-2026-09.md`: items E/F/G updated with the
+  2026-09-09/10 measurements and the known Windows-only baseline failures.
+
+### Known, not fixed (recorded honestly)
+- macOS/Linux were not exercised on hardware in this release; their behaviour is covered by
+  platform-injected unit tests and the three-harness parity suite only.
+- `codexMcpBlock` writes Windows backslash paths into `config.toml` unescaped
+  (`doctor-wiring-handshake` fails on a Windows checkout); doctor's `global prefix` check reports a
+  protected `C:\Program Files\nodejs` as writable. Both are pre-existing and tracked as follow-ups.
+  **(The escaping half of this was re-measured in 0.19.2 and does not reproduce — see that entry.)**
+
 ## [0.19.0] - 2026-09-08
 
 ### Added

package/dist/.build-id

@@ -1 +1 @@
-0043954-mtspy09e
+fb773a8-mtug045o

package/dist/holmes/cli/agents.d.ts

@@ -62,6 +62,28 @@ export declare function antigravityHookCommand(scriptPath: string): string;
 /** win32-only, best-effort: a spaced path becomes its 8.3 short name (no spaces); anything else — or
  *  any lookup failure — returns the input unchanged. */
 export declare function shortPathIfSpaced(p: string): string;
+export declare const MANAGED_BEGIN = "<!-- holmes-kit:managed:begin -->";
+export declare const MANAGED_END = "<!-- holmes-kit:managed:end -->";
+/**
+ * @implements A-SPEC-576.2
+ * The regeneration that keeps what it did not write.
+ *
+ * Measured cause: `init` rewrote AGENTS.md from the template, deleting the ADR-018 parity rule a
+ * commit had added the day before — and said nothing, so the loss was found weeks later by grep.
+ * Generated text now lives inside a MANAGED BLOCK; everything outside it belongs to the person
+ * whose repository this is.
+ *
+ * PURE, and it takes the whole file rather than a path: the caller reads `before` during init's
+ * COMPUTE phase, so a dry-run predicts the same bytes the real run writes (A-SPEC-190 §9).
+ *
+ * `preserved` is the report, not a courtesy. A run that moved something and returned an empty list
+ * would be the same silent loss in a new costume.
+ */
+export declare function mergeAgentsMd(existing: string | null, generated: string): {
+    content: string;
+    preserved: string[];
+    note: string | null;
+};
 /**
  * 이 하네스에 써야 할 파일들. **쓰지는 않는다** — 무엇을 쓸지만 말한다.
  *

package/dist/holmes/cli/agents.js

@@ -33,9 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CODEX_MARKETPLACE = exports.CODEX_PLUGIN_DIR = exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
+exports.MANAGED_END = exports.MANAGED_BEGIN = exports.CODEX_MARKETPLACE = exports.CODEX_PLUGIN_DIR = exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
 exports.antigravityHookCommand = antigravityHookCommand;
 exports.shortPathIfSpaced = shortPathIfSpaced;
+exports.mergeAgentsMd = mergeAgentsMd;
 exports.agentFiles = agentFiles;
 exports.agentLinks = agentLinks;
 // @implements A-SPEC-442
@@ -197,6 +198,80 @@ ${enforced
     ? `Gates are **enforced**. Tool calls that write un-anchored code or target unapproved specifications will be denied. Unresolved critical findings block completion.`
     : `This harness does not have measured **hook enforcement points**. Holmes-Kit provides tools and guidance here without active gate blocking.`}
 `;
+exports.MANAGED_BEGIN = '<!-- holmes-kit:managed:begin -->';
+exports.MANAGED_END = '<!-- holmes-kit:managed:end -->';
+const PRESERVED_NOTE = '<!-- kept from this file by holmes-kit init — holmes-kit does not write below this line -->';
+/**
+ * @implements A-SPEC-576.2
+ * The regeneration that keeps what it did not write.
+ *
+ * Measured cause: `init` rewrote AGENTS.md from the template, deleting the ADR-018 parity rule a
+ * commit had added the day before — and said nothing, so the loss was found weeks later by grep.
+ * Generated text now lives inside a MANAGED BLOCK; everything outside it belongs to the person
+ * whose repository this is.
+ *
+ * PURE, and it takes the whole file rather than a path: the caller reads `before` during init's
+ * COMPUTE phase, so a dry-run predicts the same bytes the real run writes (A-SPEC-190 §9).
+ *
+ * `preserved` is the report, not a courtesy. A run that moved something and returned an empty list
+ * would be the same silent loss in a new costume.
+ */
+function mergeAgentsMd(existing, generated) {
+    const block = exports.MANAGED_BEGIN + '\n' + (generated.endsWith('\n') ? generated : generated + '\n') + exports.MANAGED_END + '\n';
+    if (existing === null || existing === '')
+        return { content: block, preserved: [], note: null };
+    const b = existing.indexOf(exports.MANAGED_BEGIN);
+    const e = existing.indexOf(exports.MANAGED_END);
+    if (b !== -1 && e > b) {
+        // The ordinary case once a file has been through here: swap the block, and do not touch a
+        // single byte on either side of it.
+        const body = generated.endsWith('\n') ? generated : generated + '\n';
+        return {
+            content: existing.slice(0, b) + exports.MANAGED_BEGIN + '\n' + body + exports.MANAGED_END + existing.slice(e + exports.MANAGED_END.length),
+            preserved: [],
+            note: null,
+        };
+    }
+    // LEGACY: a file written before the markers existed — every AGENTS.md in the field today. Its
+    // lines are compared to the generated ones, and whatever the generator never wrote is carried
+    // below the block. Line terminators are kept as read, so a CRLF checkout stays CRLF.
+    const known = new Set(generated.split(/\r?\n/).map((l) => l.trim()).filter((l) => l !== ''));
+    const lines = existing.split(/(?<=\n)/);
+    const runs = [];
+    let run = [];
+    let pendingBlanks = [];
+    for (const line of lines) {
+        const t = line.trim();
+        if (t === '') {
+            if (run.length > 0)
+                pendingBlanks.push(line);
+            continue;
+        }
+        if (known.has(t)) {
+            run = closeRun(runs, run);
+            pendingBlanks = [];
+            continue;
+        }
+        // A blank line INSIDE a run is part of it; blanks trailing a run are not.
+        run.push(...pendingBlanks, line);
+        pendingBlanks = [];
+    }
+    closeRun(runs, run);
+    if (runs.length === 0)
+        return { content: block, preserved: [], note: null };
+    const preserved = runs.map((r) => (r.find((l) => l.trim() !== '') ?? '').trim());
+    return {
+        content: block + '\n' + PRESERVED_NOTE + '\n\n' + runs.map((r) => r.join('')).join('\n'),
+        preserved,
+        note: `kept ${runs.length} section(s) this generator did not write`,
+    };
+}
+/** Close the current run into `runs` (dropping an empty one) and hand back a fresh one. */
+function closeRun(runs, run) {
+    if (run.length > 0)
+        runs.push(run);
+    return [];
+}
 /**
  * 이 하네스에 써야 할 파일들. **쓰지는 않는다** — 무엇을 쓸지만 말한다.
  *

package/dist/holmes/cli/approve.js

@@ -78,7 +78,12 @@ const DEFAULT_TTL_MINUTES = 30;
 const MAX_TTL_MINUTES = 7 * 24 * 60;
 const DEFAULT_RATIONALE = 'approved via holmes-kit approve';
 const findPending = (root, id) => {
-    const state = (0, approval_queue_1.readQueue)(root);
+    // @implements A-SPEC-576.1 — RESOLUTION reads everything; the human's LIST reads decisions only.
+    // The inbox filter hides gate refusals from the screen, but `approve <id>` must still find one:
+    // the fallback below only holds entries written after the REQ-563 split, so anything refused
+    // before it lives in the queue alone. Filtering here would cut the out-of-band approval path the
+    // deny message itself promises.
+    const state = (0, approval_queue_1.readQueue)(root, { includeAllKinds: true });
     const pending = state.pending.find((p) => p.id === id);
     if (pending)
         return { entry: pending, state };

package/dist/holmes/cli/doctor.d.ts

@@ -1,3 +1,4 @@
+import { NativeEvidence } from './native-deps';
 import { type SemanticTier } from '../semantic/tier';
 /**
  * `holmes-kit doctor` — install diagnostics.
@@ -82,6 +83,43 @@ export declare function prefixVerdict(input: PrefixProbe): {
     detail: string;
     fix?: string;
 };
+/**
+ * @implements A-SPEC-580
+ * Parse a trivial source with every grammar, in a child node whose module resolution starts at
+ * `packageRoot`. `parsed` counts typescript and tsx separately (8 for the 7 grammar packages).
+ */
+export declare function grammarProbe(packageRoot: string): {
+    parsed: number;
+    failed: string[];
+    error?: string;
+};
+/**
+ * @implements A-SPEC-580
+ * Everything observable about the better-sqlite3 install, gathered for `nativeVerdict`. Each probe
+ * is independent and optional: a spawn that fails leaves its field `undefined` (not observed), and
+ * the verdict says so rather than treating silence as evidence.
+ *
+ * Which package.json holds the approval policy depends on the layout: this checkout's own for a
+ * repository run, the PROJECT's (three levels up from node_modules/@holmes-lab/holmes-kit) for a
+ * local dependency. A global or npx install has no project package.json that npm consults, so its
+ * coverage is `uncovered` by construction and the remedy is the per-command `--allow-scripts`.
+ */
+/**
+ * Where an installed dependency actually lives, asked of NODE rather than guessed from a path.
+ *
+ * 0.19.2 shipped a false FAIL to every third-party consumer: it built the directory by joining
+ * `packageRoot/node_modules/<name>`, and npm HOISTS dependencies to the project root, so for an
+ * install at `<proj>/node_modules/@holmes-lab/holmes-kit` the joined path never existed — while the
+ * binding sat at `<proj>/node_modules/better-sqlite3` and loaded fine. Hoisting is npm's default,
+ * which made the false verdict the default path of a normal install.
+ *
+ * `package.json` is the resolution target because we want the DIRECTORY, not the entry point: a
+ * package whose `exports` hides its main still resolves its own manifest by convention. A failure
+ * to resolve returns null, and the caller reports "absent" exactly as before — the repair changes
+ * how we look, never whether a real miss is reported.
+ */
+export declare function resolveDepDir(fromRoot: string, name: string): string | null;
+export declare function gatherNativeEvidence(packageRoot: string): NativeEvidence;
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 export declare function probeEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Seam for the gate probe's child process. Default is a real `spawnSync`; tests inject a fake. */
@@ -94,6 +132,18 @@ export interface ProbeRunner {
         stderr?: string;
     };
 }
+/**
+ * Where a wiring's executable actually is, judged from the PROJECT rather than from the caller.
+ *
+ * Measured 2026-09-10: the same `.codex/config.toml` under the same `--target` read PASS from the
+ * repository root and FAIL from `/tmp`, because a relative arg is resolved by Node against
+ * `process.cwd()`. A relative arg is the CONVENTION here — `.mcp.json` has always carried
+ * `bin/holmes-mcp.js` — so the verdict was decided by where the person diagnosing stood.
+ *
+ * An absolute arg is returned untouched: agy's wiring is absolute and must not move. An empty arg
+ * stays empty — resolving it would conjure the target directory itself into a "file that exists".
+ */
+export declare function resolveWiringPath(target: string, arg: string): string;
 export declare function runDoctor(packageRoot: string, target?: string, opts?: DoctorOptions, extraChecks?: Check[]): Promise<Check[]>;
 /**
  * Drive a real MCP stdio handshake: initialize -> initialized -> tools/list, with a timeout.
@@ -101,7 +151,7 @@ export declare function runDoctor(packageRoot: string, target?: string, opts?: D
  * and closes stdin makes the server exit before answering (a false FAIL this check produced on its
  * very first run against a healthy server).
  */
-export declare function wiringSpawnCheck(command: string, args: string[], timeoutMs?: number, platform?: NodeJS.Platform): Promise<Check>;
+export declare function wiringSpawnCheck(command: string, args: string[], timeoutMs?: number, platform?: NodeJS.Platform, cwd?: string): Promise<Check>;
 /**
  * Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
  * AND has git. Absence or a hook without our signature is a WARN carrying the install command —