@holmes-lab/holmes-kit 0.1.12 → 0.1.13

package/dist/holmes/governance/approval-queue.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The approval request queue — the review list a human batches decisions over.
+ *
+ * @implements A-SPEC-244
+ * WHY THIS EXISTS. Six gate sites refuse with "an out-of-band approval is required" and leave no
+ * trace. Dogfooded on a real Python repository (Notion, 2026-08-23): the agent retried the same
+ * blocked action six times, the operator had no list of what was waiting, and the narrower the
+ * approval token's scope, the more round-trips each decision cost — least privilege and usability in
+ * direct conflict (UX-3). Batch review needs a list, and the list must be written by the refusing
+ * gate itself; a list humans maintain by hand goes stale the day it is written.
+ *
+ * WHAT THIS IS NOT. Authority. Nothing in this file opens any gate: a forged `granted` event changes
+ * no verdict anywhere, which is the property that lets the queue ship before its directory has any
+ * write protection. Authority arrives in the next slice as nonce-bound grant files, verified by the
+ * same `approvalCovers`/`consumeNonceExclusively` the env channel already uses.
+ *
+ * Storage is an append-only jsonl event log folded into state — the idiom `FindingsLedger` and the
+ * provenance chain already use, so a reader learns no new model.
+ */
+export declare const QUEUE_RELPATH: string;
+export interface PendingRequest {
+    id: string;
+    kind: string;
+    target: string;
+    why: string;
+    count: number;
+    firstTs: string;
+    lastTs: string;
+    hold?: boolean;
+    question?: string;
+}
+export interface QueueState {
+    pending: PendingRequest[];
+    /** Broken lines are counted, never swallowed: an empty-looking queue must be distinguishable from a corrupted one. */
+    malformedLines: number;
+    /**
+     * The LAST decision per request id.
+     *
+     * @implements A-SPEC-246
+     * Exposed so a refusal can show the agent what a human already decided — measured six consecutive
+     * retries of one blocked action, because the agent had no way to see that a human had said no.
+     * An invisible decision cannot stop a retry loop.
+     */
+    decisions: Record<string, {
+        event: 'granted' | 'denied';
+        reason?: string;
+        ts: string;
+    }>;
+}
+/**
+ * Deterministic request id from the action's identity.
+ *
+ * @implements A-SPEC-244
+ * The same refusal must produce the same id or repeats cannot fold — measured six consecutive
+ * stop-hook blocks for one violation, which as six list rows would drown the review list. Random
+ * ids cannot fold, and randomness is a material this repository already avoids for determinism.
+ * The timestamp rides on the EVENT, never in the id.
+ */
+export declare function approvalRequestId(kind: string, target: string): string;
+/**
+ * Fold queue events into the current pending list. Pure.
+ *
+ * An unknown event kind — a future version's vocabulary — neither throws nor flips any existing
+ * entry's pending state: an old CLI reading a new queue must not silently mis-report what is
+ * waiting.
+ */
+export declare function foldQueue(lines: string[]): QueueState;
+/**
+ * Append a request event. Fire-and-forget.
+ *
+ * @implements A-SPEC-244
+ * Every failure is swallowed into `false`: this runs INSIDE gate verdict paths, and the moment a
+ * dead queue could change a verdict, killing the queue becomes a way to manipulate the gate. The
+ * caller uses the boolean only to decide whether to print the review hint.
+ */
+export declare function enqueueApprovalRequest(root: string, req: {
+    kind: string;
+    target: string;
+    why: string;
+}): boolean;
+/** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
+export declare function readQueue(root: string): QueueState;
+/**
+ * The refusal-message suffix pointing the operator at the review CLI.
+ *
+ * Appended ONLY when the enqueue succeeded: a hint naming an id that was never written would send
+ * the operator to an empty list.
+ */
+export declare function queueHint(root: string, req: {
+    kind: string;
+    target: string;
+    why: string;
+}): string;

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

@@ -0,0 +1,230 @@
+"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.QUEUE_RELPATH = void 0;
+exports.approvalRequestId = approvalRequestId;
+exports.foldQueue = foldQueue;
+exports.enqueueApprovalRequest = enqueueApprovalRequest;
+exports.readQueue = readQueue;
+exports.queueHint = queueHint;
+// @implements A-SPEC-244
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * The approval request queue — the review list a human batches decisions over.
+ *
+ * @implements A-SPEC-244
+ * WHY THIS EXISTS. Six gate sites refuse with "an out-of-band approval is required" and leave no
+ * trace. Dogfooded on a real Python repository (Notion, 2026-08-23): the agent retried the same
+ * blocked action six times, the operator had no list of what was waiting, and the narrower the
+ * approval token's scope, the more round-trips each decision cost — least privilege and usability in
+ * direct conflict (UX-3). Batch review needs a list, and the list must be written by the refusing
+ * gate itself; a list humans maintain by hand goes stale the day it is written.
+ *
+ * WHAT THIS IS NOT. Authority. Nothing in this file opens any gate: a forged `granted` event changes
+ * no verdict anywhere, which is the property that lets the queue ship before its directory has any
+ * write protection. Authority arrives in the next slice as nonce-bound grant files, verified by the
+ * same `approvalCovers`/`consumeNonceExclusively` the env channel already uses.
+ *
+ * Storage is an append-only jsonl event log folded into state — the idiom `FindingsLedger` and the
+ * provenance chain already use, so a reader learns no new model.
+ */
+exports.QUEUE_RELPATH = path.join('.ax', 'approvals', 'queue.jsonl');
+/**
+ * Deterministic request id from the action's identity.
+ *
+ * @implements A-SPEC-244
+ * The same refusal must produce the same id or repeats cannot fold — measured six consecutive
+ * stop-hook blocks for one violation, which as six list rows would drown the review list. Random
+ * ids cannot fold, and randomness is a material this repository already avoids for determinism.
+ * The timestamp rides on the EVENT, never in the id.
+ */
+function approvalRequestId(kind, target) {
+    return 'req-' + (0, node_crypto_1.createHash)('sha256').update(`${kind}:${target}`).digest('hex').slice(0, 12);
+}
+/**
+ * Fold queue events into the current pending list. Pure.
+ *
+ * An unknown event kind — a future version's vocabulary — neither throws nor flips any existing
+ * entry's pending state: an old CLI reading a new queue must not silently mis-report what is
+ * waiting.
+ */
+function foldQueue(lines) {
+    const pending = new Map();
+    const decisions = {};
+    let malformedLines = 0;
+    for (const raw of Array.isArray(lines) ? lines : []) {
+        const line = String(raw ?? '').trim();
+        if (line === '')
+            continue;
+        let e;
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                malformedLines++;
+                continue;
+            }
+            e = parsed;
+        }
+        catch {
+            malformedLines++;
+            continue;
+        }
+        const id = typeof e.id === 'string' ? e.id : undefined;
+        switch (e.event) {
+            case 'requested': {
+                if (!id) {
+                    malformedLines++;
+                    break;
+                }
+                const prev = pending.get(id);
+                const ts = typeof e.ts === 'string' ? e.ts : '';
+                if (prev) {
+                    prev.count += 1;
+                    prev.lastTs = ts || prev.lastTs;
+                }
+                else {
+                    pending.set(id, {
+                        id,
+                        kind: String(e.kind ?? ''),
+                        target: String(e.target ?? ''),
+                        why: String(e.why ?? ''),
+                        count: 1,
+                        firstTs: ts,
+                        lastTs: ts,
+                    });
+                }
+                break;
+            }
+            case 'granted':
+            case 'denied':
+                if (id) {
+                    pending.delete(id);
+                    decisions[id] = {
+                        event: e.event,
+                        ...(typeof e.reason === 'string' ? { reason: e.reason } : {}),
+                        ts: typeof e.ts === 'string' ? e.ts : '',
+                    };
+                }
+                break;
+            case 'held': {
+                const entry = id ? pending.get(id) : undefined;
+                if (entry) {
+                    entry.hold = true;
+                    if (typeof e.question === 'string')
+                        entry.question = e.question;
+                }
+                break;
+            }
+            default:
+                // Future vocabulary: preserved by ignoring, never by guessing.
+                break;
+        }
+    }
+    return { pending: [...pending.values()], malformedLines, decisions };
+}
+/**
+ * Append a request event. Fire-and-forget.
+ *
+ * @implements A-SPEC-244
+ * Every failure is swallowed into `false`: this runs INSIDE gate verdict paths, and the moment a
+ * dead queue could change a verdict, killing the queue becomes a way to manipulate the gate. The
+ * caller uses the boolean only to decide whether to print the review hint.
+ */
+function enqueueApprovalRequest(root, req) {
+    try {
+        // @implements A-SPEC-244
+        // Only under an EXISTING .ax. The constitution suite (§25a) caught the first cut creating
+        // .ax/approvals in a bare directory on a config-write refusal — the hook planting a governance
+        // marker where governance was never opted into, the exact defect A-SPEC-191 §25 exists to stop.
+        // An ungoverned directory gets no queue and no hint; it is not part of the system.
+        if (!fs.existsSync(path.join(root, '.ax')))
+            return false;
+        const file = path.join(root, exports.QUEUE_RELPATH);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const event = {
+            event: 'requested',
+            id: approvalRequestId(req.kind, req.target),
+            kind: req.kind,
+            target: req.target,
+            why: req.why,
+            ts: new Date().toISOString(),
+        };
+        fs.appendFileSync(file, JSON.stringify(event) + '\n');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
+function readQueue(root) {
+    try {
+        const raw = fs.readFileSync(path.join(root, exports.QUEUE_RELPATH), 'utf8');
+        return foldQueue(raw.split('\n'));
+    }
+    catch {
+        return { pending: [], malformedLines: 0, decisions: {} };
+    }
+}
+/**
+ * The refusal-message suffix pointing the operator at the review CLI.
+ *
+ * Appended ONLY when the enqueue succeeded: a hint naming an id that was never written would send
+ * the operator to an empty list.
+ */
+function queueHint(root, req) {
+    const id = approvalRequestId(req.kind, req.target);
+    // @implements A-SPEC-246
+    // Decisions are read BEFORE filing, so a human's answer reaches the agent in the very refusal
+    // that would otherwise just say "waiting". A hold shows its question INSTEAD of the waiting line —
+    // the question is the actionable part, and the agent's job is to carry it to the user. A denial
+    // shows its reason and still re-files: a human may change their mind, and the re-filed entry is
+    // how the reviewer sees the agent still wants it.
+    const state = readQueue(root);
+    const held = state.pending.find((p) => p.id === id && p.hold);
+    if (held) {
+        return `\n[보류 — 운영자 질문: ${held.question ?? '(질문 없음)'}] 게이트는 닫혀 있습니다.`
+            + ' 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 npx holmes-kit approve 에서 내립니다.';
+    }
+    const decided = state.decisions[id];
+    const denialLine = decided?.event === 'denied'
+        ? `\n[거부됨${decided.reason ? `: ${decided.reason}` : ''}] 같은 요청을 반복하지 말고 거부 사유를 해소해 사용자와 상의하십시오.`
+        : '';
+    return enqueueApprovalRequest(root, req)
+        ? `${denialLine}\n[승인 대기 ${id}] 운영자: npx holmes-kit approve`
+        : denialLine;
+}

package/dist/holmes/guardrail/risk-classifier.js

@@ -257,14 +257,21 @@ function scopeAxToProject(cmd, projectRoot) {
 // `state` joined the protected set with P3 (REQ-134): it holds the constitution-debt and the
 // last-green baseline, so a single-file `rm` there would bypass the WRITE_CODE debt gate — measured
 // in the campaign completeness critique. Deleting governance state is now hard-hitl like every other.
-const PROTECTED_AX_PATH_RE = /(^|\/)\.ax\/(specs|decisions|ledger|cpg_cache|state|roles)(\/|$)/;
+// @implements A-SPEC-245
+// ONE alternation, five regexes. The list of protected .ax directories was spelled out in five
+// separate literals here, and adding 'approvals' to only one of them was measured immediately:
+// 'echo x > .ax/approvals/grants/forged.json' passed while the Write gate refused the same file —
+// the exact two-copies drift this repository has paid for with isTestFile and a restated section
+// splitter. The directories are now written once; each rule keeps its own shape around them.
+const PROTECTED_AX_ALT = 'specs|decisions|ledger|cpg_cache|state|roles|approvals';
+const PROTECTED_AX_PATH_RE = new RegExp(String.raw `(^|/)\.ax/(${PROTECTED_AX_ALT})(/|$)`);
 // A removal verb + a protected .ax path anywhere in a shell command — the command form of
 // the governance-path delete, which the structured `kind:'delete'` branch alone would miss.
 // Not just removal: RELOCATING or CLOBBERING a protected .ax path is equally destructive to it, so
 // mv/cp/git-mv and a `>` truncation count too (review F4 — `mv .ax/specs /tmp` evaded the rm-only rule).
 const REMOVAL_VERB_RE = /\b(rm|rmdir|unlink|git\s+rm|git\s+mv|mv|cp)\b/i;
-const CLOBBER_AX_RE = />\s*['"]?[^\s;&|]*\.ax\/(specs|decisions|ledger|cpg_cache|state|roles)\b/i;
-const CMD_PROTECTED_AX_RE = /(^|[\s'"=(/])\.ax\/(specs|decisions|ledger|cpg_cache|state|roles)(\/|\b)/;
+const CLOBBER_AX_RE = new RegExp(String.raw `>\s*['"]?[^\s;&|]*\.ax/(${PROTECTED_AX_ALT})\b`, 'i');
+const CMD_PROTECTED_AX_RE = new RegExp(String.raw `(^|[\s'"=(/])\.ax/(${PROTECTED_AX_ALT})(/|\b)`);
 /**
  * Normalize a command string for protected-path matching: collapse `//` runs and `./` segments so
  * `./.ax//ledger/x` matches the same rules as `.ax/ledger/x` (adversarial probe: those forms slipped
@@ -285,11 +292,11 @@ function normalizeCommandPaths(cmd) {
 }
 // File-mutating shell verbs beyond redirect/removal: these WRITE a target path, so a protected path
 // as their argument is the same governance breach as `>` or `rm` (probe: tee/cp/install slipped).
-const WRITE_VERB_AX_RE = /\b(?:tee|cp|install|dd|ln|mv|rsync)\b[^;&|\n]*\.ax\/(?:specs|decisions|ledger|cpg_cache|state|roles)\b/i;
+const WRITE_VERB_AX_RE = new RegExp(String.raw `\b(?:tee|cp|install|dd|ln|mv|rsync)\b[^;&|\n]*\.ax/(?:${PROTECTED_AX_ALT})\b`, 'i');
 // An interpreter one-liner naming a protected path: `node -e "...appendFileSync('.ax/ledger/...')"`,
 // `python3 -c "open('.ax/ledger/...','a')"`. Read-only one-liners are not distinguishable from writes
 // here, so this is deliberately conservative on the .ax governance surface only.
-const INTERPRETER_AX_RE = /\b(?:node|python3?|ruby|perl|deno|bun)\b[^;&|\n]*-(?:e|c|-eval)\b[^\n]*\.ax\/(?:specs|decisions|ledger|cpg_cache|state|roles)\b/i;
+const INTERPRETER_AX_RE = new RegExp(String.raw `\b(?:node|python3?|ruby|perl|deno|bun)\b[^;&|\n]*-(?:e|c|-eval)\b[^\n]*\.ax/(?:${PROTECTED_AX_ALT})\b`, 'i');
 /**
  * Commands that only read. Everything else over a governance path is a write.
  *

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

@@ -168,6 +168,8 @@ function resolveTarget(root, raw, depth = 0) {
 }
 /** Governance directories, relative to the project root. */
 const PROTECTED_DIRS = [
+    // @implements A-SPEC-245 — grant files ARE approvals; a session that can write them mints its own.
+    path.join('.ax', 'approvals'),
     path.join('.ax', 'ledger'),
     path.join('.ax', 'roles'),
     path.join('.ax', 'cpg_cache'),

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

@@ -69,6 +69,8 @@ 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_queue_1 = require("../governance/approval-queue");
+const approval_grants_1 = require("../governance/approval-grants");
 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
@@ -399,13 +401,21 @@ function evaluateHook(input, specsDir, opts) {
         // 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);
+            // @implements A-SPEC-245 — env first, then the grant files. The grant's mandatory nonce rides
+            // the SAME atomic ledger consumption below, so hard-hitl single-use needs no new machinery.
+            const resolved = (0, approval_grants_1.resolveApproval)(opts.projectRoot, approval, { kind: 'shell', target: command }, nowTs);
+            const covers = resolved !== undefined;
+            const acting = resolved?.approval ?? approval;
             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-244 — the refusal itself files the review request. The queue kind is the
+            // approval SCOPE kind ('shell'), so the reviewing CLI can mint a covering grant mechanically.
+            if (!covers) {
+                return deny('requires an approval that covers this command'
+                    + (0, approval_queue_1.queueHint)(opts.projectRoot, { kind: 'shell', target: command, why: assessment.reasons.join('; ') }));
+            }
             // @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
@@ -420,16 +430,16 @@ function evaluateHook(input, specsDir, opts) {
             // 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)) {
+            if ((0, provenance_chain_1.blankNonce)(acting?.nonce)) {
                 return deny('승인이 단일 사용(nonce)을 선언했으나 값이 비어 있습니다 — 1회성을 집행할 수 없어 거부합니다');
             }
-            if (approval?.nonce) {
+            if (acting?.nonce) {
                 let won;
                 try {
-                    won = (0, provenance_chain_1.consumeNonceExclusively)(approval.nonce, ledgerFile, {
-                        ts: nowTs, actor: approval.actor, kind: 'nonce-consumed',
+                    won = (0, provenance_chain_1.consumeNonceExclusively)(acting.nonce, ledgerFile, {
+                        ts: nowTs, actor: acting.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),
+                        inputs: [(0, provenance_chain_1.nonceFingerprint)(acting.nonce)], rationale: acting.rationale, authorization: (0, provenance_chain_1.authorizationRef)(acting.actor, acting.token),
                     });
                 }
                 catch (err) {
@@ -441,6 +451,9 @@ function evaluateHook(input, specsDir, opts) {
                 }
                 if (!won)
                     return deny('single-use approval already consumed (replay)');
+                // The ledger consumption is the authority; removing the file is cleanup for the next reader.
+                if (resolved?.source === 'grant')
+                    (0, approval_grants_1.consumeGrantFile)(opts.projectRoot, acting.nonce);
             }
         }
         // Bash BYPASS gates (adversarial review: `cat > evil.ts` created ungoverned files, `echo x >
@@ -715,13 +728,18 @@ function evaluateHook(input, specsDir, opts) {
     // 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)) {
+        // @implements A-SPEC-245 — grant files answer here too; consumed on the allowed write below.
+        const rolesResolved = (0, approval_grants_1.resolveApproval)(opts.projectRoot, weApproval, { kind: 'config-write', target: norm }, nowTs);
+        if (rolesResolved === undefined) {
             return {
                 permissionDecision: 'deny',
                 permissionDecisionReason: '[Holmes-Kit] 역할 정책(.ax/roles/)은 이 게이트가 집행하는 권한 자체를 정의합니다 —'
-                    + ' 에이전트가 스스로 고칠 수 없습니다. config-write를 포함한 대역외 승인이 필요합니다.',
+                    + ' 에이전트가 스스로 고칠 수 없습니다. config-write를 포함한 대역외 승인이 필요합니다.'
+                    + (0, approval_queue_1.queueHint)(opts.projectRoot, { kind: 'config-write', target: norm, why: '역할 정책(.ax/roles/) 쓰기' }),
             };
         }
+        if (rolesResolved.source === 'grant' && rolesResolved.approval.nonce)
+            (0, approval_grants_1.consumeGrantFile)(opts.projectRoot, rolesResolved.approval.nonce);
     }
     // @implements A-SPEC-191 §22 — 신원으로 묻는다. 철자 정규식은 프로젝트 안 링크 하나로 빗나갔다.
     const configKind = (0, write_target_1.protectedFileKindOf)(opts.projectRoot, norm);
@@ -731,12 +749,16 @@ function evaluateHook(input, specsDir, opts) {
     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)) {
+        const cfgResolved = (0, approval_grants_1.resolveApproval)(opts.projectRoot, weApproval, { kind: 'config-write', target: norm }, nowTs);
+        if (cfgResolved === undefined) {
             // @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 를 포함한 대역외 승인이 필요합니다` };
+            return { permissionDecision: 'deny', permissionDecisionReason: `[Holmes-Kit] ${kindName} 은(는) 훅·승인 설정입니다 — HOLMES_APPROVAL 을 위조하거나 거버넌스를 끌 수 있으므로 config-write 를 포함한 대역외 승인이 필요합니다`
+                    + (0, approval_queue_1.queueHint)(opts.projectRoot, { kind: 'config-write', target: norm, why: `${kindName} 쓰기` }) };
         }
+        if (cfgResolved.source === 'grant' && cfgResolved.approval.nonce)
+            (0, approval_grants_1.consumeGrantFile)(opts.projectRoot, cfgResolved.approval.nonce);
     }
     // 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

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

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