@holmes-lab/holmes-kit 0.1.8 → 0.1.10

package/dist/holmes/guardrail/write-target.d.ts

@@ -1,3 +1,4 @@
+import * as path from 'node:path';
 /**
  * Tools known to only READ. Everything else that carries a path is treated as a write.
  *
@@ -8,6 +9,34 @@
  * problem to the fourth tool; inverting it means an unrecognised tool fails CLOSED.
  */
 export declare const READ_ONLY_TOOLS: readonly ["read", "grep", "glob", "ls", "notebookread", "webfetch", "websearch", "todowrite", "task", "bashoutput", "killshell"];
+/**
+ * What KIND of absolute path this is, read from the syntax alone.
+ *
+ * @implements A-SPEC-220.1
+ * The gate used to ask `startsWith('/')` to mean "is absolute". That question is wrong on Windows:
+ * `C:/proj/src/app.ts` is absolute and answers false, so the whole identity block — symlink
+ * resolution, case folding, project containment — was skipped for every native Windows path. The
+ * block's own comment names NTFS as a case-insensitive filesystem while NTFS paths could not reach
+ * it.
+ *
+ * Deliberately does NOT read `process.platform`. Platform is a property of where this process runs;
+ * the question here is what a STRING is, and keeping it that way is what lets a POSIX CI verify the
+ * Windows verdicts. A classifier that asked the platform could only be tested on the platform.
+ *
+ * `unc` is reported separately rather than folded into `drive` because a network path cannot be
+ * resolved to a local filesystem identity at all — the caller must refuse it, not gate it.
+ */
+export type AbsoluteKind = 'posix' | 'drive' | 'unc';
+export declare function absoluteKindOf(p: string): AbsoluteKind | null;
+/**
+ * Whether this path's syntax alone guarantees a case-insensitive filesystem.
+ *
+ * @implements A-SPEC-220.1
+ * A fallback, never the first answer: the caller probes the real filesystem (dev/ino identity across
+ * a case-flipped root) and only consults this when the probe cannot answer. A drive letter means
+ * NTFS or FAT, and both fold case — that is a fact the syntax carries, not a guess about the host.
+ */
+export declare function foldsCaseBySyntax(kind: AbsoluteKind | null): boolean;
 /**
  * Payload keys that name a file. Shared with normalization so the two cannot drift: a field the
  * gate does not know about is a path the gate cannot see, which is how `notebook_path` slipped
@@ -29,6 +58,19 @@ export declare function writesFiles(toolName: string | undefined, input: unknown
  * remainder rejoined lexically — a whole-path `realpath` throws on a file that does not exist yet,
  * which is precisely when the gate has to answer.
  */
+/**
+ * Which path grammar to reason in, chosen from the STRINGS rather than from where this process runs.
+ *
+ * @implements A-SPEC-220.2
+ * `node:path` binds its flavor to the host: on POSIX, `path.resolve('C:/proj', 'C:/proj/.ax/…')`
+ * treats a drive path as relative and resolves it under the cwd, so every containment answer about
+ * a Windows path is about the wrong location. That is invisible on Windows (where the ambient flavor
+ * is already win32) and it is precisely why the Windows verdicts were unverifiable from CI — the
+ * gap REQ-220 exists to close.
+ *
+ * A relative `raw` carries no grammar of its own, so the root decides.
+ */
+export declare function pathFlavorFor(root: string, raw: string): path.PlatformPath;
 export declare function resolveTarget(root: string, raw: string, depth?: number): string;
 /**
  * Whether a write lands inside a governance directory.

package/dist/holmes/guardrail/write-target.js

@@ -34,7 +34,10 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PATH_FIELDS = exports.READ_ONLY_TOOLS = void 0;
+exports.absoluteKindOf = absoluteKindOf;
+exports.foldsCaseBySyntax = foldsCaseBySyntax;
 exports.writesFiles = writesFiles;
+exports.pathFlavorFor = pathFlavorFor;
 exports.resolveTarget = resolveTarget;
 exports.isProtectedTarget = isProtectedTarget;
 exports.specTargetOf = specTargetOf;
@@ -56,6 +59,30 @@ exports.READ_ONLY_TOOLS = [
     'read', 'grep', 'glob', 'ls', 'notebookread',
     'webfetch', 'websearch', 'todowrite', 'task', 'bashoutput', 'killshell',
 ];
+function absoluteKindOf(p) {
+    if (typeof p !== 'string' || p.length === 0)
+        return null;
+    if (/^[/\\]{2}/.test(p))
+        return 'unc';
+    if (p.startsWith('/'))
+        return 'posix';
+    // A single letter before the colon — `http:` and `file:` are schemes, not drives. The separator
+    // is required: `C:src/app.ts` is drive-RELATIVE and therefore not an absolute path.
+    if (/^[A-Za-z]:[/\\]/.test(p))
+        return 'drive';
+    return null;
+}
+/**
+ * Whether this path's syntax alone guarantees a case-insensitive filesystem.
+ *
+ * @implements A-SPEC-220.1
+ * A fallback, never the first answer: the caller probes the real filesystem (dev/ino identity across
+ * a case-flipped root) and only consults this when the probe cannot answer. A drive letter means
+ * NTFS or FAT, and both fold case — that is a fact the syntax carries, not a guess about the host.
+ */
+function foldsCaseBySyntax(kind) {
+    return kind === 'drive';
+}
 /**
  * Payload keys that name a file. Shared with normalization so the two cannot drift: a field the
  * gate does not know about is a path the gate cannot see, which is how `notebook_path` slipped
@@ -91,8 +118,27 @@ function writesFiles(toolName, input) {
  * remainder rejoined lexically — a whole-path `realpath` throws on a file that does not exist yet,
  * which is precisely when the gate has to answer.
  */
+/**
+ * Which path grammar to reason in, chosen from the STRINGS rather than from where this process runs.
+ *
+ * @implements A-SPEC-220.2
+ * `node:path` binds its flavor to the host: on POSIX, `path.resolve('C:/proj', 'C:/proj/.ax/…')`
+ * treats a drive path as relative and resolves it under the cwd, so every containment answer about
+ * a Windows path is about the wrong location. That is invisible on Windows (where the ambient flavor
+ * is already win32) and it is precisely why the Windows verdicts were unverifiable from CI — the
+ * gap REQ-220 exists to close.
+ *
+ * A relative `raw` carries no grammar of its own, so the root decides.
+ */
+function pathFlavorFor(root, raw) {
+    const kind = absoluteKindOf(raw) ?? absoluteKindOf(root);
+    return kind === 'drive' || kind === 'unc' ? path.win32 : path.posix;
+}
+/** Compare paths in one spelling — win32 hands back backslashes that must not defeat a prefix test. */
+const foldSep = (p) => p.replace(/\\/g, '/');
 function resolveTarget(root, raw, depth = 0) {
-    const abs = path.resolve(root, raw);
+    const pp = pathFlavorFor(root, raw);
+    const abs = pp.resolve(root, raw);
     // A DANGLING symlink still names where a write would land, and `realpath` fails on it — so the
     // link is followed explicitly. Without this, `ln -s .ax/ledger/not-yet-there innocent` then
     // writing `innocent` creates a file inside the protected directory while the gate sees a name
@@ -100,7 +146,7 @@ function resolveTarget(root, raw, depth = 0) {
     if (depth < 8) {
         try {
             if (fs.lstatSync(abs).isSymbolicLink()) {
-                return resolveTarget(path.dirname(abs), fs.readlinkSync(abs), depth + 1);
+                return resolveTarget(pp.dirname(abs), fs.readlinkSync(abs), depth + 1);
             }
         }
         catch { /* not a symlink, or unreadable — fall through to ancestor resolution */ }
@@ -109,13 +155,13 @@ function resolveTarget(root, raw, depth = 0) {
     let cur = abs;
     for (;;) {
         try {
-            return path.join(fs.realpathSync(cur), ...parts.reverse());
+            return pp.join(fs.realpathSync(cur), ...parts.reverse());
         }
         catch {
-            const parent = path.dirname(cur);
+            const parent = pp.dirname(cur);
             if (parent === cur)
                 return abs; // reached the filesystem root without an existing ancestor
-            parts.push(path.basename(cur));
+            parts.push(pp.basename(cur));
             cur = parent;
         }
     }
@@ -165,13 +211,14 @@ function specTargetOf(root, specsDir, raw) {
     const resolved = resolveTarget(root, raw);
     if (!/\.md$/i.test(resolved))
         return null;
-    const t = resolved.toLowerCase();
+    // @implements A-SPEC-220.2 — one spelling for every comparison below.
+    const t = foldSep(resolved).toLowerCase();
     // The WIRED store and the default layout both count. A deployment can move its specs, but
     // `<root>/.ax/specs` stays a spec store by the project's own convention — judging only the wired
     // one would hand back exactly the bypass this section closes for anyone who writes to the other.
     for (const dir of [specsDir, path.join('.ax', 'specs')]) {
-        const b = resolveTarget(root, dir).toLowerCase();
-        if (t.startsWith(b + path.sep))
+        const b = foldSep(resolveTarget(root, dir)).toLowerCase();
+        if (t.startsWith(b + '/'))
             return resolved;
     }
     return null;
@@ -188,13 +235,15 @@ function specTargetOf(root, specsDir, raw) {
  * through a dangling link creates exactly the file it names.
  */
 function protectedFileKindOf(root, raw) {
+    // @implements A-SPEC-220.2
+    const pp = pathFlavorFor(root, raw);
     const resolved = resolveTarget(root, raw);
     const base = resolveTarget(root, '.');
-    const foldedTarget = resolved.toLowerCase();
-    const foldedBase = base.toLowerCase();
-    if (foldedTarget !== foldedBase && !foldedTarget.startsWith(foldedBase + path.sep))
+    const foldedTarget = foldSep(resolved).toLowerCase();
+    const foldedBase = foldSep(base).toLowerCase();
+    if (foldedTarget !== foldedBase && !foldedTarget.startsWith(foldedBase + '/'))
         return null;
-    const name = path.basename(resolved).toLowerCase();
+    const name = pp.basename(resolved).toLowerCase();
     if (name === '.mcp.json')
         return '.mcp.json';
     // @implements A-SPEC-193 §8 (round 13) — 하네스가 늘면 **집행 지점도 는다**. Antigravity 는
@@ -202,7 +251,7 @@ function protectedFileKindOf(root, raw) {
     // 읽는다. 그 둘은 `.claude/settings*` 및 `.mcp.json` 과 정확히 같은 성질의 파일이다 — 세션이
     // 고칠 수 있으면 세션이 제 게이트를 끌 수 있다(실측: 배선 직후 두 파일 모두 allow 였다).
     // `.agents` 전체를 잠그지는 않는다: 규칙과 스킬은 평범한 저작물이고, 잠그면 진짜 작업이 막힌다.
-    const parent = path.basename(path.dirname(resolved)).toLowerCase();
+    const parent = pp.basename(pp.dirname(resolved)).toLowerCase();
     if (parent === '.agents' && (name === 'hooks.json' || name === 'mcp_config.json'))
         return `.agents/${name}`;
     // Example/sample/template/dist copies carry no secret — the same exclusion the hook's regex had.
@@ -211,13 +260,15 @@ function protectedFileKindOf(root, raw) {
     return null;
 }
 function protectedKindOf(root, raw) {
-    const target = resolveTarget(root, raw).toLowerCase();
-    const base = resolveTarget(root, '.').toLowerCase();
-    if (target !== base && !target.startsWith(base + path.sep))
+    // @implements A-SPEC-220.2
+    const pp = pathFlavorFor(root, raw);
+    const target = foldSep(resolveTarget(root, raw)).toLowerCase();
+    const base = foldSep(resolveTarget(root, '.')).toLowerCase();
+    if (target !== base && !target.startsWith(base + '/'))
         return null; // outside the project
     for (const d of PROTECTED_DIRS) {
-        const dir = path.join(base, d).toLowerCase();
-        if (target === dir || target.startsWith(dir + path.sep))
+        const dir = foldSep(pp.join(base, d)).toLowerCase();
+        if (target === dir || target.startsWith(dir + '/'))
             return d;
     }
     return null;

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

@@ -58,6 +58,10 @@ const tspec_state_1 = require("../guardrail/tspec-state");
 const identity_1 = require("../governance/identity");
 const role_policy_1 = require("../governance/role-policy");
 const risk_classifier_1 = require("../guardrail/risk-classifier");
+const proposed_content_1 = require("../cpg/proposed-content");
+const forbidden_edges_1 = require("../cpg/forbidden-edges");
+const required_calls_1 = require("../cpg/required-calls");
+const language_parser_1 = require("../cpg/language-parser");
 const write_target_1 = require("../guardrail/write-target");
 const anchors_1 = require("../guardrail/anchors");
 const governance_history_1 = require("../guardrail/governance-history");
@@ -224,7 +228,15 @@ function normalizeHookInput(raw) {
         || ['file_path', 'notebook_path'].some((f) => f in ti && typeof ti[f] !== 'string');
     const out = {};
     // Assigned individually so an undefined never becomes a present-but-undefined key downstream.
-    const fp = str(ti.file_path ?? ti.TargetFile);
+    // @implements A-SPEC-232 — surrounding whitespace is trimmed HERE, at the input boundary, not
+    // in each gate. Measured 2026-08-22: `src/app.ts ` walked past No-Spec-No-Code entirely, because
+    // action classification matches the extension at the end of the string and an unrecognised action
+    // passes — the same inversion `write-target.ts` applied to tool names, never applied to path
+    // spelling. Inside a name it is left alone: `my file.ts` is a real filename, and merging distinct
+    // files would be worse than the defect. A path of only whitespace is no path, so the field is
+    // omitted rather than left present-but-empty (the direction REQ-144 set).
+    const fpRaw = str(ti.file_path ?? ti.TargetFile);
+    const fp = fpRaw === undefined ? undefined : (fpRaw.trim() || undefined);
     if (fp !== undefined)
         out.file_path = fp;
     const c = str(ti.content ?? ti.CodeContent);
@@ -238,7 +250,8 @@ function normalizeHookInput(raw) {
         out.command = cmd;
     // @implements A-SPEC-163 — a path field the gate does not preserve is a path the gate cannot see,
     // which is how a NotebookEdit reached protected files unexamined.
-    const nb = str(ti.notebook_path);
+    const nbRaw = str(ti.notebook_path);
+    const nb = nbRaw === undefined ? undefined : (nbRaw.trim() || undefined);
     if (nb !== undefined)
         out.notebook_path = nb;
     return { tool_name: str(r.tool_name) ?? '', tool_input: out, ...(malformed ? { malformed: true } : {}) };
@@ -612,7 +625,23 @@ function evaluateHook(input, specsDir, opts) {
     // .mcp.json` → allow, and likewise for `.ax/roles`, `.ax/ledger` and No-Spec-No-Code on `src/app.ts`
     // — the whole gate off for one character of case. Identity now decides, and the target is rewritten
     // into the PROJECT'S OWN SPELLING so every check downstream reasons about one string.
-    if (norm.startsWith('/')) {
+    // @implements A-SPEC-220.1 — the entry condition used to be `norm.startsWith('/')`, which asks
+    // "is this POSIX-absolute" while meaning "is this absolute". `C:/proj/src/app.ts` answers false,
+    // so identity resolution, case folding and containment were all skipped on native Windows — the
+    // very filesystem (NTFS) the case-folding comment below names.
+    const absKind = (0, write_target_1.absoluteKindOf)(norm);
+    if (absKind === 'unc') {
+        // A network path has no local filesystem identity to resolve, so containment cannot be decided.
+        // A-SPEC-191 §17/§29 both began as "the gate did not refuse to govern — it concluded there was
+        // nothing to govern"; an undecidable target is refused, not allowed.
+        return {
+            permissionDecision: 'deny',
+            permissionDecisionReason: '[Holmes-Kit] 네트워크 경로(UNC)는 로컬 파일시스템 정체로 해석할 수 없어'
+                + ' 프로젝트 안팎을 판정할 수 없습니다 — 판정할 수 없는 대상은 허용하지 않습니다.'
+                + ' 프로젝트를 로컬 드라이브에 두거나 드라이브 문자로 매핑한 경로를 사용하십시오.',
+        };
+    }
+    if (absKind === 'posix' || absKind === 'drive') {
         const inside = (t, r) => t === r || t.startsWith(r + '/');
         const asProject = (abs, base) => (abs.length <= base.length ? projectRoot : `${projectRoot}/${abs.slice(base.length + 1)}`);
         const realTarget = realOf(norm).replace(/\/+$/, '');
@@ -622,8 +651,11 @@ function evaluateHook(input, specsDir, opts) {
         // files folded together, and a case-insensitive volume on Linux must not keep the bypass.
         const caseBlind = (() => {
             const flipped = projectRoot.replace(/[a-zA-Z]/, (c) => (c === c.toLowerCase() ? c.toUpperCase() : c.toLowerCase()));
+            // @implements A-SPEC-220.1 — the probe cannot answer when the root has no letter to flip.
+            // A drive letter means NTFS or FAT, both case-folding; that is carried by the syntax, so it is
+            // a fact here rather than a guess about the host.
             if (flipped === projectRoot)
-                return process.platform === 'darwin' || process.platform === 'win32';
+                return (0, write_target_1.foldsCaseBySyntax)(absKind) || process.platform === 'darwin' || process.platform === 'win32';
             if (flipped === projectRoot)
                 return false;
             try {
@@ -632,7 +664,13 @@ function evaluateHook(input, specsDir, opts) {
                 return a.dev === b.dev && a.ino === b.ino;
             }
             catch {
-                return false;
+                // @implements A-SPEC-220.1 — the probe THREW, which means it has no answer, not that the
+                // filesystem is case-sensitive. Conflating the two is why a drive-letter path kept failing
+                // both containment tests: neither spelling exists to stat from a POSIX CI, and a Windows
+                // project reached over a path this process cannot resolve is the same situation. Only the
+                // syntax fact is used here — a drive letter is NTFS or FAT, both case-folding — so POSIX
+                // inputs, for which this is always false, keep their previous verdict exactly.
+                return (0, write_target_1.foldsCaseBySyntax)(absKind);
             }
         })();
         const fold = (s) => (caseBlind ? s.toLowerCase() : s);
@@ -762,6 +800,53 @@ function evaluateHook(input, specsDir, opts) {
         return { permissionDecision: 'allow' };
     // Read specs synchronously via a fresh walk (hook must be sync)
     const specs = readSpecsSync(specsDir);
+    // @implements A-SPEC-230 — structural constraints move from "checked by the suite" to "enforced at
+    // the write". One parse of the proposed file, not a scan: both engines already judge file by file,
+    // and measured 2026-08-22 that is 2ms (18ms for the 109KB outlier) against 3.3s + 1.5s for the
+    // two full scans.
+    //
+    // ONLY APPROVED C-SPECs supply rules. If a draft could enforce, anyone could block anyone else's
+    // writes by dropping one in — enforcement without approval.
+    {
+        const proposed = typeof input.tool_input.content === 'string'
+            ? { content: input.tool_input.content, mode: 'full' }
+            : typeof input.tool_input.new_string === 'string'
+                ? { content: input.tool_input.new_string, mode: 'fragment' }
+                : null;
+        if (proposed && (0, write_target_1.specTargetOf)(opts.projectRoot, specsDir, p) === null) {
+            const forbidden = [];
+            const required = [];
+            for (const sp of specs) {
+                if (sp.type !== 'C-SPEC' || sp.status !== 'approved')
+                    continue;
+                forbidden.push(...(0, forbidden_edges_1.parseForbiddenEdges)(sp.sections?.['Forbidden Edges'] ?? '').rules);
+                required.push(...(0, required_calls_1.parseRequiredCalls)(sp.sections?.['Layer Rules'] ?? '').rules);
+            }
+            if (forbidden.length > 0 || required.length > 0) {
+                const { violations } = (0, proposed_content_1.checkProposedContent)({
+                    forbidden,
+                    required,
+                    // @implements A-SPEC-231 — the path is normalised before the prefix test. Adversarial
+                    // pass 3, 2026-08-22: `./src/a/x.ts` and `src//a/x.ts` both walked past a rule scoped to
+                    // `src/a/`. The same evasion class was already paid for on the command side, where
+                    // `normalizeCommandPaths` exists because those spellings "slipped every protected-path
+                    // regex". A rule must not depend on how the caller spelled the path.
+                    sourcePath: path.posix.normalize(relPath.trim()).replace(/^\.\//, ''),
+                    content: proposed.content,
+                    mode: proposed.mode,
+                    parser: new language_parser_1.TreeSitterTsParser(),
+                });
+                if (violations.length > 0) {
+                    return {
+                        permissionDecision: 'deny',
+                        permissionDecisionReason: '[Holmes-Kit] 구조 제약 위반 — 승인된 C-SPEC 이 금지한 형태입니다:\n'
+                            + violations.map((v) => '  - ' + v).join('\n')
+                            + '\n' + proposed_content_1.CSPEC_GATE_LIMITS,
+                    };
+                }
+            }
+        }
+    }
     // @implements A-SPEC-166
     // What this change CLAIMS to implement, judged independently of what the file already carried.
     // Measured 2026-08-08: the same unapproved `@implements` was denied in a new file and allowed in

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

@@ -83,6 +83,23 @@ export declare function decideStopGuard(wantsBlock: boolean, priorConsecutiveBlo
 };
 /** Test seam for the same reason as the two exports below — the CLI sets this on a real run. */
 export declare function __setWiredSpecsForTest(v: string | undefined): void;
+/**
+ * `readGuardCount`, degraded to 0 if it throws.
+ *
+ * @implements A-SPEC-237
+ * The shape check in `readGuardState` removes the corruption we KNOW about. This removes the path
+ * an unknown one would take. In the same block, three other risky reads — provenance, findings and
+ * debt — already sit inside a try/catch; `readGuardCount` alone did not, and that asymmetry was the
+ * route this defect travelled to the outer fail-open handler.
+ *
+ * Zero means "the counter is unknown", never "there is nothing to block". The gate still evaluates.
+ *
+ * REDUNDANT WITH THE SHAPE CHECK, ON PURPOSE — and the mutation results say so plainly. Removing
+ * either layer alone leaves every case green, because each fully covers the corruption we know
+ * about; removing BOTH fails two. That is what defence in depth looks like from a mutation run, and
+ * it is recorded here rather than left as an unexplained survivor for the next reader to rediscover.
+ */
+export declare function guardCountOrZero(sessionId: string, read?: (id: string) => number): number;
 export declare function readGuardCount(sessionId: string): number;
 /**
  * Exported for the §19 race discriminator: the persistence layer was the untested half (round-11),

package/dist/holmes/hooks/stop.js

@@ -39,9 +39,11 @@ exports.evaluateStop = evaluateStop;
 exports.stopDebtAction = stopDebtAction;
 exports.decideStopGuard = decideStopGuard;
 exports.__setWiredSpecsForTest = __setWiredSpecsForTest;
+exports.guardCountOrZero = guardCountOrZero;
 exports.readGuardCount = readGuardCount;
 exports.writeGuardCount = writeGuardCount;
 const fs = __importStar(require("node:fs"));
+const json_state_1 = require("../project/json-state");
 const node_child_process_1 = require("node:child_process");
 const path = __importStar(require("node:path"));
 const test_scope_1 = require("../rtm/test-scope");
@@ -222,12 +224,47 @@ const GUARD_STATE = () => guardStatePath() ?? path.join(process.cwd(), '.ax', 'l
 // every session into a single project-level file. One cell per session, oldest evicted.
 const GUARD_SESSIONS_MAX = 32;
 function readGuardState() {
+    let parsed;
     try {
-        return JSON.parse(fs.readFileSync(GUARD_STATE(), 'utf8'));
+        parsed = JSON.parse(fs.readFileSync(GUARD_STATE(), 'utf8'));
     }
     catch {
         return {};
     }
+    // @implements A-SPEC-237
+    // The catch above sees only a parse FAILURE. `null`, `42`, `"x"`, `true` and `[1,2]` parse
+    // fine, and the failure arrives later at `s.sessions?.[…]` as a TypeError. Measured 2026-08-23,
+    // end to end: a project that answered `{"decision":"block"}` with eight article violations
+    // produced NO OUTPUT and exit 0 once this file contained the four characters `null`. The file is
+    // gitignored and written by the hook itself, so one echo disabled governance leaving no trace.
+    if (!(0, json_state_1.isJsonStateObject)(parsed))
+        return {};
+    return parsed;
+}
+/**
+ * `readGuardCount`, degraded to 0 if it throws.
+ *
+ * @implements A-SPEC-237
+ * The shape check in `readGuardState` removes the corruption we KNOW about. This removes the path
+ * an unknown one would take. In the same block, three other risky reads — provenance, findings and
+ * debt — already sit inside a try/catch; `readGuardCount` alone did not, and that asymmetry was the
+ * route this defect travelled to the outer fail-open handler.
+ *
+ * Zero means "the counter is unknown", never "there is nothing to block". The gate still evaluates.
+ *
+ * REDUNDANT WITH THE SHAPE CHECK, ON PURPOSE — and the mutation results say so plainly. Removing
+ * either layer alone leaves every case green, because each fully covers the corruption we know
+ * about; removing BOTH fails two. That is what defence in depth looks like from a mutation run, and
+ * it is recorded here rather than left as an unexplained survivor for the next reader to rediscover.
+ */
+function guardCountOrZero(sessionId, read = readGuardCount) {
+    try {
+        const n = read(sessionId);
+        return Number.isInteger(n) && n >= 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
 }
 function readGuardCount(sessionId) {
     const s = readGuardState();
@@ -377,7 +414,7 @@ if (require.main === module) {
                 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 });
-            const guard = decideStopGuard(out.block, readGuardCount(sessionId));
+            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
             // give-up records the unresolved articles so WRITE_CODE is blocked until the constitution is

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

@@ -104,6 +104,46 @@ declare function makeRawHandlers(store: SpecStore): {
         remaining: import("../spec/validator").Finding[];
         reason?: undefined;
     }>;
+    /**
+     * Move a document to `outdated` — the only path there.
+     *
+     * @implements A-SPEC-222
+     * `outdated` was in SPEC_STATUSES with no code writing it and no document carrying it: a
+     * declared state nothing could reach. That mattered the moment 23 deprecated REQs needed
+     * cleaning up, because the only transition tool sends everything to `draft`, and calling a
+     * retired document "draft" is a worse lie than the non-canonical word it replaced.
+     *
+     * Retirement withdraws authority rather than granting it, so it does NOT need the approval key
+     * by default. Two cases invert that, and the threshold follows the RISK rather than the name of
+     * the act:
+     *
+     *  - A sealed document. The code gate demands an approved T-SPEC naming the target A-SPEC;
+     *    retiring that T-SPEC removes the demand. Unguarded, retirement is an approval bypass.
+     *  - A document an APPROVED spec depends on. That chain is holding something up right now.
+     */
+    spec_retire(a: {
+        root?: string;
+        id: string;
+        reason?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        retired?: undefined;
+        id?: undefined;
+        dependents?: undefined;
+    } | {
+        ok: boolean;
+        retired: boolean;
+        id: string;
+        dependents: never[];
+        reason: string;
+    } | {
+        ok: boolean;
+        retired: boolean;
+        id: string;
+        dependents: string[];
+        reason?: undefined;
+    }>;
     spec_approve(a: {
         root?: string;
         id: string;
@@ -304,6 +344,7 @@ declare function makeRawHandlers(store: SpecStore): {
         }>;
         unrequestedSymbols: string[];
         coverageGaps: string[];
+        obligationGaps: string[];
     }>;
     review_prepare(a: {
         root: string;