@holmes-lab/holmes-kit 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,103 @@ 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.15.0] - 2026-09-06
+
+The first field report on Holmes-Kit's own operational data (1,412 unique approval requests vs. 8
+decisions — a 99.4% write-only backlog) drove this release: the approval queue becomes a real
+decision inbox, the field data itself gains machine attribution, and "did you consider all three
+harnesses and all three OSes" stops being a habit and becomes a sealing gate.
+
+### Added
+- **Compatibility declaration gate (REQ-565)** — sealing an A-SPEC now requires two frontmatter
+  declarations, `harness_impact:` and `os_impact:` — either `'none: <real reason>'` or a full
+  3-cell mapping (`{claude, codex, agy}` / `{windows, mac, linux}`, verdicts
+  `supported|unavailable|n-a: <grounds>`). The duty lives on the **act of approval** (the
+  `breaking_change` shape), so already-approved specs are untouched; any spec that changes
+  re-approves and acquires the fields. A `none` claim is **cross-checked by machine**: Files to
+  Touch entries on the harness surface (`hooks/`, adapters, `cli/init|agents`, `mcp/server`)
+  contradict a harness `none`, and file contents carrying OS signals (`process.platform`,
+  `'win32'`, `spawn(`, `.ps1`) contradict an os `none` — a 3-cell mapping is exempt, because it
+  already faced the axis. `spec_slice_init` scaffolds both fields as TODO so authors meet them;
+  the gate refuses the untouched scaffold. The author-facing blocker list (`approvalBlockers`)
+  pre-announces everything the act would refuse — gate/act parity held by test.
+- **`holmes-kit approve --refusals [N]` (REQ-563)** — a read-only view of what this machine's gate
+  refused lately (newest last), so the operator can find the id a deny message named and decide it.
+- **Per-machine field data (REQ-562)** — test outcomes now record to
+  `test-outcomes.<replica>.jsonl` (the provenance replica convention) and merge with the legacy
+  file in timestamp order, so RED→GREEN sequences survive multi-machine histories; approval-queue
+  events carry a `replica` field (`unknown` for pre-existing events). A repo-local aggregator
+  (`src/tools/field-report`, **not shipped in the package**) turns the ledgers into gate-friction,
+  queue-health and RED-first metrics.
+
+### Fixed
+- **The approval queue is a decision inbox again (REQ-563)** — measured: 1,412 unique requests,
+  8 decisions, and the two real inbox items buried under 1,404 single-shot gate refusals nobody
+  ever meant to decide. Gate refusals (shell and unknown kinds) now land in a **local, per-replica
+  refusal log** (`.ax/approvals/refusals.<replica>.jsonl`, added to the managed gitignore — raw
+  commands never leave the machine, closing the public-repo exposure where 45% of tracked targets
+  carried absolute paths). Decision-seeking kinds (`spec-approve`, `config-write`,
+  `autonomy-grant`, `spec-reappraisal`) stay in the tracked queue. `approve <id>` falls back to
+  the refusal log, so the out-of-band shell approval path survives end to end (deny → approve →
+  allow, verified); re-opening after a decision is count-based (clock-free — a millisecond tie
+  was measured losing legitimate retries), and a hold's question now reaches the retry even for
+  refusal-log ids.
+- **Fixture pollution of real field data (REQ-563)** — the adapter parity suite ran deny scenarios
+  against the repository root: 774 `rm -rf /` requested-events over ten days, the single largest
+  item in the first field report. The suite now uses governed tmp roots; measured after: a full
+  suite run adds **zero** events to the real ledgers.
+
+### Notes
+- Version bump is **minor** with two `gate-behavior` changes aboard; the release classifier
+  routes this to HITL by design. The compat gate applies to **newly sealed** A-SPECs only.
+
+## [0.14.0] - 2026-09-06
+
+Closes the gate's oldest blind spot: it judged *where* a change landed, never *what kind* of change it
+was. A dependency swap inside an approved scope — a real architecture change — passed unreviewed. This
+release adds the **spec-evolution trigger**, then hardens it (and the autonomy layer it reports through)
+against everything a post-ship adversarial audit could find. Additive and observe-first: nothing new
+blocks a turn.
+
+### Added
+
+- **Spec-evolution trigger — external-dependency drift** (REQ-559): when a changed, in-scope source
+  file (inside an approved A-SPEC's scope, carrying its anchor) **newly introduces an external
+  dependency**, Holmes-Kit raises a **spec-reappraisal**. Manual mode warns at the turn boundary;
+  under autonomy it also files the drift into the out-of-band `holmes-kit approve` queue, so an
+  autonomous agent cannot quietly re-architect a slice. The detector (`dependencyDelta` /
+  `externalImportsOf`) is pure, TS/JS + Python, and judges only *newly added* bare (non-relative)
+  top-level packages — builtins and stdlib are not drift. Every path fails open: the signal never
+  affects the stop verdict.
+
+### Fixed
+
+- **The autonomy posture is now visible to hook-side processes** (REQ-560): a hook process never
+  inherits the MCP server's environment, so a project that opted in with `init --autonomy` (the switch
+  is persisted into `.mcp.json`) got **no session-start banner and no queue escalation** — the switch
+  was real but invisible to every hook surface. `autonomousApprovalEnabled` and the banner now also
+  judge the project default by reading `.mcp.json` directly (read-only; the file is agent-write
+  protected, so this opens no self-grant path, and the owner's edit now takes effect without a restart).
+- **Dependency detection hardened against real-world source** (REQ-560): prettier-style multiline
+  imports (`import {\n a,\n} from 'pkg'`) were missed entirely — the most common shape in formatted
+  code — and a pure reformat could even report a phantom new dependency. CRLF files broke comment
+  stripping, so a commented-out `require()` fired a false drift on every turn. A `/*` inside a string
+  swallowed the real imports after it. Python `import a, b` saw only the first package. Strings,
+  template literals, docstrings and `x.require()` calls no longer produce phantom dependencies, the
+  Python stdlib and Node builtin lists were widened, and a pathological file (30k unclosed `/*`) went
+  from 2.4s to 12ms.
+- **Reappraisal escalation respects decisions and non-ASCII paths** (REQ-560): an owner-decided
+  (granted/denied) reappraisal is no longer re-queued on the next turn while the tree stays dirty, and
+  an already-pending one is not duplicated. `git status`/`show` now run with `core.quotepath=false`, so
+  Korean- and space-named sources are seen at all — the same blindness affected the ART-8 and ART-1
+  evidence collectors, which are fixed alongside. The signal is also emitted on degraded-yield turns.
+- **Evidence runs are posture-neutral** (REQ-561): `test_run` handed the MCP server's
+  `HOLMES_AUTONOMOUS_APPROVAL` to its jest children, so on a project with autonomy enabled the
+  autonomy branch skipped the elicitation path and 9 elicitation tests went red **on a tree whose full
+  suite was green** — the gate became unusable for exactly the users who opted into autonomy. The
+  switch now joins the scrub list (`HOLMES_SPECS`, `HOLMES_GATE_BYPASS`, …): a posture is an approval
+  channel, never a property of the code under test.
+
 ## [0.13.0] - 2026-09-06
 
 Autonomy grows from a single env switch into a **three-layer, always-bounded** posture — so a team can

package/README.md

@@ -14,7 +14,7 @@
 
 ---
 
-### 🛡️ Currently Supported Features (v0.13.x Production Features)
+### 🛡️ Currently Supported Features (v0.14.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).
 - 🔴 **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.
@@ -22,8 +22,10 @@
 - ⬆️ **Zero-config upgrades** *(new in 0.11.0)*: `holmes-kit upgrade` moves **every** wired workspace to the latest in one command — plan → confirm → install → re-pin all recorded workspaces (`--dry-run`/`--yes` supported). Preparation is automatic (each `init` records the workspace; a session whose pin is behind nudges you to upgrade); the re-pin **write** stays your explicit choice, never a silent auto-install. Opt out of the nudge with `HOLMES_NO_AUTO_REPIN`.
 - 📊 **World-top-tier RTM dashboard** *(new in 0.12.0–0.12.1)*: `holmes-kit serve` — ask to *see* the RTM heatmap and the `rtm_dashboard` MCP tool launches the server idempotently and hands back the URL plus an honesty **census** (requirement/pipeline counts, coverage %, what's excluded). The heatmap is a real **2D coverage matrix** (requirements × pipeline stages, rows seriated by completeness, sequential-ramp cells with the percent printed in each). Drilling into a symbol renders that function's **CFG as a layered DAG** with **PDG (data/control-dependence) colour overlays**, served by `/api/cfg?file=&symbol=` from the same engine the taint lane uses — a non-CFG language is named, never faked. Tokenised palette (sequential ramp, status colours, UI/mono pairing) with light/dark.
 - 🔢 **Sensible spec numbering** *(new in 0.12.1)*: a brand-new project's first slice is now **REQ-100**, not REQ-201 — `spec_slice_init` shares the same id allocator as the reverse-draft path (`nextIdBase`, floor 100). Existing projects are untouched: the next id is always `max(existing)+1`, so a repo already numbering from 201 keeps the exact same sequence. Numbering past 999 yields 4-digit ids cleanly, and ADR references now recognise 4-digit ADRs (`ADR-1000+`).
-- 🤖 **Autonomous Approval — three layers, always bounded** *(reworked in 0.13.0; foundation 0.8.0)*: for teams that want the agent to self-drive the SDLC, autonomy is a posture the agent holds at two scopes — a **project default** you opt into at `holmes-kit init --autonomy` (persisted as the `HOLMES_AUTONOMOUS_APPROVAL` env in `.mcp.json`), and a **per-session envelope** you grant on the spot with `holmes-kit autonomy on --for 2h` (an expiring marker under the agent-write-protected `.ax/state/`). Under either, the agent seals **low-risk** specs itself (ledgered under an `autonomous:<client>` actor); every **governance-critical, high-risk, or irreversible** decision — `gate-behavior`/breaking A-SPECs, architecture/gate/taint files, and every upstream `REQ`/`H-SPEC`/`C-SPEC` — is instead **refused and routed to the out-of-band `holmes-kit approve` queue** for a human, never silently self-approved. The active posture is **surfaced at every session start** so it can't be forgotten, and an agent can never grant it to itself: the env is env-only (blocked like `HOLMES_ROLE`), the session command needs a real TTY or an out-of-band `HOLMES_APPROVAL`, and the marker lives where agents can't write. Off = byte-identical to a fully human-gated project. *(new in 0.10.0)* `HOLMES_ELICIT=off` routes every decision straight to the same queue.
+- 🤖 **Autonomous Approval — three layers, always bounded** *(reworked in 0.13.0; foundation 0.8.0)*: for teams that want the agent to self-drive the SDLC, autonomy is a posture the agent holds at two scopes — a **project default** you opt into at `holmes-kit init --autonomy` (persisted as the `HOLMES_AUTONOMOUS_APPROVAL` env in `.mcp.json`), and a **per-session envelope** you grant on the spot with `holmes-kit autonomy on --for 2h` (an expiring marker under the agent-write-protected `.ax/state/`). Under either, the agent seals **low-risk** specs itself (ledgered under an `autonomous:<client>` actor); every **governance-critical, high-risk, or irreversible** decision — `gate-behavior`/breaking A-SPECs, architecture/gate/taint files, and every upstream `REQ`/`H-SPEC`/`C-SPEC` — is instead **refused and routed to the out-of-band `holmes-kit approve` queue** for a human, never silently self-approved. The active posture is **surfaced at every session start** so it can't be forgotten *(0.14.0: the hook side now reads the project default out of `.mcp.json` directly, so an `init --autonomy` project sees its banner and escalations without an env round-trip)*, and an agent can never grant it to itself: the env is env-only (blocked like `HOLMES_ROLE`), the session command needs a real TTY or an out-of-band `HOLMES_APPROVAL`, and the marker lives where agents can't write. Off = byte-identical to a fully human-gated project. *(new in 0.10.0)* `HOLMES_ELICIT=off` routes every decision straight to the same queue.
+- 🧭 **Spec-Evolution Trigger** *(new in 0.14.0)*: the gate used to judge only *where* a change lands (file ∈ Files-to-Touch, anchored, approved) — never *what kind* of change it is, so a real architecture swap inside an approved scope passed unreviewed. Now, when a changed in-scope source **newly introduces an external dependency** (a swapped engine, a new runtime), Holmes-Kit raises a **spec-reappraisal**: manual mode warns at the turn boundary, and under autonomy it also files the drift in the out-of-band `holmes-kit approve` queue so the owner sees it — a decided reappraisal is never re-raised for the same drift. Observe-first by design: it never blocks a turn. Detection is TS/JS + Python, string- and comment-safe (prettier multiline imports, CRLF files, docstrings and template literals all judged correctly).
 - 🚢 **Release Autonomy + Docs-Currency Gate** *(new in 0.13.0)*: publishing is irreversible and outward, so `npm publish` stays **human-approved by default** — but a deterministic classifier (`releaseAutonomy`, reusing the same per-spec risk grade) lets a **low-risk** release (patch/minor, every spec auto-grade, autonomy on) self-publish under the ledger, while a **major** bump, any `gate-behavior`/security/architecture spec, or an upstream `REQ`/`H-SPEC` forces HITL. The `holmes-publish` playbook also gains a **docs-currency gate**: before any release it diffs the specs since the last tag and blocks if a user-facing change never reached `README`/`CHANGELOG` — a stale doc is a false claim.
+- 🧭 **Compatibility declaration gate** *(new in 0.15.0)*: Holmes-Kit runs on three agent harnesses (Claude Code, Codex, Antigravity) and three OSes (Windows/macOS/Linux) — and now the **sealing act itself asks whether you considered them**. A new A-SPEC approves only with `harness_impact:` and `os_impact:` declared (`'none: <reason>'` or a full 3-cell mapping with `supported|unavailable|n-a` verdicts); a `none` claim is machine-cross-checked against Files-to-Touch (harness-surface paths, OS-signal file contents), the slice scaffold plants both fields as TODO the gate refuses untouched, and already-sealed specs are untouched — the duty arrives with the next re-approval, exactly like `breaking_change`.
 - 🌐 **English CLI & hook surface** *(new in 0.13.0)*: the operator-facing CLI and hook messages — `doctor` output, the CLI usage/errors, the hook `deny` reasons and ART citations, and the interactive `approve`/`init`/`upgrade`/`semantic-key` prompts — are now English, guarded by a hangul-absence test over the **rendered runtime output** (not just a source scan, which misses `\u`-escaped strings). The MCP tool responses (`spec_create`/`spec_approve`/ledger/review) are still being migrated and are next.
 - 🪧 **Session Banner + Update Notice** *(new in 0.8.0; refresh implemented + made uniform in 0.12.2)*: 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 on npm, an install-mode-aware `holmes-kit upgrade` command is appended. The registry refresh (dist-tags query → cached in `~/.holmes/update-check.json`) is detached, TTL-gated, and fail-silent, and now fires from **every harness's MCP-server startup** — not just Claude's SessionStart hook — so Claude / Antigravity / Codex are notified alike. Opts out via `HOLMES_NO_UPDATE_CHECK`/`CI`. Upgrade execution stays your explicit choice (`holmes-kit upgrade`), never a silent auto-install.
 - 🧱 **Deterministic Gate, Hardened** *(new in 0.8.0; further hardened in 0.13.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. *(0.13.0)* Two more bypasses are closed: the gate treats a project as **governed when any spec exists** (a fresh project holding only unapproved drafts is no longer an ungoverned free-for-all), and it classifies `cp`/`mv` by their **destination** (a copy/move landing on a source path is sealed even when the source file isn't code). Every gate change ships with two consecutive clean adversarial rounds.
@@ -32,7 +34,7 @@
 - 🐞 **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. 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.
+- 🔔 **Approval UX** *(new in 0.3.1; inbox split 0.15.0)*: 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. Since 0.15.0 the tracked queue holds **decision-seeking requests only**; plain gate refusals live in a local per-machine refusal log (raw commands never leave the machine), browsable with `approve --refusals` and still decidable by id — measured before the split, 1,404 single-shot refusals were burying a 2-item inbox.
 - 🚦 **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.

package/dist/.build-id

@@ -1 +1 @@
-55b0a37-mtp8gdtd
+2a7fb45-mtps37rf

package/dist/holmes/cli/approve.d.ts

@@ -83,6 +83,20 @@ export declare function decisionDetail(p: PendingRequest, tail?: string): string
  * must transcribe: [noguess]. An empty queue yields an empty hint — nothing to act on, nothing to
  * advise. `renderPending` itself stays hint-free: the explicit `--list` output is for scripts.
  */
+/**
+ * @implements A-SPEC-563.2
+ * The read-only refusal view: what THIS machine's gate refused lately, newest last. The raw target
+ * appears on the operator's SCREEN only — the refusal log never leaves the machine (A-SPEC-563.1),
+ * and this renderer is the reason an operator can find the id the deny message named. Row width
+ * follows the decision list's screen-safe discipline.
+ */
+export declare function renderRefusals(refusals: Array<{
+    id: string;
+    kind: string;
+    target: string;
+    why: string;
+    ts: string;
+}>, limit?: number): string;
 export declare function renderNonTtyHint(state: QueueState): string;
 export interface ApproveIO {
     print: (s: string) => void;

package/dist/holmes/cli/approve.js

@@ -42,6 +42,7 @@ exports.subjectCells = subjectCells;
 exports.subjectRoom = subjectRoom;
 exports.decisionSubject = decisionSubject;
 exports.decisionDetail = decisionDetail;
+exports.renderRefusals = renderRefusals;
 exports.renderNonTtyHint = renderNonTtyHint;
 exports.runInteractive = runInteractive;
 // @implements A-SPEC-246
@@ -78,7 +79,44 @@ const MAX_TTL_MINUTES = 7 * 24 * 60;
 const DEFAULT_RATIONALE = 'approved via holmes-kit approve';
 const findPending = (root, id) => {
     const state = (0, approval_queue_1.readQueue)(root);
-    return { entry: state.pending.find((p) => p.id === id), state };
+    const pending = state.pending.find((p) => p.id === id);
+    if (pending)
+        return { entry: pending, state };
+    // @implements A-SPEC-563.2 — the refusal-log fallback. Shell refusals no longer sit in the tracked
+    // inbox (A-SPEC-563.1), but the out-of-band approval story must survive: the operator saw the deny
+    // in session, the deny named this id, and the RAW target lives in this machine's local refusal log
+    // — exactly the "grant is for what the human saw" contract. A decided id never promotes: the
+    // granted/denied event in the queue closes the request, same single-use convention as pending.
+    try {
+        const { readRefusals } = require('../governance/approval-queue');
+        let mine = readRefusals(root).filter((r) => r.id === id);
+        // A decided id closes the request — UNLESS the gate refused it again afterwards. The fold has
+        // the same rule for pending (a later `requested` re-inserts after granted/denied): a human may
+        // change their mind, and the retry is what re-opens the question.
+        const decided = state.decisions[id];
+        if (decided) {
+            // Clock-free reopening: the decision recorded HOW MANY occurrences it covered, so a retry is
+            // simply everything past that count — millisecond ties (measured flaky under the full suite)
+            // cannot lose it. Legacy decisions without the count fall back to the timestamp rule.
+            if (typeof decided.covered === 'number')
+                mine = mine.slice(decided.covered);
+            else
+                mine = mine.filter((r) => r.ts > decided.ts);
+        }
+        if (mine.length > 0) {
+            const latest = mine[mine.length - 1];
+            return {
+                entry: {
+                    id, kind: latest.kind, target: latest.target, why: latest.why,
+                    count: mine.length, firstTs: mine[0].ts, lastTs: latest.ts,
+                    ...(latest.replica ? { replica: latest.replica } : {}),
+                },
+                state,
+            };
+        }
+    }
+    catch { /* a broken refusal log must not break the decision surface */ }
+    return { entry: undefined, state };
 };
 /** CLI-side event writer. The CLI runs in the operator's terminal, outside the session gates. */
 /**
@@ -186,7 +224,7 @@ function grantRequest(root, id, opts) {
         // class round-6 closed in findingContext, three files over.
         return { ok: false, reason: `cannot write the grant file:\n   ${(0, screen_safe_1.rowField)(e instanceof Error ? e.message : String(e), 76)}` };
     }
-    if (!appendEvent(root, { event: 'granted', id, actor: opts.actor, expires })) {
+    if (!appendEvent(root, { event: 'granted', id, actor: opts.actor, expires, covered: entry.count })) {
         try {
             fs.rmSync(tmp, { force: true });
         }
@@ -212,7 +250,7 @@ function denyRequest(root, id, reason, actor) {
     // The event IS the decision here (there is no second artefact), so a failed append is a failed
     // decision — round-5: ✓ and exit 0 were printed over a read-only queue while nothing was recorded,
     // and the agent, never seeing the denial, retried forever.
-    if (!appendEvent(root, { event: 'denied', id, reason, actor })) {
+    if (!appendEvent(root, { event: 'denied', id, reason, actor, covered: entry.count })) {
         return { ok: false, reason: 'could not write the denial record (queue event) — check write permission on .ax/approvals. Nothing was recorded' };
     }
     return { ok: true };
@@ -366,6 +404,25 @@ function decisionDetail(p, tail = '') {
  * must transcribe: [noguess]. An empty queue yields an empty hint — nothing to act on, nothing to
  * advise. `renderPending` itself stays hint-free: the explicit `--list` output is for scripts.
  */
+/**
+ * @implements A-SPEC-563.2
+ * The read-only refusal view: what THIS machine's gate refused lately, newest last. The raw target
+ * appears on the operator's SCREEN only — the refusal log never leaves the machine (A-SPEC-563.1),
+ * and this renderer is the reason an operator can find the id the deny message named. Row width
+ * follows the decision list's screen-safe discipline.
+ */
+function renderRefusals(refusals, limit = 20) {
+    if (refusals.length === 0)
+        return '◆ no refusals recorded on this machine';
+    const recent = refusals.slice(-Math.max(1, limit));
+    const lines = [`◆ ${refusals.length} refusal(s) on this machine — showing ${recent.length} (newest last)`, ''];
+    for (const r of recent) {
+        lines.push(`${(0, screen_safe_1.rowField)(r.id, 20)} ${(0, screen_safe_1.rowField)(r.kind, screen_safe_1.KIND_COLS)} ${(0, screen_safe_1.rowField)(r.target, 40)}`);
+        lines.push(`  \u2502 ${(0, screen_safe_1.rowField)(r.why, 66)}  ${(0, screen_safe_1.rowField)(r.ts, 24)}`);
+    }
+    lines.push('', `decide one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve <id>`);
+    return lines.join('\n');
+}
 function renderNonTtyHint(state) {
     if (state.pending.length === 0)
         return '';

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

@@ -36,6 +36,11 @@ exports.IGNORE_LINES = [
     // project content — left untracked they show up in `git status` and read as install damage.
     '.ax/state/',
     '*.holmes-bak-*',
+    // @implements A-SPEC-563.1 — the per-replica refusal log carries RAW refused commands (absolute
+    // paths measured in 45% of them), and the grant contract needs them raw ("the grant is for what
+    // the human saw" — round-14, exact match). Raw-and-local is the only shape that serves both ADR-012
+    // and approvals: the file never leaves the machine, and `holmes-kit approve` reads it right there.
+    '.ax/approvals/refusals*.jsonl',
     // @implements A-SPEC-193 — 하네스 배선물은 이 **설치본의 절대 경로**를 담는다(훅은 hooks.json
     // 이 있는 디렉터리를 cwd 로 돌고, 패키지가 어디 설치됐는지는 기계마다 다르다). 그 경로가
     // VCS 에 들어가면 다른 기계에서 남의 설치를 부르거나 아무것도 부르지 못한다. 팀과 공유하고

package/dist/holmes/cli/index.js

@@ -78,7 +78,7 @@ const KNOWN_FLAGS = {
     skills: ['help', 'target'],
     ci: ['help', 'target', 'specs-dir', 'json'],
     serve: ['help', 'target', 'port'],
-    approve: ['help', 'target', 'list', 'grant', 'deny', 'ask', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'],
+    approve: ['help', 'target', 'list', 'refusals', 'grant', 'deny', 'ask', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'],
     ledger: ['help', 'target', 'ref', 'dry-run'],
     // @implements A-SPEC-477 — the human's opt-in act for the cloud semantic tier.
     'semantic-key': ['help'],
@@ -839,6 +839,18 @@ async function main(argv) {
             process.stdout.write(renderPending(readQueue(root, queueOpts), listView) + '\n');
             return 0;
         }
+        // @implements A-SPEC-563.2 — the read-only refusal view (local log; raw targets stay on-screen).
+        if (flags.refusals !== undefined) {
+            const { renderRefusals } = require('./approve');
+            const { readRefusals } = require('../governance/approval-queue');
+            const limit = typeof flags.refusals === 'string' ? Number(flags.refusals) : 20;
+            if (!Number.isInteger(limit) || limit <= 0) {
+                process.stderr.write(`✗ --refusals expects a positive integer count — received: ${flags.refusals}\n`);
+                return 1;
+            }
+            process.stdout.write(renderRefusals(readRefusals(root), limit) + '\n');
+            return 0;
+        }
         // @implements A-SPEC-262.2 — the RESIDENT surface. Validate --poll-ms first (so a bad value is
         // named even on a non-TTY), then refuse a non-TTY (a resident interactive loop needs a terminal),
         // then run the loop. SIGINT and readline close both abort it — the operator leaving, either way,

package/dist/holmes/governance/approval-queue.d.ts

@@ -18,6 +18,21 @@
  * provenance chain already use, so a reader learns no new model.
  */
 export declare const QUEUE_RELPATH: string;
+export declare const DECISION_KINDS: ReadonlySet<string>;
+export interface RefusalRecord {
+    event: 'requested';
+    id: string;
+    kind: string;
+    target: string;
+    why: string;
+    ts: string;
+    replica?: string;
+}
+export declare function refusalsFilename(replica: string): string;
+/** Born split: there is no legacy single `refusals.jsonl` — the file did not exist before replicas did. */
+export declare function isRefusalsFilename(name: string): boolean;
+/** All replica refusal logs of this project, merged in ts order (stable). Missing dir → []. */
+export declare function readRefusals(root: string): RefusalRecord[];
 export interface PendingRequest {
     id: string;
     kind: string;
@@ -28,6 +43,13 @@ export interface PendingRequest {
     lastTs: string;
     hold?: boolean;
     question?: string;
+    /**
+     * @implements A-SPEC-562.2
+     * Which machine raised this request (`resolveReplicaId`), or `'unknown'` for the events written
+     * before attribution existed. Display and aggregation ONLY — no gate, grant or approval decision
+     * reads it, so an absent or wrong value can never change a verdict.
+     */
+    replica?: string;
 }
 export interface QueueState {
     pending: PendingRequest[];
@@ -53,6 +75,17 @@ export interface QueueState {
         event: 'granted' | 'denied';
         reason?: string;
         ts: string;
+        covered?: number;
+    }>;
+    /**
+     * @implements A-SPEC-563.2
+     * Live holds by id, INDEPENDENT of pending: a shell refusal is no longer a pending entry
+     * (A-SPEC-563.1), but the operator's hold question must still reach the agent's next retry.
+     * A later decision clears the hold — an answered question is not still being asked.
+     */
+    holds: Record<string, {
+        question?: string;
+        ts: string;
     }>;
 }
 /**

package/dist/holmes/governance/approval-queue.js

@@ -33,7 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QUEUE_RELPATH = void 0;
+exports.DECISION_KINDS = exports.QUEUE_RELPATH = void 0;
+exports.refusalsFilename = refusalsFilename;
+exports.isRefusalsFilename = isRefusalsFilename;
+exports.readRefusals = readRefusals;
 exports.approvalRequestId = approvalRequestId;
 exports.foldQueue = foldQueue;
 exports.enqueueApprovalRequest = enqueueApprovalRequest;
@@ -45,6 +48,7 @@ const npx_bin_1 = require("../project/npx-bin");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const screen_safe_1 = require("../cli/screen-safe");
+const replica_id_1 = require("./replica-id");
 /**
  * The approval request queue — the review list a human batches decisions over.
  *
@@ -65,6 +69,58 @@ const screen_safe_1 = require("../cli/screen-safe");
  * provenance chain already use, so a reader learns no new model.
  */
 exports.QUEUE_RELPATH = path.join('.ax', 'approvals', 'queue.jsonl');
+// @implements A-SPEC-563.1 — the tracked queue is a DECISION INBOX, not a refusal log. Measured
+// (field report, 2026-09-06): 1,412 unique requests vs 8 decisions — 99.8% of the backlog was
+// single-shot gate refusals nobody ever meant to decide, burying the real inbox (spec-approve 9,
+// config-write 1) and accumulating raw shell commands in a tracked file. Only these kinds seek a
+// decision; everything else routes to the local per-replica refusal log below. Wired RED-first.
+exports.DECISION_KINDS = new Set([
+    'spec-approve', 'config-write', 'autonomy-grant', 'spec-reappraisal',
+]);
+const REFUSALS_FILE_RE = /^refusals\.([^.]+)\.jsonl$/;
+function refusalsFilename(replica) {
+    return `refusals.${replica}.jsonl`;
+}
+/** Born split: there is no legacy single `refusals.jsonl` — the file did not exist before replicas did. */
+function isRefusalsFilename(name) {
+    return REFUSALS_FILE_RE.test(name);
+}
+/** All replica refusal logs of this project, merged in ts order (stable). Missing dir → []. */
+function readRefusals(root) {
+    const dir = path.join(root, '.ax', 'approvals');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter(isRefusalsFilename).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    let i = 0;
+    for (const name of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r === 'object' && r.event === 'requested' && typeof r.id === 'string'
+                    && typeof r.kind === 'string' && typeof r.target === 'string' && typeof r.ts === 'string') {
+                    out.push({ r: r, i: i++ });
+                }
+            }
+            catch { /* a corrupt line never breaks the read */ }
+        }
+    }
+    return out.sort((a, b) => (a.r.ts < b.r.ts ? -1 : a.r.ts > b.r.ts ? 1 : a.i - b.i)).map((e) => e.r);
+}
 /**
  * Deterministic request id from the action's identity.
  *
@@ -87,6 +143,7 @@ function approvalRequestId(kind, target) {
 function foldQueue(lines, opts) {
     const pending = new Map();
     const decisions = {};
+    const holds = {};
     let malformedLines = 0;
     for (const raw of Array.isArray(lines) ? lines : []) {
         const line = String(raw ?? '').trim();
@@ -127,6 +184,9 @@ function foldQueue(lines, opts) {
                         count: 1,
                         firstTs: ts,
                         lastTs: ts,
+                        // @implements A-SPEC-562.2 — events written before attribution existed have no field;
+                        // `unknown` names that honestly instead of pretending they came from this machine.
+                        replica: typeof e.replica === 'string' && e.replica !== '' ? e.replica : 'unknown',
                     });
                 }
                 break;
@@ -135,10 +195,12 @@ function foldQueue(lines, opts) {
             case 'denied':
                 if (id) {
                     pending.delete(id);
+                    delete holds[id]; // @implements A-SPEC-563.2 — a decision answers the question
                     decisions[id] = {
                         event: e.event,
                         ...(typeof e.reason === 'string' ? { reason: e.reason } : {}),
                         ts: typeof e.ts === 'string' ? e.ts : '',
+                        ...(typeof e.covered === 'number' ? { covered: e.covered } : {}),
                     };
                 }
                 break;
@@ -149,6 +211,10 @@ function foldQueue(lines, opts) {
                     if (typeof e.question === 'string')
                         entry.question = e.question;
                 }
+                // @implements A-SPEC-563.2 — record the hold by id too: a refusal-log request has no pending
+                // entry to hang the question on, and the question must still reach the retry.
+                if (id)
+                    holds[id] = { ...(typeof e.question === 'string' ? { question: e.question } : {}), ts: typeof e.ts === 'string' ? e.ts : '' };
                 break;
             }
             default:
@@ -158,7 +224,7 @@ function foldQueue(lines, opts) {
     }
     const all = [...pending.values()];
     if (!opts)
-        return { pending: all, expired: [], malformedLines, decisions };
+        return { pending: all, expired: [], malformedLines, decisions, holds };
     // @implements A-SPEC-507.1 — strict excess only, and an unparseable lastTs stays ACTIVE: a
     // clockless entry must never be silently hidden by a clock it does not carry.
     const expired = [];
@@ -167,7 +233,7 @@ function foldQueue(lines, opts) {
         const last = Date.parse(p.lastTs);
         (Number.isFinite(last) && last + opts.ttlMs < opts.now ? expired : active).push(p);
     }
-    return { pending: active, expired, malformedLines, decisions };
+    return { pending: active, expired, malformedLines, decisions, holds };
 }
 /**
  * Append a request event. Fire-and-forget.
@@ -186,8 +252,27 @@ function enqueueApprovalRequest(root, req) {
         // An ungoverned directory gets no queue and no hint; it is not part of the system.
         if (!fs.existsSync(path.join(root, '.ax')))
             return false;
-        const file = path.join(root, exports.QUEUE_RELPATH);
+        // @implements A-SPEC-563.1 — kind routing: only decision-seeking kinds enter the tracked inbox;
+        // a gate refusal (shell, or any future kind — fail-safe toward a clean inbox) goes to this
+        // machine's LOCAL refusal log, raw target and all, where the approve fallback can still find it.
+        let refusalReplica = 'local';
+        try {
+            refusalReplica = (0, replica_id_1.resolveReplicaId)(root) || 'local';
+        }
+        catch { /* keep the fallback */ }
+        const file = exports.DECISION_KINDS.has(req.kind)
+            ? path.join(root, exports.QUEUE_RELPATH)
+            : path.join(root, '.ax', 'approvals', refusalsFilename(refusalReplica));
         fs.mkdirSync(path.dirname(file), { recursive: true });
+        // @implements A-SPEC-562.2 — stamp the machine. Best-effort: a resolver failure omits the field
+        // rather than losing the request, because the queue is the channel a refusal depends on.
+        let replica;
+        try {
+            replica = (0, replica_id_1.resolveReplicaId)(root);
+        }
+        catch {
+            replica = undefined;
+        }
         const event = {
             event: 'requested',
             id: approvalRequestId(req.kind, req.target),
@@ -195,6 +280,7 @@ function enqueueApprovalRequest(root, req) {
             target: req.target,
             why: req.why,
             ts: new Date().toISOString(),
+            ...(replica !== undefined && replica !== '' ? { replica } : {}),
         };
         // TYPE BEFORE WRITE, for the same reason as the read (round-7): `appendFileSync` on a FIFO with
         // no reader blocks in open(2) forever. Guarding only the reader left the GATE wedged — measured:
@@ -244,12 +330,12 @@ function readQueue(root, opts) {
         // hook, the stop hook and the MCP handlers, not just the CLI. `approve-context.ts` has guarded
         // this since the 2026-08-24 hang; the queue reader, which far more code depends on, did not.
         if (!fs.lstatSync(file).isFile())
-            return { pending: [], expired: [], malformedLines: 1, decisions: {} };
+            return { pending: [], expired: [], malformedLines: 1, decisions: {}, holds: {} };
         const raw = fs.readFileSync(file, 'utf8');
         return foldQueue(raw.split('\n'), opts);
     }
     catch {
-        return { pending: [], expired: [], malformedLines: 0, decisions: {} };
+        return { pending: [], expired: [], malformedLines: 0, decisions: {}, holds: {} };
     }
 }
 /**
@@ -271,7 +357,8 @@ function queueHint(root, req) {
     // text is read twice: printed in the operator's terminal AND carried in the agent's refusal. Raw,
     // a held request could erase the screen and paint a line claiming the operator had approved. The
     // decision surface's rule applies here too — line structure belongs to the template.
-    const held = state.pending.find((p) => p.id === id && p.hold);
+    const held = state.pending.find((p) => p.id === id && p.hold)
+        ?? (state.holds[id] ? { question: state.holds[id].question } : undefined); // @implements A-SPEC-563.2
     // Round-5: folded to terminal rows. This text is read in a terminal by the operator as well, and
     // an unfolded hint carrying 300 columns of agent-authored question wraps unpredictably around
     // whatever the gate printed before it.

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

@@ -14,6 +14,7 @@ export declare const SESSION_AUTONOMY_MARKER: readonly [".ax", "state", "autonom
 export declare function sessionAutonomyActive(root: string, now: string): boolean;
 /** Whether autonomous approval is enabled — the out-of-band env switch, OR a valid session envelope
  *  (A-SPEC-553.1). `root`/`now` are optional so env-only callers are byte-identical. */
+export declare function projectDefaultAutonomy(root: string): boolean;
 export declare function autonomousApprovalEnabled(env: NodeJS.ProcessEnv, root?: string, now?: string): boolean;
 export declare function autonomyBanner(env: NodeJS.ProcessEnv, root: string, now: string): string;
 export declare function autonomyMarkerShouldPrune(root: string, now: string): boolean;

package/dist/holmes/governance/autonomy.js

@@ -37,6 +37,7 @@ exports.SESSION_AUTONOMY_MARKER = exports.AUTONOMY_ENV = void 0;
 exports.isHighRiskPath = isHighRiskPath;
 exports.specApprovalAutonomy = specApprovalAutonomy;
 exports.sessionAutonomyActive = sessionAutonomyActive;
+exports.projectDefaultAutonomy = projectDefaultAutonomy;
 exports.autonomousApprovalEnabled = autonomousApprovalEnabled;
 exports.autonomyBanner = autonomyBanner;
 exports.autonomyMarkerShouldPrune = autonomyMarkerShouldPrune;
@@ -158,17 +159,41 @@ function sessionAutonomyActive(root, now) {
 }
 /** Whether autonomous approval is enabled — the out-of-band env switch, OR a valid session envelope
  *  (A-SPEC-553.1). `root`/`now` are optional so env-only callers are byte-identical. */
+// @implements A-SPEC-560.2 — hook-side processes never inherit the MCP server's env, so the project
+// default (persisted by `init --autonomy` into .mcp.json) must be judged by READING the file. The
+// post-ship audit's live evidence: a session with .mcp.json=1 showed no banner and never escalated —
+// the switch was real but invisible to every hook-side surface. Pure read-only judgement: .mcp.json
+// is agent-write-protected, so this opens no self-grant channel; a live read also removes the
+// restart-lag footgun (the owner's edit takes effect at the next hook run).
+function projectDefaultAutonomy(root) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(root, '.mcp.json'), 'utf8'));
+        for (const server of Object.values(parsed.mcpServers ?? {})) {
+            const v = server?.env?.[exports.AUTONOMY_ENV];
+            if (typeof v === 'string' && v !== '')
+                return true; // same truthiness convention as the env switch
+        }
+        return false;
+    }
+    catch {
+        return false; // absent / unparseable file is no signal — never a throw
+    }
+}
 function autonomousApprovalEnabled(env, root, now) {
     const v = env[exports.AUTONOMY_ENV];
     if (typeof v === 'string' && v !== '')
         return true;
+    if (root !== undefined && projectDefaultAutonomy(root))
+        return true; // @implements A-SPEC-560.2
     return root !== undefined && now !== undefined && sessionAutonomyActive(root, now);
 }
 // @implements A-SPEC-554.1 — the session-start REMINDER (the headless hook surfaces, it never decides).
 // Only ON postures get a line; OFF is silent (a permanent line is one nobody reads). Wired below.
 function autonomyBanner(env, root, now) {
     const v = env[exports.AUTONOMY_ENV];
-    if (typeof v === 'string' && v !== '') {
+    // @implements A-SPEC-560.2 — the project default is visible via env (server-side) OR .mcp.json
+    // (hook-side); either way the banner names the same posture.
+    if ((typeof v === 'string' && v !== '') || projectDefaultAutonomy(root)) {
         return '[Holmes-Kit] autonomous spec approval: ON (project default) — governance-critical, high-risk and irreversible specs still ask you.';
     }
     if (sessionAutonomyActive(root, now)) {

package/dist/holmes/guardrail/dependency-delta.d.ts

@@ -0,0 +1,3 @@
+export type DepLang = 'ts' | 'py';
+export declare function externalImportsOf(source: string, lang: DepLang): Set<string>;
+export declare function dependencyDelta(before: string, after: string, lang: DepLang): string[];