@holmes-lab/holmes-kit 0.19.2 → 0.19.3

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.

package/dist/.build-id

@@ -1 +1 @@
-e63e589-mtuemhhb
+fb773a8-mtug045o

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

@@ -104,6 +104,21 @@ export declare function grammarProbe(packageRoot: string): {
  * 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;

package/dist/holmes/cli/doctor.js

@@ -38,6 +38,7 @@ exports.globalInstallDir = globalInstallDir;
 exports.npmCliEntry = npmCliEntry;
 exports.prefixVerdict = prefixVerdict;
 exports.grammarProbe = grammarProbe;
+exports.resolveDepDir = resolveDepDir;
 exports.gatherNativeEvidence = gatherNativeEvidence;
 exports.probeEnv = probeEnv;
 exports.resolveWiringPath = resolveWiringPath;
@@ -241,13 +242,39 @@ function observe(file, args) {
  * 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`.
  */
+// @implements A-SPEC-583.1
+/**
+ * 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.
+ */
+function resolveDepDir(fromRoot, name) {
+    if (name === '')
+        return null;
+    try {
+        return path.dirname(require.resolve(`${name}/package.json`, { paths: [fromRoot] }));
+    }
+    catch {
+        return null;
+    }
+}
 function gatherNativeEvidence(packageRoot) {
     const name = 'better-sqlite3';
-    const pkgDir = path.join(packageRoot, 'node_modules', name);
-    const bindingPresent = fs.existsSync(path.join(pkgDir, 'build', 'Release', 'better_sqlite3.node'));
+    // @implements A-SPEC-583.1 — resolved, not joined. A hoisted install is the npm default.
+    const pkgDir = resolveDepDir(packageRoot, name);
+    const bindingPresent = pkgDir !== null && fs.existsSync(path.join(pkgDir, 'build', 'Release', 'better_sqlite3.node'));
     let packageVersion = '(unknown)';
     try {
-        packageVersion = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8')).version ?? packageVersion;
+        packageVersion = JSON.parse(fs.readFileSync(path.join(pkgDir ?? '', 'package.json'), 'utf8')).version ?? packageVersion;
     }
     catch { /* not installed */ }
     let loadError;
@@ -354,7 +381,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     // 2. Node version vs better-sqlite3's declared range (WARN only — a mismatch still often works).
     let sqliteRange = '(unknown)';
     try {
-        sqliteRange = JSON.parse(fs.readFileSync(path.join(packageRoot, 'node_modules', 'better-sqlite3', 'package.json'), 'utf8')).engines?.node ?? '(none)';
+        // @implements A-SPEC-583.1 — the SIBLING of the evidence lookup; both move together.
+        sqliteRange = JSON.parse(fs.readFileSync(path.join(resolveDepDir(packageRoot, 'better-sqlite3') ?? '', 'package.json'), 'utf8')).engines?.node ?? '(none)';
     }
     catch { /* not resolvable from here */ }
     add('node version', 'PASS', `node ${process.version}; better-sqlite3 declares engines.node=${sqliteRange}`, 'If a native module fails to load after a Node major upgrade, reinstall holmes-kit.');

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "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",