@holmes-lab/holmes-kit 0.7.0 → 0.8.1

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/mcp/handlers.js

@@ -130,6 +130,7 @@ const package_1 = require("../review/package");
 const risk_classifier_1 = require("../guardrail/risk-classifier");
 const risk_gate_1 = require("../guardrail/risk-gate");
 const elicit_approval_1 = require("./elicit-approval");
+const autonomy_1 = require("../governance/autonomy");
 const anchor_comment_1 = require("../rtm/anchor-comment");
 const consistency_lints_1 = require("../cpg/consistency-lints");
 const approval_queue_1 = require("../governance/approval-queue");
@@ -669,6 +670,15 @@ function makeRawHandlers(store, opts) {
         token: crypto.randomUUID(),
         rationale: reason ?? 'elicitation grant',
     });
+    // @implements A-SPEC-532.2 — the autonomous channel: the SAME synthesized-Approval shape that
+    // rides the existing seal path, but its actor names `autonomous:<client>` so an audit can tell a
+    // self-approved seal from a human-approved (elicitation) or operator (env/grant) one. Single-use
+    // by construction — it exists only inside this call, persisted nowhere.
+    const autonomousApproval = () => ({
+        actor: `autonomous:${opts?.clientName?.() ?? 'unknown'}`,
+        token: crypto.randomUUID(),
+        rationale: `autonomous grant (${'HOLMES_AUTONOMOUS_APPROVAL'} enabled, spec grade auto)`,
+    });
     /**
      * Where the audit record for a governance act belongs — resolved BEFORE the act writes anything.
      *
@@ -1134,26 +1144,38 @@ function makeRawHandlers(store, opts) {
             if (approveResolved === undefined) {
                 const target = await store.read(a.id).catch(() => null);
                 if (target) {
-                    const resealing = typeof target.spec.frontmatter.approved_digest === 'string';
-                    // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char
-                    // title pushed '(재봉인)' past the dialog's 200-char summary cap, dressing a re-seal (the
-                    // more consequential act) as a first approval. The cap cuts the title, never the marker.
-                    const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`);
-                    if (out.kind === 'answered' && out.decision.granted) {
-                        approveResolved = { approval: elicitApproval(out.decision.reason), source: 'elicitation' };
+                    // @implements A-SPEC-532.2 — the autonomous gate sits BEFORE the human ask: when the
+                    // out-of-band autonomy switch is on AND the spec is low/mid-risk (never gate-behavior, an
+                    // architecture/taint file, or an upstream REQ/H/C — those stay human), the agent seals it
+                    // itself. The switch is env-only and an agent cannot set it (pre-tool-use blocks that,
+                    // A-SPEC-532.2). Off, or a hitl-classed spec, falls straight through to the elicitor
+                    // unchanged — the autonomous-OFF path is byte-identical to before.
+                    if ((0, autonomy_1.autonomousApprovalEnabled)(process.env)
+                        && (0, autonomy_1.specApprovalAutonomy)(target.spec, resolver([target.spec])) === 'auto') {
+                        approveResolved = { approval: autonomousApproval(), source: 'autonomous' };
                     }
-                    else if (out.kind === 'answered') {
-                        // The human ANSWERED (deny/question/decline): the answer is the message, and no queue
-                        // entry is filed — a decided request is not a pending one (REQ-246 visibility).
-                        return { ok: false, reason: `spec_approve: 세션에서 거부됨 — ${out.decision.reason ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
-                    }
-                    else if (out.kind === 'expired') {
-                        // @implements A-SPEC-497.1 — only the expiry earns a name: the notice LEADS the same
-                        // fail-closed refusal + queue path, so the semantics stay refusal+queue and only the
-                        // message learned to say what happened.
-                        elicitExpiredMs = out.waitedMs;
+                    else {
+                        const resealing = typeof target.spec.frontmatter.approved_digest === 'string';
+                        // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char
+                        // title pushed '(재봉인)' past the dialog's 200-char summary cap, dressing a re-seal (the
+                        // more consequential act) as a first approval. The cap cuts the title, never the marker.
+                        const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`);
+                        if (out.kind === 'answered' && out.decision.granted) {
+                            approveResolved = { approval: elicitApproval(out.decision.reason), source: 'elicitation' };
+                        }
+                        else if (out.kind === 'answered') {
+                            // The human ANSWERED (deny/question/decline): the answer is the message, and no queue
+                            // entry is filed — a decided request is not a pending one (REQ-246 visibility).
+                            return { ok: false, reason: `spec_approve: 세션에서 거부됨 — ${out.decision.reason ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
+                        }
+                        else if (out.kind === 'expired') {
+                            // @implements A-SPEC-497.1 — only the expiry earns a name: the notice LEADS the same
+                            // fail-closed refusal + queue path, so the semantics stay refusal+queue and only the
+                            // message learned to say what happened.
+                            elicitExpiredMs = out.waitedMs;
+                        }
+                        // silent: the channel gave no answer — fall through to the byte-identical refusal.
                     }
-                    // silent: the channel gave no answer — fall through to the byte-identical refusal.
                 }
             }
             if (approveResolved === undefined) {

package/dist/holmes/mcp/server-instructions.d.ts

@@ -0,0 +1,8 @@
+import { InstallMode } from '../update/update-notice';
+export interface ServerInstructionsInput {
+    version: string;
+    home: string;
+    mode: InstallMode;
+    readFile: (p: string) => string;
+}
+export declare function buildServerInstructions(input: ServerInstructionsInput): string;

package/dist/holmes/mcp/server-instructions.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildServerInstructions = buildServerInstructions;
+// @implements A-SPEC-531.2
+// The MCP server's `instructions` banner. A harness with no SessionStart hook (codex, antigravity)
+// still gets the intro (+ optional update notice) delivered to the agent through the server's
+// initialize response. PURE and fail-soft — a cache read failure yields the intro only, and never
+// throws, so server construction is never blocked by the banner.
+const update_notice_1 = require("../update/update-notice");
+function buildServerInstructions(input) {
+    const cached = (0, update_notice_1.readCache)(input.home, input.readFile); // readCache already swallows a throw → null
+    return (0, update_notice_1.composeBanner)({ current: input.version, cached, mode: input.mode, npmUrl: update_notice_1.NPM_URL });
+}

package/dist/holmes/mcp/server.js

@@ -54,7 +54,27 @@ const PKG_VERSION = (() => {
         return '0.0.0';
     }
 })();
-const server = new index_js_1.Server({ name: 'holmes-kit', version: PKG_VERSION }, { capabilities: { tools: {} } });
+// @implements A-SPEC-531.2 — the banner rides `instructions` so a harness without a SessionStart
+// hook still delivers the intro (+ update notice) to the agent. Fail-soft: any failure omits it and
+// the server starts normally.
+const SERVER_INSTRUCTIONS = (() => {
+    try {
+        const { buildServerInstructions } = require('./server-instructions');
+        const { detectInstallMode } = require('../hooks/session-start');
+        const os = require('node:os');
+        const fs = require('node:fs');
+        return buildServerInstructions({
+            version: PKG_VERSION,
+            home: os.homedir(),
+            mode: detectInstallMode(require('node:path').resolve(__dirname, '..', '..', '..')),
+            readFile: (p) => fs.readFileSync(p, 'utf8'),
+        });
+    }
+    catch {
+        return undefined;
+    }
+})();
+const server = new index_js_1.Server({ name: 'holmes-kit', version: PKG_VERSION }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
 const fullProfile = process.env.HOLMES_MCP_PROFILE === 'full';
 // Register each handler as a tool with its real typed inputSchema so MCP
 // clients can marshal complex (array/object) arguments; fall back to a

package/dist/holmes/rtm/rtm-builder.js

@@ -413,6 +413,10 @@ function addImportEdges(scanned, graph, opts) {
         else if (head === 'super') {
             baseDir = path.posix.dirname(path.posix.dirname(fromFile));
             while (segs[0] === 'super') {
+                // @implements A-SPEC-527.1 — super:: above the crate root is an rustc error; resolving
+                // it pinned '.' and produced edges to repo-root files (adversarial sweep). Refuse.
+                if (baseDir === '.' || baseDir === '/')
+                    return null;
                 segs.shift();
                 baseDir = path.posix.dirname(baseDir);
             }
@@ -447,6 +451,11 @@ function addImportEdges(scanned, graph, opts) {
         if (/\.cs$/.test(fromFile))
             return uniqueSuffix(`${spec.split('.').join('/')}.cs`);
         if (/\.(cpp|cc|cxx|hpp|h)$/.test(fromFile)) {
+            // @implements A-SPEC-527.1 — an ABSOLUTE include is not a repository coordinate: joining
+            // it into the repo frame let `#include "/etc/passwd"` match a coincidentally-shaped
+            // scanned file (adversarial sweep). Absolute means absolute; it resolves to nothing here.
+            if (spec.startsWith('/'))
+                return null;
             // extension preserved: the dotted split below would butcher `util/env.h`
             const relative = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), spec));
             if (known.has(relative))

package/dist/holmes/rtm/taint-vocabulary.js

@@ -51,7 +51,9 @@ const JAVA_VOCABULARY = {
     sanitizers: ['escapeHtml', 'quoteReplacement', 'encode'],
 };
 const CSHARP_VOCABULARY = {
-    sources: ['GetEnvironmentVariable', 'ReadLine', 'QueryString', 'Form'],
+    // @implements A-SPEC-527.1 — bare 'Form' matched every *Form identifier (WinForms world);
+    // the request-shaped spellings keep the actual web input reads.
+    sources: ['GetEnvironmentVariable', 'ReadLine', 'QueryString', 'Request.Form', '.Form['],
     sinks: ['Start', 'ExecuteReader', 'ExecuteNonQuery', 'ExecuteScalar', 'Deserialize'],
     sanitizers: ['HtmlEncode', 'UrlEncode', 'EscapeDataString'],
 };
@@ -61,7 +63,9 @@ const RUST_VOCABULARY = {
     sanitizers: ['escape', 'quote'],
 };
 const CPP_VOCABULARY = {
-    sources: ['getenv', 'argv', 'cin', 'fgets'],
+    // @implements A-SPEC-527.1 — 'cin' alone bled into English identifiers (racing, medicine…),
+    // measured by the adversarial sweep; the qualified spellings keep the real reads.
+    sources: ['getenv', 'argv', 'std::cin', 'cin >>', 'fgets'],
     sinks: ['system', 'popen', 'exec', 'execl', 'execlp', 'execle', 'execv', 'execvp', 'ShellExecute'],
     sanitizers: ['escape', 'quote'],
 };

package/dist/holmes/update/update-notice.d.ts

@@ -0,0 +1,28 @@
+export declare const NPM_URL = "https://www.npmjs.com/package/@holmes-lab/holmes-kit";
+/** How this install was wired — decides how (or whether) to phrase the update command. */
+export type InstallMode = 'global-npx' | 'local-dep' | 'source';
+export interface UpdateCache {
+    latest: string;
+    checkedAt: number;
+}
+export interface BannerInput {
+    current: string;
+    cached: UpdateCache | null;
+    mode: InstallMode;
+    npmUrl: string;
+}
+/** -1 if a<b, 0 if equal, 1 if a>b — NUMERIC per field, so 0.9.0 < 0.10.0 (a string compare fails). */
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+/** The cache file, read only — no network, no write. Anything unreadable/malformed/mis-shaped → null. */
+export declare function readCache(home: string, readFile: (p: string) => string): UpdateCache | null;
+/** The one-line update guidance, branched by install mode. `source` returns null (git updates it). */
+export declare function installModeGuide(mode: InstallMode, latest: string, current: string): string | null;
+/**
+ * The banner: always an English intro line (version + governance rule + npm page). If the cache
+ * knows a newer version AND the install mode has an update path, a second guidance line follows.
+ */
+export declare function composeBanner(input: BannerInput): string;
+/** Whether a network refresh is allowed at all. Opt-out via HOLMES_NO_UPDATE_CHECK or CI. */
+export declare function shouldQuery(env: NodeJS.ProcessEnv): boolean;
+/** Whether the cache is old enough to refresh. A missing cache is stale. */
+export declare function cacheIsStale(cached: UpdateCache | null, now: number, ttlMs?: number): boolean;