@holmes-lab/holmes-kit 0.2.1 → 0.3.1

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

@@ -38,18 +38,22 @@ exports.resolveRmSignals = resolveRmSignals;
 exports.readApprovalFromEnv = readApprovalFromEnv;
 exports.dumpsEnvInCommandPosition = dumpsEnvInCommandPosition;
 exports.normalizeHookInput = normalizeHookInput;
+exports.preEditEvidenceGate = preEditEvidenceGate;
 exports.decideOnGateError = decideOnGateError;
 exports.isGovernedProject = isGovernedProject;
 exports.gateErrorDecision = gateErrorDecision;
 exports.wiredSpecsDir = wiredSpecsDir;
 exports.evaluateHook = evaluateHook;
 exports.readSpecsSync = readSpecsSync;
+// @implements A-SPEC-278
 // @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 os = __importStar(require("node:os"));
 const node_child_process_1 = require("node:child_process");
+const config_1 = require("../config/config");
 const phase_1 = require("../guardrail/phase");
 const spec_parser_1 = require("../spec/spec-parser");
 const spec_digest_1 = require("../spec/spec-digest");
@@ -72,6 +76,7 @@ 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");
+const impact_gate_1 = require("../guardrail/impact-gate");
 // 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.
@@ -275,6 +280,29 @@ function normalizeHookInput(raw) {
  * and inventing a denial there is its own failure mode. And an operator — never the session — can
  * escape via `HOLMES_GATE_BYPASS`.
  */
+/**
+ * @implements A-SPEC-278
+ * Pre-edit impact evidence, wired but OFF by default.
+ *
+ * `mode: 'off'` returns null before touching anything — a repository that never opted in must behave
+ * exactly as it did before this gate existed, and that includes not paying for a disk read. A
+ * covering `code-write` approval overrides it exactly as it overrides every other gate here, and
+ * actions that are not code or test writes are simply not this gate's business.
+ *
+ * The evidence digest comes from the ENVIRONMENT (`HOLMES_EVIDENCE`), never from the tool payload —
+ * the same rule the approval channel follows, because a session naming its own justification inside
+ * the request it is making is the session asserting its own authority.
+ */
+function preEditEvidenceGate(o) {
+    if (o.mode === 'off')
+        return null;
+    if (o.action !== 'WRITE_CODE' && o.action !== 'WRITE_TEST')
+        return null;
+    if (o.covered)
+        return null;
+    const verdict = (0, impact_gate_1.evaluateEditEvidence)((0, impact_gate_1.loadEditEvidence)(o.projectRoot, o.relPath, o.declaredDigest, o.currentHead));
+    return (0, impact_gate_1.preEditEvidenceDecision)(verdict, o.mode);
+}
 function decideOnGateError(opts) {
     if (opts.bypass) {
         return { permissionDecision: 'allow', permissionDecisionReason: `[Holmes-Kit] 내부 오류를 HOLMES_GATE_BYPASS로 우회했습니다: ${opts.message}` };
@@ -485,12 +513,22 @@ function evaluateHook(input, specsDir, opts) {
             // 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)`;
+            // @implements A-SPEC-477 — the semantic key joins the family: it IS the egress consent
+            // (REQ-476), so reading it is harvesting and ASSIGNING it is self-granted egress, the same
+            // class as HOLMES_ROLE. The GEMINI_API_KEY spelling is included because that is the
+            // ecosystem-compatible name the resolver honors; the narrowed usage forms below keep
+            // `grep GEMINI_API_KEY src/…` free exactly as they do for the HOLMES names.
+            const SECRET = String.raw `(?:HOLMES_(?:LEDGER_KEY|APPROVAL|ROLE|GATE_BYPASS|SEMANTIC_API_KEY)|GEMINI_API_KEY|GOOGLE_API_KEY)`;
             // 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
+            const GRANTS_SELF = new RegExp(String.raw `\b(?:HOLMES_(?:ROLE|GATE_BYPASS)|HOLMES_SEMANTIC_API_KEY|GEMINI_API_KEY|GOOGLE_API_KEY)\b`).test(command);
+            const usesSecret = 
+            // @implements A-SPEC-477 — the credential file is the same secret at rest; reading,
+            // copying or redirecting it is the harvest in file form. Path-usage only, so mentioning
+            // the string in a search or a commit message stays free.
+            /(?:\bcat\b|\bcp\b|\bless\b|\bhead\b|\btail\b|[<>])[^;&|\n]*[.\/\\]holmes[\/\\]credentials/.test(command) ||
+                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
@@ -530,10 +568,92 @@ function evaluateHook(input, specsDir, opts) {
             // @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);
+            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 CONFIG_FILE = '(?:\\.claude[\\\\/]settings[\\w.-]*\\.json|\\.mcp\\.json|\\.env(?!\\.(?:example|sample|template|dist))(?:\\.[\\w-]+)?)';
+            // @implements A-SPEC-448
+            // Paths an INTERPRETER one-liner writes. The residual both shell rules recorded, closed by
+            // asking for the evidence of a write rather than for an interpreter's name near a pattern.
+            // That earlier draft denied `node -e "console.log(cfg.env.name)"` — a property read — and was
+            // rightly rejected; it could not tell reading from writing. Writing leaves two marks in the
+            // text: a write function's NAME, or an `open(path, mode)` whose mode literal is a write mode.
+            // `readFileSync(p,'utf8')` has a quoted second argument and is not one, which is exactly the
+            // distinction the rejected draft could not make. Measured before this was written: 5/5 writes
+            // caught, 0/8 reads misfired.
+            const interpreterWritePaths = () => {
+                // @implements A-SPEC-451 — the entry test used to ask which FLAG carried the program, and
+                // `python3 -` carries it on stdin with no flag at all. A heredoc therefore walked through
+                // with the write evidence and the path both in plain view. The negative lookahead keeps
+                // `-m`, `--version` and `-v` out: only a BARE hyphen means "read the program from stdin",
+                // which covers heredocs and pipes alike.
+                const INTERP = /\b(?:node|python[0-9.]*|ruby|perl|deno|bun|php)\b/;
+                const ONE_LINER = /\b(?:node|python[0-9.]*|ruby|perl|deno|bun|php)\b[^\n]*?(?:-e|--eval|-c|-r)\b/;
+                const STDIN_PROGRAM = /\b(?:node|python[0-9.]*|ruby|perl|deno|bun|php)\b\s+-(?![\w-])/;
+                if (!INTERP.test(command) || !(ONE_LINER.test(command) || STDIN_PROGRAM.test(command)))
+                    return [];
+                // @implements A-SPEC-450 — the evidence and the path need not sit in the same CALL.
+                // A-SPEC-448 required that, so `p='<path>'; open(p,'w')` passed — a variable binding, not
+                // obfuscation, and the idiom this repository writes its own spec bodies with. The
+                // spec/ledger rule never had this hole because it matches the PATH anywhere in the command.
+                // Write evidence is still REQUIRED, which is what keeps reads of the same path allowed.
+                const WRITE_EVIDENCE = new RegExp(String.raw `\b(?:writeFileSync|appendFileSync|createWriteStream|write_text|writelines|File\.write|file_put_contents)\s*\(`
+                    + '|' + String.raw `\bopen\s*\([^)]*,\s*['"](?:[wax]\+?[bt]?|r\+[bt]?)['"]`);
+                if (!WRITE_EVIDENCE.test(command))
+                    return [];
+                // Assembled with String.raw throughout: a plain template literal collapses `\s` to `s`,
+                // which silently turned the character class into "any char but s" and broke every path
+                // containing that letter. Caught by a test, not by reading.
+                // @implements A-SPEC-463 — the path sits BETWEEN quotes here, so spaces inside it are part
+                // of the path, not an argument boundary. `[^'"\s]*` stopped at the first space and missed
+                // `open('C:\Users\이름 성\a.ts','w')`; `[^'"]*` keeps the space and still cannot cross a quote.
+                const NOT_QUOTE = String.raw `[^'"]*`;
+                const QUOTED_PATH = new RegExp(String.raw `['"](` + NOT_QUOTE + String.raw `\.` + CODE_EXT + '|' + NOT_QUOTE + CONFIG_FILE + String.raw `)['"]`, 'g');
+                const out = [];
+                for (const m of command.matchAll(QUOTED_PATH))
+                    if (m[1])
+                        out.push(m[1]);
+                return out;
+            };
+            const interpreterWrites = interpreterWritePaths();
+            // @implements A-SPEC-446
+            // Scope by LOCATION, as A-SPEC-445 did for the code rule — here the approximation ran the
+            // other way: no path anchor at all, so a `.env` anywhere on the machine matched. Measured
+            // 2026-08-30: `/tmp/demo/.env` and another repository's `.env` were denied with a reason
+            // about THIS session's hook config, which those files cannot touch. `~/.claude` stays in
+            // scope on purpose — user-level settings DO change this session's wiring, so narrowing to
+            // "inside the project" alone would open a self-grant path.
+            // @implements A-SPEC-463 — Windows W-2. The extraction below approximated a path with a
+            // character class that excludes spaces (`[^\s...]*`) preceded by an OPTIONAL opening quote
+            // that no closing quote ever paired. A quoted path with a space — the Windows default home is
+            // `C:\Users\<이름 성>` — matched only up to the first space, never reached the extension, and
+            // was captured as nothing, so the write was allowed. `pathAlt` is three alternatives: a
+            // double- or single-quoted path (spaces kept, up to the closing quote) or the unquoted form
+            // (still ends at the first shell word boundary — an un-escaped space is an argument break).
+            // Trailing whitespace before the closing quote is dropped so `"a.ts "` — which Windows strips
+            // back to the real file `a.ts` — is still judged as that file. `tail` is the extension part
+            // (code) or the whole CONFIG_FILE pattern; both are non-capturing, so `pathAlt` owns groups.
+            const pathAlt = (tail) => `(?:"([^"]*${tail})\\s*"|'([^']*${tail})\\s*'|([^\\s;|&'"<>]*${tail})\\b)`;
+            const firstGroup = (m) => {
+                for (let i = 1; i < m.length; i++)
+                    if (m[i] !== undefined)
+                        return m[i];
+                return undefined;
+            };
+            const cfgCandidates = [];
+            const cfgCollect = (re) => {
+                for (const m of command.matchAll(re)) {
+                    const g = firstGroup(m);
+                    if (g !== undefined)
+                        cfgCandidates.push(g);
+                }
+            };
+            cfgCollect(new RegExp(`(?:>{1,2}|\\btee\\b(?:\\s+-a)?\\s)\\s*${pathAlt(CONFIG_FILE)}`, 'g'));
+            cfgCollect(new RegExp(`\\b(?:cp|mv|install|rsync|ln|dd|truncate|chmod|chown)\\b[^;|&]*?${pathAlt(CONFIG_FILE)}`, 'g'));
+            cfgCollect(new RegExp(`\\bsed\\b[^;|&]*\\s-i\\b[^;|&]*?${pathAlt(CONFIG_FILE)}`, 'g'));
+            // @implements A-SPEC-447 — one containment predicate, shared with the code rule below.
+            const SESSION_ROOTS = [opts.projectRoot, path.join(os.homedir(), '.claude')];
+            const CFG_RE = new RegExp(`${CONFIG_FILE}$`);
+            const configWrite = [...cfgCandidates, ...interpreterWrites.filter((p) => CFG_RE.test(p))]
+                .some((raw) => (0, write_target_1.resolvesInside)(raw, SESSION_ROOTS));
             // 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
@@ -546,10 +666,53 @@ function evaluateHook(input, specsDir, opts) {
             //     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);
+            // @implements A-SPEC-445
+            // Scope comes from where the path RESOLVES, not from how it is spelled. The previous rule
+            // approximated "inside the project" with `(?![/~])` — "does not look absolute" — and the
+            // approximation WAS the bypass: measured 2026-08-30, `echo x > src/a.ts` denied while
+            // `echo x > <absolute project path>/src/a.ts` was allowed. Same file, same content, one
+            // spelling apart. The same string test also over-blocked the other way, denying
+            // `> ../elsewhere/a.ts`, which leaves the governed tree entirely.
+            // @implements A-SPEC-463 — same quoted-space fix as the config rule; `EXT_TAIL` is the
+            // extension part and `pathAlt` supplies the prefix and the quoting alternatives.
+            const EXT_TAIL = `\\.${CODE_EXT}`;
+            const candidates = [];
+            const collect = (re) => {
+                for (const m of command.matchAll(re)) {
+                    const g = firstGroup(m);
+                    if (g !== undefined)
+                        candidates.push(g);
+                }
+            };
+            collect(new RegExp(`(?:>{1,2}|\\btee\\b(?:\\s+-a)?\\s)\\s*${pathAlt(EXT_TAIL)}`, 'g'));
+            collect(new RegExp(`\\btouch\\s+[^;|&]*?${pathAlt(EXT_TAIL)}`, 'g'));
+            collect(new RegExp(`\\bsed\\b[^;|&]*\\s-i\\b[^;|&]*?${pathAlt(EXT_TAIL)}`, 'g'));
+            // @implements A-SPEC-449 — the copy/move family. The CONFIG rule has carried it since
+            // A-SPEC-191 §28 ("a gate that names one syntax for an act is a gate over that syntax, not
+            // over the act"); the code rule never got it, and `cp /tmp/e.ts src/a.ts` walked through.
+            // Only the TARGET counts: `cp src/a.ts /tmp/backup.ts` reads the project and writes outside,
+            // which is an ordinary backup and not this gate's business.
+            for (const seg of command.split(/[;|&]+/)) {
+                if (!/\b(?:cp|mv|install|rsync|ln|dd)\b/.test(seg))
+                    continue;
+                const of = seg.match(new RegExp(`\\bof=${pathAlt(EXT_TAIL)}`));
+                if (of) {
+                    const g = firstGroup(of);
+                    if (g !== undefined) {
+                        candidates.push(g);
+                        continue;
+                    }
+                }
+                const all = [...seg.matchAll(new RegExp(pathAlt(EXT_TAIL), 'g'))]
+                    .map(firstGroup).filter((x) => x !== undefined);
+                if (all.length >= 2)
+                    candidates.push(all[all.length - 1]); // last path is the destination
+            }
+            // @implements A-SPEC-447 — same predicate as the config rule; it lived in two copies, which
+            // is how one of two gets fixed.
+            const CODE_RE = new RegExp(`\\.${CODE_EXT}$`);
+            const shellCodeWrite = [...candidates, ...interpreterWrites.filter((p) => CODE_RE.test(p))]
+                .some((raw) => (0, write_target_1.resolvesInside)(raw, [opts.projectRoot]));
             if (shellCodeWrite) {
                 const governed = readSpecsSync(specsDir).some((s) => s.status === 'approved');
                 if (governed) {
@@ -1172,6 +1335,35 @@ function evaluateHook(input, specsDir, opts) {
             };
         }
     }
+    // @implements A-SPEC-278
+    // Pre-edit impact evidence, deliberately the LAST gate on this path.
+    //
+    // Dogfooding 2026-08-28 caught why the position matters: sitting earlier, `warn` mode returned its
+    // allow-with-reason and SHORT-CIRCUITED the gates behind it — an un-specced write that `off`
+    // correctly denied became an allow the moment someone switched the advisory mode on. An advisory
+    // setting that quietly disables No-Spec-No-Code is worse than no setting. Last means this gate can
+    // only ever ADD a refusal, never remove one.
+    //
+    // OFF unless the project opted in, so it is a no-op — and costs no disk or git — for every
+    // repository that has not asked for it. A covering code-write approval overrides it as it does the
+    // other gates.
+    const preEditMode = (0, config_1.loadConfig)(projectRoot).guardrail.preEditEvidence;
+    if (preEditMode !== 'off') {
+        let evidenceHead = '';
+        try {
+            evidenceHead = (0, node_child_process_1.execFileSync)('git', ['-C', projectRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() }).trim();
+        }
+        catch { /* non-git tree: the basis degrades to "" on both sides, never to a crash */ }
+        const evidenceDecision = preEditEvidenceGate({
+            action, projectRoot, relPath, covered: codeWriteCovered, mode: preEditMode,
+            // ENVIRONMENT only (A-SPEC-133's rule): a digest inside the payload would be the session
+            // vouching for itself.
+            declaredDigest: process.env.HOLMES_EVIDENCE?.trim() || null,
+            currentHead: evidenceHead,
+        });
+        if (evidenceDecision)
+            return evidenceDecision;
+    }
     return { permissionDecision: 'allow' };
 }
 // Synchronous spec loader for hook context (fail-open: directory read errors are skipped)

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

@@ -44,7 +44,72 @@ export interface StopEvidence {
      * cleared standing ART-7 debt — an unreadable ledger laundering the very state it records.
      */
     findingsUnreadable?: boolean;
+    /**
+     * @implements A-SPEC-452
+     * Changed source files carrying NO `@implements` anchor at all — ART-1's second enforcement point.
+     *
+     * `undefined` means NO SIGNAL (not a git repository, or git failed) and must not read as clean;
+     * an empty array means measured and clean. The distinction is the same one A-SPEC-191 §4a drew
+     * for the findings ledger, and for the same reason.
+     *
+     * Deliberately WEAKER than the write-time rule, which demands the anchor on line 1: measured on
+     * this repository, the strict form misfires on four legitimate files whose first line is
+     * `'use strict'`, an eslint directive, or an import, while this form reports nothing across 114
+     * changed source files and still catches a file with no anchor at all.
+     */
+    unanchoredChangedSources?: string[];
+    /**
+     * @implements A-SPEC-453
+     * Spec ids approved in the working tree with NO `spec-approved` record in the ledger — ART-5's
+     * second enforcement point.
+     *
+     * The seal cannot carry this weight: `approved_digest` is a plain content hash, so anyone able to
+     * write the file can produce a self-consistent approval. What a forgery cannot produce is the
+     * RECORD of the approving act. `undefined` is no signal, as everywhere else here.
+     *
+     * Scoped to CHANGED specs by measurement: this repository holds 89 approved specs with no ledger
+     * entry (other machines, and the era before the ledger split). Reporting those every turn would
+     * make the check noise; a forgery, by definition, changes a file.
+     */
+    unrecordedApprovals?: string[];
+    /**
+     * @implements A-SPEC-455
+     * Tracked provenance ledgers whose COMMITTED history is no longer a prefix of the working copy.
+     *
+     * The key does not cover this: measured 2026-08-30, wiping a ledger resets single-use and
+     * `verify()` still returns ok, because an empty chain is trivially valid. The judgement that
+     * catches it already existed inside `rechainLedger` and ran from the CLI only.
+     */
+    rolledBackLedgers?: string[];
 }
+/**
+ * @implements A-SPEC-452
+ * ART-1 evidence: which changed source files claim nothing.
+ *
+ * The write gate that enforces ART-1 is text-based and a two-step chain evades it — a generator
+ * written OUTSIDE the project (correctly allowed) and then run (its contents are not in the
+ * command). Both verdicts are right; together they are no gate. This is the turn-boundary backstop.
+ *
+ * git is a REFINEMENT, never a requirement: no repository means no signal, which is `undefined`,
+ * which produces no violation. Failing closed here would block every ungoverned scratch directory.
+ */
+export declare function unanchoredChangedSources(root: string): string[] | undefined;
+/**
+ * @implements A-SPEC-453
+ * ART-5 evidence: approvals that happened without the approving act.
+ *
+ * git is a refinement — no repository means `undefined`, which produces no violation.
+ */
+export declare function unrecordedApprovals(root: string): string[] | undefined;
+/**
+ * @implements A-SPEC-455
+ * ART-2 evidence: ledgers whose committed history was rolled back.
+ *
+ * Uses the SAME predicate the rechain command uses — `mainlineIsPrefix` — so the two can never
+ * drift apart. Named limit: entries appended since the last commit have nothing to compare
+ * against, so this catches rollback of COMMITTED history, not deletion of uncommitted history.
+ */
+export declare function rolledBackLedgers(root: string): string[] | undefined;
 /**
  * @implements A-SPEC-175
  * The turn-boundary answer to "this project is governed but its specs are gone".

package/dist/holmes/hooks/stop.js

@@ -34,6 +34,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
+exports.unanchoredChangedSources = unanchoredChangedSources;
+exports.unrecordedApprovals = unrecordedApprovals;
+exports.rolledBackLedgers = rolledBackLedgers;
 exports.governanceLostPreflight = governanceLostPreflight;
 exports.evaluateStop = evaluateStop;
 exports.stopDebtAction = stopDebtAction;
@@ -57,6 +60,171 @@ const pre_tool_use_1 = require("./pre-tool-use");
 const governance_history_1 = require("../guardrail/governance-history");
 const constitution_debt_1 = require("../governance/constitution-debt");
 const root_1 = require("../project/root");
+/**
+ * @implements A-SPEC-452
+ * ART-1 evidence: which changed source files claim nothing.
+ *
+ * The write gate that enforces ART-1 is text-based and a two-step chain evades it — a generator
+ * written OUTSIDE the project (correctly allowed) and then run (its contents are not in the
+ * command). Both verdicts are right; together they are no gate. This is the turn-boundary backstop.
+ *
+ * git is a REFINEMENT, never a requirement: no repository means no signal, which is `undefined`,
+ * which produces no violation. Failing closed here would block every ungoverned scratch directory.
+ */
+function unanchoredChangedSources(root) {
+    const SOURCE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|rb|php|swift)$/;
+    const VENDORED = /^(?:reference|node_modules|dist|build|vendor|third_party)\//;
+    let raw;
+    try {
+        // `-uall`: without it git folds a wholly-untracked directory into one `?? src/` line and the
+        // files inside it are never seen — which is precisely where a bypassed write lands.
+        raw = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-uall'], {
+            cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(),
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        let rel = line.slice(3).trim().replace(/^"|"$/g, '');
+        if (rel.includes(' -> '))
+            rel = rel.split(' -> ')[1]; // renames name the destination
+        if (!SOURCE.test(rel) || VENDORED.test(rel))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(root, rel), 'utf8');
+        }
+        catch {
+            continue;
+        } // deleted, unreadable
+        if (!text.includes('@implements'))
+            out.push(rel);
+    }
+    return out;
+}
+/**
+ * @implements A-SPEC-453
+ * ART-5 evidence: approvals that happened without the approving act.
+ *
+ * git is a refinement — no repository means `undefined`, which produces no violation.
+ */
+function unrecordedApprovals(root) {
+    let raw;
+    try {
+        raw = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-uall'], {
+            cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(),
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const approvedIds = [];
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        let rel = line.slice(3).trim().replace(/^"|"$/g, '');
+        if (rel.includes(' -> '))
+            rel = rel.split(' -> ')[1];
+        if (!rel.endsWith('.md') || !rel.replace(/\\/g, '/').includes('/specs/'))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(root, rel), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const head = text.slice(0, 4000);
+        const id = /^id:\s*(\S+)\s*$/m.exec(head)?.[1];
+        const status = /^status:\s*(\S+)\s*$/m.exec(head)?.[1];
+        if (id !== undefined && status === 'approved')
+            approvedIds.push(id);
+    }
+    if (approvedIds.length === 0)
+        return [];
+    // Which ids the ledger records an approving act for. Unreadable ledger -> no signal, rather than
+    // a wave of false accusations.
+    const recorded = new Set();
+    const dir = path.join(root, '.ax', 'ledger');
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+    }
+    catch {
+        return undefined;
+    }
+    for (const f of files) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, f), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            if (!line.includes('"spec-approved"'))
+                continue;
+            for (const m of line.matchAll(/\b(?:REQ|H-SPEC|A-SPEC|C-SPEC|T-SPEC)-[0-9.]+/g))
+                recorded.add(m[0]);
+        }
+    }
+    return approvedIds.filter((id) => !recorded.has(id));
+}
+/**
+ * @implements A-SPEC-455
+ * ART-2 evidence: ledgers whose committed history was rolled back.
+ *
+ * Uses the SAME predicate the rechain command uses — `mainlineIsPrefix` — so the two can never
+ * drift apart. Named limit: entries appended since the last commit have nothing to compare
+ * against, so this catches rollback of COMMITTED history, not deletion of uncommitted history.
+ */
+function rolledBackLedgers(root) {
+    const git = (args) => (0, node_child_process_1.execFileSync)('git', args, {
+        cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(),
+    });
+    let tracked;
+    try {
+        tracked = git(['ls-files', '.ax/ledger']).split('\n')
+            .map((l) => l.trim()).filter((l) => /provenance[\w.-]*\.jsonl$/.test(l));
+    }
+    catch {
+        return undefined;
+    }
+    const parse = (text) => text.split('\n')
+        .map((l) => l.trim()).filter((l) => l !== '')
+        .map((l) => { try {
+        return JSON.parse(l);
+    }
+    catch {
+        return null;
+    } })
+        .filter((e) => e !== null);
+    const { mainlineIsPrefix } = require('../governance/ledger-rechain');
+    const out = [];
+    for (const rel of tracked) {
+        let committed;
+        try {
+            committed = git(['show', `HEAD:${rel}`]);
+        }
+        catch {
+            continue;
+        } // no HEAD, or newly added
+        let working;
+        try {
+            working = fs.readFileSync(path.join(root, rel), 'utf8');
+        }
+        catch {
+            working = '';
+        }
+        if (!mainlineIsPrefix(parse(committed), parse(working)))
+            out.push(rel);
+    }
+    return out;
+}
 /**
  * @implements A-SPEC-175
  * The turn-boundary answer to "this project is governed but its specs are gone".
@@ -97,6 +265,27 @@ function evaluateStop(specs, evidence) {
         problems.push('[ART-7] findings 원장을 읽을 수 없습니다 — 열린 치명 발견의 존재를 확인할 수 없는 턴은 깨끗한 턴이 아닙니다 (원장 파일의 권한·형식을 복구하십시오)');
         structured.push({ article: 'ART-7', detail: 'findings 원장을 읽을 수 없습니다' });
     }
+    // @implements A-SPEC-452 — ART-1's second enforcement point. `undefined` is no signal and says
+    // nothing; an empty array is measured and clean. A file that claims nothing is a file the write
+    // gate never judged, which is exactly what the two-step generator bypass produces.
+    for (const file of evidence?.unanchoredChangedSources ?? []) {
+        const detail = `${file}: 변경된 소스에 @implements 앵커가 없습니다 — 이 파일이 무엇을 구현하는지 말하지 않습니다 (승인된 A-SPEC 을 만들고 앵커를 다십시오)`;
+        problems.push(`[ART-1] ${detail}`);
+        structured.push({ article: 'ART-1', detail });
+    }
+    // @implements A-SPEC-453 — ART-5's second enforcement point. The seal is forgeable; the record
+    // of the approving act is not.
+    for (const id of evidence?.unrecordedApprovals ?? []) {
+        const detail = `${id}: 승인 상태인데 원장에 승인 행위 기록이 없습니다 — 봉인은 내용 해시라 스스로를 증명하지 못합니다 (spec_approve 로 승인하십시오)`;
+        problems.push(`[ART-5] ${detail}`);
+        structured.push({ article: 'ART-5', detail });
+    }
+    // @implements A-SPEC-455
+    for (const file of evidence?.rolledBackLedgers ?? []) {
+        const detail = `${file}: 커밋된 원장 이력이 되돌려졌습니다 — 작업본이 커밋본을 접두로 포함하지 않습니다 (원장은 덧붙이기만 합니다; holmes-kit ledger rechain 으로 확인하십시오)`;
+        problems.push(`[ART-2] ${detail}`);
+        structured.push({ article: 'ART-2', detail });
+    }
     if (problems.length === 0)
         return { block: false };
     const shown = problems.slice(0, 20);
@@ -104,7 +293,10 @@ function evaluateStop(specs, evidence) {
     // @implements A-SPEC-134 — the distinct articles feed the constitution-debt state on a cap-yield.
     const articles = [...new Set(violations.map((x) => x.article)
             .concat(evidence?.provenance && !evidence.provenance.ok ? ['ART-2'] : [])
-            .concat(evidence?.findingsUnreadable ? ['ART-7'] : []))];
+            .concat(evidence?.findingsUnreadable ? ['ART-7'] : [])
+            .concat((evidence?.unanchoredChangedSources ?? []).length > 0 ? ['ART-1'] : [])
+            .concat((evidence?.unrecordedApprovals ?? []).length > 0 ? ['ART-5'] : [])
+            .concat((evidence?.rolledBackLedgers ?? []).length > 0 ? ['ART-2'] : []))];
     return {
         block: true,
         articles,
@@ -492,7 +684,13 @@ if (require.main === module) {
             catch {
                 findingsUnreadable = true;
             } // @implements A-SPEC-191 (§4a) — list() absorbs ENOENT; a throw means the ledger EXISTS and cannot be read, which must block, not launder
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable });
+            // @implements A-SPEC-452 — collected here (I/O half) so evaluateStop stays pure.
+            const unanchored = unanchoredChangedSources(stopProjectRoot());
+            // @implements A-SPEC-453
+            const unrecorded = unrecordedApprovals(stopProjectRoot());
+            // @implements A-SPEC-455
+            const rolledBack = rolledBackLedgers(stopProjectRoot());
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack });
             // @implements A-SPEC-247 — before deciding to re-block, ask whether every unresolved debt is
             // already queued for the owner. If so, tell the user ONCE and let the turn finish; a single
             // non-waiting violation and we block exactly as before.

package/dist/holmes/mcp/elicit-approval.d.ts

@@ -26,12 +26,42 @@ export interface ElicitApprovalRequest {
     /** Human-facing one-liner: what is being approved (id, title, sealed-or-not). */
     summary: string;
 }
-/** The human's decision. `null` from an elicitor means "the channel gave no answer — fall back". */
+/** The human's decision. `null` from interpretElicitResult means "no answer in this shape". */
 export interface ElicitDecision {
     granted: boolean;
     reason?: string;
 }
-export type Elicitor = (req: ElicitApprovalRequest) => Promise<ElicitDecision | null>;
+/**
+ * The three fates of an elicitation, told apart. The old `Elicitor` returned decision-or-null, and
+ * the wiring's `catch { return null }` erased the SDK's RequestTimeout — so an expired dialog (the
+ * human saw dead arrows) and an absent capability (the human saw nothing at all) wore the same
+ * refusal. Only `expired` earns a name in the message; `silent` stays byte-identical to the
+ * pre-elicitation refusal (A-SPEC-263.1's lossless-degradation promise, kept).
+ */
+export type ElicitOutcome = {
+    kind: 'answered';
+    decision: ElicitDecision;
+} | {
+    kind: 'expired';
+    waitedMs: number;
+} | {
+    kind: 'silent';
+};
+export type Elicitor = (req: ElicitApprovalRequest) => Promise<ElicitOutcome>;
+/** The one timeout truth: the SDK option, the dialog forewarning and `waitedMs` all derive from it. */
+export declare const ELICIT_TIMEOUT_MS = 120000;
+/**
+ * Classify an elicitInput rejection. Only the exact SDK timeout code — on a real Error — is
+ * `expired`; a message that merely SAYS "timed out", a near-miss code, or a code on a non-Error
+ * is `silent`, because the expiry face carries friendlier guidance and must not be spoofable.
+ */
+export declare function classifyElicitError(e: unknown): ElicitOutcome;
+/**
+ * The expiry notice that LEADS an expired refusal: what happened (the session dialog expired),
+ * where the request went (the approval queue), and where the decision still lives (the CLI).
+ * Template-owned text with no interpolated attacker data.
+ */
+export declare function expiredNotice(waitedMs: number): string;
 /**
  * The question form. Decisions only (REQ-263 Out): the single free-text field is `reason`, and it
  * is subordinate to the decision — this channel never collects arbitrary input.