@holmes-lab/holmes-kit 0.29.0 → 0.30.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 (65) hide show
  1. package/CHANGELOG.md +62 -0
  2. package/README.md +6 -5
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  5. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  6. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  7. package/dist/holmes/cli/agents-guidance.js +11 -8
  8. package/dist/holmes/cli/codex-toml.d.ts +23 -1
  9. package/dist/holmes/cli/codex-toml.js +151 -4
  10. package/dist/holmes/cli/doctor.d.ts +11 -1
  11. package/dist/holmes/cli/doctor.js +88 -12
  12. package/dist/holmes/cli/init.d.ts +2 -0
  13. package/dist/holmes/cli/init.js +20 -40
  14. package/dist/holmes/cli/interactive-prompt.js +2 -2
  15. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  16. package/dist/holmes/cli/worktree-readiness.js +17 -3
  17. package/dist/holmes/governance/autonomy.d.ts +9 -0
  18. package/dist/holmes/governance/autonomy.js +28 -1
  19. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  20. package/dist/holmes/hooks/rtm-refresh-child.js +100 -18
  21. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  22. package/dist/holmes/hooks/rtm-refresh.js +56 -15
  23. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  24. package/dist/holmes/mcp/approval-adapters.js +21 -0
  25. package/dist/holmes/mcp/approval-commit.d.ts +21 -0
  26. package/dist/holmes/mcp/approval-commit.js +92 -0
  27. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  28. package/dist/holmes/mcp/approval-intent.js +67 -0
  29. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  30. package/dist/holmes/mcp/approval-policy.js +18 -0
  31. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  32. package/dist/holmes/mcp/elicit-approval.js +5 -2
  33. package/dist/holmes/mcp/handlers/graph-operations.d.ts +17 -1
  34. package/dist/holmes/mcp/handlers/graph-operations.js +13 -5
  35. package/dist/holmes/mcp/handlers/maintenance-evidence.js +1 -1
  36. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +26 -0
  37. package/dist/holmes/mcp/handlers/requirement-triage.js +45 -10
  38. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  39. package/dist/holmes/mcp/handlers/review-evidence.js +9 -5
  40. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +7 -0
  41. package/dist/holmes/mcp/handlers/slice-orchestration.js +8 -1
  42. package/dist/holmes/mcp/handlers/spec-approval.d.ts +26 -2
  43. package/dist/holmes/mcp/handlers/spec-approval.js +72 -47
  44. package/dist/holmes/mcp/handlers/spec-authoring.js +20 -2
  45. package/dist/holmes/mcp/handlers.d.ts +46 -0
  46. package/dist/holmes/mcp/handlers.js +57 -13
  47. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  48. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  49. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +36 -2
  50. package/dist/holmes/mcp/requirement-triage-evidence.js +71 -1
  51. package/dist/holmes/mcp/server.js +5 -3
  52. package/dist/holmes/mcp/supervisor.js +7 -3
  53. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  54. package/dist/holmes/mcp/tool-schemas.js +31 -1
  55. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  56. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  57. package/dist/holmes/review/condition-hunk-replay.d.ts +12 -0
  58. package/dist/holmes/review/condition-hunk-replay.js +11 -1
  59. package/dist/holmes/review/condition-hunk-resolution.js +59 -8
  60. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  61. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  62. package/dist/holmes/review/scope.js +6 -1
  63. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  64. package/dist/holmes/review/test-outcomes.js +90 -1
  65. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,68 @@ 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.30.0] - 2026-09-23
9
+
10
+ New requirements now start from fresh, prompt-bound triage evidence in every supported harness,
11
+ Codex binds to the session workspace, and approvals are negotiated in-session where the client can
12
+ show them. Four adversarial review rounds and a live three-harness run preceded this release
13
+ (`docs/goals/EVIDENCE-live-sessions-2026-09-23.md`).
14
+
15
+ ### Added
16
+
17
+ - **Fresh-evidence requirement intake** (A-SPEC-719, A-SPEC-723). A receipt-bearing refresh
18
+ coordinator (`.ax/state/fresh-evidence.json`) leases one detached refresh per workspace and HEAD,
19
+ coalesces concurrent requests, records retry state for failed workers, and re-refreshes a usable
20
+ receipt after 30 minutes so uncommitted work keeps the graph fresh. `requirement_triage` persists a
21
+ v2 artifact bound to prompt, workspace, HEAD and receipt generation, and requests the same
22
+ background refresh when evidence is not current. New REQ creation — through `spec_create` **and**
23
+ `spec_slice_init` — validates that artifact at one shared MCP boundary (A-SPEC-724).
24
+ - **Lexical-only intake** (owner decision). A workspace with no semantic tier, or with
25
+ `HOLMES_NO_SEMANTIC_WARM` set, can still create a REQ; triage and its evidence say
26
+ `lexicalOnly: true`. The switch now also stops the background refresh from embedding requirement
27
+ documents and stops triage from embedding the prompt.
28
+ - **In-session approval UX for all three harnesses** (A-SPEC-718, A-SPEC-720): native MCP form
29
+ approval negotiated from the client's advertised capability, a timeout policy, and the approval
30
+ queue as the fallback; no tool annotation is claimed to guarantee a human prompt.
31
+ - **Explicit release test lane** (A-SPEC-714): `prepublishOnly` verifies a HEAD-bound, local,
32
+ scoped test-lane receipt instead of launching external-project tests.
33
+ - **Requirement-triage human-model measurement** (A-SPEC-715) and a conservative condition-hunk
34
+ advisory extension (A-SPEC-717).
35
+
36
+ ### Changed
37
+
38
+ - **Codex uses the configuration it actually loads** (A-SPEC-721): init/doctor wire and judge
39
+ `$CODEX_HOME/config.toml` (normally `~/.codex/config.toml`) without a fixed `HOLMES_SPECS`. Doctor
40
+ warns on a pinned `HOLMES_SPECS`, stays silent about Codex for Claude/Antigravity-only workspaces,
41
+ names Holmes settings written in a shape init does not own, and init refuses to rewrite such a file
42
+ rather than corrupt the shared config. `init --remove --agent codex` states that it disables Holmes
43
+ MCP for every Codex workspace.
44
+ - **H-SPEC obligations are shared by approved sibling slices** (A-SPEC-724.2); release reconciliation
45
+ observability is bound to the existing receipt, outcome and maintenance records (A-SPEC-724.1).
46
+ - **Replay recall** (A-SPEC-725): a cited request with an underfull window may admit a direct,
47
+ scanned importer of the lexical leader; the HOLMES/60 and JARVIS/30 pins are unchanged.
48
+
49
+ ### Fixed
50
+
51
+ - The Codex MCP server bound to the package directory instead of the session workspace: the
52
+ autoreload supervisor started its child in the package root (found only in a live `codex exec`).
53
+ - A freshness lease written with `head: null` in a git workspace could only ever complete as stale,
54
+ so new REQ creation was permanently refused; the lease now binds the git HEAD.
55
+ - The source-semantic lane no longer withholds currentness; the refresh child checks its lease
56
+ before every phase that writes and records synchronous failures as bounded retry.
57
+ - `.ax/evidence/release-test-lane.json` is ignored so the publish gate no longer refuses its own
58
+ receipt as a dirty tree.
59
+
60
+ ### Known limitations
61
+
62
+ - **Codex pre-tool gate on codex-cli 0.155.x**: Codex removed plugin hooks (`plugin_hooks: removed`),
63
+ so the Holmes gate hook does not load there; MCP tools and MCP-side enforcement still apply. Named
64
+ gap REQ-248; measured in `docs/goals/EVIDENCE-live-sessions-2026-09-23.md`.
65
+ - Triage evidence is a provenance guard, not a security boundary: an artifact is not consumed on use
66
+ and is not bound to the REQ title, and a local writer can fabricate one. A dedicated REQ follows.
67
+ - A HOLMES_SPECS pin written as a TOML multi-line string, and unicode-escaped Holmes keys, are not
68
+ recognised by doctor/init.
69
+
8
70
  ## [0.29.0] - 2026-09-22
9
71
 
10
72
  Holmes-Kit now prepares a local semantic layer by default and can compare a
package/README.md CHANGED
@@ -23,7 +23,8 @@ 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
+ - 🪟 **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.
27
+ - 🧾 **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
28
  - 🧭 **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
29
  - 🧷 **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
30
  - 📏 **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 +72,7 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
71
72
  - 📋 **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
73
  - 🔴 **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
74
  - 🧱 **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.
75
+ - 🤖 **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
76
  - 🧭 **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
77
  - 🚢 **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
78
  - 🧠 **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 +80,7 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
79
80
  - 🐞 **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
81
  - 📏 **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
82
  - 📊 **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.
83
+ - 🔔 **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
84
  - ⬆️ **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
85
  - 🧰 **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
86
  - 🚦 **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 +108,7 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
107
108
  | :--- | :--- | :--- |
108
109
  | 🤖 **Claude Code CLI** | 🥇 Tier 1 (Native) | OS PreToolUse & Stop hooks (`.claude/settings.local.json`), MCP server (`.mcp.json`) |
109
110
  | 🚀 **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. |
111
+ | 💻 **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 on 0.155.x the pre-tool gate does not load** — MCP tools and MCP-side enforcement (REQ intake, approval acts) still apply. Tracked as the named gap REQ-248 (live evidence: `docs/goals/EVIDENCE-live-sessions-2026-09-23.md`). |
111
112
  | 🧩 **Google Antigravity SDK** | 🥇 Tier 1 (Native) | Autonomous Agent SDK bindings and cryptographic provenance verification |
112
113
 
113
114
  > **Note**: Holmes-Kit focuses strictly on CLI-based autonomous agents to guarantee 100% deterministic OS hook gating (`deny` enforcement) before file modifications occur.
@@ -169,7 +170,7 @@ npx holmes-kit init # drop the npx prefix if you installed with -g
169
170
  ? Select the AI Agent harnesses to wire into this project:
170
171
  [X] 🤖 Claude Code (.claude/settings.local.json, .mcp.json)
171
172
  [X] 🚀 Antigravity CLI (AGY) (.agents/mcp_config.json, hooks.json, skills)
172
- [ ] 💻 Codex CLI (.codex/config.toml)
173
+ [ ] 💻 Codex CLI (~/.codex/config.toml)
173
174
  ```
174
175
  *It then asks — defaulting to **No** — whether to grant **autonomous spec approval** (low-risk specs
175
176
  self-seal; governance-critical, high-risk and irreversible always stay human). Skip the prompt with
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 5fc87d4f-mubu528k
1
+ ed82db7d-mudiuihz
@@ -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;
@@ -1,12 +1,18 @@
1
1
  import { McpServerEntry } from './mcp-launcher';
2
2
  /** The one table holmes-kit owns in a Codex config.toml. */
3
3
  export declare const CODEX_TABLE = "mcp_servers.holmes-kit";
4
+ /**
5
+ * The default configuration location actually loaded by Codex CLI. A named profile may layer a
6
+ * different config, but it is invocation state and cannot be inferred by an offline doctor run.
7
+ * Injectable values keep this platform-sensitive path rule deterministic in tests.
8
+ */
9
+ export declare function defaultCodexConfigPath(env?: NodeJS.ProcessEnv, home?: string): string;
4
10
  /**
5
11
  * Serialize the `[mcp_servers.holmes-kit]` table. `env` is an inline table so the whole entry is ONE
6
12
  * contiguous region (no `[mcp_servers.holmes-kit.env]` child header) — that keeps the merge boundary
7
13
  * unambiguous: our region runs from the header to the next table header. Ends with a trailing newline.
8
14
  */
9
- export declare function codexMcpBlock(entry: McpServerEntry, specsDir: string): string;
15
+ export declare function codexMcpBlock(entry: McpServerEntry, _legacySpecsDir?: string): string;
10
16
  /**
11
17
  * Merge `block` (a full `codexMcpBlock` output) into `existing`. When `existing` is null/empty the
12
18
  * block stands alone. When our table is already present its region is REPLACED (no duplicate); when
@@ -24,6 +30,22 @@ export declare function readCodexHolmesEntry(raw: string): {
24
30
  command: string;
25
31
  args: string[];
26
32
  } | null;
33
+ /** @implements A-SPEC-721 — whether the config carries Holmes's table at all (well-formed or not). */
34
+ export declare function hasCodexHolmesTable(raw: string): boolean;
35
+ /** @implements A-SPEC-721 — whether the shared config configures the Holmes server at all. */
36
+ export declare function mentionsHolmes(raw: string): boolean;
37
+ /**
38
+ * @implements A-SPEC-721 — Holmes settings outside the one region init owns (dotted keys, an inline
39
+ * table under `[mcp_servers]`, a subtable without its parent). Merging our block into such a file
40
+ * would declare the table twice and Codex would reject the whole shared config.
41
+ */
42
+ export declare function unownedHolmesShape(raw: string): boolean;
43
+ /**
44
+ * @implements A-SPEC-721 — a `HOLMES_SPECS` value set on any Holmes line (inline env, env subtable,
45
+ * quoted key; basic or literal string). Null when absent or unreadable. Doctor decides whether the
46
+ * value binds one fixed project.
47
+ */
48
+ export declare function readCodexFixedSpecs(raw: string): string | null;
27
49
  /**
28
50
  * @implements A-SPEC-585
29
51
  * The first invalid basic-string escape inside OUR table's `command =` / `args =` lines, with its
@@ -1,14 +1,68 @@
1
1
  "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
2
35
  Object.defineProperty(exports, "__esModule", { value: true });
3
36
  exports.CODEX_TABLE = void 0;
37
+ exports.defaultCodexConfigPath = defaultCodexConfigPath;
4
38
  exports.codexMcpBlock = codexMcpBlock;
5
39
  exports.mergeCodexToml = mergeCodexToml;
6
40
  exports.removeCodexToml = removeCodexToml;
7
41
  exports.readCodexHolmesEntry = readCodexHolmesEntry;
42
+ exports.hasCodexHolmesTable = hasCodexHolmesTable;
43
+ exports.mentionsHolmes = mentionsHolmes;
44
+ exports.unownedHolmesShape = unownedHolmesShape;
45
+ exports.readCodexFixedSpecs = readCodexFixedSpecs;
8
46
  exports.invalidTomlEscape = invalidTomlEscape;
47
+ // @implements A-SPEC-721
48
+ // @implements A-SPEC-266
49
+ // Codex reads default MCP servers from `$CODEX_HOME/config.toml` (normally
50
+ // `~/.codex/config.toml`), not from a repository-local `.codex/config.toml`. This module owns only
51
+ // Holmes' TOML table there and preserves the rest byte-for-byte. The launched server deliberately
52
+ // has no HOLMES_SPECS binding: it resolves its governed workspace from the active Codex session cwd.
53
+ const path = __importStar(require("node:path"));
54
+ const os = __importStar(require("node:os"));
9
55
  /** The one table holmes-kit owns in a Codex config.toml. */
10
56
  exports.CODEX_TABLE = 'mcp_servers.holmes-kit';
11
57
  const HEADER = `[${exports.CODEX_TABLE}]`;
58
+ /**
59
+ * The default configuration location actually loaded by Codex CLI. A named profile may layer a
60
+ * different config, but it is invocation state and cannot be inferred by an offline doctor run.
61
+ * Injectable values keep this platform-sensitive path rule deterministic in tests.
62
+ */
63
+ function defaultCodexConfigPath(env = process.env, home = os.homedir()) {
64
+ return path.join(env.CODEX_HOME || path.join(home, '.codex'), 'config.toml');
65
+ }
12
66
  /** TOML basic-string escape — backslash and quote, the named whitespace escapes, then any remaining
13
67
  * C0 control character as \uXXXX. Built by code point so no literal control byte lives in the source. */
14
68
  function tomlStr(s) {
@@ -37,13 +91,13 @@ function tomlStr(s) {
37
91
  * contiguous region (no `[mcp_servers.holmes-kit.env]` child header) — that keeps the merge boundary
38
92
  * unambiguous: our region runs from the header to the next table header. Ends with a trailing newline.
39
93
  */
40
- function codexMcpBlock(entry, specsDir) {
94
+ function codexMcpBlock(entry, _legacySpecsDir) {
41
95
  const args = entry.args.map(tomlStr).join(', ');
42
96
  return [
43
97
  HEADER,
44
98
  `command = ${tomlStr(entry.command)}`,
45
99
  `args = [${args}]`,
46
- `env = { HOLMES_SPECS = ${tomlStr(specsDir)} }`,
100
+ 'env = { HOLMES_MCP_AUTORELOAD = "1" }',
47
101
  '',
48
102
  ].join('\n');
49
103
  }
@@ -156,13 +210,17 @@ function tableKeyPath(line) {
156
210
  continue;
157
211
  }
158
212
  if (c === '.') {
159
- segs.push(cur.trim());
213
+ segs.push(cur);
160
214
  cur = '';
161
215
  continue;
162
216
  }
217
+ // Whitespace OUTSIDE quotes separates tokens and is dropped; inside quotes it is part of the key
218
+ // (`" holmes-kit"` is another server — A-SPEC-721), so segments are never trimmed.
219
+ if (c === ' ' || c === '\t')
220
+ continue;
163
221
  cur += c;
164
222
  }
165
- segs.push(cur.trim());
223
+ segs.push(cur);
166
224
  if (q !== null)
167
225
  return null; // unbalanced quote — not a clean header
168
226
  return segs;
@@ -271,6 +329,95 @@ function readCodexHolmesEntry(raw) {
271
329
  return null;
272
330
  return { command, args };
273
331
  }
332
+ /** @implements A-SPEC-721 — whether the config carries Holmes's table at all (well-formed or not). */
333
+ function hasCodexHolmesTable(raw) {
334
+ return ourRegion(raw.split('\n')) !== null;
335
+ }
336
+ /** A line with its trailing comment removed — `#` inside a quoted string is not a comment. */
337
+ function stripComment(line) {
338
+ let q = null;
339
+ for (let i = 0; i < line.length; i++) {
340
+ const c = line[i];
341
+ if (q) {
342
+ if (c === '\\' && q === '"')
343
+ i++;
344
+ else if (c === q)
345
+ q = null;
346
+ continue;
347
+ }
348
+ if (c === '"' || c === "'")
349
+ q = c;
350
+ else if (c === '#')
351
+ return line.slice(0, i);
352
+ }
353
+ return line;
354
+ }
355
+ /**
356
+ * @implements A-SPEC-721 — every line that configures the Holmes server, in any TOML spelling: a
357
+ * `[mcp_servers.holmes-kit…]` header, or a key whose full dotted path starts `mcp_servers.holmes-kit`
358
+ * (`holmes-kit = {…}` / `holmes-kit.command = …` under `[mcp_servers]`, or any key inside our table).
359
+ * Lines inside multi-line strings and arrays, and comments, are never counted.
360
+ */
361
+ function holmesLines(raw) {
362
+ const lines = raw.split('\n');
363
+ const states = lineStartStates(lines);
364
+ const out = [];
365
+ let table = [];
366
+ for (let i = 0; i < lines.length; i++) {
367
+ if (states[i].ml !== null || states[i].depth !== 0)
368
+ continue;
369
+ const text = stripComment(lines[i]);
370
+ if (/^\s*\[/.test(text)) {
371
+ table = tableKeyPath(text) ?? ['<unparsed>'];
372
+ if (isOurPrefix(table))
373
+ out.push({ i, header: true, text });
374
+ continue;
375
+ }
376
+ const eq = text.indexOf('=');
377
+ if (eq <= 0)
378
+ continue;
379
+ const key = tableKeyPath(`[${text.slice(0, eq).trim()}]`);
380
+ if (!key)
381
+ continue;
382
+ if (isOurPrefix([...table, ...key]))
383
+ out.push({ i, header: false, text });
384
+ }
385
+ return out;
386
+ }
387
+ /** @implements A-SPEC-721 — whether the shared config configures the Holmes server at all. */
388
+ function mentionsHolmes(raw) {
389
+ return holmesLines(raw).length > 0;
390
+ }
391
+ /**
392
+ * @implements A-SPEC-721 — Holmes settings outside the one region init owns (dotted keys, an inline
393
+ * table under `[mcp_servers]`, a subtable without its parent). Merging our block into such a file
394
+ * would declare the table twice and Codex would reject the whole shared config.
395
+ */
396
+ function unownedHolmesShape(raw) {
397
+ const region = ourRegion(raw.split('\n'));
398
+ return holmesLines(raw).some(({ i }) => !region || i < region.start || i >= region.end);
399
+ }
400
+ /**
401
+ * @implements A-SPEC-721 — a `HOLMES_SPECS` value set on any Holmes line (inline env, env subtable,
402
+ * quoted key; basic or literal string). Null when absent or unreadable. Doctor decides whether the
403
+ * value binds one fixed project.
404
+ */
405
+ function readCodexFixedSpecs(raw) {
406
+ for (const { text } of holmesLines(raw)) {
407
+ const m = text.match(/(?:^|[\s{,.])["']?HOLMES_SPECS["']?\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')/);
408
+ if (!m)
409
+ continue;
410
+ if (m[2] !== undefined)
411
+ return m[2];
412
+ try {
413
+ return unescapeToml(m[1]);
414
+ }
415
+ catch {
416
+ return null;
417
+ }
418
+ }
419
+ return null;
420
+ }
274
421
  /**
275
422
  * @implements A-SPEC-585
276
423
  * The first invalid basic-string escape inside OUR table's `command =` / `args =` lines, with its
@@ -18,6 +18,10 @@ export interface DoctorOptions {
18
18
  run?: ProbeRunner;
19
19
  autoFix?: boolean;
20
20
  agent?: Agent;
21
+ /** Test/integration override for Codex's active default user configuration. */
22
+ codexConfigPath?: string;
23
+ /** Test seam for Codex's local plugin registry; production reads its JSON CLI output. */
24
+ readCodexPluginList?: () => string | undefined;
21
25
  }
22
26
  /**
23
27
  * Environment variables removed before spawning a probe.
@@ -193,7 +197,13 @@ export declare function formatChecks(checks: Check[]): string;
193
197
  * The `node` fast-path is gone. Existence survives as a fast FAIL, because spending a 30s deadline on
194
198
  * a path that does not exist tells nobody anything new.
195
199
  */
196
- export declare function wiringHandshakeChecks(target: string): Promise<Check[]>;
200
+ /**
201
+ * @implements A-SPEC-721 — the target itself carries Codex wiring (plugin directory, or a legacy
202
+ * repository-local config/JSON). The active config is shared by every workspace, so only such a
203
+ * target is told that the shared file lacks a Holmes entry.
204
+ */
205
+ export declare function codexWiredTarget(target: string): boolean;
206
+ export declare function wiringHandshakeChecks(target: string, codexConfigPath?: string): Promise<Check[]>;
197
207
  /**
198
208
  * @implements A-SPEC-476
199
209
  * The semantic tier's doctor verdict, pure so the three states are unit-testable offline.