@holmes-lab/holmes-kit 0.1.15 → 0.1.17

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.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.
+
+### Added
+- **spec_create refuses a wild id (REQ-252)**: a new id whose base number leaps past
+  `max(base) + 1` is refused, naming the next available number. `spec_slice_init` assigns
+  `max + 1`, which is only predictable while numbering stays sequential — a single hand-picked
+  id (REQ-1403) once dragged the max to 1403 and every slice after jumped to 1404. The guard
+  closes the one door that let a manual id in, so `max + 1` can never be poisoned again.
+  Gap-fills, chain completion (base == max), and sub-slices (250.1) still pass; slice_init is
+  unaffected. Pure `sequentialIdVerdict`, injected id list — no filesystem.
+
+### Changed
+- **Spec numbering restructured for readability**: the MCP drift fix shipped in 0.1.15 as two
+  top-level REQs (1404/1405) that were really one problem. Refiled under this repo's own
+  sub-slice convention as REQ-251 with A-SPEC-251.1 (npx wiring) and A-SPEC-251.2 (doctor
+  drift). The out-of-sequence REQ-1403 was renumbered to its rightful 250. Code `@implements`
+  anchors moved with them. No runtime behavior change — ids and anchors only; the 0.1.15
+  features are byte-identical.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.1.15] - 2026-08-23
 

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 @@
-d6b14ca-mt5ea641
+e6199ca-mt5qbc5d

package/dist/holmes/cli/agents.js

@@ -70,7 +70,7 @@ exports.HARNESS_ENFORCES = {
     codex: false,
 };
 const q = (p) => p;
-// @implements A-SPEC-1404 — same launch contract as the Claude wiring: npx-pin for installed
+// @implements A-SPEC-251.1 — same launch contract as the Claude wiring: npx-pin for installed
 // packageRoots, node for source checkouts. Shared via mcpEntryForInstall so all three harnesses
 // move together.
 const mcpConfig = (packageRoot, specsDir, launcher) => {
@@ -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/doctor.js

@@ -456,7 +456,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         else {
             add('approval channel', 'WARN', '이 프로세스에는 HOLMES_APPROVAL이 있으나 .mcp.json의 서버 환경에는 없습니다 — spec_approve는 서버 환경을 읽습니다', 'settings.local.json의 env가 MCP 서버까지 전달된다는 보장은 없습니다. 그 변수를 설정한 셸에서 Claude Code를 띄우면 자식 서버가 상속합니다.');
         }
-        // @implements A-SPEC-1405 — the version this project's MCP server will ACTUALLY launch, vs this
+        // @implements A-SPEC-251.2 — the version this project's MCP server will ACTUALLY launch, vs this
         // CLI. The stale-global trap (measured 2026-08-23: .mcp.json pinned a 0.1.9 global while the user
         // believed they had upgraded) was invisible because nothing compared them. Offline: the launch
         // version comes from the wiring string, or a node wiring's LOCAL package.json — never the registry.

package/dist/holmes/cli/index.js

@@ -429,7 +429,7 @@ async function main(argv) {
     }
     if (cmd === 'init') {
         const mode = (typeof flags.mode === 'string' ? flags.mode : 'guardrail');
-        // @implements A-SPEC-1404 — an unknown launch mode is refused, not defaulted: substituting a
+        // @implements A-SPEC-251.1 — an unknown launch mode is refused, not defaulted: substituting a
         // default acts where the operator did not point (REQ-144). Only npx|node are wiring modes.
         let mcpLauncher;
         if (typeof flags['mcp-launcher'] === 'string') {

package/dist/holmes/cli/init.js

@@ -310,7 +310,7 @@ function runInit(opts) {
             const kept = Object.keys(prevEnv).filter((k) => !settings_merge_2.HOLMES_OWNED_MCP_ENV.includes(k));
             if (kept.length > 0)
                 messages.push(`Preserved your MCP server env: ${kept.join(', ')}`);
-            // @implements A-SPEC-1404 — compute the launch entry once (npx-pin for installs, node for source),
+            // @implements A-SPEC-251.1 — compute the launch entry once (npx-pin for installs, node for source),
             // then merge; env preservation is unchanged.
             const mcpEntry = (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: mcpBin, flag: opts.mcpLauncher });
             changes.push({ path: mcpPath, before: m.raw, after: JSON.stringify((0, settings_merge_1.mergeMcpServers)(m.value, exports.SERVER_NAME, mcpEntry, opts.specsDir), null, 2) + '\n' });

package/dist/holmes/cli/mcp-launcher.d.ts

@@ -3,7 +3,7 @@
  *
  * 왜 한 곳인가: `.mcp.json`(Claude)·`.agents/mcp_config.json`(antigravity)·`.codex/mcp_config.json`
  * 세 배선이 같은 서버를 띄운다. 셋이 각자 command/args 를 지으면 하나가 npx 로 옮겨갈 때 나머지가
- * 절대경로에 남아 어긋난다 — 그 드리프트가 REQ-1404 자체의 출발점이었다.
+ * 절대경로에 남아 어긋난다 — 그 드리프트가 REQ-251 자체의 출발점이었다.
  *
  * 왜 두 모드인가: 최종 사용자는 npm 설치본에서 init 하므로 `npx ...@<정확한버전> holmes-mcp` 가
  * 옳다 — 전역 설치도 `-g` 도 필요 없고(Windows EPERM 회피), 절대경로 고착이 없다. 그러나 개발
@@ -45,7 +45,7 @@ export declare function readPackageVersion(packageRoot: string): string | undefi
  * 세 배선(Claude/antigravity/codex)이 공유하는 조립: 모드 판별 → 버전 읽기 → entry.
  *
  * npx 로 판별됐어도 버전을 못 읽으면 node 로 물러난다 — 빈 핀(`@holmes-lab/holmes-kit@`)을 박느니
- * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-1404 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
+ * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-251.1 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
  */
 export declare function mcpEntryForInstall(opts: {
     packageRoot: string;

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

@@ -38,7 +38,7 @@ exports.mcpServerEntry = mcpServerEntry;
 exports.resolveLauncherMode = resolveLauncherMode;
 exports.readPackageVersion = readPackageVersion;
 exports.mcpEntryForInstall = mcpEntryForInstall;
-// @implements A-SPEC-1404
+// @implements A-SPEC-251.1
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 /** npm 상의 정식 패키지 이름. 핀은 이 이름에 정확한 버전을 붙인다. */
@@ -83,7 +83,7 @@ function readPackageVersion(packageRoot) {
  * 세 배선(Claude/antigravity/codex)이 공유하는 조립: 모드 판별 → 버전 읽기 → entry.
  *
  * npx 로 판별됐어도 버전을 못 읽으면 node 로 물러난다 — 빈 핀(`@holmes-lab/holmes-kit@`)을 박느니
- * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-1404 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
+ * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-251.1 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
  */
 function mcpEntryForInstall(opts) {
     const mode = resolveLauncherMode({ flag: opts.flag, packageRoot: opts.packageRoot });

package/dist/holmes/cli/mcp-version.d.ts

@@ -1,7 +1,7 @@
 /**
  * `.mcp.json` 배선이 **실제로 띄울** holmes-kit 버전을, 네트워크 없이 로컬로 뽑는다.
  *
- * 이 판정이 없어서 사용자의 전역 0.1.9 정체를 아무 진단도 보지 못했다(REQ-1405). 레지스트리를
+ * 이 판정이 없어서 사용자의 전역 0.1.9 정체를 아무 진단도 보지 못했다(REQ-251). 레지스트리를
  * 묻지 않는다 — 배선 문자열과, node 배선인 경우 주입된 로컬 reader 만 본다. reader 를 안 주면 node
  * 경로는 판정 불능(null)이지 실제 fs 를 더듬지 않는다: 순수성이 [offline] 을 시험 가능하게 한다.
  */

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

@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mcpLaunchVersion = mcpLaunchVersion;
 exports.versionDriftVerdict = versionDriftVerdict;
-// @implements A-SPEC-1405
+// @implements A-SPEC-251.2
 const path = __importStar(require("node:path"));
 /** npx 인자에서 핀 버전을 뽑는 정규식: `@holmes-lab/holmes-kit@<X>` 의 X. `@` 없는 스펙은 안 잡힌다. */
 const NPX_PIN = /^@holmes-lab\/holmes-kit@(.+)$/;

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

@@ -90,7 +90,7 @@ function disableMcpServer(existing, name) {
  * put it there.
  */
 exports.HOLMES_OWNED_MCP_ENV = ['HOLMES_SPECS'];
-// @implements A-SPEC-1404
+// @implements A-SPEC-251.1
 // The server entry (command/args) is COMPUTED by the caller (mcp-launcher: npx-pin for installs,
 // node for source checkouts) rather than assembled here, so all three harness wirings share one
 // launch contract. This merge owns only env preservation, not how the server is launched.

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

@@ -138,6 +138,7 @@ const ignore_1 = require("../project/ignore");
 // @implements A-SPEC-126
 const scan_1 = require("../reverse/scan");
 const draft_1 = require("../reverse/draft");
+const spec_id_guard_1 = require("./spec-id-guard");
 const anchor_1 = require("../reverse/anchor");
 // @implements A-SPEC-128
 // Where a project begins, for tools that only walk the tree.
@@ -261,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;
@@ -300,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;
@@ -593,6 +594,16 @@ function makeRawHandlers(store) {
                     return { ok: false, reason: `depends_on "${String(pid)}"는 ${ptype}입니다 — ${def.type}의 부모는 ${def.parents.join('|') || '없음(빈 depends_on)'}이어야 합니다.` };
                 }
             }
+            // @implements A-SPEC-252
+            // A new id may not LEAP past the sequence. spec_slice_init assigns nextId = max(base)+1, which
+            // is only predictable while numbering stays sequential; a hand-picked wild id (REQ-1403) once
+            // dragged max to 1403 and every slice after jumped to 1404. Refused here, at the one door that
+            // lets a manual id in — so max+1 can never be poisoned again. After the shape check on purpose:
+            // an id whose base cannot be read is the shape check's to name, not this guard's.
+            const corpus = await store.list();
+            const seq = (0, spec_id_guard_1.sequentialIdVerdict)(String(id), corpus.map((s) => s.id));
+            if (!seq.ok)
+                return { ok: false, reason: seq.reason };
             // @implements A-SPEC-188
             // Creation creates. Probed before this check existed: spec_create over an approved+sealed
             // REQ returned {"created"} while the disk went draft / seal gone / prose gone — the sanctioned
@@ -600,7 +611,7 @@ function makeRawHandlers(store) {
             // refusals on purpose: a malformed id must keep its own message (order is pinned by test).
             // Legacy (typeless) documents count as existing too — overwriting one makes the store's
             // orphan removal delete the differently-named original file along with its history.
-            const existing = (await store.list()).find((s) => s.id === id);
+            const existing = corpus.find((s) => s.id === id);
             if (existing) {
                 const sealed = existing.status === 'approved' || Boolean(existing.frontmatter?.approved_digest);
                 const kind = existing.type ? `${existing.type} (status: ${existing.status})` : `옛 형식 문서 (status: ${existing.status})`;

package/dist/holmes/mcp/spec-id-guard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 넘버링 오염을 생성 시점에 막는 순수 가드.
+ *
+ * spec_slice_init 의 `nextId = max(base) + 1` 은 번호가 항상 순차 배정될 때만 예측 가능하다. 그런데
+ * spec_create 는 id 형태만 보고 순번은 보지 않아, 손으로 심은 wild id(REQ-1403) 하나가 max 를 끌어올려
+ * 이후 모든 슬라이스를 오염시켰다(실측: 249→1404). 이 가드는 그 하나의 구멍을 막는다 — 새 base 는
+ * 현재 max 를 한 칸 넘게 뛸 수 없다. 막으면 max+1 은 다시 오염되지 않고 넘버링이 영구히 예측 가능하다.
+ */
+/** id 의 base 숫자. "REQ-1403"→1403, "A-SPEC-250.1"→250(서브번호 무시), 레거시 "H-SPEC-050"→50. 못 뽑으면 null. */
+export declare function specIdBase(id: string): number | null;
+export type IdVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    nextAvailable: number;
+};
+/**
+ * 새 id 의 base 가 코퍼스 max base 를 한 칸 넘게 뛰면 거부한다.
+ *
+ * - 빈 코퍼스, 또는 base 를 못 뽑는 id → 통과(비교 대상이 없거나, 형태 검증은 별도 소관이라 한 결함에
+ *   두 이름을 주지 않는다).
+ * - base ≤ maxBase(갭 메우기·체인 완성) 또는 base == maxBase+1(새 체인) → 통과.
+ * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
+ */
+export declare function sequentialIdVerdict(newId: string, existingIds: string[]): IdVerdict;

package/dist/holmes/mcp/spec-id-guard.js

@@ -0,0 +1,50 @@
+"use strict";
+// @implements A-SPEC-252
+/**
+ * 넘버링 오염을 생성 시점에 막는 순수 가드.
+ *
+ * spec_slice_init 의 `nextId = max(base) + 1` 은 번호가 항상 순차 배정될 때만 예측 가능하다. 그런데
+ * spec_create 는 id 형태만 보고 순번은 보지 않아, 손으로 심은 wild id(REQ-1403) 하나가 max 를 끌어올려
+ * 이후 모든 슬라이스를 오염시켰다(실측: 249→1404). 이 가드는 그 하나의 구멍을 막는다 — 새 base 는
+ * 현재 max 를 한 칸 넘게 뛸 수 없다. 막으면 max+1 은 다시 오염되지 않고 넘버링이 영구히 예측 가능하다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specIdBase = specIdBase;
+exports.sequentialIdVerdict = sequentialIdVerdict;
+/** id 의 base 숫자. "REQ-1403"→1403, "A-SPEC-250.1"→250(서브번호 무시), 레거시 "H-SPEC-050"→50. 못 뽑으면 null. */
+function specIdBase(id) {
+    if (typeof id !== 'string')
+        return null;
+    // 마지막 하이픈 뒤의 숫자 토막(점 앞)을 base 로 본다.
+    const m = /-(\d+)(?:\.\d+)?\s*$/.exec(id.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    return Number.isNaN(n) ? null : n;
+}
+/**
+ * 새 id 의 base 가 코퍼스 max base 를 한 칸 넘게 뛰면 거부한다.
+ *
+ * - 빈 코퍼스, 또는 base 를 못 뽑는 id → 통과(비교 대상이 없거나, 형태 검증은 별도 소관이라 한 결함에
+ *   두 이름을 주지 않는다).
+ * - base ≤ maxBase(갭 메우기·체인 완성) 또는 base == maxBase+1(새 체인) → 통과.
+ * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
+ */
+function sequentialIdVerdict(newId, existingIds) {
+    const base = specIdBase(newId);
+    if (base === null)
+        return { ok: true };
+    const bases = (existingIds ?? []).map(specIdBase).filter((n) => n !== null);
+    if (bases.length === 0)
+        return { ok: true };
+    const maxBase = Math.max(...bases);
+    if (base > maxBase + 1) {
+        const nextAvailable = maxBase + 1;
+        return {
+            ok: false,
+            reason: `${newId} 는 순번을 벗어납니다 — 현재 최대 번호는 ${maxBase}, 다음 가용 번호는 ${nextAvailable} 입니다. 순차 번호나 기존 base 의 서브슬라이스만 만들 수 있습니다(넘버링 오염 방지).`,
+            nextAvailable,
+        };
+    }
+    return { ok: true };
+}

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/package.json

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