@holmes-lab/holmes-kit 0.35.1 → 0.35.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/CHANGELOG.md +72 -0
  2. package/README.md +6 -3
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve.js +9 -2
  5. package/dist/holmes/cli/doctor.js +21 -2
  6. package/dist/holmes/cli/init.d.ts +2 -0
  7. package/dist/holmes/cli/init.js +37 -1
  8. package/dist/holmes/cli/runtime-binding.d.ts +16 -0
  9. package/dist/holmes/cli/runtime-binding.js +62 -2
  10. package/dist/holmes/governance/approval-grants.d.ts +7 -0
  11. package/dist/holmes/governance/approval-grants.js +8 -2
  12. package/dist/holmes/governance/approval-queue.d.ts +5 -0
  13. package/dist/holmes/governance/approval-queue.js +14 -3
  14. package/dist/holmes/governance/autonomy.d.ts +10 -1
  15. package/dist/holmes/governance/autonomy.js +66 -14
  16. package/dist/holmes/guardrail/risk-classifier.js +32 -3
  17. package/dist/holmes/guardrail/write-verb-word.d.ts +13 -0
  18. package/dist/holmes/guardrail/write-verb-word.js +55 -0
  19. package/dist/holmes/hooks/pre-tool-use.d.ts +2 -0
  20. package/dist/holmes/hooks/pre-tool-use.js +32 -9
  21. package/dist/holmes/mcp/approval-policy.d.ts +4 -1
  22. package/dist/holmes/mcp/approval-policy.js +5 -4
  23. package/dist/holmes/mcp/elicit-approval.d.ts +0 -2
  24. package/dist/holmes/mcp/elicit-approval.js +3 -4
  25. package/dist/holmes/mcp/handlers/review-evidence.d.ts +1 -2
  26. package/dist/holmes/mcp/handlers/review-evidence.js +4 -12
  27. package/dist/holmes/mcp/handlers/spec-approval.d.ts +2 -2
  28. package/dist/holmes/mcp/handlers/spec-approval.js +18 -11
  29. package/dist/holmes/mcp/handlers.d.ts +1 -9
  30. package/dist/holmes/mcp/handlers.js +7 -7
  31. package/dist/holmes/mcp/harness-attestation.d.ts +10 -1
  32. package/dist/holmes/mcp/harness-attestation.js +70 -3
  33. package/dist/holmes/mcp/operator-recovery.js +4 -1
  34. package/dist/holmes/mcp/server.js +6 -3
  35. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,78 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.35.3] - 2026-10-05
9
+
10
+ ### Security
11
+
12
+ - **An approval prompt that is not answered is held, never approved** (A-SPEC-718.1, A-SPEC-718.2). With autonomous
13
+ approval on, an in-session approval dialog that ran out of time was recorded as an approval under the actor
14
+ `autonomous-timeout:<harness>`. This applied to exactly the acts autonomy reserves for a person: sealing a spec that
15
+ loosens a gate or is graded high-risk, and recording a critical review finding as resolved. A session left
16
+ unattended could therefore seal them with no human decision. The rule was unreachable on machines with a runtime
17
+ registry until 0.35.2 restored the in-session dialog there, and was observed live on 0.35.2. An unanswered dialog
18
+ now returns the request to the approval queue in every mode, and the dialog no longer says that silence approves.
19
+ Upgrade is recommended for every project that runs with autonomous approval on.
20
+ To audit earlier sessions, search the provenance ledger for `autonomous-timeout`: each such record is a seal or a
21
+ resolution no person decided, and can be withdrawn with `spec_unseal` or by reopening the finding.
22
+
23
+ ### Fixed
24
+
25
+ - **The request a constitution-debt refusal files is listed by `holmes-kit approve`** (A-SPEC-134.2). Since 0.35.1 a
26
+ code write refused under constitution debt printed a request id and pointed the operator at `holmes-kit approve`,
27
+ but the request went to the local refusal log — one line for every refused edit — so `approve --list` and the
28
+ interactive inbox showed nothing; only `approve --grant <id>` reached it. `code-write` is now a decision kind: the
29
+ request is written once per path to the approval queue and listed like any other. A repeated refusal of the same
30
+ path names the pending request instead of saying the request could not be saved. The request's target is the
31
+ project-relative file path, which is now written to the tracked queue file.
32
+
33
+ ## [0.35.2] - 2026-10-05
34
+
35
+ ### Security
36
+
37
+ - **A protected store path is recognised wherever it is spelled** (A-SPEC-226.1, A-SPEC-226.2). Through 0.35.1 the
38
+ gate recognised a protected `.ax` store path in a shell command only after white space, a quote, `=`, `(` or `/`.
39
+ A path spelled directly after a shell expansion, a variable, or a letter the shell removes at run time was not seen
40
+ as protected, so a removal, move or overwrite of sealed specs, the ledger or the approval queue could pass without
41
+ a refusal. The spelling now counts wherever it appears in the command, and an output redirect to a computed target
42
+ is no longer treated as a read. Found by independent review; upgrade is recommended for every governed project.
43
+ Cost: a real directory whose name ends in `.ax` and holds a child named like the store's (`backup.ax/specs`) is
44
+ judged as the store; reads still pass. Known limit, unchanged: a path assembled so that the store spelling never
45
+ appears in the command text.
46
+
47
+ ### Fixed
48
+
49
+ - **`init` and `upgrade` leave wiring that the operator runtime registry owns** (A-SPEC-752.8). On a machine with a
50
+ runtime registry, `init --agent codex` (and so `upgrade`) rewrote the user-level Codex config and hooks files that a
51
+ reviewed `runtime-binding setup` plan had written, replacing the dispatcher wiring with direct entries. A wiring
52
+ file listed in the registry's installation receipt is now left byte for byte, `--force` included, and the report
53
+ says why. Not covered: a sibling file the receipt does not list is still created.
54
+ - **In-session approval works under the runtime dispatcher** (A-SPEC-751.3). The server decides whether a harness
55
+ launched it by walking up its parent processes; the registry's `<harness>-mcp.js` dispatcher was not a known
56
+ launcher, so on a registered machine the approval dialog never opened and every approval fell to an out-of-band
57
+ command. The receipted dispatcher is now recognised. Takes effect once the new build is bound and the session is
58
+ restarted; not yet observed live.
59
+ - **A marked shell refusal says what it is** (A-SPEC-163.7). A shell command refused for mentioning the patch tool was
60
+ told an edit's `file_path` was missing. It now gets its own reason naming the plain reads that pass.
61
+ - **`git check-ignore` over the store is a read** (A-SPEC-747.1). The rest of A-SPEC-747.1 (not counting a write verb
62
+ inside another word) was withdrawn after review showed it let real writes through; those read-only commands are
63
+ still refused.
64
+
65
+ ### Changed
66
+
67
+ - **Autonomous approval covers gate changes that only tighten or only reword** (A-SPEC-532.4). An A-SPEC that declares
68
+ `gate-behavior: tightens — …` or `gate-behavior: wording — …` is sealed without the operator even when it touches
69
+ gate files; any other gate change still asks. The seal event records the declared direction.
70
+ - **A seal handed to the operator names the rule** (A-SPEC-532.3). The refusal carries the grading rule that fired, and
71
+ the pending hint also offers the resident approval surface (`approve --watch`).
72
+ - **An approval bound to its content does not expire** (A-SPEC-532.5). A grant made for a request that carries a
73
+ content digest, without `--ttl`, has no time limit: it ends when used, revoked, or when the approved content
74
+ changes. Grants without a content digest keep the 30-minute default. Not yet changed: the in-session dialog's own
75
+ time limit, and the status view still shows such a grant with a far date.
76
+ - **`doctor` and `runtime-binding setup` say more** (A-SPEC-751.2, A-SPEC-752.7). `doctor` names its own package when
77
+ the registry routes sessions to a different one; the setup report lists changed files that git tracks and how to
78
+ keep them local.
79
+
8
80
  ## [0.35.1] - 2026-10-04
9
81
 
10
82
  ### Fixed
package/README.md CHANGED
@@ -23,6 +23,9 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **The protected store is recognised however a shell command spells it** *(new in 0.35.2 — security fix, upgrade recommended)*: through 0.35.1 a path into `.ax/specs`, `.ax/ledger`, `.ax/approvals` or `.ax/state` written directly after a shell expansion, a variable, or a character the shell removes at run time was not seen as protected, so a removal, move or overwrite of governance state could pass the gate. The store spelling now counts wherever it appears in a command, and an output redirect to a computed target is not a read. Reads still pass. A directory that merely ends in `.ax` and has a child named like the store's is judged as the store. Limit: a path assembled so the spelling never appears in the command text is outside this rule.
27
+ - **An unanswered approval is held, never approved** *(new in 0.35.3 — security fix, upgrade recommended)*: with autonomous approval on, an in-session approval dialog that ran out of time used to be recorded as an approval (actor `autonomous-timeout:<harness>`) — for exactly the seals and critical-finding resolutions autonomy reserves for a person. An unanswered dialog now returns the request to the approval queue in every mode. To audit earlier sessions, search the provenance ledger for `autonomous-timeout`.
28
+ - **Approvals that fit how people work** *(new in 0.35.2)*: an approval for a request that carries the approved content's digest (a spec seal) no longer expires after 30 minutes — it stays valid until used, revoked, or the content changes (`--ttl` still bounds it; requests without a digest keep the default). With autonomous approval on, a gate change declared `gate-behavior: tightens — …` or `gate-behavior: wording — …` is sealed without the operator; any other gate change still asks, and a seal handed to the operator says which rule handed it over. On a machine with a runtime registry the in-session approval dialog is reachable again, and `init`/`upgrade` no longer replace wiring the registry owns. Not yet changed: the in-session dialog's own time limit.
26
29
  - **Separate development and consumer runtimes** *(new in 0.35.0)*: `runtime-binding setup` explicitly registers a checkout and its built package in an operator-owned registry. Normal Claude, Codex and Antigravity launches select that development package for the registered workspace; other workspaces select the configured release. Missing or conflicting bindings refuse with diagnosis instead of silently switching builds. Setup previews exact changes and requires authority for a changed installation; a validated unchanged plan needs no new grant. Normal migration preserves disabled hooks and native trust. `--activate-hooks` explicitly restores selected Holmes entries, while native trust and global disable switches still require native review. See [development runtime setup and recovery](docs/install-guide.md#development-and-consumer-runtime-binding) for the workflow and current approval limitation. Configuration readiness does not prove live three-harness enforcement.
27
30
  - **Bounded routed-hook recovery** *(new in 0.35.0)*: routed hooks share an 18-second input/selection/execution budget and allow up to 8 seconds for owned-process cleanup. Failure reports the selected runtime and diagnosis commands, retains unresolved findings, and directs an approved repair followed by retry of the original operation. Cleanup uncertainty is reported; persistent MCP sessions have no hook lifetime deadline. Literal recovery prompts and recognized installer previews are distinguished from actual shell writes without permitting command substitutions or protected output targets.
28
31
  - **Maintenance evidence survives the RED commit, and test evidence records what ran** *(new in 0.35.0)*: persisted `maintenance_analyze` evidence includes the request and explicit `changedFiles`, allowing the pre-edit advisory to cover named new files and analyses up to 20 ancestor commits back when every intervening change is covered. A passing `test_run` records the tree captured before execution, so edits made during a run remain unverified changes. The static test counter handles literals and same-file aliases, and recognizes suite skips only in code. The shared shell gate accepts read-only loops, prose literals, and commit messages mentioning `.ax`, and classifies file redirects using `>&` and `>|` as protected writes where applicable.
@@ -32,7 +35,7 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
32
35
  - 🚦 **The gate only ever denies** *(changed in 0.31.0)*: an action Holmes does not deny is left to your harness's own permission flow — Claude Code and Codex get no permission decision, Antigravity gets `ask` (or `allow` for a read inside the workspace that git does not ignore). Earlier versions answered `allow`, which Claude Code treats as "bypassing permission prompt", so anything the shell model missed ran unconfirmed. In Claude Code's default mode you now see its confirmations again, as without Holmes.
33
36
  - 🪝 **The Codex gate loads again on codex-cli 0.155** *(new in 0.31.0)*: plugin hooks were removed upstream, so `init --agent codex` wires the Holmes PreToolUse and Stop kernels into the user-level `$CODEX_HOME/hooks.json`, keeps every hook it does not own, and `--remove` takes away only its own groups. Codex runs a user hook only after you trust it once with `/hooks`; Holmes never forges that trust, and `doctor` says so instead of claiming enforcement.
34
37
  - 🧭 **The shell gate judges by identity, from where the command really runs** *(new in 0.31.0)*: wiring files, the whole `.ax` store and the files inside it are protected as shell WORDS resolved against each segment's real base — a `cd` moves the base only when it is certain to have run, an uncertain or expanded one (`cd .a?`, a link made in the same command, `cd "$X"`) leaves it unknown and the command is judged at every base it could have produced, and the base starts at the harness's own working directory (the payload `cwd`, a Codex `workdir`), not the project root. Every evaluation runs under a fail-closed deadline wall. The Codex oracle asks the installed Codex whether your config loads — locally, over copies, with plugins and every proxy closed, `sqlite_home`/`analytics`/`otel` isolated from the user copy alone, and a verdict it could not obtain labelled `approximate`. Source walkers skip nested git working trees only when git says the tree is not the project's, read regular files only, and ask git once per scan; every reader on a gate path is linear in its input.
35
- - 🪟 **Approval stays inside the agent session** *(new in 0.29.0)*: Claude Code, Codex, and Antigravity use the same capability-negotiated route. Holmes opens a direct MCP form only when that live client advertises `elicitation.form`; otherwise it exposes one sensitive, challenge-bound `approval_commit` continuation in the same agent session. The host may render its native tool confirmation, but its arrival is recorded as `host-gated`, never claimed as proof that a human answered. The server issues an opaque, memory-only intent bound to the action kind, target, subject digest, workspace and MCP run; only one matching retry can consume it. No `config.toml` value or persisted `HOLMES_APPROVAL` is authority. The `holmes-kit approve` TUI is recovery-only when a session cannot present approval. Under autonomous mode, eligible low-risk work stays automatic and an ordinary unclassified HITL request queues without interrupting the agent; only an observable direct-form timeout on high-risk or irreversible work takes the auditable `autonomous-timeout:<harness>` route. Cancel, deny, malformed and unavailable outcomes never auto-approve.
38
+ - 🪟 **Approval stays inside the agent session** *(new in 0.29.0)*: Claude Code, Codex, and Antigravity use the same capability-negotiated route. Holmes opens a direct MCP form only when that live client advertises `elicitation.form`; otherwise it exposes one sensitive, challenge-bound `approval_commit` continuation in the same agent session. The host may render its native tool confirmation, but its arrival is recorded as `host-gated`, never claimed as proof that a human answered. The server issues an opaque, memory-only intent bound to the action kind, target, subject digest, workspace and MCP run; only one matching retry can consume it. No `config.toml` value or persisted `HOLMES_APPROVAL` is authority. The `holmes-kit approve` TUI is recovery-only when a session cannot present approval. Under autonomous mode, eligible low-risk work stays automatic and an ordinary unclassified HITL request queues without interrupting the agent; high-risk or irreversible work is shown in the session and waits for an answer. Timeout, cancel, deny, malformed and unavailable outcomes never approve *(timeout: since 0.35.3)*.
36
39
  - 🧾 **A new prompt is checked against governed intent before it becomes a new spec** *(new in 0.29.0)*: `requirement_triage` reads the approved REQ/H-SPEC/A-SPEC/T-SPEC lineage, a receipt-bound current RTM graph, source and requirement-document semantic coverage, code anchors, and exact-HEAD execution evidence before recommending `fulfilled`, `existing-change`, `new`, or `ambiguous`. BM25 is always present; a verified local BGE-M3 cache and explicit Gemini opt-in add candidates and also enter the ranking score, so when lexical evidence is weak or tied a semantic match can decide which lineage leads — every such answer shows its semantic coverage, and a run that used no semantic score says `lexicalOnly: true`. A cold, stale, unreadable, failed, partial, or absent lane remains visible as ambiguity; a workspace with no semantic tier, or with transfer switched off by `HOLMES_NO_SEMANTIC_WARM`, runs **lexical-only** — it can still author a new REQ, and the answer and its evidence say `lexicalOnly: true` (set it in the environment of both your harness — its hooks spawn the background refresh — and the Holmes MCP server; a refresh recorded as suppressed also keeps triage from embedding. The switch stops automatic transfer: the background refresh embeds neither source nor requirement documents, and `requirement_triage` does not embed the prompt; tools you invoke explicitly under an opted-in cloud tier — `maintenance_analyze`, `issue_localize`, `rtm_reindex` — still embed their query or index as before). The detached refresh worker warms both versioned semantic populations under existing cloud-consent rules; a persisted v2 artifact binds prompt, workspace, HEAD, and receipt generation. New REQ creation — through `spec_create` or `spec_slice_init` — verifies that evidence at one shared MCP boundary, so no supported harness or tool can bypass it.
37
40
  - 🧭 **One governed operating contract survives every harness** *(new in 0.28.0)*: the common managed block in `AGENTS.md` carries the same No Spec, No Code rules to Claude Code, Codex CLI, and Antigravity while leaving the repository's own rules outside the block intact. `holmes-kit guidance check` names a stale or locally conflicted managed block, `guidance refresh` first plans the change and then replaces only the Holmes-owned region, and `doctor` runs the same check. An installer or upgrader cannot silently discard local guidance.
38
41
  - 🧷 **A worktree can prove which workspace the MCP server serves before an edit** *(new in 0.28.0)*: `workspace_preflight` returns the bound root/store identity and reports a foreign caller as a mismatch without registering, rebinding, or writing anything. `holmes-kit doctor --agent claude|codex|antigravity` checks each harness's local wiring prerequisites and states that preparation is not evidence of live hook enforcement. This is paired with a packaged Superpowers compatibility playbook that preserves Holmes specifications, RED/GREEN evidence, review closure, and finish/reconciliation requirements through the corresponding Superpowers workflow. Fixture and subprocess coverage preserve neighboring configuration and foreign-root isolation; live linked-worktree and paid-harness acceptance remain explicitly unverified until observed.
@@ -81,7 +84,7 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
81
84
  - 📋 **Requirements & specification governance**: strict **"No Spec, No Code"** across a 4-tier chain (`REQ ➔ H-SPEC ➔ A-SPEC ➔ T-SPEC`) with `// @implements A-SPEC-XXX` code anchors — comma-lists and every anchor in a file participate in the gate.
82
85
  - 🔴 **Inbuilt TDD — RED-first, enforced not asked** *(0.9.0)*: constitution article **ART-8** requires a recorded `red-assertion → green` sequence in the ledger, and 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. Ships observe-first (`redFirstEvidence: track`). Where superpowers *asks* for RED-first, holmes-kit *proves* it.
83
86
  - 🧱 **Deterministic gate, hardened** *(0.8.0, 0.13.0)*: shell writes are judged at the segment's **effective working directory**, the governing anchor is the whole set rather than the first match, a project is governed when **any** spec exists, and `cp`/`mv` are classified by **destination**. Every gate change ships with two consecutive clean adversarial rounds.
84
- - 🤖 **Autonomous approval — three layers, always bounded** *(0.8.0, reworked 0.13.0; session UX 0.29.0)*: a project default (`init --autonomy`) and an expiring per-session envelope let the agent seal **low-risk** specs itself under an `autonomous:<client>` actor. Ordinary unclassified HITL work queues without a form; governance-critical, high-risk or irreversible work stays in-session human-confirmed, except that an observed form timeout under that explicit posture becomes `autonomous-timeout:<client>`. Deny/cancel never do. The agent can never grant autonomy to itself, the posture is surfaced at every session start, and off is byte-identical to a human-gated project.
87
+ - 🤖 **Autonomous approval — three layers, always bounded** *(0.8.0, reworked 0.13.0; session UX 0.29.0)*: a project default (`init --autonomy`) and an expiring per-session envelope let the agent seal **low-risk** specs itself under an `autonomous:<client>` actor. Ordinary unclassified HITL work queues without a form; governance-critical, high-risk or irreversible work stays in-session human-confirmed; a form that is not answered returns to the approval queue *(since 0.35.3 — it was recorded as an approval before)*. The agent can never grant autonomy to itself, the posture is surfaced at every session start, and off is byte-identical to a human-gated project.
85
88
  - 🧭 **Compatibility and evolution gates** *(0.14.0, 0.15.0)*: a new A-SPEC seals only with `harness_impact:` and `os_impact:` declared and machine-cross-checked against Files-to-Touch; separately, a changed in-scope source that **newly introduces an external dependency** raises a spec-reappraisal — a warning when manual, a queued item under autonomy, never a blocked turn.
86
89
  - 🚢 **Release autonomy + docs-currency gate** *(0.13.0, machine-checked in 0.23.2)*: `npm publish` stays **human-approved by default** while a deterministic classifier lets a low-risk release self-publish under the ledger; a major bump or any gate-behavior/security/architecture spec forces HITL. The publish gate refuses a release whose docs never caught up — a stale doc is a false claim.
87
90
  - 🧠 **3-tier semantic layer** *(local preparation default in 0.29.0)*: BGE-M3 is prepared and verified locally during a normal npm installation (zero repository-text egress); `HOLMES_SKIP_MODEL_INSTALL=1` is the explicit opt-out. `cloud` remains the opt-in `gemini-embedding-001` tier. Measured on 305 traceability cases: recall 0.486 → 0.667 → **0.887**; on lexical-zero requests 0% → 52% → **92%**. Surfaced additively, never as a hard filter.
@@ -89,7 +92,7 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
89
92
  - 🐞 **Causal defect localization & CPG** *(equalized in 0.5–0.7)*: AST code property graph (CFG/DDG/CDG) and dataflow taint reachability across 7 languages — **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).
90
93
  - 📏 **Measured, not claimed** *(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.
91
94
  - 📊 **RTM dashboard & heatmaps** *(0.12.0–0.12.1)*: `holmes-kit serve` renders a real 2D coverage matrix (requirements × pipeline stages) with an honesty census, drills into a symbol's **CFG as a layered DAG with PDG colour overlays**, and a non-CFG language is named rather than faked. Standalone HTML/SVG reports (`generateRtmHeatmap`) cover spec coverage and taint reachability.
92
- - 🔔 **Approval UX** *(0.3.1; inbox split 0.15.0; in-session recovery 0.29.0)*: the agent-session UI is primary; the tracked queue is the fallback when the client cannot present it. A form timeout is distinguished from cancel/unavailable, and only autonomous mode may make that observed timeout a one-shot auto-approval. The queue holds **decision-seeking requests only** — plain gate refusals live in a local per-machine log (raw commands never leave the machine), after 1,404 single-shot refusals were measured burying a 2-item inbox.
95
+ - 🔔 **Approval UX** *(0.3.1; inbox split 0.15.0; in-session recovery 0.29.0)*: the agent-session UI is primary; the tracked queue is the fallback when the client cannot present it. A form timeout is distinguished from cancel/unavailable, and in every mode it returns the request to the queue. The queue holds **decision-seeking requests only** — plain gate refusals live in a local per-machine log (raw commands never leave the machine), after 1,404 single-shot refusals were measured burying a 2-item inbox.
93
96
  - ⬆️ **Zero-config upgrades & session banner** *(0.8.0–0.12.2)*: `holmes-kit upgrade` re-pins **every** recorded workspace in one command (`--dry-run`/`--yes`), and every session start states the version, the governance rule and any newer published version — from every harness's MCP startup, not just Claude's. The write stays your explicit choice, never a silent auto-install.
94
97
  - 🧰 **Governance UX tools** *(0.10.0)*: `spec_unseal` (return a sealed spec to editable `draft` in one act, out-of-band approval required), `approval_status` and `ledger_timeline` for read-only observability, and a structured `conflict` on optimistic-concurrency refusal.
95
98
  - 🚦 **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 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.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 68b21a0e-mutvc7i3
1
+ 39b711d0-muupj0n0
@@ -47,7 +47,7 @@ exports.decisionDetail = decisionDetail;
47
47
  exports.renderRefusals = renderRefusals;
48
48
  exports.renderNonTtyHint = renderNonTtyHint;
49
49
  exports.runInteractive = runInteractive;
50
- // @implements A-SPEC-246, A-SPEC-626
50
+ // @implements A-SPEC-246, A-SPEC-626, A-SPEC-532.5
51
51
  // @implements A-SPEC-549.4 — renderPending and renderNonTtyHint in this file are the English CLI
52
52
  // surface the Hangul-absence guard reads.
53
53
  const execution_context_1 = require("../project/execution-context");
@@ -175,6 +175,11 @@ function grantRequest(root, id, opts) {
175
175
  return { ok: false, reason: `TTL must be an integer number of minutes in 1..${MAX_TTL_MINUTES} — received: ${(0, screen_safe_1.rowField)(String(ttl), 40)}` };
176
176
  }
177
177
  const { entry } = findPending(root, id);
178
+ // @implements A-SPEC-532.5 — owner decision 2026-10-05: a grant bound to the content the operator read does not
179
+ // expire by time; it ends when it is used, revoked, or the content changes (the subject no longer matches). Measured
180
+ // 2026-10-04: five seal grants expired unused after 30 minutes. An explicit --ttl still bounds it; a request without
181
+ // a subject keeps the default, because there the clock is all that stands between the decision and a changed act.
182
+ const untilUsed = opts.ttlMinutes === undefined && typeof entry?.subject === 'string' && entry.subject !== '';
178
183
  if (!entry)
179
184
  return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)} — check with ${(0, npx_bin_1.npxBin)()} holmes-kit approve --list` };
180
185
  if (!recordIsSelfConsistent(entry))
@@ -184,7 +189,7 @@ function grantRequest(root, id, opts) {
184
189
  // different id, so the lookup misses; the SAME id can only carry the same subject. An unexercised
185
190
  // second guard is not defence in depth, it is a line nobody can prove still works (round-3
186
191
  // mutation test: neutering it left the suite green).
187
- const expires = new Date(Date.now() + ttl * 60_000).toISOString();
192
+ const expires = untilUsed ? approval_grants_1.GRANT_NO_EXPIRY : new Date(Date.now() + ttl * 60_000).toISOString();
188
193
  // @implements A-SPEC-649 — the grant names WHERE it was minted and WHAT the operator read, so a
189
194
  // copy in another clone and a seal of changed content are refused by name (measured 2026-09-14:
190
195
  // both were accepted). A legacy workspace has no id to name; a request filed without a subject
@@ -213,6 +218,8 @@ function grantRequest(root, id, opts) {
213
218
  // "the grant is for what the human saw" (round-3) in the scope layer.
214
219
  scope: [{ kind: entry.kind, pattern: entry.target, exact: true }],
215
220
  expires,
221
+ // Stated, never implied by a missing field: a file that merely lacks an expiry is not a grant (isNarrow).
222
+ ...(untilUsed ? { lifetime: 'until-used' } : {}),
216
223
  nonce: id,
217
224
  };
218
225
  // @implements A-SPEC-262.1 — AUDIT AND AUTHORITY STAND OR FALL TOGETHER.
@@ -67,7 +67,7 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
67
67
  exports.semanticCoverageCheck = semanticCoverageCheck;
68
68
  exports.semanticTierVerdict = semanticTierVerdict;
69
69
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
70
- // @implements A-SPEC-733, A-SPEC-727, A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751
70
+ // @implements A-SPEC-733, A-SPEC-727, A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2
71
71
  // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712
72
72
  const doctor_guidance_1 = require("./doctor-guidance");
73
73
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
@@ -717,7 +717,26 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
717
717
  mcp: (h, e) => ['claude', 'codex', 'antigravity'].includes(h) && e?.command === process.execPath
718
718
  && Array.isArray(e.args) && e.args.length === 1 && e.args[0] === script(h, 'mcp') };
719
719
  }
720
- add('runtime binding', report.conflicts.length ? 'FAIL' : 'WARN', `${s.mode}: workspace=${s.workspaceRoot}; package=${s.packageRoot}; build=${s.buildId}; specs=${s.specsRoot}; live activation unverified`
720
+ // @implements A-SPEC-751.2 — the routed package and the package doctor checks can be two packages (measured: a
721
+ // local 0.35.1 install beside a registry routing to the global 0.34.0); the line says so when they are.
722
+ const real = (p) => { try {
723
+ return fs.realpathSync.native(p);
724
+ }
725
+ catch {
726
+ return null;
727
+ } };
728
+ const routedReal = real(s.packageRoot);
729
+ const ownReal = real(packageRoot);
730
+ let own = '';
731
+ if (routedReal === null || ownReal === null || routedReal !== ownReal) {
732
+ let ownBuild = 'unknown';
733
+ try {
734
+ ownBuild = fs.readFileSync(path.join(packageRoot, 'dist/.build-id'), 'utf8').trim() || 'unknown';
735
+ }
736
+ catch { /* no build id */ }
737
+ own = `; doctor runs from ${packageRoot} (build ${ownBuild}); sessions routed by this registry load the package named first`;
738
+ }
739
+ add('runtime binding', report.conflicts.length ? 'FAIL' : 'WARN', `${s.mode}: workspace=${s.workspaceRoot}; package=${s.packageRoot}; build=${s.buildId}${own}; specs=${s.specsRoot}; live activation unverified`
721
740
  + (report.conflicts.length ? `; ${report.conflicts.join('; ')}` : ''), 'Use runtime-binding status and setup --dry-run to inspect routed wiring. Native hook trust and enable state remain operator-controlled.');
722
741
  }
723
742
  catch (e) {
@@ -46,6 +46,8 @@ export interface InitOptions {
46
46
  }) => CodexVerdict;
47
47
  autonomy?: boolean;
48
48
  autonomyInteractive?: boolean;
49
+ /** @implements A-SPEC-752.8 — test override for the operator runtime registry whose receipt names owned wiring. */
50
+ runtimeRegistryPath?: string;
49
51
  }
50
52
  export interface FileChange {
51
53
  path: string;
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.settingsPathOf = exports.MATCHERS = exports.SERVER_NAME = void 0;
37
37
  exports.buildHookPlan = buildHookPlan;
38
38
  exports.runInit = runInit;
39
- // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738
39
+ // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8
40
40
  // @implements A-SPEC-709
41
41
  // @implements A-SPEC-340
42
42
  // @implements A-SPEC-100.2
@@ -61,6 +61,7 @@ const governed_precondition_1 = require("./governed-precondition");
61
61
  const risk_gate_1 = require("../guardrail/risk-gate");
62
62
  const bounded_io_1 = require("../project/bounded-io");
63
63
  const claude_switches_1 = require("./claude-switches");
64
+ const runtime_binding_1 = require("./runtime-binding");
64
65
  /**
65
66
  * `holmes-kit init` — wire holmes-kit into a TARGET project (the I/O half; all merge logic is pure
66
67
  * and lives in settings-merge.ts / gitignore-merge.ts).
@@ -1154,6 +1155,41 @@ function runInitUnguarded(opts) {
1154
1155
  if (guidance && !changes.some(c => c.path === guidanceFile)) {
1155
1156
  changes.push({ path: guidanceFile, before: guidance.before, after: guidance.after });
1156
1157
  }
1158
+ // @implements A-SPEC-752.8 — a wiring file the operator runtime registry's receipt lists is left byte for byte: its
1159
+ // content is a reviewed plan's, and init rewrote it thirteen seconds after a global install (measured 2026-10-04:
1160
+ // the user-level Codex files went back to direct release entries and every workspace's status reported a conflict).
1161
+ // `--force` does not override; a claim about a file that is not written is withdrawn, as for a failed write below.
1162
+ {
1163
+ const leftOwned = [];
1164
+ for (let i = changes.length - 1; i >= 0; i--) {
1165
+ const own = (0, runtime_binding_1.registryWiringOwnership)(changes[i].path, opts.runtimeRegistryPath);
1166
+ if (own.owned) {
1167
+ leftOwned.unshift({ path: changes[i].path, matches: own.matches });
1168
+ changes.splice(i, 1);
1169
+ }
1170
+ }
1171
+ for (let i = removals.length - 1; i >= 0; i--) {
1172
+ const own = (0, runtime_binding_1.registryWiringOwnership)(removals[i], opts.runtimeRegistryPath);
1173
+ if (own.owned) {
1174
+ leftOwned.unshift({ path: removals[i], matches: own.matches });
1175
+ removals.splice(i, 1);
1176
+ }
1177
+ }
1178
+ if (leftOwned.length > 0) {
1179
+ const names = leftOwned.map((l) => l.path);
1180
+ const codexLeft = names.some((p) => /[\\/]\.codex[\\/]/.test(p) || p === (opts.codexConfigPath ?? '') || p === (opts.codexHooksPath ?? ''));
1181
+ const claims = (m) => (names.some((p) => m.includes(p)) && /wired|active|repaired|written/.test(m))
1182
+ || (codexLeft && /pre-tool gate runs from the user-level Codex hooks file|codex: the gate is enforced \(hooks wired\)|codex: tools and instructions wired/.test(m));
1183
+ for (let i = messages.length - 1; i >= 0; i--)
1184
+ if (claims(messages[i]))
1185
+ messages.splice(i, 1);
1186
+ for (const l of leftOwned) {
1187
+ messages.push(l.matches
1188
+ ? `${l.path}: left as it is — owned by the operator runtime registry. Preview a change to it with: holmes-kit runtime-binding setup --dry-run`
1189
+ : `${l.path}: left as it is — owned by the operator runtime registry, but the registry's receipt and the file disagree. Inspect with: holmes-kit runtime-binding status, then preview with: holmes-kit runtime-binding setup --dry-run`);
1190
+ }
1191
+ }
1192
+ }
1157
1193
  // @implements A-SPEC-251.1 (round 27) — no write, removal or link goes through a link the repository carries out of the
1158
1194
  // target: a cloned repo's `.agents -> ../../.codex` made the default init merge Antigravity's hooks into
1159
1195
  // `~/.codex/hooks.json` and turn the Codex gate off everywhere (measured). A user's own (untracked) link is followed
@@ -21,9 +21,25 @@ export declare function runtimeHookCommand(registryPath: string, harness: Runtim
21
21
  * A list of keys to keep missed ones that switch Holmes off, so the view names what it drops (A-SPEC-752.6).
22
22
  */
23
23
  export declare function wiringViewOf(file: string, content: string): string;
24
+ /**
25
+ * @implements A-SPEC-752.8 — whether the installation receipt beside the operator registry lists `file`, and whether the
26
+ * file still matches it. Measured 2026-10-04: init rewrote the user-level Codex files a setup plan had written, because
27
+ * nothing outside this module read the receipt. No registry, no receipt, or a receipt that cannot be read owns nothing.
28
+ */
29
+ export declare function registryWiringOwnership(file: string, registryPath?: string): {
30
+ owned: boolean;
31
+ matches: boolean;
32
+ };
33
+ export declare function registryOwnedWiring(file: string, registryPath?: string): boolean;
24
34
  export declare function runtimeBindingStatus(registryPath: string, workspace: string): {
25
35
  selection: import("../runtime/binding").RuntimeSelection;
26
36
  conflicts: string[];
27
37
  activation: "unverified";
28
38
  };
29
39
  export declare function runRuntimeBinding(opts: RuntimeBindingOptions): unknown;
40
+ /**
41
+ * @implements A-SPEC-752.7 — which of `files` lie inside `root` and are tracked by git, relative to `root` and sorted.
42
+ * Measured 2026-10-04: setup rewrote committed wiring files with machine paths and the release check was the first to
43
+ * say so. No work tree, no git, a timeout or a failure all read as "none": this report never fails for it.
44
+ */
45
+ export declare function trackedWorkspacePaths(root: string, files: readonly string[], env?: NodeJS.ProcessEnv): string[];
@@ -36,13 +36,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.defaultRuntimeRegistry = void 0;
37
37
  exports.runtimeHookCommand = runtimeHookCommand;
38
38
  exports.wiringViewOf = wiringViewOf;
39
+ exports.registryWiringOwnership = registryWiringOwnership;
40
+ exports.registryOwnedWiring = registryOwnedWiring;
39
41
  exports.runtimeBindingStatus = runtimeBindingStatus;
40
42
  exports.runRuntimeBinding = runRuntimeBinding;
41
- // @implements A-SPEC-751, A-SPEC-752
43
+ exports.trackedWorkspacePaths = trackedWorkspacePaths;
44
+ // @implements A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8
42
45
  const fs = __importStar(require("node:fs"));
43
46
  const os = __importStar(require("node:os"));
44
47
  const path = __importStar(require("node:path"));
45
48
  const node_crypto_1 = require("node:crypto");
49
+ const bounded_io_1 = require("../project/bounded-io");
46
50
  const smol_toml_1 = require("smol-toml");
47
51
  const binding_1 = require("../runtime/binding");
48
52
  const runtime_binding_approval_1 = require("./runtime-binding-approval");
@@ -125,6 +129,38 @@ function wiringViewOf(file, content) {
125
129
  const { model: _model, ...rest } = doc;
126
130
  return JSON.stringify(rest);
127
131
  }
132
+ /**
133
+ * @implements A-SPEC-752.8 — whether the installation receipt beside the operator registry lists `file`, and whether the
134
+ * file still matches it. Measured 2026-10-04: init rewrote the user-level Codex files a setup plan had written, because
135
+ * nothing outside this module read the receipt. No registry, no receipt, or a receipt that cannot be read owns nothing.
136
+ */
137
+ function registryWiringOwnership(file, registryPath = (0, exports.defaultRuntimeRegistry)()) {
138
+ const none = { owned: false, matches: false };
139
+ try {
140
+ const manifest = readOptional(path.join(path.dirname(registryPath), 'installation.json'));
141
+ if (manifest === null)
142
+ return none;
143
+ const rows = JSON.parse(manifest).files;
144
+ if (!Array.isArray(rows))
145
+ return none;
146
+ const wanted = canonicalFuture(file);
147
+ for (const row of rows) {
148
+ if (!object(row) || typeof row.path !== 'string' || typeof row.digest !== 'string')
149
+ return none;
150
+ if (row.path !== wanted && row.path !== file)
151
+ continue;
152
+ const current = readOptional(row.path);
153
+ return { owned: true, matches: current !== null && (digest(wiringViewOf(row.path, current)) === row.digest || digest(current) === row.digest) };
154
+ }
155
+ return none;
156
+ }
157
+ catch {
158
+ return none;
159
+ }
160
+ }
161
+ function registryOwnedWiring(file, registryPath) {
162
+ return registryWiringOwnership(file, registryPath).owned;
163
+ }
128
164
  function runtimeBindingStatus(registryPath, workspace) {
129
165
  const selection = (0, binding_1.selectRuntime)((0, binding_1.readRuntimeRegistry)(registryPath), { cwd: workspace });
130
166
  const manifest = readOptional(path.join(path.dirname(registryPath), 'installation.json'));
@@ -566,5 +602,29 @@ function runRuntimeBinding(opts) {
566
602
  }
567
603
  });
568
604
  }
569
- return { dryRun: opts.dryRun, changes, conflicts, selection, planDigest, activation: 'unverified' };
605
+ // @implements A-SPEC-752.7 — outside the plan digest: what git tracks is not part of the reviewed wiring plan.
606
+ const trackedChanges = trackedWorkspacePaths(root, changes.map((c) => c.path));
607
+ return { dryRun: opts.dryRun, changes, conflicts, selection, planDigest, activation: 'unverified', trackedChanges,
608
+ ...(trackedChanges.length ? { trackedAdvice: `${trackedChanges.length} changed file(s) are tracked by git and now hold this machine's paths; do not commit them — keep them local with: git update-index --skip-worktree ${trackedChanges.join(' ')} (a release check otherwise sees a dirty tree)` } : {}) };
609
+ }
610
+ /**
611
+ * @implements A-SPEC-752.7 — which of `files` lie inside `root` and are tracked by git, relative to `root` and sorted.
612
+ * Measured 2026-10-04: setup rewrote committed wiring files with machine paths and the release check was the first to
613
+ * say so. No work tree, no git, a timeout or a failure all read as "none": this report never fails for it.
614
+ */
615
+ function trackedWorkspacePaths(root, files, env = process.env) {
616
+ const rel = files.filter((f) => (0, binding_1.inside)(root, f) && f !== root).map((f) => path.relative(root, f));
617
+ if (rel.length === 0)
618
+ return [];
619
+ try {
620
+ // The shared bounded child (A-SPEC-734): a timeout, a large buffer, and the blocked-root memory.
621
+ const r = (0, bounded_io_1.gitOnce)(root, ['-C', root, 'ls-files', '-z', '--', ...rel], 'worktree', { env });
622
+ if (r.error || r.status !== 0 || typeof r.stdout !== 'string')
623
+ return [];
624
+ const wanted = new Set(rel.map((p) => p.split(path.sep).join('/')));
625
+ return r.stdout.split('\0').filter((p) => wanted.has(p)).sort();
626
+ }
627
+ catch {
628
+ return [];
629
+ }
570
630
  }
@@ -43,7 +43,14 @@ export type BoundGrant = Approval & {
43
43
  workspace?: string;
44
44
  subject?: string;
45
45
  requestedBy?: string;
46
+ lifetime?: 'until-used';
46
47
  };
48
+ /**
49
+ * @implements A-SPEC-532.5 — the `expires` a subject-bound grant carries: it keeps the field every grant must have
50
+ * (a grant is narrow: scope, expires, nonce) and the comparison every consumer already makes, while the grant's
51
+ * `lifetime: 'until-used'` says in words that no time limit was meant.
52
+ */
53
+ export declare const GRANT_NO_EXPIRY = "9999-12-31T23:59:59.999Z";
47
54
  export type BindingRefusal = 'foreign-workspace' | 'stale-subject';
48
55
  /** @implements A-SPEC-649 — the grants that WOULD cover this action but are refused by their binding, by name. */
49
56
  export declare function refusedGrantReasons(root: string, action: {
@@ -33,13 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.GRANTS_RELDIR = void 0;
36
+ exports.GRANT_NO_EXPIRY = exports.GRANTS_RELDIR = void 0;
37
37
  exports.readGrants = readGrants;
38
38
  exports.refusedGrantReasons = refusedGrantReasons;
39
39
  exports.pickCoveringGrant = pickCoveringGrant;
40
40
  exports.resolveApproval = resolveApproval;
41
41
  exports.consumeGrantFile = consumeGrantFile;
42
- // @implements A-SPEC-245
42
+ // @implements A-SPEC-245, A-SPEC-532.5
43
43
  const fs = __importStar(require("node:fs"));
44
44
  const path = __importStar(require("node:path"));
45
45
  const risk_gate_1 = require("../guardrail/risk-gate");
@@ -105,6 +105,12 @@ function readGrants(root) {
105
105
  }
106
106
  return { grants, ignored };
107
107
  }
108
+ /**
109
+ * @implements A-SPEC-532.5 — the `expires` a subject-bound grant carries: it keeps the field every grant must have
110
+ * (a grant is narrow: scope, expires, nonce) and the comparison every consumer already makes, while the grant's
111
+ * `lifetime: 'until-used'` says in words that no time limit was meant.
112
+ */
113
+ exports.GRANT_NO_EXPIRY = '9999-12-31T23:59:59.999Z';
108
114
  /** The current workspace id, or undefined for a legacy workspace / an unreadable identity. */
109
115
  function currentWorkspaceId(root) {
110
116
  try {
@@ -20,6 +20,11 @@ import { ExecutionContext } from '../project/execution-context';
20
20
  */
21
21
  export declare const QUEUE_RELPATH: string;
22
22
  export declare const DECISION_KINDS: ReadonlySet<string>;
23
+ /**
24
+ * The line a refusal ends with to name its pending request and the operator command.
25
+ * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
26
+ */
27
+ export declare function pendingRequestLine(id: string): string;
23
28
  export interface RefusalRecord {
24
29
  event: 'requested';
25
30
  id: string;
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.DECISION_KINDS = exports.QUEUE_RELPATH = void 0;
37
+ exports.pendingRequestLine = pendingRequestLine;
37
38
  exports.refusalsFilename = refusalsFilename;
38
39
  exports.isRefusalsFilename = isRefusalsFilename;
39
40
  exports.readRefusals = readRefusals;
@@ -47,7 +48,7 @@ exports.queueHint = queueHint;
47
48
  exports.grantableRequests = grantableRequests;
48
49
  exports.openOccurrences = openOccurrences;
49
50
  exports.asPendingRequest = asPendingRequest;
50
- // @implements A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754
51
+ // @implements A-SPEC-134.2, A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754
51
52
  const execution_context_1 = require("../project/execution-context");
52
53
  const root_1 = require("../project/root");
53
54
  const node_crypto_1 = require("node:crypto");
@@ -85,9 +86,19 @@ exports.QUEUE_RELPATH = path.join('.ax', 'approvals', 'queue.jsonl');
85
86
  // human, review_record's refusal points that human at `holmes-kit approve`, and without this entry the
86
87
  // request went to the refusal log so the inbox stayed empty (measured 2026-09-14 on Windows: two
87
88
  // expired session dialogs, then `approve --list` answered "No requests awaiting approval").
89
+ // @implements A-SPEC-134.2 — `code-write` is a decision too: the constitution-debt refusal points the operator at
90
+ // `holmes-kit approve`, and its target is a project-relative path, not a command line, so the reason shell
91
+ // requests stay out of the tracked queue does not apply.
88
92
  exports.DECISION_KINDS = new Set([
89
- 'spec-approve', 'config-write', 'autonomy-grant', 'spec-reappraisal', 'review-resolve', 'governance-wiring',
93
+ 'spec-approve', 'config-write', 'autonomy-grant', 'spec-reappraisal', 'review-resolve', 'governance-wiring', 'code-write',
90
94
  ]);
95
+ /**
96
+ * The line a refusal ends with to name its pending request and the operator command.
97
+ * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
98
+ */
99
+ function pendingRequestLine(id) {
100
+ return `\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
101
+ }
91
102
  const REFUSALS_FILE_RE = /^refusals\.([^.]+)\.jsonl$/;
92
103
  function refusalsFilename(replica) {
93
104
  return `refusals.${replica}.jsonl`;
@@ -508,7 +519,7 @@ function queueHint(root, req, opts) {
508
519
  // @implements A-SPEC-564.2 — the hint is composed BEFORE the enqueue so the refusal record can
509
520
  // carry its own feedback cost: reasonBytes = the caller's base reason + this hint, i.e. the text
510
521
  // that actually re-enters the conversation. Observation only — nothing reads it on a gate path.
511
- const hint = denialLine + (opts?.pendingHint ? opts.pendingHint(id) : `\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`);
522
+ const hint = denialLine + (opts?.pendingHint ? opts.pendingHint(id) : pendingRequestLine(id));
512
523
  return enqueueApprovalRequest(root, { ...req, reasonBytes: (opts?.baseReasonBytes ?? 0) + hint.length })
513
524
  ? hint
514
525
  : denialLine;
@@ -26,13 +26,22 @@ export declare function descendantAspecs(spec: Spec, all: Spec[]): Spec[];
26
26
  * or no A-SPEC at all (unknown scope) → human. The two-argument call keeps the old answer.
27
27
  */
28
28
  export declare function specApprovalAutonomy(spec: Spec, resolveParent: (id: string) => Spec | null, descendants?: Spec[]): ApprovalAutonomy;
29
+ export declare function declaredGateDirection(spec: Spec): 'tightens' | 'wording' | null;
30
+ /** @implements A-SPEC-532.3 — one plain clause per rule name, for the refusal a person reads. */
31
+ export declare function autonomyRuleMeaning(rule: string): string;
32
+ /**
33
+ * @implements A-SPEC-532.3 — the first rule that hands this seal to the owner, or null when none does. Measured
34
+ * 2026-10-04: two gate specs were refused with the generic out-of-band sentence and neither the session nor the owner
35
+ * could tell which rule had fired.
36
+ */
37
+ export declare function specApprovalAutonomyReason(spec: Spec, resolveParent: (id: string) => Spec | null, descendants?: Spec[]): string | null;
29
38
  /**
30
39
  * Whether an otherwise HITL-classed approval is one of the exceptional cases that must still be
31
40
  * presented in-session while autonomous mode is enabled. This is intentionally narrower than
32
41
  * `specApprovalAutonomy(...) === 'hitl'`: an upstream REQ/H-SPEC with no implemented A-SPEC is
33
42
  * not identified as high-risk yet, so autonomous mode queues it without interrupting the agent.
34
43
  * Architecture, an explicitly high-risk A-SPEC, and an upstream document leading to either remain
35
- * visible to a human; their direct-form timeout is handled separately as an autonomous timeout.
44
+ * visible to a human; a prompt that is not answered is held (A-SPEC-718.1).
36
45
  */
37
46
  export declare function requiresAutonomousApprovalPrompt(spec: Spec, descendants?: Spec[]): boolean;
38
47
  export declare const SESSION_AUTONOMY_MARKER: readonly [".ax", "state", "autonomy.json"];