@holmes-lab/holmes-kit 0.29.0 → 0.31.0

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 (169) hide show
  1. package/CHANGELOG.md +556 -0
  2. package/README.md +15 -5
  3. package/bin/holmes-hook-antigravity.js +4 -0
  4. package/bin/holmes-kit.js +4 -0
  5. package/bin/holmes-pre-push.js +3 -0
  6. package/bin/holmes-stop-antigravity.js +4 -0
  7. package/dist/.build-id +1 -1
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  9. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  10. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  11. package/dist/holmes/cli/agents-guidance.js +11 -8
  12. package/dist/holmes/cli/agents.d.ts +41 -0
  13. package/dist/holmes/cli/agents.js +382 -2
  14. package/dist/holmes/cli/attest.d.ts +2 -0
  15. package/dist/holmes/cli/attest.js +66 -15
  16. package/dist/holmes/cli/ci-gate.js +16 -1
  17. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  18. package/dist/holmes/cli/claude-switches.js +967 -0
  19. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  20. package/dist/holmes/cli/codex-hooks.js +802 -0
  21. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  22. package/dist/holmes/cli/codex-oracle.js +1245 -0
  23. package/dist/holmes/cli/codex-toml.d.ts +58 -1
  24. package/dist/holmes/cli/codex-toml.js +456 -40
  25. package/dist/holmes/cli/doctor.d.ts +108 -8
  26. package/dist/holmes/cli/doctor.js +1408 -98
  27. package/dist/holmes/cli/index.js +23 -11
  28. package/dist/holmes/cli/init.d.ts +13 -0
  29. package/dist/holmes/cli/init.js +749 -77
  30. package/dist/holmes/cli/interactive-prompt.js +2 -2
  31. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  32. package/dist/holmes/cli/mcp-launcher.js +189 -6
  33. package/dist/holmes/cli/mcp-version.js +13 -2
  34. package/dist/holmes/cli/settings-merge.js +8 -2
  35. package/dist/holmes/cli/upgrade.d.ts +13 -0
  36. package/dist/holmes/cli/upgrade.js +116 -23
  37. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  38. package/dist/holmes/cli/workspace-scope.js +375 -0
  39. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  40. package/dist/holmes/cli/worktree-readiness.js +17 -3
  41. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  42. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  43. package/dist/holmes/cpg/cycle-detect.js +2 -1
  44. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  45. package/dist/holmes/cpg/required-calls.js +8 -1
  46. package/dist/holmes/governance/autonomy.d.ts +9 -0
  47. package/dist/holmes/governance/autonomy.js +28 -1
  48. package/dist/holmes/governance/constitution-debt.js +3 -2
  49. package/dist/holmes/governance/constitution.js +15 -3
  50. package/dist/holmes/governance/provenance-chain.js +3 -2
  51. package/dist/holmes/governance/push-gate-runner.js +4 -3
  52. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  53. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  54. package/dist/holmes/guardrail/linear-match.js +256 -0
  55. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  56. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  57. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  58. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  59. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  60. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  61. package/dist/holmes/guardrail/shell-words.js +1720 -0
  62. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  63. package/dist/holmes/guardrail/write-target.js +2379 -87
  64. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  65. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  66. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  67. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  68. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  69. package/dist/holmes/hooks/rtm-refresh-child.js +102 -18
  70. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  71. package/dist/holmes/hooks/rtm-refresh.js +60 -15
  72. package/dist/holmes/hooks/session-start.d.ts +10 -0
  73. package/dist/holmes/hooks/session-start.js +31 -7
  74. package/dist/holmes/hooks/stop.d.ts +2 -1
  75. package/dist/holmes/hooks/stop.js +197 -91
  76. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  77. package/dist/holmes/mcp/approval-adapters.js +21 -0
  78. package/dist/holmes/mcp/approval-commit.d.ts +20 -0
  79. package/dist/holmes/mcp/approval-commit.js +108 -0
  80. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  81. package/dist/holmes/mcp/approval-intent.js +67 -0
  82. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  83. package/dist/holmes/mcp/approval-policy.js +18 -0
  84. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  85. package/dist/holmes/mcp/elicit-approval.js +8 -3
  86. package/dist/holmes/mcp/handlers/graph-operations.d.ts +17 -1
  87. package/dist/holmes/mcp/handlers/graph-operations.js +15 -6
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  89. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  90. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  91. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  92. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +26 -0
  93. package/dist/holmes/mcp/handlers/requirement-triage.js +48 -11
  94. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  95. package/dist/holmes/mcp/handlers/review-evidence.js +15 -5
  96. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +18 -0
  97. package/dist/holmes/mcp/handlers/slice-orchestration.js +122 -16
  98. package/dist/holmes/mcp/handlers/spec-approval.d.ts +35 -2
  99. package/dist/holmes/mcp/handlers/spec-approval.js +175 -57
  100. package/dist/holmes/mcp/handlers/spec-authoring.js +36 -3
  101. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  102. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  103. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  104. package/dist/holmes/mcp/handlers.d.ts +126 -8
  105. package/dist/holmes/mcp/handlers.js +109 -18
  106. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  107. package/dist/holmes/mcp/harness-attestation.js +179 -0
  108. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  109. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  110. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +72 -2
  111. package/dist/holmes/mcp/requirement-triage-evidence.js +227 -1
  112. package/dist/holmes/mcp/server.js +24 -3
  113. package/dist/holmes/mcp/supervisor.js +7 -3
  114. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  115. package/dist/holmes/mcp/tool-schemas.js +54 -7
  116. package/dist/holmes/mcp/validate-args.js +12 -0
  117. package/dist/holmes/project/bounded-io.d.ts +102 -0
  118. package/dist/holmes/project/bounded-io.js +212 -0
  119. package/dist/holmes/project/change-source.js +3 -1
  120. package/dist/holmes/project/ci-runs.js +3 -2
  121. package/dist/holmes/project/ignore.d.ts +31 -2
  122. package/dist/holmes/project/ignore.js +409 -50
  123. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  124. package/dist/holmes/project/regular-file-guard.js +149 -0
  125. package/dist/holmes/project/root.js +12 -3
  126. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  127. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  128. package/dist/holmes/reverse/anchor.js +4 -3
  129. package/dist/holmes/reverse/scan.js +6 -2
  130. package/dist/holmes/review/commit-text.js +3 -2
  131. package/dist/holmes/review/condition-hunk-replay.d.ts +12 -0
  132. package/dist/holmes/review/condition-hunk-replay.js +13 -2
  133. package/dist/holmes/review/condition-hunk-resolution.js +59 -8
  134. package/dist/holmes/review/failed-test-names.js +13 -10
  135. package/dist/holmes/review/findings.js +3 -1
  136. package/dist/holmes/review/kills-check.js +6 -1
  137. package/dist/holmes/review/point-in-time-replay.js +5 -4
  138. package/dist/holmes/review/replay-corpus.js +5 -4
  139. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  140. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  141. package/dist/holmes/review/run-replay.js +3 -2
  142. package/dist/holmes/review/scope.js +6 -1
  143. package/dist/holmes/review/temporal-prior.js +3 -2
  144. package/dist/holmes/review/test-evidence.js +3 -2
  145. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  146. package/dist/holmes/review/test-outcomes.js +92 -2
  147. package/dist/holmes/review/test-runner.d.ts +6 -0
  148. package/dist/holmes/review/test-runner.js +36 -15
  149. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  150. package/dist/holmes/rtm/anchor-ids.js +42 -2
  151. package/dist/holmes/rtm/file-anchors.js +4 -1
  152. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  153. package/dist/holmes/rtm/git-changes.js +3 -1
  154. package/dist/holmes/rtm/graph-store.js +3 -2
  155. package/dist/holmes/rtm/test-scope.js +9 -4
  156. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  157. package/dist/holmes/spec/compat-impact.js +682 -11
  158. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  159. package/dist/holmes/spec/entity-integration.js +3 -2
  160. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  161. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  162. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  163. package/dist/holmes/spec/renumber.js +25 -10
  164. package/dist/holmes/spec/spec-parser.js +9 -3
  165. package/dist/holmes/spec/yaml-scalar.js +2 -2
  166. package/dist/holmes/update/refresh.js +3 -1
  167. package/dist/holmes/update/update-notice.d.ts +6 -0
  168. package/dist/holmes/update/update-notice.js +18 -1
  169. package/package.json +11 -4
package/README.md CHANGED
@@ -23,7 +23,11 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
- - 🧾 **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, its current RTM graph, 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 only add candidates and never decide the outcome alone. A cold, stale, unreadable, or absent evidence lane remains visible as ambiguity. `rtm_reindex` is the only operation that warms versioned requirement-document vectors; optional persistence writes one content-addressed advisory artifact and never changes a spec or opens an edit gate.
26
+ - 🚦 **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.
27
+ - 🪝 **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.
28
+ - 🧭 **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.
29
+ - 🪟 **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.
30
+ - 🧾 **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.
27
31
  - 🧭 **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.
28
32
  - 🧷 **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.
29
33
  - 📏 **Say how much of the repository is governed — as a number, not a label** *(new in 0.27.0)*: `holmes-kit attest` reports how many scanned source files are anchored to an **approved** spec, beside how many approved A-SPECs are anchored from code, and says where that is true (commit, plus a digest of the approved specs) so anyone can reproduce it. No new judgement: the scanner's files, the anchors, the existing link census. A per-file "generated under holmes-kit" header was declined — it is a claim that survives an ungoverned edit, and line 1 already carries the anchor a gate verifies. `--exclude a,b` names vendored trees at a path boundary and is echoed in every output; what cannot be measured is `n/a`, never `0%`; `100` appears only when every file is traced. `--badge` writes a self-contained local SVG, and `--readme` rewrites **only** the region between the `holmes-kit:attest` markers — a README without them is never touched, and a half marker is refused. A statement, not a gate: the numbers never change the exit code.
@@ -71,7 +75,7 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
71
75
  - 📋 **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.
72
76
  - 🔴 **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.
73
77
  - 🧱 **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.
74
- - 🤖 **Autonomous approval — three layers, always bounded** *(0.8.0, reworked 0.13.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; every governance-critical, high-risk or irreversible decision is refused and routed to the out-of-band `holmes-kit approve` queue. The agent can never grant it to itself, the posture is surfaced at every session start, and off is byte-identical to a fully human-gated project.
78
+ - 🤖 **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.
75
79
  - 🧭 **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.
76
80
  - 🚢 **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.
77
81
  - 🧠 **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.
@@ -79,7 +83,7 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
79
83
  - 🐞 **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).
80
84
  - 📏 **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.
81
85
  - 📊 **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.
82
- - 🔔 **Approval UX** *(0.3.1; inbox split 0.15.0)*: dialogs forewarn their 120s deadline and, on expiry, say exactly where the decision went. The tracked 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.
86
+ - 🔔 **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.
83
87
  - ⬆️ **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.
84
88
  - 🧰 **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.
85
89
  - 🚦 **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.
@@ -107,7 +111,7 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
107
111
  | :--- | :--- | :--- |
108
112
  | 🤖 **Claude Code CLI** | 🥇 Tier 1 (Native) | OS PreToolUse & Stop hooks (`.claude/settings.local.json`), MCP server (`.mcp.json`) |
109
113
  | 🚀 **Antigravity CLI (AGY)** | 🥇 Tier 1 (Native) | AGY Hooks (`hooks.json`), MCP config (`.agents/mcp_config.json`), Governance Skills |
110
- | 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (`.codex/config.toml`), plugin-packaged gate hooks at the marketplace path Codex reads (`.claude-plugin/marketplace.json`, codex-cli 0.152.x). Hard-gate enforcement verified on real codex-cli: the captured PreToolUse payload is judged and an unauthorized code-write is denied. |
114
+ | 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (user-level `$CODEX_HOME/config.toml`, normally `~/.codex/config.toml`, shared by every workspace), plugin-packaged gate hooks at the marketplace path Codex reads (`.claude-plugin/marketplace.json`). Hard-gate enforcement was verified on codex-cli 0.152.x; codex-cli 0.155.x removed plugin hooks (`plugin_hooks: removed`), so `init --agent codex` also wires the pre-tool and Stop gates into the user-level `$CODEX_HOME/hooks.json`, preserving your own hooks (REQ-727). **Codex runs that hook only after you trust it once: open `codex` and run `/hooks`.** Holmes never writes that trust, and `doctor` WARNs because it cannot verify it offline (live evidence: `docs/goals/EVIDENCE-live-sessions-2026-09-23.md`). |
111
115
  | 🧩 **Google Antigravity SDK** | 🥇 Tier 1 (Native) | Autonomous Agent SDK bindings and cryptographic provenance verification |
112
116
 
113
117
  > **Note**: Holmes-Kit focuses strictly on CLI-based autonomous agents to guarantee 100% deterministic OS hook gating (`deny` enforcement) before file modifications occur.
@@ -139,6 +143,12 @@ Add `-DryRun` to see what it would do without installing. Exit codes: `0` ok / a
139
143
  | CI / container | none | same, plus `--prefer-online` right after a release |
140
144
  | CLI across many projects (`-g`) | depends | run `npm config get prefix` first — see below |
141
145
 
146
+ **How the MCP server is wired** *(0.31.0)*: from an install (`--save-dev` or `-g`), `init` wires every
147
+ harness as `node <install>/bin/holmes-mcp.js`. A zero-install `npx` run has no lasting path, so it is
148
+ wired through `npx` — and npx runs npm in each session workspace, whose `.npmrc` (`node-options`,
149
+ registry) and `node_modules` can replace the Holmes server. `init` and `doctor` say so; install, then
150
+ re-run `holmes-kit init --force`.
151
+
142
152
  **Stale global shadowing** *(field-measured on Windows, 2026-08-31)*: an old global install makes the
143
153
  bare `holmes-kit` command run the OLD version while `npx holmes-kit` runs the local one — and
144
154
  Windows has TWO global roots (`C:\Program Files\nodejs` and `%APPDATA%\npm`), so `npm uninstall -g`
@@ -169,7 +179,7 @@ npx holmes-kit init # drop the npx prefix if you installed with -g
169
179
  ? Select the AI Agent harnesses to wire into this project:
170
180
  [X] 🤖 Claude Code (.claude/settings.local.json, .mcp.json)
171
181
  [X] 🚀 Antigravity CLI (AGY) (.agents/mcp_config.json, hooks.json, skills)
172
- [ ] 💻 Codex CLI (.codex/config.toml)
182
+ [ ] 💻 Codex CLI (~/.codex/config.toml)
173
183
  ```
174
184
  *It then asks — defaulting to **No** — whether to grant **autonomous spec approval** (low-risk specs
175
185
  self-seal; governance-critical, high-risk and irreversible always stay human). Skip the prompt with
@@ -1,5 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  // @implements A-SPEC-193
3
+ // @implements A-SPEC-734
3
4
  // Antigravity PreToolUse 진입점 — 번역만 한다. 판정은 dist 의 훅 프로그램이 내린다.
4
5
  //
5
6
  // 가드는 require 앞에서 Node 내장만으로 돈다(bin/holmes-kit.js 와 같은 이유). 그리고 가드가
@@ -23,6 +24,9 @@ let buf = '';
23
24
  process.stdin.on('data', (c) => { buf += c; });
24
25
  process.stdin.on('end', () => {
25
26
  try {
27
+ // A-SPEC-734 (round 13): the adapters run in this process, so the guard is installed here — a FIFO in the
28
+ // workspace must never hold this hook (the other harnesses' hook processes install it themselves).
29
+ require(path.join(__dirname, '..', 'dist', 'holmes', 'project', 'regular-file-guard.js')).installProcessGuards();
26
30
  const { adaptPreToolUse } = require(entry);
27
31
  process.stdout.write(JSON.stringify(adaptPreToolUse(buf, process.cwd())));
28
32
  } catch (e) {
package/bin/holmes-kit.js CHANGED
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  // @implements A-SPEC-100.2
3
3
  // @implements A-SPEC-173
4
+ // @implements A-SPEC-734
4
5
  // The guard runs BEFORE the require, using only Node built-ins. `runInit` carries the same guidance
5
6
  // but lives inside `dist` — measured 2026-08-12, a package whose `prepare` was blocked emitted
6
7
  // `node:internal/modules/cjs/loader` from every entry point and that guidance never ran.
@@ -17,6 +18,9 @@ if (!fs.existsSync(entry)) {
17
18
  process.exit(1);
18
19
  }
19
20
 
21
+ // A-SPEC-734 (round 14): this entry requires the CLI as a module, so the CLI's own `require.main` block never
22
+ // runs — the guard is installed here (a FIFO `.env` held `doctor` past 45 s — measured).
23
+ require('../dist/holmes/project/regular-file-guard.js').installProcessGuards();
20
24
  require('../dist/holmes/cli/index.js')
21
25
  .main(process.argv.slice(2))
22
26
  .then((code) => process.exit(code))
@@ -1,9 +1,12 @@
1
1
  #!/usr/bin/env node
2
2
  // @implements A-SPEC-509.1
3
+ // @implements A-SPEC-734
3
4
  // HOLMES-KIT PUSH GATE v1 — thin stdin adapter over dist/holmes/governance/push-gate-runner.js.
4
5
  // Fail-open by contract (H-SPEC-509): this gate safens the default, it is not a security
5
6
  // boundary, so any load or collection failure lets the push proceed.
6
7
  try {
8
+ // A-SPEC-734 (round 14): no product process blocks on a file that is not a regular file.
9
+ require('../dist/holmes/project/regular-file-guard.js').installProcessGuards();
7
10
  const { runPrePush } = require('../dist/holmes/governance/push-gate-runner.js');
8
11
  let text = '';
9
12
  process.stdin.setEncoding('utf8');
@@ -1,5 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  // @implements A-SPEC-193
3
+ // @implements A-SPEC-734
3
4
  // Antigravity Stop 진입점 — 번역만 한다. 판정은 dist 의 Stop 훅이 내린다.
4
5
  //
5
6
  // PreToolUse 와 달리 여기서는 실패가 **열어 준다**. Stop 훅은 이미 fail-open 계약이다: 턴을
@@ -20,6 +21,9 @@ let buf = '';
20
21
  process.stdin.on('data', (c) => { buf += c; });
21
22
  process.stdin.on('end', () => {
22
23
  try {
24
+ // A-SPEC-734 (round 13): the adapters run in this process, so the guard is installed here — a FIFO in the
25
+ // workspace must never hold this hook (the other harnesses' hook processes install it themselves).
26
+ require(path.join(__dirname, '..', 'dist', 'holmes', 'project', 'regular-file-guard.js')).installProcessGuards();
23
27
  const { adaptStop } = require(entry);
24
28
  process.stdout.write(JSON.stringify(adaptStop(buf, process.cwd())));
25
29
  } catch (e) {
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 5fc87d4f-mubu528k
1
+ 89eba670-mum0nzxm
@@ -3,7 +3,7 @@ export declare const GUIDANCE_HISTORY: readonly {
3
3
  enforced: boolean;
4
4
  body: string;
5
5
  }[];
6
- export declare const CURRENT_GUIDANCE_REVISION = 1;
6
+ export declare const CURRENT_GUIDANCE_REVISION = 2;
7
7
  export declare const GUIDANCE_REVISIONS: readonly {
8
8
  revision: number;
9
9
  body: string;
@@ -1,6 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.GUIDANCE_REVISIONS = exports.CURRENT_GUIDANCE_REVISION = exports.GUIDANCE_HISTORY = void 0;
4
+ // @implements A-SPEC-722
4
5
  // @implements A-SPEC-708
5
6
  // Immutable migration evidence from Git; never regenerate from the current renderer.
6
7
  exports.GUIDANCE_HISTORY = [
@@ -26,10 +27,18 @@ exports.GUIDANCE_HISTORY = [
26
27
  }
27
28
  ];
28
29
  // Revisioned generated baseline captured from 68611c61; append, never overwrite, on policy changes.
29
- exports.CURRENT_GUIDANCE_REVISION = 1;
30
+ exports.CURRENT_GUIDANCE_REVISION = 2;
31
+ // Snapshot, not a renderer call: a future policy edit must add a new revision rather than rewrite
32
+ // the bytes that identify revision 2 in already-installed AGENTS.md files.
33
+ const GUIDANCE_REVISION_2_BODY = Buffer.from([
34
+ 'IyBIb2xtZXMtS2l0IOKAlCBXb3Jrc3BhY2UgT3BlcmF0aW9uYWwgRGlzY2lwbGluZQoKVGhpcyByZXBvc2l0b3J5IG9wZXJhdGVzIHVuZGVyICoqTm8gU3BlYywgTm8gQ29kZSoqIGdvdmVybmFuY2UuIEFuIGFwcHJvdmVkIHNwZWNpZmljYXRpb24gTVVTVCBleGlzdCBiZWZvcmUgd3JpdGluZyBzb3VyY2Ugb3IgdGVzdCBjb2RlLgoKIyMgMyBDb3JlIE9wZXJhdGlvbmFsIFJ1bGVzCgoxLiAqKlRvb2wtRmlyc3QgUHJpbmNpcGxlIChOTyBXb3JrYXJvdW5kIFNjcmlwdHMpKio6CiAgIC0gQ3JlYXRpbmcgb3IgbXV0YXRpbmcgYC5heC9zcGVjc2Agb3IgZ292ZXJuYW5jZSBsZWRnZXJzIHZpYSBhcmJpdHJhcnkgdGVtcG9yYXJ5IHNjcmlwdHMgKGAvdG1wLyouanNgKSBpcyBzdHJpY3RseSBmb3JiaWRkZW4uCiAgIC0gYHNwZWNfc2xpY2VfaW5pdGAgYW5kIGBzcGVjX2NyZWF0ZWAgU0NBRkZPTEQgc3BlYyBkb2N1bWVudHM7IGBzcGVjX3NsaWNlX2FwcHJvdmVgIGFuZCBgc3BlY19hcHByb3ZlYCBTRUFMIHRoZW0uIFVzZSB0aGVzZSB0b29scyBmb3IgdGhvc2UgdHdvIGFjdHMg4oCUIG5ldmVyIGEgc2NyaXB0LgogICAtICoqV3JpdGluZyB0aGUgYm9keSBpcyBlZGl0aW5nIHRoZSBmaWxlLioqIEFmdGVyIHNjYWZmb2xkaW5nLCBmaWxsIHRoZSBgVE9ET2AgcGxhY2Vob2xkZXJzIGJ5IGVkaXRpbmcgdGhlIGdlbmVyYXRlZCBzcGVjIG1hcmtkb3duIGluIGAuYXgvc3BlY3MvYCB3aXRoIHlvdXIgbm9ybWFsIGVkaXRvci4gVGhpcyBpcyB0aGUgZXhwZWN0ZWQgYXV0aG9yaW5nIHBhdGgsIG5vdCBhIHdvcmthcm91bmQg4oCUIG5vIE1DUCB0b29sIHRha2VzIHNlY3Rpb24gdGV4dC4KICAgLSBBIFJFUSdzIGAjIyBTdWNjZXNzIENyaXRlcmlhYCBpcyBzY2FmZm9sZGVkIEVNUFRZIG9uIHB1cnBvc2UsIGJlY2F1c2UgYSBnZW5lcmF0b3IgbXVzdCBub3QgaW52ZW50IHdoYXQgInNhdGlzZmllZCIgbWVhbnMuIEFwcHJvdmFsIGlzIHJlZnVzZWQgdW50aWwgeW91IHdyaXRlIG9ic2VydmFibGUgY3JpdGVyaWEgdGhlcmUuCgoyLiAqKkFuY2hvci1GaXJzdCBQcmluY2lwbGUgKE1hbmRhdG9yeSBDb2RlIEFuY2hvcnMpKio6CiAgIC0gV2hlbiBjcmVhdGluZyBvciBtb2RpZnlpbmcgc291cmNlIGNvZGUgYW5kIHRlc3QgZmlsZXMsIGxpbmUgMSBNVVNUIGluY2x1ZGUgYW4gZXhwbGljaXQgYW5jaG9yIGNvbW1lbnQ6IGAvLyBAYCArIGBpbXBsZW1lbnRzIEEtU1BFQy1YWFhgLgoKMy4gKipSZW1lZGlhdGlvbiBQcm90b2NvbCAoTk8gR3VhcmRyYWlsIFJldmVyc2UgRW5naW5lZXJpbmcpKio6CiAgIC0gV2hlbiBhIHRvb2wgY2FsbCBpcyBkZW5pZWQgYnkgYSBob29rIGdhdGUsIERPIE5PVCBpbnNwZWN0IGd1YXJkcmFpbCBzb3VyY2UgY29kZSAoYHByZS10b29sLXVzZS50c2AsIGBwaGFzZS50c2ApIG9yIGF0dGVtcHQgdG8gd3JpdGUgYnlwYXNzIGNvZGUuCiAgIC0gSW1tZWRpYXRlbHkgZm9sbG93IHRoZSAzLXN0ZXAgcmVtZWRpYXRpb24gaW5zdHJ1Y3Rpb25z',
35
+ 'IHByb3ZpZGVkIGluIHRoZSByZWZ1c2FsIG1lc3NhZ2Ugb3IgaW52b2tlIHRoZSBgc3BlY19yZW1lZGlhdGVgIE1DUCB0b29sIC8gYGhvbG1lcy1yZW1lZGlhdGlvbmAgcGxheWJvb2sgc2tpbGwuCgojIyBQcm9jZWR1cmUKCjEuICoqQmVmb3JlIGEgbmV3IFJFUSoqLCBydW4gYHJlcXVpcmVtZW50X3RyaWFnZSh7IHJvb3QsIHByb21wdDogPHRoZSBleGFjdCB1c2VyIHJlcXVpcmVtZW50PiwgcGVyc2lzdDogdHJ1ZSB9KWAuIEEgZnJlc2ggcmVzdWx0IHN1cHBsaWVzIGB0cmlhZ2VfZXZpZGVuY2Uge2RpZ2VzdCxwcm9tcHREaWdlc3R9YDsgc3RhbGUsIHBhcnRpYWwsIHN1cHByZXNzZWQsIGZhaWxlZCwgb3IgdW5hdmFpbGFibGUgZnJlc2huZXNzIHJlbWFpbnMgYGFtYmlndW91c2AgYW5kIG11c3QgYmUgcmVmcmVzaGVkIHJhdGhlciB0aGFuIGd1ZXNzZWQuIEEgYGZ1bGZpbGxlZGAgcmVzdWx0IG11c3QgdXNlIGl0cyBleGlzdGluZyBsaW5lYWdlOyBhbiBgZXhpc3RpbmctY2hhbmdlYCBtdXN0IG5hbWUgdGhhdCBwcmVkZWNlc3Nvci4KMi4gUnVuIGBzcGVjX3NsaWNlX2luaXRgIG9yIGBzcGVjX2NyZWF0ZWAgdG8gc2NhZmZvbGQgUkVRIC0+IEgtU1BFQyAtPiBBLVNQRUMsIHRoZW4gZWRpdCB0aGUgZ2VuZXJhdGVkIG1hcmtkb3duIHRvIHJlcGxhY2UgZXZlcnkgYFRPRE9gIGFuZCB0byB3cml0ZSB0aGUgUkVRJ3MgU3VjY2VzcyBDcml0ZXJpYS4gTmV3IFJFUSBjcmVhdGlvbiBpcyBzaGFyZWQtTUNQIGVuZm9yY2VkIGFuZCByZXF1aXJlcyBpdHMgY3VycmVudCBgdHJpYWdlX2V2aWRlbmNlYC4KMy4gQXBwcm92ZSBzcGVjcyB2aWEgYHNwZWNfc2xpY2VfYXBwcm92ZWAgb3IgYHNwZWNfYXBwcm92ZWAuCjQuICoqQmVmb3JlIGVkaXRpbmcgc291cmNlKiosIHJ1biBgbWFpbnRlbmFuY2VfYW5hbHl6ZSh7IHJvb3QsIHJlcXVlc3QsIHBlcnNpc3Q6IHRydWUgfSlgIGFuZCBrZWVwIHRoZSBkaWdlc3QgaXQgcmV0dXJucyDigJQgdGhhdCBwZXJzaXN0ZWQgYW5hbHlzaXMgaXMgd2hhdCB0aGUgcHJlLWVkaXQgZXZpZGVuY2UgZ2F0ZSBjaGVja3MuCjUuICoqV3JpdGUgdGVzdHMgZmlyc3QqKiBhbmQgdmVyaWZ5IGZhaWx1cmUgKFJFRCBzdGFnZSkuCjYuIEFwcHJvdmUgdGhlIG1pcnJvcmluZyBULVNQRUMgKGBBLVNQRUMtMTg4YCAtPiBgVC1TUEVDLTE4OGApLgo3LiBJbXBsZW1lbnQgc291cmNlIGNvZGUgKEdSRUVOIHN0YWdlKS4KClVzZSBgc3BlY19uZXh0YCB0byBjaGVjayB0aGUgbmV4dCByZXF1aXJlZCBnb3Zlcm5hbmNlIHN0ZXAuIFVzZSBgcGhhc2VfY2hlY2tgIHRvIHZlcmlmeSBhY3Rpb24gcGVybWlzc2lvbnMgYWhlYWQgb2YgZXhlY3V0aW9uLiBVc2UgYGltcGFjdF9nYXRlX2NoZWNrYCB0byBhc2sgd2hhdCB0aGUgcHJlLWVkaXQgZXZpZGVuY2UgZ2F0ZSB3b3VsZCBzYXkgYWJvdXQgYW4gZWRpdCDigJQgaXQgaXMgYWR2aXNvcnkgYW5kIGJsb2NrcyBub3RoaW5nLCBzbyBpdCBhbnN3ZXJzIHRoZSBzYW1lIHdheSBpbiBldmVyeSBoYXJu',
36
+ 'ZXNzLgoKIyMgRW5mb3JjZW1lbnQgaW4gdGhpcyBIYXJuZXNzCgpIb29rIGVuZm9yY2VtZW50IGRlcGVuZHMgb24gdGhlIGFjdGl2ZSBoYXJuZXNzIGFuZCBsb2FkZWQgY29uZmlndXJhdGlvbi4gUHJlcGFyYXRpb24gZGlhZ25vc3RpY3MgZG8gbm90IHByb3ZlIGxpdmUgZW5mb3JjZW1lbnQ7IHZlcmlmeSB0aGUgY3VycmVudCBzZXNzaW9uIGJlZm9yZSByZWx5aW5nIG9uIGdhdGVzLiBVbnJlc29sdmVkIGNyaXRpY2FsIGZpbmRpbmdzIGJsb2NrIGNvbXBsZXRpb24uCg==',
37
+ ].join(''), 'base64').toString('utf8');
30
38
  exports.GUIDANCE_REVISIONS = [
31
39
  {
32
40
  "revision": 1,
33
41
  "body": "# Holmes-Kit — Workspace Operational Discipline\n\nThis repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.\n\n## 3 Core Operational Rules\n\n1. **Tool-First Principle (NO Workaround Scripts)**:\n - Creating or mutating `.ax/specs` or governance ledgers via arbitrary temporary scripts (`/tmp/*.js`) is strictly forbidden.\n - `spec_slice_init` and `spec_create` SCAFFOLD spec documents; `spec_slice_approve` and `spec_approve` SEAL them. Use these tools for those two acts — never a script.\n - **Writing the body is editing the file.** After scaffolding, fill the `TODO` placeholders by editing the generated spec markdown in `.ax/specs/` with your normal editor. This is the expected authoring path, not a workaround — no MCP tool takes section text.\n - A REQ's `## Success Criteria` is scaffolded EMPTY on purpose, because a generator must not invent what \"satisfied\" means. Approval is refused until you write observable criteria there.\n\n2. **Anchor-First Principle (Mandatory Code Anchors)**:\n - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: `// @` + `implements A-SPEC-XXX`.\n\n3. **Remediation Protocol (NO Guardrail Reverse Engineering)**:\n - When a tool call is denied by a hook gate, DO NOT inspect guardrail source code (`pre-tool-use.ts`, `phase.ts`) or attempt to write bypass code.\n - Immediately follow the 3-step remediation instructions provided in the refusal message or invoke the `spec_remediate` MCP tool / `holmes-remediation` playbook skill.\n\n## Procedure\n\n1. Run `spec_slice_init` or `spec_create` to scaffold REQ -> H-SPEC -> A-SPEC, then edit the generated markdown to replace every `TODO` and to write the REQ's Success Criteria.\n2. Approve specs via `spec_slice_approve` or `spec_approve`.\n3. **Before editing source**, run `maintenance_analyze({ root, request, persist: true })` and keep the digest it returns — that persisted analysis is what the pre-edit evidence gate checks.\n4. **Write tests first** and verify failure (RED stage).\n5. Approve the mirroring T-SPEC (`A-SPEC-188` -> `T-SPEC-188`).\n6. Implement source code (GREEN stage).\n\nUse `spec_next` to check the next required governance step. Use `phase_check` to verify action permissions ahead of execution. Use `impact_gate_check` to ask what the pre-edit evidence gate would say about an edit — it is advisory and blocks nothing, so it answers the same way in every harness.\n\n## Enforcement in this Harness\n\nHook enforcement depends on the active harness and loaded configuration. Preparation diagnostics do not prove live enforcement; verify the current session before relying on gates. Unresolved critical findings block completion.\n"
34
- }
42
+ },
43
+ { revision: 2, body: GUIDANCE_REVISION_2_BODY }
35
44
  ];
@@ -1 +1,2 @@
1
+ export declare const CURRENT_GUIDANCE_BODY = "# Holmes-Kit \u2014 Workspace Operational Discipline\n\nThis repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.\n\n## 3 Core Operational Rules\n\n1. **Tool-First Principle (NO Workaround Scripts)**:\n - Creating or mutating `.ax/specs` or governance ledgers via arbitrary temporary scripts (`/tmp/*.js`) is strictly forbidden.\n - `spec_slice_init` and `spec_create` SCAFFOLD spec documents; `spec_slice_approve` and `spec_approve` SEAL them. Use these tools for those two acts \u2014 never a script.\n - **Writing the body is editing the file.** After scaffolding, fill the `TODO` placeholders by editing the generated spec markdown in `.ax/specs/` with your normal editor. This is the expected authoring path, not a workaround \u2014 no MCP tool takes section text.\n - A REQ's `## Success Criteria` is scaffolded EMPTY on purpose, because a generator must not invent what \"satisfied\" means. Approval is refused until you write observable criteria there.\n\n2. **Anchor-First Principle (Mandatory Code Anchors)**:\n - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: `// @` + `implements A-SPEC-XXX`.\n\n3. **Remediation Protocol (NO Guardrail Reverse Engineering)**:\n - When a tool call is denied by a hook gate, DO NOT inspect guardrail source code (`pre-tool-use.ts`, `phase.ts`) or attempt to write bypass code.\n - Immediately follow the 3-step remediation instructions provided in the refusal message or invoke the `spec_remediate` MCP tool / `holmes-remediation` playbook skill.\n\n## Procedure\n\n1. **Before a new REQ**, run `requirement_triage({ root, prompt: <the exact user requirement>, persist: true })`. A fresh result supplies `triage_evidence {digest,promptDigest}`; stale, partial, suppressed, failed, or unavailable freshness remains `ambiguous` and must be refreshed rather than guessed. A `fulfilled` result must use its existing lineage; an `existing-change` must name that predecessor.\n2. Run `spec_slice_init` or `spec_create` to scaffold REQ -> H-SPEC -> A-SPEC, then edit the generated markdown to replace every `TODO` and to write the REQ's Success Criteria. New REQ creation is shared-MCP enforced and requires its current `triage_evidence`.\n3. Approve specs via `spec_slice_approve` or `spec_approve`.\n4. **Before editing source**, run `maintenance_analyze({ root, request, persist: true })` and keep the digest it returns \u2014 that persisted analysis is what the pre-edit evidence gate checks.\n5. **Write tests first** and verify failure (RED stage).\n6. Approve the mirroring T-SPEC (`A-SPEC-188` -> `T-SPEC-188`).\n7. Implement source code (GREEN stage).\n\nUse `spec_next` to check the next required governance step. Use `phase_check` to verify action permissions ahead of execution. Use `impact_gate_check` to ask what the pre-edit evidence gate would say about an edit \u2014 it is advisory and blocks nothing, so it answers the same way in every harness.\n\n## Enforcement in this Harness\n\nHook enforcement depends on the active harness and loaded configuration. Preparation diagnostics do not prove live enforcement; verify the current session before relying on gates. Unresolved critical findings block completion.\n";
1
2
  export declare const renderCommonGuidance: () => string;
@@ -1,9 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.renderCommonGuidance = void 0;
3
+ exports.renderCommonGuidance = exports.CURRENT_GUIDANCE_BODY = void 0;
4
+ // @implements A-SPEC-722
4
5
  // @implements A-SPEC-707
5
6
  // Pure common discipline; runtime capabilities belong to the harness registry.
6
- const renderCommonGuidance = () => `# Holmes-Kit — Workspace Operational Discipline
7
+ exports.CURRENT_GUIDANCE_BODY = `# Holmes-Kit — Workspace Operational Discipline
7
8
 
8
9
  This repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.
9
10
 
@@ -24,12 +25,13 @@ This repository operates under **No Spec, No Code** governance. An approved spec
24
25
 
25
26
  ## Procedure
26
27
 
27
- 1. Run \`spec_slice_init\` or \`spec_create\` to scaffold REQ -> H-SPEC -> A-SPEC, then edit the generated markdown to replace every \`TODO\` and to write the REQ's Success Criteria.
28
- 2. Approve specs via \`spec_slice_approve\` or \`spec_approve\`.
29
- 3. **Before editing source**, run \`maintenance_analyze({ root, request, persist: true })\` and keep the digest it returns — that persisted analysis is what the pre-edit evidence gate checks.
30
- 4. **Write tests first** and verify failure (RED stage).
31
- 5. Approve the mirroring T-SPEC (\`A-SPEC-188\` -> \`T-SPEC-188\`).
32
- 6. Implement source code (GREEN stage).
28
+ 1. **Before a new REQ**, run \`requirement_triage({ root, prompt: <the exact user requirement>, persist: true })\`. A fresh result supplies \`triage_evidence {digest,promptDigest}\`; stale, partial, suppressed, failed, or unavailable freshness remains \`ambiguous\` and must be refreshed rather than guessed. A \`fulfilled\` result must use its existing lineage; an \`existing-change\` must name that predecessor.
29
+ 2. Run \`spec_slice_init\` or \`spec_create\` to scaffold REQ -> H-SPEC -> A-SPEC, then edit the generated markdown to replace every \`TODO\` and to write the REQ's Success Criteria. New REQ creation is shared-MCP enforced and requires its current \`triage_evidence\`.
30
+ 3. Approve specs via \`spec_slice_approve\` or \`spec_approve\`.
31
+ 4. **Before editing source**, run \`maintenance_analyze({ root, request, persist: true })\` and keep the digest it returns — that persisted analysis is what the pre-edit evidence gate checks.
32
+ 5. **Write tests first** and verify failure (RED stage).
33
+ 6. Approve the mirroring T-SPEC (\`A-SPEC-188\` -> \`T-SPEC-188\`).
34
+ 7. Implement source code (GREEN stage).
33
35
 
34
36
  Use \`spec_next\` to check the next required governance step. Use \`phase_check\` to verify action permissions ahead of execution. Use \`impact_gate_check\` to ask what the pre-edit evidence gate would say about an edit — it is advisory and blocks nothing, so it answers the same way in every harness.
35
37
 
@@ -37,4 +39,5 @@ Use \`spec_next\` to check the next required governance step. Use \`phase_check\
37
39
 
38
40
  Hook enforcement depends on the active harness and loaded configuration. Preparation diagnostics do not prove live enforcement; verify the current session before relying on gates. Unresolved critical findings block completion.
39
41
  `;
42
+ const renderCommonGuidance = () => exports.CURRENT_GUIDANCE_BODY;
40
43
  exports.renderCommonGuidance = renderCommonGuidance;
@@ -44,6 +44,8 @@ export interface AgentWiringOptions {
44
44
  packageRoot: string;
45
45
  specsDir: string;
46
46
  launcher?: LauncherMode;
47
+ /** A-SPEC-251.1 (round 27): `false` (`--no-mcp`) leaves the MCP registration out (Antigravity's was written anyway). */
48
+ mcp?: boolean;
47
49
  }
48
50
  export interface AgentFile {
49
51
  path: string;
@@ -69,6 +71,13 @@ export declare function shortPathIfSpaced(p: string): string;
69
71
  * these INSTEAD of "the gate is enforced". Empty when every path is space-free (posix without a
70
72
  * space, or win32 where 8.3 resolved it).
71
73
  */
74
+ /**
75
+ * @implements A-SPEC-251.2 (round 45) — a script path agy's launcher passes on literally: agy runs `command` through `sh -c` on
76
+ * Unix and `cmd /c` on Windows (its embedded hooks.json documentation), so a path holding a character either shell reads —
77
+ * `'`, `(`, `&`, `$`, `;`, quotes, `%`, a leading `~` — does not run as written (`inst'q` was an sh syntax error, `R&D` two
78
+ * commands — measured).
79
+ */
80
+ export declare const AGY_LITERAL_PATH: RegExp;
72
81
  export declare function antigravityHookWarnings(packageRoot: string): string[];
73
82
  export declare const AGENTS_MD: (_enforced: boolean) => string;
74
83
  export { MANAGED_BEGIN, MANAGED_END } from './agents-guidance-plan';
@@ -111,6 +120,25 @@ export interface WiringMerge {
111
120
  * all — is kept. Turning someone's switch back on without a word is the surprise this prevents.
112
121
  */
113
122
  export declare function mergeMcpConfigJson(before: string | null, ours: string): WiringMerge;
123
+ export declare function agyHooksFileProblem(raw: string, parsed: unknown): string | null;
124
+ /**
125
+ * @implements A-SPEC-251.2 (round 46) — the user-level hooks file agy shares between its TUI and its backend
126
+ * (`~/.gemini/config/hooks.json`, agy's changelog; `/hooks` writes `"enabled": false` there). agy merges named hooks from
127
+ * every source by name, and the last source that sets `enabled` decides it: a `holmes-kit` entry switched off there switches
128
+ * the workspace gate off (read from the binary — not run).
129
+ */
130
+ /** The largest hooks file read (round 47). */
131
+ export declare const AGY_HOOKS_MAX_BYTES: number;
132
+ /**
133
+ * @implements A-SPEC-251.2 (round 50) — agy's home: `USERPROFILE` on Windows (Go's `os.UserHomeDir`; Git Bash can set `HOME` to
134
+ * another drive — code reading, not measured on Windows), `HOME` elsewhere.
135
+ */
136
+ export declare function agyHome(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string;
137
+ export declare function agyUserHooksPath(home?: string): string;
138
+ export declare function agyUserSwitch(file?: string): {
139
+ off: boolean;
140
+ unconfirmed: string | null;
141
+ };
114
142
  /** `.agents/hooks.json`. Top-level keys are tool namespaces; only ours is replaced. */
115
143
  export declare function mergeHooksJson(before: string | null, ours: string): WiringMerge;
116
144
  /**
@@ -136,3 +164,16 @@ export interface AgentLink {
136
164
  * 지나간다(A-SPEC-193 §7 이 그 담장을 '타깃 밖만'으로 좁힌 이유이기도 하다).
137
165
  */
138
166
  export declare function agentLinks(agent: Agent, opts: AgentWiringOptions): AgentLink[];
167
+ export declare function agyOtherHooksFiles(target: string, cut?: {
168
+ short: boolean;
169
+ }): string[];
170
+ /** The first switch among the user-level file and the other workspace roots: off, or not confirmed. */
171
+ export declare function agySwitches(target: string, userFile?: string): {
172
+ offIn: string | null;
173
+ unconfirmed: string | null;
174
+ };
175
+ /**
176
+ * `raw` (round 48): the text itself must be the parsed object written out again — parsing keeps only the last of two equal keys,
177
+ * so `"timeout": "10", "timeout": 30` and a first `"holmes-kit": {"enabled": false}` read as init's file (measured).
178
+ */
179
+ export declare function agyCanonicalFile(parsed: unknown, raw?: string): boolean;