@holmes-lab/holmes-kit 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.3.3] - 2026-08-31
+
+Docs-only: the README the npm page shows catches up with 0.3.x.
+
+### Changed
+
+- README rewritten to 0.3.x: the 3-tier semantic layer (consent ladder + measured recalls), the
+  graded impact surface and its pre-registered baselines, the measured-not-claimed grading against
+  the modeled-human band (independent blind-judge P 0.727 = 81% of the band), approval-dialog
+  expiry visibility, the corrected Codex wiring path (`.codex/config.toml`), the Windows row
+  corrected from a CI claim to the 2026-08-31 field validation, a zero-install `npx` one-shot row,
+  and the stale-global-shim shadowing warning (field-measured dual global roots on Windows).
+  No code changes.
+
+<!-- @implements A-SPEC-209 -->
+## [0.3.2] - 2026-08-31
+
+Windows doctor unbroken: the wiring-handshake checks can now actually run the wiring they judge.
+
+### Fixed
+
+- **doctor wiring handshake on Windows** (A-SPEC-499.1): the four wiring checks (claude / codex /
+  antigravity handshake + mcp wiring spawn) spawned `npx` directly, which on win32 is `npx.cmd`
+  and cannot be executed by a plain spawn — every check died `spawn npx ENOENT` on a correctly
+  wired target (field-measured on 0.3.1). A pure platform adapter now reroutes execution through
+  `cmd.exe /d /s /c` (whitespace-bearing tokens quoted — space-in-username installs included);
+  posix spawn arguments are value-identical to before.
+- **ENOENT prescription**: a command the OS cannot find no longer gets "Re-run `holmes-kit init`"
+  — re-initing into the identical failure forever was the measured loop. It now says the command
+  could not be resolved (PATH/platform) and to try it in a shell; genuine stale-wiring failures
+  keep the re-init wording byte-for-byte.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.3.1] - 2026-08-31
 

package/README.md

@@ -14,11 +14,15 @@
 
 ---
 
-### 🛡️ Currently Supported Features (v0.1.x Production Features)
+### 🛡️ Currently Supported Features (v0.3.x Production Features)
 
 - 📋 **Requirements & Specification Governance**: Strict **"No Spec, No Code"** enforcement with 4-tier spec chain traceability (`REQ ➔ H-SPEC ➔ A-SPEC ➔ T-SPEC`) and `// @implements A-SPEC-XXX` line 1 code anchors.
+- 🧠 **3-Tier Semantic Layer** *(new in 0.3.0)*: knowledge-graph semantic search with an explicit consent ladder — `none` (default, **zero egress**), `local` (bge-m3, no egress, optional module), `cloud` (gemini-embedding-001, opt-in via `GEMINI_API_KEY`). Measured on 305 traceability cases: recall 0.486 (lexical) → 0.667 (local) → **0.887 (cloud)**; on lexical-zero requests: 0% → 52% → **92%**. Surfaced only additively — rerank, evidence (`semCos`), and `semanticAlternates` — never as a hard filter.
+- 🎯 **Graded Impact Surface** *(new in 0.3.0)*: `rankedImpact` (personalized-PageRank over the spec/code graph) beat its pre-registered naive baseline on **both recall and precision across 3 corpora (×1.6–×17)** — the necessary condition for any better-than-a-person phrasing, measured before claimed.
 - 🐞 **Causal Defect Localization & CPG**: AST Code Property Graph (CPG) & Dataflow Taint reachability analysis across 7 languages (TS/JS, Python, Go, Rust, Java, C/C++, C#).
-- 🧪 **Self-Healing & Diagnostic Doctor**: Automated integrity checks and self-healing auto-fix remediation (`holmes-kit doctor --fix` & `spec_remediate`).
+- 📏 **Measured, Not Claimed** *(new in 0.3.x)*: performance is judged against a pre-registered modeled-human band (R 0.67–0.78 / P ≈0.9±). Current official grade: **band entry on recall; division-of-labor precision 0.727 = 81% of the modeled human — reproduced by an independent context-free judge on a fresh blind window.** No superhuman claims until both metrics exceed the band.
+- 🧪 **Self-Healing & Diagnostic Doctor**: Automated integrity checks and self-healing auto-fix remediation (`holmes-kit doctor --fix` & `spec_remediate`) — wiring-handshake checks run on Windows natively as of 0.3.2.
+- 🔔 **Approval UX** *(new in 0.3.1)*: in-session approval dialogs forewarn their 120s deadline and, on expiry, the refusal says exactly where the decision went (`npx holmes-kit approve` out-of-band queue) — no more silently dead dialogs.
 - 🚦 **CI/CD Governance Gate Runner**: Non-interactive headless CI/CD build gate (`holmes-kit ci`) for GitHub Actions and GitLab CI pipelines.
 - 📊 **Automated RTM & Taint Heatmap**: Interactive standalone HTML/SVG report generation (`generateRtmHeatmap`) for spec coverage and security dataflow reachability.
 - 🤖 **CLI-First AI Harness Matrix**: Native process hook gating for Claude Code, Antigravity CLI (AGY), Codex CLI, and Google Antigravity SDK.
@@ -42,7 +46,7 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
 | :--- | :--- | :--- |
 | 🤖 **Claude Code CLI** | 🥇 Tier 1 (Native) | OS PreToolUse & Stop hooks (`.claude/settings.local.json`), MCP server (`.mcp.json`) |
 | 🚀 **Antigravity CLI (AGY)** | 🥇 Tier 1 (Native) | AGY Hooks (`hooks.json`), MCP config (`.agents/mcp_config.json`), Governance Skills |
-| 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (`.codex/mcp_config.json`), Subshell Isolation Gates |
+| 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (`.codex/config.toml`), plugin-packaged gate hooks (installed via Codex plugin marketplace) |
 | 🧩 **Google Antigravity SDK** | 🥇 Tier 1 (Native) | Autonomous Agent SDK bindings and cryptographic provenance verification |
 
 > **Note**: Holmes-Kit focuses strictly on CLI-based autonomous agents to guarantee 100% deterministic OS hook gating (`deny` enforcement) before file modifications occur.
@@ -69,10 +73,18 @@ Add `-DryRun` to see what it would do without installing. Exit codes: `0` ok / a
 | Which situation are you in? | Privileges | Command |
 |---|---|---|
 | **Using it in one project** (most people) | none | `npm install --save-dev @holmes-lab/holmes-kit` |
+| **Zero-install one-shot** (try it first) | none | `npx -y @holmes-lab/holmes-kit init` — npx fetches and runs, nothing to install beforehand |
 | Company-managed PC / restricted account | none | same — no system directory is touched |
 | CI / container | none | same, plus `--prefer-online` right after a release |
 | CLI across many projects (`-g`) | depends | run `npm config get prefix` first — see below |
 
+**Stale global shadowing** *(field-measured on Windows, 2026-08-31)*: an old global install makes the
+bare `holmes-kit` command run the OLD version while `npx holmes-kit` runs the local one — and
+Windows has TWO global roots (`C:\Program Files\nodejs` and `%APPDATA%\npm`), so `npm uninstall -g`
+against one root can leave a live shim in the other. If `holmes-kit --version` and
+`npx holmes-kit --version` disagree, run `where.exe holmes-kit` (Windows) / `which -a holmes-kit`
+and remove the stale shim; prefer the `npx` form day-to-day.
+
 **Before `npm install -g`**: if `npm config get prefix` names a protected directory
 (`C:\Program Files\nodejs`, `/usr/local`), `-g` dies with `EPERM` **before any package file
 arrives** — no package version can fix that, and elevation is the wrong fix (it runs native
@@ -96,7 +108,7 @@ npx holmes-kit init      # drop the npx prefix if you installed with -g
 ? Select the AI Agent harnesses to wire into this project:
   [X] 🤖 Claude Code          (.claude/settings.local.json, .mcp.json)
   [X] 🚀 Antigravity CLI (AGY) (.agents/mcp_config.json, hooks.json, skills)
-  [ ] 💻 Codex CLI            (.codex/mcp_config.json)
+  [ ] 💻 Codex CLI            (.codex/config.toml)
 ```
 
 ### 3. Verify Health
@@ -181,7 +193,7 @@ Holmes-Kit embeds native AST & Code Property Graph (D-CPG) analyzers to track ca
 | **macOS** | Apple Silicon (arm64) / Intel (x64) | ✅ Tier 1 | macOS 12+ (Full hook enforcement) |
 | **Linux** | x86_64 / arm64 | ✅ Tier 1 | Ubuntu, Debian, Fedora, Arch, RHEL |
 | **Windows (WSL2)** | x86_64 | ✅ Tier 1 | WSL2 Ubuntu/Debian recommended |
-| **Windows Native** | x86_64 | ✅ Tier 1 | Windows 10/11 (Node.js 20+ with C++ build tools). Gate parity verified from CI — see [ADR-015](.ax/decisions/ADR-015_platform-tier-is-decided-by-executed-verification.md) for the graduation criteria and the residual risks (NTFS 8.3 names, reserved device names, 260-char paths) |
+| **Windows Native** | x86_64 | ✅ Tier 1 | Windows 10/11 (Node.js 20+; prebuilt natives, no build tools needed in the common case). **Field-validated 2026-08-31** on a real user machine: registry install, natives (better-sqlite3 + 7 tree-sitter grammars), both OS gates, MCP handshake (30 tools), interactive init TUI, out-of-band approval channel (doctor 25 PASS; the 4 false FAILs it also showed were doctor's own win32 spawn bug, fixed in 0.3.2). See [ADR-015](.ax/decisions/ADR-015_platform-tier-is-decided-by-executed-verification.md) for tier criteria and residual risks (NTFS 8.3 names, reserved device names, 260-char paths; no Windows CI yet) |
 
 > **Runtime Requirement**: Node.js `>= 20.0.0` (LTS recommended)
 >

package/dist/.build-id

@@ -1 +1 @@
-9dd2f60-mthaxwnr
+8c7f0ed-mthde5yw

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

@@ -95,6 +95,13 @@ export interface ProbeRunner {
     };
 }
 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.
+ * Async by necessity — the protocol is a ROUND TRIP, so a spawnSync that writes everything at once
+ * 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 formatChecks(checks: Check[]): string;
 /**
  * Prove that EVERY wired harness can actually start a server, not merely that its file parses.

package/dist/holmes/cli/doctor.js

@@ -39,6 +39,7 @@ exports.npmCliEntry = npmCliEntry;
 exports.prefixVerdict = prefixVerdict;
 exports.probeEnv = probeEnv;
 exports.runDoctor = runDoctor;
+exports.wiringSpawnCheck = wiringSpawnCheck;
 exports.formatChecks = formatChecks;
 exports.wiringHandshakeChecks = wiringHandshakeChecks;
 exports.semanticTierVerdict = semanticTierVerdict;
@@ -52,6 +53,7 @@ const path = __importStar(require("node:path"));
 const role_policy_1 = require("../governance/role-policy");
 const blind_spots_1 = require("../guardrail/blind-spots");
 const node_child_process_1 = require("node:child_process");
+const spawn_spec_1 = require("./spawn-spec");
 const os = __importStar(require("node:os"));
 const settings_merge_1 = require("./settings-merge");
 const playbook_skills_1 = require("./playbook-skills");
@@ -1026,8 +1028,20 @@ function cleanupOnSignal(dir) {
 // Spawn the TARGET's wiring verbatim and require initialize inside the deadline. Unlike
 // `mcpHandshakeCheck` below (which proves this INSTALL can serve), this proves the WIRING the
 // harness will actually run reaches a server — the gap the dead npx form lived in.
-function wiringSpawnCheck(command, args, timeoutMs = 30000) {
+// @implements A-SPEC-499.1 — exported for the prescription tests; `platform` is injectable so the
+// win32 branch is testable off-Windows.
+function wiringSpawnCheck(command, args, timeoutMs = 30000, platform = process.platform) {
+    // The DISPLAYED command stays the original wiring string even when the win32 adapter rewraps the
+    // execution — the user compares this against their wiring file, not against cmd.exe plumbing.
     const quoted = `${command} ${args.join(' ')}`;
+    // @implements A-SPEC-499.1 — Windows field measurement: four wiring checks on a correctly rewired
+    // 0.3.1 target all died `spawn npx ENOENT`, because `npx` is `npx.cmd` there and a plain spawn
+    // cannot execute a .cmd shim. The adapter reroutes through cmd.exe; posix is value-identical.
+    const spec = (0, spawn_spec_1.spawnSpecFor)(command, args, platform);
+    // The re-init prescription is only honest when the wiring might actually be stale. A command the
+    // OS cannot find (ENOENT) re-inits into the identical failure forever — the measured loop.
+    const enoentFix = `\`${command}\` 명령을 찾지 못했습니다(PATH 또는 플랫폼) — 배선 문자열이 옳다면 재-init은 도움이 되지 않습니다. 같은 명령을 셸에서 직접 실행해 확인하십시오.`;
+    const spawnFailFix = (e) => e?.code === 'ENOENT' ? enoentFix : 'Re-run `holmes-kit init` in the target to rewrite the wiring.';
     return new Promise((resolve) => {
         let done = false;
         let out = '';
@@ -1045,13 +1059,13 @@ function wiringSpawnCheck(command, args, timeoutMs = 30000) {
         };
         const timer = setTimeout(() => finish('FAIL', `wiring did not answer initialize within ${timeoutMs / 1000}s: \`${quoted}\``, 'Re-run `holmes-kit init` in the target to rewrite the wiring, then re-run doctor.'), timeoutMs);
         try {
-            child = (0, node_child_process_1.spawn)(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+            child = (0, node_child_process_1.spawn)(spec.command, spec.args, { stdio: ['pipe', 'pipe', 'pipe'] });
         }
         catch (e) {
-            finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, 'Re-run `holmes-kit init` in the target to rewrite the wiring.');
+            finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, spawnFailFix(e));
             return;
         }
-        child.on('error', (e) => finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, 'Re-run `holmes-kit init` in the target to rewrite the wiring.'));
+        child.on('error', (e) => finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, spawnFailFix(e)));
         child.on('exit', (code) => finish('FAIL', `wiring exited (code ${code}) before answering initialize: \`${quoted}\``, 'Re-run `holmes-kit init` in the target to rewrite the wiring.'));
         child.stdin?.on('error', () => { });
         child.stdout?.on('data', (d) => {

package/dist/holmes/cli/spawn-spec.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Platform adapter for spawning a WIRING command verbatim. On win32, `npx` is `npx.cmd`, and a
+ * plain child_process.spawn cannot execute a .cmd shim (Node's CVE-2024-27980 hardening) — the
+ * Windows field measurement: doctor's four wiring-handshake checks all died `spawn npx ENOENT`
+ * on a target whose wiring was provably correct. Routing through cmd.exe is what the check's own
+ * purpose demands (it executes what the wiring file says), and no interpolation is added: tokens
+ * pass through byte-identical, quoted only when they carry whitespace (the measured
+ * space-in-username install path).
+ *
+ * PURE — platform arrives as an argument so every branch is testable off-Windows.
+ */
+export declare function spawnSpecFor(command: string, args: string[], platform: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};

package/dist/holmes/cli/spawn-spec.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnSpecFor = spawnSpecFor;
+// @implements A-SPEC-499.1
+/**
+ * Platform adapter for spawning a WIRING command verbatim. On win32, `npx` is `npx.cmd`, and a
+ * plain child_process.spawn cannot execute a .cmd shim (Node's CVE-2024-27980 hardening) — the
+ * Windows field measurement: doctor's four wiring-handshake checks all died `spawn npx ENOENT`
+ * on a target whose wiring was provably correct. Routing through cmd.exe is what the check's own
+ * purpose demands (it executes what the wiring file says), and no interpolation is added: tokens
+ * pass through byte-identical, quoted only when they carry whitespace (the measured
+ * space-in-username install path).
+ *
+ * PURE — platform arrives as an argument so every branch is testable off-Windows.
+ */
+function spawnSpecFor(command, args, platform) {
+    if (platform !== 'win32')
+        return { command, args: [...args] };
+    const joined = [command, ...args].map((t) => (/\s/.test(t) ? `"${t}"` : t)).join(' ');
+    return { command: 'cmd.exe', args: ['/d', '/s', '/c', joined] };
+}

package/package.json

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