@holmes-lab/holmes-kit 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -5,7 +5,52 @@ 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
+## [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

package/README.md

@@ -18,7 +18,8 @@
 
 - 📋 **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.
+- 🧰 **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.

package/dist/.build-id

@@ -1 +1 @@
-2a5de17-mtm0zp6n
+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

@@ -810,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/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/mcp/elicit-approval.d.ts

@@ -20,6 +20,15 @@
  */
 /** Approval kinds that may ask in-session. Widening this set is a spec revision, not a drive-by. */
 export declare const ELICITABLE_KINDS: ReadonlySet<string>;
+/**
+ * @implements A-SPEC-540.1
+ * True when the operator has opted OUT of in-client elicitation via `HOLMES_ELICIT`. Then the server
+ * folds every elicitation to `silent` (refuse+enqueue) — the same path a client that never advertised
+ * the capability takes — so claude/agy/codex converge on ONE out-of-band decision surface
+ * (`holmes-kit approve`) instead of depending on each client's prompt rendering. Unset, or any
+ * non-disabling value, keeps elicitation ON — byte-identical to before.
+ */
+export declare function elicitationDisabled(env: NodeJS.ProcessEnv): boolean;
 export interface ElicitApprovalRequest {
     kind: string;
     target: string;

package/dist/holmes/mcp/elicit-approval.js

@@ -2,6 +2,7 @@
 // @implements A-SPEC-263.1
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_PRESENTATIONS = exports.ELICIT_TIMEOUT_MS = exports.ELICITABLE_KINDS = void 0;
+exports.elicitationDisabled = elicitationDisabled;
 exports.elicitTimeoutMsFor = elicitTimeoutMsFor;
 exports.classifyElicitError = classifyElicitError;
 exports.expiredNotice = expiredNotice;
@@ -31,6 +32,20 @@ exports.interpretElicitResult = interpretElicitResult;
  */
 /** Approval kinds that may ask in-session. Widening this set is a spec revision, not a drive-by. */
 exports.ELICITABLE_KINDS = new Set(['spec-approve', 'review-resolve']);
+/** The `HOLMES_ELICIT` values that turn the in-client prompt OFF. */
+const ELICIT_DISABLED_TOKENS = new Set(['off', '0', 'false', 'no', 'disabled']);
+/**
+ * @implements A-SPEC-540.1
+ * True when the operator has opted OUT of in-client elicitation via `HOLMES_ELICIT`. Then the server
+ * folds every elicitation to `silent` (refuse+enqueue) — the same path a client that never advertised
+ * the capability takes — so claude/agy/codex converge on ONE out-of-band decision surface
+ * (`holmes-kit approve`) instead of depending on each client's prompt rendering. Unset, or any
+ * non-disabling value, keeps elicitation ON — byte-identical to before.
+ */
+function elicitationDisabled(env) {
+    const v = env.HOLMES_ELICIT;
+    return typeof v === 'string' && ELICIT_DISABLED_TOKENS.has(v.trim().toLowerCase());
+}
 /**
  * The lock-holding path's timeout truth (and the stage-2 reason dialog's): review-resolve holds
  * the findings-ledger lock while the dialog waits, so its ceiling never grows (REQ-497 기아 방지).

package/dist/holmes/mcp/handlers.d.ts

@@ -158,6 +158,85 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         dependents: string[];
         reason?: undefined;
     }>;
+    /**
+     * @implements A-SPEC-538.1
+     * The inverse of spec_approve: returns a SEALED (approved) spec to an editable `draft`, clearing
+     * `approved_digest` and `parent_digests` in ONE act, and records `spec-unsealed`. Hand-editing
+     * only `status` leaves seal residue that later trips validation; this atomizes the reverse.
+     *
+     * Un-sealing WITHDRAWS a seal, so — like retiring a sealed document — it demands a covering
+     * out-of-band HOLMES_APPROVAL (fail-closed): un-sealing an approved T-SPEC removes the code
+     * gate's demand, so an unguarded un-seal would be an approval bypass. And it refuses when an
+     * APPROVED spec depends on the target, because that dependent's `parent_digests` — the snapshot
+     * drift detection compares against — would silently go stale.
+     */
+    spec_unseal(a: {
+        root?: string;
+        id: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        unsealed?: undefined;
+        id?: undefined;
+        dependents?: undefined;
+    } | {
+        ok: boolean;
+        unsealed: boolean;
+        id: string;
+        dependents: never[];
+        reason: string;
+    } | {
+        ok: boolean;
+        unsealed: boolean;
+        id: string;
+        dependents: string[];
+        reason?: undefined;
+    }>;
+    /**
+     * @implements A-SPEC-538.2
+     * Read-only: report a spec's approval/seal state — sealed?, approved_digest, each parent's seal
+     * state, and the concrete blockers still standing between it and approval — so a caller need not
+     * parse files to ask "what is the approval state right now". Reuses `sealOf` and `approvalBlockers`
+     * (the same predicates the code gate and spec_approve read) so the report cannot drift from the
+     * acts it describes. No writes, no ledger append.
+     */
+    approval_status(a: {
+        root?: string;
+        id: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+    } | {
+        id: string;
+        type?: string;
+        status: string;
+        sealed: boolean;
+        approvedDigest?: string;
+        parents: import("../spec/approval-status").ParentApproval[];
+        blockers: string[];
+        ok: boolean;
+        reason?: undefined;
+    }>;
+    /**
+     * @implements A-SPEC-538.3
+     * Read-only: return the provenance ledger's events in time order (optionally narrowed to one
+     * spec) so the governance history — approved / unsealed / retired / review-needed … — is legible
+     * at a glance without reading raw JSONL. Reuses FileLedgerStore.loadAll(); the ordering/filtering/
+     * projection is the pure `timelineFrom`. No writes. An absent ledger is an empty history, not an
+     * error.
+     */
+    ledger_timeline(a: {
+        root?: string;
+        id?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        events?: undefined;
+    } | {
+        ok: boolean;
+        events: import("../governance/ledger-timeline").TimelineEntry[];
+        reason?: undefined;
+    }>;
     spec_approve(a: {
         root?: string;
         id: string;
@@ -165,12 +244,21 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         ok: boolean;
         reason: string;
         findings?: undefined;
+        conflict?: undefined;
         approved?: undefined;
         digest?: undefined;
     } | {
         ok: boolean;
         reason: string;
         findings: import("../spec/validator").Finding[];
+        conflict?: undefined;
+        approved?: undefined;
+        digest?: undefined;
+    } | {
+        ok: boolean;
+        reason: string;
+        conflict: import("../spec/version-conflict").ConflictDetail;
+        findings?: undefined;
         approved?: undefined;
         digest?: undefined;
     } | {
@@ -179,6 +267,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         ok?: undefined;
         reason?: undefined;
         findings?: undefined;
+        conflict?: undefined;
     }>;
     spec_list(a: any): Promise<{
         specs: {

package/dist/holmes/mcp/handlers.js

@@ -189,6 +189,9 @@ const spec_digest_1 = require("../spec/spec-digest");
 const spec_store_2 = require("../spec/spec-store");
 const breaking_change_1 = require("../spec/breaking-change");
 const approval_blockers_1 = require("../spec/approval-blockers");
+const approval_status_1 = require("../spec/approval-status");
+const ledger_timeline_1 = require("../governance/ledger-timeline");
+const version_conflict_1 = require("../spec/version-conflict");
 const ledger_store_1 = require("../governance/ledger-store");
 const provenance_chain_1 = require("../governance/provenance-chain");
 const ledger_lock_1 = require("../governance/ledger-lock");
@@ -703,6 +706,11 @@ function makeRawHandlers(store, opts) {
     // stays byte-identical to the pre-elicitation one — nothing is ever worse than before the
     // channel existed.
     const tryElicit = async (kind, target, summary) => {
+        // @implements A-SPEC-540.1 — operator opt-out: with HOLMES_ELICIT=off the server never shows the
+        // in-client prompt, folding to the byte-identical `silent` (refuse+enqueue) path so claude/agy/
+        // codex all converge on one out-of-band surface (holmes-kit approve). Unset ⇒ unchanged.
+        if ((0, elicit_approval_1.elicitationDisabled)(process.env))
+            return { kind: 'silent' };
         if (!opts?.elicit || !elicit_approval_1.ELICITABLE_KINDS.has(kind))
             return { kind: 'silent' };
         try {
@@ -1174,6 +1182,146 @@ function makeRawHandlers(store, opts) {
             });
             return { ok: true, retired: true, id: a.id, dependents: dependents.map((s) => s.id) };
         },
+        /**
+         * @implements A-SPEC-538.1
+         * The inverse of spec_approve: returns a SEALED (approved) spec to an editable `draft`, clearing
+         * `approved_digest` and `parent_digests` in ONE act, and records `spec-unsealed`. Hand-editing
+         * only `status` leaves seal residue that later trips validation; this atomizes the reverse.
+         *
+         * Un-sealing WITHDRAWS a seal, so — like retiring a sealed document — it demands a covering
+         * out-of-band HOLMES_APPROVAL (fail-closed): un-sealing an approved T-SPEC removes the code
+         * gate's demand, so an unguarded un-seal would be an approval bypass. And it refuses when an
+         * APPROVED spec depends on the target, because that dependent's `parent_digests` — the snapshot
+         * drift detection compares against — would silently go stale.
+         */
+        async spec_unseal(a) {
+            const all = await store.list();
+            if (all.filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본이 진본인지 도구가 고를 수 없어 봉인 해제 전에 거부합니다.`,
+                };
+            }
+            const cur = await store.read(a.id);
+            if (!cur) {
+                const dir = store.specsRoot;
+                const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
+                return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
+            }
+            const spec = cur.spec;
+            if (!spec.type) {
+                return {
+                    ok: false,
+                    reason: `${a.id}에는 \`type:\` 선언이 없습니다(구형식 문서) — 어느 폴더에 속하는지 알 수 없어 봉인 해제할 수 없습니다.`
+                        + ` 먼저 spec_upgrade({ id: "${a.id}" })로 형식을 올린 뒤 다시 시도하십시오.`,
+                };
+            }
+            // Sealed ⇔ carries approved_digest. Un-sealing an already-draft spec writes NOTHING (a second
+            // un-seal is history, not graffiti) — mirrors spec_retire's idempotent no-op.
+            const sealed = typeof spec.frontmatter.approved_digest === 'string';
+            if (!sealed) {
+                return { ok: true, unsealed: false, id: a.id, dependents: [], reason: `${a.id}은(는) 이미 미봉인(draft) 상태입니다` };
+            }
+            const approvalRaw = process.env.HOLMES_APPROVAL;
+            let approval;
+            try {
+                approval = approvalRaw ? JSON.parse(approvalRaw) : undefined;
+            }
+            catch {
+                approval = undefined;
+            }
+            const resolved = resolveHandlerApproval(a.root, store, approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString());
+            if (resolved === undefined) {
+                return {
+                    ok: false,
+                    reason: `${a.id}은(는) 봉인된 문서입니다 — 봉인 해제는 이 행위를 덮는 유효한 대역외 HOLMES_APPROVAL 이 필요합니다.`
+                        + ' 봉인을 해제하면 코드 게이트가 요구하던 approved 스펙의 봉인이 사라지므로, 해제가 승인 우회 경로가 되지 않도록 fail-closed 로 막습니다.'
+                        + ' (범위를 쓰면 kind "spec-approve")'
+                        + refusalQueueHint(a.root, store, { kind: 'spec-approve', target: a.id, why: '봉인된 스펙의 해제' }),
+                };
+            }
+            // @implements A-SPEC-245 — a grant that authorized breaking a seal is spent by it.
+            if (resolved.source === 'grant' && resolved.root && resolved.approval.nonce) {
+                (0, approval_grants_1.consumeGrantFile)(resolved.root, resolved.approval.nonce);
+            }
+            const dependents = all.filter((s) => s.id !== a.id && s.dependsOn.includes(a.id));
+            const blocking = dependents.filter((s) => s.status === 'approved').map((s) => s.id);
+            if (blocking.length > 0) {
+                return {
+                    ok: false,
+                    reason: `${a.id}의 봉인을 해제하면 approved 문서 ${blocking.join(', ')}의 parent_digests 가 stale 이 됩니다 — 지금 그 사슬을 지탱하고 있으므로 거부합니다.`
+                        + ' 해당 문서를 먼저 해제/폐기하거나 부모를 다른 문서로 옮기십시오.',
+                };
+            }
+            // Destination BEFORE the write (A-SPEC-188 order): a resolution failure leaves nothing behind.
+            const dest = resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            const ledgerRoot = dest.root;
+            const fm = { ...spec.frontmatter };
+            delete fm.approved_digest; // the seal this act withdraws
+            delete fm.parent_digests;
+            try {
+                await store.write({ ...spec, status: 'draft', frontmatter: fm }, { expectedVersion: cur.version });
+            }
+            catch (e) {
+                if (e instanceof spec_store_2.SpecVersionConflictError) {
+                    return { ok: false, reason: `봉인 해제 진행 중 ${a.id}이(가) 바뀌었습니다 — 확인 후 다시 시도하십시오. 이번 해제는 아무것도 쓰지 않았습니다.` };
+                }
+                throw e;
+            }
+            new ledger_store_1.FileLedgerStore(path.join(ledgerRoot, '.ax', 'ledger')).append({
+                ts: new Date().toISOString(),
+                actor: approval?.actor ?? 'unattributed',
+                kind: 'spec-unsealed',
+                summary: `unsealed ${a.id}`,
+                inputs: [a.id],
+                rationale: approval?.rationale ?? 'unsealed',
+                ...(approval ? { authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token) } : {}),
+            });
+            return { ok: true, unsealed: true, id: a.id, dependents: dependents.map((s) => s.id) };
+        },
+        /**
+         * @implements A-SPEC-538.2
+         * Read-only: report a spec's approval/seal state — sealed?, approved_digest, each parent's seal
+         * state, and the concrete blockers still standing between it and approval — so a caller need not
+         * parse files to ask "what is the approval state right now". Reuses `sealOf` and `approvalBlockers`
+         * (the same predicates the code gate and spec_approve read) so the report cannot drift from the
+         * acts it describes. No writes, no ledger append.
+         */
+        async approval_status(a) {
+            assertSpecStoreReachable('approval_status', store, a.root); // @implements A-SPEC-419
+            const all = await store.list();
+            if (all.filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본의 상태를 물었는지 도구가 고를 수 없어 거부합니다.`,
+                };
+            }
+            const cur = await store.read(a.id);
+            if (!cur) {
+                const dir = store.specsRoot;
+                const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
+                return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
+            }
+            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, resolver(all)) };
+        },
+        /**
+         * @implements A-SPEC-538.3
+         * Read-only: return the provenance ledger's events in time order (optionally narrowed to one
+         * spec) so the governance history — approved / unsealed / retired / review-needed … — is legible
+         * at a glance without reading raw JSONL. Reuses FileLedgerStore.loadAll(); the ordering/filtering/
+         * projection is the pure `timelineFrom`. No writes. An absent ledger is an empty history, not an
+         * error.
+         */
+        async ledger_timeline(a) {
+            const dest = resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            const dir = path.join(dest.root, '.ax', 'ledger');
+            const events = fs.existsSync(dir) ? new ledger_store_1.FileLedgerStore(dir).loadAll() : [];
+            return { ok: true, events: (0, ledger_timeline_1.timelineFrom)(events, a.id) };
+        },
         async spec_approve(a) {
             const approvalRaw = process.env.HOLMES_APPROVAL;
             let approval;
@@ -1415,10 +1563,15 @@ function makeRawHandlers(store, opts) {
             }
             catch (e) {
                 if (e instanceof spec_store_2.SpecVersionConflictError) {
+                    // @implements A-SPEC-538.4 — the refusal is unchanged (refuse, write nothing, the edit
+                    // wins); it now also CARRIES the conflict: the version this act read, the version now on
+                    // disk, and what to retry. Re-read to learn the current version (null if it vanished).
+                    const now = await store.read(a.id).catch(() => null);
                     return {
                         ok: false,
                         reason: `승인 진행 중 ${a.id}이(가) 바뀌었습니다 — 바뀐 내용을 확인하고 다시 승인하십시오.`
                             + ' 이번 승인은 아무것도 쓰지 않았습니다.',
+                        conflict: (0, version_conflict_1.conflictDetail)({ id: a.id, expected: cur.version, current: now?.version ?? null }),
                     };
                 }
                 // @implements A-SPEC-188 — approval can RELOCATE the file (req_type classification moves

package/dist/holmes/mcp/tool-schemas.js

@@ -101,6 +101,38 @@ exports.TOOL_SCHEMAS = {
             required: ['id'],
         },
     },
+    spec_unseal: {
+        description: "The inverse of spec_approve: return ONE sealed (approved) spec to an editable `status: draft`, clearing `approved_digest` and `parent_digests` in a single ACT, and record `spec-unsealed` in the provenance ledger. Un-sealing WITHDRAWS a seal, so it requires the same out-of-band HOLMES_APPROVAL as spec_approve/spec_retire's sealed path (fail-closed): un-sealing an approved T-SPEC removes the code gate's demand, which unguarded would be an approval bypass. Refuses when an APPROVED spec depends on the target — that dependent's parent_digests would silently go stale — naming the blockers. Idempotent: un-sealing a spec that is already draft (never sealed) writes nothing and returns unsealed:false. Written only at the version this act read; a concurrent edit wins and the un-seal is refused for retry. Distinct from spec_retire (which withdraws authority to status:outdated); un-seal keeps the spec alive and editable.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: str('Id of the spec to un-seal (return to draft).'),
+                root: str('Optional when the server is bound to a file store — the ledger location is derived from the store itself; if supplied it must resolve to the SAME project.'),
+            },
+            required: ['id'],
+        },
+    },
+    approval_status: {
+        description: "Read-only: report ONE spec's approval/seal state without the caller parsing files — { sealed, approvedDigest?, status, parents: [{ id, status, sealed, resolved }], blockers: [] }. `sealed` is the same approved_digest predicate the code gate reads; `blockers` is the exact list spec_approve would refuse on (empty once approved), so the report cannot drift from the acts it describes. Each parent entry shows that parent's OWN live seal state (an unresolved depends_on id is reported as status:'missing', resolved:false — not dropped). No writes, no ledger append. Refuses a duplicate or unknown id.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: str('Id of the spec whose approval/seal state to report.'),
+                root: str('Optional when the server is bound to a file store; if supplied it must resolve to the SAME project.'),
+            },
+            required: ['id'],
+        },
+    },
+    ledger_timeline: {
+        description: "Read-only: return the provenance ledger's events in time order — { events: [{ ts, kind, actor, summary, inputs }] } ascending by ts (tiebroken by chain seq). Pass an `id` to narrow to one spec (only events whose `inputs` reference it: spec-approved, spec-unsealed, spec-retired, review-needed …). The chain-integrity fields (hash/prevHash/seq/replicaId) are plumbing and are projected away — this is the governance history, not the tamper-evidence chain. No writes. An absent ledger is an empty history, not an error.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: str('Optional spec id — narrow the timeline to events that reference it.'),
+                root: str('Optional when the server is bound to a file store; the ledger location is derived from the store, or from this root.'),
+            },
+        },
+    },
     spec_approve: {
         description: 'Approve a spec as a sealing ACT: confirm the ledger destination BEFORE sealing → validate (zero errors) → record approved_digest + parent_digests snapshots → status: approved (written only at the version this act read; a concurrent edit wins and the approval is refused for retry) → append spec-approved to the provenance ledger. Requires a valid out-of-band HOLMES_APPROVAL in the SERVER environment (fail-closed; nothing in the request can substitute). Refuses an unsealed approved parent — seal parents first.',
         inputSchema: {

package/dist/holmes/spec/approval-status.d.ts

@@ -0,0 +1,29 @@
+import { Spec } from './spec-parser';
+/** One parent's approval/seal state as seen from a child. */
+export interface ParentApproval {
+    id: string;
+    status: string;
+    sealed: boolean;
+    /** false when the resolver could not find the parent (a dangling depends_on). */
+    resolved: boolean;
+}
+/** A spec's approval/seal state, answerable without the caller parsing any file. */
+export interface ApprovalStatus {
+    id: string;
+    type?: string;
+    status: string;
+    /** carries approved_digest — the code gate treats it as sealed. */
+    sealed: boolean;
+    approvedDigest?: string;
+    parents: ParentApproval[];
+    /** the concrete reasons this spec cannot be approved right now (empty once approved). */
+    blockers: string[];
+}
+/**
+ * @implements A-SPEC-538.2
+ * Pure: describe a spec's approval/seal state from the spec object and a parent resolver. Reuses
+ * `sealOf` (the same seal predicate the code gate reads) and `approvalBlockers` (the exact list
+ * spec_approve would refuse on) so the report cannot drift from the acts it describes. Touches no
+ * filesystem — the handler reads the store and hands the objects in.
+ */
+export declare function describeApproval(spec: Spec, resolve: (id: string) => Spec | null): ApprovalStatus;

package/dist/holmes/spec/approval-status.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeApproval = describeApproval;
+const spec_digest_1 = require("./spec-digest");
+const approval_blockers_1 = require("./approval-blockers");
+/**
+ * @implements A-SPEC-538.2
+ * Pure: describe a spec's approval/seal state from the spec object and a parent resolver. Reuses
+ * `sealOf` (the same seal predicate the code gate reads) and `approvalBlockers` (the exact list
+ * spec_approve would refuse on) so the report cannot drift from the acts it describes. Touches no
+ * filesystem — the handler reads the store and hands the objects in.
+ */
+function describeApproval(spec, resolve) {
+    const seal = (0, spec_digest_1.sealOf)(spec);
+    const parents = (spec.dependsOn ?? []).map((pid) => {
+        const parent = resolve(pid);
+        return parent
+            ? { id: pid, status: parent.status, sealed: !!(0, spec_digest_1.sealOf)(parent).approvedDigest, resolved: true }
+            : { id: pid, status: 'missing', sealed: false, resolved: false };
+    });
+    // An approved spec has, by definition, cleared every blocker; recomputing would only re-report
+    // the placeholder/parent checks against a document that already passed them.
+    const blockers = spec.status === 'approved' ? [] : (0, approval_blockers_1.approvalBlockers)(spec, resolve);
+    return {
+        id: spec.id,
+        type: spec.type,
+        status: spec.status,
+        sealed: !!seal.approvedDigest,
+        approvedDigest: seal.approvedDigest,
+        parents,
+        blockers,
+    };
+}

package/dist/holmes/spec/version-conflict.d.ts

@@ -0,0 +1,21 @@
+/** A structured report of an optimistic-concurrency conflict during a sealing act. */
+export interface ConflictDetail {
+    id: string;
+    /** the version this act READ (and tried to write at). */
+    expectedVersion: string;
+    /** the version now on disk — null when the spec was removed between read and write. */
+    currentVersion: string | null;
+    /** one non-empty sentence: what happened and what to do next. */
+    retry: string;
+}
+/**
+ * @implements A-SPEC-538.4
+ * Pure: describe a version conflict so the refusal names what won and what to retry. The act's
+ * refusal behaviour (refuse, write nothing, the edit wins) is unchanged — this only exposes the
+ * detail. `current` is null when the spec vanished between read and write.
+ */
+export declare function conflictDetail(a: {
+    id: string;
+    expected: string;
+    current: string | null;
+}): ConflictDetail;

package/dist/holmes/spec/version-conflict.js

@@ -0,0 +1,21 @@
+"use strict";
+// @implements A-SPEC-538.4
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conflictDetail = conflictDetail;
+/**
+ * @implements A-SPEC-538.4
+ * Pure: describe a version conflict so the refusal names what won and what to retry. The act's
+ * refusal behaviour (refuse, write nothing, the edit wins) is unchanged — this only exposes the
+ * detail. `current` is null when the spec vanished between read and write.
+ */
+function conflictDetail(a) {
+    const what = a.current === null
+        ? `${a.id} was removed since this act read it (read ${a.expected})`
+        : `${a.id} changed since this act read it (read ${a.expected}, now ${a.current})`;
+    return {
+        id: a.id,
+        expectedVersion: a.expected,
+        currentVersion: a.current,
+        retry: `${what} — nothing was written; re-read ${a.id} and try the approval again.`,
+    };
+}

package/package.json

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