@holmes-lab/holmes-kit 0.7.1 → 0.9.0

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

@@ -43,6 +43,7 @@ exports.isProtectedTarget = isProtectedTarget;
 exports.specTargetOf = specTargetOf;
 exports.protectedFileKindOf = protectedFileKindOf;
 exports.protectedKindOf = protectedKindOf;
+exports.shellSegments = shellSegments;
 exports.resolvesInside = resolvesInside;
 // @implements A-SPEC-163
 const fs = __importStar(require("node:fs"));
@@ -300,6 +301,148 @@ function protectedKindOf(root, raw) {
     }
     return null;
 }
+const HEREDOC_RE = /<<-?\s*(['"]?)([A-Za-z_]\w*)\1/;
+const SHELL_STDIN_RE = /(?:^|[\s;|&(])(?:sh|bash|zsh|dash|ksh)\b[^<\n]*<</;
+const PROG_STRING_RE = /\b(?:(?:sh|bash|zsh|dash|ksh)\b[^\n;|&]*?-c|eval)\s+(?:'([^']*)'|"([^"]*)")/g;
+function shellSegments(command, startBase, depth = 0) {
+    if (depth > 3)
+        return [{ text: command, base: null }];
+    const out = [];
+    let base = startBase;
+    const pieces = [];
+    {
+        const lines = command.split('\n');
+        let cur = [];
+        const flush = () => { if (cur.length > 0) {
+            pieces.push({ text: cur.join('\n'), kind: 'cmd' });
+            cur = [];
+        } };
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const hd = HEREDOC_RE.exec(line);
+            if (!hd) {
+                cur.push(line);
+                continue;
+            }
+            cur.push(line);
+            flush();
+            const body = [];
+            for (i++; i < lines.length && lines[i].replace(/^\t+/, '') !== hd[2]; i++)
+                body.push(lines[i]);
+            pieces.push({ text: body.join('\n'), kind: SHELL_STDIN_RE.test(line) ? 'prog' : 'data' });
+        }
+        flush();
+    }
+    // Quote-aware split at ; & | and newlines — separators inside quotes are data.
+    const splitTop = (text) => {
+        const parts = [];
+        let acc = '';
+        let quote = null;
+        for (let k = 0; k < text.length; k++) {
+            const ch = text[k];
+            if (quote !== null) {
+                acc += ch;
+                if (ch === quote)
+                    quote = null;
+                continue;
+            }
+            if (ch === "'" || ch === '"') {
+                quote = ch;
+                acc += ch;
+                continue;
+            }
+            if (ch === '\\' && k + 1 < text.length) {
+                acc += ch + text[++k];
+                continue;
+            }
+            if (ch === ';' || ch === '&' || ch === '|' || ch === '\n') {
+                if (acc.trim() !== '')
+                    parts.push(acc);
+                acc = '';
+                continue;
+            }
+            acc += ch;
+        }
+        if (acc.trim() !== '')
+            parts.push(acc);
+        return parts;
+    };
+    const applyCd = (part) => {
+        // `(`/`{` open groups whose leading cd still runs (a brace group shares the CURRENT shell; a
+        // subshell's cd is over-approximated by design — REQ-528 Out). `builtin cd` and `command cd`
+        // ARE the real cd — round-1 adversarial harvest: the unprefixed matcher left the base behind
+        // while the shell moved.
+        const lead = part.replace(/^[\s({]+/, '').replace(/^(?:builtin|command(?:\s+-p)?)\s+/, '');
+        if (/^popd\b/.test(lead)) {
+            base = null;
+            return;
+        }
+        const m = /^(?:cd|chdir|pushd)(?:\s+([\s\S]*))?$/.exec(lead);
+        if (!m)
+            return;
+        const rawArg = (m[1] ?? '').trim();
+        if (rawArg === '') {
+            base = os.homedir();
+            return;
+        }
+        if (/[$`]/.test(rawArg)) {
+            base = null;
+            return;
+        }
+        const words = rawArg.match(/(?:[^\s'"]+|'[^']*'|"[^"]*")+/g) ?? [];
+        if (words.length !== 1) {
+            base = null;
+            return;
+        }
+        const arg = words[0].replace(/^"([^"]*)"$/, '$1').replace(/^'([^']*)'$/, '$1');
+        if (arg === '' || arg === '-') {
+            base = null;
+            return;
+        }
+        if (arg === '~') {
+            base = os.homedir();
+            return;
+        }
+        if (arg.startsWith('~/')) {
+            base = path.join(os.homedir(), arg.slice(2));
+            return;
+        }
+        if (base === null) {
+            const kind = absoluteKindOf(arg);
+            base = kind === null ? null : pathFlavorFor(arg, arg).resolve(arg);
+            return;
+        }
+        base = pathFlavorFor(base, arg).resolve(base, arg);
+    };
+    for (const piece of pieces) {
+        if (piece.kind === 'data') {
+            out.push({ text: piece.text, base });
+            continue;
+        }
+        if (piece.kind === 'prog') {
+            // A shell reading its program from stdin is a CHILD — its cds do not move the parent base.
+            out.push(...shellSegments(piece.text, base ?? startBase, depth + 1)
+                .map((s) => (base === null ? { ...s, base: null } : s)));
+            continue;
+        }
+        for (const part of splitTop(piece.text)) {
+            let rem = part;
+            for (const m of part.matchAll(PROG_STRING_RE)) {
+                const prog = m[1] ?? m[2];
+                if (prog === undefined || prog === '')
+                    continue;
+                // Same child-shell rule as stdin programs; blank the program out of the parent text so its
+                // candidates are judged once, at the child's own bases.
+                out.push(...shellSegments(prog, base ?? startBase, depth + 1)
+                    .map((s) => (base === null ? { ...s, base: null } : s)));
+                rem = rem.replace(`'${prog}'`, "''").replace(`"${prog}"`, '""');
+            }
+            applyCd(rem);
+            out.push({ text: rem, base });
+        }
+    }
+    return out;
+}
 function resolvesInside(raw, roots, impl = path) {
     if (typeof raw !== 'string' || raw.length === 0 || roots.length === 0)
         return false;

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

@@ -535,11 +535,14 @@ function evaluateHook(input, specsDir, opts) {
             // 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)`;
+            // @implements A-SPEC-532.2 — HOLMES_AUTONOMOUS_APPROVAL is the out-of-band autonomy switch; a
+            // session that could set it would self-grant autonomous approval, the same self-disarm the
+            // ROLE/GATE_BYPASS names are blocked for.
+            const SECRET = String.raw `(?:HOLMES_(?:LEDGER_KEY|APPROVAL|ROLE|GATE_BYPASS|SEMANTIC_API_KEY|AUTONOMOUS_APPROVAL)|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 `\b(?:HOLMES_(?:ROLE|GATE_BYPASS)|HOLMES_SEMANTIC_API_KEY|GEMINI_API_KEY|GOOGLE_API_KEY)\b`).test(command);
+            const GRANTS_SELF = new RegExp(String.raw `\b(?:HOLMES_(?:ROLE|GATE_BYPASS|AUTONOMOUS_APPROVAL)|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
@@ -655,22 +658,53 @@ function evaluateHook(input, specsDir, opts) {
                         return m[i];
                 return undefined;
             };
-            const cfgCandidates = [];
-            const cfgCollect = (re) => {
-                for (const m of command.matchAll(re)) {
+            // @implements A-SPEC-528.1 — every shell-write candidate carries the EFFECTIVE base of the
+            // segment it appears in. The rules below used to hand relative candidates to `resolvesInside`
+            // with the project root as the base; a `cd` earlier in the command moves that base, and the
+            // mismatch was measured both ways (2026-09-03 probe C1~C11): five in-project writes spelled
+            // from a subdirectory walked through, three legitimate out-of-tree writes were denied.
+            const segments = (0, write_target_1.shellSegments)(command, opts.projectRoot);
+            const isTilde = (p) => p === '~' || p.startsWith('~/');
+            // Relative candidate in a segment whose base is unknowable (dynamic cd argument): 'unknown',
+            // and the caller fails CLOSED — but only when such a candidate exists, so `cd "$X" && npm
+            // test` stays free.
+            const judgeCand = (c, roots) => {
+                if ((0, write_target_1.absoluteKindOf)(c.raw) !== null || isTilde(c.raw))
+                    return (0, write_target_1.resolvesInside)(c.raw, roots) ? 'in' : 'out';
+                if (c.base === null)
+                    return 'unknown';
+                const pp = (0, write_target_1.pathFlavorFor)(c.base, c.raw);
+                const abs = pp.resolve(c.base, c.raw);
+                const kind = (0, write_target_1.absoluteKindOf)(abs);
+                return (0, write_target_1.resolvesInside)(abs, roots, kind === 'drive' || kind === 'unc' ? path.win32 : path.posix) ? 'in' : 'out';
+            };
+            const collectSeg = (seg, re, list) => {
+                for (const m of seg.text.matchAll(re)) {
                     const g = firstGroup(m);
                     if (g !== undefined)
-                        cfgCandidates.push(g);
+                        list.push({ raw: g, base: seg.base });
                 }
             };
-            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'));
+            const cfgCandidates = [];
+            for (const seg of segments) {
+                collectSeg(seg, new RegExp(`(?:>{1,2}|\\btee\\b(?:\\s+-a)?\\s)\\s*${pathAlt(CONFIG_FILE)}`, 'g'), cfgCandidates);
+                collectSeg(seg, new RegExp(`\\b(?:cp|mv|install|rsync|ln|dd|truncate|chmod|chown)\\b[^;|&]*?${pathAlt(CONFIG_FILE)}`, 'g'), cfgCandidates);
+                collectSeg(seg, new RegExp(`\\bsed\\b[^;|&]*\\s-i\\b[^;|&]*?${pathAlt(CONFIG_FILE)}`, 'g'), cfgCandidates);
+            }
+            // Interpreter one-liner paths keep their whole-text matching (A-SPEC-448/450); a RELATIVE one
+            // is judged as a may-analysis over every determinate base plus the start base — deny-only
+            // over-approximation, sealed in A-SPEC-528.1 §3.
+            const detBases = [...new Set(segments.map((s) => s.base).filter((b) => b !== null)), opts.projectRoot];
+            const hasUnknownBase = segments.some((s) => s.base === null);
+            const expandInterp = (raw) => (0, write_target_1.absoluteKindOf)(raw) !== null || isTilde(raw)
+                ? [{ raw, base: opts.projectRoot }]
+                : [...detBases.map((b) => ({ raw, base: b })), ...(hasUnknownBase ? [{ raw, base: null }] : [])];
             // @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));
+            const cfgVerdicts = [...cfgCandidates, ...interpreterWrites.filter((p) => CFG_RE.test(p)).flatMap(expandInterp)]
+                .map((c) => judgeCand(c, SESSION_ROOTS));
+            const configWrite = cfgVerdicts.includes('in');
             // 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
@@ -694,46 +728,55 @@ function evaluateHook(input, specsDir, opts) {
             // 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'));
+            for (const seg of segments) {
+                collectSeg(seg, new RegExp(`(?:>{1,2}|\\btee\\b(?:\\s+-a)?\\s)\\s*${pathAlt(EXT_TAIL)}`, 'g'), candidates);
+                collectSeg(seg, new RegExp(`\\btouch\\s+[^;|&]*?${pathAlt(EXT_TAIL)}`, 'g'), candidates);
+                collectSeg(seg, new RegExp(`\\bsed\\b[^;|&]*\\s-i\\b[^;|&]*?${pathAlt(EXT_TAIL)}`, 'g'), candidates);
+            }
             // @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);
+            // (A data heredoc body may still carry separators inside one segment, so the per-segment
+            // text is split the way the whole command used to be — the base is the segment's either way.)
+            for (const seg of segments) {
+                for (const sub of seg.text.split(/[;|&]+/)) {
+                    if (!/\b(?:cp|mv|install|rsync|ln|dd)\b/.test(sub))
                         continue;
+                    const of = sub.match(new RegExp(`\\bof=${pathAlt(EXT_TAIL)}`));
+                    if (of) {
+                        const g = firstGroup(of);
+                        if (g !== undefined) {
+                            candidates.push({ raw: g, base: seg.base });
+                            continue;
+                        }
                     }
+                    const all = [...sub.matchAll(new RegExp(pathAlt(EXT_TAIL), 'g'))]
+                        .map(firstGroup).filter((x) => x !== undefined);
+                    if (all.length >= 2)
+                        candidates.push({ raw: all[all.length - 1], base: seg.base }); // last path is the destination
                 }
-                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 codeVerdicts = [...candidates, ...interpreterWrites.filter((p) => CODE_RE.test(p)).flatMap(expandInterp)]
+                .map((c) => judgeCand(c, [opts.projectRoot]));
+            // @implements A-SPEC-528.1 — an unresolvable base under a governed relative write candidate
+            // fails CLOSED: the gate cannot know where the file lands, and guessing is the bypass this
+            // slice closes. Config candidates get the same fail-closed unconditionally (the config rule
+            // has never depended on governance); code candidates stay dormant on a spec-less repo.
+            const UNRESOLVED_BASE_DENY = '[Holmes-Kit] shell write to a relative path cannot be located: an earlier cd has a target the gate cannot resolve statically (dynamic argument) — use an absolute path, the gated Write/Edit tools, or out-of-band approval';
+            if (cfgVerdicts.includes('unknown')) {
+                return { permissionDecision: 'deny', permissionDecisionReason: UNRESOLVED_BASE_DENY };
+            }
+            if (codeVerdicts.includes('in') || codeVerdicts.includes('unknown')) {
                 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' };
+                    return codeVerdicts.includes('in')
+                        ? { 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' }
+                        : { permissionDecision: 'deny', permissionDecisionReason: UNRESOLVED_BASE_DENY };
                 }
             }
         }
@@ -1231,10 +1274,32 @@ function evaluateHook(input, specsDir, opts) {
     // 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;
+    // @implements A-SPEC-529.1
+    // The GOVERNING anchor is a SET, not the first regex match. Comma lists are legal (S-503.1), so
+    // `@implements A-SPEC-100, A-SPEC-200` claims both — and every id after the first used to be
+    // absent from the stale gate and from phaseCheck (measured 2026-09-03: a broken seal on the
+    // second id passed). The shared parser is consumed through `stripStringLiterals`, the same
+    // preprocessing the claim gate got in S-504.1, so a fixture string anchor no longer governs.
+    // Disk-anchor precedence is preserved as a set: a non-empty disk set governs, else the payload.
+    const { anchorSpecIds: govAnchorIds, stripStringLiterals: govStrip } = require('../rtm/anchor-ids');
+    const uniq = (xs) => [...new Set(xs)];
+    // @implements A-SPEC-529.2 — the preprocessing branches on FILE FORMAT. A-SPEC-529.1 stripped
+    // string literals so a code fixture like `const s = "@implements A-SPEC-999"` could not become
+    // the governing anchor; but a JSON file's ONLY way to carry an anchor is a string value
+    // (`"//": "@implements A-SPEC-209"` in package.json), and stripping over-dropped it — measured
+    // 2026-09-03, a release package.json edit was refused with "A-SPEC(unspecified)". Code formats
+    // (line-comment anchors) still strip; JSON/YAML/TOML/config and unknown extensions read raw
+    // (over-inclusion is safe — an anchored-but-unapproved id is still refused downstream).
+    const GOV_CODE_EXT = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|cc|cxx|cpp|hh|hpp|rb|php|swift)$/i;
+    const govPrep = (s) => (GOV_CODE_EXT.test(relPath) ? govStrip(s) : s);
+    const diskGovIds = uniq(govAnchorIds(govPrep(onDiskContent)));
+    const payloadGovIds = uniq(govAnchorIds(govPrep([input.tool_input.content ?? '', input.tool_input.new_string ?? ''].join('\n'))));
+    const governingIds = diskGovIds.length > 0 ? diskGovIds : payloadGovIds;
+    // The single "primary" id kept for message templates and phaseCheck's targetAspecId default: the
+    // first governing id, which is exactly what `m?.[1]` used to be for a single-anchor file.
+    const m = governingIds.length > 0
+        ? Object.assign([`@implements ${governingIds[0]}`, governingIds[0]], { index: 0, input: '', groups: undefined })
+        : null;
     // RE-ANCHORING scope (review C6) moved into judgeScope below (S-508.1): every payload anchor the
     // disk does not carry is an ADMISSION, judged against the incoming spec's gate — the C6 property
     // (a rewrite of the anchor line is judged under the NEW spec) is preserved there, now for the
@@ -1268,11 +1333,15 @@ function evaluateHook(input, specsDir, opts) {
         }
         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-529.1 — the stale gate runs over the WHOLE governing set: any anchored spec
+    // whose seal is broken, and (for WRITE_CODE) any of that spec's qualifying T-SPECs, blocks — and
+    // the message names the one that failed, not the first anchor. The single-anchor path is a set
+    // of one, byte-identical to the previous `m?.[1]` behaviour.
+    const staleTarget = (governingIds.map((id) => sealProblem(id)).find(Boolean) ?? null)
+        ?? (action === 'WRITE_CODE'
+            ? (specs.filter((s) => s.type === 'T-SPEC' && s.status === 'approved' && governingIds.some((id) => s.dependsOn.includes(id)))
+                .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) {
@@ -1306,7 +1375,21 @@ function evaluateHook(input, specsDir, opts) {
             };
         }
     }
-    const res = (0, phase_1.phaseCheck)(action, { specs, targetAspecId: m?.[1] });
+    // @implements A-SPEC-529.1 — phaseCheck runs for EVERY governing id; the first failure is the
+    // verdict, and its id flows into the refusal template (so the author sees the anchor that is
+    // actually unsatisfied, not merely the first one on the file). An empty set keeps the prior
+    // single call with an undefined target. Deterministic: governing-set order is document order.
+    const phaseTargets = governingIds.length > 0 ? governingIds : [undefined];
+    let failedTarget;
+    let res = (0, phase_1.phaseCheck)(action, { specs, targetAspecId: phaseTargets[0] });
+    for (const tid of phaseTargets) {
+        const r = (0, phase_1.phaseCheck)(action, { specs, targetAspecId: tid });
+        if (r.decision === 'deny') {
+            res = r;
+            failedTarget = tid;
+            break;
+        }
+    }
     if (res.decision === 'deny') {
         // @implements A-SPEC-175
         // When the spec tree is gone from a project the ledger remembers approving, the generic
@@ -1315,7 +1398,7 @@ function evaluateHook(input, specsDir, opts) {
         // 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, '..', '..'));
-        const targetSpecId = m?.[1] ?? 'A-SPEC-XXX';
+        const targetSpecId = failedTarget ?? m?.[1] ?? 'A-SPEC-XXX';
         const prescriptiveGuide = ` — Next Action (DO NOT write workaround scripts in /tmp): Step 1: Call 'spec_next({})' to verify slice state. Step 2: Call 'spec_approve({ id: "${targetSpecId}" })' to seal spec. Step 3: Ensure '// @implements ${targetSpecId}' is on line 1 of target file.`;
         return {
             permissionDecision: 'deny',

package/dist/holmes/hooks/session-start.d.ts

@@ -0,0 +1,23 @@
+import { InstallMode } from '../update/update-notice';
+export interface SessionStartInput {
+    version: string;
+    home: string;
+    now: number;
+    env: NodeJS.ProcessEnv;
+    readFile: (p: string) => string;
+    mode: InstallMode;
+}
+export interface SessionStartOutput {
+    hookSpecificOutput: {
+        hookEventName: 'SessionStart';
+        additionalContext: string;
+    };
+    shouldRefresh: boolean;
+}
+/** node_modules → local dependency; anything else is treated as a source checkout (conservative:
+ *  a source install shows no update command, which is safer than a wrong one). A global npx pin is
+ *  detected by the caller from argv/exec path; here the package root alone distinguishes local-dep. */
+export declare function detectInstallMode(packageRoot: string): InstallMode;
+/** Pure: build the banner output and decide whether a refresh should fire. No I/O beyond the
+ *  injected readFile; the caller performs the detached spawn when shouldRefresh is true. */
+export declare function buildSessionStartOutput(input: SessionStartInput): SessionStartOutput;

package/dist/holmes/hooks/session-start.js

@@ -0,0 +1,111 @@
+"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.detectInstallMode = detectInstallMode;
+exports.buildSessionStartOutput = buildSessionStartOutput;
+// @implements A-SPEC-531.2
+// The SessionStart banner hook. It emits the intro (+ optional update notice) as additionalContext,
+// which Claude Code delivers to BOTH the human transcript and the agent context — the "human and
+// agent" delivery REQ-531 asks for. The update refresh is a DETACHED, fire-and-forget child so the
+// session start is never delayed; its result shows up on the NEXT session.
+//
+// FAIL-OPEN: this is a banner, not a gate. Any error yields an empty, harmless output and exit 0 —
+// the session must always start.
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const update_notice_1 = require("../update/update-notice");
+/** node_modules → local dependency; anything else is treated as a source checkout (conservative:
+ *  a source install shows no update command, which is safer than a wrong one). A global npx pin is
+ *  detected by the caller from argv/exec path; here the package root alone distinguishes local-dep. */
+function detectInstallMode(packageRoot) {
+    const folded = packageRoot.replace(/\\/g, '/');
+    return /(?:^|\/)node_modules\//.test(folded) ? 'local-dep' : 'source';
+}
+/** Pure: build the banner output and decide whether a refresh should fire. No I/O beyond the
+ *  injected readFile; the caller performs the detached spawn when shouldRefresh is true. */
+function buildSessionStartOutput(input) {
+    const cached = (0, update_notice_1.readCache)(input.home, input.readFile);
+    const additionalContext = (0, update_notice_1.composeBanner)({ current: input.version, cached, mode: input.mode, npmUrl: update_notice_1.NPM_URL });
+    const shouldRefresh = (0, update_notice_1.shouldQuery)(input.env) && (0, update_notice_1.cacheIsStale)(cached, input.now);
+    return { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext }, shouldRefresh };
+}
+// The package root, derived from this file's location (dist/holmes/hooks/session-start.js → 3 up).
+function pkgRootFromEntry() {
+    return path.resolve(__dirname, '..', '..', '..');
+}
+function pkgVersion() {
+    try {
+        const raw = fs.readFileSync(path.join(pkgRootFromEntry(), 'package.json'), 'utf8');
+        return JSON.parse(raw).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+// CLI entry: read the hook JSON on stdin (unused beyond triggering), emit the banner, and — when
+// allowed — fire the detached refresh. Wrapped so any failure is an empty output + exit 0.
+if (require.main === module) {
+    let buf = '';
+    process.stdin.on('data', (c) => (buf += c));
+    process.stdin.on('end', () => {
+        try {
+            const out = buildSessionStartOutput({
+                version: pkgVersion(),
+                home: os.homedir(),
+                now: Date.now(),
+                env: process.env,
+                readFile: (p) => fs.readFileSync(p, 'utf8'),
+                mode: detectInstallMode(pkgRootFromEntry()),
+            });
+            process.stdout.write(JSON.stringify({ hookSpecificOutput: out.hookSpecificOutput }));
+            if (out.shouldRefresh) {
+                // Detached, unref'd child so the session start does not wait on the network. The refresh
+                // subcommand queries the registry (dist-tags.latest), times out fast, and writes the cache;
+                // any failure there is silent. Reads only public metadata — no spec text, no egress.
+                try {
+                    const child = (0, node_child_process_1.spawn)(process.execPath, [__filename, '--refresh'], { detached: true, stdio: 'ignore' });
+                    child.unref();
+                }
+                catch { /* refresh is best-effort */ }
+            }
+        }
+        catch {
+            // Fail-open: emit nothing and let the session start.
+            process.stdout.write('{}');
+        }
+    });
+}

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

@@ -1,5 +1,6 @@
 import { PendingRequest } from '../governance/approval-queue';
 import { Spec } from '../spec/spec-parser';
+import type { TestOutcome } from '../review/test-runner';
 /**
  * @implements A-SPEC-100.2
  * Stop-hook governance gate (Phase-2 #1: push, not pull).
@@ -81,7 +82,26 @@ export interface StopEvidence {
      * catches it already existed inside `rechainLedger` and ran from the CLI only.
      */
     rolledBackLedgers?: string[];
+    /**
+     * @implements A-SPEC-534.4
+     * ART-8 RED-first evidence. `changedAspecs` are the A-SPECs whose source is dirty this turn;
+     * `outcomesByAspec` are their recorded outcomes at the current baseline HEAD; `redFirstMode` is the
+     * config posture. `strict` blocks via the constitution; `track` records to `tracked` without
+     * blocking; `off`/absent does nothing.
+     */
+    changedAspecs?: string[];
+    outcomesByAspec?: Record<string, Array<{
+        outcome: TestOutcome;
+        ts: string;
+    }>>;
+    redFirstMode?: 'strict' | 'track' | 'off';
 }
+/**
+ * @implements A-SPEC-534.4
+ * ART-8 evidence (I/O half): the A-SPECs whose DIRTY source files carry an @implements anchor. git is
+ * a refinement — no repository means `undefined` (no signal), never a false clean.
+ */
+export declare function changedAnchoredAspecs(root: string): string[] | undefined;
 /**
  * @implements A-SPEC-452
  * ART-1 evidence: which changed source files claim nothing.
@@ -127,6 +147,10 @@ export declare function evaluateStop(specs: Spec[], evidence?: StopEvidence): {
         article: string;
         detail: string;
     }[];
+    tracked?: {
+        article: string;
+        detail: string;
+    }[];
 };
 /**
  * @implements A-SPEC-134