@holmes-lab/holmes-kit 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -5,6 +5,72 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.8.1] - 2026-09-03
+
+Codex hard-enforcement completed and verified on real codex-cli 0.152.1 (GOAL-codex-enforcement),
+plus the README refreshed to the 0.8.x feature set.
+
+### Fixed
+
+- **Codex marketplace manifest location** (REQ-533): `init --agent codex` now writes the manifest
+  where codex-cli 0.152.x actually reads it (`.claude-plugin/marketplace.json`), keeping the old
+  `.agents/plugins/` location for 0.151.x. Measured: the shipped wiring installs with no manual copy
+  — `codex plugin marketplace add` → `codex plugin add` → `installed, enabled`. `doctor` now flags a
+  wiring that has only the old location.
+
+### Verified
+
+- **Codex hard gate, model-independently**: the codex PreToolUse payload was captured (Claude-shaped:
+  `tool_name` + `tool_input`) and replayed through the gate — an unauthorized shell code-write is
+  denied, a harmless read passes. A session cannot self-grant `HOLMES_AUTONOMOUS_APPROVAL` (blocked
+  like `HOLMES_ROLE`).
+
+## [0.8.0] - 2026-09-03
+
+A hardening campaign (GOAL-hardening-2026-09) closing measured gate gaps, adding server-side CI
+re-validation, a session banner with update notice, and — new this release — **autonomous spec
+approval** so an agent in an explicitly-enabled autonomous mode can seal low/mid-risk specs
+without the human elicitation TUI, while gate-behavior, architecture, taint, and upstream specs
+still ask a human. Every slice was TDD'd (RED verified first) with two consecutive clean
+adversarial rounds where a gate was changed.
+
+### Added
+
+- **Autonomous spec approval** (REQ-532): with the out-of-band `HOLMES_AUTONOMOUS_APPROVAL`
+  switch set (an agent cannot set it — the pre-tool-use gate blocks that, like `HOLMES_ROLE`),
+  `spec_approve` seals a low/mid-risk spec itself, ledgered under an `autonomous:<client>` actor
+  so audits tell the channel apart from human (`elicitation:`) and operator (`env`) approvals.
+  The bound is conservative: `gate-behavior` breaking changes, architecture/gate/governance/taint
+  files, and every REQ/H-SPEC/C-SPEC stay on the human channel. Autonomy OFF is byte-identical to
+  before.
+- **Session banner + update notice** (REQ-531): every session start emits an English intro line
+  (version + governance rule + npm page URL) to both the human transcript and the agent context
+  via a SessionStart hook, and the MCP server carries the same banner in its `instructions` for
+  harnesses without that hook. When the `~/.holmes` cache knows a newer published version, an
+  install-mode-aware update command is appended. The registry refresh is detached and fail-silent;
+  `HOLMES_NO_UPDATE_CHECK` or `CI` opts out.
+- **Server-side CI re-validation** (REQ-530): a Gitea Actions workflow re-runs the pre-push
+  evidence check (npm ci → build → full suite → tarball install probe) so a `--no-verify` push or
+  a hook-less clone is still caught. The lockfile is now tracked (`npm ci` reproducible). NOTE:
+  wiring only until a runner is registered — an operator step.
+
+### Fixed
+
+- **cd-relative shell writes are judged at the segment's effective directory** (REQ-528): a write
+  spelled from a subdirectory (`cd sub && cat > ../src/x.ts`) is judged at the real location, not
+  the project root — five bypasses (subshell, `sh -c`, heredoc-program, …) are sealed and three
+  legitimate out-of-tree writes are un-blocked. A quote-aware split closes a data-injection route
+  a transparent split would open.
+- **A file's whole governing anchor SET is judged** (REQ-529): comma-list anchors past the first
+  id used to be absent from the stale gate and phaseCheck; every governing id now participates and
+  the refusal names the one that failed. String-value anchors in JSON/config files
+  (`"//": "@implements …"` in package.json) are honored; code-file fixture strings stay excluded.
+
+### Guardrail
+
+- **`HOLMES_AUTONOMOUS_APPROVAL` joins the self-disarm family**: a session cannot read or set the
+  autonomy switch (same protection as `HOLMES_ROLE`/`HOLMES_GATE_BYPASS`).
+
 ## [0.7.1] - 2026-09-02
 
 An adversarial self-review of the seven-language work — 42 probes the test suite never pinned

package/README.md

@@ -14,16 +14,19 @@
 
 ---
 
-### 🛡️ Currently Supported Features (v0.3.x Production Features)
+### 🛡️ Currently Supported Features (v0.8.x Production Features)
 
-- 📋 **Requirements & Specification Governance**: Strict **"No Spec, No Code"** enforcement with 4-tier spec chain traceability (`REQ ➔ H-SPEC ➔ A-SPEC ➔ T-SPEC`) and `// @implements A-SPEC-XXX` line 1 code anchors.
+- 📋 **Requirements & Specification Governance**: Strict **"No Spec, No Code"** enforcement with 4-tier spec chain traceability (`REQ ➔ H-SPEC ➔ A-SPEC ➔ T-SPEC`) and `// @implements A-SPEC-XXX` code anchors (comma-lists and every anchor in a file participate in the gate).
+- 🤖 **Autonomous Approval** *(new in 0.8.0)*: with the out-of-band `HOLMES_AUTONOMOUS_APPROVAL` switch on, an agent seals **low/mid-risk** specs itself (ledgered under an `autonomous:<client>` actor) — while `gate-behavior` changes, architecture/gate/taint files, and every upstream `REQ`/`H-SPEC`/`C-SPEC` still ask a human through the in-session TUI. The switch is env-only; a session cannot set it (blocked like `HOLMES_ROLE`). Off = byte-identical to before.
+- 🪧 **Session Banner + Update Notice** *(new in 0.8.0)*: every session start emits an English intro (version + governance rule + npm URL) to both the human transcript and the agent context (SessionStart hook + MCP `instructions`); when a newer published version is cached, an install-mode-aware update command is appended. Registry check is detached, fail-silent, and opts out via `HOLMES_NO_UPDATE_CHECK`/`CI`.
+- 🧱 **Deterministic Gate, Hardened** *(new in 0.8.0)*: shell writes are judged at the segment's **effective working directory** (`cd sub && cat > ../src/x.ts` is sealed, legitimate out-of-tree scratch writes are freed); the governing anchor is the **whole set**, not the first match. Every gate change ships with two consecutive clean adversarial rounds.
 - 🧠 **3-Tier Semantic Layer** *(new in 0.3.0)*: knowledge-graph semantic search with an explicit consent ladder — `none` (default, **zero egress**), `local` (bge-m3, no egress, optional module), `cloud` (gemini-embedding-001, opt-in via `GEMINI_API_KEY`). Measured on 305 traceability cases: recall 0.486 (lexical) → 0.667 (local) → **0.887 (cloud)**; on lexical-zero requests: 0% → 52% → **92%**. Surfaced only additively — rerank, evidence (`semCos`), and `semanticAlternates` — never as a hard filter.
 - 🎯 **Graded Impact Surface** *(new in 0.3.0)*: `rankedImpact` (personalized-PageRank over the spec/code graph) beat its pre-registered naive baseline on **both recall and precision across 3 corpora (×1.6–×17)** — the necessary condition for any better-than-a-person phrasing, measured before claimed.
-- 🐞 **Causal Defect Localization & CPG**: AST Code Property Graph (CPG) & Dataflow Taint reachability analysis across 7 languages (TS/JS, Python, Go, Rust, Java, C/C++, C#).
+- 🐞 **Causal Defect Localization & CPG** *(equalized in 0.5–0.7)*: AST Code Property Graph (CFG/DDG/CDG) & Dataflow Taint reachability across 7 languages (TS/JS, Python, Go, Rust, Java, C/C++, C#) — **42 language×layer cells graded on measured evidence** (11 corpora, 39,344 functions, zero invariant violations; C++ conditional on 67.9% parse coverage, disclosed in the matrix).
 - 📏 **Measured, Not Claimed** *(new in 0.3.x)*: performance is judged against a pre-registered modeled-human band (R 0.67–0.78 / P ≈0.9±). Current official grade: **band entry on recall; division-of-labor precision 0.727 = 81% of the modeled human — reproduced by an independent context-free judge on a fresh blind window.** No superhuman claims until both metrics exceed the band.
 - 🧪 **Self-Healing & Diagnostic Doctor**: Automated integrity checks and self-healing auto-fix remediation (`holmes-kit doctor --fix` & `spec_remediate`) — wiring-handshake checks run on Windows natively as of 0.3.2.
 - 🔔 **Approval UX** *(new in 0.3.1)*: in-session approval dialogs forewarn their 120s deadline and, on expiry, the refusal says exactly where the decision went (`npx holmes-kit approve` out-of-band queue) — no more silently dead dialogs.
-- 🚦 **CI/CD Governance Gate Runner**: Non-interactive headless CI/CD build gate (`holmes-kit ci`) for GitHub Actions and GitLab CI pipelines.
+- 🚦 **Push & Server-Side Re-Validation** *(hardened in 0.8.0)*: a local `pre-push` evidence gate (test-run ledger head == push HEAD, green, executed > 0) plus a **server-side CI workflow** that re-runs `npm ci → build → full suite → tarball install probe`, so a `--no-verify` push or a hook-less clone is still caught.
 - 📊 **Automated RTM & Taint Heatmap**: Interactive standalone HTML/SVG report generation (`generateRtmHeatmap`) for spec coverage and security dataflow reachability.
 - 🤖 **CLI-First AI Harness Matrix**: Native process hook gating for Claude Code, Antigravity CLI (AGY), Codex CLI, and Google Antigravity SDK.
 
@@ -46,7 +49,7 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
 | :--- | :--- | :--- |
 | 🤖 **Claude Code CLI** | 🥇 Tier 1 (Native) | OS PreToolUse & Stop hooks (`.claude/settings.local.json`), MCP server (`.mcp.json`) |
 | 🚀 **Antigravity CLI (AGY)** | 🥇 Tier 1 (Native) | AGY Hooks (`hooks.json`), MCP config (`.agents/mcp_config.json`), Governance Skills |
-| 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (`.codex/config.toml`), plugin-packaged gate hooks (installed via Codex plugin marketplace) |
+| 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (`.codex/config.toml`), plugin-packaged gate hooks at the marketplace path Codex reads (`.claude-plugin/marketplace.json`, codex-cli 0.152.x). Hard-gate enforcement verified on real codex-cli: the captured PreToolUse payload is judged and an unauthorized code-write is denied. |
 | 🧩 **Google Antigravity SDK** | 🥇 Tier 1 (Native) | Autonomous Agent SDK bindings and cryptographic provenance verification |
 
 > **Note**: Holmes-Kit focuses strictly on CLI-based autonomous agents to guarantee 100% deterministic OS hook gating (`deny` enforcement) before file modifications occur.

package/dist/.build-id

@@ -1 +1 @@
-9196dd1-mtk1gito
+a14dfa1-mtkqq7jw

package/dist/holmes/cli/agents.js

@@ -204,19 +204,29 @@ function agentFiles(agent, opts) {
             // The MCP wiring stays in `.codex/config.toml` (merged by init.ts).
             // Wiring is not installation: the user still runs `codex plugin marketplace add` and
             // `codex plugin add`, which is why HARNESS_ENFORCES.codex is false.
+            // @implements A-SPEC-533.1 — the marketplace manifest, built ONCE and emitted at BOTH
+            // locations. codex-cli 0.152.x reads `<root>/.claude-plugin/marketplace.json` (measured
+            // 2026-09-03: the `.agents/plugins/` path A-SPEC-442 wrote for 0.151.0 fails with "does not
+            // contain a supported manifest"); the old path stays for 0.151.x backward compatibility.
+            // One source so the two files cannot drift in format or source.path.
+            const marketplaceJson = `${JSON.stringify({
+                name: exports.CODEX_MARKETPLACE,
+                interface: { displayName: 'Holmes-Kit (local)' },
+                plugins: [{
+                        name: 'holmes-kit',
+                        source: { source: 'local', path: `./${exports.CODEX_PLUGIN_DIR.split(path.sep).join('/')}` },
+                        policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+                        category: 'Developer Tools',
+                    }],
+            }, null, 2)}\n`;
             return [
                 {
-                    path: path.join(target, '.agents', 'plugins', 'marketplace.json'),
-                    content: `${JSON.stringify({
-                        name: exports.CODEX_MARKETPLACE,
-                        interface: { displayName: 'Holmes-Kit (local)' },
-                        plugins: [{
-                                name: 'holmes-kit',
-                                source: { source: 'local', path: `./${exports.CODEX_PLUGIN_DIR.split(path.sep).join('/')}` },
-                                policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
-                                category: 'Developer Tools',
-                            }],
-                    }, null, 2)}\n`,
+                    path: path.join(target, '.claude-plugin', 'marketplace.json'), // codex 0.152.x reads here
+                    content: marketplaceJson,
+                },
+                {
+                    path: path.join(target, '.agents', 'plugins', 'marketplace.json'), // 0.151.x (backward compat)
+                    content: marketplaceJson,
                 },
                 {
                     path: path.join(target, exports.CODEX_PLUGIN_DIR, '.codex-plugin', 'plugin.json'),

package/dist/holmes/cli/doctor.js

@@ -876,9 +876,14 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 // it made the tool agree with the mistake.
                 const cdxPluginJson = path.join(target, agents_1.CODEX_PLUGIN_DIR, '.codex-plugin', 'plugin.json');
                 const cdxHooksJson = path.join(target, agents_1.CODEX_PLUGIN_DIR, 'hooks.json');
-                const cdxMarketplace = path.join(target, '.agents', 'plugins', 'marketplace.json');
+                // @implements A-SPEC-533.3 — codex-cli 0.152.x reads the marketplace manifest at
+                // `.claude-plugin/marketplace.json` (measured 2026-09-03); 0.151.x read `.agents/plugins/`.
+                // Judge the gate against the location codex ACTUALLY reads, so a pre-A-SPEC-533.1 wiring (old
+                // location only) is caught instead of passing as "wiring is correct" when it cannot install.
+                const cdxMarketplaceNew = path.join(target, '.claude-plugin', 'marketplace.json');
+                const cdxMarketplaceOld = path.join(target, '.agents', 'plugins', 'marketplace.json');
                 const installCmds = `codex plugin marketplace add "${target}" 후 codex plugin add holmes-kit@${agents_1.CODEX_MARKETPLACE}`;
-                if (fs.existsSync(cdxPluginJson) && fs.existsSync(cdxHooksJson) && fs.existsSync(cdxMarketplace)) {
+                if (fs.existsSync(cdxPluginJson) && fs.existsSync(cdxHooksJson) && (fs.existsSync(cdxMarketplaceNew) || fs.existsSync(cdxMarketplaceOld))) {
                     try {
                         const h = JSON.parse(fs.readFileSync(cdxHooksJson, 'utf8'));
                         const manifest = JSON.parse(fs.readFileSync(cdxPluginJson, 'utf8'));
@@ -895,6 +900,12 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                             // The one path measured to load. `./hooks/hooks.json` parses fine and never fires.
                             add('codex gate', 'FAIL', `플러그인 매니페스트의 hooks 가 './hooks.json' 이 아닙니다: ${String(manifest.hooks)} — Codex 가 적재하지 않습니다`, 'holmes-kit init --target <dir> --agent codex --force 로 다시 배선하십시오.');
                         }
+                        else if (!fs.existsSync(cdxMarketplaceNew)) {
+                            // @implements A-SPEC-533.3 — hooks are correct, but the marketplace manifest is only at
+                            // the old `.agents/plugins/` location; codex 0.152.x reads `.claude-plugin/` and cannot
+                            // install this. Judged AFTER the stale-hook / manifest FAILs so those still win.
+                            add('codex gate', 'WARN', `codex 0.152.x 가 읽는 .claude-plugin/marketplace.json 이 없습니다 — 구 위치(.agents/plugins/marketplace.json)만 있어 codex plugin marketplace add 가 "manifest 없음" 으로 실패합니다 (0.151.x 는 .agents/plugins/, 0.152.x 는 .claude-plugin/)`, 'holmes-kit init --target <dir> --agent codex --force 로 다시 배선하면 두 위치에 매니페스트가 놓입니다.');
+                        }
                         else {
                             add('codex gate', 'WARN', '플러그인 배선은 옳습니다 — 그러나 설치되기 전까지 게이트는 집행되지 않습니다(Codex 는 설치된 마켓플레이스에서만 플러그인을 적재하며, doctor 는 설치 여부를 오프라인에서 확인할 수 없습니다)', `${installCmds} 를 실행한 뒤 새 세션에서 사용하십시오.`);
                         }

package/dist/holmes/cli/init.js

@@ -97,6 +97,9 @@ function buildHookPlan(packageRoot, matcher, specsDir = '.ax/specs') {
         preToolUseMatcher: matcher,
         preToolUseCommand: q(path.join(packageRoot, 'dist', 'holmes', 'hooks', 'pre-tool-use.js')),
         stopCommand: q(path.join(packageRoot, 'dist', 'holmes', 'hooks', 'stop.js')),
+        // @implements A-SPEC-531.2 — the SessionStart banner runs the same node entry; it takes no
+        // `--specs` arg (the banner reads only the package version and the ~/.holmes cache).
+        sessionStartCommand: `node "${path.join(packageRoot, 'dist', 'holmes', 'hooks', 'session-start.js')}"`,
     };
 }
 /**

package/dist/holmes/cli/settings-merge.d.ts

@@ -32,6 +32,7 @@ export interface HookPlan {
     preToolUseMatcher: string;
     preToolUseCommand: string;
     stopCommand: string;
+    sessionStartCommand?: string;
 }
 /** A hook entry belongs to holmes-kit iff its command references our hook scripts. */
 export declare function isHolmesCommand(command: string): boolean;

package/dist/holmes/cli/settings-merge.js

@@ -12,7 +12,7 @@ exports.mergeMcpServers = mergeMcpServers;
 exports.removeMcpServer = removeMcpServer;
 /** A hook entry belongs to holmes-kit iff its command references our hook scripts. */
 function isHolmesCommand(command) {
-    return /dist[/\\]holmes[/\\]hooks[/\\](pre-tool-use|stop)\.js/.test(command) || /\bholmes-(kit|mcp|pre-tool-use|stop)\b/.test(command);
+    return /dist[/\\]holmes[/\\]hooks[/\\](pre-tool-use|stop|session-start)\.js/.test(command) || /\bholmes-(kit|mcp|pre-tool-use|stop)\b/.test(command);
 }
 /**
  * The script path out of a hook command line, e.g. `node "/pkg/dist/.../stop.js"` -> `/pkg/dist/.../stop.js`.
@@ -43,6 +43,11 @@ function mergeHooks(existing, plan) {
     };
     upsert('PreToolUse', { matcher: plan.preToolUseMatcher, hooks: [{ type: 'command', command: plan.preToolUseCommand }] });
     upsert('Stop', { hooks: [{ type: 'command', command: plan.stopCommand }] }); // Stop takes NO matcher
+    // @implements A-SPEC-531.2 — the banner hook, wired like Stop (no matcher). Guarded so an older
+    // caller that builds a plan without it is unchanged (no empty SessionStart group appears).
+    if (plan.sessionStartCommand) {
+        upsert('SessionStart', { hooks: [{ type: 'command', command: plan.sessionStartCommand }] });
+    }
     out.hooks = hooks;
     return out;
 }

package/dist/holmes/governance/autonomy.d.ts

@@ -0,0 +1,14 @@
+import { Spec } from '../spec/spec-parser';
+/** The out-of-band switch. An agent cannot read or set it — the pre-tool-use gate blocks that
+ *  (A-SPEC-532.2), the same self-disarm protection HOLMES_APPROVAL and HOLMES_GATE_BYPASS have. */
+export declare const AUTONOMY_ENV = "HOLMES_AUTONOMOUS_APPROVAL";
+export type ApprovalAutonomy = 'auto' | 'hitl';
+export declare function isHighRiskPath(p: string): boolean;
+/**
+ * The autonomy verdict for approving THIS spec. `resolveParent` is accepted for future
+ * parent-aware rules (kept in the signature so callers wire it once); the current bound is decided
+ * from the spec itself.
+ */
+export declare function specApprovalAutonomy(spec: Spec, _resolveParent: (id: string) => Spec | null): ApprovalAutonomy;
+/** Whether autonomous approval is enabled at all — the out-of-band switch, read at the wiring layer. */
+export declare function autonomousApprovalEnabled(env: NodeJS.ProcessEnv): boolean;

package/dist/holmes/governance/autonomy.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTONOMY_ENV = void 0;
+exports.isHighRiskPath = isHighRiskPath;
+exports.specApprovalAutonomy = specApprovalAutonomy;
+exports.autonomousApprovalEnabled = autonomousApprovalEnabled;
+const scope_judgment_1 = require("../guardrail/scope-judgment");
+/** The out-of-band switch. An agent cannot read or set it — the pre-tool-use gate blocks that
+ *  (A-SPEC-532.2), the same self-disarm protection HOLMES_APPROVAL and HOLMES_GATE_BYPASS have. */
+exports.AUTONOMY_ENV = 'HOLMES_AUTONOMOUS_APPROVAL';
+/**
+ * Path prefixes whose files govern the gate, the ledger, taint boundaries, or this session's own
+ * wiring. A spec touching one of these must not self-approve even at a mid grade — changing them is
+ * exactly the "structural / irreversible" class the owner drew the line at.
+ */
+const HIGH_RISK_PREFIXES = [
+    'src/holmes/hooks/',
+    'src/holmes/guardrail/',
+    'src/holmes/governance/',
+    '.ax/roles',
+    '.claude',
+];
+const TAINT_MARKERS = ['taint', 'dataflow-taint', 'flow-sensitive'];
+function isHighRiskPath(p) {
+    const s = p.replace(/^\.\//, '').replace(/^["'`]|["'`]$/g, '');
+    if (HIGH_RISK_PREFIXES.some((pre) => s.startsWith(pre)))
+        return true;
+    if (s === '.mcp.json' || s.endsWith('/.mcp.json'))
+        return true;
+    // A taint/security boundary file anywhere under rtm/ — the flow engine and its vocabulary.
+    if (s.startsWith('src/holmes/rtm/') && TAINT_MARKERS.some((m) => s.includes(m)))
+        return true;
+    return false;
+}
+/** The declared breaking-change grade of an A-SPEC, or null when absent/blank. */
+function breakingGrade(spec) {
+    const raw = spec.frontmatter?.breaking_change;
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return null;
+    // `<grade>: <reason>` or a bare `none` — the grade is the token before the first colon.
+    return raw.trim().split(':')[0].trim();
+}
+// Grades at or below code-interface are auto; gate-behavior (and anything unrecognised) is not.
+const AUTO_GRADES = new Set(['none', 'persisted-artifact', 'derived-artifact', 'code-interface']);
+/**
+ * The autonomy verdict for approving THIS spec. `resolveParent` is accepted for future
+ * parent-aware rules (kept in the signature so callers wire it once); the current bound is decided
+ * from the spec itself.
+ */
+function specApprovalAutonomy(spec, _resolveParent) {
+    switch (spec.type) {
+        case 'T-SPEC':
+            return 'auto'; // tests are low risk
+        case 'REQ':
+        case 'H-SPEC':
+        case 'C-SPEC':
+            return 'hitl'; // wide blast radius / structural constraint
+        case 'A-SPEC': {
+            const grade = breakingGrade(spec);
+            if (grade === null || !AUTO_GRADES.has(grade))
+                return 'hitl'; // undeclared or gate-behavior
+            const paths = (0, scope_judgment_1.fttPathTokens)(spec.sections['Files to Touch'] ?? '');
+            if (paths.some(isHighRiskPath))
+                return 'hitl'; // gate/governance/taint file
+            return 'auto';
+        }
+        default:
+            return 'hitl'; // unknown kind: fail-safe to human
+    }
+}
+/** Whether autonomous approval is enabled at all — the out-of-band switch, read at the wiring layer. */
+function autonomousApprovalEnabled(env) {
+    const v = env[exports.AUTONOMY_ENV];
+    return typeof v === 'string' && v !== '';
+}

package/dist/holmes/guardrail/write-target.d.ts

@@ -153,4 +153,29 @@ export interface PathImpl {
     resolve: (...parts: string[]) => string;
     sep: string;
 }
+/**
+ * @implements A-SPEC-528.1
+ * One shell command, cut at its separators, with the EFFECTIVE working directory each piece runs
+ * in. The shell-write rules used to hand every relative candidate 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): five in-project writes spelled from a subdirectory were
+ * allowed, three legitimate out-of-tree writes were denied.
+ *
+ * `base: null` means the gate cannot know where the piece runs (dynamic cd argument, `cd -`,
+ * `popd`, ambiguous multi-token target). The consumer fails CLOSED on a governed relative write
+ * candidate in such a piece — and stays silent when no candidate follows.
+ *
+ * The split is QUOTE-AWARE on purpose: a separator inside quotes is data, and a transparent split
+ * would let `printf 'cd /\n'` place a fake `cd` at a segment start and push the base out of the
+ * project (injection found while designing this — the honest-revision note in H-SPEC-528).
+ * Command strings are re-opened explicitly instead: `sh -c '…'`/`eval '…'` programs and
+ * shell-stdin heredoc bodies recurse (their cds stay LOCAL to the child shell, matching real
+ * semantics); data heredoc bodies keep their text for candidate matching but never move the base.
+ * Pure: no fs, no env reads beyond `os.homedir()` for `~`, no `process.platform`.
+ */
+export interface ShellSegment {
+    text: string;
+    base: string | null;
+}
+export declare function shellSegments(command: string, startBase: string, depth?: number): ShellSegment[];
 export declare function resolvesInside(raw: string, roots: readonly string[], impl?: PathImpl): boolean;

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/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/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;

package/dist/holmes/update/update-notice.js

@@ -0,0 +1,131 @@
+"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.NPM_URL = void 0;
+exports.compareSemver = compareSemver;
+exports.readCache = readCache;
+exports.installModeGuide = installModeGuide;
+exports.composeBanner = composeBanner;
+exports.shouldQuery = shouldQuery;
+exports.cacheIsStale = cacheIsStale;
+// @implements A-SPEC-531.1
+// The session banner and update notice, as a PURE core. Every side channel — the filesystem, the
+// clock, the environment — is a parameter, so the whole module verifies offline. The delivery
+// points (SessionStart hook, MCP instructions, init wiring) consume this in A-SPEC-531.2.
+//
+// No new dependency: semver comparison is a three-integer compare (our versions are plain
+// major.minor.patch — a full semver library would carry prerelease/build code this never runs), and
+// the registry query (A-SPEC-531.2) uses Node's built-in https.
+const path = __importStar(require("node:path"));
+exports.NPM_URL = 'https://www.npmjs.com/package/@holmes-lab/holmes-kit';
+const DEFAULT_TTL_MS = 24 * 3600_000;
+/** Parse `major.minor.patch` to a 3-tuple; a non-numeric field becomes 0 (never throws). */
+function triple(v) {
+    const parts = String(v).split('.');
+    const n = (i) => { const x = Number.parseInt(parts[i] ?? '', 10); return Number.isFinite(x) ? x : 0; };
+    return [n(0), n(1), n(2)];
+}
+/** -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). */
+function compareSemver(a, b) {
+    const x = triple(a);
+    const y = triple(b);
+    for (let i = 0; i < 3; i++) {
+        if (x[i] < y[i])
+            return -1;
+        if (x[i] > y[i])
+            return 1;
+    }
+    return 0;
+}
+/** The cache file, read only — no network, no write. Anything unreadable/malformed/mis-shaped → null. */
+function readCache(home, readFile) {
+    let raw;
+    try {
+        raw = readFile(path.join(home, '.holmes', 'update-check.json'));
+    }
+    catch {
+        return null;
+    }
+    if (!raw)
+        return null;
+    try {
+        const v = JSON.parse(raw);
+        if (v && typeof v === 'object'
+            && typeof v.latest === 'string'
+            && typeof v.checkedAt === 'number') {
+            return { latest: v.latest, checkedAt: v.checkedAt };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The one-line update guidance, branched by install mode. `source` returns null (git updates it). */
+function installModeGuide(mode, latest, current) {
+    const head = `[Holmes-Kit] Update available: ${latest} (current ${current}).`;
+    switch (mode) {
+        case 'global-npx':
+            return `${head} Run: npm i -g @holmes-lab/holmes-kit@latest, then holmes-kit init --force (re-pins wiring; requires HOLMES_APPROVAL).`;
+        case 'local-dep':
+            return `${head} Run: npm i -D @holmes-lab/holmes-kit@latest`;
+        case 'source':
+            return 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.
+ */
+function composeBanner(input) {
+    const intro = `[Holmes-Kit] This session is governed by Holmes-Kit v${input.current} (No Spec, No Code) — ${input.npmUrl}`;
+    const latest = input.cached?.latest;
+    if (latest && compareSemver(latest, input.current) > 0) {
+        const guide = installModeGuide(input.mode, latest, input.current);
+        if (guide)
+            return `${intro}\n${guide}`;
+    }
+    return intro;
+}
+/** Whether a network refresh is allowed at all. Opt-out via HOLMES_NO_UPDATE_CHECK or CI. */
+function shouldQuery(env) {
+    return !env.HOLMES_NO_UPDATE_CHECK && !env.CI;
+}
+/** Whether the cache is old enough to refresh. A missing cache is stale. */
+function cacheIsStale(cached, now, ttlMs = DEFAULT_TTL_MS) {
+    if (!cached)
+        return true;
+    return now - cached.checkedAt > ttlMs;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",