@holmes-lab/holmes-kit 0.28.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.
- package/CHANGELOG.md +100 -0
- package/README.md +24 -21
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
- package/dist/holmes/cli/agents-guidance-history.js +11 -2
- package/dist/holmes/cli/agents-guidance.d.ts +1 -0
- package/dist/holmes/cli/agents-guidance.js +11 -8
- package/dist/holmes/cli/codex-toml.d.ts +23 -1
- package/dist/holmes/cli/codex-toml.js +151 -4
- package/dist/holmes/cli/doctor.d.ts +11 -1
- package/dist/holmes/cli/doctor.js +113 -13
- package/dist/holmes/cli/init.d.ts +2 -0
- package/dist/holmes/cli/init.js +20 -40
- package/dist/holmes/cli/interactive-prompt.js +2 -2
- package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
- package/dist/holmes/cli/worktree-readiness.js +17 -3
- package/dist/holmes/cpg/ast-mutation.d.ts +2 -0
- package/dist/holmes/cpg/ast-mutation.js +4 -2
- package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
- package/dist/holmes/cpg/foundation/cfg.js +27 -1
- package/dist/holmes/governance/autonomy.d.ts +9 -0
- package/dist/holmes/governance/autonomy.js +28 -1
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
- package/dist/holmes/hooks/rtm-refresh-child.js +100 -18
- package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
- package/dist/holmes/hooks/rtm-refresh.js +56 -15
- package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
- package/dist/holmes/mcp/approval-adapters.js +21 -0
- package/dist/holmes/mcp/approval-commit.d.ts +21 -0
- package/dist/holmes/mcp/approval-commit.js +92 -0
- package/dist/holmes/mcp/approval-intent.d.ts +44 -0
- package/dist/holmes/mcp/approval-intent.js +67 -0
- package/dist/holmes/mcp/approval-policy.d.ts +14 -0
- package/dist/holmes/mcp/approval-policy.js +18 -0
- package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
- package/dist/holmes/mcp/elicit-approval.js +5 -2
- package/dist/holmes/mcp/handlers/graph-operations.d.ts +24 -1
- package/dist/holmes/mcp/handlers/graph-operations.js +38 -6
- package/dist/holmes/mcp/handlers/maintenance-evidence.js +1 -1
- package/dist/holmes/mcp/handlers/requirement-triage.d.ts +142 -0
- package/dist/holmes/mcp/handlers/requirement-triage.js +220 -0
- package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
- package/dist/holmes/mcp/handlers/review-evidence.js +9 -5
- package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +7 -0
- package/dist/holmes/mcp/handlers/slice-orchestration.js +8 -1
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +26 -2
- package/dist/holmes/mcp/handlers/spec-approval.js +72 -47
- package/dist/holmes/mcp/handlers/spec-authoring.js +20 -2
- package/dist/holmes/mcp/handlers.d.ts +153 -0
- package/dist/holmes/mcp/handlers.js +67 -13
- package/dist/holmes/mcp/maintenance-analyze.js +28 -4
- package/dist/holmes/mcp/maintenance-evidence.js +1 -1
- package/dist/holmes/mcp/requirement-triage-evidence.d.ts +45 -0
- package/dist/holmes/mcp/requirement-triage-evidence.js +149 -0
- package/dist/holmes/mcp/server.js +5 -3
- package/dist/holmes/mcp/supervisor.js +7 -3
- package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
- package/dist/holmes/mcp/tool-schemas.js +44 -1
- package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
- package/dist/holmes/refresh/freshness-coordinator.js +230 -0
- package/dist/holmes/review/condition-hunk-replay.d.ts +45 -0
- package/dist/holmes/review/condition-hunk-replay.js +122 -0
- package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
- package/dist/holmes/review/condition-hunk-resolution.js +258 -0
- package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
- package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
- package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
- package/dist/holmes/review/requirement-triage-human-records.js +119 -0
- package/dist/holmes/review/requirement-triage.d.ts +61 -0
- package/dist/holmes/review/requirement-triage.js +143 -0
- package/dist/holmes/review/scope.js +6 -1
- package/dist/holmes/review/test-outcomes.d.ts +28 -0
- package/dist/holmes/review/test-outcomes.js +90 -1
- package/dist/holmes/semantic/local-model.d.ts +3 -3
- package/dist/holmes/semantic/local-model.js +10 -12
- package/dist/holmes/semantic/model-cache.d.ts +15 -6
- package/dist/holmes/semantic/model-cache.js +77 -21
- package/dist/holmes/semantic/tier.d.ts +5 -1
- package/dist/holmes/semantic/tier.js +7 -6
- package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
- package/dist/holmes/semantic/vector-coverage.js +37 -0
- package/docs/install-guide.md +19 -24
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,106 @@ 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
|
+
|
|
70
|
+
## [0.29.0] - 2026-09-22
|
|
71
|
+
|
|
72
|
+
Holmes-Kit now prepares a local semantic layer by default and can compare a
|
|
73
|
+
new prompt with governed requirement lineage before an agent starts a new spec.
|
|
74
|
+
|
|
75
|
+
### Added
|
|
76
|
+
|
|
77
|
+
- **Verified local BGE-M3 semantic preparation** (A-SPEC-712). Normal package
|
|
78
|
+
installation prepares the pinned public local model in the shared user cache
|
|
79
|
+
and activates it only after offline inference verification. The explicit
|
|
80
|
+
HOLMES_SKIP_MODEL_INSTALL=1 opt-out remains available. A blocked install
|
|
81
|
+
script, offline download, corrupt cache, or failed inference keeps the
|
|
82
|
+
package usable and reports a precise unavailable or degraded recovery path;
|
|
83
|
+
repository text never leaves the machine through this tier.
|
|
84
|
+
- **Read-only requirement lifecycle triage** (A-SPEC-713). The new
|
|
85
|
+
requirement_triage MCP tool ranks governed REQ/H-SPEC/A-SPEC/T-SPEC
|
|
86
|
+
lineages with deterministic BM25 and additive cached semantic candidates,
|
|
87
|
+
then uses content, approval, implementation-anchor, exact-HEAD execution,
|
|
88
|
+
and published-graph evidence to recommend fulfilled, existing-change, new,
|
|
89
|
+
or ambiguous. It can persist a content-addressed evidence artifact but
|
|
90
|
+
cannot create, edit, approve, unseal, retire, or open a source-edit gate.
|
|
91
|
+
- **Condition hunk advisory evidence** (A-SPEC-661). A separate, opt-in
|
|
92
|
+
advisory resolver maps a zero-context diff hunk through a symbol to CFG
|
|
93
|
+
predicate provenance and reports only locally demonstrable relaxed,
|
|
94
|
+
narrowed, or unknown direction. It does not change changedFiles, scanner
|
|
95
|
+
output, hooks, or gates. The recorded 20-commit replay found 21 resolved
|
|
96
|
+
predicate records from 102 symbol candidates; its measured heavy-path cost
|
|
97
|
+
stays outside the synchronous scanner.
|
|
98
|
+
|
|
99
|
+
### Changed
|
|
100
|
+
|
|
101
|
+
- **Requirement-triage measurement is preregistered, not overstated.** A
|
|
102
|
+
12-case frozen prompt corpus and analyst protocol record retrieval coverage,
|
|
103
|
+
human-choice agreement, false reuse/new, evidence completeness, ambiguity
|
|
104
|
+
preservation, and elapsed time as comparison/gap metrics only. No
|
|
105
|
+
human-superiority or release-gate claim is made before an independent blind
|
|
106
|
+
run supplies analyst records.
|
|
107
|
+
|
|
8
108
|
## [0.28.0] - 2026-09-21
|
|
9
109
|
|
|
10
110
|
Holmes-Kit can now keep its governed operating discipline consistent while a
|
package/README.md
CHANGED
|
@@ -23,6 +23,8 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
|
|
|
23
23
|
|
|
24
24
|
### 🛡️ Currently Supported Features (Production Features)
|
|
25
25
|
|
|
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.
|
|
26
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.
|
|
27
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.
|
|
28
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.
|
|
@@ -70,15 +72,15 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
|
|
|
70
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.
|
|
71
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.
|
|
72
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.
|
|
73
|
-
- 🤖 **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;
|
|
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.
|
|
74
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.
|
|
75
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.
|
|
76
|
-
- 🧠 **3-tier semantic layer** *(0.
|
|
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.
|
|
77
79
|
- 🎯 **Graded impact surface** *(0.3.0)*: `rankedImpact` (personalized PageRank over the spec/code graph) beat its pre-registered naive baseline on **both** recall and precision across 3 corpora (×1.6–×17) — measured before claimed.
|
|
78
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).
|
|
79
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.
|
|
80
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.
|
|
81
|
-
- 🔔 **Approval UX** *(0.3.1; inbox split 0.15.0)*:
|
|
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.
|
|
82
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.
|
|
83
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.
|
|
84
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.
|
|
@@ -106,7 +108,7 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
|
|
|
106
108
|
| :--- | :--- | :--- |
|
|
107
109
|
| 🤖 **Claude Code CLI** | 🥇 Tier 1 (Native) | OS PreToolUse & Stop hooks (`.claude/settings.local.json`), MCP server (`.mcp.json`) |
|
|
108
110
|
| 🚀 **Antigravity CLI (AGY)** | 🥇 Tier 1 (Native) | AGY Hooks (`hooks.json`), MCP config (`.agents/mcp_config.json`), Governance Skills |
|
|
109
|
-
| 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (
|
|
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`). |
|
|
110
112
|
| 🧩 **Google Antigravity SDK** | 🥇 Tier 1 (Native) | Autonomous Agent SDK bindings and cryptographic provenance verification |
|
|
111
113
|
|
|
112
114
|
> **Note**: Holmes-Kit focuses strictly on CLI-based autonomous agents to guarantee 100% deterministic OS hook gating (`deny` enforcement) before file modifications occur.
|
|
@@ -168,7 +170,7 @@ npx holmes-kit init # drop the npx prefix if you installed with -g
|
|
|
168
170
|
? Select the AI Agent harnesses to wire into this project:
|
|
169
171
|
[X] 🤖 Claude Code (.claude/settings.local.json, .mcp.json)
|
|
170
172
|
[X] 🚀 Antigravity CLI (AGY) (.agents/mcp_config.json, hooks.json, skills)
|
|
171
|
-
[ ] 💻 Codex CLI (
|
|
173
|
+
[ ] 💻 Codex CLI (~/.codex/config.toml)
|
|
172
174
|
```
|
|
173
175
|
*It then asks — defaulting to **No** — whether to grant **autonomous spec approval** (low-risk specs
|
|
174
176
|
self-seal; governance-critical, high-risk and irreversible always stay human). Skip the prompt with
|
|
@@ -180,28 +182,29 @@ npx holmes-kit doctor
|
|
|
180
182
|
```
|
|
181
183
|
*If everything is green, your project is governed and ready for AI pair-programming!*
|
|
182
184
|
|
|
183
|
-
### 4.
|
|
185
|
+
### 4. Local semantic layer by default; cloud remains optional
|
|
184
186
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
187
|
+
During a normal npm installation, Holmes-Kit prepares the public pinned BGE-M3 assets in a shared
|
|
188
|
+
user cache and enables tier **`local`** only after a real offline inference check succeeds. Local
|
|
189
|
+
inference has **zero repository-text egress**. BM25, citation, and graph search remain available
|
|
190
|
+
whether preparation succeeds or not. The optional cloud tier raises recall further on requests
|
|
191
|
+
your vocabulary cannot reach (measured on 305 traceability cases — see the feature list above):
|
|
188
192
|
|
|
189
|
-
**Tier `local` — no egress, no account.** The embedding runtime ships with holmes-kit
|
|
190
|
-
|
|
191
|
-
`init` downloads it, because a large download nobody asked for is not a default. One command:
|
|
193
|
+
**Tier `local` — no egress, no account.** The embedding runtime ships with holmes-kit. Package
|
|
194
|
+
installation attempts setup once by default; run these commands later to retry or prove readiness:
|
|
192
195
|
```bash
|
|
193
196
|
npx holmes-kit semantic-setup # downloads the public bge-m3 assets once, shared across projects
|
|
194
197
|
npx holmes-kit semantic-check # verifies OFFLINE inference — a real 1024-dim normalized vector
|
|
195
198
|
npx holmes-kit doctor # → semantic tier: local (no egress)
|
|
196
199
|
```
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
200
|
+
`HOLMES_SKIP_MODEL_INSTALL=1` explicitly declines automatic preparation. It never blocks an
|
|
201
|
+
explicit `semantic-setup` or `semantic-check`. Models live in `~/.holmes/models`
|
|
202
|
+
(`%USERPROFILE%\.holmes\models` on Windows); `HOLMES_MODEL_CACHE` overrides that, including for a
|
|
203
|
+
prepopulated offline cache. A cache activates the local tier only after successful offline inference
|
|
204
|
+
writes a current readiness receipt. If lifecycle scripts are blocked, the download fails, or the
|
|
205
|
+
cache is unverified or changed, the package remains usable: `doctor` reports **unavailable** or
|
|
206
|
+
**degraded** and names `semantic-setup` as the recovery command. A runtime or nonempty directory is
|
|
207
|
+
never treated as a working embedding tier.
|
|
205
208
|
|
|
206
209
|
> **Security note.** This package's dependency chain pulls `protobufjs@6.x` through
|
|
207
210
|
> `@xenova/transformers → onnxruntime-web → onnx-proto`, which carries a critical advisory. npm's
|
|
@@ -275,7 +278,7 @@ flowchart LR
|
|
|
275
278
|
| `holmes-kit autonomy status` | Show the current autonomous-approval posture (project default + session envelope) |
|
|
276
279
|
| `holmes-kit autonomy on --for 2h` | Self-drive low-risk specs for this session only (expiring; needs a TTY or `HOLMES_APPROVAL`) |
|
|
277
280
|
| `holmes-kit autonomy off` | End session autonomy immediately |
|
|
278
|
-
| `holmes-kit semantic-setup` | Download and verify the local `bge-m3` model (
|
|
281
|
+
| `holmes-kit semantic-setup` | Download and verify the local `bge-m3` model (retry/recovery; shared across projects) |
|
|
279
282
|
| `holmes-kit semantic-check` | Verify local inference **offline**, without downloading anything |
|
|
280
283
|
| `holmes-kit semantic-key set` | Store the cloud-tier key outside the tree (stdin only, never argv) |
|
|
281
284
|
| `holmes-kit approve --status` | The whole approval picture: workspace, delegation, per-request risk/run/subject/grant preview, recent outcomes |
|
package/dist/.build-id
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
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 =
|
|
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 =
|
|
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
|
-
|
|
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.
|
|
28
|
-
2.
|
|
29
|
-
3.
|
|
30
|
-
4. **
|
|
31
|
-
5.
|
|
32
|
-
6.
|
|
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,
|
|
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,
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|