@holmes-lab/holmes-kit 0.20.0 → 0.20.2

package/CHANGELOG.md

@@ -5,6 +5,90 @@ 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.20.2] - 2026-09-16
+
+Two findings the Windows cycle recorded and could not close, closed — without giving autonomy or the
+drift check one inch of slack.
+
+### Fixed
+- **A sealed spec can now admit a root-level file** (A-SPEC-654). `Files to Touch` tokens had to contain
+  a slash, so a spec listing `- jest.config.js` produced no token at all and its own anchored write was
+  refused as "outside its Files to Touch scope" — measured 2026-09-15 on Windows, where A-SPEC-652.4 had
+  to be redesigned around it. A list item whose first word is a filename with an extension is now a token;
+  a filename mentioned inside prose, a version-like item (`- 0.20.1`) and a bare word still yield nothing,
+  and the enforcer still admits exactly that one path.
+- **A CRLF checkout is no longer reported as skill drift.** Under `core.autocrlf=true`, git rewrote the
+  skill files the installer writes with LF, so `doctor` reported three untouched skills as `drifted` and
+  advised a refresh that produced LF for the next checkout to convert straight back (measured 2026-09-16,
+  Windows). `init`'s `.gitattributes` block now declares `.claude/skills/**/SKILL.md` and
+  `.agents/skills/**/SKILL.md` as `text eol=lf`, so checkout stops re-creating the difference. One
+  `holmes-kit skills refresh` converges an existing CRLF working tree.
+
+### Unchanged on purpose
+- **Autonomy did not widen with the new tokens.** Measured before the change: 36 A-SPECs in this
+  repository have prose-only Files to Touch and 8 of them would have gained tokens — one mentioning
+  `handlers.ts` in a sentence would have flipped from human approval to self-approval. The grader now
+  requires at least one directory-scoped token, so a spec whose tokens are all root-level files still asks
+  a human: a root-level file is project-wide configuration. A test walks every A-SPEC in the store and
+  asserts each verdict equals the pre-change verdict.
+- **The drift comparison is still byte-exact.** Folding CRLF into it was implemented, measured against
+  A-SPEC-190 §9a — whitespace-touched files are `drifted` *and a refresh reclaims them* — and reverted:
+  it would have made the first of those three mutations invisible rather than recoverable. That refusal
+  is pinned in the new suite.
+
+### Measured
+- macOS: 503 suites / 6,461 passed / 11 skipped; official `test_run` green, last-green recorded.
+- Still open: the Windows residual single-assertion reds. They need the failure text from the Windows box
+  (`npx jest --json`); nothing in this repository names why they fail, and guessing from a macOS run would
+  be inventing evidence.
+
+## [0.20.1] - 2026-09-16
+
+The Windows release. 0.20.0's external matrix was run natively on Windows 11 (Node 24, npm 12, pytest 9)
+and it found defects no POSIX run could see; this patch fixes them, then reconciles the result with the
+POSIX suite. Eighteen A-SPECs (651.1–651.5, 652.1–652.6, 653), each RED-first with an official run.
+
+### Fixed
+- **Every 3-way merge on Windows failed** (A-SPEC-652.6). `entity_integrate`'s merge tool pointed git's
+  global config at `\\.\nul`, which Windows git cannot open, so each merge reported
+  `merge-tool-failure`. It now uses `NUL` on win32 (`os.devNull` elsewhere).
+- **One path, two spellings** (A-SPEC-651.1). Reaching a workspace through an 8.3 short name
+  (`C:\Users\SUNGNA~1\…`) made entity adoption refuse its own store as `foreign-store` and keyed pytest
+  outcomes by a `../../…` path. Entity binding, execution context and the pytest cwd now judge with the
+  same canonical spelling `resolveProjectRoot` uses.
+- **The MCP server opens the right spec store** (A-SPEC-652.2). The store is resolved from
+  `CLAUDE_PROJECT_DIR`, then the nearest `.mcp.json`/`.ax` ancestor, then the cwd, and reported as an
+  absolute path; refusals name it.
+- **Lock retirement survives Windows' transient `EPERM`** (A-SPEC-652.5): the rename retries briefly, and a
+  reader treats those codes as a generation change instead of an error.
+- **A doctor probe that times out is retried once** and the failure reason is written into the detail
+  (A-SPEC-651.2) — a healthy install no longer exits 1 on a cold npx cache.
+- **`spec_slice_init` never overwrites** (A-SPEC-651.5): numbering counts both stores and an existing file
+  refuses the whole slice; **`spec_slice_approve` picks the mirror T-SPEC** (`A-SPEC-652.1 → T-SPEC-652.1`)
+  instead of the first base-number match, and refuses by name when there is none (A-SPEC-652.1).
+- **`test-support` modules no longer ship** in `dist` or the npm package.
+
+### Added
+- **`review-resolve` requests reach the decision inbox** (A-SPEC-651.4): resolving a critical finding
+  through `review_record` files a request `holmes-kit approve` can grant, and the grant is consumed.
+- **`doctor` names corrupted npx cache entries** (`npx cache` check, A-SPEC-652.2) — the cause of an MCP
+  server that dies at session start with `ENOENT … _npx/<hash>/package.json`. Filesystem reads only
+  (measured 0.18 ms).
+
+### Changed
+- **The test-case counter recognises the reporting skip** (A-SPEC-653): `posixOnly(reason)(…)` and its
+  siblings count as cases for ART-4, so a platform-conditional suite reports `skipped` on the other OS
+  instead of returning early and reading as a pass. Three suites converted.
+- Windows Jest budgets scale by a measured factor of 4 (test infrastructure only, A-SPEC-652.4).
+- `doctor`'s `Check`/`Level` types moved to their own module (an import cycle removed, A-SPEC-653).
+
+### Measured, stated limits
+- Windows native external matrix (`EVIDENCE-windows-native-matrix-2026-09-14.md`): every step passes from the
+  long-name path; the full Windows Jest run still carries pre-existing single-assertion reds that these
+  slices did not scope (`EVIDENCE-windows-followup-2026-09-15.md`). macOS: 501 suites green.
+- Open findings: the write gate cannot admit a root-level file named in Files to Touch (a token needs a
+  slash); `doctor`'s recovery-skill drift check compares bytes and reads CRLF checkouts as drifted.
+
 ## [0.20.0] - 2026-09-14
 
 The Concurrent Multi-Agent Workspace release. Several agents, machines and clones now work on one spec

package/README.md

@@ -302,7 +302,7 @@ Full per-cell bases (and every stated limit) live in [docs/language-support.md](
 | **macOS** | Apple Silicon (arm64) / Intel (x64) | ✅ Tier 1 | macOS 12+ (Full hook enforcement) |
 | **Linux** | x86_64 / arm64 | ✅ Tier 1 | Ubuntu, Debian, Fedora, Arch, RHEL. **Field-validated 2026-09-14** (Ubuntu 24.04 aarch64, OrbStack): tarball install, `init --agent all`, doctor, pytest RED→GREEN, Git integration, renumber, derived-state recovery and the approval round-trip, all from the external matrix probe |
 | **Windows (WSL2)** | x86_64 | ✅ Tier 1 | WSL2 Ubuntu/Debian recommended |
-| **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 (platform tier is decided by executed verification — internal decision record) for tier criteria and residual risks (NTFS 8.3 names, reserved device names, 260-char paths; no Windows CI yet) |
+| **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-09-14/15** (Windows 11, Node 24, npm 12, pytest 9): tarball install, `init --agent all`, doctor, pytest RED→GREEN, adoption, Git integration, renumber, derived-state recovery and the approval round-trip — the external matrix passes from the long-name path; 0.20.1 fixes the defects it found (8.3 short paths, the merge tool's global config, transient `EPERM`, npx cache corruption). Under **npm 12** declare `allowScripts` for `better-sqlite3` and `sharp` in the consuming project (doctor prints the exact entry). |
 
 > **Runtime Requirement**: Node.js `>= 20.0.0` (LTS recommended)
 >

package/dist/.build-id

@@ -1 +1 @@
-e2d9bd59-mu0pzf41
+5796f530-mu3b082d

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

@@ -0,0 +1,15 @@
+/**
+ * The doctor's verdict shape, in a module of its own.
+ *
+ * Measured 2026-09-16: `npx-cache-check.ts` imported `type Check` from `doctor.ts` while `doctor.ts`
+ * imported the check — an import cycle (A-SPEC-574.3), red on every POSIX run after the Windows
+ * merge. A check module must be able to name the shape it returns without importing the runner.
+ */
+export type Level = 'PASS' | 'WARN' | 'FAIL';
+export interface Check {
+    name: string;
+    level: Level;
+    detail: string;
+    fix?: string;
+    remediate?: () => boolean;
+}

package/dist/holmes/cli/doctor-check.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -11,14 +11,8 @@ export declare function resolvesToPackage(filePath: string, packageRoot: string)
  * hooks fail OPEN, so a broken install is silent: governance simply never fires. This command makes
  * that loud. Every check reports PASS/WARN/FAIL plus a concrete remediation.
  */
-export type Level = 'PASS' | 'WARN' | 'FAIL';
-export interface Check {
-    name: string;
-    level: Level;
-    detail: string;
-    fix?: string;
-    remediate?: () => boolean;
-}
+import type { Check, Level } from './doctor-check';
+export type { Check, Level } from './doctor-check';
 export interface DoctorOptions {
     run?: ProbeRunner;
     autoFix?: boolean;

package/dist/holmes/cli/doctor.js

@@ -64,6 +64,7 @@ const install_scripts_policy_1 = require("../project/install-scripts-policy");
 const native_deps_1 = require("./native-deps");
 const tier_1 = require("../semantic/tier");
 const probe_process_1 = require("./probe-process");
+const npx_cache_check_1 = require("./npx-cache-check");
 const path = __importStar(require("node:path"));
 const role_policy_1 = require("../governance/role-policy");
 const blind_spots_1 = require("../guardrail/blind-spots");
@@ -515,6 +516,11 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     //    before it answers (a false FAIL this check produced on its first run).
     if (built) {
         checks.push(await mcpHandshakeCheck(packageRoot));
+        // @implements A-SPEC-652.2 — the handshake above proves THIS install; the wiring may run a
+        // cached npx copy instead, and a corrupt cache entry dies before any handshake (measured
+        // 2026-09-15: "Connection closed" at session start, npm ENOENT on the entry's package.json).
+        if (target)
+            checks.push((0, npx_cache_check_1.checkNpxCache)(target, { env: process.env, homedir: os.homedir(), platform: process.platform, exists: fs.existsSync, readFile: (p) => fs.readFileSync(p, 'utf8'), readdir: (p) => fs.readdirSync(p) }));
         // @implements A-SPEC-323
         // Every wired harness, actually started. The check above proves THIS INSTALL can serve; these
         // prove the wiring each harness will really run reaches a server. Measured: 367ms for three.
@@ -1340,9 +1346,11 @@ cwd) {
                 return;
             done = true;
             clearTimeout(timer);
-            void (0, probe_process_1.stopProbeProcess)(child).then(released => resolve(released
+            // @implements A-SPEC-651.2 — the platform the spawn was adapted for is the platform the cleanup
+            // is judged on, and an unconfirmed cleanup names its reason (timeout vs refusal vs no close).
+            void (0, probe_process_1.stopProbeProcess)(child, { platform }).then(released => resolve(released
                 ? { name: 'mcp wiring spawn', level, detail, fix }
-                : { name: 'mcp wiring spawn', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed`,
+                : { name: 'mcp wiring spawn', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed (${(0, probe_process_1.lastProbeStopReason)() ?? 'unknown'})`,
                     fix: `${fix ?? ''} Close the remaining diagnostic process for \`${command}\`, then retry doctor.` }));
         };
         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 for \`${command}\`, then re-run doctor.`), timeoutMs);
@@ -1414,9 +1422,10 @@ function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
                     removed = true;
                 }
                 catch { /* signal cleanup retains the path for a later attempt */ }
+                const why = !released ? ((0, probe_process_1.lastProbeStopReason)() ?? 'unknown') : 'temp dir not removed';
                 resolve(released && removed
                     ? { name: 'MCP server', level, detail, fix }
-                    : { name: 'MCP server', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed`,
+                    : { name: 'MCP server', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed (${why})`,
                         fix: 'Close the remaining diagnostic process and retry doctor.' });
             });
         };

package/dist/holmes/cli/gitignore-merge.js

@@ -61,6 +61,16 @@ exports.ATTRIBUTE_LINES = [
     '# 남는 체인 이음새는 `holmes-kit ledger rechain`의 일이다.',
     '.ax/ledger/*.jsonl merge=union',
     '.ax/approvals/queue.jsonl merge=union',
+    // @implements A-SPEC-654
+    // The installer writes these with LF and doctor compares them byte for byte (A-SPEC-190 §9a: a
+    // whitespace-touched file is `drifted` so a refresh can reclaim it). Under `core.autocrlf=true`
+    // checkout rewrote them to CRLF, so three untouched skills read `drifted` and the advised refresh
+    // produced LF for the next checkout to convert straight back — measured 2026-09-16 on Windows.
+    // Declaring the files settles it where the disagreement is, instead of teaching the drift check to
+    // ignore a difference it exists to catch.
+    '# @implements A-SPEC-654 — 설치기가 LF 로 쓰는 파일은 체크아웃에서 CRLF 로 바뀌지 않는다.',
+    '.claude/skills/**/SKILL.md text eol=lf',
+    '.agents/skills/**/SKILL.md text eol=lf',
 ];
 /** As `mergeGitignore`, over `.gitattributes` — the same marker block machinery, so idempotence
  *  and user-content preservation are inherited rather than re-implemented. */

package/dist/holmes/cli/npx-cache-check.d.ts

@@ -0,0 +1,16 @@
+import type { Check } from './doctor-check';
+export interface NpxCacheDeps {
+    env: NodeJS.ProcessEnv;
+    homedir: string;
+    platform: NodeJS.Platform;
+    exists: (p: string) => boolean;
+    readFile: (p: string) => string;
+    readdir: (p: string) => string[];
+}
+/** The `-p <pkg>@<ver>` pin of the target's holmes-kit wiring, or null when it is not an npx pin. */
+export declare function npxPinOf(target: string, deps: Pick<NpxCacheDeps, 'exists' | 'readFile'>): {
+    pkg: string;
+    version: string;
+} | null;
+export declare function npmCacheRoot(deps: Pick<NpxCacheDeps, 'env' | 'homedir' | 'platform'>): string;
+export declare function checkNpxCache(target: string, deps: NpxCacheDeps): Check;

package/dist/holmes/cli/npx-cache-check.js

@@ -0,0 +1,130 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.npxPinOf = npxPinOf;
+exports.npmCacheRoot = npmCacheRoot;
+exports.checkNpxCache = checkNpxCache;
+// @implements A-SPEC-652.2
+/**
+ * doctor: is the npx cache entry the wiring will run intact?
+ *
+ * Measured 2026-09-15 on Windows: `.mcp.json` wires `npx -y -p @holmes-lab/holmes-kit@0.19.4
+ * holmes-mcp`; npx resolved it to `_npx/a739130c5322c549`, whose root `package.json` had gone, and
+ * died with `npm error ENOENT … package.json` before any handshake. The harness reported only
+ * "Connection closed". Six entries in that cache had the same shape (two of them this package).
+ *
+ * Filesystem only — no npm spawn: the cache root is `npm_config_cache`, else the platform default
+ * (`%LOCALAPPDATA%\npm-cache` on win32, `~/.npm` elsewhere). Only entries holding the PINNED version
+ * of the pinned package are judged; a corrupt entry of another version is not what this wiring runs.
+ */
+const path = __importStar(require("node:path"));
+const NAME = 'npx cache';
+/** The `-p <pkg>@<ver>` pin of the target's holmes-kit wiring, or null when it is not an npx pin. */
+function npxPinOf(target, deps) {
+    const mcpPath = path.join(target, '.mcp.json');
+    if (!deps.exists(mcpPath))
+        return null;
+    let server;
+    try {
+        server = JSON.parse(deps.readFile(mcpPath)).mcpServers?.['holmes-kit'];
+    }
+    catch {
+        return null;
+    }
+    if (!server || !/^npx(\.cmd)?$/i.test(String(server.command ?? '')) || !Array.isArray(server.args))
+        return null;
+    const at = server.args.indexOf('-p');
+    const spec = at >= 0 ? server.args[at + 1] : undefined;
+    const m = spec ? /^(@?[^@]+)@([0-9][^\s]*)$/.exec(spec) : null;
+    return m ? { pkg: m[1], version: m[2] } : null;
+}
+function npmCacheRoot(deps) {
+    const configured = deps.env.npm_config_cache;
+    if (configured && configured.trim() !== '')
+        return configured;
+    if (deps.platform === 'win32') {
+        const local = deps.env.LOCALAPPDATA && deps.env.LOCALAPPDATA.trim() !== '' ? deps.env.LOCALAPPDATA : path.join(deps.homedir, 'AppData', 'Local');
+        return path.join(local, 'npm-cache');
+    }
+    return path.join(deps.homedir, '.npm');
+}
+function checkNpxCache(target, deps) {
+    const pin = npxPinOf(target, deps);
+    if (!pin)
+        return { name: NAME, level: 'PASS', detail: 'the holmes-kit wiring is not an npx pin — nothing cached to judge' };
+    const npxDir = path.join(npmCacheRoot(deps), '_npx');
+    if (!deps.exists(npxDir))
+        return { name: NAME, level: 'PASS', detail: `${pin.pkg}@${pin.version} is not cached yet (${npxDir} absent) — the first launch installs it` };
+    let hashes = [];
+    try {
+        hashes = deps.readdir(npxDir);
+    }
+    catch {
+        return { name: NAME, level: 'PASS', detail: `${npxDir} could not be listed — nothing to judge` };
+    }
+    const matching = [];
+    const corrupt = [];
+    for (const hash of hashes) {
+        const entry = path.join(npxDir, hash);
+        const pkgJson = path.join(entry, 'node_modules', ...pin.pkg.split('/'), 'package.json');
+        if (!deps.exists(pkgJson))
+            continue;
+        let version;
+        try {
+            version = JSON.parse(deps.readFile(pkgJson)).version;
+        }
+        catch {
+            continue;
+        }
+        if (version !== pin.version)
+            continue;
+        matching.push(hash);
+        if (!deps.exists(path.join(entry, 'package.json')))
+            corrupt.push(hash);
+    }
+    if (matching.length === 0)
+        return { name: NAME, level: 'PASS', detail: `${pin.pkg}@${pin.version} is not cached yet under ${npxDir} — the first launch installs it` };
+    if (corrupt.length === 0)
+        return { name: NAME, level: 'PASS', detail: `${matching.length} intact npx cache entr${matching.length === 1 ? 'y' : 'ies'} for ${pin.pkg}@${pin.version}` };
+    const dirs = corrupt.map((h) => path.join(npxDir, h));
+    const remove = deps.platform === 'win32'
+        ? dirs.map((d) => `Remove-Item -Recurse -Force "${d}"`).join('; ')
+        : dirs.map((d) => `rm -rf ${d}`).join(' && ');
+    return {
+        name: NAME, level: 'FAIL',
+        detail: `npx cache entr${corrupt.length === 1 ? 'y' : 'ies'} ${corrupt.join(', ')} for ${pin.pkg}@${pin.version} ${corrupt.length === 1 ? 'is' : 'are'} missing its package.json — the wiring dies with \`npm error ENOENT\` before the handshake and the harness reports only "Connection closed" (${dirs.join(', ')})`,
+        fix: `Delete the corrupt entr${corrupt.length === 1 ? 'y' : 'ies'} and let the next launch reinstall: ${remove}`,
+    };
+}

package/dist/holmes/cli/probe-process.d.ts

@@ -1,8 +1,23 @@
-import { type ChildProcess } from 'node:child_process';
+import { execFile as nodeExecFile, type ChildProcess } from 'node:child_process';
 /** Each POSIX probe gets its own process group; Windows taskkill targets only its owned PID. */
 export declare const PROBE_SPAWN_OPTIONS: {
     detached: boolean;
     windowsHide: boolean;
 };
+/**
+ * A-SPEC-651.2 — budgets measured, not guessed. taskkill /T /F finished in 0.56–0.67 s on a quiet
+ * box (2026-09-14); the old 2.5 s budget, spent once, read "cleanup could not be confirmed" on a
+ * healthy install in 1 of 4 quiet doctor runs and 2 of 3 loaded ones. 8 s each, and a timed-out
+ * taskkill gets exactly one more try — a refused one does not (A-SPEC-592: a failed tree kill is never
+ * success).
+ */
+export declare const PROBE_KILL_TIMEOUT_MS = 8000;
+export declare const PROBE_CLOSE_TIMEOUT_MS = 8000;
+export interface ProbeStopDeps {
+    platform?: NodeJS.Platform;
+    execFile?: typeof nodeExecFile;
+}
+/** Why the most recent stopProbeProcess answered false; undefined after a confirmed cleanup. */
+export declare function lastProbeStopReason(): string | undefined;
 export declare function trackProbeProcess(child: ChildProcess): void;
-export declare function stopProbeProcess(child?: ChildProcess): Promise<boolean>;
+export declare function stopProbeProcess(child?: ChildProcess, deps?: ProbeStopDeps): Promise<boolean>;

package/dist/holmes/cli/probe-process.js

@@ -1,13 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROBE_SPAWN_OPTIONS = void 0;
+exports.PROBE_CLOSE_TIMEOUT_MS = exports.PROBE_KILL_TIMEOUT_MS = exports.PROBE_SPAWN_OPTIONS = void 0;
+exports.lastProbeStopReason = lastProbeStopReason;
 exports.trackProbeProcess = trackProbeProcess;
 exports.stopProbeProcess = stopProbeProcess;
 // @implements A-SPEC-592
+// @implements A-SPEC-651.2
 const node_child_process_1 = require("node:child_process");
 /** Each POSIX probe gets its own process group; Windows taskkill targets only its owned PID. */
 exports.PROBE_SPAWN_OPTIONS = { detached: process.platform !== 'win32', windowsHide: true };
+/**
+ * A-SPEC-651.2 — budgets measured, not guessed. taskkill /T /F finished in 0.56–0.67 s on a quiet
+ * box (2026-09-14); the old 2.5 s budget, spent once, read "cleanup could not be confirmed" on a
+ * healthy install in 1 of 4 quiet doctor runs and 2 of 3 loaded ones. 8 s each, and a timed-out
+ * taskkill gets exactly one more try — a refused one does not (A-SPEC-592: a failed tree kill is never
+ * success).
+ */
+exports.PROBE_KILL_TIMEOUT_MS = 8000;
+exports.PROBE_CLOSE_TIMEOUT_MS = 8000;
 const states = new WeakMap();
+let lastReason;
+/** Why the most recent stopProbeProcess answered false; undefined after a confirmed cleanup. */
+function lastProbeStopReason() { return lastReason; }
 function trackProbeProcess(child) {
     if (states.has(child))
         return;
@@ -15,30 +29,45 @@ function trackProbeProcess(child) {
     states.set(child, state);
     child.once('close', () => { state.closed = true; });
 }
-async function stopProbeProcess(child) {
+const isTimeout = (error) => {
+    const e = error;
+    return !!e && (e.killed === true || e.code === null || e.code === undefined);
+};
+async function stopProbeProcess(child, deps = {}) {
+    lastReason = undefined;
     if (!child)
         return true;
     trackProbeProcess(child);
+    const platform = deps.platform ?? process.platform;
+    const execFile = deps.execFile ?? node_child_process_1.execFile;
     let closed = states.get(child).closed;
     let onClose = () => { };
     let closeTimer;
     const closure = new Promise(resolve => {
         onClose = () => { closed = true; clearTimeout(closeTimer); resolve(true); };
         child.once('close', onClose);
-        closeTimer = setTimeout(() => resolve(false), 3000);
+        closeTimer = setTimeout(() => resolve(false), exports.PROBE_CLOSE_TIMEOUT_MS);
         if (closed || !child.pid)
             onClose();
     });
     let stopped = true;
+    let stopReason;
     try {
-        if (child.pid && process.platform === 'win32' && !closed) {
-            stopped = await new Promise(resolve => {
-                (0, node_child_process_1.execFile)('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: 2500 }, error => {
-                    resolve(!error);
-                });
+        if (child.pid && platform === 'win32' && !closed) {
+            const taskkill = () => new Promise(resolve => {
+                execFile('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: exports.PROBE_KILL_TIMEOUT_MS }, error => resolve(error ?? null));
             });
+            let error = await taskkill();
+            if (error && isTimeout(error))
+                error = await taskkill(); // one retry, for a timeout only
+            if (error) {
+                stopped = false;
+                stopReason = isTimeout(error)
+                    ? `taskkill timed out twice (${exports.PROBE_KILL_TIMEOUT_MS} ms each)`
+                    : `taskkill exited ${String(error.code)}`;
+            }
         }
-        else if (child.pid && process.platform !== 'win32') {
+        else if (child.pid && platform !== 'win32') {
             const signalGroup = (signal) => {
                 try {
                     process.kill(-child.pid, signal);
@@ -56,8 +85,9 @@ async function stopProbeProcess(child) {
             signalGroup('SIGKILL');
         }
     }
-    catch {
+    catch (error) {
         stopped = false;
+        stopReason = `kill failed: ${error.message}`;
     }
     // Terminate the tree before closing stdin: an EOF could make the wrapper exit first,
     // leaving Windows taskkill with no parent from which to enumerate its descendants.
@@ -69,5 +99,8 @@ async function stopProbeProcess(child) {
     child.removeListener('close', onClose);
     if (!released)
         child.unref();
-    return stopped && released;
+    const ok = stopped && released;
+    if (!ok)
+        lastReason = stopReason ?? `child never closed within ${exports.PROBE_CLOSE_TIMEOUT_MS} ms`;
+    return ok;
 }

package/dist/holmes/governance/approval-queue.js

@@ -78,8 +78,12 @@ exports.QUEUE_RELPATH = path.join('.ax', 'approvals', 'queue.jsonl');
 // single-shot gate refusals nobody ever meant to decide, burying the real inbox (spec-approve 9,
 // config-write 1) and accumulating raw shell commands in a tracked file. Only these kinds seek a
 // decision; everything else routes to the local per-replica refusal log below. Wired RED-first.
+// @implements A-SPEC-651.4 — `review-resolve` is a decision too: resolving an open critical needs a
+// human, review_record's refusal points that human at `holmes-kit approve`, and without this entry the
+// request went to the refusal log so the inbox stayed empty (measured 2026-09-14 on Windows: two
+// expired session dialogs, then `approve --list` answered "No requests awaiting approval").
 exports.DECISION_KINDS = new Set([
-    'spec-approve', 'config-write', 'autonomy-grant', 'spec-reappraisal',
+    'spec-approve', 'config-write', 'autonomy-grant', 'spec-reappraisal', 'review-resolve',
 ]);
 const REFUSALS_FILE_RE = /^refusals\.([^.]+)\.jsonl$/;
 function refusalsFilename(replica) {

package/dist/holmes/governance/autonomy.js

@@ -178,6 +178,12 @@ function specApprovalAutonomy(spec, resolveParent, descendants) {
                 return 'hitl';
             if (paths.some(isHighRiskPath))
                 return 'hitl'; // gate/governance/taint file
+            // @implements A-SPEC-654 — a ROOT-level file is project-wide configuration (the test runner, the
+            // manifest, the ignore policy): admitting it at the gate was the point of that slice, but grading
+            // it auto would be a widening nobody asked for. A spec earns self-approval only when it also names
+            // a directory-scoped surface — the same doubt `paths.length === 0` already encodes.
+            if (!paths.some((p) => p.includes('/')))
+                return 'hitl';
             return 'auto';
         }
         default:

package/dist/holmes/guardrail/scope-judgment.d.ts

@@ -29,7 +29,18 @@ export declare function isTestPath(relPath: string): boolean;
  * one bounded fragment, so no ReDoS surface.
  */
 export declare function matchesFtt(token: string, relPath: string): boolean;
-/** Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none. */
+export declare function isRootFileToken(token: string): boolean;
+/**
+ * Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none.
+ *
+ * @implements A-SPEC-654
+ * The slashed match alone could not see a ROOT-level file, so a sealed spec listing `- jest.config.js`
+ * admitted nothing at all and its own anchored write was refused as out of scope (measured 2026-09-15 on
+ * Windows; A-SPEC-652.4 was redesigned around it). A bare filename counts only as a LIST ITEM's first
+ * word: `- \`tsconfig.test.json\` (신규)` is a token, while `\`cfg.ts\`, \`ddg.ts\` 를 고친다` — prose, and a
+ * word carrying a comma — stays what it always was, nothing. The enforcer is unchanged: a root token
+ * admits that exact path (`matchesFtt`), and the grader requires a directory-scoped token of its own.
+ */
 export declare function fttPathTokens(fttText: string): string[];
 export interface ScopeInput {
     relPath: string;

package/dist/holmes/guardrail/scope-judgment.js

@@ -25,6 +25,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTestPath = isTestPath;
 exports.matchesFtt = matchesFtt;
+exports.isRootFileToken = isRootFileToken;
 exports.fttPathTokens = fttPathTokens;
 exports.judgeScope = judgeScope;
 /** Repo test conventions — the single census every dispensation consumer shares. */
@@ -63,9 +64,37 @@ function matchesFtt(token, relPath) {
         return relPath === tok; // file literal: that file only
     return relPath === tok || relPath.startsWith(tok + '/'); // dir literal: its subtree
 }
-/** Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none. */
+/**
+ * @implements A-SPEC-654
+ * A repository-ROOT file named as a Files-to-Touch item: a bare filename with an extension that starts
+ * with a letter, so a version (`0.20.1`) is not a file and a bare word (`README`) is not either.
+ */
+const ROOT_FILE = /^[\w@.-]+\.[A-Za-z][A-Za-z0-9]*$/;
+function isRootFileToken(token) {
+    return !token.includes('/') && ROOT_FILE.test(token);
+}
+/**
+ * Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none.
+ *
+ * @implements A-SPEC-654
+ * The slashed match alone could not see a ROOT-level file, so a sealed spec listing `- jest.config.js`
+ * admitted nothing at all and its own anchored write was refused as out of scope (measured 2026-09-15 on
+ * Windows; A-SPEC-652.4 was redesigned around it). A bare filename counts only as a LIST ITEM's first
+ * word: `- \`tsconfig.test.json\` (신규)` is a token, while `\`cfg.ts\`, \`ddg.ts\` 를 고친다` — prose, and a
+ * word carrying a comma — stays what it always was, nothing. The enforcer is unchanged: a root token
+ * admits that exact path (`matchesFtt`), and the grader requires a directory-scoped token of its own.
+ */
 function fttPathTokens(fttText) {
-    return fttText.match(/[\w@.*-]+(?:\/[\w@.*-]+)+/g) ?? [];
+    const tokens = [...(fttText.match(/[\w@.*-]+(?:\/[\w@.*-]+)+/g) ?? [])];
+    for (const line of fttText.split('\n')) {
+        const item = /^\s*[-*]\s+(.*)$/.exec(line);
+        if (!item)
+            continue;
+        const word = (item[1].trim().split(/\s+/)[0] ?? '').replace(/^[`'"]+|[`'"]+$/g, '');
+        if (isRootFileToken(word) && !tokens.includes(word))
+            tokens.push(word);
+    }
+    return tokens;
 }
 // @implements A-SPEC-508.1
 function judgeScope(input) {

package/dist/holmes/mcp/handlers/slice-orchestration.d.ts

@@ -16,6 +16,15 @@ export interface SliceOrchestrationContext {
         }): Promise<unknown>;
     };
 }
+/**
+ * @implements A-SPEC-652.1 — the T-SPEC that belongs to an A-SPEC, by the mirror rule the
+ * author-slice playbook states (the chain inherits the parent's number, dot included): the
+ * mirror id first, then a T-SPEC that declares `depends_on` on this exact A-SPEC, then — for an
+ * UNDOTTED id only — the old base-number match that kept legacy `T-SPEC-1291`-style ids working.
+ * Measured 2026-09-14: `spec_slice_approve('A-SPEC-651.2')` sealed `T-SPEC-651.1`, because the old
+ * `find` accepted any T-SPEC whose base number matched and .1 came first.
+ */
+export declare function tspecFor(aspec: Spec, specs: Spec[]): Spec | undefined;
 export declare function createSliceOrchestrationHandlers(context: SliceOrchestrationContext): {
     spec_slice_init(a: {
         root?: string;
@@ -25,8 +34,16 @@ export declare function createSliceOrchestrationHandlers(context: SliceOrchestra
         filesToTouch: string[];
     }): Promise<{
         ok: boolean;
+        reason: string;
+        existing: string[];
         specsCreated: string[];
         unreadable: string[];
+    } | {
+        ok: boolean;
+        specsCreated: string[];
+        unreadable: string[];
+        reason?: undefined;
+        existing?: undefined;
     }>;
     spec_slice_approve(a: {
         root?: string;

package/dist/holmes/mcp/handlers/slice-orchestration.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.tspecFor = tspecFor;
 exports.createSliceOrchestrationHandlers = createSliceOrchestrationHandlers;
 // @implements A-SPEC-609, A-SPEC-100.2, A-SPEC-156, A-SPEC-203, A-SPEC-204, A-SPEC-298, A-SPEC-299, A-SPEC-536.1, A-SPEC-546.1, A-SPEC-565.2, A-SPEC-587.2, A-SPEC-501.1
 const fs = __importStar(require("node:fs"));
@@ -42,6 +43,30 @@ const root_1 = require("../../project/root");
 const yaml_scalar_1 = require("../../spec/yaml-scalar");
 const draft_1 = require("../../reverse/draft");
 const anchor_comment_1 = require("../../rtm/anchor-comment");
+/**
+ * @implements A-SPEC-652.1 — the T-SPEC that belongs to an A-SPEC, by the mirror rule the
+ * author-slice playbook states (the chain inherits the parent's number, dot included): the
+ * mirror id first, then a T-SPEC that declares `depends_on` on this exact A-SPEC, then — for an
+ * UNDOTTED id only — the old base-number match that kept legacy `T-SPEC-1291`-style ids working.
+ * Measured 2026-09-14: `spec_slice_approve('A-SPEC-651.2')` sealed `T-SPEC-651.1`, because the old
+ * `find` accepted any T-SPEC whose base number matched and .1 came first.
+ */
+function tspecFor(aspec, specs) {
+    const number = aspec.id.replace(/^A-SPEC-/, '');
+    const mirror = specs.find((s) => s.type === 'T-SPEC' && s.id === `T-SPEC-${number}`);
+    if (mirror)
+        return mirror;
+    const dependent = specs.filter((s) => s.type === 'T-SPEC' && s.dependsOn.includes(aspec.id)).sort((a, b) => a.id.localeCompare(b.id))[0];
+    if (dependent)
+        return dependent;
+    if (number.includes('.'))
+        return undefined;
+    // Undotted only: the old base-number match (`T-SPEC-700.1` for `A-SPEC-700`) and the pre-REQ-187
+    // convention that appended one digit (`T-SPEC-1291` for `A-SPEC-129`).
+    const mainId = (id) => id.split('.')[0].replace(/\D/g, '');
+    const legacy = new RegExp(`^T-SPEC-${number}\\d$`);
+    return specs.find((s) => s.type === 'T-SPEC' && (mainId(s.id) === number || legacy.test(s.id)));
+}
 function createSliceOrchestrationHandlers(context) {
     return {
         async spec_slice_init(a) {
@@ -51,7 +76,11 @@ function createSliceOrchestrationHandlers(context) {
             // @implements A-SPEC-546.1 — align with the sibling reverse-draft path (nextIdBase, floor 100)
             // instead of a hard-coded 200 floor, so a fresh project starts at REQ-100, not REQ-201. Existing
             // projects are unchanged: nextIdBase returns max(existing)+1, which dominates the floor.
-            const nextId = (0, draft_1.nextIdBase)(existing.map((s) => s.id));
+            // @implements A-SPEC-651.5 — the number is never below EITHER store's max: the bound store's
+            // (the contract above) and the store the files are written to. Measured 2026-09-14: the bound
+            // store was empty, the id fell to 100 and the sealed REQ-100.md of the target was overwritten.
+            const targetIds = fs.existsSync(specsDir) ? (await new spec_store_1.LocalMarkdownRepository(specsDir).list()).map((s) => s.id) : [];
+            const nextId = (0, draft_1.nextIdBase)([...existing.map((s) => s.id), ...targetIds]);
             const reqId = `REQ-${nextId}`;
             const hspecId = `H-SPEC-${nextId}`;
             const aspecId = `A-SPEC-${nextId}`;
@@ -194,6 +223,16 @@ depends_on:
   When operation is performed
   Then boundary limits are respected
 `;
+            // @implements A-SPEC-651.5 — all or nothing, judged BEFORE the first byte: a target path that
+            // already exists (readable or not — the number cannot see an unparseable file) refuses the
+            // whole chain and names the files, so a sealed document is never replaced by a stub.
+            const targets = [
+                ['01_req', `${reqId}.md`], ['02_h-spec/functional', `${hspecId}.md`], ['03_a-spec', `${aspecId}.md`], ['05_t-spec', `${tspecId}.md`],
+            ];
+            const existingFiles = targets.filter(([dir, name]) => fs.existsSync(path.join(specsDir, dir, name))).map(([dir, name]) => `${dir}/${name}`);
+            if (existingFiles.length > 0) {
+                return { ok: false, reason: `spec_slice_init: ${existingFiles.length} target file(s) already exist — nothing written`, existing: existingFiles, specsCreated: [], unreadable: [] };
+            }
             fs.mkdirSync(path.join(specsDir, '01_req'), { recursive: true });
             fs.mkdirSync(path.join(specsDir, '02_h-spec', 'functional'), { recursive: true });
             fs.mkdirSync(path.join(specsDir, '03_a-spec'), { recursive: true });
@@ -225,12 +264,16 @@ depends_on:
                 return false;
             });
             const idsToApprove = [];
+            // @implements A-SPEC-652.1 — a dotted A-SPEC with no mirror and no dependent T-SPEC is named
+            // in `refused` AFTER the rest of the chain is sealed: the code gate stays shut without a
+            // T-SPEC, and a silent `ok:true` would read as "the slice is approved".
+            let missingTspec;
             if (inSlice.length > 0) {
                 const aspec = inSlice.find((s) => s.type === 'A-SPEC') ?? inSlice[0];
                 const mainId = (id) => id.split('.')[0].replace(/\D/g, '');
                 const req = specs.find((s) => aspec.dependsOn.includes(s.id) || mainId(s.id) === mainId(aspec.id));
                 const hspec = specs.find((s) => s.type === 'H-SPEC' && (s.dependsOn.includes(req?.id ?? '') || mainId(s.id) === mainId(aspec.id)));
-                const tspec = specs.find((s) => s.type === 'T-SPEC' && (s.dependsOn.includes(aspec.id) || mainId(s.id) === mainId(aspec.id)));
+                const tspec = tspecFor(aspec, specs);
                 if (req)
                     idsToApprove.push(req.id);
                 if (hspec)
@@ -238,6 +281,8 @@ depends_on:
                 idsToApprove.push(aspec.id);
                 if (tspec)
                     idsToApprove.push(tspec.id);
+                else if (aspec.type === 'A-SPEC' && aspec.id.includes('.'))
+                    missingTspec = `T-SPEC-${aspec.id.replace(/^A-SPEC-/, '')}`;
             }
             else {
                 const matches = specs.filter((s) => s.id.includes(a.sliceName));
@@ -281,6 +326,10 @@ depends_on:
             for (const id of idsToApprove.slice(approvedSpecs.length + alreadySealed.length + refused.length)) {
                 refused.push({ id, reason: 'not attempted — an earlier spec in the chain was refused' });
             }
+            if (missingTspec !== undefined) {
+                const aspecId = `A-SPEC-${missingTspec.replace(/^T-SPEC-/, '')}`;
+                refused.push({ id: missingTspec, reason: `no T-SPEC mirrors ${aspecId} or depends on it — write ${missingTspec} first` });
+            }
             // `ok` means the slice is approved — freshly or already. Anything less is not a success.
             return { ok: refused.length === 0 && approvedSpecs.length + alreadySealed.length > 0, approvedSpecs, alreadySealed, refused };
         },

package/dist/holmes/mcp/handlers.d.ts

@@ -590,9 +590,17 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         objective: string;
         filesToTouch: string[];
     }) => Promise<{
+        ok: boolean;
+        reason: string;
+        existing: string[];
+        specsCreated: string[];
+        unreadable: string[];
+    } | {
         ok: boolean;
         specsCreated: string[];
         unreadable: string[];
+        reason?: undefined;
+        existing?: undefined;
     }>;
     spec_slice_approve: (a: {
         root?: string;

package/dist/holmes/mcp/handlers.js

@@ -326,7 +326,9 @@ function assertSpecStoreReachable(tool, store, root) {
     // The tool name is NOT prefixed here: the raw-handler wrapper already prefixes it, and doing it
     // twice produced `spec_list: spec_list: ...` in the installed server (seen in the probe).
     void tool;
-    throw new HandlerRefusal(`이 서버가 바인딩된 스펙 디렉터리 ${store.specsRoot} 가 존재하지 않습니다 —`
+    // @implements A-SPEC-652.2 — the ABSOLUTE path, so the operator can see which directory was tried
+    // (a relative `.ax/specs` in this message told nobody where the server had looked, 2026-09-14).
+    throw new HandlerRefusal(`이 서버가 바인딩된 스펙 디렉터리 ${path.resolve(store.specsRoot)} 가 존재하지 않습니다 —`
         + ` 요청한 root ${root} 에는 스펙 저장소가 있습니다. 빈 답을 돌려주면 '스펙이 없다'로 읽히므로`
         + ' 거부합니다. 서버를 프로젝트 루트에서 시작하거나 HOLMES_SPECS 로 스펙 경로를 지정하십시오.');
 }

package/dist/holmes/mcp/server-specs-dir.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_SERVER_SPECS = ".ax/specs";
+export declare function resolveServerSpecsDir(env: NodeJS.ProcessEnv, cwd: string, exists?: (p: string) => boolean): string;

package/dist/holmes/mcp/server-specs-dir.js

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SERVER_SPECS = void 0;
+exports.resolveServerSpecsDir = resolveServerSpecsDir;
+// @implements A-SPEC-652.2
+/**
+ * Where the MCP server's spec store is. `HOLMES_SPECS` is written RELATIVE by `init` (`.ax/specs`,
+ * so the wiring file stays portable across machines) and used to be resolved against whatever cwd
+ * the server got. Measured 2026-09-14: a session's server refused every store-bound tool with
+ * "바인딩된 스펙 디렉터리 .ax/specs 가 존재하지 않습니다" — its cwd was not the project.
+ *
+ * The base for a relative path is, in order: `CLAUDE_PROJECT_DIR` (Claude Code sets it for every
+ * stdio MCP server to the stable project root — code.claude.com/docs/en/mcp), then the nearest
+ * ancestor of cwd holding `.mcp.json` or `.ax` (a server started in a sub-directory, or by a harness
+ * that sets no variable), then cwd itself (the old behaviour, for a project that has not run `init`).
+ * The answer is always absolute, so every refusal can name the directory it looked at.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+exports.DEFAULT_SERVER_SPECS = '.ax/specs';
+function resolveServerSpecsDir(env, cwd, exists = fs.existsSync) {
+    const configured = env.HOLMES_SPECS && env.HOLMES_SPECS.trim() !== '' ? env.HOLMES_SPECS : exports.DEFAULT_SERVER_SPECS;
+    if (path.isAbsolute(configured))
+        return path.normalize(configured);
+    const projectDir = env.CLAUDE_PROJECT_DIR;
+    if (projectDir && projectDir.trim() !== '' && exists(projectDir))
+        return path.resolve(projectDir, configured);
+    let dir = path.resolve(cwd);
+    for (;;) {
+        if (exists(path.join(dir, '.mcp.json')) || exists(path.join(dir, '.ax')))
+            return path.resolve(dir, configured);
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return path.resolve(cwd, configured);
+}

package/dist/holmes/mcp/server.js

@@ -11,7 +11,16 @@ const tool_schemas_1 = require("./tool-schemas");
 Object.defineProperty(exports, "HOOK_ENFORCED_TOOLS", { enumerable: true, get: function () { return tool_schemas_1.HOOK_ENFORCED_TOOLS; } });
 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');
+// @implements A-SPEC-652.2 — the store is opened at an ABSOLUTE path resolved against the project
+// root (CLAUDE_PROJECT_DIR, then the nearest .mcp.json/.ax ancestor, then cwd), and the path is
+// logged once to stderr (stdout is the protocol channel) so a mis-bound server is diagnosable.
+const { resolveServerSpecsDir } = require('./server-specs-dir');
+const SPECS_DIR = resolveServerSpecsDir(process.env, process.cwd());
+try {
+    process.stderr.write(`[Holmes-Kit] spec store: ${SPECS_DIR}\n`);
+}
+catch { /* a diagnostic must never keep the server from starting */ }
+const store = new spec_store_1.LocalMarkdownRepository(SPECS_DIR);
 // @implements A-SPEC-263.1 — the elicitation approval channel's wiring. The capability arrives at
 // initialize, AFTER this factory runs, so it is consulted lazily at CALL time.
 // @implements A-SPEC-497.1 — the three fates, told apart at THIS seam (the only place the SDK error

package/dist/holmes/project/execution-context.js

@@ -59,7 +59,8 @@ function validateExecution(value) {
 const scope = new node_async_hooks_1.AsyncLocalStorage();
 /** Internal entry-point boundary; an unavailable operator identity explicitly clears ambient scope. */
 function withOwnedExecution(root, execution, act) {
-    const owned = execution ? { root: fs.realpathSync(root), execution: validateExecution(execution) } : undefined;
+    // @implements A-SPEC-651.1 — the scope's root and every root compared against it share one spelling.
+    const owned = execution ? { root: (0, root_1.canonicalPath)(root), execution: validateExecution(execution) } : undefined;
     return scope.run(owned, act);
 }
 /** Writers may inherit only the context of the actual checkout that owns them. */
@@ -69,7 +70,7 @@ function executionForRoot(root) {
         return undefined;
     let actual = path.resolve(root);
     if (fs.existsSync(actual))
-        actual = fs.realpathSync(actual);
+        actual = (0, root_1.canonicalPath)(actual);
     if (actual !== active.root)
         throw new workspace_identity_1.WorkspaceIdentityError('foreign-execution', 'The writer belongs to a different execution workspace.');
     return active.execution;
@@ -102,7 +103,7 @@ function createExecutionScope(storeRoot, observe) {
         if (identity.state !== 'registered')
             throw new workspace_identity_1.WorkspaceIdentityError('unregistered-replica', 'Register this replica through workspace_identity before governance writes.');
         const execution = validateExecution({ schema: 'holmes-execution/1', workspaceId: identity.workspaceId, replicaId: identity.replicaId, runId });
-        return scope.run({ root: fs.realpathSync(bound.root), execution }, invoke);
+        return scope.run({ root: (0, root_1.canonicalPath)(bound.root), execution }, invoke);
     };
 }
 /** Validate observation attribution before an append; absence is never inferred from bad input. */

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

@@ -45,6 +45,15 @@ export declare const MARKER = ".ax";
  * makes: one spelling per directory, the spelling every path key is built from.
  */
 export declare const canonicalPath: (p: string) => string;
+/**
+ * @implements A-SPEC-651.1 — "the same directory" judged by ONE spelling. Every path that names a
+ * workspace or a store is canonicalised the way `resolveProjectRoot` canonicalises (`realpath.native`,
+ * so 8.3 aliases and symlinks collapse); a path that does not exist compares by its resolved spelling.
+ * `realpath` is injectable so the 8.3 scenario runs on every OS in the tests. Measured 2026-09-14
+ * (WIN0200-20260914-SHORTPATH): `entityStoreBinding` compared JS `fs.realpathSync` output against a
+ * native-canonical root, so a workspace entered as `C:\Users\SUNGNA~1\…` was refused as foreign.
+ */
+export declare function sameCanonicalDirectory(a: string, b: string, realpath?: (p: string) => string): boolean;
 export declare function resolveProjectRoot(dir: string, opts?: {
     includeGit?: boolean;
 }): ProjectRoot;

package/dist/holmes/project/root.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.canonicalPath = exports.MARKER = void 0;
 exports.cleanSubprocessEnv = cleanSubprocessEnv;
 exports.cleanTestEnv = cleanTestEnv;
+exports.sameCanonicalDirectory = sameCanonicalDirectory;
 exports.resolveProjectRoot = resolveProjectRoot;
 // @implements A-SPEC-205, A-SPEC-627
 // @implements A-SPEC-128
@@ -111,6 +112,23 @@ exports.MARKER = '.ax';
 const canonicalPath = (p) => fs.realpathSync.native(p);
 exports.canonicalPath = canonicalPath;
 const canonical = exports.canonicalPath;
+/**
+ * @implements A-SPEC-651.1 — "the same directory" judged by ONE spelling. Every path that names a
+ * workspace or a store is canonicalised the way `resolveProjectRoot` canonicalises (`realpath.native`,
+ * so 8.3 aliases and symlinks collapse); a path that does not exist compares by its resolved spelling.
+ * `realpath` is injectable so the 8.3 scenario runs on every OS in the tests. Measured 2026-09-14
+ * (WIN0200-20260914-SHORTPATH): `entityStoreBinding` compared JS `fs.realpathSync` output against a
+ * native-canonical root, so a workspace entered as `C:\Users\SUNGNA~1\…` was refused as foreign.
+ */
+function sameCanonicalDirectory(a, b, realpath = exports.canonicalPath) {
+    const spell = (p) => { try {
+        return realpath(p);
+    }
+    catch {
+        return path.resolve(p);
+    } };
+    return spell(a) === spell(b);
+}
 function gitTopLevel(dir) {
     try {
         // stderr silenced: "not a git repository" is an expected branch here, not a fault worth printing.

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

@@ -475,7 +475,10 @@ function runPytest(files, mode, cwd) {
         return outcomes;
     };
     try {
-        const out = (0, node_child_process_1.execFileSync)(python, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: RUNNER_MAX_BUFFER, env: (0, root_1.cleanTestEnv)() });
+        // @implements A-SPEC-651.1 — launch from the canonical spelling: pytest keys its JUnit `file`
+        // attribute relative to its rootdir, and an 8.3 invocation dir made that key climb out of the
+        // project (`../../…/tests/test_calc.py`, measured 2026-09-14 on Windows).
+        const out = (0, node_child_process_1.execFileSync)(python, args, { cwd: fs.existsSync(cwd) ? (0, root_1.canonicalPath)(cwd) : cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: RUNNER_MAX_BUFFER, env: (0, root_1.cleanTestEnv)() });
         return { passed: true, tail: tailOf(out), executed: read(), outcomes: readOutcomes(true) };
     }
     catch (e) {

package/dist/holmes/rtm/test-scope.js

@@ -172,7 +172,10 @@ const FRAMEWORKS = [
         suiteSkip: /\bdescribe\s*(?:\.\s*skip|\[\s*['"]skip['"]\s*\])|\bxdescribe\b/,
         // Head must be a STANDALONE identifier (not `.test(`/`.it(` method calls) followed directly by
         // `(` or by `.each(...)(`: `it.skip(`/`it.todo(`/`xit(` never match — no subtraction needed.
-        head: /(?<![.\w])(?:it|test|fit)(?:\s*\.\s*each\s*\([^)]*\)\s*)?\s*\(/g,
+        // @implements A-SPEC-653 — the platform helpers of A-SPEC-220.3 (`posixOnly('why')(…)`) are heads too:
+        // a POSIX-only suite written with the REPORTING skip must not read as "no real cases" (measured: that
+        // is why two suites had used a bare early return instead). `.skip` on a helper is still not a head.
+        head: /(?<![.\w])(?:it|test|fit|(?:posixOnly|posixOnlyNonRoot|posixOnlyWithCommand|win32Only)\s*\([^)]*\))(?:\s*\.\s*each\s*\([^)]*\)\s*)?\s*\(/g,
     },
     {
         id: 'pytest',

package/dist/holmes/spec/entity-integration.d.ts

@@ -103,6 +103,15 @@ export interface EntityGitFileMerge {
     };
 }
 /** Merge already-normalized bytes. Scratch files are not a materialized Holmes workspace. */
+/**
+ * @implements A-SPEC-652.6 — the environment `git merge-file` runs in: the caller's GIT_* stripped,
+ * the system and global configs blocked, the ceiling at the scratch parent. The "empty global
+ * config" is `os.devNull` on POSIX; on Windows `os.devNull` is `\\.\nul`, which git cannot open as
+ * a config file (`fatal: unable to access '\\.\nul': Invalid argument`, status 128 — measured
+ * 2026-09-15), so every content merge there was reported as a merge-tool-failure conflict. `NUL`
+ * is the spelling git accepts on that platform.
+ */
+export declare function mergeToolEnv(base: NodeJS.ProcessEnv, scratch: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
 export declare function mergeEntityGitFile(base: EntityGitFileVersion | null, left: EntityGitFileVersion | null, right: EntityGitFileVersion | null): EntityGitFileMerge;
 export interface EntityGitSourceBranch {
     files: Array<{

package/dist/holmes/spec/entity-integration.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.unchangedNonRegular = unchangedNonRegular;
 exports.planEntityGitMergedSources = planEntityGitMergedSources;
+exports.mergeToolEnv = mergeToolEnv;
 exports.mergeEntityGitFile = mergeEntityGitFile;
 exports.planEntityGitSources = planEntityGitSources;
 exports.planEntityGitDocuments = planEntityGitDocuments;
@@ -250,6 +251,24 @@ async function planEntityGitMergedSources(root, revisions, storeLocator) {
     return result;
 }
 /** Merge already-normalized bytes. Scratch files are not a materialized Holmes workspace. */
+/**
+ * @implements A-SPEC-652.6 — the environment `git merge-file` runs in: the caller's GIT_* stripped,
+ * the system and global configs blocked, the ceiling at the scratch parent. The "empty global
+ * config" is `os.devNull` on POSIX; on Windows `os.devNull` is `\\.\nul`, which git cannot open as
+ * a config file (`fatal: unable to access '\\.\nul': Invalid argument`, status 128 — measured
+ * 2026-09-15), so every content merge there was reported as a merge-tool-failure conflict. `NUL`
+ * is the spelling git accepts on that platform.
+ */
+function mergeToolEnv(base, scratch, platform = process.platform) {
+    const env = { ...base };
+    for (const key of Object.keys(env))
+        if (key.startsWith('GIT_'))
+            delete env[key];
+    env.GIT_CONFIG_NOSYSTEM = '1';
+    env.GIT_CONFIG_GLOBAL = platform === 'win32' ? 'NUL' : os.devNull;
+    env.GIT_CEILING_DIRECTORIES = path.dirname(scratch);
+    return env;
+}
 function mergeEntityGitFile(base, left, right) {
     const copy = (version) => version && ({ mode: version.mode, bytes: Buffer.from(version.bytes) });
     const inputs = { base: copy(base), left: copy(left), right: copy(right) };
@@ -287,13 +306,7 @@ function mergeEntityGitFile(base, left, right) {
     try {
         for (const [name, version] of Object.entries({ base, left, right }))
             fs.writeFileSync(path.join(scratch, name), version.bytes, { mode: 0o600 });
-        const env = { ...process.env };
-        for (const key of Object.keys(env))
-            if (key.startsWith('GIT_'))
-                delete env[key];
-        env.GIT_CONFIG_NOSYSTEM = '1';
-        env.GIT_CONFIG_GLOBAL = os.devNull;
-        env.GIT_CEILING_DIRECTORIES = path.dirname(scratch);
+        const env = mergeToolEnv(process.env, scratch);
         const merged = (0, node_child_process_1.spawnSync)('git', ['merge-file', '--stdout', '--diff3', '-L', 'left', '-L', 'base', '-L', 'right', '--', 'left', 'base', 'right'], { cwd: scratch, env, maxBuffer: limit });
         if (merged.error || merged.status === null || merged.status > 127)
             return conflict('merge-tool-failure');

package/dist/holmes/spec/entity-store.js

@@ -74,13 +74,15 @@ function entityStoreBinding(storeRoot) {
     const resolved = (0, root_1.resolveProjectRoot)(ancestor, { includeGit: false });
     if (resolved.marker !== '.ax')
         throw new entity_transaction_1.EntityStoreError('missing-workspace', 'The configured store must belong to a Holmes workspace.');
-    const root = fs.realpathSync(resolved.root);
+    // @implements A-SPEC-651.1 — the same canonical spelling resolveProjectRoot used (realpath.native):
+    // an 8.3 alias on Windows or /var on macOS collapses on both sides of the comparison.
+    const root = (0, root_1.canonicalPath)(resolved.root);
     // The workspace may be reached through a platform alias (/var on macOS).
     // Normalize that prefix only; retain components inside it for symlink checks.
     let spelling = ancestor;
-    while (fs.realpathSync(spelling) !== root && path.dirname(spelling) !== spelling)
+    while (!(0, root_1.sameCanonicalDirectory)(spelling, root) && path.dirname(spelling) !== spelling)
         spelling = path.dirname(spelling);
-    if (fs.realpathSync(spelling) !== root)
+    if (!(0, root_1.sameCanonicalDirectory)(spelling, root))
         throw new entity_transaction_1.EntityStoreError('foreign-store', 'The configured store does not descend from the workspace.');
     const relative = path.relative(spelling, store);
     if (!relative || relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative))

package/dist/holmes/spec/entity-transaction.d.ts

@@ -72,6 +72,22 @@ export declare function settleEntityTransients(root: string, steps: EntityByteCh
  * after the move-aside is refused and both files are preserved.
  */
 export declare function applyEntityByteChange(root: string, change: EntityByteChange): void;
+/**
+ * @implements A-SPEC-652.5 — Windows refuses to rename a directory while another process holds a
+ * file inside it open, and answers EPERM (EBUSY/EACCES in other shapes). A reader of the lock
+ * (entityLockOwner) holds owner.json for microseconds, so the writer's retirement rename raced it
+ * and died with `EPERM: operation not permitted, rename …/entity-locks/<hash> ->
+ * …/entity-retired-locks/<uuid>` (measured 2026-09-15 beside a looping reader). These codes are
+ * TRANSIENT there: retry briefly, on win32 only, for these codes only, within a fixed budget.
+ */
+export declare function isTransientWindowsFsError(e: unknown): boolean;
+export declare function renameWithTransientRetry(from: string, to: string, deps?: {
+    rename?: (from: string, to: string) => void;
+    platform?: NodeJS.Platform;
+    attempts?: number;
+    delayMs?: number;
+    sleep?: (ms: number) => void;
+}): void;
 /** The shared source-publication coordination namespace, independent of every configured spec store (A-SPEC-634: exported so recovery can release it without importing the renumber module). */
 export declare const SOURCE_PUBLICATION_LOCATOR = ".ax/state/entity-renumber-source-publication";
 /** Age after which a `.staging-*` entry beside the locks is treated as abandoned by a publisher that died before its rename (A-SPEC-633). */

package/dist/holmes/spec/entity-transaction.js

@@ -49,6 +49,8 @@ exports.isEntityTransientName = isEntityTransientName;
 exports.observeEntityTarget = observeEntityTarget;
 exports.settleEntityTransients = settleEntityTransients;
 exports.applyEntityByteChange = applyEntityByteChange;
+exports.isTransientWindowsFsError = isTransientWindowsFsError;
+exports.renameWithTransientRetry = renameWithTransientRetry;
 exports.withEntityStoreLock = withEntityStoreLock;
 exports.withEntityStoreLockAsync = withEntityStoreLockAsync;
 exports.entityLockHolderAlive = entityLockHolderAlive;
@@ -219,7 +221,11 @@ function entityLockOwner(root, locator) {
             bytes = readEntityBytes(path.join(dir, 'owner.json'));
         }
         catch (e) {
-            vanished = e.code === 'ENOENT' || (e instanceof EntityStoreError && e.code === 'entity-state-changed');
+            // A-SPEC-652.5 — on Windows a file inside a directory that is being renamed away answers
+            // EPERM/EBUSY for the instant of the rename: the generation is changing under the reader,
+            // the same fact ENOENT reports on POSIX.
+            vanished = e.code === 'ENOENT' || (e instanceof EntityStoreError && e.code === 'entity-state-changed')
+                || (process.platform === 'win32' && isTransientWindowsFsError(e));
             if (!vanished)
                 throw e;
         }
@@ -456,6 +462,40 @@ function applyEntityByteChange(root, change) {
             fs.unlinkSync(temp);
     }
 }
+/**
+ * @implements A-SPEC-652.5 — Windows refuses to rename a directory while another process holds a
+ * file inside it open, and answers EPERM (EBUSY/EACCES in other shapes). A reader of the lock
+ * (entityLockOwner) holds owner.json for microseconds, so the writer's retirement rename raced it
+ * and died with `EPERM: operation not permitted, rename …/entity-locks/<hash> ->
+ * …/entity-retired-locks/<uuid>` (measured 2026-09-15 beside a looping reader). These codes are
+ * TRANSIENT there: retry briefly, on win32 only, for these codes only, within a fixed budget.
+ */
+function isTransientWindowsFsError(e) {
+    const code = e?.code;
+    return code === 'EPERM' || code === 'EBUSY' || code === 'EACCES';
+}
+const sleepSync = (ms) => { try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+catch { /* a runtime without Atomics.wait retries without waiting */ } };
+function renameWithTransientRetry(from, to, deps = {}) {
+    const rename = deps.rename ?? ((a, b) => fs.renameSync(a, b));
+    const platform = deps.platform ?? process.platform;
+    const attempts = Math.max(1, deps.attempts ?? 50);
+    const delayMs = deps.delayMs ?? 20;
+    const sleep = deps.sleep ?? sleepSync;
+    for (let attempt = 1;; attempt++) {
+        try {
+            rename(from, to);
+            return;
+        }
+        catch (e) {
+            if (platform !== 'win32' || !isTransientWindowsFsError(e) || attempt >= attempts)
+                throw e;
+            sleep(delayMs);
+        }
+    }
+}
 function retireOwnedLock(root, dir, expected, owned) {
     const current = entityStat(dir);
     if (current?.dev !== expected.dev || current?.ino !== expected.ino)
@@ -468,7 +508,7 @@ function retireOwnedLock(root, dir, expected, owned) {
     if (entityStat(destination))
         throw new EntityStoreError('retirement-conflict', 'Lock retirement destination is occupied.');
     // Release the active pathname in one step, retaining owner evidence until then.
-    fs.renameSync(dir, destination);
+    renameWithTransientRetry(dir, destination);
     for (const file of owned)
         fs.unlinkSync(path.join(destination, path.basename(file)));
     fs.rmdirSync(destination);

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",
@@ -59,7 +59,10 @@
     "testMatch": [
       "**/src/**/*.test.ts"
     ],
-    "testTimeout": 30000
+    "testTimeout": 30000,
+    "setupFilesAfterEnv": [
+      "<rootDir>/src/holmes/test-support/jest-timeouts-setup.ts"
+    ]
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",