@holmes-lab/holmes-kit 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,87 @@ 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.10.0] - 2026-09-04
+
+Governance UX tools for multi-agent round-trips and observability, a cross-harness approval fix, and
+an Antigravity portability fix. All additive and backward-compatible; existing behaviour is unchanged
+at the default settings.
+
+### Added
+
+- **Governance UX tools** (REQ-538): three new read/act MCP tools plus a conflict-report enrichment.
+  - **`spec_unseal`** — the inverse of `spec_approve`: return a sealed (approved) spec to an editable
+    `draft` in one act, clearing `approved_digest` and `parent_digests`, and record `spec-unsealed`
+    in the provenance ledger. Un-sealing withdraws a seal, so it requires the same out-of-band
+    `HOLMES_APPROVAL` as retiring a sealed doc (fail-closed), and it refuses when an **approved** spec
+    depends on the target (naming the blockers — their `parent_digests` would go stale). Idempotent on
+    an already-draft spec. Distinct from `spec_retire` (which withdraws authority to `outdated`);
+    un-seal keeps the spec alive and editable.
+  - **`approval_status`** *(read-only)* — report a spec's approval/seal state without parsing files:
+    `{ sealed, approvedDigest?, status, parents: [{ id, status, sealed, resolved }], blockers }`.
+    `sealed` is the same predicate the code gate reads and `blockers` is the exact list `spec_approve`
+    would refuse on, so the report cannot drift from the acts it describes.
+  - **`ledger_timeline`** *(read-only)* — return the provenance ledger's events in time order
+    (`{ ts, kind, actor, summary, inputs }`), optionally narrowed to one spec, so the governance
+    history (approved / unsealed / retired / review-needed …) is legible at a glance. Chain-integrity
+    fields are projected away.
+  - **`spec_approve` conflict detail** — the optimistic-concurrency refusal now also carries a
+    structured `conflict: { id, expectedVersion, currentVersion, retry }` (the version this act read,
+    the version now on disk, and what to retry). The refusal itself — refuse, write nothing, the edit
+    wins — is unchanged; this only exposes what happened.
+- **Cross-harness approval opt-out** (REQ-540): a new server-env switch **`HOLMES_ELICIT=off`** makes
+  the server skip the in-client `elicitInput` prompt entirely and fold to the byte-identical
+  refuse+enqueue path — the same path clients that do not advertise elicitation already take. With it
+  on, **claude/agy/codex converge on one out-of-band decision surface** (`holmes-kit approve`, whose
+  default readline input is robust over SSH) instead of each client's own prompt rendering. Env-only
+  (a session cannot set it); unset = byte-identical to before. Not an approval bypass — it routes the
+  prompt to the queue; approval still comes only from a grant or `HOLMES_APPROVAL`.
+
+### Fixed
+
+- **Antigravity hooks survive a package path with spaces** (REQ-539): the `.agents/hooks.json`
+  wiring now emits `command: "node"` + `args: ["<abs path>"]` instead of a single
+  `node "<quoted path>"` string. agy's hook launcher tokenizes the command on whitespace **without
+  honoring quotes**, so a Windows default path (`C:\Program Files\nodejs\…`) split at the space and
+  the PreToolUse hook never loaded (the gate silently off). Passing the path as an `args` element —
+  the array form `mcp_config.json` already used — sidesteps tokenization on every platform. `doctor`'s
+  Antigravity wiring check reads `args[0]` too (older string wirings still handled). *Real Windows/agy
+  execution remains unverified in CI; validated by the emitted JSON shape on the dev environment.*
+
+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),

package/README.md

@@ -14,17 +14,19 @@
 
 ---
 
-### 🛡️ Currently Supported Features (v0.8.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` 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.
+- 🔴 **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.
+- 🧰 **Governance UX tools** *(new in 0.10.0)*: `spec_unseal` (the inverse of `spec_approve` — return a sealed spec to editable `draft` in one act, out-of-band approval required, refuses approved dependents), `approval_status` and `ledger_timeline` (read-only observability into a spec's seal state and the governance history), and a structured `conflict` on `spec_approve`'s optimistic-concurrency refusal (read vs. current version + retry). See CHANGELOG for details.
+- 🤖 **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. *(new in 0.10.0)* Set **`HOLMES_ELICIT=off`** to skip the in-session prompt entirely and route every decision to the out-of-band `holmes-kit approve` queue instead — one decision surface that behaves identically across Claude Code / Antigravity / Codex.
 - 🪧 **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** *(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.
 - 🚦 **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.

package/dist/.build-id

@@ -1 +1 @@
-a14dfa1-mtkqq7jw
+0d70dec-mtn1jk14

package/dist/holmes/cli/agents.js

@@ -107,12 +107,21 @@ const mcpConfig = (packageRoot, specsDir, launcher) => {
  * (Claude 배선이 `guardrail` 모드에서 좁은 매처를 쓰는 것과 다른 선택인데, 그쪽은 그 좁힘이
  * 무엇을 뜻하는지 문서화된 모드 선택이고 여기는 기본 배선이기 때문이다.)
  */
-// A hook `command` is ONE shell string, so the path must be quoted — `buildHookPlan` in init.ts has
-// always done this for the Claude wiring, and this one did not. Measured 2026-08-23 on a machine
-// whose home directory contains a space: the shell split the path, the hook never ran, and the
-// Antigravity gate was silently off. (The MCP config above is different: it passes `args` as an
-// array, where quoting would put literal quote characters into the path.)
-const hookCommand = (packageRoot, script) => `node "${path.join(packageRoot, 'bin', script)}"`;
+// @implements A-SPEC-539.1
+// agy's hook launcher tokenizes the `command` string on whitespace and does NOT honor quotes, so an
+// earlier quoted `node "<path>"` (A-SPEC-193 §2b-2) still broke on a path with spaces: measured on a
+// Windows machine whose Node lives at `C:\Program Files\nodejs`, reported from agy 2026-09-04 — the
+// launcher split `node "C:\Program Files\...` at the space, node took `"C:\Program` for a module
+// (MODULE_NOT_FOUND), and the gate loaded not at all (silently off). Passing the script path as an
+// `args` ELEMENT — the same array form mcp_config already uses — sidesteps tokenization entirely, on
+// every platform. This supersedes the quoted-string form for the antigravity wiring; quoting only
+// ever helped launchers that honor quotes, which agy's does not.
+const antigravityHookEntry = (packageRoot, script) => ({
+    type: 'command',
+    command: 'node',
+    args: [path.join(packageRoot, 'bin', script)],
+    timeout: 30,
+});
 /**
  * @implements A-SPEC-442
  * Codex 훅이 부를 것: **Claude 와 같은 정책 커널**.
@@ -128,17 +137,9 @@ const hooksJson = (packageRoot) => `${JSON.stringify({
     'holmes-kit': {
         PreToolUse: [{
                 matcher: '*',
-                hooks: [{
-                        type: 'command',
-                        command: hookCommand(packageRoot, 'holmes-hook-antigravity.js'),
-                        timeout: 30,
-                    }],
-            }],
-        Stop: [{
-                type: 'command',
-                command: hookCommand(packageRoot, 'holmes-stop-antigravity.js'),
-                timeout: 30,
+                hooks: [antigravityHookEntry(packageRoot, 'holmes-hook-antigravity.js')],
             }],
+        Stop: [antigravityHookEntry(packageRoot, 'holmes-stop-antigravity.js')],
     },
 }, null, 2)}\n`;
 const AGENTS_MD = (enforced) => `# Holmes-Kit — Workspace Operational Discipline

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
@@ -798,17 +810,17 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 const h = JSON.parse(fs.readFileSync(agyHooks, 'utf8'));
                 const entry = h['holmes-kit'];
                 const pre = entry?.PreToolUse?.[0];
-                const preCmd = pre?.hooks?.[0]?.command ?? '';
-                const stopCmd = entry?.Stop?.[0]?.command ?? '';
-                const stale = [preCmd, stopCmd].filter((c) => {
-                    const p2 = (0, settings_merge_1.hookScriptPath)(c);
-                    return !resolvesToPackage(p2, packageRoot);
-                });
+                // @implements A-SPEC-539.1 — the hook script path now lives in args[0] (command is bare
+                // 'node'); older wirings joined it into the command string. Read args first, fall back to
+                // parsing the string so a pre-539 hooks.json is still judged correctly.
+                const scriptOf = (e) => (Array.isArray(e?.args) && typeof e?.args[0] === 'string') ? e.args[0] : (0, settings_merge_1.hookScriptPath)(e?.command ?? '');
+                const stale = [scriptOf(pre?.hooks?.[0]), scriptOf(entry?.Stop?.[0])]
+                    .filter((p2) => !resolvesToPackage(p2, packageRoot));
                 if (entry === undefined) {
                     add('antigravity wiring', 'WARN', `${agyHooks} 에 holmes-kit 항목이 없습니다`, 'holmes-kit init --target <dir> --agent antigravity');
                 }
                 else if (stale.length > 0) {
-                    add('antigravity wiring', 'FAIL', `이 설치본을 가리키지 않는 명령: ${stale.join(' | ')}`, 'holmes-kit init --target <dir> --agent antigravity --force 로 절대 경로를 갱신하십시오.');
+                    add('antigravity wiring', 'FAIL', `이 설치본을 가리키지 않는 훅 경로: ${stale.join(' | ')}`, 'holmes-kit init --target <dir> --agent antigravity --force 로 절대 경로를 갱신하십시오.');
                 }
                 else if ((pre?.matcher ?? '') !== '*') {
                     // 매처가 좁으면 그 밖의 도구가 게이트를 지나간다 — 조용한 구멍이므로 말한다.

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

@@ -0,0 +1,21 @@
+import { ProvenanceEvent } from './provenance-chain';
+/** One governance event, projected to what a timeline shows — chain-integrity fields dropped. */
+export interface TimelineEntry {
+    ts: string;
+    kind: string;
+    actor: string;
+    summary: string;
+    inputs: string[];
+}
+/** The subset of a ledger event this projection reads (structurally typed so callers can pass
+ * FileLedgerStore.loadAll() results directly). */
+type TimelineSource = Pick<ProvenanceEvent, 'ts' | 'kind' | 'actor' | 'summary'> & Partial<Pick<ProvenanceEvent, 'inputs' | 'seq'>>;
+/**
+ * @implements A-SPEC-538.3
+ * Pure: order ledger events into a timeline, optionally narrowed to one spec. Ascending by `ts`
+ * (ISO strings sort lexically), tiebroken by `seq` so same-timestamp events keep chain order. When
+ * `id` is given, only events whose `inputs` reference it survive. Chain-integrity fields
+ * (hash/prevHash/seq/replicaId) are plumbing, not timeline content, and are projected away.
+ */
+export declare function timelineFrom(events: TimelineSource[], id?: string): TimelineEntry[];
+export {};

package/dist/holmes/governance/ledger-timeline.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timelineFrom = timelineFrom;
+/**
+ * @implements A-SPEC-538.3
+ * Pure: order ledger events into a timeline, optionally narrowed to one spec. Ascending by `ts`
+ * (ISO strings sort lexically), tiebroken by `seq` so same-timestamp events keep chain order. When
+ * `id` is given, only events whose `inputs` reference it survive. Chain-integrity fields
+ * (hash/prevHash/seq/replicaId) are plumbing, not timeline content, and are projected away.
+ */
+function timelineFrom(events, id) {
+    const selected = id ? events.filter((e) => (e.inputs ?? []).includes(id)) : events.slice();
+    selected.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : (a.seq ?? 0) - (b.seq ?? 0)));
+    return selected.map((e) => ({
+        ts: e.ts,
+        kind: e.kind,
+        actor: e.actor,
+        summary: e.summary,
+        inputs: e.inputs ?? [],
+    }));
+}

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

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

package/dist/holmes/hooks/stop.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
+exports.changedAnchoredAspecs = changedAnchoredAspecs;
 exports.unanchoredChangedSources = unanchoredChangedSources;
 exports.unrecordedApprovals = unrecordedApprovals;
 exports.rolledBackLedgers = rolledBackLedgers;
@@ -56,10 +57,50 @@ const test_scope_1 = require("../rtm/test-scope");
 const constitution_1 = require("../governance/constitution");
 const provenance_chain_1 = require("../governance/provenance-chain");
 const test_evidence_1 = require("../review/test-evidence");
+const test_outcomes_1 = require("../review/test-outcomes");
+const config_1 = require("../config/config");
 const pre_tool_use_1 = require("./pre-tool-use");
 const governance_history_1 = require("../guardrail/governance-history");
 const constitution_debt_1 = require("../governance/constitution-debt");
 const root_1 = require("../project/root");
+/**
+ * @implements A-SPEC-534.4
+ * ART-8 evidence (I/O half): the A-SPECs whose DIRTY source files carry an @implements anchor. git is
+ * a refinement — no repository means `undefined` (no signal), never a false clean.
+ */
+function changedAnchoredAspecs(root) {
+    const SOURCE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|rb|php|swift)$/;
+    const VENDORED = /^(?:reference|node_modules|dist|build|vendor|third_party)\//;
+    let raw;
+    try {
+        raw = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-uall'], {
+            cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(),
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const ids = new Set();
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        let rel = line.slice(3).trim().replace(/^"|"$/g, '');
+        if (rel.includes(' -> '))
+            rel = rel.split(' -> ')[1]; // renames name the destination
+        if (!SOURCE.test(rel) || VENDORED.test(rel))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(root, rel), 'utf8');
+        }
+        catch {
+            continue;
+        } // deleted/unreadable
+        for (const m of text.matchAll(/@implements\s+(A-SPEC-\d+(?:\.\d+)?)/g))
+            ids.add(m[1]);
+    }
+    return [...ids].sort();
+}
 /**
  * @implements A-SPEC-452
  * ART-1 evidence: which changed source files claim nothing.
@@ -248,7 +289,21 @@ function evaluateStop(specs, evidence) {
     // L1: the Stop gate IS the constitution's re-verification point — every turn boundary re-runs the
     // inviolable articles (ART-2 RTM, ART-3 validity incl. 4-quadrant GWT, ART-4 coverage evidence).
     // The articles live in ONE place (governance/constitution.ts); this gate merely executes them.
-    const violations = (0, constitution_1.verifyConstitution)({ specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings });
+    // @implements A-SPEC-534.4 — ART-8 evidence rides through to the constitution, which emits a
+    // BLOCKING ART-8 violation only in `strict` mode. `track`/`off` produce none here.
+    const violations = (0, constitution_1.verifyConstitution)({
+        specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
+        redFirstMode: evidence?.redFirstMode, changedAspecs: evidence?.changedAspecs, outcomesByAspec: evidence?.outcomesByAspec,
+    });
+    // @implements A-SPEC-534.4 — `track` records ART-8 findings without blocking the turn. Computed
+    // separately (the constitution stays silent on ART-8 outside strict) and returned in `tracked` for
+    // the CLI to record; it never enters `problems`/the block decision.
+    let tracked;
+    if (evidence?.redFirstMode === 'track' && evidence.changedAspecs && evidence.outcomesByAspec) {
+        const t = (0, constitution_1.redFirstViolations)(evidence.changedAspecs, evidence.outcomesByAspec);
+        if (t.length)
+            tracked = t;
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -287,7 +342,7 @@ function evaluateStop(specs, evidence) {
         structured.push({ article: 'ART-2', detail });
     }
     if (problems.length === 0)
-        return { block: false };
+        return { block: false, ...(tracked ? { tracked } : {}) };
     const shown = problems.slice(0, 20);
     const more = problems.length > shown.length ? `\n…and ${problems.length - shown.length} more` : '';
     // @implements A-SPEC-134 — the distinct articles feed the constitution-debt state on a cap-yield.
@@ -301,6 +356,7 @@ function evaluateStop(specs, evidence) {
         block: true,
         articles,
         violations: structured,
+        ...(tracked ? { tracked } : {}),
         reason: `[Holmes-Kit] constitution gate: ${problems.length} article violation(s) must be ` +
             `fixed before finishing:\n${shown.join('\n')}${more}`,
     };
@@ -656,6 +712,25 @@ if (require.main === module) {
             catch {
                 executedByAspec = undefined;
             }
+            // @implements A-SPEC-534.4 — ART-8 RED-first evidence (I/O half). Outcomes recorded at the
+            // current baseline HEAD (where the dirty work's red+green ran); changed anchored A-SPECs from
+            // the working tree; the posture from config. Fail-open: any error leaves ART-8 inert this turn.
+            let redFirstMode;
+            let changedAspecs;
+            let outcomesByAspec;
+            try {
+                redFirstMode = (0, config_1.loadConfig)(stopProjectRoot()).guardrail.redFirstEvidence;
+                if (redFirstMode !== 'off') {
+                    const head = (0, node_child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], { cwd: stopProjectRoot(), stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() }).toString().trim();
+                    changedAspecs = changedAnchoredAspecs(stopProjectRoot());
+                    outcomesByAspec = (0, test_outcomes_1.groupOutcomesByAspec)((0, test_outcomes_1.readOutcomes)(stopProjectRoot()), head);
+                }
+            }
+            catch {
+                redFirstMode = undefined;
+                changedAspecs = undefined;
+                outcomesByAspec = undefined;
+            }
             // Provenance-chain verification (fail-open: a verify error skips the check, never crashes).
             let provenance;
             // @implements A-SPEC-148
@@ -690,7 +765,12 @@ if (require.main === module) {
             const unrecorded = unrecordedApprovals(stopProjectRoot());
             // @implements A-SPEC-455
             const rolledBack = rolledBackLedgers(stopProjectRoot());
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack });
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec });
+            // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
+            // the operator observes RED-first gaps before an owner promotes the posture to strict.
+            if (out.tracked && out.tracked.length > 0) {
+                process.stderr.write(`[Holmes-Kit] ART-8 RED-first (track): ${out.tracked.map((t) => t.detail).join(' | ')}\n`);
+            }
             // @implements A-SPEC-247 — before deciding to re-block, ask whether every unresolved debt is
             // already queued for the owner. If so, tell the user ONCE and let the turn finish; a single
             // non-waiting violation and we block exactly as before.