@holmes-lab/holmes-kit 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -4,6 +4,100 @@ 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
+(hostile syntax through every new lowering, taint false-positive/negative controls, import
+boundary and escape attempts). The strong properties held: zero crashes, zero invariant
+violations, zero out-of-scan escapes, and the sanitizer's exact-match fail-open was confirmed
+correct. Four low-severity harvest items were fixed; every keep-as-is verdict carries its
+measurement.
+
+### Fixed
+
+- **Labeled statements are breakable** (REQ-527): Java (and TS) allow `break L` out of ANY
+  labeled statement; the lowering registered only loops and switches, so the legal
+  `L: { … break L; }` refused the whole function. The labeled statement now owns its label's
+  breaks (loops/switches keep consuming labels as before; `continue` stays loop-only, as in the
+  languages themselves).
+- **Two taint sources stopped bleeding through substrings** (REQ-527): C++'s bare `cin` matched
+  inside ordinary identifiers (`racing`, `medicine`…), C#'s bare `Form` matched every `*Form`.
+  Now `std::cin`/`cin >>` and `Request.Form`/`.Form[` — the adversarial probes are regression
+  tests, and the positive controls prove the real reads still fire. **Corpus re-verification:
+  identical numbers everywhere** (violations 0, C++'s two genuine findings kept, all five
+  import-arrival counts unchanged — no legitimate signal was lost).
+- **Two wrong-frame import resolutions refuse** (REQ-527): an absolute `#include "/…"` no longer
+  normalizes into the repository frame, and `super::` beyond a Rust crate root resolves to
+  nothing (rustc calls it an error too). Both could only ever hit scanned files — wrong
+  coordinates, not escapes — and now hit none.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.7.0] - 2026-09-02
 

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 @@
-7cb32c4-mtjifuwa
+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/cpg/foundation/cfg.js

@@ -325,8 +325,31 @@ function cfgOf(ast, fn, source) {
                     return lowerSeq(stmtChildren(i), ctx);
                 case 'labeled_statement': {
                     const [labelNode, inner] = [kids.of(i)[0], stmtChildren(i).at(-1)];
-                    ctx.pendingLabel = labelName(labelNode);
-                    return lowerStmt(inner, ctx);
+                    const lname = labelName(labelNode);
+                    // @implements A-SPEC-527.1 — Java (and TS) allow `break L` out of ANY labeled
+                    // statement, not only loops and switches. Loop/switch inners keep consuming the label
+                    // themselves (their break machinery owns the exits); for every OTHER statement the
+                    // labeled statement itself becomes the breakable, and its parked breaks exit past it.
+                    // `continue` is deliberately NOT registered — the language keeps it loop-only too.
+                    const LABEL_CONSUMERS = new Set([
+                        'while_statement', 'do_statement', 'for_statement', 'for_in_statement',
+                        'enhanced_for_statement', 'foreach_statement', 'for_range_loop',
+                        'switch_statement', 'switch_expression', 'expression_switch_statement',
+                        'type_switch_statement', 'select_statement',
+                        'for_expression', 'while_expression', 'loop_expression',
+                    ]);
+                    if (LABEL_CONSUMERS.has(ast.nodes[inner].type)) {
+                        ctx.pendingLabel = lname;
+                        return lowerStmt(inner, ctx);
+                    }
+                    const owner = { label: lname, target: -1 };
+                    ctx.breakT.push({ label: lname, owner });
+                    const f = lowerStmt(inner, ctx);
+                    ctx.breakT.pop();
+                    const exits = [...f.exits];
+                    for (const b of claimBreaks(owner))
+                        exits.push({ from: b.point, kind: 'break' });
+                    return { entry: f.entry, exits };
                 }
                 case 'elif_clause':
                 case 'if_statement': {

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;