@holmes-lab/holmes-kit 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,108 @@ 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.9.0] - 2026-09-04
+
+Internalized TDD discipline — RED-first evidence enforced by a new constitution article (ART-8),
+not a prompt — plus a doctor transparency check and a BUG-1 authoring fix. All additive and
+backward-compatible; existing behaviour is unchanged at the default settings.
+
+### Added
+
+- **Inbuilt TDD, made enforceable** (REQ-534): the superpowers TDD discipline is now a holmes-installed
+  skill AND deterministically enforced, not merely advised.
+  - **ART-8 RED-first evidence** (new constitution article): a changed A-SPEC must show a recorded
+    `red-assertion → green` sequence in the ledger. A `red-error` (a test that could not run — a
+    load/import/collection failure) is **not** a valid RED, so "the covering test failed *correctly*"
+    is judged mechanically. `test_run` classifies each covered file as `red-assertion | red-error |
+    green` and appends per-A-SPEC outcomes; the Stop hook reads them. Ships at
+    `guardrail.redFirstEvidence: track` (observe-first, non-blocking) — promote to `strict` per repo,
+    `off` disables. Evidence-gated (inert until outcomes are recorded) and jest-only for now.
+  - **`holmes-tdd-slice` skill**: restates the Iron Law and Red-Green-Refactor in holmes terms and
+    tags each rule with the article that enforces it (`[ART-1]`/`[ART-4]`/`[ART-8]`/honor-system).
+    Installed alongside the other recovery skills.
+  - **Discriminating power**: a T-SPEC may declare `kills:` (named mutations), and
+    `test_run --mutate <tspec>` applies each against the A-SPEC's source, reporting which SURVIVED
+    (a coverage gap). Selective and opt-in — never a blanket gate.
+- **doctor `mcp schema cost`** (REQ-535): reports holmes-kit's own advertised MCP schema cost
+  (computed live from the tool set, no hardcoded number) and WARNs when `HOLMES_MCP_PROFILE=full`
+  re-advertises the hook-enforced gate-duplicate tools; advises client-side deferred loading.
+  Advisory only (never FAIL), and it never claims to have detected a client's resident behaviour.
+
+### Fixed
+
+- **BUG-1 remainder** (REQ-536): `spec_slice_init` now safe-quotes the `slice` value with `yamlScalar`
+  — it was the one raw interpolation among the slice builders, so a `sliceName` containing a colon or
+  quote could break the generated A-SPEC's frontmatter YAML. And `spec_approve` on a missing id now
+  surfaces any unparseable spec file (with a YAML hint) instead of a bare "not found", closing the
+  silent-loss that hid a broken file behind a "not found".
+
+## [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,20 @@
 
 ---
 
-### 🛡️ Currently Supported Features (v0.3.x Production Features)
+### 🛡️ Currently Supported Features (v0.9.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).
+- 🔴 **Inbuilt TDD — RED-first, enforced not asked** *(new in 0.9.0)*: the test-first discipline is a holmes-installed `holmes-tdd-slice` skill **and** a new constitution article **ART-8**. A changed A-SPEC must show a recorded `red-assertion → green` sequence in the ledger; a `red-error` (a test that could not run) is not a valid RED, so "the covering test failed *correctly*" is judged mechanically, not on trust. `test_run` classifies each covered file (`red-assertion`/`red-error`/`green`) and records per-A-SPEC outcomes the Stop hook reads. Ships at `redFirstEvidence: track` (observe-first, non-blocking; `strict`/`off` per repo), evidence-gated and jest-only for now. A T-SPEC may also declare `kills:` mutations and `test_run --mutate` reports which SURVIVED (a coverage gap). Where superpowers *asks* for RED-first and discriminating power, holmes-kit *proves* them.
+- 🤖 **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.
+- 🧪 **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. As of 0.9.0, doctor also reports holmes-kit's own advertised **MCP schema token cost** (computed live) and warns when `HOLMES_MCP_PROFILE=full` needlessly re-advertises the hook-enforced gate-duplicate tools.
 - 🔔 **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 +50,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
+2a5de17-mtm0zp6n

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

@@ -63,6 +63,8 @@ const mcp_version_1 = require("./mcp-version");
 const codex_toml_1 = require("./codex-toml");
 const agents_1 = require("./agents");
 const mcp_launcher_1 = require("./mcp-launcher");
+const tool_schemas_1 = require("../mcp/tool-schemas");
+const mcp_schema_cost_1 = require("./mcp-schema-cost");
 /**
  * Checks if a script path belongs to the packageRoot, supporting symlinked global installs.
  */
@@ -443,6 +445,16 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     else {
         add('ledger signing', 'WARN', '원장이 서명되지 않습니다(HOLMES_LEDGER_KEY 없음) — 체인이 평문 해시라 파일을 쓸 수 있는 자가 승인 기록도 만들 수 있고, ART-5 의 원장 대조는 장벽이 아니라 비용이 됩니다', 'HOLMES_LEDGER_KEY 를 대역외(에이전트를 기동하는 사람의 환경)에서 설정한 뒤 서버를 다시 시작하십시오. 값은 이 보고서에 절대 출력되지 않습니다.');
     }
+    // @implements A-SPEC-535.1
+    // Advisory: holmes-kit's OWN advertised MCP schema cost, and the one holmes-controlled
+    // misconfiguration (HOLMES_MCP_PROFILE=full re-advertising hook-enforced gate-duplicates). Never
+    // FAIL — efficiency, not correctness. The number is derived from TOOL_SCHEMAS at runtime (no drift),
+    // and the resident-client cost is stated conditionally: a static checker cannot observe whether the
+    // client keeps schemas resident, so it never claims to have detected it.
+    {
+        const sc = (0, mcp_schema_cost_1.mcpSchemaCost)(tool_schemas_1.TOOL_SCHEMAS, tool_schemas_1.HOOK_ENFORCED_TOOLS, process.env.HOLMES_MCP_PROFILE);
+        add('mcp schema cost', sc.level, sc.detail, sc.fix);
+    }
     // @implements A-SPEC-457
     // Whether the ART-2 truncation backstop (A-SPEC-455) is even armed. That backstop compares the
     // committed ledger to the working copy and enumerates targets with `git ls-files .ax/ledger`; an
@@ -876,9 +888,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 +912,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/mcp-schema-cost.d.ts

@@ -0,0 +1,18 @@
+/**
+ * doctor advisory (REQ-535): report holmes-kit's OWN advertised MCP schema cost and flag the one
+ * holmes-controlled misconfiguration (HOLMES_MCP_PROFILE=full re-advertising hook-enforced
+ * gate-duplicates). Pure — no I/O. Never FAIL (efficiency, not correctness). Never claims to have
+ * detected that the client keeps schemas resident (a static checker cannot observe that); the
+ * resident-client cost is stated conditionally.
+ */
+export interface SchemaCostResult {
+    level: 'PASS' | 'WARN';
+    detail: string;
+    fix?: string;
+    advertised: number;
+    tokens: number;
+}
+export declare function mcpSchemaCost(schemas: Record<string, {
+    description?: string;
+    inputSchema?: unknown;
+}>, hidden: Set<string>, profileEnv: string | undefined): SchemaCostResult;

package/dist/holmes/cli/mcp-schema-cost.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpSchemaCost = mcpSchemaCost;
+function mcpSchemaCost(schemas, hidden, profileEnv) {
+    const jsonLen = (n) => JSON.stringify({ name: n, description: schemas[n]?.description, inputSchema: schemas[n]?.inputSchema }).length;
+    const names = Object.keys(schemas);
+    const advertisedNames = names.filter((n) => !hidden.has(n));
+    const hiddenNames = names.filter((n) => hidden.has(n));
+    const est = (ns) => Math.round(ns.reduce((s, n) => s + jsonLen(n), 0) / 4);
+    const tokens = est(advertisedNames);
+    const advertised = advertisedNames.length;
+    if (profileEnv === 'full' && hiddenNames.length > 0) {
+        return {
+            level: 'WARN',
+            detail: `HOLMES_MCP_PROFILE=full re-advertises ${hiddenNames.length} hook-enforced gate-duplicate tool(s) (${hiddenNames.join(', ')}) — about +${est(hiddenNames)} tokens/turn on a client that keeps MCP schemas resident. They are already enforced deterministically by the Stop/PreToolUse hooks and stay callable by name.`,
+            fix: 'Unset HOLMES_MCP_PROFILE unless you specifically need to invoke these tools by name.',
+            advertised, tokens,
+        };
+    }
+    return {
+        level: 'PASS',
+        detail: `holmes-kit advertises ${advertised} MCP tool(s) ≈ ${tokens} tokens in the default profile`
+            + `${hiddenNames.length ? ` (${hiddenNames.length} gate-duplicate tool(s) already hidden)` : ''}. `
+            + `If your MCP client keeps tool schemas resident, this is re-sent each turn — a fixed cost that shrinks as the session grows.`,
+        fix: 'If your MCP client supports on-demand/deferred tool loading, enabling it removes this overhead with no loss (tools load when searched).',
+        advertised, tokens,
+    };
+}

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/config/config.d.ts

@@ -12,6 +12,14 @@ export interface AxConfig {
          * silently impose a new one.
          */
         preEditEvidence: 'off' | 'warn' | 'block';
+        /**
+         * @implements A-SPEC-534.3
+         * RED-first evidence enforcement (ART-8). `off` skips the check; `track` records violations
+         * without blocking a turn (observe-first, the ship default); `strict` blocks like any other
+         * article. Default `track` — unlike `preEditEvidence`, `track` never blocks, so observing
+         * RED-first across the repo is safe before an owner promotes it to `strict`.
+         */
+        redFirstEvidence: 'off' | 'track' | 'strict';
     };
     highRiskDomains: string[];
     storage: {

package/dist/holmes/config/config.js

@@ -47,7 +47,7 @@ exports.DEFAULT_CONFIG = {
     // first refusal is `no-analysis`. Warn reports the missing evidence without stopping work, which
     // is also the only path that accumulates the data a later block decision would need. Raised as an
     // authority question rather than decided by measurement — the user chose this level.
-    guardrail: { enforcement: 'block', enforceHighRisk: true, overrideRequiresAdr: true, preEditEvidence: 'warn' },
+    guardrail: { enforcement: 'block', enforceHighRisk: true, overrideRequiresAdr: true, preEditEvidence: 'warn', redFirstEvidence: 'track' },
     highRiskDomains: ['@auth', '@payment'],
     storage: { specStore: 'local-markdown' },
 };

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/governance/constitution.d.ts

@@ -1,4 +1,5 @@
 import { Spec } from '../spec/spec-parser';
+import type { TestOutcome } from '../review/test-runner';
 /**
  * L1 — Governance CONSTITUTION (target-architecture §7 L1).
  *
@@ -56,6 +57,31 @@ export interface ConstitutionContext {
      * record cannot hide a missing test suite because the syntactic bound is still enforced.
      */
     executedByAspec?: Record<string, number>;
+    /**
+     * @implements A-SPEC-534.2
+     * RED-first evidence (ART-8). `changedAspecs` are the A-SPECs whose source changed in this work
+     * unit; `outcomesByAspec` are the recorded per-A-SPEC test outcomes (from the ledger). ART-8 fires
+     * only in `strict` mode here — `track`/`off` are the caller's report-only / ignore concerns (the
+     * config read and the track-mode recording are I/O, done by the Stop hook). Evidence-gated like
+     * ART-4: an A-SPEC with no recorded outcomes is not a violation.
+     */
+    redFirstMode?: 'strict' | 'track' | 'off';
+    changedAspecs?: string[];
+    outcomesByAspec?: Record<string, Array<{
+        outcome: TestOutcome;
+        ts: string;
+    }>>;
 }
+/**
+ * @implements A-SPEC-534.2
+ * ART-8 RED-first check (pure). For each changed A-SPEC that HAS recorded outcomes, require a
+ * `red-assertion` at ts_red followed by a `green` at ts_green > ts_red. A `red-error` is NOT a valid
+ * RED (a file that could not run its cases proves nothing). An A-SPEC with no outcomes is skipped
+ * (evidence-gated).
+ */
+export declare function redFirstViolations(changedAspecs: string[], outcomesByAspec: Record<string, Array<{
+    outcome: TestOutcome;
+    ts: string;
+}>>): ConstitutionViolation[];
 export declare const ARTICLES: Record<string, string>;
 export declare function verifyConstitution(ctx: ConstitutionContext): ConstitutionViolation[];

package/dist/holmes/governance/constitution.js

@@ -1,11 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ARTICLES = void 0;
+exports.redFirstViolations = redFirstViolations;
 exports.verifyConstitution = verifyConstitution;
 const basis_1 = require("../mcp/basis");
 const spec_types_1 = require("../spec/spec-types");
 const rtm_check_1 = require("../rtm/rtm-check");
 const validator_1 = require("../spec/validator");
+/**
+ * @implements A-SPEC-534.2
+ * ART-8 RED-first check (pure). For each changed A-SPEC that HAS recorded outcomes, require a
+ * `red-assertion` at ts_red followed by a `green` at ts_green > ts_red. A `red-error` is NOT a valid
+ * RED (a file that could not run its cases proves nothing). An A-SPEC with no outcomes is skipped
+ * (evidence-gated).
+ */
+function redFirstViolations(changedAspecs, outcomesByAspec) {
+    const v = [];
+    for (const aspec of changedAspecs) {
+        const outcomes = outcomesByAspec[aspec];
+        if (!outcomes || outcomes.length === 0)
+            continue; // evidence-gated: no record → no violation
+        // The EARLIEST red-assertion anchors the ordering; a green must come after it. A red-error is
+        // deliberately excluded — it means the cases never ran, so it cannot stand in for a real RED.
+        const reds = outcomes.filter((o) => o.outcome === 'red-assertion').map((o) => o.ts).sort();
+        const tsRed = reds[0];
+        const greenAfterRed = tsRed !== undefined && outcomes.some((o) => o.outcome === 'green' && o.ts > tsRed);
+        if (!greenAfterRed) {
+            v.push({ article: 'ART-8', detail: `${aspec}: source changed but no recorded red-assertion→green sequence — a covering test that never failed first proves nothing; make it fail (assertion, not error) before the code (ART-8)` });
+        }
+    }
+    return v;
+}
 exports.ARTICLES = {
     'ART-7': '열린 치명 발견은 미완이다 — severity critical 이 open 인 한 완료가 없다 (important/minor 는 review_status 보고에만 남는다: 기록을 피하게 만드는 차단은 원장을 죽인다)',
     'ART-6': '판단은 현재 빌드에서 내려야 한다 — 설치된 코드와 갈라진 서버에서 봉인된 리뷰 결과는 이미 사라진 세계를 기술한다',
@@ -14,6 +39,7 @@ exports.ARTICLES = {
     'ART-3': 'Spec validity — every governed spec satisfies its type rules, including honest 4-quadrant GWT coverage',
     'ART-4': 'Coverage honesty — declared coverage must be backed by real anchored test cases, not prose',
     'ART-5': 'Approval is out-of-band — a spec cannot self-approve; governance config cannot be self-written',
+    'ART-8': 'Test-first is observed — a changed A-SPEC must show a recorded red-assertion→green sequence before it is done (a red-error is not a valid RED)',
 };
 function verifyConstitution(ctx) {
     const governed = (0, spec_types_1.filterGoverned)(ctx.specs);
@@ -67,6 +93,13 @@ function verifyConstitution(ctx) {
             }
         }
     }
+    // @implements A-SPEC-534.2
+    // ART-8: RED-first evidence. Only `strict` mode emits a BLOCKING violation here; `track` (report
+    // only) and `off` are the caller's I/O concern (the config read + track-mode ledger recording live
+    // in the Stop hook, 534.3). Evidence-gated inside redFirstViolations.
+    if (ctx.redFirstMode === 'strict' && ctx.changedAspecs && ctx.outcomesByAspec) {
+        v.push(...redFirstViolations(ctx.changedAspecs, ctx.outcomesByAspec));
+    }
     // @implements A-SPEC-160
     // ART-6: a judgement sealed while the answering server ran code that no longer matched what was
     // installed. Measured 2026-08-08: such a server reported `impactedSpecs: []` for a commit touching

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;