@holmes-lab/holmes-kit 0.1.11 → 0.1.13

package/dist/holmes/hooks/stop.d.ts

@@ -1,3 +1,4 @@
+import { PendingRequest } from '../governance/approval-queue';
 import { Spec } from '../spec/spec-parser';
 /**
  * @implements A-SPEC-100.2
@@ -57,6 +58,10 @@ export declare function evaluateStop(specs: Spec[], evidence?: StopEvidence): {
     block: boolean;
     reason?: string;
     articles?: string[];
+    violations?: {
+        article: string;
+        detail: string;
+    }[];
 };
 /**
  * @implements A-SPEC-134
@@ -76,6 +81,40 @@ export declare function stopDebtAction(evaluation: {
     articles: string[];
 };
 export declare const MAX_CONSECUTIVE_BLOCKS = 3;
+/**
+ * Should the stop gate keep re-blocking a turn, or has every unresolved debt already been queued
+ * for the owner's decision?
+ *
+ * @implements A-SPEC-247
+ * Measured (Notion UX-2): the stop hook re-blocks a violation whose only fix is an owner approval on
+ * every turn — six in a row — even when the request is already waiting in the queue, giving the
+ * agent nothing to do and the user the same wall repeatedly. This answers "is anything left that the
+ * agent or a NON-waiting approval could resolve?".
+ *
+ * ASYMMETRY IS THE POINT, and it is what keeps this from becoming amnesty: acknowledged is true ONLY
+ * when nothing is blocking AND at least one thing is waiting. A single non-waiting violation — a
+ * code debt, or an approval debt nobody queued — and the gate blocks exactly as before. Waiting is
+ * read from the pending list (REQ-244's fold), not re-derived. A violation whose detail names no
+ * spec id cannot be matched to a request, so it blocks — the safe direction.
+ */
+export declare function acknowledgeStop(violations: {
+    article: string;
+    detail: string;
+}[], pending: PendingRequest[]): {
+    acknowledged: boolean;
+    blocking: string[];
+    waiting: string[];
+};
+/**
+ * One-line health of the env approval token, for the server's startup log.
+ *
+ * @implements A-SPEC-247
+ * Measured (Notion UX-4): an invalid token gives no signal until an approval is attempted, so the
+ * operator round-trips without knowing why. This is a LOG, not a gate — an absent or invalid token
+ * is a legitimate read-only posture, and the server must start regardless. The reason distinguishes
+ * "not JSON" from "wrong shape" so the operator knows which to fix.
+ */
+export declare function describeTokenHealth(raw: string | undefined): string;
 export declare function decideStopGuard(wantsBlock: boolean, priorConsecutiveBlocks: number, cap?: number): {
     block: boolean;
     nextCount: number;

package/dist/holmes/hooks/stop.js

@@ -37,12 +37,15 @@ exports.MAX_CONSECUTIVE_BLOCKS = void 0;
 exports.governanceLostPreflight = governanceLostPreflight;
 exports.evaluateStop = evaluateStop;
 exports.stopDebtAction = stopDebtAction;
+exports.acknowledgeStop = acknowledgeStop;
+exports.describeTokenHealth = describeTokenHealth;
 exports.decideStopGuard = decideStopGuard;
 exports.__setWiredSpecsForTest = __setWiredSpecsForTest;
 exports.guardCountOrZero = guardCountOrZero;
 exports.readGuardCount = readGuardCount;
 exports.writeGuardCount = writeGuardCount;
 const fs = __importStar(require("node:fs"));
+const risk_gate_1 = require("../guardrail/risk-gate");
 const json_state_1 = require("../project/json-state");
 const node_child_process_1 = require("node:child_process");
 const path = __importStar(require("node:path"));
@@ -79,15 +82,20 @@ function evaluateStop(specs, evidence) {
     // The articles live in ONE place (governance/constitution.ts); this gate merely executes them.
     const violations = (0, constitution_1.verifyConstitution)({ specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings });
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
+    // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
+    // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
+    const structured = violations.map((x) => ({ article: x.article, detail: x.detail }));
     // Tampered audit trail blocks finishing — wires the provenance chain's verify into the live gate
     // (review finding: verify() previously had no product caller, so the chain's guarantee was inert).
     if (evidence?.provenance && !evidence.provenance.ok) {
         problems.push(`[ART-2] provenance chain broken at seq ${evidence.provenance.brokenAt}: ${evidence.provenance.detail}`);
+        structured.push({ article: 'ART-2', detail: `provenance chain broken at seq ${evidence.provenance.brokenAt}: ${evidence.provenance.detail}` });
     }
     // @implements A-SPEC-191 (§4a) — an existing-but-unreadable findings ledger is not a clean turn:
     // it may hold an open critical, and a "clean" verdict here would also CLEAR standing ART-7 debt.
     if (evidence?.findingsUnreadable) {
         problems.push('[ART-7] findings 원장을 읽을 수 없습니다 — 열린 치명 발견의 존재를 확인할 수 없는 턴은 깨끗한 턴이 아닙니다 (원장 파일의 권한·형식을 복구하십시오)');
+        structured.push({ article: 'ART-7', detail: 'findings 원장을 읽을 수 없습니다' });
     }
     if (problems.length === 0)
         return { block: false };
@@ -100,6 +108,7 @@ function evaluateStop(specs, evidence) {
     return {
         block: true,
         articles,
+        violations: structured,
         reason: `[Holmes-Kit] constitution gate: ${problems.length} article violation(s) must be ` +
             `fixed before finishing:\n${shown.join('\n')}${more}`,
     };
@@ -125,6 +134,76 @@ function stopDebtAction(evaluation, guard) {
 // blocking while problems persist, up to MAX_CONSECUTIVE_BLOCKS, then yields with a loud warning
 // (bounded, so an unfixable state cannot infinite-loop the session). Any clean stop resets the count.
 exports.MAX_CONSECUTIVE_BLOCKS = 3;
+/**
+ * Constitution violation codes whose ONLY resolution is an owner's approval, not the agent's code.
+ *
+ * @implements A-SPEC-247
+ * stale-parent and post-approval-edit are cleared by re-approving the spec — a human act, out of
+ * band. ART-4 (no anchored test), a dangling RTM edge, an unmet obligation: those the agent fixes
+ * by writing code, so they are NOT here. Acknowledging a code-resolvable violation would bury a
+ * debt the agent is supposed to pay.
+ */
+const APPROVAL_RESOLVABLE = ['stale-parent', 'post-approval-edit'];
+const SPEC_ID_RE = /\b([A-Z]-SPEC-\d+(?:\.\d+)?|REQ-\d+)\b/;
+/**
+ * Should the stop gate keep re-blocking a turn, or has every unresolved debt already been queued
+ * for the owner's decision?
+ *
+ * @implements A-SPEC-247
+ * Measured (Notion UX-2): the stop hook re-blocks a violation whose only fix is an owner approval on
+ * every turn — six in a row — even when the request is already waiting in the queue, giving the
+ * agent nothing to do and the user the same wall repeatedly. This answers "is anything left that the
+ * agent or a NON-waiting approval could resolve?".
+ *
+ * ASYMMETRY IS THE POINT, and it is what keeps this from becoming amnesty: acknowledged is true ONLY
+ * when nothing is blocking AND at least one thing is waiting. A single non-waiting violation — a
+ * code debt, or an approval debt nobody queued — and the gate blocks exactly as before. Waiting is
+ * read from the pending list (REQ-244's fold), not re-derived. A violation whose detail names no
+ * spec id cannot be matched to a request, so it blocks — the safe direction.
+ */
+function acknowledgeStop(violations, pending) {
+    const waitingTargets = new Set((Array.isArray(pending) ? pending : []).map((p) => p.target));
+    const blocking = [];
+    const waiting = [];
+    for (const vln of Array.isArray(violations) ? violations : []) {
+        const detail = String(vln?.detail ?? '');
+        const approvalResolvable = APPROVAL_RESOLVABLE.some((k) => detail.includes(k));
+        if (!approvalResolvable) {
+            blocking.push(`[${vln.article}] ${detail}`);
+            continue;
+        }
+        const id = (SPEC_ID_RE.exec(detail) ?? [])[1];
+        if (id && waitingTargets.has(id))
+            waiting.push(id);
+        else
+            blocking.push(`[${vln.article}] ${detail}`); // named no id, or not queued → block
+    }
+    return { acknowledged: blocking.length === 0 && waiting.length > 0, blocking, waiting };
+}
+/**
+ * One-line health of the env approval token, for the server's startup log.
+ *
+ * @implements A-SPEC-247
+ * Measured (Notion UX-4): an invalid token gives no signal until an approval is attempted, so the
+ * operator round-trips without knowing why. This is a LOG, not a gate — an absent or invalid token
+ * is a legitimate read-only posture, and the server must start regardless. The reason distinguishes
+ * "not JSON" from "wrong shape" so the operator knows which to fix.
+ */
+function describeTokenHealth(raw) {
+    if (raw === undefined || raw === '')
+        return 'HOLMES_APPROVAL 토큰 없음 (읽기 전용 — 승인이 필요한 행위만 막힙니다)';
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return 'HOLMES_APPROVAL 무효: JSON 파싱 실패 — 승인이 필요한 행위가 막힙니다';
+    }
+    if (!(0, risk_gate_1.isValidApproval)(parsed)) {
+        return 'HOLMES_APPROVAL 무효: 필수 필드(actor·token·rationale) 누락 — 승인이 필요한 행위가 막힙니다';
+    }
+    return 'HOLMES_APPROVAL 유효';
+}
 function decideStopGuard(wantsBlock, priorConsecutiveBlocks, cap = exports.MAX_CONSECUTIVE_BLOCKS) {
     if (!wantsBlock)
         return { block: false, nextCount: 0, capped: false };
@@ -413,7 +492,22 @@ if (require.main === module) {
             catch {
                 findingsUnreadable = true;
             } // @implements A-SPEC-191 (§4a) — list() absorbs ENOENT; a throw means the ledger EXISTS and cannot be read, which must block, not launder
-            const out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable });
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable });
+            // @implements A-SPEC-247 — before deciding to re-block, ask whether every unresolved debt is
+            // already queued for the owner. If so, tell the user ONCE and let the turn finish; a single
+            // non-waiting violation and we block exactly as before.
+            let ackWaiting = [];
+            if (out.block) {
+                try {
+                    const { readQueue } = require('../governance/approval-queue');
+                    const ack = acknowledgeStop(out.violations ?? [], readQueue(stopProjectRoot()).pending);
+                    if (ack.acknowledged) {
+                        out = { block: false };
+                        ackWaiting = ack.waiting;
+                    }
+                }
+                catch { /* awareness is best-effort; a failure leaves the block intact */ }
+            }
             const guard = decideStopGuard(out.block, guardCountOrZero(sessionId));
             const persisted = writeGuardCount(sessionId, guard.nextCount);
             // @implements A-SPEC-134 — the cap-yield is no longer silent: a clean turn clears any debt, a
@@ -438,6 +532,11 @@ if (require.main === module) {
                 process.stdout.write(JSON.stringify({ decision: 'block', reason: out.reason }));
                 process.stderr.write(`${out.reason}\n`);
             }
+            else if (ackWaiting.length > 0) {
+                // @implements A-SPEC-247 — acknowledged, not clean: name what is waiting so the user sees
+                // the standing approval debt exactly once, and the agent knows the ball is not in its court.
+                process.stderr.write(`[Holmes-Kit] 승인 대기 중 — 오너 결정을 기다리는 항목: ${ackWaiting.join(', ')}. npx holmes-kit approve 에서 결재하십시오. (이 부채로는 재차단하지 않습니다)\n`);
+            }
             else if (guard.capped) {
                 process.stderr.write(`[Holmes-Kit] governance gate YIELDING after ${exports.MAX_CONSECUTIVE_BLOCKS} consecutive blocks — issues remain UNRESOLVED:\n${out.reason ?? ''}\n`);
             }

package/dist/holmes/mcp/handlers.js

@@ -99,6 +99,8 @@ const findings_1 = require("../review/findings");
 const package_1 = require("../review/package");
 const risk_classifier_1 = require("../guardrail/risk-classifier");
 const risk_gate_1 = require("../guardrail/risk-gate");
+const approval_queue_1 = require("../governance/approval-queue");
+const approval_grants_1 = require("../governance/approval-grants");
 const spec_digest_1 = require("../spec/spec-digest");
 const spec_store_2 = require("../spec/spec-store");
 const breaking_change_1 = require("../spec/breaking-change");
@@ -148,6 +150,46 @@ const anchor_1 = require("../reverse/anchor");
 // The hazard that guard addressed is real but belongs to the GIT CHANGE SOURCE: gitChangedFiles
 // yields top-level-relative paths while scan(root, root) tags root-relative ones, so a disagreement
 // silently produces wrong impact sets. `GitChangeSource` now enforces exactly that, and only there.
+/**
+ * @implements A-SPEC-244
+ * File the review request from a handler refusal. A failure to resolve the root files nothing —
+ * the queue is information, and a refusal path must not gain a new failure mode from it.
+ */
+/**
+ * @implements A-SPEC-245
+ * Env-or-grant resolution for handler gates. With no resolvable root there is no disk to read
+ * grants from, so the env channel alone answers — same fail-closed posture as before this slice.
+ */
+function resolveHandlerApproval(rootArg, store, envApproval, action, now) {
+    let root;
+    try {
+        const storeRoot = store?.specsRoot;
+        const base = rootArg !== undefined ? rootArg : (typeof storeRoot === 'string' ? storeRoot : undefined);
+        root = base !== undefined ? projectRootOf(base) : undefined;
+    }
+    catch {
+        root = undefined;
+    }
+    if (root === undefined) {
+        return (0, risk_gate_1.approvalCovers)(envApproval, action, now) ? { approval: envApproval, source: 'env' } : undefined;
+    }
+    const r = (0, approval_grants_1.resolveApproval)(root, envApproval, action, now);
+    return r ? { ...r, root } : undefined;
+}
+function refusalQueueHint(rootArg, store, req) {
+    try {
+        // The SpecStore interface carries no root; the file-backed store exposes one. A store without a
+        // root files nothing — the queue lives on disk, and with no disk location there is nothing to do.
+        const storeRoot = store?.specsRoot;
+        const base = rootArg !== undefined ? rootArg : (typeof storeRoot === 'string' ? storeRoot : undefined);
+        if (base === undefined)
+            return '';
+        return (0, approval_queue_1.queueHint)(projectRootOf(base), req);
+    }
+    catch {
+        return '';
+    }
+}
 function projectRootOf(root) {
     return (0, root_2.resolveProjectRoot)(root).root;
 }
@@ -771,16 +813,22 @@ function makeRawHandlers(store) {
             catch {
                 approval = undefined;
             }
-            const covered = (0, risk_gate_1.approvalCovers)(approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString());
+            const retireResolved = resolveHandlerApproval(a.root, store, approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString());
+            const covered = retireResolved !== undefined;
             const sealed = typeof spec.frontmatter.approved_digest === 'string';
             if (sealed && !covered) {
                 return {
                     ok: false,
                     reason: `${a.id}은(는) 봉인된 문서입니다 — 폐기는 이 행위를 덮는 유효한 대역외 HOLMES_APPROVAL 이 필요합니다.`
                         + ' 코드 게이트를 막고 있는 approved T-SPEC 을 폐기하면 그 게이트가 열리므로, 폐기가 승인 우회 경로가 되지 않도록 fail-closed 로 막습니다.'
-                        + ' (범위를 쓰면 kind "spec-approve")',
+                        + ' (범위를 쓰면 kind "spec-approve")'
+                        + refusalQueueHint(a.root, store, { kind: 'spec-approve', target: a.id, why: '봉인된 스펙의 폐기' }),
                 };
             }
+            // @implements A-SPEC-245 — a grant that authorized breaking a seal is spent by it.
+            if (sealed && retireResolved?.source === 'grant' && retireResolved.root && retireResolved.approval.nonce) {
+                (0, approval_grants_1.consumeGrantFile)(retireResolved.root, retireResolved.approval.nonce);
+            }
             const dependents = all.filter((s) => s.id !== a.id && s.dependsOn.includes(a.id));
             const blocking = dependents.filter((s) => s.status === 'approved').map((s) => s.id);
             if (blocking.length > 0) {
@@ -835,8 +883,10 @@ function makeRawHandlers(store) {
             // covers, not merely well-formed (round-3 escalation: a token scoped to review-resolve — or
             // expired outright — completed a FULL SEAL here, so A-SPEC-133's narrowing was decorative at
             // the most consequential consumer). Unscoped {actor,token,rationale} stays the session key.
-            if (!(0, risk_gate_1.approvalCovers)(approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString())) {
-                return { ok: false, reason: 'spec_approve requires an out-of-band HOLMES_APPROVAL that COVERS this act — a request-payload approval is not a channel, and an expired or elsewhere-scoped token does not open this door (scoped approvals need kind "spec-approve"). (fail-closed)' };
+            const approveResolved = resolveHandlerApproval(a.root, store, approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString());
+            if (approveResolved === undefined) {
+                return { ok: false, reason: 'spec_approve requires an out-of-band HOLMES_APPROVAL that COVERS this act — a request-payload approval is not a channel, and an expired or elsewhere-scoped token does not open this door (scoped approvals need kind "spec-approve"). (fail-closed)'
+                        + refusalQueueHint(a.root, store, { kind: 'spec-approve', target: a.id, why: '스펙 봉인 승인' }) };
             }
             // @implements A-SPEC-188 — destination BEFORE seal.
             // The old order (seal at :481, resolve the ledger at :483) produced both measured harms: a
@@ -1025,12 +1075,12 @@ function makeRawHandlers(store) {
             const chain = new ledger_store_1.FileLedgerStore(path.join(ledgerRoot, '.ax', 'ledger'));
             chain.append({
                 ts: new Date().toISOString(),
-                actor: approval.actor,
+                actor: approveResolved.approval.actor,
                 kind: 'spec-approved',
                 summary: `approved ${a.id} sealing ${digest}`,
                 inputs: [a.id, digest],
-                rationale: approval.rationale,
-                authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token),
+                rationale: approveResolved.approval.rationale,
+                authorization: (0, provenance_chain_1.authorizationRef)(approveResolved.approval.actor, approveResolved.approval.token),
             });
             // @implements A-SPEC-135
             // P4 routing signal: a re-approval whose content CHANGED (prior seal existed and differs) mints
@@ -1042,14 +1092,18 @@ function makeRawHandlers(store) {
                 try {
                     const files = (0, review_targets_1.anchoredForReview)(a.id, cachedScan(ledgerRoot, ledgerRoot), specs);
                     chain.append({
-                        ts: new Date().toISOString(), actor: approval.actor, kind: 'review-needed',
+                        ts: new Date().toISOString(), actor: approveResolved.approval.actor, kind: 'review-needed',
                         summary: `targeted review needed: ${a.id} content moved — re-examine ${files.length} anchored file(s) against the new spec content`,
                         inputs: [a.id, priorDigest, digest, ...files],
-                        rationale: approval.rationale, authorization: '',
+                        rationale: approveResolved.approval.rationale, authorization: '',
                     });
                 }
                 catch { /* a missed routing signal is not a broken seal */ }
             }
+            // @implements A-SPEC-245 — single-use: the grant is spent by the seal it authorized.
+            if (approveResolved.source === 'grant' && approveResolved.root && approveResolved.approval.nonce) {
+                (0, approval_grants_1.consumeGrantFile)(approveResolved.root, approveResolved.approval.nonce);
+            }
             return { approved: a.id, digest };
         },
         async spec_list(a) {
@@ -1602,8 +1656,13 @@ function makeRawHandlers(store) {
                         // not a master key — an EXPIRED or elsewhere-scoped approval must not lift a critical.
                         // An unscoped {actor,token,rationale} stays the operator's session key (unchanged).
                         const nowTs = new Date().toISOString();
-                        if (!(0, risk_gate_1.approvalCovers)(approval, { kind: 'review-resolve', target: f.id }, nowTs)) {
-                            throw new HandlerRefusal(`review_record: id ${f.id} 의 열린 치명 발견을 해소하는 기록은 이 행위를 덮는 유효한 대역외 승인이 필요합니다 — 차단당한 쪽이 스스로 이빨을 뽑을 수 없어야 하고, 만료·다른 범위의 승인은 덮지 않습니다. HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why fixed>"}' (범위를 쓰면 kind "review-resolve") 를 서버 환경에 설정하고 다시 기록하십시오`);
+                        const rrResolved = resolveHandlerApproval(a.root, store, approval, { kind: 'review-resolve', target: f.id }, nowTs);
+                        if (rrResolved === undefined) {
+                            throw new HandlerRefusal(`review_record: id ${f.id} 의 열린 치명 발견을 해소하는 기록은 이 행위를 덮는 유효한 대역외 승인이 필요합니다 — 차단당한 쪽이 스스로 이빨을 뽑을 수 없어야 하고, 만료·다른 범위의 승인은 덮지 않습니다. HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why fixed>"}' (범위를 쓰면 kind "review-resolve") 를 서버 환경에 설정하고 다시 기록하십시오`
+                                + refusalQueueHint(a.root, store, { kind: 'review-resolve', target: f.id, why: '열린 치명 발견의 해소 기록' }));
+                        }
+                        if (rrResolved.source === 'grant' && rrResolved.root && rrResolved.approval.nonce) {
+                            (0, approval_grants_1.consumeGrantFile)(rrResolved.root, rrResolved.approval.nonce);
                         }
                         // @implements A-SPEC-191 §11 — 한 배치가 같은 id 를 다시 열고 다시 닫으면 lift 는 두 번
                         // 일어난다. 소비는 호출당 1회이므로, 세 번의 호출이면 거부됐을 일이 한 배치에서는

package/dist/holmes/mcp/server.js

@@ -68,4 +68,13 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
     }
     return { content: [{ type: 'text', text: JSON.stringify(out) }] };
 });
+// @implements A-SPEC-247 — surface the approval token's health once at startup, so an invalid
+// token is known before an approval is attempted (Notion UX-4). STDERR only: stdout is the MCP
+// protocol channel, and a single stray byte there breaks the handshake. This is a log, never a
+// gate — the server starts with any token, or none.
+try {
+    const { describeTokenHealth } = require('../hooks/stop');
+    process.stderr.write(`[Holmes-Kit] ${describeTokenHealth(process.env.HOLMES_APPROVAL)}\n`);
+}
+catch { /* a diagnostic must never keep the server from starting */ }
 void server.connect(new stdio_js_1.StdioServerTransport());

package/docs/install-guide.md

@@ -0,0 +1,131 @@
+# Install Guide — by account type and permissions
+
+This guide exists because of a measured failure, not a hypothetical one: an adopter on Windows ran
+`npm install -g` three times — once from an elevated PowerShell — and hit the same `EPERM` every
+time, because their npm global prefix pointed inside `C:\Program Files\nodejs`. The local install
+worked on the first try. Find your row, run its one command.
+
+## Which situation are you in?
+
+| Situation | Privileges needed | Command |
+|---|---|---|
+| **Using it in one project** (most people) | none | `npm install --save-dev @holmes-lab/holmes-kit` then `npx holmes-kit init` |
+| Company-managed PC / restricted account | none | same as above — no system directory is touched |
+| CI / container | none | same as above, plus `--prefer-online` right after a release |
+| Want the CLI across many projects (`-g`) | depends on your prefix | **check first**: `npm config get prefix` ↓ |
+
+The local install is the path verified end to end, on macOS and Windows, against the public
+registry. The wiring `init` writes uses absolute paths, so nothing needs to be on `PATH`.
+
+## Before `npm install -g`: check your prefix
+
+```
+npm config get prefix
+```
+
+| Result looks like | Verdict |
+|---|---|
+| `%APPDATA%\npm`, `~/.npm-global`, `/opt/homebrew`, an nvm/fnm/volta directory | user-writable — `npm install -g @holmes-lab/holmes-kit` works as-is |
+| `C:\Program Files\nodejs`, `/usr/local` | protected — `-g` dies with `EPERM` **before any package file arrives**. Move the prefix (below). **Do not elevate.** |
+
+`npx holmes-kit doctor` (after a local install) runs this exact check for you — the
+`global prefix` line names the directory and the remedy.
+
+### Moving the prefix to user space — one-time setup
+
+Windows (PowerShell):
+
+```powershell
+npm config set prefix "$env:APPDATA\npm"
+[Environment]::SetEnvironmentVariable('Path', "$([Environment]::GetEnvironmentVariable('Path','User'));$env:APPDATA\npm", 'User')
+# open a NEW terminal, then:
+npm install -g @holmes-lab/holmes-kit
+```
+
+macOS / Linux:
+
+```bash
+npm config set prefix "$HOME/.npm-global"
+export PATH="$HOME/.npm-global/bin:$PATH"   # add to your shell profile too
+npm install -g @holmes-lab/holmes-kit
+```
+
+A Node version manager (`nvm`, `fnm`, `volta`) achieves the same by keeping the whole toolchain
+under your home directory.
+
+### Why elevation is the wrong fix
+
+npm's own error text ends with *"try running the command again as root/Administrator."* Do not
+follow it here, for two reasons:
+
+1. **It may not even work.** The reported failure recurred from an elevated PowerShell — antivirus
+   and Windows Controlled Folder Access block protected-folder writes regardless of elevation.
+2. **When it works, it is worse.** `better-sqlite3` declares
+   `install: prebuild-install || node-gyp rebuild` — under an elevated `-g`, that downloads and
+   executes, or invokes a compiler, **with system privileges**. Keeping installs in user space is
+   what contains a compromised dependency.
+
+## Troubleshooting, by the error you actually see
+
+### `EPERM … mkdir C:\Program Files\nodejs\node_modules\@holmes-lab`
+
+```
+npm error code EPERM
+npm error syscall mkdir
+npm error path C:\Program Files\nodejs\node_modules\@holmes-lab
+```
+
+Your global prefix is a protected directory. The failure happens while npm creates the scope
+folder — **before a single package file is transferred** — so no package version can fix it, and
+neither can this one. Either drop `-g` (the local install needs none of this) or move the prefix
+(one-time setup above).
+
+### `notarget No matching version found`
+
+```
+npm error code ETARGET
+npm error notarget No matching version found for @holmes-lab/holmes-kit@<version>
+```
+
+Your npm metadata cache predates the release — measured minutes after publishing 0.1.11, the
+registry already listed the version while a default-cache install still refused it. Add
+`--prefer-online`, or retry in a few minutes.
+
+### `better-sqlite3` fails to build
+
+The one dependency that may need a toolchain. The 8 tree-sitter grammars ship prebuilt binaries
+(`darwin-arm64`, `darwin-x64`, `linux-x64`, `win32-x64`) and compile nothing; `better-sqlite3`
+downloads a prebuild at install time and **falls back to compiling** when none matches your
+platform and Node ABI. If it compiles, you need:
+
+| Platform | Toolchain |
+|---|---|
+| Windows | Visual Studio Build Tools (C++ workload) |
+| macOS | Xcode Command Line Tools (`xcode-select --install`) |
+| Alpine | `apk add --no-cache python3 make g++` |
+
+### `spawn sh ENOENT` during a git-URL install
+
+`npm i -g git+ssh://…` is not a supported path: npm 11 clones the repository into its cache and
+runs `prepare` there without installing dependencies, so the build tooling is missing. Install
+from the registry or from a packed tarball.
+
+## Verify — the last step of every path
+
+```
+npx holmes-kit doctor        # local install
+holmes-kit doctor            # global install
+```
+
+Expect `10 pass, 1 warn, 0 fail` on a healthy install. The lines that matter most:
+
+- `global prefix` — whether `-g` would work on this machine, and the remedy if not
+- `tree-sitter grammars` / `better-sqlite3` — whether the native modules actually load
+
+## What we deliberately do NOT do
+
+| Idea | Why not |
+|---|---|
+| A `postinstall` script that prints guidance | Triggers npm 11's `allow-scripts` warning and forfeits this package's current property of running no install scripts at all |
+| Recommending `npx @holmes-lab/holmes-kit init` with no install | `init` writes wiring with absolute paths; under bare `npx` those point into the npx cache and break when it is pruned |
+| Fixing your npm prefix from inside the package | A package rewriting your npm configuration is exactly the supply-chain behaviour this guide warns about |

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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/",
+    "docs/install-guide.md",
     "CHANGELOG.md"
   ],
   "engines": {