@holmes-lab/holmes-kit 0.1.0

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

@@ -0,0 +1,1262 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SPECS_DIR = void 0;
+exports.resolveRmSignals = resolveRmSignals;
+exports.readApprovalFromEnv = readApprovalFromEnv;
+exports.dumpsEnvInCommandPosition = dumpsEnvInCommandPosition;
+exports.normalizeHookInput = normalizeHookInput;
+exports.decideOnGateError = decideOnGateError;
+exports.isGovernedProject = isGovernedProject;
+exports.gateErrorDecision = gateErrorDecision;
+exports.wiredSpecsDir = wiredSpecsDir;
+exports.evaluateHook = evaluateHook;
+exports.readSpecsSync = readSpecsSync;
+// @implements A-SPEC-194, A-SPEC-195
+const registry_1 = require("../messages/registry");
+const root_1 = require("../project/root");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const phase_1 = require("../guardrail/phase");
+const spec_parser_1 = require("../spec/spec-parser");
+const spec_digest_1 = require("../spec/spec-digest");
+const constitution_debt_1 = require("../governance/constitution-debt");
+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 write_target_1 = require("../guardrail/write-target");
+const anchors_1 = require("../guardrail/anchors");
+const governance_history_1 = require("../guardrail/governance-history");
+const rtm_check_1 = require("../rtm/rtm-check");
+const ledger_store_1 = require("../governance/ledger-store");
+const provenance_chain_1 = require("../governance/provenance-chain");
+const risk_gate_1 = require("../guardrail/risk-gate");
+const approval_blockers_1 = require("../spec/approval-blockers");
+// Resolve per-rm-target git facts (H1 git-aware guardrail): is each recursive-rm target a
+// regenerable build artifact (gitignored), version-controlled source (tracked), or escaping the
+// project? This is the I/O half — the classifier stays pure and merely consumes these signals.
+//
+// OPTIONAL BY DESIGN: git is a REFINEMENT layer, never a requirement. Outside a git repo (or with git
+// unavailable), this returns undefined and the classifier falls back to its git-independent floor
+// (catastrophic targets) + static name-allowlist — i.e. exactly the pre-H1 behavior. So the guardrail
+// works fully in non-git / air-gapped contexts; git only SHARPENS the verdict when present.
+// FAIL-OPEN and shell-injection-safe: uses execFileSync (arg arrays, no shell); any failure (not a
+// git repo, git missing, odd target) yields no signal for that target. Metachar/tilde targets are
+// skipped (the classifier's catastrophic floor handles them and they must never reach a subprocess).
+function resolveRmSignals(command, cwd) {
+    const targets = (0, risk_classifier_1.rmCommandTargets)(command);
+    if (targets.length === 0)
+        return undefined;
+    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);
+    }
+    catch {
+        return undefined; // not a git repo / git unavailable -> static fallback
+    }
+    const signals = {};
+    for (const raw of targets) {
+        const unq = raw.replace(/^["']/, '').replace(/["']$/, '');
+        if (!unq || unq.startsWith('~') || /[^A-Za-z0-9._/-]/.test(unq))
+            continue; // floor handles these; never shell them
+        let resolved = path.resolve(baseReal, unq);
+        // Resolve symlinks on the real target so a lexically-in-project path that SYMLINKS outside the
+        // repo (e.g. `rm -rf link` where link -> /etc) is correctly seen as escaping (inProject=false →
+        // dangerous). path.resolve alone is lexical and would be fooled. Non-existent targets keep the
+        // lexical path (nothing to delete yet); realpath errors fail safe to the lexical value.
+        try {
+            if (fs.existsSync(resolved))
+                resolved = fs.realpathSync(resolved);
+        }
+        catch { /* keep lexical */ }
+        const inProject = resolved === repoRoot || resolved.startsWith(repoRoot + path.sep);
+        let gitIgnored = false;
+        let tracked = false;
+        try {
+            (0, node_child_process_1.execFileSync)('git', ['check-ignore', '-q', '--', unq], { cwd, stdio: 'ignore', env: (0, root_1.cleanSubprocessEnv)() });
+            gitIgnored = true;
+        }
+        catch { /* exit!=0 -> not ignored/unknown */ }
+        try {
+            (0, node_child_process_1.execFileSync)('git', ['ls-files', '--error-unmatch', '--', unq], { cwd, stdio: 'ignore', env: (0, root_1.cleanSubprocessEnv)() });
+            tracked = true;
+        }
+        catch { /* not tracked */ }
+        signals[raw] = { gitIgnored, tracked, inProject };
+    }
+    return Object.keys(signals).length ? signals : undefined;
+}
+// Reads the out-of-band approval marker from HOLMES_APPROVAL. The AI session driving this
+// hook process cannot set its own environment, so this env var is an out-of-band channel —
+// a malformed/absent value must resolve to "no approval", never crash the hook (fail-closed
+// for hard-hitl means the ABSENCE of a valid approval denies; a parse error is absence).
+/**
+ * @implements A-SPEC-149
+ * The out-of-band approval channel, read at the ENTRY only. `evaluateHook` no longer calls this on
+ * its own — an exported HOLMES_APPROVAL used to reach the decision directly and turn a denial into
+ * permission with nothing recording that it had. Exported so the entry's contract (parse, and treat
+ * malformed input as absent) is testable at the layer that owns it.
+ */
+function readApprovalFromEnv() {
+    const raw = process.env.HOLMES_APPROVAL;
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when `env`/`printenv` runs as an actual COMMAND (an environment dump) rather than appearing as
+ * a mere word — `grep -rn env src/` and `git commit -m "set the env"` must stay allowed, while
+ * `env`, `/usr/bin/env`, `X=1 env`, `command env`, `(env)`, `sh -c 'env'` must not. Each segment is
+ * stripped of leading assignments/wrappers and, for a nested shell, its `-c` body is re-examined.
+ * `env FOO=1 cmd` is a RUNNER (assignment then command), not a dump.
+ */
+function dumpsEnvInCommandPosition(command, depth = 0) {
+    if (depth > 3)
+        return false;
+    for (const rawSeg of command.split(/[;&|\n]+/)) {
+        let seg = rawSeg.trim().replace(/^[({\s]+/, '').replace(/[)}\s]+$/, '');
+        // strip leading VAR=value assignments and neutral wrappers
+        for (;;) {
+            const next = seg.replace(/^(?:\w+=(?:"[^"]*"|'[^']*'|\S*)\s+|(?:command|eval|exec|builtin|nohup|time|sudo)\s+)/, '');
+            if (next === seg)
+                break;
+            seg = next;
+        }
+        const tokens = seg.split(/\s+/).filter(Boolean);
+        if (tokens.length === 0)
+            continue;
+        if (tokens[0].startsWith('#'))
+            continue; // comment / shebang line
+        const head = tokens[0].replace(/^['"]|['"]$/g, '').replace(/^.*\//, ''); // /usr/bin/env -> env
+        if (head === 'printenv')
+            return true;
+        if (head === 'env') {
+            // POSIX: `env [-flags] [NAME=VAL...] [command]`. With a COMMAND it is a runner, not a dump —
+            // `#!/usr/bin/env node` and `env FOO=1 node x` must stay allowed (dogfooding caught this
+            // over-block: the shebang is the most common line in a Node project). Only a bare `env`, or
+            // one carrying just flags/assignments, actually prints the environment.
+            const runsCommand = tokens.slice(1).some((t) => !t.startsWith('-') && !t.includes('='));
+            if (!runsCommand)
+                return true;
+        }
+        if (/^(?:sh|bash|zsh|ksh|dash)$/.test(head)) {
+            // nested shell: inspect the -c body (quotes already split away by the tokenizer)
+            const ci = tokens.findIndex((t) => /^-\w*c$/.test(t.replace(/^-+/, '-')));
+            if (ci >= 0) {
+                const body = seg.slice(seg.indexOf(tokens[ci]) + tokens[ci].length).trim().replace(/^['"]|['"]$/g, '');
+                if (dumpsEnvInCommandPosition(body, depth + 1))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+// Does this Write/Edit promote a spec to status:approved? Uses the SAME YAML loader as downstream
+// (parseSpec) on a full Write body so quoting/comments (`status: "approved"`, `status: approved # x`)
+// cannot slip a bespoke regex (verification review — that reopened the self-approval bypass). An Edit
+// carries only a fragment (not a parseable document), so a quote/comment-tolerant regex backs it up.
+function incomingSetsApproved(ti) {
+    if (typeof ti.content === 'string' && ti.content.trim()) {
+        try {
+            if ((0, spec_parser_1.parseSpec)(ti.content).status === 'approved')
+                return true;
+        }
+        catch { /* fall through to regex */ }
+    }
+    const text = `${ti.content ?? ''}\n${ti.new_string ?? ''}`;
+    return /^\s*status\s*:\s*["']?approved["']?\s*(?:#.*)?$/im.test(text);
+}
+function normalizeHookInput(raw) {
+    const str = (v) => (typeof v === 'string' ? v : undefined);
+    if (!raw || typeof raw !== 'object')
+        return { tool_name: '', tool_input: {} };
+    const r = raw;
+    const tiRaw = r.tool_input;
+    const tiIsObject = !!tiRaw && typeof tiRaw === 'object' && !Array.isArray(tiRaw);
+    const ti = (tiIsObject ? tiRaw : {});
+    // Present-but-wrong-typed is not the same as absent. A path that arrived as an array or an object
+    // is a request the gate cannot evaluate, and REQ-144 fixed the direction that must take.
+    const malformed = !tiIsObject
+        || ['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);
+    if (fp !== undefined)
+        out.file_path = fp;
+    const c = str(ti.content);
+    if (c !== undefined)
+        out.content = c;
+    const ns = str(ti.new_string);
+    if (ns !== undefined)
+        out.new_string = ns;
+    const cmd = str(ti.command);
+    if (cmd !== undefined)
+        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);
+    if (nb !== undefined)
+        out.notebook_path = nb;
+    return { tool_name: str(r.tool_name) ?? '', tool_input: out, ...(malformed ? { malformed: true } : {}) };
+}
+/**
+ * Which way to fail when the gate itself throws.
+ *
+ * @implements A-SPEC-144
+ * The entry point used to answer `allow` unconditionally, with the comment "to avoid blocking the
+ * workflow". The tension is real — an unrelated bug that denies every tool call bricks a session —
+ * but resolving it toward a silent grant makes every future bug in the gate a bypass instead of a
+ * visible failure, which is the opposite of the posture the rest of this codebase takes.
+ *
+ * So: a governed project DENIES, because a gate that cannot evaluate must not grant (the same rule
+ * REQ-141 applied to the ledger). An ungoverned project ALLOWS, because there was no policy to apply
+ * and inventing a denial there is its own failure mode. And an operator — never the session — can
+ * escape via `HOLMES_GATE_BYPASS`.
+ */
+function decideOnGateError(opts) {
+    if (opts.bypass) {
+        return { permissionDecision: 'allow', permissionDecisionReason: `[Holmes-Kit] 내부 오류를 HOLMES_GATE_BYPASS로 우회했습니다: ${opts.message}` };
+    }
+    if (!opts.governed)
+        return { permissionDecision: 'allow' };
+    // Names an INTERNAL ERROR on purpose. Imitating a policy denial would send an operator to fix a
+    // spec chain that was never the problem.
+    return {
+        permissionDecision: 'deny',
+        permissionDecisionReason: `[Holmes-Kit] 내부 오류로 판정할 수 없습니다 — 게이트는 판정 불가 시 허용하지 않습니다: ${opts.message}`
+            + ' → `holmes-kit doctor`로 설치를 점검하세요. 운영자 판단으로 통과시키려면 환경에 HOLMES_GATE_BYPASS=1을 설정하십시오(세션이 스스로 설정할 수 없는 대역외 채널).',
+    };
+}
+/**
+ * Is this project governed? Computed on the ERROR path, so it must not re-run the logic that just
+ * failed: presence of a configured spec root or a non-empty spec directory, nothing more. Any
+ * problem reading it means NOT governed — the conservative direction here is the one that keeps an
+ * unrelated failure from bricking a project that never asked for gating.
+ */
+function isGovernedProject(specsDir, env = process.env) {
+    try {
+        if (env.HOLMES_SPECS)
+            return true;
+        const stack = [specsDir];
+        while (stack.length) {
+            const d = stack.pop();
+            for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+                if (e.isDirectory())
+                    stack.push(path.join(d, e.name));
+                else if (e.name.endsWith('.md'))
+                    return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The whole error-path decision, assembled from an environment.
+ *
+ * @implements A-SPEC-144
+ * Exported and env-injected so the WIRING is tested rather than trusted. Mutation testing found the
+ * gap: hardcoding `bypass: true` and inverting the governance check both left every test green,
+ * because the tests exercised the pure helpers directly and nothing exercised the code that reads
+ * the environment. An untested wire is where a fix quietly stops applying.
+ */
+function gateErrorDecision(message, env = process.env, argv = process.argv, projectRoot) {
+    // @implements A-SPEC-190 §11 (round 9) — the ERROR path must read the same wiring the normal path
+    // does. `--specs` reached `evaluateHook` only, so a project wired with `--specs-dir docs/specs`
+    // looked UNGOVERNED the moment the gate hit an internal error — and 'not governed' is the branch
+    // that fails OPEN. The one path where being wrong is most expensive was the one still guessing.
+    //
+    // @implements A-SPEC-191 §17 (round 11) — and against the PROJECT's tree, not the shell's: a
+    // subdirectory session hit this same fail-open on the error path too (measured with a malformed
+    // payload). The caller passes the resolved root; the default keeps the old shape for callers that
+    // have none.
+    const wired = wiredSpecsDir(argv, env);
+    const specsDir = path.isAbsolute(wired) || projectRoot === undefined ? wired : path.join(projectRoot, wired);
+    return decideOnGateError({
+        governed: isGovernedProject(specsDir, env),
+        // Environment ONLY. The session authors the payload and the operator authors the environment,
+        // so an agent cannot grant itself relief from a gate it happens to be able to crash.
+        bypass: !!env.HOLMES_GATE_BYPASS,
+        message,
+    });
+}
+/**
+ * @implements A-SPEC-190 (round 8)
+ * Which spec directory this hook enforces against. The wiring writes it on the hook's own command
+ * line because the hook entry in settings carries no environment: `init --specs-dir docs/specs`
+ * reached the MCP server (HOLMES_SPECS in .mcp.json) and NOT the gate, so a project could be wired
+ * `governed` while the gate read an empty `.ax/specs` and refused nothing. Precedence is
+ * argv > env > default: the wiring is more specific than an ambient variable.
+ */
+function wiredSpecsDir(argv, env) {
+    const i = argv.indexOf('--specs');
+    const fromArgv = i >= 0 && argv[i + 1] ? argv[i + 1] : undefined;
+    return fromArgv ?? (env.HOLMES_SPECS || undefined) ?? exports.DEFAULT_SPECS_DIR;
+}
+/** Default spec root. Used to tell "never governed" apart from an explicitly configured HOLMES_SPECS. */
+exports.DEFAULT_SPECS_DIR = '.ax/specs';
+// @implements A-SPEC-100.2
+function evaluateHook(input, specsDir, opts) {
+    // @implements A-SPEC-133 — resolved once so every gate in this call shares one timestamp.
+    const nowTs = opts?.now ?? new Date().toISOString();
+    const ledgerFile = path.join(opts.projectRoot, '.ax', 'ledger', 'provenance.jsonl');
+    // @implements A-SPEC-125.4
+    // Bash/shell risk gate: this branch runs BEFORE the Write/Edit phaseCheck logic below and
+    // is intentionally fail-CLOSED — a classifier throw on the Bash surface denies, never
+    // allows, unlike the fail-open Write/Edit path further down.
+    // Case-insensitive tool_name match: an exact 'Bash' check would let a differently-cased
+    // 'bash'/'BASH' invocation fall through to the unconditional allow below, bypassing the
+    // whole gate on a hard-hitl command. A safety gate must not hinge on casing (defense in
+    // depth — the harness normally sets tool_name, but the gate defends regardless).
+    if ((input.tool_name ?? '').toLowerCase() === 'bash' && typeof input.tool_input.command === 'string' && input.tool_input.command.length > 0) {
+        const command = input.tool_input.command;
+        // Git-aware rm signals (H1): resolved only when a resolver is injected (the CLI wires the real
+        // git-backed one; unit tests omit it and exercise the pure static path). Fail-open: a throwing
+        // resolver must never block a command, so a resolution error degrades to no signals.
+        let rmTargetSignals;
+        try {
+            rmTargetSignals = opts?.resolveRmSignals?.(command);
+        }
+        catch {
+            rmTargetSignals = undefined;
+        }
+        // projectRoot scopes the protected-`.ax` rules to THIS repository's governance directory; without
+        // it the substring match gated `.ax` paths in any other project on the machine.
+        const action = {
+            kind: 'shell', target: command, command, rmTargetSignals,
+            projectRoot: opts.projectRoot.replace(/\\/g, '/').replace(/\/+$/, ''),
+        };
+        const assess = opts?.assess ?? risk_classifier_1.assessRisk;
+        const approval = opts.approval;
+        let assessment;
+        try {
+            assessment = assess(action);
+        }
+        catch {
+            return { permissionDecision: 'deny', permissionDecisionReason: '[Holmes-Kit] risk classification failed on a shell command — denied (fail-closed)' };
+        }
+        // @implements A-SPEC-133
+        // Hard-hitl needs an approval that COVERS this specific command (scope + not expired), and if
+        // the approval is single-use its nonce must not already be spent. An out-of-scope, expired, or
+        // replayed token denies exactly as an absent one — one token stops being a master key.
+        if (assessment.level === 'hard-hitl') {
+            const covers = (0, risk_gate_1.approvalCovers)(approval, { kind: 'shell', target: command }, nowTs);
+            const deny = (why) => ({
+                permissionDecision: 'deny',
+                permissionDecisionReason: `[Holmes-Kit] hard-hitl risk: ${assessment.reasons.join('; ')} — ${why}`,
+            });
+            if (!covers)
+                return deny('requires an approval that covers this command');
+            // @implements A-SPEC-141
+            // Check and spend in ONE atomic operation. The previous shape asked `isNonceConsumed(...)`
+            // and only afterwards appended the consumption record, so two concurrent agents both saw
+            // "not consumed" and both proceeded — measured, the same single-use approval was honoured
+            // twice in 20 of 20 barrier-synchronized trials. That is a TOCTOU on the authorization gate,
+            // not a logging problem, so the fix belongs here rather than around the append.
+            // @implements A-SPEC-191 §15 (round 11) — NOT a refusal here, deliberately, and this is the
+            // reasoning: the MCP consumers refuse a nonce they cannot record in a bound project (§13b),
+            // and round-10 flagged the hook for lacking the same rule. But this consumer's anchor now
+            // walks UP (§14a), so a subdirectory resolves to the real project and the only case left is a
+            // directory with no project above it at all — a fresh project's first guarded command, where
+            // creating `.ax/ledger` is the wiring working, not a plant. Refusing there would deny the
+            // first legitimate use in every new project. The single-use guarantee still holds: the record
+            // lands in the resolved root, which is the same file every later call resolves to.
+            if ((0, provenance_chain_1.blankNonce)(approval?.nonce)) {
+                return deny('승인이 단일 사용(nonce)을 선언했으나 값이 비어 있습니다 — 1회성을 집행할 수 없어 거부합니다');
+            }
+            if (approval?.nonce) {
+                let won;
+                try {
+                    won = (0, provenance_chain_1.consumeNonceExclusively)(approval.nonce, ledgerFile, {
+                        ts: nowTs, actor: approval.actor, kind: 'nonce-consumed',
+                        summary: `consumed single-use approval for: ${(0, provenance_chain_1.redactTarget)('command', command)}`.slice(0, 200),
+                        inputs: [(0, provenance_chain_1.nonceFingerprint)(approval.nonce)], rationale: approval.rationale, authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token),
+                    });
+                }
+                catch (err) {
+                    // FAIL CLOSED. A gate that cannot prove exclusivity must not grant — degrading to an
+                    // allow here would restore exactly the race this exists to remove. The wording is
+                    // deliberately DIFFERENT from the replay wording: an operator debugging a wedged agent
+                    // needs to tell "someone already used this token" from "the ledger was busy".
+                    return deny(`could not obtain exclusive ledger access to spend the single-use approval (${err instanceof Error ? err.message : String(err)})`);
+                }
+                if (!won)
+                    return deny('single-use approval already consumed (replay)');
+            }
+        }
+        // Bash BYPASS gates (adversarial review: `cat > evil.ts` created ungoverned files, `echo x >
+        // .claude/settings.json` forged hook config, and `echo $HOLMES_LEDGER_KEY` harvested the very
+        // secrets the out-of-band channel depends on). All override-able by a valid approval.
+        if (!(0, risk_gate_1.isValidApproval)(approval)) {
+            // (a) Reading/dumping the out-of-band secrets: possession of the approval token or ledger key
+            //     lets the agent forge approvals / re-sign history. Best-effort (a determined exfil via an
+            //     interpreter remains — documented residual); raises the cost from one echo to a gated act.
+            // Environment-dump detection. Widened after a 68-vector corpus showed 29 escapes (nested shells
+            // `sh -c env`, `env -0`, `/usr/bin/env`, `node -p`, `ps e`, newline-separated commands, …).
+            // HONEST SCOPE: this raises the cost of harvesting the out-of-band secrets; it is NOT a boundary
+            // (an interpreter can always read its own environ). Nothing security-critical may depend on it —
+            // which is why ART-4 evidence is additive-only, so stealing the key still unlocks nothing.
+            // The by-name rule matches how the secret is USED, not that it is named. Matching the bare
+            // word anywhere denied `grep HOLMES_APPROVAL src/*.ts` — reading a source file, not the
+            // environment — which is a false positive developers hit constantly on their own config
+            // names. The three forms below are the ones that matter, and nothing is lost by narrowing:
+            // `env | grep …`, `printenv …`, `set | …`, `/proc/*/environ` and interpreter reads are all
+            // caught by the separate rules underneath.
+            // @implements A-SPEC-154
+            // Measured 2026-08-08: LEDGER_KEY and APPROVAL were refused while ROLE and GATE_BYPASS were
+            // allowed, though all four carry the same property — a session must not be able to set them
+            // for itself. A reviewer could run `HOLMES_ROLE=maintainer claude -p '...'` and get a fully
+            // capable child; the role gate never lied, the discipline just evaporated. The detection
+            // shapes below are inherited unchanged, which is deliberate: they were narrowed because
+            // matching the bare word denied `grep HOLMES_APPROVAL src/*.ts`, and re-widening for the new
+            // names would bring that false positive back wearing a new label.
+            const SECRET = String.raw `HOLMES_(?:LEDGER_KEY|APPROVAL|ROLE|GATE_BYPASS)`;
+            // Which of the two harms this is. Setting a role or a bypass is not reading a secret, it is
+            // self-granting authority — reporting both as "reads the environment" sends an operator to
+            // hunt a leak that never happened.
+            const GRANTS_SELF = new RegExp(String.raw `\bHOLMES_(?:ROLE|GATE_BYPASS)\b`).test(command);
+            const usesSecret = new RegExp(String.raw `\$\{?\s*${SECRET}\b`).test(command) || // $VAR / ${VAR} — a read
+                new RegExp(String.raw `\b${SECRET}\s*=`).test(command) || // assignment — a self-issued approval / forged key
+                // A quoted key only counts as a LOOKUP when something indexes or calls with it —
+                // `env['VAR']`, `getenv("VAR")`, `ENVIRON["VAR"]`. A quoted bare word after a space is a
+                // search pattern (`grep "VAR" file`), which is the false positive being removed.
+                new RegExp(String.raw `[[(]\s*['"\`]${SECRET}['"\`]`).test(command);
+            const dumpsEnv = usesSecret ||
+                dumpsEnvInCommandPosition(command) || // env/printenv as a COMMAND
+                /(^|[;&|\n]\s*)(?:set|export\s+-p|declare\s+-x|typeset\s+-x)\s*(?:$|[;&|\n>])/.test(command) ||
+                /\$\{!\s*\w/.test(command) || // ${!VAR*} indirection
+                /\/proc\/(?:self|\d+|\$\$|\$\{?\w+\}?)\/environ/.test(command) || // /proc/*/environ incl. $$
+                /\bps\b[^;&|\n]*\s-?e\w*\b/.test(command) || // ps e / ps -e www
+                // Interpreter access to the environment, in any dash form (-e/-c/-p/--eval/--print/eval).
+                // @implements A-SPEC-163
+                // The bare `\bENV\b` alternative is GONE. It was narrowed once already (it denied
+                // `python3 -m venv .venv`) and still fired on any property named `env`: measured
+                // 2026-08-08, `node -e "const s=require('./x.json'); console.log(s.env)"` — reading one
+                // JSON key — was refused as an environment dump. The remaining alternatives
+                // (`process.env`, `os.environ`, `ENVIRON`, `getenv`) name real environment access; Perl's
+                // `%ENV`/`$ENV{…}` are the loss, and they are rarer than the false positives were.
+                /\b(?:node|python[0-9.]*|ruby|perl|deno|bun|php|awk|gawk)\b[^\n]*?(?:process\s*\.\s*env|os\s*\.\s*environ|from\s+os\s+import\s+environ|ENVIRON|getenv)/i.test(command) ||
+                // @implements A-SPEC-163
+                // Perl's `$ENV{…}` and Ruby's bare `ENV` still have to be caught, but CASE-SENSITIVELY and
+                // not after a dot. The old alternative was `\bENV\b` under /i, which also matched `s.env` —
+                // reading one JSON key was refused as an environment dump (measured 2026-08-08). Requiring
+                // upper case and a non-dot boundary keeps the real reads and drops the property access.
+                /\b(?:node|python[0-9.]*|ruby|perl|deno|bun|php|awk|gawk)\b[^\n]*?(?<![.\w])ENV\b/.test(command);
+            if (dumpsEnv) {
+                return {
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: GRANTS_SELF
+                        ? '[Holmes-Kit] 명령이 HOLMES_ROLE/HOLMES_GATE_BYPASS를 지정하거나 읽습니다 — 세션이 스스로 권한을 부여하는 경로입니다.'
+                            + ' 역할은 에이전트를 기동하는 사람이 대역외로 정합니다. 운영자 판단으로 실행하려면 config-write를 포함한 승인이 필요합니다.'
+                        : '[Holmes-Kit] command reads or dumps process environment (holds the out-of-band HOLMES_APPROVAL / HOLMES_LEDGER_KEY secrets) — requires out-of-band approval',
+                };
+            }
+            // (b) Shell-writing hook/approval CONFIG (the F6a surface, previously Write/Edit-only).
+            // @implements A-SPEC-191 §28 (round 13) — the rule matched only redirection and `tee`, and
+            // `cp`, `mv`, `install`, `ln -f`, `dd of=`, `rsync` and `sed -i` write the same file just as
+            // well. A gate that names one syntax for an act is a gate over that syntax, not over the act.
+            const CONFIG_FILE = '(?:\\.claude\\/settings[\\w.-]*\\.json|\\.mcp\\.json|\\.env(?!\\.(?:example|sample|template|dist))(?:\\.[\\w-]+)?)';
+            const configWrite = new RegExp(`(?:>{1,2}|\\btee\\b(?:\\s+-a)?\\s)\\s*['"]?[^\\s;|&]*${CONFIG_FILE}\\b`).test(command)
+                || new RegExp(`\\b(?:cp|mv|install|rsync|ln|dd|truncate|chmod|chown)\\b[^;|&]*${CONFIG_FILE}\\b`).test(command)
+                || new RegExp(`\\bsed\\b[^;|&]*\\s-i\\b[^;|&]*${CONFIG_FILE}\\b`).test(command);
+            // Residual, stated rather than papered over: an INTERPRETER can write these files too. A first
+            // draft matched `node|python|perl|ruby` anywhere near the pattern and denied
+            // `node -e "console.log(cfg.env.name)"` — reading a property named `env`. A rule that cannot
+            // tell reading from writing costs more than the hole it closes; the same residual is already
+            // recorded for the code-write rule below.
+            if (configWrite) {
+                return { permissionDecision: 'deny', permissionDecisionReason: registry_1.MESSAGES.INTEGRITY_CONFIG_EDIT('.claude/settings, .env, .mcp.json', 'A-SPEC-191') };
+            }
+            // (c) Shell-writing PROJECT CODE files (redirect/tee/touch/sed -i to a relative code path)
+            //     bypasses the No-Spec-No-Code Write/Edit gate entirely. Enforced only when this repo HAS
+            //     governed specs (a spec-less repo has no phase gate to bypass — keeps the guardrail
+            //     side-effect-free on ordinary ungoverned coding). Residual: interpreter-mediated writes.
+            const CODE_EXT = '(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|cc|cxx|cpp|hh|hpp|rb|php|swift)';
+            const shellCodeWrite = new RegExp(`(?:>{1,2}|\\btee\\b(?:\\s+-a)?\\s)\\s*['"]?(?![/~])[\\w@.-][\\w@./-]*\\.${CODE_EXT}\\b`).test(command) ||
+                new RegExp(`\\btouch\\s+[^;|&]*(?<![/~])\\b[\\w@.-][\\w@./-]*\\.${CODE_EXT}\\b`).test(command) ||
+                new RegExp(`\\bsed\\b[^;|&]*\\s-i\\b[^;|&]*\\.${CODE_EXT}\\b`).test(command);
+            if (shellCodeWrite) {
+                const governed = readSpecsSync(specsDir).some((s) => s.status === 'approved');
+                if (governed) {
+                    return { permissionDecision: 'deny', permissionDecisionReason: '[Holmes-Kit] shell write to a project code file bypasses the No-Spec-No-Code gate — use the Write/Edit tools (gated) or supply out-of-band approval' };
+                }
+            }
+        }
+        // auto/notify/confirm, or hard-hitl with a valid approval: this slice blocks only
+        // hard-hitl; confirm is advisory here.
+        return { permissionDecision: 'allow' };
+    }
+    // @implements A-SPEC-191 §27 (round 13) — `PATH_FIELDS` exists because `notebook_path` slipped
+    // past a gate that knew only `file_path`, and this line still knew only `file_path`: a valid
+    // NotebookEdit was denied in EVERY project with "편집 대상 경로를 읽을 수 없습니다", which names
+    // the wrong fault (the path was there and readable) and blocks a legitimate tool outright.
+    const p1 = typeof input.tool_input.file_path === 'string' ? input.tool_input.file_path : undefined;
+    const p2 = typeof input.tool_input.notebook_path === 'string' ? input.tool_input.notebook_path : undefined;
+    const isNb = input.tool_name?.toLowerCase() === 'notebookedit';
+    const p = isNb ? (p2 ?? p1) : (p1 ?? p2);
+    // @implements A-SPEC-163
+    // Inverted: a tool NOT known to be read-only, carrying a path, is a write. The membership test
+    // this replaces let `MultiEdit`, `NotebookEdit` and a lower-case `write` reach the very files
+    // `Write` was denied (measured 2026-08-08), and adding those names would only postpone the next
+    // tool. An unrecognised name now fails closed.
+    // @implements A-SPEC-163 — a payload the gate cannot evaluate denies, whichever tool sent it.
+    if (input.malformed) {
+        // The SAME wording the path-missing branch already used. Inventing a second phrase for the same
+        // condition would split what a reader (and a playbook trigger, which quotes these verbatim)
+        // has to recognise.
+        return {
+            permissionDecision: 'deny',
+            permissionDecisionReason: '[Holmes-Kit] 편집 대상 경로를 읽을 수 없어 판정할 수 없습니다 (file_path 누락 또는 문자열이 아님)',
+        };
+    }
+    const writesCode = (0, write_target_1.writesFiles)(input.tool_name, input.tool_input);
+    // @implements A-SPEC-144
+    // A code-writing tool with NO readable target must not pass in a governed project. Measured
+    // end-to-end after normalization landed: dropping a non-string `file_path` stopped the exception
+    // but left the outcome identical — `evaluateHook` saw no target and allowed. That is the same
+    // bypass wearing a quieter face, and it is worse, because there is no longer an error line to see.
+    // You cannot check whether an approved spec covers a file you cannot name, so the honest answer is
+    // no. An UNGOVERNED project is unaffected: the escape below already returns allow before this.
+    if (writesCode && !p) {
+        return {
+            permissionDecision: 'deny',
+            permissionDecisionReason: '[Holmes-Kit] 편집 대상 경로를 읽을 수 없어 판정할 수 없습니다 (file_path 누락 또는 문자열이 아님)'
+                + ' — 이름을 알 수 없는 파일이 승인된 스펙에 덮이는지 확인할 방법이 없으므로 허용하지 않습니다.',
+        };
+    }
+    if (!p || !writesCode)
+        return { permissionDecision: 'allow' };
+    const weApproval = opts.approval;
+    let norm = p.replace(/\\/g, '/');
+    // Holmes-Kit governs THIS project. An absolute path outside the project root (scratchpads, temp
+    // dirs, other checkouts) is not governed surface — gating it blocked ordinary harness scratch
+    // files (live over-block found in dogfooding). Relative paths are always in-project.
+    const projectRoot = opts.projectRoot.replace(/\\/g, '/').replace(/\/+$/, '');
+    // @implements A-SPEC-191 §17 (round 11) — "inside the project" is a fact about the RESOLVED
+    // location, not about how the caller spelled the path. Measured: with the project reached through
+    // a symlinked ancestor (macOS `/var` → `/private/var`, a symlinked home, `/tmp`), the root came
+    // back real-pathed while the target kept the caller's spelling, so EVERY file in the project read
+    // as "outside the project" and this line allowed the whole tree. The gate did not refuse to
+    // govern — it concluded there was nothing to govern.
+    // @implements A-SPEC-191 §29 (round 13) — the walk stopped after 64 ancestors and returned the
+    // UNRESOLVED path, which then failed both containment tests and took the early allow: a deep new
+    // 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.
+    const realOf = (abs) => {
+        let head = abs;
+        const tail = [];
+        for (;;) {
+            try {
+                return [fs.realpathSync(head).replace(/\\/g, '/'), ...tail].join('/');
+            }
+            catch { /* walk up */ }
+            const parent = path.dirname(head);
+            if (parent === head)
+                return abs;
+            tail.unshift(path.basename(head));
+            head = parent;
+        }
+    };
+    // @implements A-SPEC-191 §20 (round 11) — §17 said "the resolved location, not the spelling", and
+    // resolved only SYMLINKS. On a case-insensitive filesystem (APFS, NTFS) `fs.realpathSync` keeps
+    // each segment's letter case, so flipping one ancestor's case produced a path that is the SAME FILE
+    // (measured: identical dev/ino) yet failed both containment tests and took the early allow.
+    // Measured on a fixture project: `/private/tmp/…/proj/.mcp.json` → deny, `/PRIVATE/tmp/…/proj/
+    // .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('/')) {
+        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(/\/+$/, '');
+        const realRoot = realOf(projectRoot).replace(/\/+$/, '');
+        // Case-blindness is a property of THIS filesystem, probed on the project root itself rather than
+        // assumed from the platform — a case-sensitive volume mounted on macOS must not have two distinct
+        // 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()));
+            if (flipped === projectRoot)
+                return process.platform === 'darwin' || process.platform === 'win32';
+            if (flipped === projectRoot)
+                return false;
+            try {
+                const a = fs.statSync(projectRoot);
+                const b = fs.statSync(flipped);
+                return a.dev === b.dev && a.ino === b.ino;
+            }
+            catch {
+                return false;
+            }
+        })();
+        const fold = (s) => (caseBlind ? s.toLowerCase() : s);
+        // 접기는 해석된 위치에만 적용한다 — 철자 그대로의 norm 을 접어 '안'이라 부르면, 프로젝트
+        // 밖을 가리키는 링크가 이름만으로 안에 들어온다. 해석이 먼저, 접기는 그 위에서.
+        const canonical = inside(norm, projectRoot) ? asProject(norm, projectRoot)
+            : inside(realTarget, realRoot) ? asProject(realTarget, realRoot)
+                : inside(fold(realTarget), fold(realRoot)) ? asProject(realTarget, realRoot)
+                    : null;
+        if (canonical === null)
+            return { permissionDecision: 'allow' };
+        norm = canonical;
+    }
+    // @implements A-SPEC-191 §20e — an in-project target whose spelling cannot be decided is not a
+    // permitted one. A NUL byte truncates the path for any consumer that hands it to a syscall, and a
+    // trailing slash makes `.mcp.json/` miss every pattern that names `.mcp.json`. Both were measured
+    // reaching `allow` where the plain spelling denied. The slash is normalisation (same file); the NUL
+    // is a refusal, in the direction REQ-144 already set for unreadable targets.
+    if (norm.includes('\u0000')) {
+        return {
+            permissionDecision: 'deny',
+            permissionDecisionReason: '[Holmes-Kit] 편집 대상 경로에 NUL 바이트가 있어 어느 파일인지 판정할 수 없습니다'
+                + ' — 이름을 확정할 수 없는 대상은 허용하지 않습니다.',
+        };
+    }
+    norm = norm.length > 1 ? norm.replace(/\/+$/, '') : norm;
+    // Everything downstream that reasons about WHERE a file sits — classifyAction's test rules and the
+    // Files-to-Touch scope check — must see the PROJECT-RELATIVE path. Handing classifyAction an
+    // absolute one let a project checked out under `/…/test/` read as one big test tree, which
+    // DOWNGRADES the gate (WRITE_TEST does not require an approved T-SPEC).
+    const relPath = norm.startsWith(projectRoot + '/') ? norm.slice(projectRoot.length + 1) : norm;
+    // F6a: writing hook/approval CONFIG (.claude/settings*, .env, .mcp.json) can inject HOLMES_APPROVAL
+    // or turn the hooks off — it forges the very out-of-band channel the guardrail relies on. Gate it as
+    // hard-hitl so the model cannot self-provision approval or disable governance from tool input.
+    // The L4 ledgers are APPEND-ONLY audit evidence — hand-editing them via Write/Edit is history
+    // rewriting (append goes through the progress-ledger/decision-ledger APIs). Gate like the other
+    // governance surfaces (adversarial finding HIGH-3: a Write could forge/truncate the audit trail).
+    // @implements A-SPEC-153
+    // The role policy is the OTHER entrance to the same door. `HOLMES_ROLE` is out-of-band precisely so
+    // a session cannot claim its own role — but if it can WRITE `.ax/roles/`, it simply declares a role
+    // that may do everything, or a `default:` granting it without any claim at all. REQ-152 identified
+    // this threat and closed only the shell entrance; a plain Write was measured as ALLOWED. Unlike
+    // specs, no approval seal covers this file, so the write itself must be the thing that is gated.
+    if ((0, write_target_1.protectedKindOf)(opts.projectRoot, norm) === path.join('.ax', 'roles')) {
+        if (!(0, risk_gate_1.approvalCovers)(weApproval, { kind: 'config-write', target: norm }, nowTs)) {
+            return {
+                permissionDecision: 'deny',
+                permissionDecisionReason: '[Holmes-Kit] 역할 정책(.ax/roles/)은 이 게이트가 집행하는 권한 자체를 정의합니다 —'
+                    + ' 에이전트가 스스로 고칠 수 없습니다. config-write를 포함한 대역외 승인이 필요합니다.',
+            };
+        }
+    }
+    // @implements A-SPEC-191 §22 — 신원으로 묻는다. 철자 정규식은 프로젝트 안 링크 하나로 빗나갔다.
+    const configKind = (0, write_target_1.protectedFileKindOf)(opts.projectRoot, norm);
+    // @implements A-SPEC-163 — identity, not spelling. Measured: `.ax//ledger//p.jsonl`,
+    // `.ax/./ledger/p.jsonl` and `.AX/roles/policy.yaml` all reached the protected file while the
+    // regex saw a different string. Adding `//` to the pattern would only move the next variant.
+    if (configKind !== null || (0, write_target_1.isProtectedTarget)(opts.projectRoot, norm)) {
+        // @implements A-SPEC-133 — a token scoped to config-write authorizes this; a spec-only or
+        // out-of-scope token does not, so config forgery cannot ride a narrow grant.
+        if (!(0, risk_gate_1.approvalCovers)(weApproval, { kind: 'config-write', target: norm }, nowTs)) {
+            // @implements A-SPEC-193 §8 — 무엇을 막았는지 이름한다. 목록을 문장에 박아 두면 하네스가
+            // 늘 때마다 문면이 거짓이 된다(REQ-155: 엉뚱한 파일을 지목하는 진단의 값은 음수다).
+            const kindName = configKind ?? (0, write_target_1.protectedKindOf)(opts.projectRoot, norm) ?? '설정';
+            return { permissionDecision: 'deny', permissionDecisionReason: `[Holmes-Kit] ${kindName} 은(는) 훅·승인 설정입니다 — HOLMES_APPROVAL 을 위조하거나 거버넌스를 끌 수 있으므로 config-write 를 포함한 대역외 승인이 필요합니다` };
+        }
+    }
+    // Spec-file edit → graph-aware blast-radius risk (Tier-2 push-feed): a change to a widely-depended-on
+    // or foundational (REQ) spec ripples across the graph, so its risk is assessed from the spec
+    // dependency graph and escalated to out-of-band approval when the impact reaches the hard-hitl
+    // threshold. Uses only the already-loaded specs (cheap); non-spec edits skip this entirely.
+    // @implements A-SPEC-191 §23 (round 12) — identity, like every other protected surface. The
+    // resolved path is also what the disk is read with below: `existsSync(p)` on the caller's raw
+    // spelling answered "not approved" for `<file>/` and skipped the seal-breaking branch entirely.
+    const specTarget = (0, write_target_1.specTargetOf)(opts.projectRoot, specsDir, norm);
+    if (specTarget !== null) {
+        const p = specTarget;
+        // F1: a spec cannot SELF-APPROVE. `status: approved` is what unlocks every downstream gate
+        // (phaseCheck trusts the on-disk status). If the incoming write promotes a spec to approved and it
+        // is not ALREADY approved on disk, that is a new approval — an out-of-band act, never a raw tool
+        // write. Authoring/editing draft|review specs stays free; only the approval transition is gated.
+        // The status is read with the SAME YAML loader as downstream (parseSpec) so a quoted/commented
+        // `status: "approved"` cannot slip a bespoke regex (verification review — that reopened the bypass);
+        // a tolerant regex backs it up for Edit fragments that aren't a parseable full document.
+        let onDiskApproved = false;
+        try {
+            onDiskApproved = fs.existsSync(p) && (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8')).status === 'approved';
+        }
+        catch { /* treat as not approved */ }
+        // @implements A-SPEC-133 — spec approval/edit is authorized by a token covering spec-write.
+        const specWriteCovered = (0, risk_gate_1.approvalCovers)(weApproval, { kind: 'spec-write', target: norm }, nowTs);
+        if (incomingSetsApproved(input.tool_input) && !specWriteCovered) {
+            if (!onDiskApproved) {
+                return { permissionDecision: 'deny', permissionDecisionReason: registry_1.MESSAGES.SEAL_SELF_APPROVAL_RESTRICTED(path.basename(p, '.md'), 'A-SPEC-133') };
+            }
+        }
+        // @implements A-SPEC-132
+        // Sealed-content forgery rule: once a spec is approved on disk, editing its BODY or its seal
+        // fields is an approval-scope act — it either drifts the sealed content or forges the seal, both
+        // of which the whole P1 mechanism exists to prevent. Only spec_approve (out-of-band) may. Draft
+        // authoring stays free (onDiskApproved is false). Measured origin: an Edit rewriting an approved
+        // A-SPEC's Behavior section returned `allow` with no approval anywhere.
+        if (onDiskApproved && !specWriteCovered) {
+            return {
+                permissionDecision: 'deny',
+                permissionDecisionReason: registry_1.MESSAGES.SEAL_APPROVED_SPEC_MUTATION(path.basename(p, '.md'), undefined, 'A-SPEC-132'),
+            };
+        }
+        const m = /(REQ|H-SPEC|A-SPEC|C-SPEC|T-SPEC)-\d{3,}(?:\.\d+)?/.exec(path.basename(p));
+        if (m) {
+            const br = (0, rtm_check_1.computeBlastRadius)(readSpecsSync(specsDir), m[0]);
+            const brAction = { kind: 'edit', target: p, blastRadius: br };
+            const assessment = (opts?.assess ?? risk_classifier_1.assessRisk)(brAction);
+            if (assessment.level === 'hard-hitl' && !(0, risk_gate_1.isValidApproval)(opts.approval)) {
+                return {
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: `[Holmes-Kit] high blast-radius spec edit: ${assessment.reasons.join('; ')} — requires out-of-band approval`,
+                };
+            }
+        }
+        return { permissionDecision: 'allow' };
+    }
+    // @implements A-SPEC-167 — the body is passed so a shebang can be seen. `Edit` carries only a
+    // fragment, so the shebang check simply does not fire there; the path signals still answer.
+    const action = (0, phase_1.classifyAction)(relPath, input.tool_input.content);
+    if (!action)
+        return { permissionDecision: 'allow' };
+    // Read specs synchronously via a fresh walk (hook must be sync)
+    const specs = readSpecsSync(specsDir);
+    // @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
+    // an existing one, because the gate looked at the file's anchors rather than the change's. Only
+    // ADDED claims are checked — re-judging the file's existing ones would block the very edits
+    // needed to fix a spec that moved back to draft.
+    if (typeof input.tool_input.content === 'string') {
+        let previous;
+        try {
+            previous = fs.readFileSync(norm, 'utf8');
+        }
+        catch {
+            previous = undefined;
+        }
+        const added = (0, anchors_1.newlyClaimed)(input.tool_input.content, previous);
+        // An anchor naming a spec that does not exist is worse than one naming a draft — it claims
+        // authority from a document nobody can read. Unknown is treated as unapproved, the direction
+        // REQ-144 established for everything the gate cannot resolve.
+        const unapproved = added.filter((id) => specs.find((x) => x.id === id)?.status !== 'approved');
+        if (unapproved.length > 0) {
+            // @implements A-SPEC-182
+            // This is the SECOND place the gate refuses over an unapproved A-SPEC, and it fires before
+            // phaseCheck. The census over 244 governed runs found both wordings in the field — the
+            // phaseCheck one in 99 runs, this one in 18 — so improving only the first would leave the
+            // same inconsistency the REQ is about, just smaller. Same computation, same sentence.
+            const byId = new Map(specs.map((s) => [s.id, s]));
+            // Group by REASON, then cap the number of distinct reasons — not a positional slice.
+            // Two review findings meet here: the naive per-spec form grew a 139-character refusal to 2019
+            // by repeating one sentence five times, and the positional cap that replaced it silently
+            // dropped a THIRD spec's different blocker while telling the author the rest were "the same".
+            // Specs stuck for the same reason are named together; every distinct reason is shown.
+            const DISTINCT_REASON_CAP = 3;
+            // Group by REASON. The key is the summary SPLIT on the spec's own id and kept as parts, so no
+            // sentinel is inserted into user-controlled text — review found a `‹self›` marker being
+            // replaced inside a section NAME, and before that an id deleted outright so the author was
+            // told `id "" fails …`. Splitting loses nothing and can collide with nothing.
+            // Split on the spec's OWN id at a token boundary. A raw `split(id)` fired mid-token whenever
+            // the id was a prefix of another id in the same sentence — measured: `A-SPEC-901` whose parent
+            // `A-SPEC-9011` is missing rendered `depends_on "해당 스펙1" not found`, destroying the one
+            // fact the author needed. This repository's own dotted ids (`A-SPEC-100.1`) make the prefix
+            // relation ordinary, not exotic.
+            const selfRe = (id) => new RegExp(`(?<![\\w.-])${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w.-])`, 'g');
+            const byReason = new Map();
+            for (const id of unapproved) {
+                const summary = (0, approval_blockers_1.blockerSummary)(byId.get(id), (x) => byId.get(x) ?? null, id);
+                if (summary === null)
+                    continue;
+                const key = JSON.stringify(summary.slice(summary.indexOf(']') + 1).trim().split(selfRe(id)));
+                byReason.set(key, [...(byReason.get(key) ?? []), id]);
+            }
+            const groups = [...byReason];
+            // Rejoin with the spec's own id when the group is one spec; with a neutral phrase when it is
+            // several, because substituting the whole list produced `id "A-SPEC-90, A-SPEC-91" fails …` —
+            // a quoted id no spec has. The `[…]` label already names them.
+            // A single-spec group rejoins the sentence with the RAW id — a 20,000-char id made a
+            // 20,291-char refusal straight past every budget (round-1). tspec-state's rule 1 applies:
+            // an id longer than ID_MAX is never quoted; the […] label already carries the (folded) name.
+            // budgets IMPORTED from tspec-state (r5-192: hand-copied 80/1200 were the same second-truth
+            // family this REQ eliminated for ID_BUDGET/SPEC_STATUSES/ACTIONS).
+            // The blocker SENTENCE is spec-authored text (field echoes, allowed-value lists) — one
+            // pathological spec reproduced a 20,185-char refusal with every id list dutifully budgeted
+            // (round-1 [12]). Whole-sentence cap, REQ-183's REASON discipline.
+            const REASON_MAX = tspec_state_1.REASON_BUDGET;
+            // SHARED across groups (round-3: per-group caps let 3 pathological groups compose a
+            // 3,808-char refusal — tspec-state's discipline decrements ONE budget across specs).
+            let reasonLeft = REASON_MAX;
+            // SKIP, never cut (round-4): truncation mid-sentence sliced spec ids into other (or
+            // nonexistent) ids, split astral chars, and — worst — one pathological first group zeroed
+            // the budget so later SHORT sentences vanished under a FALSE '잘림' label. clampBlockers'
+            // discipline instead: an oversized sentence is replaced whole by an honest omission label,
+            // and fitting sentences keep rendering out of the shared budget.
+            const OMIT_OVER = ' (사유가 예산을 넘어 생략 — 해당 스펙을 개별 확인하십시오)';
+            const OMIT_SPENT = ' (문면 예산 소진 — 해당 스펙을 개별 확인하십시오)';
+            const shown0 = groups.slice(0, DISTINCT_REASON_CAP);
+            // @implements A-SPEC-192 §5R (round 9) — a SHARE, not a race. First-come-full-draw made the
+            // budget a cliff: one 1,199-character sentence (just under the cap) took the whole allowance
+            // and every short sibling vanished behind '예산 소진', while making that same sentence TEN
+            // characters LONGER flipped it to the omission label and brought the siblings back — a
+            // refusal that improves when the input gets worse. Each group is guaranteed its equal share
+            // first; whatever the short ones do not use is then offered to the rest in order.
+            const bodies = new Map();
+            for (const [key, ids] of shown0) {
+                bodies.set(key, JSON.parse(key).join(ids.length === 1 && ids[0].length <= tspec_state_1.ID_MAX ? ids[0] : '해당 스펙'));
+            }
+            // @implements A-SPEC-192 §8R (round 10, 2nd) — the SAME algorithm the sibling surface uses, and
+            // only that one. The share/remainder pair moved the cliff instead of removing it, and its two
+            // accounting units disagreed; here the share branch had additionally become dead code, which a
+            // mutation battery could only report as "equivalent" — a rule nothing enforces. One rule:
+            // spend the budget SHORTEST-FIRST on the sentences as they will be printed.
+            const priced = shown0
+                .map(([key], i) => ({ key, i, cost: (bodies.get(key) ?? '').length }))
+                .filter((g) => g.cost > 0 && g.cost <= REASON_MAX)
+                .sort((a, b) => a.cost - b.cost || a.i - b.i);
+            const allowance = new Map();
+            let pool = REASON_MAX;
+            for (const g of priced) {
+                if (g.cost <= pool) {
+                    allowance.set(g.key, pool);
+                    pool -= g.cost;
+                }
+                else
+                    allowance.set(g.key, 0);
+            }
+            reasonLeft = pool;
+            const render = (key, ids) => {
+                void ids;
+                const body = bodies.get(key) ?? '';
+                if (body.length > REASON_MAX)
+                    return OMIT_OVER;
+                if (body.length > (allowance.get(key) ?? 0))
+                    return OMIT_SPENT;
+                return body;
+            };
+            const shown = shown0;
+            const hidden = groups.slice(DISTINCT_REASON_CAP);
+            // @implements A-SPEC-192 — the three id lists ride REQ-183's budget: bounded naming, honest counts.
+            const why = shown.map(([key, ids]) => ` [${(0, tspec_state_1.listOrCount)(ids, tspec_state_1.ID_BUDGET, '개', Infinity)}] ${render(key, ids)}`).join('')
+                // Name the specs whose reasons did not fit. Saying only "N more" sends the author back to
+                // check all of them — the round-trip this REQ exists to remove.
+                + (hidden.length > 0
+                    ? ` (${(0, tspec_state_1.listOrCount)(hidden.flatMap(([, ids]) => ids), tspec_state_1.ID_BUDGET, '개', Infinity)}는 사유가 각각 달라 개별 확인이 필요하다)` : '');
+            return {
+                permissionDecision: 'deny',
+                permissionDecisionReason: `[Holmes-Kit] 이 변경이 새로 주장하는 ${(0, tspec_state_1.listOrCount)(unapproved, tspec_state_1.ID_BUDGET, '개', Infinity)}이(가) approved가 아닙니다`
+                    + ` — 기존 파일이라도 승인되지 않은 스펙을 주장할 수 없습니다.${why}`,
+            };
+        }
+    }
+    // @implements A-SPEC-175
+    // Ungoverned-project escape hatch. No-Spec-No-Code has no referent on a project that never opted
+    // into governance, and without this, pointing the Write|Edit matcher at a spec-less project denies
+    // 100% of source writes — a brick, not a gate. Found by installing into a fresh target and probing.
+    // The condition is deliberately narrow, because "no specs" must not become a way to disarm:
+    //   spec dir absent, and NO approval in the ledger -> never governed  -> allow
+    //   spec dir present, HOLMES_SPECS set, or the ledger remembers       -> deny, as before
+    //
+    // This comment used to justify the gap with two claims. Measured 2026-08-12 on an installed
+    // tarball: the first held — `rm -rf .ax/specs`, `rm -rf .ax`, `mv`, `git clean -fd .ax` and
+    // `git checkout -- .` are all denied by the shell risk gate. The second — "the Stop hook
+    // re-verifies the constitution" — was FALSE: with the spec tree gone the Stop hook produced no
+    // output and exited 0, because there was no constitution left to verify. Every route that is not a
+    // shell command (an editor, Finder, git run outside the session, a branch without specs, an
+    // unmounted drive) therefore switched governance off in silence. The ledger is what remembers.
+    // @implements A-SPEC-191 §26 (round 13) — this compared the specs directory to the DEFAULT as a
+    // STRING, and §17 (round 11) made the CLI pass an absolute path. So on every shipped invocation
+    // the comparison was false and A-SPEC-175's ungoverned escape was dead: a project with no specs
+    // had every code write denied with nothing the author could do about it, while the unit tests —
+    // which pass the relative default — kept the branch green. Compare the resolved LOCATIONS, and
+    // ask the filesystem about the same absolute path the rest of this function uses.
+    const specsDirAbs = path.isAbsolute(specsDir) ? specsDir : path.resolve(opts.projectRoot, specsDir);
+    const defaultSpecsAbs = path.resolve(opts.projectRoot, exports.DEFAULT_SPECS_DIR);
+    if (specs.length === 0 && specsDirAbs === defaultSpecsAbs && !fs.existsSync(specsDirAbs)
+        && !(0, governance_history_1.hasGovernanceHistory)(opts.projectRoot)) {
+        return { permissionDecision: 'allow' };
+    }
+    // Extract @implements A-SPEC-xxx from all available marker sources:
+    // - tool_input.content (Write payloads)
+    // - tool_input.new_string (Edit payloads)
+    // - the current on-disk contents of file_path, if it exists (Edit only changes a fragment,
+    //   so the marker may already be present elsewhere in the file being edited)
+    let onDiskContent = '';
+    try {
+        if (fs.existsSync(p)) {
+            onDiskContent = fs.readFileSync(p, 'utf8');
+        }
+    }
+    catch {
+        // Fail-open: if the file can't be read (permissions, race, etc.), just skip this source
+    }
+    // Marker precedence: an EXISTING file's OWN on-disk anchor governs it — a fragment that merely
+    // MENTIONS another spec id (a test fixture's anchor string, a doc snippet) must not re-anchor the
+    // edit to that id. Only when the file carries no on-disk anchor (new file, or first anchoring) does
+    // the incoming payload supply it. Found live: editing a test file whose fixture named an unapproved
+    // spec was denied even though the file's own anchor is approved.
+    const ANCHOR_RE = /@implements\s+(A-SPEC-\d{3,}(?:\.\d+)?)/;
+    const payloadAnchor = ANCHOR_RE.exec([input.tool_input.content ?? '', input.tool_input.new_string ?? ''].join('\n'));
+    const diskAnchor = ANCHOR_RE.exec(onDiskContent);
+    const m = diskAnchor ?? payloadAnchor;
+    // RE-ANCHORING must be scope-checked against the NEW spec (review C6: on-disk precedence meant an
+    // edit that rewrites the anchor line was judged under the OLD spec, so a file could be re-attributed
+    // to any spec without that spec's Files-to-Touch ever being consulted — which then mis-credits
+    // coverage evidence). Both the current and the incoming anchor must accept the path.
+    const anchorsToScope = [m?.[1], payloadAnchor?.[1] !== m?.[1] ? payloadAnchor?.[1] : undefined].filter(Boolean);
+    // @implements A-SPEC-132
+    // Stale-aware gate (rev.1): a target A-SPEC whose seal is PRESENT and BROKEN (edited after
+    // approval) or STALE (a parent moved) is not a trustworthy approval, so code must not be written
+    // against it — even though its status still reads 'approved'. The denial names staleness and
+    // spec_approve, deliberately DISTINCT from phaseCheck's "…이 approved가 아닙니다" (REQ-130's lesson:
+    // two different failures must not share the same words). An ABSENT seal falls through — the backfill
+    // closes that window and the Stop hook's unsealed-approval error blocks the turn regardless.
+    const resolveSpec = (id) => specs.find((s) => s.id === id) ?? null;
+    const sealProblem = (id) => {
+        if (!id)
+            return null;
+        const spec = specs.find((s) => s.id === id);
+        if (!spec || spec.status !== 'approved')
+            return null; // phaseCheck owns "not approved"
+        const seal = (0, spec_digest_1.sealOf)(spec);
+        if (!seal.approvedDigest)
+            return null; // absent seal: backfill + Stop hook territory
+        if ((0, spec_digest_1.specDigest)(spec) !== seal.approvedDigest)
+            return `${id}는 승인 이후 내용이 변경되었습니다(post-approval-edit)`;
+        for (const pid of spec.dependsOn) {
+            const parent = resolveSpec(pid);
+            if (!parent || parent.status !== 'approved')
+                continue;
+            const parentSeal = (0, spec_digest_1.sealOf)(parent).approvedDigest;
+            if (parentSeal && seal.parentDigests[pid] !== parentSeal)
+                return `${id}의 부모 ${pid}가 재승인되어 체인이 stale입니다(stale-parent)`;
+        }
+        return null;
+    };
+    // The qualifying T-SPEC matters for WRITE_CODE too — a stale test spec must not bless code.
+    const staleTarget = sealProblem(m?.[1]) ?? (action === 'WRITE_CODE'
+        ? (specs.filter((s) => s.type === 'T-SPEC' && s.status === 'approved' && m?.[1] && s.dependsOn.includes(m[1]))
+            .map((s) => sealProblem(s.id)).find(Boolean) ?? null)
+        : null);
+    // @implements A-SPEC-133 — the override is authorized by a token covering the code write.
+    const codeWriteCovered = (0, risk_gate_1.approvalCovers)(weApproval, { kind: 'code-write', target: relPath }, nowTs);
+    if (staleTarget && !codeWriteCovered) {
+        return { permissionDecision: 'deny', permissionDecisionReason: `[Holmes-Kit] ${staleTarget} — spec_approve로 재승인 후 진행하세요` };
+    }
+    // @implements A-SPEC-152
+    // Role gate — BEFORE the spec gate on purpose: if this identity may not perform the action at all,
+    // there is no point discussing whether a spec covers it, and answering with the spec reason would
+    // send the reader to fix the wrong thing.
+    //
+    // OPT-IN: `loadRolePolicy` returns null when the project has no `.ax/roles/`, and then this is a
+    // no-op — a project that never asked for roles must behave exactly as before. Once a policy
+    // exists it is fail-closed: no role, an unregistered role, and a role without the action are all
+    // refusals. The claim comes from the ENVIRONMENT only; a role in the payload would be the session
+    // asserting its own authority, which is what ART-5 forbids on the spec axis.
+    const roleIssue = (0, role_policy_1.roleCheck)(action, new identity_1.EnvIdentityProvider().current(), (0, role_policy_1.loadRolePolicy)(projectRoot));
+    if (roleIssue && !codeWriteCovered) {
+        return { permissionDecision: 'deny', permissionDecisionReason: roleIssue };
+    }
+    // @implements A-SPEC-134
+    // Constitution-debt gate: after the Stop gate gave up its block cap on an unresolved constitution,
+    // new CODE must not be layered on top of it. WRITE_TEST and spec authoring stay open — you must be
+    // able to fix the tests/specs that clear the debt. A covering approval overrides; a clean Stop
+    // clears the debt and code resumes.
+    if (action === 'WRITE_CODE' && !codeWriteCovered) {
+        const debt = (0, constitution_debt_1.readDebt)(projectRoot);
+        if (debt && debt.length > 0) {
+            return {
+                permissionDecision: 'deny',
+                permissionDecisionReason: `[Holmes-Kit] constitution-debt outstanding (${debt.join(', ')}) — resolve the constitution (a clean turn clears it) before writing new code, or supply a covering approval`,
+            };
+        }
+    }
+    const res = (0, phase_1.phaseCheck)(action, { specs, targetAspecId: m?.[1] });
+    if (res.decision === 'deny') {
+        // @implements A-SPEC-175
+        // When the spec tree is gone from a project the ledger remembers approving, the generic
+        // "no approved A-SPEC" is true but useless — the specs are not unwritten, they are missing, and
+        // the fix is to restore them or to leave governance properly. Appended rather than substituted:
+        // the phase gate's own verdict is still what denied this.
+        const lost = specs.length === 0 && !fs.existsSync(specsDir)
+            && (0, governance_history_1.hasGovernanceHistory)(path.resolve(specsDir, '..', '..'));
+        return {
+            permissionDecision: 'deny',
+            permissionDecisionReason: `[Holmes-Kit] ${res.remediation?.message} → ${res.remediation?.next_action} (${res.remediation?.discipline})`
+                + (lost ? `\n${governance_history_1.GOVERNANCE_LOST_HINT}` : ''),
+        };
+    }
+    // Marker self-attestation mitigation: an @implements anchor is a claim the writer makes. When the
+    // anchored A-SPEC's `Files to Touch` names CONCRETE paths, the file must fall under one of them —
+    // so anchoring evil.ts (or an unrelated edit) to a random approved spec fails when that spec scoped
+    // its files. Applies to EVERY governed code Write/Edit, not just new files: the earlier new-file-only
+    // scoping left "create it some other way, then edit freely" open, and a stale anchor blessed
+    // unrelated edits forever. The legitimate flow is to extend the spec's Files-to-Touch FIRST
+    // (editing an approved spec's sections is allowed; only the approval transition is gated).
+    // Still bounded: only when concrete paths are listed (a prose/TODO section imposes nothing), and a
+    // valid out-of-band approval overrides. Verified 0/93 violations across this repo's anchored files.
+    for (const anchorId of anchorsToScope) {
+        const aspec = specs.find((s) => s.id === anchorId);
+        const ftt = aspec?.sections['Files to Touch'] ?? '';
+        const listed = ftt.match(/[\w@.-]+(?:\/[\w@.*-]+)+/g) ?? []; // concrete path-like tokens only
+        if (listed.length === 0)
+            continue; // prose-only section imposes nothing
+        const rel = relPath;
+        const covered = listed.some((t) => {
+            const tok = t.replace(/\/?\*+$/, ''); // dir/** -> dir
+            const dir = /\.[A-Za-z0-9]+$/.test(tok) ? tok.replace(/\/[^/]*$/, '') : tok; // file -> its dir
+            return rel === tok || rel.startsWith(tok + '/') || rel.startsWith(dir + '/');
+        });
+        if (!covered && !codeWriteCovered) { // @implements A-SPEC-133 — same code-write coverage as the stale gate
+            return {
+                permissionDecision: 'deny',
+                permissionDecisionReason: `[Holmes-Kit] ${rel} is anchored to ${anchorId} but falls outside its 'Files to Touch' scope — extend that section first (spec edit is allowed) or supply out-of-band approval`,
+            };
+        }
+    }
+    return { permissionDecision: 'allow' };
+}
+// Synchronous spec loader for hook context (fail-open: directory read errors are skipped)
+function readSpecsSync(root) {
+    const out = [];
+    const walk = (d) => {
+        if (!fs.existsSync(d))
+            return;
+        // Wrap the entire directory read in try/catch to handle permission errors, ENOTDIR, etc.
+        try {
+            for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+                const q = path.join(d, e.name);
+                try {
+                    if (e.isDirectory())
+                        walk(q);
+                    else if (e.name.endsWith('.md')) {
+                        const spec = (0, spec_parser_1.parseSpec)(fs.readFileSync(q, 'utf8'));
+                        // Only include valid specs with non-empty id
+                        if (spec.id) {
+                            out.push(spec);
+                        }
+                    }
+                }
+                catch {
+                    // Skip individual files/entries that fail to read or parse
+                }
+            }
+        }
+        catch {
+            // Skip directories that cannot be read (permission denied, not a directory, symlink loop, etc.)
+            // This ensures the walk is fully fail-open and never throws.
+        }
+    };
+    walk(root);
+    return out;
+}
+// CLI entry point: Claude Code passes hook JSON via stdin
+// Wrapped in fail-open error handling: any error emits allow + exits 0 to avoid blocking workflows
+if (require.main === module) {
+    let buf = '';
+    process.stdin.on('data', (c) => (buf += c));
+    process.stdin.on('end', () => {
+        try {
+            // @implements A-SPEC-144 — normalize BEFORE deciding: most of the measured bypasses were a
+            // wrong type reaching code that assumed a string, not an interesting failure of the gate.
+            const input = normalizeHookInput(JSON.parse(buf || '{}'));
+            // @implements A-SPEC-149
+            // The ONE place process context is read. `evaluateHook` no longer reaches for `process.cwd()`
+            // or `process.env` on its own, so a caller always states which project it is judging and under
+            // whose authority — and a unit test's verdict stops depending on the shell it ran in.
+            // @implements A-SPEC-191 §13 — the ledger a single-use approval is spent in must be the
+            // PROJECT's, not the shell's. Round-9 measured it: running an agent from a subdirectory made
+            // `process.cwd()` the anchor, so a consumed nonce opened again and a stray `.ax/ledger` grew
+            // outside the project. The walk stops at the same marker every consumer uses.
+            // @implements A-SPEC-191 §24 (round 12) — `resolveProjectRoot` answers `{root: cwd, marker:
+            // 'given'}` when it finds NOTHING, and this took that answer as a project. On the first-class
+            // `--specs-dir docs/specs` deployment (no `.ax` anywhere) a session started in a subdirectory
+            // therefore declared that subdirectory the project, and every file of the real project became
+            // "outside the project" — config-write, No-Spec-No-Code and the scope check all off from the
+            // first turn. §19/§21 taught `stop.ts` exactly this and the lesson never crossed to here.
+            // Look for the marker, then for the wired spec directory (the deployment's own evidence), and
+            // only then fall back to cwd — as an UNANCHORED root, which mints nothing (see below).
+            const hookRoot = (() => {
+                try {
+                    const { resolveProjectRoot } = require('../project/root');
+                    const r = resolveProjectRoot(process.cwd());
+                    if (r.marker !== 'given')
+                        return { root: r.root, anchored: true };
+                }
+                catch { /* fall through to the wired-specs walk */ }
+                const wired = wiredSpecsDir(process.argv, process.env);
+                if (!path.isAbsolute(wired)) {
+                    let dir = process.cwd();
+                    for (let hop = 0; hop < 64; hop++) {
+                        if (fs.existsSync(path.join(dir, wired)))
+                            return { root: dir, anchored: true };
+                        const parent = path.dirname(dir);
+                        if (parent === dir)
+                            break;
+                        dir = parent;
+                    }
+                }
+                return { root: process.cwd(), anchored: false };
+            })();
+            const hookProjectRoot = hookRoot.root;
+            // @implements A-SPEC-191 §17 (round 11) — and the SPECS the gate judges against come from the
+            // same tree. Round-10 moved the project root here and left this path relative, so a session
+            // opened in a subdirectory looked for `<sub>/.ax/specs`, found nothing, and `isGovernedProject`
+            // answered false — which is the branch that fails OPEN. Measured on a real governed project:
+            // No-Spec-No-Code, Files-to-Touch scope, spec promotion and the phase gate all flipped to
+            // allow on the FIRST turn, with no approval, no shell trick and no planted marker; only the
+            // path-pattern rules (.mcp.json, .ax/roles) still bit, which is exactly what makes a
+            // spot-check look healthy. Same one-line shape the Stop hook already carries.
+            const specsDirWired = (() => {
+                const wired = wiredSpecsDir(process.argv, process.env);
+                return path.isAbsolute(wired) ? wired : path.join(hookProjectRoot, wired);
+            })();
+            const out = evaluateHook(input, specsDirWired, {
+                projectRoot: hookProjectRoot,
+                approval: readApprovalFromEnv(),
+                resolveRmSignals: (command) => resolveRmSignals(command, hookProjectRoot),
+            });
+            process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', ...out } }));
+            // N3 provenance: record the audit-critical decision classes on the tamper-evident chain —
+            // every DENY, and every ALLOW that was unlocked by an out-of-band approval. Fail-open: a
+            // provenance write failure never changes the already-computed verdict.
+            try {
+                // @implements A-SPEC-191 §25 (round 13) — the `anchored` flag §24 introduced was never read,
+                // so a hook that found NEITHER a marker NOR the wired spec directory still wrote
+                // `<cwd>/.ax/ledger/` and minted the very marker the next resolution stops at. §19 removed
+                // exactly this from `stop.ts`; it stayed here because round-12's first draft of the guard
+                // was reverted wholesale after it broke three audit-line tests. The guard was not wrong —
+                // its FIXTURES were: a project's audit chain belongs to a project, and `holmes-kit init`
+                // creates `.ax/specs` before any hook runs, so there is no first turn that needs minting.
+                // A directory that carries `.ax` already is a project and is written to as before.
+                if (!hookRoot.anchored && !fs.existsSync(path.join(hookProjectRoot, '.ax'))) {
+                    throw new Error('unanchored: no project to record against');
+                }
+                const approval = readApprovalFromEnv();
+                const valid = (0, risk_gate_1.isValidApproval)(approval);
+                // @implements A-SPEC-191 §11 — 'unlocked' must mean an approval OPENED something. The old
+                // predicate (allow + well-formed approval) filed an `approved-action` for every ordinary
+                // allow while any approval sat in the environment: r8 measured a Write, unblocked by nobody,
+                // recorded as approved under a token that had expired in 2000. Under a session key that made
+                // the whole log 'approved-action' and hid the real openings. Ask the counterfactual instead:
+                // would this same call have been denied with no approval in hand?
+                const withoutApproval = out.permissionDecision === 'allow' && valid
+                    ? evaluateHook(input, specsDirWired, {
+                        projectRoot: hookProjectRoot,
+                        approval: undefined,
+                        resolveRmSignals: (command) => resolveRmSignals(command, process.cwd()),
+                    })
+                    : undefined;
+                const unlocked = withoutApproval?.permissionDecision === 'deny';
+                if (out.permissionDecision === 'deny' || unlocked) {
+                    const target = input.tool_input?.file_path
+                        ? (0, provenance_chain_1.redactTarget)('path', input.tool_input.file_path)
+                        : (0, provenance_chain_1.redactTarget)('command', input.tool_input?.command ?? '');
+                    // @implements A-SPEC-148 — writes go to THIS replica's chain; the legacy file is read-only now.
+                    new ledger_store_1.FileLedgerStore(path.join(hookProjectRoot, path.dirname(provenance_chain_1.PROVENANCE_FILE))).append({
+                        ts: new Date().toISOString(),
+                        actor: unlocked && approval ? approval.actor : 'agent',
+                        kind: out.permissionDecision === 'deny' ? 'gate-deny' : 'approved-action',
+                        // REDACTED. Both fields used to carry the raw command; an audit of this repository's own
+                        // ledger found 15 of 29 records leaking absolute home paths and 6 matching secret-ish
+                        // patterns. That is structural: the gate denies `echo $HOLMES_APPROVAL` and
+                        // `HOLMES_LEDGER_KEY=…`, and denials are precisely what gets recorded — so the audit
+                        // trail was the one artefact guaranteed to accumulate the secrets the gate protects.
+                        // `summary` keeps the human-readable classification, which is the auditable part.
+                        summary: out.permissionDecision === 'deny'
+                            ? (out.permissionDecisionReason ?? 'denied')
+                            : `approved action: ${input.tool_name} ${target}`.slice(0, 300),
+                        // @implements A-SPEC-133 — a master-key use becomes an audit line: the approval's
+                        // narrowing (or its absence) travels with the record (r7-191: promised, never shipped).
+                        inputs: [input.tool_name, target,
+                            ...(unlocked ? [(0, provenance_chain_1.approvalMarkers)(approval)] : []), // 한 항목·마지막 자리 — 표지가 갈라져 자기모순이 되지 않는다
+                        ].filter(Boolean),
+                        // round-9: a deny inherited the actor/rationale/authorization of an ambient approval that
+                        // did NOT cover it, so the audit line credited an authorizer who authorized nothing.
+                        rationale: unlocked && approval ? approval.rationale : '',
+                        // NEVER the raw token (review #1): a fingerprint identifies the credential without
+                        // storing the replayable secret; invalid approval attempts record nothing of it.
+                        authorization: unlocked && approval ? (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token) : '',
+                    });
+                }
+            }
+            catch { /* provenance must never break the gate */ }
+            if (out.permissionDecision === 'deny') {
+                // Belt-and-suspenders: Claude Code's exit-code-2 contract feeds STDERR back to the
+                // model as the block reason, while permissionDecisionReason in the stdout JSON is
+                // read on the exit-0 (allow) channel. Write the reason to both so the remediation
+                // string reaches the model regardless of which channel a given CC version honors.
+                process.stderr.write(`${out.permissionDecisionReason ?? ''}\n`);
+                process.exit(2);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            // @implements A-SPEC-144
+            // An error must never GRANT. This used to answer `allow` unconditionally, which made a wrong
+            // type in `file_path` a working bypass of No-Spec-No-Code and every future bug in the gate a
+            // silent one. Direction is decided by governance, and the escape is the operator's alone.
+            const message = err instanceof Error ? err.message : String(err);
+            // The error path resolves the project the same way the normal path does — the failure that
+            // brought us here must not also decide which tree we are judging (§17).
+            const errProjectRoot = (() => {
+                try {
+                    const { resolveProjectRoot } = require('../project/root');
+                    return resolveProjectRoot(process.cwd()).root;
+                }
+                catch {
+                    return process.cwd();
+                }
+            })();
+            const decision = gateErrorDecision(message, process.env, process.argv, errProjectRoot);
+            process.stderr.write(`[Holmes-Kit PreToolUse Hook] Error: ${message}\n`);
+            process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', ...decision } }));
+            if (decision.permissionDecision === 'deny') {
+                process.stderr.write(`${decision.permissionDecisionReason ?? ''}\n`);
+                process.exit(2);
+            }
+            process.exit(0);
+        }
+    });
+}