@holmes-lab/holmes-kit 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.1.18] - 2026-08-23
+
+### Fixed
+- **The npx MCP wiring actually starts the server (REQ-259)**: `init` on an npm-installed package wrote `npx -y @holmes-lab/holmes-kit@<ver> holmes-mcp`, which npx resolves to the package-name-matching *default* binary (`holmes-kit`) with `holmes-mcp` as its argument — exit 1, so **every npm-installed wiring since the 0.1.15 npx pin launched a dead MCP server** (`CONNECTION_CLOSED` in the harness). The wiring now rides `-p` (`npx -y -p <pkg>@<ver> holmes-mcp`), the launcher test spawns the generated form against a locally packed tarball (with the pre-fix form kept as a failing control), and `doctor` gains **`mcp wiring spawn`** — it runs the target's `.mcp.json` command verbatim inside a 30s bound and names a dead wiring FAIL with the re-init remediation. Existing projects: re-run `holmes-kit init` (doctor will point at the dead wiring).
+- **`serverInfo.version` reports the real package version** — it was hardcoded to `0.1.0`, blinding client-side drift diagnosis.
+
+### Changed
+- **`approve` without a TTY names the next command (REQ-260)**: the implicit non-TTY fallback (e.g. Claude Code's `!` shell) used to print the pending list and exit 0 silently; it now appends runnable `--grant` / `--deny` / `--ask` examples carrying the first real pending id. Explicit `--list` output is unchanged for scripts.
+
+## [0.1.17] - 2026-08-23
+
+The two `main` lines — the Windows-compatibility line (12 commits, verified on Windows 11 and
+independently re-verified on macOS 26.5/APFS: 156/156 suites, gate probes over the `/tmp` →
+`/private/tmp` link spelling all as expected) and the mac release line (0.1.10–0.1.16) — are merged
+into one linear history in this release. Full suite on the merged tree: 191/191.
+
+### Added
+- **Windows Bootstrap Installer (REQ-253)**: `scripts/install.ps1`, a pure Windows PowerShell 5.1 script that runs *before* `npm install` and fixes what npm cannot — relocates out of protected directories (an elevated PowerShell opens in `C:\WINDOWS\System32`, where `npm install` fails with `EPERM`), substitutes a per-user `--prefix` when npm's global prefix is under `C:\Program Files\nodejs` (a second, distinct `EPERM`), gates on `engines.node`, and classifies native-build failures (`msbuild` / `python` / `node-gyp` / `network`) into the one `winget` command that fixes them. Non-interactive, idempotent, no persistent changes. Shipped in the package and documented as the recommended Windows install path. Measured end-to-end on a Windows 11 machine from `System32`: exit 0, no user input.
+
+### Fixed
+- **Path identity is canonical on every filesystem**: `resolveProjectRoot`, the containment gate, the store/derived checks and `resolveRmSignals` all canonicalise through `canonicalPath` (`fs.realpathSync.native`), closing an 8.3-short-name bypass on Windows while keeping the macOS `/tmp → /private/tmp` and case-folding behaviour — measured on both platforms, including mixed link/real spellings against the shipped hook.
+- **Drive-letter paths are absolute**: project containment no longer asks "is this POSIX-absolute" while meaning "is this absolute", so `C:\…` targets are governed on native Windows.
+- **Antigravity hook commands quote their paths**: a space in the install path no longer splits the command and silently disables the gate.
+- **Parser suites run on Windows**: `tsc`/`node` are spawned via `process.execPath`, `dist` is rebuilt only when stale, and `__test-support__` is excluded from `dist` and the npm package.
+- **Suites repaired for fresh checkouts**: the read-compat baseline fixture is tracked through a `.gitignore` re-inclusion chain, and `packaging.test.ts` asserts the CHANGELOG section of the *current* version instead of a stale literal.
+
+### Changed
+- **Spec renumbering**: the Windows installer slice had claimed REQ/H/A/T-SPEC-220, an id family the mac line had already assigned to *Windows Native Tier 1 Governance Parity*; the installer family is renumbered to REQ/H/A/T-SPEC-253 and re-sealed.
+
 ## [0.1.16] - 2026-08-23
 
 Predictable spec numbering — enforced at the door, and the corpus cleaned to match.

package/README.md

@@ -56,6 +56,16 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
 The same wrong command was run three times by a real adopter before the right one; a table beats
 prose read top-to-bottom.
 
+**Windows (recommended)** — a bootstrap installer that runs *before* npm and fixes what npm cannot: it relocates out of protected folders (an elevated PowerShell opens in `C:\WINDOWS\System32`, where `npm install` fails with `EPERM`), checks the Node.js version, and, if a native module fails to build, prints the one `winget` command that installs the missing C++ toolchain instead of raw compiler output. Pure Windows PowerShell 5.1; no prompts; nothing persistent is changed.
+```powershell
+# From a downloaded copy of the package (e.g. after `npm pack`, or from a checkout):
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1
+
+# One-liner (once hosted):
+# irm https://<host>/install.ps1 | iex
+```
+Add `-DryRun` to see what it would do without installing. Exit codes: `0` ok / already installed · `2` bad argument · `3` Node.js too old · `4` npm failed (remediation printed) · `5` installed but not on `PATH` (prefix printed).
+
 | Which situation are you in? | Privileges | Command |
 |---|---|---|
 | **Using it in one project** (most people) | none | `npm install --save-dev @holmes-lab/holmes-kit` |

package/dist/.build-id

@@ -1 +1 @@
-3c84046-mt5fni4h
+f8c9769-mt5t8gnu

package/dist/holmes/cli/agents.js

@@ -93,19 +93,25 @@ const mcpConfig = (packageRoot, specsDir, launcher) => {
  * (Claude 배선이 `guardrail` 모드에서 좁은 매처를 쓰는 것과 다른 선택인데, 그쪽은 그 좁힘이
  * 무엇을 뜻하는지 문서화된 모드 선택이고 여기는 기본 배선이기 때문이다.)
  */
+// A hook `command` is ONE shell string, so the path must be quoted — `buildHookPlan` in init.ts has
+// always done this for the Claude wiring, and this one did not. Measured 2026-08-23 on a machine
+// whose home directory contains a space: the shell split the path, the hook never ran, and the
+// Antigravity gate was silently off. (The MCP config above is different: it passes `args` as an
+// array, where quoting would put literal quote characters into the path.)
+const hookCommand = (packageRoot, script) => `node "${path.join(packageRoot, 'bin', script)}"`;
 const hooksJson = (packageRoot) => `${JSON.stringify({
     'holmes-kit': {
         PreToolUse: [{
                 matcher: '*',
                 hooks: [{
                         type: 'command',
-                        command: `node ${path.join(packageRoot, 'bin', 'holmes-hook-antigravity.js')}`,
+                        command: hookCommand(packageRoot, 'holmes-hook-antigravity.js'),
                         timeout: 30,
                     }],
             }],
         Stop: [{
                 type: 'command',
-                command: `node ${path.join(packageRoot, 'bin', 'holmes-stop-antigravity.js')}`,
+                command: hookCommand(packageRoot, 'holmes-stop-antigravity.js'),
                 timeout: 30,
             }],
     },

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

@@ -30,6 +30,17 @@ export declare function holdRequest(root: string, id: string, question: string,
  * teaches syntax, humans start typing it.
  */
 export declare function renderPending(state: QueueState): string;
+/**
+ * The non-TTY fallback's next-command hint. Pure.
+ *
+ * @implements A-SPEC-260
+ * Without a TTY the interactive loop cannot run, and the silent list-then-exit-0 left the operator
+ * with no idea what to type (measured 2026-08-23 — Claude Code's `!` runs with a non-TTY stdin).
+ * The examples carry the FIRST pending id read from the queue, never a placeholder the operator
+ * must transcribe: [noguess]. An empty queue yields an empty hint — nothing to act on, nothing to
+ * advise. `renderPending` itself stays hint-free: the explicit `--list` output is for scripts.
+ */
+export declare function renderNonTtyHint(state: QueueState): string;
 export interface ApproveIO {
     print: (s: string) => void;
     /** Ask one question, resolve with the raw answer. Injected so tests script the conversation. */

package/dist/holmes/cli/approve.js

@@ -37,6 +37,7 @@ exports.grantRequest = grantRequest;
 exports.denyRequest = denyRequest;
 exports.holdRequest = holdRequest;
 exports.renderPending = renderPending;
+exports.renderNonTtyHint = renderNonTtyHint;
 exports.runInteractive = runInteractive;
 // @implements A-SPEC-246
 const fs = __importStar(require("node:fs"));
@@ -154,6 +155,27 @@ function renderPending(state) {
         lines.push(`(큐에 읽을 수 없는 줄 ${state.malformedLines}건 — 손상 여부를 확인하십시오)`);
     return lines.join('\n');
 }
+/**
+ * The non-TTY fallback's next-command hint. Pure.
+ *
+ * @implements A-SPEC-260
+ * Without a TTY the interactive loop cannot run, and the silent list-then-exit-0 left the operator
+ * with no idea what to type (measured 2026-08-23 — Claude Code's `!` runs with a non-TTY stdin).
+ * The examples carry the FIRST pending id read from the queue, never a placeholder the operator
+ * must transcribe: [noguess]. An empty queue yields an empty hint — nothing to act on, nothing to
+ * advise. `renderPending` itself stays hint-free: the explicit `--list` output is for scripts.
+ */
+function renderNonTtyHint(state) {
+    if (state.pending.length === 0)
+        return '';
+    const id = state.pending[0].id;
+    return [
+        '대화형 결정은 TTY에서만 동작합니다 — 이 셸에서는 아래 비대화형 명령을 사용하십시오:',
+        `  holmes-kit approve --grant ${id}`,
+        `  holmes-kit approve --deny ${id} --reason "<사유>"`,
+        `  holmes-kit approve --ask ${id} --question "<질문>"`,
+    ].join('\n');
+}
 /**
  * The interactive loop — one entry at a time, one letter per decision.
  *

package/dist/holmes/cli/doctor.js

@@ -487,6 +487,38 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             }
         }
         catch { /* .mcp.json 부재/파싱 실패 → 이 점검 없이 진행 */ }
+        // @implements A-SPEC-259 — the wiring is judged by SPAWNING it. String comparison is exactly how
+        // the dead `npx -y <pkg>@<ver> holmes-mcp` form (npx resolves the default bin and hands
+        // `holmes-mcp` to it as an argument) passed the launcher test, this doctor's own handshake check
+        // (which starts the server directly, not through the wiring), and the release tarball probe —
+        // measured 2026-08-23. A node wiring is judged on path existence (a source checkout must not pay
+        // a spawn), an absent .mcp.json is skipped by name, and the spawn is BOUNDED: it succeeds or
+        // fails inside its deadline, never hangs (REQ-258's lesson, applied from this check onward).
+        {
+            const mcpPath = path.join(target, '.mcp.json');
+            if (!fs.existsSync(mcpPath)) {
+                add('mcp wiring spawn', 'PASS', 'skipped — no .mcp.json in the target: an absent wiring is not a dead one');
+            }
+            else {
+                try {
+                    const server = JSON.parse(fs.readFileSync(mcpPath, 'utf8'))
+                        .mcpServers?.[init_1.SERVER_NAME];
+                    if (!server || typeof server.command !== 'string' || !Array.isArray(server.args)) {
+                        add('mcp wiring spawn', 'WARN', `.mcp.json carries no runnable ${init_1.SERVER_NAME} entry`, 'Run `holmes-kit init` in the target to write the wiring.');
+                    }
+                    else if (server.command === 'node') {
+                        const bin = server.args[0] ?? '';
+                        add('mcp wiring spawn', fs.existsSync(bin) ? 'PASS' : 'FAIL', fs.existsSync(bin) ? `node wiring resolves: ${bin}` : `node wiring points at a missing file: ${bin}`, fs.existsSync(bin) ? undefined : 'Run `holmes-kit init` in the target to rewire the absolute path.');
+                    }
+                    else {
+                        checks.push(await wiringSpawnCheck(server.command, server.args));
+                    }
+                }
+                catch {
+                    add('mcp wiring spawn', 'WARN', 'could not read .mcp.json', 'Run `holmes-kit init` in the target to rewrite the wiring.');
+                }
+            }
+        }
         // @implements A-SPEC-193 — 배선된 하네스마다 그 하네스의 배선을 검사한다. 배선되지 않은
         // 하네스는 진단하지 않는다(없는 것을 결함이라 부르면 doctor 가 소음이 된다).
         const agyHooks = path.join(target, '.agents', 'hooks.json');
@@ -616,6 +648,54 @@ function cleanupOnSignal(dir) {
  * and closes stdin makes the server exit before answering (a false FAIL this check produced on its
  * very first run against a healthy server).
  */
+// @implements A-SPEC-259
+// 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) {
+    const quoted = `${command} ${args.join(' ')}`;
+    return new Promise((resolve) => {
+        let done = false;
+        let out = '';
+        let child;
+        const finish = (level, detail, fix) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            try {
+                child.kill();
+            }
+            catch { /* already gone */ }
+            resolve({ name: 'mcp wiring spawn', level, detail, fix });
+        };
+        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'] });
+        }
+        catch (e) {
+            finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, 'Re-run `holmes-kit init` in the target to rewrite the wiring.');
+            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('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) => {
+            out += String(d);
+            for (const line of out.split('\n')) {
+                try {
+                    const m = JSON.parse(line);
+                    if (m?.result?.serverInfo) {
+                        finish('PASS', `wiring reaches a live server (v${m.result.serverInfo.version ?? '?'}): \`${quoted}\``);
+                        return;
+                    }
+                }
+                catch { /* partial line */ }
+            }
+        });
+        child.stdin?.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'holmes-doctor', version: '1' } } }) + '\n');
+    });
+}
 function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
     return new Promise((resolve) => {
         const mcpCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-doctor-mcp-'));

package/dist/holmes/cli/index.js

@@ -359,7 +359,7 @@ async function main(argv) {
         // @implements A-SPEC-246 — the surface where a human decides. Interactive on a TTY with no
         // decision flags; every interactive decision has a flag equivalent so a CI or remote operator
         // is never locked out.
-        const { grantRequest, denyRequest, holdRequest, renderPending, runInteractive } = require('./approve');
+        const { grantRequest, denyRequest, holdRequest, renderPending, renderNonTtyHint, runInteractive } = require('./approve');
         const { readQueue } = require('../governance/approval-queue');
         const root = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
         const actor = (() => { try {
@@ -402,10 +402,18 @@ async function main(argv) {
             process.stdout.write(r.ok ? '✓ 보류 — 질문이 다음 거부 문면에 실립니다\n' : `✗ ${r.reason}\n`);
             return r.ok ? 0 : 1;
         }
-        if (flags.list || !process.stdin.isTTY) {
+        if (flags.list) {
             process.stdout.write(renderPending(readQueue(root)) + '\n');
             return 0;
         }
+        // @implements A-SPEC-260 — the implicit non-TTY fallback tells the operator the next command,
+        // with the real pending id filled in; the explicit --list above stays script-clean.
+        if (!process.stdin.isTTY) {
+            const state = readQueue(root);
+            const hint = renderNonTtyHint(state);
+            process.stdout.write(renderPending(state) + (hint ? '\n\n' + hint : '') + '\n');
+            return 0;
+        }
         const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
         void runInteractive(root, {
             print: (t) => process.stdout.write(t + '\n'),

package/dist/holmes/cli/mcp-launcher.js

@@ -52,7 +52,12 @@ exports.MCP_PACKAGE = '@holmes-lab/holmes-kit';
  */
 function mcpServerEntry(opts) {
     if (opts.mode === 'npx') {
-        return { command: 'npx', args: ['-y', `${exports.MCP_PACKAGE}@${opts.version}`, 'holmes-mcp'] };
+        // @implements A-SPEC-259 — the package must ride `-p` with the command named separately.
+        // `npx <pkg> holmes-mcp` runs the package-name-matching DEFAULT bin (holmes-kit) and hands
+        // `holmes-mcp` to it as an argument: measured 2026-08-23, exit 1 "unknown command" — every
+        // npm-installed wiring since the npx pin was a dead server. The `-p` form is the one that
+        // reached initialize in the same measurement.
+        return { command: 'npx', args: ['-y', '-p', `${exports.MCP_PACKAGE}@${opts.version}`, 'holmes-mcp'] };
     }
     return { command: 'node', args: [opts.mcpBinPath] };
 }

package/dist/holmes/hooks/pre-tool-use.js

@@ -90,11 +90,14 @@ function resolveRmSignals(command, cwd) {
     let repoRoot;
     let baseReal;
     try {
-        repoRoot = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], { cwd, stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() })
-            .toString().trim();
-        // git realpaths the toplevel (resolves symlinks like macOS /var -> /private/var); resolve the
-        // cwd the same way so in-project containment comparisons don't spuriously fail on a symlinked path.
-        baseReal = fs.realpathSync(cwd);
+        // Both sides through the ONE canonicaliser. git prints the top-level symlink-resolved, with `/`
+        // separators on Windows and the long name; the JS realpath kept 8.3 aliases and `path.sep`
+        // comparisons below never matched `C:/…` against `C:\…`. Measured 2026-08-23: `rm -rf build`
+        // in a real repo read as inProject=false, so a gitignored build dir was escalated as if it were
+        // outside the project — fail-safe in direction, wrong in fact, and a needless HITL every time.
+        repoRoot = (0, root_1.canonicalPath)((0, node_child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], { cwd, stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() })
+            .toString().trim());
+        baseReal = (0, root_1.canonicalPath)(cwd);
     }
     catch {
         return undefined; // not a git repo / git unavailable -> static fallback
@@ -111,7 +114,7 @@ function resolveRmSignals(command, cwd) {
         // lexical path (nothing to delete yet); realpath errors fail safe to the lexical value.
         try {
             if (fs.existsSync(resolved))
-                resolved = fs.realpathSync(resolved);
+                resolved = (0, root_1.canonicalPath)(resolved);
         }
         catch { /* keep lexical */ }
         const inProject = resolved === repoRoot || resolved.startsWith(repoRoot + path.sep);
@@ -615,12 +618,17 @@ function evaluateHook(input, specsDir, opts) {
     // path under a symlinked ancestor (macOS `/tmp` → `/private/tmp` is the ordinary case) switched
     // the gate off. A bound that runs out must fail toward the gate, not away from it — so the walk
     // is not bounded by a count at all; it ends at the filesystem root, which always terminates.
+    // `canonicalPath` (realpathSync.native), not the JS realpath: the root arrives canonicalised by
+    // root.ts, which expands Windows 8.3 aliases; the JS realpath does not. Measured 2026-08-23 on
+    // the built hook — an in-project target spelled through `%TEMP%`'s alias (`C:\Users\SUNGNA~1\…`)
+    // resolved to a string the long-name root did not contain, and took the "outside → allow" exit
+    // below. Both sides must go through the one canonicaliser, or an alias is a free pass.
     const realOf = (abs) => {
         let head = abs;
         const tail = [];
         for (;;) {
             try {
-                return [fs.realpathSync(head).replace(/\\/g, '/'), ...tail].join('/');
+                return [(0, root_1.canonicalPath)(head).replace(/\\/g, '/'), ...tail].join('/');
             }
             catch { /* walk up */ }
             const parent = path.dirname(head);

package/dist/holmes/mcp/handlers.js

@@ -262,13 +262,13 @@ function boundNonceLedger(store) {
         // `--specs-dir docs/specs` an ordinary review_record could still plant `docs/specs/.ax` and move
         // every consumed nonce, every audit line, and spec_approve's notion of "this project" with it.
         const storeReal = (() => { try {
-            return fs.realpathSync(store.specsRoot);
+            return (0, root_2.canonicalPath)(store.specsRoot);
         }
         catch {
             return store.specsRoot;
         } })();
         const derivedReal = (() => { try {
-            return fs.realpathSync(derived);
+            return (0, root_2.canonicalPath)(derived);
         }
         catch {
             return derived;
@@ -301,13 +301,13 @@ function boundFindingsLedger(store, root) {
     try {
         const derived = projectRootOf(store.specsRoot);
         const storeReal = (() => { try {
-            return fs.realpathSync(store.specsRoot);
+            return (0, root_2.canonicalPath)(store.specsRoot);
         }
         catch {
             return store.specsRoot;
         } })();
         const derivedReal = (() => { try {
-            return fs.realpathSync(derived);
+            return (0, root_2.canonicalPath)(derived);
         }
         catch {
             return derived;

package/dist/holmes/mcp/server.js

@@ -12,7 +12,19 @@ const validate_args_1 = require("./validate-args");
 // @implements A-SPEC-100.2
 const store = new spec_store_1.LocalMarkdownRepository(process.env.HOLMES_SPECS ?? '.ax/specs');
 const handlers = (0, handlers_1.makeHandlers)(store);
-const server = new index_js_1.Server({ name: 'holmes-kit', version: '0.1.0' }, { capabilities: { tools: {} } });
+// @implements A-SPEC-259 — the advertised version is the package's own, not a literal that froze at
+// 0.1.0: a hardcoded serverInfo.version blinds any client-side drift diagnosis.
+const PKG_VERSION = (() => {
+    try {
+        // dist/holmes/mcp/server.js → three levels up is the package root, same as the source layout.
+        const raw = require('node:fs').readFileSync(require('node:path').join(__dirname, '..', '..', '..', 'package.json'), 'utf8');
+        return JSON.parse(raw).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+const server = new index_js_1.Server({ name: 'holmes-kit', version: PKG_VERSION }, { capabilities: { tools: {} } });
 const fullProfile = process.env.HOLMES_MCP_PROFILE === 'full';
 // Register each handler as a tool with its real typed inputSchema so MCP
 // clients can marshal complex (array/object) arguments; fall back to a

package/dist/holmes/project/change-source.js

@@ -189,7 +189,12 @@ class GitChangeSource {
         this.base = base;
         this.head = head;
         this.topLevel = (0, root_1.resolveProjectRoot)(root).git?.topLevel;
-        if (this.topLevel && fs.realpathSync(path.resolve(root)) !== this.topLevel) {
+        // The GIVEN root must be the top-level — `changes()` runs git against it, so a subdirectory
+        // (even one that walks up to the same `.ax`) would tag paths against the wrong base. Both sides
+        // go through ONE canonicaliser: the old `fs.realpathSync(root)` here was the JS realpath, which
+        // keeps Windows 8.3 aliases the top-level side had already expanded — measured 2026-08-23, the
+        // same directory spelled `C:\AI_PRO~1\…` threw as a mismatch.
+        if (this.topLevel && (0, root_1.canonicalPath)(path.resolve(root)) !== this.topLevel) {
             throw new Error(`GitChangeSource: root must be the git top-level (got ${root}, top-level is ${this.topLevel})`);
         }
     }

package/dist/holmes/project/root.d.ts

@@ -31,4 +31,17 @@ export interface ProjectRoot {
 }
 /** The marker directory that makes a directory a Holmes-Kit project. */
 export declare const MARKER = ".ax";
+/**
+ * The one canonical spelling of an existing path.
+ *
+ * `fs.realpathSync.native`, not `fs.realpathSync`. The JS implementation resolves symlinks only;
+ * on Windows it leaves 8.3 short-name aliases (`C:\Users\SUNGNA~1`, which is what `%TEMP%` and
+ * `os.tmpdir()` hand out) exactly as spelled, while `git rev-parse --show-toplevel` prints the
+ * long name. Measured 2026-08-23: `resolveProjectRoot('C:/AI_PRO~1/AX-COD~1')` reported
+ * `root: C:\AI_PRO~1\AX-COD~1` beside `git.topLevel: C:\ai_project\AX-Coding-Project` for ONE
+ * directory, and GitChangeSource refused it as a mismatch. The native call expands both symlinks
+ * and 8.3 names (a strict superset, same ENOENT behaviour), so `root` keeps the promise its type
+ * makes: one spelling per directory, the spelling every path key is built from.
+ */
+export declare const canonicalPath: (p: string) => string;
 export declare function resolveProjectRoot(dir: string): ProjectRoot;

package/dist/holmes/project/root.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MARKER = void 0;
+exports.canonicalPath = exports.MARKER = void 0;
 exports.cleanSubprocessEnv = cleanSubprocessEnv;
 exports.resolveProjectRoot = resolveProjectRoot;
 // @implements A-SPEC-205
@@ -56,6 +56,21 @@ function cleanSubprocessEnv(env = process.env) {
 }
 /** The marker directory that makes a directory a Holmes-Kit project. */
 exports.MARKER = '.ax';
+/**
+ * The one canonical spelling of an existing path.
+ *
+ * `fs.realpathSync.native`, not `fs.realpathSync`. The JS implementation resolves symlinks only;
+ * on Windows it leaves 8.3 short-name aliases (`C:\Users\SUNGNA~1`, which is what `%TEMP%` and
+ * `os.tmpdir()` hand out) exactly as spelled, while `git rev-parse --show-toplevel` prints the
+ * long name. Measured 2026-08-23: `resolveProjectRoot('C:/AI_PRO~1/AX-COD~1')` reported
+ * `root: C:\AI_PRO~1\AX-COD~1` beside `git.topLevel: C:\ai_project\AX-Coding-Project` for ONE
+ * directory, and GitChangeSource refused it as a mismatch. The native call expands both symlinks
+ * and 8.3 names (a strict superset, same ENOENT behaviour), so `root` keeps the promise its type
+ * makes: one spelling per directory, the spelling every path key is built from.
+ */
+const canonicalPath = (p) => fs.realpathSync.native(p);
+exports.canonicalPath = canonicalPath;
+const canonical = exports.canonicalPath;
 function gitTopLevel(dir) {
     try {
         // stderr silenced: "not a git repository" is an expected branch here, not a fault worth printing.
@@ -66,7 +81,7 @@ function gitTopLevel(dir) {
         }).trim();
         // git resolves symlinks in its output; realpath ours too so comparisons are like-for-like
         // (macOS /var -> /private/var otherwise makes an identical directory look like a mismatch).
-        return out ? fs.realpathSync(out) : undefined;
+        return out ? canonical(out) : undefined;
     }
     catch {
         return undefined;
@@ -75,7 +90,7 @@ function gitTopLevel(dir) {
 function resolveProjectRoot(dir) {
     let start;
     try {
-        start = fs.realpathSync(path.resolve(dir));
+        start = canonical(path.resolve(dir));
     }
     catch {
         // @implements A-SPEC-189 §7 (round 11) — this is a POINTED refusal about the caller's own

package/dist/holmes/server/dashboard.js

@@ -765,7 +765,7 @@ function renderDashboardHtml() {
         items.forEach(s => { statuses[s.status] = (statuses[s.status] || 0) + 1; });
         const statusSummary = Object.keys(statuses).map(k => escapeHtml(k) + ' × ' + statuses[k]).join(' · ');
         html += '<div class="req-card" style="margin-bottom:20px;">'
-          + '<div class="req-header" onclick="toggleAccordion(\'legacy-body-' + escapeHtml(kind) + '\')">'
+          + '<div class="req-header" onclick="toggleAccordion(\\'legacy-body-' + escapeHtml(kind) + '\\')">'
           + '<div class="req-title-group"><span class="req-id-badge">' + escapeHtml(kind) + '</span>'
           + '<span class="req-title">' + items.length + ' unmapped document' + (items.length === 1 ? '' : 's') + '</span>'
           + '<span class="neighbor-rel badge-unmeasured">' + statusSummary + '</span></div>'
@@ -851,7 +851,7 @@ function renderDashboardHtml() {
       if (!label) {
         return '<td class="' + cls + ' stage-missing" title="No artifact for this stage">' + arrow + '— missing</td>';
       }
-      const onclick = jumpId ? ' onclick="focusSpecInGraph(\'' + escapeHtml(String(jumpId)) + '\')"' : '';
+      const onclick = jumpId ? ' onclick="focusSpecInGraph(\\'' + escapeHtml(String(jumpId)) + '\\')"' : '';
       return '<td class="' + cls + '"' + onclick + '>' + arrow + icon + ' ' + escapeHtml(String(label)) + '</td>';
     }
     // REQ-Grouped Structured 6-Stage Pipeline Heatmap Matrix Renderer

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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",
@@ -13,6 +13,7 @@
     "bin/",
     "dist/",
     "playbooks/",
+    "scripts/install.ps1",
     "docs/install-guide.md",
     "CHANGELOG.md"
   ],

package/scripts/install.ps1

@@ -0,0 +1,297 @@
+<#
+.SYNOPSIS
+  Holmes-Kit bootstrap installer for Windows.  @implements A-SPEC-253
+.DESCRIPTION
+  Runs BEFORE npm to fix what npm cannot: a protected CWD (an elevated PowerShell opens in
+  C:\WINDOWS\System32 and `npm install` dies there with EPERM), an unwritable global prefix
+  (C:\Program Files\nodejs), a too-old Node.js, and native-build failures that print compiler
+  noise instead of the one command that installs the toolchain.  Then it runs
+  `npm install -g @holmes-lab/holmes-kit`.  Windows PowerShell 5.1 only; no prompts; nothing
+  persistent is changed.
+.PARAMETER DryRun   Run every check, print the npm command that WOULD run, exit 0 without running it.
+.PARAMETER Version  Package version to install (default: latest).
+.PARAMETER Prefix   Optional npm --prefix for the global install.
+.EXAMPLE
+  powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1 [-DryRun] [-Version 0.1.9]
+.NOTES
+  Exit codes: 0 ok / already installed, 2 argument error, 3 Node too old, 4 npm failed, 5 not on PATH.
+#>
+# Non-positional on purpose: otherwise `install.ps1 foo` binds `foo` to -Version and runs a REAL
+# `npm install -g @holmes-lab/holmes-kit@foo` from a typo.  Stray tokens land in $Rest -> exit 2.
+[CmdletBinding(PositionalBinding = $false)]
+param(
+  [Parameter(Mandatory = $false)][switch]$DryRun,
+  [Parameter(Mandatory = $false)][string]$Version = 'latest',
+  [Parameter(Mandatory = $false)][string]$Prefix,
+  [Parameter(Mandatory = $false, ValueFromRemainingArguments = $true)][string[]]$Rest
+)
+
+Set-StrictMode -Version 2.0
+$ErrorActionPreference = 'Stop'
+
+# Mirrors package.json#engines.node (">=20").  Bump both together.
+$script:NodeMajorFloor = 20
+$script:PackageName = '@holmes-lab/holmes-kit'
+$script:BinName = 'holmes-kit'
+
+# Failure classifier.  Pure: npm's combined output in, one token out.  Precedence is fixed so the
+# most ACTIONABLE cause wins when several signatures appear in the same transcript - an EPERM in a
+# protected directory also drags node-gyp down with it, and telling the user to install MSVC
+# would send them the wrong way.
+function Get-InstallFailureKind([string]$NpmOutput) {
+  if ($null -eq $NpmOutput) { $NpmOutput = '' }
+  # Two EPERMs, one code.  CWD (System32): relocating fixes it.  GLOBAL PREFIX (C:\Program Files\
+  # nodejs, the Node installer's default): only --prefix fixes it.  Measured 2026-08-23: after the
+  # relocation the install still died on `mkdir 'C:\Program Files\nodejs\node_modules\@holmes-lab'`.
+  # Keyed on the FAILING PATH line, not any mention of that directory: every npm stack trace names
+  # npm's own home under Program Files\nodejs\node_modules\npm, which is not the error.
+  if ($NpmOutput -match 'EPERM' -and $NpmOutput -match "(?m)^npm error path .*Program Files[\\/]+nodejs[\\/]+node_modules[\\/]+(?!npm[\\/])") { return 'eperm-prefix' }
+  if ($NpmOutput -match 'EPERM' -and ($NpmOutput -match 'mkdir' -or $NpmOutput -match 'System32' -or $NpmOutput -match 'Program Files')) { return 'eperm' }
+  if ($NpmOutput -match 'MSB\d{4}' -or $NpmOutput -match 'MSBuild' -or $NpmOutput -match 'Visual Studio' -or $NpmOutput -match 'vcvarsall') { return 'msbuild' }
+  if ($NpmOutput -match 'Could not find any Python' -or $NpmOutput -match 'gyp ERR! find Python') { return 'python' }
+  if ($NpmOutput -match 'node-gyp' -or $NpmOutput -match 'gyp ERR!') { return 'nodegyp-generic' }
+  if ($NpmOutput -match 'ENOTFOUND' -or $NpmOutput -match 'ETIMEDOUT' -or $NpmOutput -match 'ECONNRESET' -or $NpmOutput -match 'EAI_AGAIN') { return 'network' }
+  return 'none'
+}
+
+$script:Remediation = @{
+  'eperm' = @'
+npm was denied permission to create files in the current directory.
+This usually means the shell was opened in a protected system folder (e.g. C:\WINDOWS\System32).
+Re-run this installer (it relocates to your user profile automatically), or `cd` to a folder you own first.
+'@
+  'eperm-prefix' = @'
+npm's GLOBAL prefix is inside C:\Program Files\nodejs, which only an administrator can write.
+This installer passes a per-user prefix automatically; if you ran npm yourself, use one of:
+  npm install -g @holmes-lab/holmes-kit --prefix "$env:APPDATA\npm"      (this install only)
+  npm config set prefix "$env:APPDATA\npm"                                (every global install)
+and make sure that folder is on your user PATH (the Node.js installer normally adds it).
+'@
+  'msbuild' = @'
+A native module needed a C++ compiler and none was found.
+Install the Visual Studio Build Tools with the C++ workload (one command, ~2 GB):
+
+  winget install Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+
+Then open a NEW terminal and re-run this installer.
+'@
+  'python' = @'
+node-gyp could not find a Python 3 interpreter (it needs one to drive the native build).
+
+  winget install Python.Python.3.12
+
+Then open a NEW terminal and re-run this installer.
+'@
+  'nodegyp-generic' = @'
+A native module failed to build and no prebuilt binary matched your Node.js version.
+Most often the C++ Build Tools are missing:
+  winget install Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+If they are installed, try a current Node.js LTS (prebuilt binaries track LTS releases).
+'@
+  'network' = @'
+npm could not reach the registry (DNS / timeout / connection reset).
+Check your connection and proxy settings (`npm config get proxy`, `npm config get https-proxy`), then re-run.
+'@
+  'none' = @'
+npm exited with an error this installer does not recognise.  The last lines of its output are above.
+'@
+}
+
+# Stage helpers
+function Write-Stage([string]$Text) { Write-Host $Text }
+function Write-Problem([string]$Text) { [Console]::Error.WriteLine($Text) }
+
+function Get-NormalizedPath([string]$P) {
+  if ([string]::IsNullOrWhiteSpace($P)) { return $null }
+  $t = $P.TrimEnd('\', '/')
+  if ($t.Length -eq 2 -and $t[1] -eq ':') { $t = $t + '\' }   # 'C:' -> 'C:\' so the drive root compares as itself
+  return $t.ToLowerInvariant()
+}
+
+function Test-UnderRoot([string]$Candidate, [string]$Root) {
+  if ($null -eq $Root) { return $false }
+  if ($Candidate -eq $Root) { return $true }
+  $prefix = $Root
+  if (-not $prefix.EndsWith('\')) { $prefix = $prefix + '\' }  # separator first: C:\Windowsx is NOT under C:\Windows
+  return $Candidate.StartsWith($prefix)
+}
+
+function Test-ProtectedDirectory([string]$Dir) {
+  $here = Get-NormalizedPath $Dir
+  # The drive root is protected only when $PWD IS the root (C:\) - everything on the drive is
+  # under it, so treating it like the other roots would relocate every project on the machine.
+  $driveRoot = Get-NormalizedPath ([IO.Path]::GetPathRoot($Dir))
+  if ($null -ne $driveRoot -and $here -eq $driveRoot) { return $true }
+  $roots = @($env:SystemRoot, $env:ProgramFiles, ${env:ProgramFiles(x86)}, $env:ProgramData)
+  foreach ($r in $roots) {
+    if (Test-UnderRoot $here (Get-NormalizedPath $r)) { return $true }
+  }
+  return $false
+}
+
+function Test-WritableDirectory([string]$Dir) {
+  $probe = Join-Path $Dir ('.holmes-kit-write-probe-' + [Guid]::NewGuid().ToString('N'))
+  try {
+    New-Item -ItemType File -Path $probe -ErrorAction Stop | Out-Null
+    Remove-Item -LiteralPath $probe -Force -ErrorAction SilentlyContinue
+    return $true
+  } catch {
+    return $false
+  }
+}
+
+function Test-Elevated {
+  try {
+    $id = [Security.Principal.WindowsIdentity]::GetCurrent()
+    $p = New-Object Security.Principal.WindowsPrincipal($id)
+    return $p.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+  } catch { return $false }
+}
+
+function Get-NodeVersionString {
+  $cmd = Get-Command node -ErrorAction SilentlyContinue
+  if ($null -eq $cmd) { return $null }
+  try { return ((& node --version) | Select-Object -First 1).Trim() } catch { return $null }
+}
+
+function Get-InstalledVersion {
+  $cmd = Get-Command $script:BinName -ErrorAction SilentlyContinue
+  if ($null -eq $cmd) { return $null }
+  try {
+    $out = (& $script:BinName --version 2>$null) | Select-Object -First 1
+    if ($out -match '(\d+\.\d+\.\d+[^\s]*)') { return $Matches[1] }
+    return $null
+  } catch { return $null }
+}
+
+function Get-NpmPrefix {
+  # Skipped in -DryRun only when npm is absent; otherwise it is a local config read, no network.
+  $r = Invoke-Npm @('config', 'get', 'prefix')
+  if ($r.Code -ne 0) { return $null }
+  $v = $r.Output.Trim()
+  if ([string]::IsNullOrWhiteSpace($v) -or $v -eq 'undefined') { return $null }
+  return $v
+}
+
+function Invoke-Npm([string[]]$Arguments) {
+  # Array arguments, never one interpolated string; npm is npm.cmd on Windows and needs the
+  # .cmd resolution that `&` performs.  Both streams are merged so the classifier sees everything.
+  $npm = Get-Command npm.cmd -ErrorAction SilentlyContinue
+  if ($null -eq $npm) { $npm = Get-Command npm -ErrorAction SilentlyContinue }
+  if ($null -eq $npm) { return @{ Code = 127; Output = 'npm was not found on PATH' } }
+  $prev = $ErrorActionPreference
+  $ErrorActionPreference = 'Continue'   # a native command writing to stderr must not throw here
+  try {
+    $lines = & $npm.Source @Arguments 2>&1 | ForEach-Object { "$_" }
+    $code = $LASTEXITCODE
+  } finally {
+    $ErrorActionPreference = $prev
+  }
+  return @{ Code = $code; Output = ($lines -join "`n") }
+}
+
+# Pipeline
+function Invoke-Main {
+  # Stage 0 - arguments
+  if ($null -ne $Rest -and $Rest.Count -gt 0) {
+    Write-Problem ("Unrecognised argument(s): " + ($Rest -join ' '))
+    Write-Problem 'Usage: install.ps1 [-DryRun] [-Version <string>] [-Prefix <dir>]'
+    return 2
+  }
+  if ([string]::IsNullOrWhiteSpace($Version)) { $Version = 'latest' }
+
+  # Stage 1 - directory guard.  Relocate, report, never ask.
+  $cwd = (Get-Location).Path
+  $protected = Test-ProtectedDirectory $cwd
+  $writable = $false
+  if (-not $protected) { $writable = Test-WritableDirectory $cwd }
+  if ($protected -or -not $writable) {
+    $home_ = $env:USERPROFILE
+    Write-Stage ("Relocating: {0} is a protected or read-only directory; continuing from {1}" -f $cwd, $home_)
+    Set-Location -LiteralPath $home_
+  }
+
+  # Stage 2 - elevation notice (warn, continue)
+  if (Test-Elevated) {
+    Write-Stage 'Note: this shell is elevated. A global npm install from here may land in a per-machine prefix that your normal (non-admin) terminal does not see. A regular user shell is recommended.'
+  }
+
+  # Stage 3 - Node version gate
+  $nodeV = Get-NodeVersionString
+  $major = -1
+  if ($null -ne $nodeV -and $nodeV -match '^v?(\d+)\.(\d+)\.(\d+)') { $major = [int]$Matches[1] }
+  if ($major -lt $script:NodeMajorFloor) {
+    $found = $nodeV
+    if ($null -eq $found) { $found = 'none' }
+    Write-Problem ("Node.js >= {0} is required (found {1}). Install from https://nodejs.org/" -f $script:NodeMajorFloor, $found)
+    return 3
+  }
+  Write-Stage ("Node.js {0} OK" -f $nodeV)
+
+  # Stage 4 - idempotence
+  $installed = Get-InstalledVersion
+  if ($null -ne $installed) {
+    $want = $Version
+    if ($want -eq 'latest' -and -not $DryRun) {
+      $view = Invoke-Npm @('view', $script:PackageName, 'version')
+      if ($view.Code -eq 0) { $want = $view.Output.Trim() }
+    }
+    if ($want -ne 'latest' -and $installed -eq $want) {
+      Write-Stage ("already installed ({0})" -f $installed)
+      return 0
+    }
+    Write-Stage ("holmes-kit {0} is installed; will install {1}" -f $installed, $Version)
+  }
+
+  # Stage 4b - prefix guard.  A non-elevated shell cannot write the Node installer's default
+  # prefix (C:\Program Files\nodejs) and Stage 1 does not help.  Per-user prefix for THIS call
+  # only; the user's npm config is never modified (REQ-253 Constraint 2).
+  if ([string]::IsNullOrWhiteSpace($Prefix) -and -not (Test-Elevated)) {
+    $cur = Get-NpmPrefix
+    if ($null -ne $cur -and (Test-ProtectedDirectory $cur)) {
+      $Prefix = Join-Path $env:APPDATA 'npm'
+      Write-Stage ("npm's global prefix ({0}) is not writable without elevation; using --prefix {1} for this install" -f $cur, $Prefix)
+    }
+  }
+
+  # Stage 5 - npm install
+  $spec = '{0}@{1}' -f $script:PackageName, $Version
+  $npmArgs = @('install', '-g', $spec)
+  $display = 'npm install -g "{0}"' -f $spec
+  if (-not [string]::IsNullOrWhiteSpace($Prefix)) {
+    $npmArgs += @('--prefix', $Prefix)
+    $display = $display + (' --prefix "{0}"' -f $Prefix)
+  }
+  if ($DryRun) {
+    Write-Stage ('DRY-RUN: ' + $display)
+    return 0
+  }
+  Write-Stage ('Running: ' + $display)
+  $r = Invoke-Npm $npmArgs
+  if ($r.Code -ne 0) {
+    $kind = Get-InstallFailureKind $r.Output
+    $tail = ($r.Output -split "`n") | Select-Object -Last 15
+    Write-Problem '--- npm output (last 15 lines) ---'
+    foreach ($l in $tail) { Write-Problem $l }
+    Write-Problem '--- what to do ---'
+    Write-Problem $script:Remediation[$kind]
+    return 4
+  }
+
+  # Stage 6 - PATH verification
+  $cmd = Get-Command $script:BinName -ErrorAction SilentlyContinue
+  if ($null -eq $cmd) {
+    $pfx = (Invoke-Npm @('config', 'get', 'prefix')).Output.Trim()
+    Write-Problem ("holmes-kit installed but {0} is not on PATH for this shell. Open a new terminal, or add it to your user PATH." -f $pfx)
+    return 5
+  }
+  $v = Get-InstalledVersion
+  Write-Stage ("holmes-kit {0} installed" -f $v)
+  return 0
+}
+
+# Dot-sourcing (`. .\install.ps1`) loads the functions for testing and does NOT run the pipeline.
+if ($MyInvocation.InvocationName -ne '.') {
+  $code = Invoke-Main
+  exit $code
+}