@holmes-lab/holmes-kit 0.41.1 → 0.41.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +29 -5
  3. package/bin/holmes-mcp.js +36 -1
  4. package/dist/.build-id +1 -1
  5. package/dist/holmes/cli/claude-switches.d.ts +9 -0
  6. package/dist/holmes/cli/claude-switches.js +11 -8
  7. package/dist/holmes/cli/doctor.d.ts +7 -1
  8. package/dist/holmes/cli/doctor.js +63 -20
  9. package/dist/holmes/cli/holmes-hook-id.d.ts +9 -0
  10. package/dist/holmes/cli/holmes-hook-id.js +22 -0
  11. package/dist/holmes/cli/hook-failure-posture.d.ts +44 -0
  12. package/dist/holmes/cli/hook-failure-posture.js +65 -0
  13. package/dist/holmes/cli/index.js +3 -1
  14. package/dist/holmes/cli/init.d.ts +6 -0
  15. package/dist/holmes/cli/init.js +151 -3
  16. package/dist/holmes/cli/native-deps.d.ts +10 -4
  17. package/dist/holmes/cli/native-deps.js +30 -29
  18. package/dist/holmes/cli/release-history.d.ts +21 -0
  19. package/dist/holmes/cli/release-history.js +116 -0
  20. package/dist/holmes/cli/run-wiring.js +4 -2
  21. package/dist/holmes/cli/runtime-binding.d.ts +24 -0
  22. package/dist/holmes/cli/runtime-binding.js +67 -25
  23. package/dist/holmes/cli/settings-merge.d.ts +3 -2
  24. package/dist/holmes/cli/settings-merge.js +11 -9
  25. package/dist/holmes/config/config.d.ts +6 -0
  26. package/dist/holmes/config/config.js +23 -3
  27. package/dist/holmes/config/judgement-keys.d.ts +20 -0
  28. package/dist/holmes/config/judgement-keys.js +100 -0
  29. package/dist/holmes/config/project-caps.js +3 -2
  30. package/dist/holmes/governance/autonomous-shell.js +1 -1
  31. package/dist/holmes/governance/autonomy.d.ts +27 -1
  32. package/dist/holmes/governance/autonomy.js +126 -6
  33. package/dist/holmes/governance/wiring-receipt.d.ts +7 -0
  34. package/dist/holmes/governance/wiring-receipt.js +84 -0
  35. package/dist/holmes/guardrail/cli-root.d.ts +31 -0
  36. package/dist/holmes/guardrail/cli-root.js +261 -0
  37. package/dist/holmes/guardrail/command-traits.d.ts +2 -0
  38. package/dist/holmes/guardrail/command-traits.js +26 -1
  39. package/dist/holmes/guardrail/impact-gate.d.ts +17 -1
  40. package/dist/holmes/guardrail/impact-gate.js +44 -5
  41. package/dist/holmes/guardrail/outward-acts.js +10 -3
  42. package/dist/holmes/guardrail/package-manager-acts.d.ts +41 -0
  43. package/dist/holmes/guardrail/package-manager-acts.js +1298 -0
  44. package/dist/holmes/guardrail/refusal-codes.js +9 -1
  45. package/dist/holmes/guardrail/shell-syntax.d.ts +3 -0
  46. package/dist/holmes/guardrail/shell-syntax.js +7 -2
  47. package/dist/holmes/guardrail/write-target.d.ts +20 -0
  48. package/dist/holmes/guardrail/write-target.js +168 -2
  49. package/dist/holmes/hooks/pre-tool-use.d.ts +110 -3
  50. package/dist/holmes/hooks/pre-tool-use.js +1208 -60
  51. package/dist/holmes/mcp/evidence-artifact.d.ts +112 -0
  52. package/dist/holmes/mcp/evidence-artifact.js +2 -0
  53. package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +2 -1
  54. package/dist/holmes/mcp/handlers/maintenance-evidence.js +24 -2
  55. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +1 -1
  56. package/dist/holmes/mcp/handlers/operator-inspection.js +2 -2
  57. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +1 -1
  58. package/dist/holmes/mcp/handlers/requirement-triage.js +3 -2
  59. package/dist/holmes/mcp/handlers/spec-approval.d.ts +1 -1
  60. package/dist/holmes/mcp/handlers/spec-approval.js +6 -6
  61. package/dist/holmes/mcp/handlers/test-execution.d.ts +8 -0
  62. package/dist/holmes/mcp/handlers/test-execution.js +12 -6
  63. package/dist/holmes/mcp/handlers.d.ts +16 -7
  64. package/dist/holmes/mcp/maintenance-evidence.d.ts +11 -82
  65. package/dist/holmes/mcp/maintenance-evidence.js +57 -2
  66. package/dist/holmes/mcp/outcome-replay.d.ts +18 -0
  67. package/dist/holmes/mcp/outcome-replay.js +85 -0
  68. package/dist/holmes/mcp/outcome-windows.d.ts +136 -0
  69. package/dist/holmes/mcp/outcome-windows.js +236 -0
  70. package/dist/holmes/mcp/tool-schemas.js +1 -1
  71. package/dist/holmes/project/hook-specs-arg.d.ts +4 -0
  72. package/dist/holmes/project/hook-specs-arg.js +39 -0
  73. package/dist/holmes/project/install-layout.d.ts +11 -0
  74. package/dist/holmes/project/install-layout.js +109 -0
  75. package/dist/holmes/project/install-scripts-policy.d.ts +4 -1
  76. package/dist/holmes/project/install-scripts-policy.js +6 -3
  77. package/dist/holmes/project/native-recovery.d.ts +29 -0
  78. package/dist/holmes/project/native-recovery.js +62 -0
  79. package/dist/holmes/project/root.d.ts +6 -0
  80. package/dist/holmes/project/root.js +15 -3
  81. package/dist/holmes/project/wiring-receipt-format.d.ts +20 -0
  82. package/dist/holmes/project/wiring-receipt-format.js +42 -0
  83. package/dist/holmes/project/workspace-preflight.d.ts +9 -0
  84. package/dist/holmes/project/workspace-preflight.js +40 -1
  85. package/dist/holmes/review/classification-replay.d.ts +53 -0
  86. package/dist/holmes/review/classification-replay.js +78 -0
  87. package/dist/holmes/review/head-worktree.js +5 -4
  88. package/dist/holmes/review/run-provenance.js +3 -2
  89. package/dist/holmes/review/test-evidence.js +2 -2
  90. package/dist/holmes/review/test-outcomes.js +3 -1
  91. package/dist/holmes/rtm/graph-store.d.ts +5 -0
  92. package/dist/holmes/rtm/graph-store.js +12 -4
  93. package/dist/holmes/rtm/native-driver.d.ts +42 -0
  94. package/dist/holmes/rtm/native-driver.js +147 -0
  95. package/dist/holmes/rtm/rtm-graph.js +11 -2
  96. package/dist/holmes/runtime/dispatch.d.ts +6 -0
  97. package/dist/holmes/runtime/dispatch.js +51 -2
  98. package/dist/holmes/runtime/hook-process.d.ts +6 -0
  99. package/dist/holmes/runtime/hook-process.js +3 -3
  100. package/dist/holmes/update/semver-strict.d.ts +3 -0
  101. package/dist/holmes/update/semver-strict.js +58 -0
  102. package/docs/install-guide.md +8 -1
  103. package/package.json +3 -2
  104. package/playbooks/tdd-slice/PLAYBOOK.md +1 -1
  105. package/release-history.json +181 -0
package/CHANGELOG.md CHANGED
@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
  <!-- @implements A-SPEC-209 -->
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.41.3] - 2026-11-18
11
+
12
+ ### Security
13
+ - **An agent can no longer switch its own gate off with `holmes-kit init` (A-SPEC-772.15).** In 0.41.2 `holmes-kit init --matcher Nothing` or `holmes-kit init --specs-dir <an empty directory>`, run from a Claude Code session, was allowed by the gate and applied without approval, leaving the gate matching no tool or reading an empty spec store. Now the gate treats init's `--remove`, `--force`, `--matcher`, `--specs-dir`, `--settings`, `--autonomy` and any option it does not know as the owner's; and init itself, on an already-wired project, keeps the current matcher, spec store and settings file unless they are named, and needs a `governance-wiring` approval to change them. A plain `holmes-kit init` still repairs removed wiring. `holmes-kit upgrade` now keeps a custom spec store when it re-pins a workspace (it reset it to `.ax/specs`). (A-SPEC-772.16) A plain init still widens an old default matcher (`Bash`, `Bash|Write|Edit`) to `.*`, and `--matcher ".*"` needs no approval; re-wiring from a holmes-kit copy older than the one wired needs the approval, and so does re-wiring from another copy when the wired package's version cannot be read (A-SPEC-772.17 — re-installing the same copy in place is unaffected); every hook command now names its spec store with `--specs`, so a `HOLMES_SPECS` in the harness's environment no longer chooses it (workspaces wired before keep working, `run start` included). (A-SPEC-772.21) A `holmes-kit init --dry-run` frees only itself: other holmes-kit commands on the same line (`ledger rechain`, `runtime-binding setup|remove`) are judged as before (with a computed target the dry-run is itself refused since A-SPEC-772.34, below). (A-SPEC-772.23) `holmes-kit init` or `upgrade` run from a holmes-kit package other than the one governing the session — found by real path, whether named by path, through `node`, by the project's `node_modules/.bin` or by PATH — is the owner's (a `governance-wiring` approval), as is one whose package the gate cannot tell (a `PATH=` before it, a `cd` before it on the line, `sudo`); `npx @holmes-lab/holmes-kit …` is still judged by the package reader (latest free, a pinned older version the owner's). A bare `holmes-kit init` therefore needs the approval when the `holmes-kit` on PATH is another install than the one wired: that CLI runs from another install root, so it is another gate's code re-wiring this one, and the governing gate cannot vouch for what it will write. To keep it free, run it from the wired install — the wired package's own `bin/holmes-kit.js`, the project's `node_modules/.bin/holmes-kit` when that is the wired install, or a PATH whose `holmes-kit` is that install — or name the package, `npx @holmes-lab/holmes-kit init`, which the package reader judges (latest free). init's own version check compares strict semver only (a label such as `garbage`, `99` or `1e3` needs the approval) and orders a prerelease below its release. (A-SPEC-772.28) `npx @holmes-lab/holmes-kit init|upgrade` without a version runs the project's own copy when one is installed (npm exec), so it is compared by root the same way; with no local copy, or with a version, the package reader judges it as before. An npm or pnpm shim (`.cmd`, `.ps1`, an sh shim in `node_modules/.bin`) is read for the package it runs, `bun x` is a runner, and `time`/`env` before a runner are looked through; a relative PATH entry counts from where the command runs. The refusal names the command that runs the governing install (`node <governing root>/bin/holmes-kit.js init …`), which is free, and a `config-write` approval for the refused command lifts it. (A-SPEC-772.29) With the gate in both Claude Code settings files, `holmes-kit init --settings project` (or `local`) naming a file that already holds it is no change of file, so it needs no approval. (A-SPEC-772.30) That approval lifts only the "another copy" refusal: an owner option on the same command (`--force`, `--remove` …) or another governed act on the line (`ledger rechain`) is still refused. The self-recovery command is quoted for sh (a governing root with a space, a quoted argument, a Windows `C:\…` root), and after a `cd` it names the directory as `--target`; an absolute path to the governing install is free after a `cd`. `npm exec -- holmes-kit`, `npm x`, `npx -p @holmes-lab/holmes-kit holmes-kit` and `bunx --bun` are read as runners; a text shim whose target cannot be read is unresolved. (A-SPEC-772.31) When both Claude Code settings files hold the gate, re-wiring is "no change" only when the two entries name the same spec store, package and matcher; otherwise init needs the approval. A `cd` to a computed place (`cd "$X"`) gives no recovery command, also inside a nested `sh -c`; an `init` or `upgrade` with more words than the gate reads is refused; a text shim on PATH whose target cannot be read is unresolved on Windows too; the refusal names every governed act on the line. The audit row principle 7 writes for a file excused by the runtime binding receipt now records the digest it matched when judged, and when the ledger chain is not this repository's the missing row is reported on stderr. (A-SPEC-772.32) A holmes-kit init or upgrade inside a command substitution (`$(…)`, backticks) on a line that also changes directory is judged as after an unknown `cd` (it ran with no verdict). The "another copy" refusal files its approval request under a target of its own (`holmes-kit root rule: <command>`), so a line that also installs or pins a holmes-kit version needs both approvals, each request naming its own reason; an approval for the command itself lifts only the package-version refusal. (A-SPEC-772.33) A shell line that names holmes-kit and `init`, `upgrade`, `ledger` or `runtime-binding` is judged only when the gate reads all of it; a line with a group or loop (`{ }`, `if`, `for` …), `eval`, a subshell, a computed command name, a wrapper the gate does not read in front of holmes-kit (`timeout`, `xargs`, `find -exec`, `env -C`), a shell reading its input, a here-string, a heredoc fed to a shell or runner (one fed to a read-only program is text, A-SPEC-772.34), a parameter default that runs a command, `CDPATH` or a reassigned `HOME` is refused with no recovery command — write the holmes-kit call as a plain line. A command spelled with the "another copy" approval prefix takes no `config-write` approval. (A-SPEC-772.34) The rule covers what one line shows; a program written to a file or passed on stdin by an earlier call is outside it (0.41.4 checks the wiring after the fact). On such a line a computed or glob word in a command that runs the CLI, or in the place a runner or shell takes its program (`node $X`, `sh -c "$S"`), a runner given anything but its own options before holmes-kit (`node -e`, `npx tsx -e`, `deno eval`, `node --import`), a shell or runner reading code from its input, a program that is neither the CLI nor a read-only one (writers, `timeout`, `xargs`, `find`), a git alias or `git -c`, `rg --pre`, `LESSOPEN`/`LESSCLOSE`, `$'…'`, an unquoted subshell, a `cd ~user`, and an assignment of `HOME`, `CODEX_HOME`, `PWD`, `OLDPWD` or any `GIT_*` are refused. Text is text: a heredoc fed to a read-only program (`git commit -F - <<'EOF'`, `cat <<'EOF'` inside `-m "$(…)"` or `--body "$(…)"`) and quoted words are no longer read as commands, and the refusal names the way out (`git commit -F <file>`, `gh pr create --body-file <file>`). A computed command or program counts only on a line that spells holmes-kit or one of those subcommands somewhere; a line that spells neither is outside the rule. Measured with the shipped build on 2026-11-18 over every agent Bash command in this machine's Claude Code transcripts, subagents' included (95,514 commands; the transcripts grow, so a re-run moves the counts slightly): 167 (0.17%) are refused — 101 of 28,612 (0.35%) in Holmes-Kit's own development, and 66 of 66,902 (0.10%) in other projects, all 66 in one project where Holmes review work ran; a replay probe in the holmes-kit repository (`docs/goals/probes/corpus-772-34.probe.ts`) re-runs it. A dry-run init with a computed target (`--target "$PWD"`) is now refused too; write the target out. (A-SPEC-772.35) This rule is accident prevention: it stops the common ways an agent runs an old holmes-kit by mistake. Deliberate bypass forms are named limits in the spec — among them `git fetch --upload-pack`, an assignment before git or less, a program read from a pipe through `xargs` or `awk`, a program written to a file then run by path or by an interpreter on the file (`./x.sh`, `bash f`, `sh f`, `source f`, `. f`), `find -exec`, a `<<` inside a comment or arithmetic, and a spelling computed entirely — and the guarantee is the after-the-fact integrity check planned for 0.41.4. Claude Code's own commit and PR form, a heredoc fed to `cat` inside `-m "$(…)"`, is text whatever words its body holds (a body with `"CDPATH"` was refused). (A-SPEC-772.36) A heredoc body is text only when the command that receives it is a read-only program — inside a `$(…)` too — and the body runs nothing: with an unquoted tag (`<<EOF`) a `$(…)`, backtick or `${…}` in the body runs, so such a body counts; `OUT="$(bash <<'EOF' …)"` and `eval` of a heredoc's text are refused on a line that runs holmes-kit. (A-SPEC-772.37) The gate reads what each code reader (a shell, `eval`, `source`, `.`, `node`, `bun`, `deno`, `tsx`, `python`, `perl`, `ruby`, also behind `sudo`, `timeout`, `nohup`, `exec`, `command`, `time` or `env`) receives, in every `$(…)`, backtick and pipe stage: a heredoc piped to `bash` inside `$(…)`, `$(cat <<'EOF' …)` as `bash -c`'s argument, and `echo '…' | sudo sh` are refused when that text runs holmes-kit. A line whose holmes-kit is only text is allowed (`source .venv/bin/activate && git commit -m "…holmes-kit…"`, `eval "$(ssh-agent -s)" && …`). An unquoted tag's body runs only its `$(…)` and backticks, which are judged as commands; `$VAR`, `${VAR}` and `$((…))` run nothing. `cat >&2 <<'EOF'`, `<<\EOF` and `<<'END-X'` are read correctly. The refusal names the heredoc's tag and the reader its text reaches. Its refusal carries its own code, `line.unread` (permanent: no approval lifts it), whose remediation is the plain line, the file way out, or a quoted heredoc tag (`<<'EOF'`) fed to a read-only program so its body is text.
14
+ - **An agent cannot change its own gate's settings by a write that names `ax.config.json` (A-SPEC-476.8, 476.9).** A write that changes the effective value of any judgement key in `ax.config.json` — raising or lowering, by any write that names the file — needs a `config-write` approval (refused in a run); a shell write to it always does (a write that does not name it, such as `git apply` or `checkout`, a variable or a script, is not judged). An edit that leaves the judgement unchanged, or touches only keys Holmes does not read, passes; lowering one of the two caps stays free. A write through a hard link to a protected file (`ax.config.json`, the harness settings, `.mcp.json` and the other wiring files) is judged as a write to that file, and `ln`/`link` of a protected file is a config write. Texts an agent reads no longer name a judgement key as the fix; they say to ask the owner. Named cost: a shell line that only reads but spells `ax.config.json` in a loop list — `for k in "ax.config.json" …; do echo "$(grep -ci -- "$k" README.md) | $k"; done` — is read as a shell write to it and needs the approval (measured 2026-11-18: allowed by 0.41.2, refused by 0.41.3); reducing it is planned for 0.41.4.
15
+ - **An agent can no longer swap the holmes-kit that governs it by the common package-manager forms (A-SPEC-794.134–794.145; accident prevention, not a boundary).** A package reader judges npm, pnpm, yarn and bun commands that point at holmes-kit. These are the owner's: removing holmes-kit; naming it at a version, range or tag that is not latest and not above the governing one — the governing version itself included — in any package-manager command but a read, or in a runner (npx, pnpx, bunx, `npm exec`, `pnpm dlx`, `yarn dlx`) other than a `report` run; a version computed at run time (`@$V`) or left empty (`@`); a swap (an `npm:` alias, a tarball, a git or path source named holmes-kit); linking it (by name, or a directory whose package.json names it — `npm i -g` with no argument, `.`, `..`); a manifest edit that removes, lowers or swaps its entry, or adds an older one; and a shell write to a package.json that names holmes-kit. Every other command is free, including an unversioned or `@latest` install or update, `holmes-kit upgrade` and a versioned `report` run. The reader looks behind shell keywords and common wrappers and reads here-documents, backtick continuations and ANSI-C quotes in one pass, and re-reads cmd and PowerShell bodies with their own comment rules. Its work budget is under Changed; the forms it does not judge are under Known limitations.
16
+ - **A hook answer that is not a valid decision is refused (A-SPEC-728.4).** The PreToolUse hook writes exactly one answer: the judging worker's own output goes to stderr, and an answer that is not a valid decision (not one JSON object, a wrong event or decision, an exit code that disagrees) is replaced by the gate-error decision — a deny in a governed project; outside one it allows as before. Text printed before the hook's code runs (a `NODE_OPTIONS` preload) is outside its reach.
17
+ - **The routed hook dispatcher refuses a gate that gave no decision (A-SPEC-772.20, 772.22).** With routed wiring (`~/.holmes/runtime`), a gate process that dies by a signal (an out-of-memory kill included) made the dispatcher die by the same signal, and a gate that exited 0 with no output, or answered `null` or `{}`, was forwarded — each of which Claude Code treats as letting the tool through. The dispatcher now refuses them (PreToolUse deny, Stop block for a signal), checking the answer against the gate's own contract; a signal sent to the dispatcher itself still ends it as before. **Routed workspaces get this only after `holmes-kit runtime-binding setup` is run again with this build: it copies the dispatcher into `~/.holmes/runtime`, and `holmes-kit upgrade` does not touch that copy. The setup is the owner's act; `doctor` names a dispatcher that lacks these refusals (A-SPEC-772.25).**
18
+
19
+ ### Added
20
+ - **doctor and workspace_preflight say what a failed hook does to the gate (A-SPEC-772.14).** A new `hook failure posture` line (preflight: `hook-failure`) reads Holmes's Claude Code PreToolUse entries: without `"onFailure": "block"`, a hook that crashes, times out or cannot start lets every tool through, and the model sees no error (measured on Claude Code 2.1.325); with it, every tool is refused, Read included, until a person repairs it. holmes-kit does not write `onFailure` yet. The line reads every settings file Claude Code applies (managed, user, project, local), counts only Holmes's gate entries, and is never PASS while `claude hook switches` says the gate does not run; a target routed through the runtime router, or wired for Codex or Antigravity, gets a `hook failure posture (<surface>)` WARN saying it is not judged and why (A-SPEC-772.18). `claude hook switches` accepts `"onFailure": "block"` on init's gate entry, and `holmes-kit init` keeps it when it rewrites the entry. Until 0.41.4 writes it, add `"onFailure": "block"` yourself; init keeps it.
21
+
22
+ ### Changed
23
+ - **Principle 7 and the runtime binding receipt (A-SPEC-794.131–794.133).** A local-only wiring file (skip-worktree or assume-unchanged), changed only in the working tree and whose bytes match exactly the digest the runtime binding receipt recorded, is no longer an unopened file. The excuse needs the file in all three git reads (baseline, index, HEAD) — a failed read excuses nothing — and leaves an audit row when it passes. A receipt kept outside `~/.holmes/runtime` (a custom `--registry`) excuses nothing. Any other difference is judged as before.
24
+ - **A missing native driver is named before a tool fails (A-SPEC-580.2–580.5).** A missing SQLite driver is its own error with the recovery commands; a reusable graph file is replaced only when SQLite reports it corrupt — never for a missing driver — and `requirement_triage`, spec approval's impact advisory and operator inspection report `driver-unavailable` instead of `unreadable`. `workspace_preflight` gains a `native-driver` check, the MCP launcher warns once on stderr and still starts, and the edit gate's no-analysis reason and `impact_gate_check` give the cause and recovery. These texts ask the owner instead of naming the setting that switches the edit gate off.
25
+ - **Maintenance predictions are scored on their own window (A-SPEC-578.17, 578.18).** test_run's automatic close attributes to each persisted analysis only the commits between its HEAD and the next analysis's HEAD (`window`: `commits`, `superseded`, `unattributable`); the latest analysis stays open until another is persisted, a range too wide or outside a repository is `unattributable`, and a git failure closes nothing. A prediction records `rankedFiles`, and `maintenance_calibration` returns `fileScores` (test files scored apart, micro averages, the precision ceiling, exclusion counts). `falsePositives`/`falseNegatives` leave out `superseded` and `unattributable` outcomes and read the same scorable set as `fileScores`, so they differ from 0.41.2. The schema stays `maintenance-evidence/1.4`.
26
+ - **The package reader has a work budget (A-SPEC-794.147–794.152).** A command's judgement spends work in proportion to its length; for most commands, one past the budget is treated as the owner's rather than judged slowly (a hook that times out lets the write through — the forms that still take seconds are under Known limitations). A command that names holmes-kit and holds more than 20,000 words is the owner's as too large to judge (the longest of 86,000 measured agent commands has 1,553 words), as are wrappers nested more than 64 deep. PowerShell lines read one body after the first `-Command` (measured on Windows PowerShell 5.1: `powershell -c "x" -c "U"` runs `x -c U` as one line), so such a line reads as one command (0.41.2 had no package reader: every such line was free); cmd and PowerShell entry forms measured on Windows are read (abbreviated parameters, slash heads, Unicode dashes, `start` titles and switches, `call`, `@`). The words the reader copies count toward the budget too (A-SPEC-794.151); a copy of up to 1,024 words is free, so ordinary `start` chains are not charged for their length (A-SPEC-794.152).
27
+ - **doctor and the native-driver texts (A-SPEC-580.7–580.12).** A holmes-kit installed with `npm i -g --prefix P` is judged a global install by its layout (`<P>/lib/node_modules` with the file `<P>/bin/holmes-kit`, or one of the files `holmes-kit.cmd`, `holmes-mcp.cmd`, `holmes-kit.ps1` beside `<P>/node_modules` on Windows). Only doctor, which knows npm's default prefix, names `--prefix` (an install under npm's default prefix names none — A-SPEC-580.12): it puts P in its global commands when P holds only letters, digits and `_ . : / -` (and `\` on Windows), and otherwise writes `<PREFIX>` with P on its own line, after the commands, to quote by your shell's rules (holmes builds no shell quoting); a Windows path carries a note that Git Bash needs it quoted. The named driver error, workspace_preflight and the MCP server's start-up line give the plain `-g` commands and say "`holmes-kit doctor` prints the exact command" for a prefix install. Optional and peer dependencies make a project install. With the driver out, impact_gate_check's remediation is the recovery; the bindings error keeps the first path tried; every surface pins the approval command to the installed driver version, and doctor no longer reports the working directory's package version as the driver's.
28
+ - **A release write on a forge is a publish under a full profile (A-SPEC-794.146, 794.147).** A program name with a Windows suffix (`npm.cmd`, `gh.cmd`, `.bat`, `.ps1`) is read as the program (A-SPEC-794.148; measured free before). With the profile's publish flag off, `gh release create|upload|edit|delete|delete-asset`, `hub release create|edit|delete` and `glab release create|upload|update|delete` are refused, and the refusal names the subcommand (`` `gh release create` writes a release ``); with the flag on they pass. Measured 2026-11-15: `gh release create` was free in every profile. Reads (`gh release list|view|download|verify|verify-asset`, `hub release`, `hub release show`, `glab release list|view|download`), help and every other forge subcommand (`gh pr create`, `gh api …`) are unchanged. Without a full profile nothing changes.
29
+
30
+ ### Upgrading
31
+ - Hook commands now name their spec store with `--specs`, so a `HOLMES_SPECS` in the harness's environment no longer chooses it (A-SPEC-772.21).
32
+ - When the `holmes-kit` on PATH is another install than the wired one, a plain `holmes-kit init` needs a `governance-wiring` approval; run the wired install's `bin/holmes-kit.js` or `npx @holmes-lab/holmes-kit init` instead (A-SPEC-772.28).
33
+ - `holmes-kit init --dry-run` with a computed target (`--target "$PWD"`) is refused; write the target out (A-SPEC-772.34).
34
+ - `line.unread` is a permanent refusal: no approval lifts it; write the holmes-kit call as a plain line (A-SPEC-772.33–772.37).
35
+ - A shell write to `ax.config.json` always needs a `config-write` approval; use Edit or Write for a change that keeps the judgement (A-SPEC-476.8).
36
+ - Under a full profile with the publish flag off, `gh`, `hub` and `glab` release writes are refused (A-SPEC-794.146).
37
+ - `maintenance_calibration`'s `falsePositives`/`falseNegatives` count a different set (no `superseded` or `unattributable` outcomes), so they differ from 0.41.2 (A-SPEC-578.17, 578.18).
38
+
39
+ ### Known limitations
40
+ - **The package reader is accident prevention, not a boundary (A-SPEC-794.134–794.145).** It does not judge: an install target or version it cannot read (`npm i -g $(npm pack)`, `"$PWD"`, `$(pwd)`, a name held in a variable, a command passed through `xargs`); a version chosen by configuration (`npm config set tag`, `.npmrc`, `npm_config_*` variables, `--tag`, `--registry`, `--before`); a body fed to a shell (`bash <<EOF`, `… | bash`); a function or a wrapper outside its table (`f() { npm uninstall -g …; }; f`, `gtimeout`, `find -exec`); PowerShell `-EncodedCommand`. The barrier against a deliberate swap is the after-the-fact integrity check planned for 0.41.4.
41
+ - **Lines the hook can still take seconds to judge.** A hook that times out lets the tool through. A `start "" cmd /c …` chain repeated 30 times with a 1,024-word tail took 8–9 seconds in the package reader (measured in A-SPEC-794.153, whose bound was reverted for over-blocking); a line of many heredocs (`cat <<a⏎a⏎` repeated) that names holmes-kit took 0.5–0.8 seconds at about 120 KB and 1.9–3.0 seconds at about 240 KB in the shell-line judgement (measured 2026-11-18 on the shipped build; the cost grows faster than the length).
42
+ - **The rule on shell lines that run holmes-kit is accident prevention, not a boundary (A-SPEC-772.33–772.35).** It judges what one line shows and stops the common ways an agent runs an old or other holmes-kit copy by mistake. A deliberate bypass is not stopped: a program written to a file or passed on stdin by an earlier call, `git fetch --upload-pack`/`clone -u`/`push --receive-pack`, an assignment before a command (`GIT_SSH_COMMAND=…`, `LESSOPEN=…`), a program read from a pipe through `xargs` or `awk`, a program written to a file then run by path or by an interpreter on the file (`./x.sh`, `bash f`, `sh f`, `source f`, `. f`), `find … -exec`, process substitution into a reader (`tee >(bash)`), readers outside the gate's table (`python3.12`, `npx tsx`, `pwsh`, `fish`), a read-only program's run options (`sort --compress-program`), a `<<` inside a comment or arithmetic, and a holmes-kit spelling computed entirely or in part (`npx holmes-$(echo kit)` in a heredoc or pipe body that reaches a reader); a variable assigned from a heredoc and read later is judged only in the leading `NAME=` form (`export`, `local`, `declare`, `readonly` and `A=1 X=…` are not). The heredoc reader differs from bash, and can err either way — refusing a plain line or letting one through: an apostrophe inside a `#` comment carries the quoting on to the next line; a `<<` inside quotes is read as a heredoc; a mixed-quote tag (`E'OF'`); a body with no terminator. Also not read (A-SPEC-772.37 re-review): a reader put on the next line after a pipe's line break; a reader inside a group or subshell (`| (cd d && bash)`, `| { …; sh; }`, `{ cat <<…; } | bash`); a wrapper outside the gate's table or spelled by path (`gtimeout`, `/usr/bin/env bash`, `/usr/bin/sudo`, `setsid`, `caffeinate`); `sudo -s`, `sudo -i`, `sudo -iu root` and `parallel`. The guarantee is planned for 0.41.4: an after-the-fact integrity check of the gate's wiring against its last receipt. The rule's named costs, all only on a line that also names holmes-kit and `init`, `upgrade`, `ledger` or `runtime-binding`: a reader's data argument or stdin is read as code (`python3 x.py "$(cat <<'EOF' …)"`, `rg … | python3 -c …`); a heredoc's receiver that is not a read-only program (`kubectl`, `psql`, `tee`, `ssh`, `timeout 60 cat`) makes its body count.
43
+ - **Forge release writes the gate does not read (A-SPEC-794.146, 794.147).** A REST write through `gh api …/releases`; a tag push (`git push --tags`) — that is a push, judged by the push flag; a Bash-tool Windows wrapper or backslash path around the forge (`cmd /c "gh release create v1"`, `C:\Tools\gh.exe …`) — the same limit as the push and publish reading; a help or version word given as an argument value (`--notes "-h"`) passes as help; hub's global options taking a separated value (`hub --git-dir .git release create`); `gtimeout`. `glab release update` is treated as a write though it was not confirmed against glab's documentation. A gh alias (`gh alias set rc "release create"`, then `gh rc v1`) and a workflow that releases (`gh workflow run release.yml`) pass.
44
+
45
+ ## [0.41.2] - 2026-11-14
46
+
47
+ ### Added
48
+ - **The package carries a per-version release summary, and the release checks it (A-SPEC-795).** `release-history.json` at the package root holds a short Korean and English summary of each release from 0.40.0 on: what it gives its users, the conditions for upgrading, and the limitations that still hold. The Holmes Lab website reads it from the exact published version. `verify-release` now refuses a publish whose file is absent, oversized or not JSON, lacks an entry for the version being published, repeats a version, misses a language, holds placeholder text or an absolute path or host, or is not in the packed artifact. The rules include the website reader's own, so a file the release accepts is one the site accepts. Versions before 0.40.0 have no entry; the website shows them as awaiting a summary. Nothing else in this release changes.
49
+
10
50
  ## [0.41.1] - 2026-11-13
11
51
 
12
52
  ### Fixed
package/README.md CHANGED
@@ -11,8 +11,8 @@
11
11
  <!-- holmes-kit:attest:begin -->
12
12
  ![traced files](.ax/badges/traced.svg)
13
13
 
14
- **565/565** source files (100%) trace to an approved spec · **1272/1379** approved A-SPECs (92.2%) are anchored from code.
15
- Measured at `774b6d166839` (specs `sha256:dcdcb2217da0`) — reproduce with `holmes-kit attest --exclude docs/goals/probes/`.
14
+ **584/584** source files (100%) trace to an approved spec · **1335/1444** approved A-SPECs (92.4%) are anchored from code.
15
+ Measured at `2c4124a10927` (specs `sha256:cfed470e74f3`) — reproduce with `holmes-kit attest --exclude docs/goals/probes/`.
16
16
  <!-- holmes-kit:attest:end -->
17
17
 
18
18
  ### 0.40.x push evidence: the supported surface
@@ -67,6 +67,13 @@ The pre-push gate accepts a full `test_run` as evidence only where holmes can ch
67
67
  ---
68
68
 
69
69
  ### 🛡️ Currently Supported Features (Production Features)
70
+ - **An agent cannot switch off or swap the gate that governs it** *(new in 0.41.3 — gate fix, upgrade recommended; the shell-line rule prevents accidents and is not a security boundary)*:
71
+ - `holmes-kit init`/`upgrade` options that re-wire the gate (`--remove`, `--force`, `--matcher` — `--matcher ".*"` stays free —, `--specs-dir`, `--settings`, `--autonomy`) and re-wiring from another or an older holmes-kit copy need a `governance-wiring` or `config-write` approval. A shell line that runs holmes-kit `init`, `upgrade`, `ledger` or `runtime-binding` in a form the gate cannot read whole is refused (`line.unread`) — write it as a plain line; no approval lifts it. A plain `holmes-kit init` still repairs removed wiring.
72
+ - A package-manager command that removes holmes-kit, names it at a version that is neither latest nor above the governing one (in any command but a read, or in a runner other than a `report` run), swaps or links it, a manifest edit that removes, lowers or swaps its entry, and a shell write to a package.json that names it, are the owner's; an unversioned or `@latest` install and `holmes-kit upgrade` stay free. The reader has a work budget: for most commands, one past it is the owner's rather than judged slowly. This reader is accident prevention, not a security boundary; the CHANGELOG names the forms it does not judge.
73
+ - A write that changes a judgement key of `ax.config.json` — in either direction, by any write that names the file, a hard link included — is the owner's; a write that does not name it (`git apply`, a checkout, a variable, a script) is not judged; lowering `semantic.maxTier` or `autonomy.ceiling` stays free.
74
+ - A hook answer that is not a valid decision is refused in a governed project (the judging worker's own output goes to stderr), and so is a routed gate that died by a signal or gave no valid decision (routed workspaces: run `holmes-kit runtime-binding setup` again). `doctor` and `workspace_preflight` report whether a failed hook lets tools through (doctor: `hook failure posture`; preflight: `hook-failure`).
75
+ - The CHANGELOG's Known limitations name the forms the gate does not read; an after-the-fact integrity check is planned for 0.41.4.
76
+ - **A prediction is scored on its own window** *(new in 0.41.3)*: `test_run`'s automatic close attributes to each persisted `maintenance_analyze` only the commits up to the next analysis, and `maintenance_calibration` returns `fileScores` (test files scored apart, the precision ceiling).
70
77
  - **The gate says what it judges, and run start judges what wiring launches** *(new in 0.40.0)*:
71
78
  - **A shell command that builds a path into `.ax` while it runs** is judged by the same not-a-read rule as one that names a protected path. The refusal says how the command was read and what to do first. This rule prevents accidents; its resistance to forgery has not been verified. Replaying 1,000 commands agents really wrote against 0.39's rules on the real hook, two samples gave 1 and 4 newly refused (0.1% and 0.4%). That corpus ran on the Claude Code input shape only.
72
79
  - **`run start`** passes `mcp` and `gate` only for what launches holmes-kit's own entries, not for wiring that merely names it (breaking). `--provision` now covers a Codex worktree's MCP table; Antigravity run start is refused until its loading of a linked worktree's `.agents` is measured (breaking).
@@ -85,7 +92,7 @@ The pre-push gate accepts a full `test_run` as evidence only where holmes can ch
85
92
  - A seal the grader hands to a person seals as `full-autonomy:`. An un-admitted REQ or an undeclared or unknown grade is refused, and the refusal names its fix.
86
93
  - A workspace-local destructive git act, or an `rm -rf` inside the scope, passes after a restorable recovery point is written under `refs/holmes/full/`.
87
94
  - Every other act the gate already refuses is refused with a route and never queued: secrets, config, approval or ledger writes (in the forms the gate's text judgement recognises), and a recursive delete outside the scope. Outside spec staging, a headless benchmark run does not wait on a person.
88
- - **BREAKING: push and publish follow the flags** *(new in 0.40.0)*. A `git push` or `npm publish` the gate reads in the command's clauses is refused without `--allow-push` or `--allow-publish`, and a grant does not lift it. A help or dry-run form passes, except that a force push with such a flag is still refused while the push flag is off. The gate reads a limited set of command forms; the CHANGELOG's Known limitations name the classes it does not read. A registry write is read where a program takes its subcommand *(0.41)*: `npm publish`, `npm dist-tag add`, a release tool, or a package script that runs one, read from the `package.json` npm would use; the words a program takes as data (`git commit -m "…publish…"`, `gh pr create --body …`, `grep publish`) are never searched. It prevents accidents and does not stop a determined agent — keep two-factor authentication required for publishing on the npm account, and give agents a token without publish rights. Known limits of that reading *(0.41)*: a program the gate's table does not list that runs one of its string arguments as a command; shell functions and aliases; script files a command runs (`./release.sh`, `source`); make variables; words assembled at run time (`npm ${V}lish`); packages inside git-ignored directories; a one-line `case`; `npx -c` or `npm exec -c` behind a wrapper; option variants around `bash -c`; rare wrapper subcommands (`launchctl asuser`, `nix shell -c`); a git alias that pushes without `!`; `foreach` after `git submodule` options; `git subtree push`, `hub push`, `git send-pack`, `git svn dcommit`, `p4 submit`; `script -c` and `flock -c`; `parallel :::`; variable variants (`builtin`/`command` prefixes, `printf -vW`, `${W/a/b}`, CDPATH); `sudo -D` and `--chdir`; contradicting dry-run flag pairs; option-value positions in `git push`; nested git repositories; yarn v1's `publish --dry-run` semantics; a package name after an npm `--no-*` flag that matches a write abbreviation; run valued options outside the gate's table; npm options after `--`; `mise -c`/`--command` and `mise --cd <dir>`; a script run inside an unknown program; wrappers nested nine deep or more; a command of more than 100,000 words; the `.ax` working-directory test harness; the directory where `npm exec -w <ws> -c '…'` runs its `-c` command; a yarn publish option outside the gate's table whose value is read as the folder; valued options after a bare `yarn` outside the table (`--https-proxy`, `--preferred-cache-folder`); a global install whose argument is not literal or is a `file:` spec (`npm i -g "$PWD"`, `$(pwd)`, `file:.`), and `-g --omit dev`; the directory `.` names in `npm i -g --prefix <dir> .`; the aliases `pnpm install-test`/`it`, `pnpm t` and `bun a`. A command too large to judge — more than 400,000 words, a clause of more than 20,000 words, more than 2,000 package directories read, more than eight readings of options the gate does not know, or more than 900 ms — is refused under a full profile whatever its push and publish flags, with its size named and the advice to split it (the longest of 86,000 measured agent commands has 1,553 words). The "more than 100,000 words" limit above is the shell lexer's, where the gate stops reading structure; this budget is the outward judgement's own. Subshell groups nested more than 64 deep are closed the same way, and a refusal lists at most 200 findings and counts the rest. The 1-second bound is the outward judgement's; the hook's whole time on a 1 MB command also includes the other gates (1.3–1.8 s measured). Known limit: in a project that holds no spec file yet, a gate error (a deadline, a crash) lets the command through, so a deadline there does not stop an outward act. In a program it does not know, only standalone words are read (`mytool npm publish` is refused, `claude -p "…npm publish…"` is not). The barrier to an outward act is npm's 2FA and the profile's push flag. With or without the flag, in a repository holding a spec change that no approval staged, the spec-change check refuses a push first, a command that only names a push included; a publish has no such check. Issuing a profile again replaces every flag: one issued with `--no-architecture` returns to approving architecture documents unless the flag is named again.
95
+ - **BREAKING: push and publish follow the flags** *(new in 0.40.0)*. A `git push`, an `npm publish` or a forge release write (`gh release create|upload|edit|delete|delete-asset`, `hub release create|edit|delete`, `glab release create|upload|update|delete` *(0.41.3)*) the gate reads in the command's clauses is refused without `--allow-push` or `--allow-publish`, and a grant does not lift it. A help or dry-run form passes, except that a force push with such a flag is still refused while the push flag is off. The gate reads a limited set of command forms; the CHANGELOG's Known limitations name the classes it does not read. A registry write is read where a program takes its subcommand *(0.41)*: `npm publish`, `npm dist-tag add`, a release tool, or a package script that runs one, read from the `package.json` npm would use; the words a program takes as data (`git commit -m "…publish…"`, `gh pr create --body …`, `grep publish`) are never searched. It prevents accidents and does not stop a determined agent — keep two-factor authentication required for publishing on the npm account, and give agents a token without publish rights. Known limits of that reading *(0.41)*: a program the gate's table does not list that runs one of its string arguments as a command; shell functions and aliases; script files a command runs (`./release.sh`, `source`); make variables; words assembled at run time (`npm ${V}lish`); packages inside git-ignored directories; a one-line `case`; `npx -c` or `npm exec -c` behind a wrapper; option variants around `bash -c`; rare wrapper subcommands (`launchctl asuser`, `nix shell -c`); a git alias that pushes without `!`; `foreach` after `git submodule` options; `git subtree push`, `hub push`, `git send-pack`, `git svn dcommit`, `p4 submit`; `script -c` and `flock -c`; `parallel :::`; variable variants (`builtin`/`command` prefixes, `printf -vW`, `${W/a/b}`, CDPATH); `sudo -D` and `--chdir`; contradicting dry-run flag pairs; option-value positions in `git push`; nested git repositories; yarn v1's `publish --dry-run` semantics; a package name after an npm `--no-*` flag that matches a write abbreviation; run valued options outside the gate's table; npm options after `--`; `mise -c`/`--command` and `mise --cd <dir>`; a script run inside an unknown program; wrappers nested nine deep or more; a command of more than 100,000 words; the `.ax` working-directory test harness; the directory where `npm exec -w <ws> -c '…'` runs its `-c` command; a yarn publish option outside the gate's table whose value is read as the folder; valued options after a bare `yarn` outside the table (`--https-proxy`, `--preferred-cache-folder`); a global install whose argument is not literal or is a `file:` spec (`npm i -g "$PWD"`, `$(pwd)`, `file:.`), and `-g --omit dev`; the directory `.` names in `npm i -g --prefix <dir> .`; the aliases `pnpm install-test`/`it`, `pnpm t` and `bun a`. A command too large to judge — more than 400,000 words, a clause of more than 20,000 words, more than 2,000 package directories read, more than eight readings of options the gate does not know, or more than 900 ms — is refused under a full profile whatever its push and publish flags, with its size named and the advice to split it (the longest of 86,000 measured agent commands has 1,553 words). The "more than 100,000 words" limit above is the shell lexer's, where the gate stops reading structure; this budget is the outward judgement's own. Subshell groups nested more than 64 deep are closed the same way, and a refusal lists at most 200 findings and counts the rest. The 1-second bound is the outward judgement's; the hook's whole time on a 1 MB command also includes the other gates (1.3–1.8 s measured). Known limit: in a project that holds no spec file yet, a gate error (a deadline, a crash) lets the command through, so a deadline there does not stop an outward act. In a program it does not know, only standalone words are read (`mytool npm publish` is refused, `claude -p "…npm publish…"` is not). The barrier to an outward act is npm's 2FA and the profile's push flag. With or without the flag, in a repository holding a spec change that no approval staged, the spec-change check refuses a push first, a command that only names a push included; a publish has no such check. Issuing a profile again replaces every flag: one issued with `--no-architecture` returns to approving architecture documents unless the flag is named again.
89
96
  - **Not judged.** A plain write outside the scope gets no decision, so REQ-792's criterion that such an act is refused is not met in 0.40.0.
90
97
  - **Revoking.** `--revoke` ends the profile.
91
98
  - **The agent does not type approval commands.** The agent's refusal tells it to call `approval_ask` with the id. The operator's own screens (the non-TTY hint and the refusal-log footer) still print an `approve --grant <id>` line for a person to paste.
@@ -96,8 +103,9 @@ The pre-push gate accepts a full `test_run` as evidence only where holmes can ch
96
103
  - **Agents clean up their own temporary work** *(new in 0.35.25)*: `holmes-kit scratch --new <label>` makes a directory under a per-user Holmes scratch root (`os.tmpdir()/holmes-scratch-<uid>`, mode 0700), and on macOS and Linux the gate lets an agent in Claude Code, Codex or Antigravity remove it with one plain `rm -rf <absolute path>` without an operator act; the root itself, tracked source, every other path and any compound command keep their verdict. Where another holmes-kit install sits in an ancestor `node_modules` of the workspace or the home directory (npm, Windows shims and pnpm alike), approval hints name the running install's own path so that copy cannot answer them (a PowerShell form on Windows), and doctor's `npx resolution` row names it.
97
104
  - **You can tell whether a harness's gate actually ran here** *(new in 0.35.24)*: the PreToolUse and Stop hooks of Claude Code, Codex and Antigravity leave a git-ignored per-harness record (`.ax/state/hook-heartbeat/`, at most one write a minute, never part of a decision). `workspace_preflight` with `harness` passes `runtime-enforcement` only after that harness's PreToolUse gate was observed within 24 h and since its wiring last changed; doctor shows one `hook observed (<harness>)` row each; `runtime-binding status` reports `activation` for this selection's gate and names every other observation and an outdated deployed dispatcher. `runtime_binding` answers an unbound workspace with its routing instead of "not registered", init states a Codex verdict for registry-owned Codex files, and doctor FAILs a running Stop hook under 75 s. Measured need: a Codex session in a release-routed workspace concluded it was ungoverned.
98
105
  - **A benchmark run the operator pre-approved finishes with zero human waits — the run delegation** *(new in 0.35.19)*: `holmes-kit autonomy delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]` (same human proof as `autonomy on`) writes a run-scoped, workspace-bound (realpath), expiring delegation that covers a closed set of autonomy-grader rules — root-only or gate-file Files to Touch, an undirected gate-behavior grade, an upstream without A-SPEC; never architecture documents, un-admitted requirements, undeclared or unknown grades. A hitl spec whose only reason is a covered rule seals on its own with `source: 'delegated'` and a ledger row naming the run and the rule; an uncovered case refuses with the named limit (`does not cover`, `expired`, `for <workspace>, not this root`, `invalid document`). `autonomy status`, `approve --status` and the session-start banner show it; `revoke-delegation` or `off` ends it. The host's own approval layer is named as not covered. Measured need: X1 (2026-10-12) stopped a pre-approved fixture on `files-to-touch-root-only`. Every operator hint now also names the workspace (`--target <root>`), a context-only Codex patch is refused as a no-op by name, and `runtime-binding status`/`doctor` report a Codex lifecycle routed to Holmes from both the user-level and the workspace hooks file.
106
+ - **Each release carries its own summary** *(new in 0.41.2)*: `release-history.json` at the package root holds a short Korean and English summary of each release from 0.40.0 on (benefits, upgrade conditions, limitations), which the Holmes Lab website reads from the exact published version. The release gate refuses a publish without a valid entry for its own version.
99
107
  - **The ledger has a witness the tree cannot move** *(new in 0.41)*: in Holmes-Kit's own repository (and for a package that is not npm-installed), the gate reads its provenance chain only when the chain is the one this repository wrote — a witness in the git directory, moved by every append, says so. A chain taken back by a checkout or a stash, or extended by rows brought in from outside, closes the judgement until the tree returns or a person vouches (`holmes-kit ledger witness`). A new checkout starts closed until a person vouches once.
100
- - **The gate and approval-processing source is sealed by a person** *(new in 0.41)*: a spec whose Files to Touch names a module that reads or writes a grant, an actor, a seal or a decision (the hooks, guardrail and governance code, the approval CLI and MCP handlers, review verdicts, runtime dispatch, the spec transition policy) is sealed only by a person — no declared grade, run delegation or full profile seals it; a census test keeps the category whole. Such a file is also *written* only within 12 hours (`autonomy.sealWindowHours`, 1–24) of a person's seal of an approved A-SPEC whose Files to Touch names it — in the session form (or a host's approval dialog); a seal spent from a grant file does not count, since a file write can make one — and each write a window opens is recorded in the ledger; an anchor already in the file, or an older seal, opens nothing. Whatever wrote it, a gate-file change since the live gate's baseline (the commit the gate last built, recorded in the ledger) — in the working tree, the index or a commit — that no window names blocks the turn's end, a commit and a build. It stays blocked until a person seals a spec naming it, a branch switch or pull that brought it is undone, or the file is made equal to the baseline again; a commit made outside the gate (an owner's terminal commit, a pull) is judged the same way, and the refusal warns first that a restore from the baseline also discards such commits (Holmes-Kit's own repository; it prevents accidents, forgery resistance is not verified).
108
+ - **The gate and approval-processing source is sealed by a person** *(new in 0.41)*: a spec whose Files to Touch names a module that reads or writes a grant, an actor, a seal or a decision (the hooks, guardrail and governance code, the approval CLI and MCP handlers, review verdicts, runtime dispatch, the spec transition policy) is sealed only by a person — no declared grade, run delegation or full profile seals it; a census test keeps the category whole. Such a file is also *written* only within 12 hours (`autonomy.sealWindowHours`, 1–24) of a person's seal of an approved A-SPEC whose Files to Touch names it — in the session form (or a host's approval dialog); a seal spent from a grant file does not count, since a file write can make one — and each write a window opens is recorded in the ledger; an anchor already in the file, or an older seal, opens nothing. Whatever wrote it, a gate-file change since the live gate's baseline (the commit the gate last built, recorded in the ledger) — in the working tree, the index or a commit — that no window names blocks the turn's end, a commit and a build. It stays blocked until a person seals a spec naming it, a branch switch or pull that brought it is undone, or the file is made equal to the baseline again; a commit made outside the gate (an owner's terminal commit, a pull) is judged the same way, and the refusal warns first that a restore from the baseline also discards such commits (Holmes-Kit's own repository; it prevents accidents, forgery resistance is not verified). A local-only wiring file (skip-worktree or assume-unchanged), changed only in the working tree, whose bytes are exactly what the runtime binding receipt recorded is not an unopened file *(0.41.3)*.
101
109
  - **Un-seal and retire are decisions of their own** *(new in 0.41)*: `spec-unseal` and `spec-retire` are approval kinds of their own (a seal's approval does not cover them), every path names a transition's kind from one table, and a seal records the MCP server instance that made it.
102
110
  - **An autonomy profile is issued only through its own request** *(new in 0.41)*: a command that sets an out-of-band approval itself before `holmes-kit autonomy full|on|delegate` is refused as `profile.own-request` and files nothing; the request the plain command files names the flags it changes.
103
111
  - **Sealed specs are staged without a person** *(new in 0.41)*: under a full profile, staging a spec whose seal holds, whose parents are sealed and pinned, which sits where its type and id say, and whose Files to Touch stay outside the gate category is approved by the gate itself (R1). A spec that touches the gate, a draft, or a broken chain still goes to the person's form; `autonomy.specStaging: "off"` restores the form for all.
@@ -291,7 +299,23 @@ text (`EPERM mkdir`, `notarget`, `better-sqlite3` build failures).
291
299
  **Prerequisites** — Node.js `>= 20.0.0`. The 8 tree-sitter grammars ship prebuilt binaries for
292
300
  macOS/Linux/Windows and compile nothing; `better-sqlite3` downloads a prebuild at install time,
293
301
  falling back to compiling — only that fallback needs a C++ toolchain (VS Build Tools / Xcode CLT /
294
- `apk add python3 make g++`).
302
+ `apk add python3 make g++`). **npm 12 skips dependency install scripts that `allowScripts` does not
303
+ cover.** npm's docs say a global install has "no project `package.json` to write to" and point to the
304
+ install-time `--allow-scripts` flag or a user-level setting; the 0.41.2 field install was blocked with
305
+ `allowScripts` present. So after `npm install -g` the driver may never be built and every graph tool fails
306
+ ("Could not locate the bindings file"). Rebuild it, then restart the MCP server:
307
+ - global install: `npm rebuild -g better-sqlite3 --foreground-scripts --allow-scripts=better-sqlite3`
308
+ (installed with a prefix, `npm i -g --prefix P`? `holmes-kit doctor` prints the exact command — it alone names `--prefix`, and a path with a space or shell character appears as `<PREFIX>` with the path on its own line)
309
+ (or install with `npm install -g @holmes-lab/holmes-kit --allow-scripts=better-sqlite3`, or persist it
310
+ with `npm config set allow-scripts=better-sqlite3 --location=user`);
311
+ - project install: `npm install-scripts approve better-sqlite3`, then
312
+ `npm rebuild better-sqlite3 --foreground-scripts` (npm refuses `--allow-scripts` on a project rebuild).
313
+
314
+ On Windows use `npm.cmd`, and run the two project commands as two lines (PowerShell 5.1 does not accept
315
+ `&&`). If the driver cannot be rebuilt on a machine (no rights over the global prefix), the owner can set
316
+ `guardrail.preEditEvidence` in `ax.config.json` to `warn` until it is; an agent cannot change that setting
317
+ (it is the owner's, *new in 0.41.3*), and the texts an agent reads only tell it to ask the owner. `holmes-kit doctor` and `workspace_preflight` (check `native-driver`) report the cause, which differs
318
+ for a Node upgrade (rebuild for the new Node) and a binary from another platform *(new in 0.41.3)*.
295
319
 
296
320
  ### 2. Initialize in Your Project
297
321
  ```bash
package/bin/holmes-mcp.js CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- // @implements A-SPEC-162
2
+ // @implements A-SPEC-162, A-SPEC-580.3, A-SPEC-580.4, A-SPEC-580.7, A-SPEC-580.8, A-SPEC-580.9, A-SPEC-580.10
3
3
  // @implements A-SPEC-173
4
4
  // The guard runs BEFORE the require, using only Node built-ins — see bin/holmes-kit.js. The wording
5
5
  // is duplicated rather than shared: reading it from `dist` is exactly the dependency that fails here.
@@ -19,6 +19,41 @@ if (!fs.existsSync(entry)) {
19
19
  process.exit(1);
20
20
  }
21
21
 
22
+ // @implements A-SPEC-580.3 — every graph tool needs the native SQLite driver. npm 12 skips its install script on a
23
+ // global install (Windows field case, 2026-11-15), so say it once at start, on stderr, and still start: the spec
24
+ // tools and approvals work without it.
25
+ // @implements A-SPEC-580.4 — the commands come from the one source in dist (project/native-recovery), joined for this
26
+ // platform's shell; dist exists here (checked above).
27
+ function recoveryLines() {
28
+ try {
29
+ const { nativeRecovery, joinCommands } = require('../dist/holmes/project/native-recovery.js');
30
+ // A-SPEC-580.7: pinned to the installed driver version, as the other surfaces pin it
31
+ let packageVersion = '';
32
+ try { packageVersion = String(require('better-sqlite3/package.json').version || ''); } catch { /* unknown → unpinned */ }
33
+ // A-SPEC-580.10: no `--prefix` here (only doctor knows npm's default prefix); the sentence sends a prefix install
34
+ // to doctor
35
+ const r = nativeRecovery({ platform: process.platform, packageName: 'better-sqlite3', packageVersion });
36
+ return ` global install: ${joinCommands(r.global, process.platform)}\n`
37
+ + ` project install: ${joinCommands(r.project, process.platform)}\n`
38
+ + ' then restart the MCP server; holmes-kit doctor names the cause.\n'
39
+ + ' Installed with a prefix (`npm i -g --prefix P`)? `holmes-kit doctor` prints the exact command.\n';
40
+ } catch { return ' holmes-kit doctor names the cause and the command that repairs it.\n'; } // an older dist without the module
41
+ }
42
+ // @implements A-SPEC-580.8 — the line the named error and doctor print (bindings' first path tried); an older dist keeps
43
+ // the first line
44
+ function observedFirst(e) {
45
+ const message = String((e && e.message) || e);
46
+ try { return require('../dist/holmes/rtm/native-driver.js').observedLine(message); }
47
+ catch { return message.split(/\r?\n/)[0].replace(/^\\\\\?\\/, ''); }
48
+ }
49
+ try {
50
+ const Database = require('better-sqlite3');
51
+ new Database(':memory:').close();
52
+ } catch (e) {
53
+ const first = observedFirst(e);
54
+ process.stderr.write(`[Holmes-Kit] native SQLite driver unavailable — graph tools will fail: ${first}\n${recoveryLines()}`);
55
+ }
56
+
22
57
  // Opt-in only. Without HOLMES_MCP_AUTORELOAD this is the same direct require it has always been —
23
58
  // swapping the implementation under a shipped user mid-session would be an undeclared change in gate
24
59
  // behaviour, which ADR-013 forbids.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 35d54f07-mwfu2hez
1
+ 2333b5c7-mwnqk74f
@@ -87,6 +87,15 @@ export interface ClaudeSwitches {
87
87
  gateScripts: string[];
88
88
  /** Round 40: files wiring Holmes's other hooks with no Holmes PreToolUse gate anywhere Claude applies. */
89
89
  noGate: string[];
90
+ /**
91
+ * A-SPEC-772.18: the gate entries Claude runs (every shape), how many carry `onFailure: "block"`, and their files — what
92
+ * the hook failure posture words.
93
+ */
94
+ gateFailure: {
95
+ entries: number;
96
+ blocking: number;
97
+ files: string[];
98
+ };
90
99
  }
91
100
  /**
92
101
  * @implements A-SPEC-251.2 (round 50) — `planned`: settings files by path with the content init is about to write, judged in
@@ -62,6 +62,7 @@ const os = __importStar(require("node:os"));
62
62
  const path = __importStar(require("node:path"));
63
63
  const bounded_io_1 = require("../project/bounded-io");
64
64
  const codex_oracle_1 = require("./codex-oracle");
65
+ const holmes_hook_id_1 = require("./holmes-hook-id");
65
66
  /** The managed-settings folders Claude Code reads on each platform. */
66
67
  function managedSettingsDirs(platform = process.platform) {
67
68
  if (platform === 'darwin')
@@ -555,9 +556,8 @@ function isAbsoluteScript(p) {
555
556
  }
556
557
  /** Matchers under which the gate sees every tool (Claude reads an absent, empty or `*` matcher as all; `.*` is init's). */
557
558
  const ALL_TOOLS = new Set(['', '*', '.*']);
558
- /** A hook entry that names Holmes's gate in any shape (command text or exec-form `args`). */
559
- const namesGate = (h) => [h.command, ...(Array.isArray(h.args) ? h.args : [])]
560
- .some((x) => typeof x === 'string' && /dist[/\\]holmes[/\\]hooks[/\\]pre-tool-use\.js|\bholmes-pre-tool-use\b/.test(x));
559
+ /** A hook entry that names Holmes's gate in any shape (command text or exec-form `args`) — A-SPEC-772.18: one module. */
560
+ const namesGate = holmes_hook_id_1.namesHolmesGate;
561
561
  /**
562
562
  * The Holmes gate entries of a file's loadable PreToolUse groups (after Claude's cleaning): the canonical entry, one Claude
563
563
  * does not wait for (`async`/`asyncRewake` — backgrounded; PreToolUse is never forced synchronous), one that runs only under
@@ -579,12 +579,13 @@ function gateEntries(v, file, managed) {
579
579
  const keys = Object.keys(h);
580
580
  // Round 40: under a matcher that lets every tool through, and with nothing the shell rewrites inside the quotes.
581
581
  const canonical = h.type === 'command' && typeof h.command === 'string' && CANONICAL_GATE.test(h.command)
582
- && !SHELL_SPECIAL_IN_QUOTES.test(h.command) && keys.every((k) => k === 'type' || k === 'command')
582
+ // @implements A-SPEC-772.18 — and `onFailure: "block"`, the posture's own advice (it read "another shape", WARN)
583
+ && !SHELL_SPECIAL_IN_QUOTES.test(h.command) && keys.every((k) => k === 'type' || k === 'command' || (k === 'onFailure' && h.onFailure === 'block'))
583
584
  && ALL_TOOLS.has(typeof g.matcher === 'string' ? g.matcher : '')
584
585
  && isAbsoluteScript(/^node "([^"]*)"/.exec(h.command)?.[1] ?? '');
585
586
  const kind = canonical ? 'canonical' : h.async === true || h.asyncRewake === true ? 'background'
586
587
  : typeof h.if === 'string' && h.if !== '' ? 'conditional' : 'other';
587
- out.push({ kind, file, managed, ...(canonical ? { script: /^node "([^"]*)"/.exec(h.command)?.[1] } : {}) });
588
+ out.push({ kind, file, managed, blocking: h.onFailure === 'block', ...(canonical ? { script: /^node "([^"]*)"/.exec(h.command)?.[1] } : {}) });
588
589
  }
589
590
  }
590
591
  return out;
@@ -595,8 +596,7 @@ function holdsHolmes(v, depth = 0) {
595
596
  return false;
596
597
  if (Array.isArray(v))
597
598
  return v.some((x) => holdsHolmes(x, depth + 1));
598
- const c = v.command;
599
- if (typeof c === 'string' && /dist[/\\]holmes[/\\]hooks[/\\](pre-tool-use|stop|session-start)\.js|\bholmes-(kit|mcp|pre-tool-use|stop)\b/.test(c))
599
+ if ((0, holmes_hook_id_1.isHolmesCommand)(v.command))
600
600
  return true;
601
601
  return Object.values(v).some((x) => holdsHolmes(x, depth + 1));
602
602
  }
@@ -742,7 +742,8 @@ function claudeSwitches(target, env = claudeSwitchEnv(), planned) {
742
742
  const canonical = canonicalLocalSettingsPath(target, env.home);
743
743
  if (canonical !== null)
744
744
  sources.push({ file: canonical, managed: false });
745
- const out = { hooksOff: [], toolsOff: [], unreadable: [], notApplied: [], unconfirmed: [], spared: [], gateScripts: [], noGate: [] };
745
+ const out = { hooksOff: [], toolsOff: [], unreadable: [], notApplied: [], unconfirmed: [], spared: [], gateScripts: [], noGate: [],
746
+ gateFailure: { entries: 0, blocking: 0, files: [] } };
746
747
  // Round 40: switches that turn every hook off (a managed `disableAllHooks`) and those that spare managed hooks.
747
748
  const offAll = [];
748
749
  const offNonManaged = [];
@@ -885,6 +886,8 @@ function claudeSwitches(target, env = claudeSwitchEnv(), planned) {
885
886
  const nonBlocking = live.filter((e) => e.kind === 'background' || e.kind === 'conditional');
886
887
  appliedHolmes = confirmed || other.length > 0;
887
888
  out.gateScripts.push(...new Set(live.filter((e) => e.kind === 'canonical').map((e) => e.script ?? '')));
889
+ // @implements A-SPEC-772.18 — every gate entry Claude runs, in the files Claude applies
890
+ out.gateFailure = { entries: live.length, blocking: live.filter((e) => e.blocking).length, files: [...new Set(live.map((e) => e.file))] };
888
891
  const said = (e) => e.kind === 'background'
889
892
  ? `${e.file} (a Holmes gate entry that runs in the background — async — so Claude does not wait for it)`
890
893
  : e.kind === 'conditional' ? `${e.file} (a Holmes gate entry that runs only when its \`if\` condition matches)`
@@ -177,7 +177,7 @@ export declare function npmHome(home?: string): string | undefined;
177
177
  * how we look, never whether a real miss is reported.
178
178
  */
179
179
  export declare function resolveDepDir(fromRoot: string, name: string): string | null;
180
- export declare function gatherNativeEvidence(packageRoot: string, target?: string): NativeEvidence;
180
+ export declare function gatherNativeEvidence(packageRoot: string, target?: string, npmPrefix?: () => string | undefined): NativeEvidence;
181
181
  /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
182
182
  export declare function probeEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
183
183
  /** Seam for the gate probe's child process. Default is a real `spawnSync`; tests inject a fake. */
@@ -202,6 +202,12 @@ export interface ProbeRunner {
202
202
  * stays empty — resolving it would conjure the target directory itself into a "file that exists".
203
203
  */
204
204
  export declare function resolveWiringPath(target: string, arg: string): string;
205
+ /**
206
+ * @implements A-SPEC-580.10 — doctor's `node version` line, its own function so a test can hold it: the driver's
207
+ * declared range, read from the driver directory only (A-SPEC-580.9: with none, nothing is read — `?? ''` had read the
208
+ * working directory's package.json).
209
+ */
210
+ export declare function nodeVersionCheck(packageRoot: string): Check;
205
211
  export declare function runDoctor(packageRoot: string, target?: string, opts?: DoctorOptions, extraChecks?: Check[]): Promise<Check[]>;
206
212
  export declare function resetWiringSpawns(): void;
207
213
  export declare function wiringSpawnShared(command: string, args: string[], cwd: string): Promise<Check>;
@@ -46,6 +46,7 @@ exports.resolveDepDir = resolveDepDir;
46
46
  exports.gatherNativeEvidence = gatherNativeEvidence;
47
47
  exports.probeEnv = probeEnv;
48
48
  exports.resolveWiringPath = resolveWiringPath;
49
+ exports.nodeVersionCheck = nodeVersionCheck;
49
50
  exports.runDoctor = runDoctor;
50
51
  exports.resetWiringSpawns = resetWiringSpawns;
51
52
  exports.wiringSpawnShared = wiringSpawnShared;
@@ -75,7 +76,7 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
75
76
  exports.semanticCoverageCheck = semanticCoverageCheck;
76
77
  exports.semanticTierVerdict = semanticTierVerdict;
77
78
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
78
- // @implements A-SPEC-794.113, A-SPEC-794.110, A-SPEC-794.59, A-SPEC-794.55, A-SPEC-792.46, A-SPEC-792.48, A-SPEC-245.8, A-SPEC-251.5, A-SPEC-476.1, A-SPEC-476.5, A-SPEC-751.4, A-SPEC-751.9, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.9, A-SPEC-770.10,A-SPEC-733,A-SPEC-727, A-SPEC-774.22, A-SPEC-781.2, A-SPEC-182.3, A-SPEC-182.4,A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-102.28, A-SPEC-102.29
79
+ // @implements A-SPEC-772.25, A-SPEC-772.16, A-SPEC-772.14,A-SPEC-580.12, A-SPEC-580.10, A-SPEC-580.9, A-SPEC-580.8, A-SPEC-794.113, A-SPEC-794.110, A-SPEC-794.59, A-SPEC-794.55, A-SPEC-792.46, A-SPEC-792.48, A-SPEC-245.8, A-SPEC-251.5, A-SPEC-476.1, A-SPEC-476.5, A-SPEC-751.4, A-SPEC-751.9, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.9, A-SPEC-770.10,A-SPEC-733,A-SPEC-727, A-SPEC-774.22, A-SPEC-781.2, A-SPEC-182.3, A-SPEC-182.4,A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-102.28, A-SPEC-102.29
79
80
  // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712, A-SPEC-769.14, A-SPEC-769.16, A-SPEC-769.17, A-SPEC-769.18, A-SPEC-769.19, A-SPEC-769.20, A-SPEC-769.21
80
81
  const doctor_guidance_1 = require("./doctor-guidance");
81
82
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
@@ -611,16 +612,22 @@ function resolveDepDir(fromRoot, name) {
611
612
  return null;
612
613
  }
613
614
  }
614
- function gatherNativeEvidence(packageRoot, target = process.cwd()) {
615
+ // @implements A-SPEC-580.12 — `npmPrefix` injects npm's default prefix (tests: jest's env does not reach the npm child);
616
+ // absent, npm is asked as before
617
+ function gatherNativeEvidence(packageRoot, target = process.cwd(), npmPrefix) {
615
618
  const name = 'better-sqlite3';
616
619
  // @implements A-SPEC-583.1 — resolved, not joined. A hoisted install is the npm default.
617
620
  const pkgDir = resolveDepDir(packageRoot, name);
618
621
  const bindingPresent = pkgDir !== null && fs.existsSync(path.join(pkgDir, 'build', 'Release', 'better_sqlite3.node'));
619
- let packageVersion = '(unknown)';
620
- try {
621
- packageVersion = JSON.parse(fs.readFileSync(path.join(pkgDir ?? '', 'package.json'), 'utf8')).version ?? packageVersion;
622
+ let packageVersion = ''; // A-SPEC-580.8: unread → the unpinned command, as on the other surfaces
623
+ // A-SPEC-580.8: with no driver directory there is no version — `path.join('', 'package.json')` read the working
624
+ // directory's package.json and reported its version as the driver's
625
+ if (pkgDir !== null) {
626
+ try {
627
+ packageVersion = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8')).version ?? packageVersion;
628
+ }
629
+ catch { /* not installed */ }
622
630
  }
623
- catch { /* not installed */ }
624
631
  let loadError;
625
632
  try {
626
633
  const Database = require(name);
@@ -634,8 +641,9 @@ function gatherNativeEvidence(packageRoot, target = process.cwd()) {
634
641
  const npmCli = npmCliEntry(process.env, process.execPath, probeContext(target).keep);
635
642
  const npmVersion = npmCli !== null ? observe(process.execPath, [npmCli, '--version', ...NPM_QUIET], npmHome()) : observe('npm', ['--version', ...NPM_QUIET], npmHome());
636
643
  const npmMajor = npmVersion !== undefined && /^\d+/.test(npmVersion) ? Number(npmVersion.match(/^\d+/)[0]) : undefined;
637
- const prefix = npmCli !== null ? observe(process.execPath, [npmCli, 'config', 'get', 'prefix', ...NPM_QUIET], npmHome()) : observe('npm', ['config', 'get', 'prefix', ...NPM_QUIET], npmHome());
644
+ const prefix = npmPrefix !== undefined ? npmPrefix() : npmCli !== null ? observe(process.execPath, [npmCli, 'config', 'get', 'prefix', ...NPM_QUIET], npmHome()) : observe('npm', ['config', 'get', 'prefix', ...NPM_QUIET], npmHome());
638
645
  const kind = (0, native_deps_1.installKind)(packageRoot, prefix ? globalInstallDir(prefix, process.platform) : undefined);
646
+ const layoutPrefix = (0, native_deps_1.installPrefix)(packageRoot, prefix ? globalInstallDir(prefix, process.platform) : undefined); // A-SPEC-580.8
639
647
  let coverage = 'uncovered';
640
648
  const policyJson = kind === 'repo' ? path.join(packageRoot, 'package.json')
641
649
  : kind === 'local' ? path.join(packageRoot, '..', '..', '..', 'package.json')
@@ -649,7 +657,7 @@ function gatherNativeEvidence(packageRoot, target = process.cwd()) {
649
657
  }
650
658
  const ev = {
651
659
  platform: process.platform, packageName: name, packageVersion, bindingPresent, loadError, npmMajor,
652
- coverage, installKind: kind, pathHasSpace: packageRoot.includes(' '),
660
+ coverage, installKind: kind, ...(layoutPrefix !== undefined ? { installPrefix: layoutPrefix } : {}), pathHasSpace: packageRoot.includes(' '),
653
661
  };
654
662
  if (process.platform === 'win32') {
655
663
  const python = observe('where.exe', ['python']) !== undefined || observe('where.exe', ['py']) !== undefined;
@@ -713,6 +721,23 @@ function resolveWiringPath(target, arg) {
713
721
  return '';
714
722
  return path.isAbsolute(arg) ? arg : path.resolve(target, arg);
715
723
  }
724
+ /**
725
+ * @implements A-SPEC-580.10 — doctor's `node version` line, its own function so a test can hold it: the driver's
726
+ * declared range, read from the driver directory only (A-SPEC-580.9: with none, nothing is read — `?? ''` had read the
727
+ * working directory's package.json).
728
+ */
729
+ function nodeVersionCheck(packageRoot) {
730
+ let sqliteRange = '(unknown)';
731
+ try {
732
+ // @implements A-SPEC-583.1 — the SIBLING of the evidence lookup; both move together.
733
+ const dep = resolveDepDir(packageRoot, 'better-sqlite3');
734
+ if (dep !== null)
735
+ sqliteRange = JSON.parse(fs.readFileSync(path.join(dep, 'package.json'), 'utf8')).engines?.node ?? '(none)';
736
+ }
737
+ catch { /* not resolvable from here */ }
738
+ return { name: 'node version', level: 'PASS', detail: `node ${process.version}; better-sqlite3 declares engines.node=${sqliteRange}`,
739
+ fix: 'If a native module fails to load after a Node major upgrade, reinstall holmes-kit.' };
740
+ }
716
741
  async function runDoctor(packageRoot, target, opts, extraChecks) {
717
742
  const checks = (0, doctor_guidance_1.guidanceChecks)(packageRoot, target ?? process.cwd());
718
743
  const add = (name, level, detail, fix) => checks.push({ name, level, detail, fix });
@@ -769,10 +794,9 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
769
794
  + (changedSinceInstall.length ? `; changed since installation (operator-owned, still routed): ${changedSinceInstall.join(', ')}` : '')
770
795
  + (staleRows.length ? `; stale receipt rows (workspace gone): ${staleRows.join(', ')}` : '')
771
796
  // @implements A-SPEC-772.7 — a router deployed by an older setup runs older code than the selected build.
772
- + ((report.routerOutdated ?? []).length
773
- // @implements A-SPEC-772.9 — a capability check (772.8), and the advice names a build that can clear it.
774
- ? `; the deployed dispatcher does not report its routing mode (${(report.routerOutdated ?? []).join(', ')} predates it) — re-run holmes-kit runtime-binding setup with a holmes-kit build that reports it (newer than 0.35.23, or the development checkout)`
775
- : ''), 'Use runtime-binding status and setup --dry-run to inspect routed wiring. Native hook trust and enable state remain operator-controlled.');
797
+ // @implements A-SPEC-772.9 — a capability check (772.8), and the advice names a build that can clear it.
798
+ // @implements A-SPEC-772.25 — every capability, each with what a router without it lets through.
799
+ + (0, runtime_binding_1.routerLacksLine)(report.routerLacks ?? []), 'Use runtime-binding status and setup --dry-run to inspect routed wiring. Native hook trust and enable state remain operator-controlled.');
776
800
  // @implements A-SPEC-769.8 — one WARN per Codex lifecycle routed to Holmes from both the user-level and the
777
801
  // workspace hooks file (measured 2026-10-12: the Stop hook ran twice per session end in both X1 fixtures).
778
802
  for (const d of report.duplicateRoutes ?? []) {
@@ -807,13 +831,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
807
831
  // never declared (build/mcp/release/test/typecheck only); dist/ ships because `files` lists it.
808
832
  built ? undefined : 'This package ships compiled dist/ — if you are working from the repository run `npm run build`; if this is an install, reinstall it.');
809
833
  // 2. Node version vs better-sqlite3's declared range (WARN only — a mismatch still often works).
810
- let sqliteRange = '(unknown)';
811
- try {
812
- // @implements A-SPEC-583.1 — the SIBLING of the evidence lookup; both move together.
813
- sqliteRange = JSON.parse(fs.readFileSync(path.join(resolveDepDir(packageRoot, 'better-sqlite3') ?? '', 'package.json'), 'utf8')).engines?.node ?? '(none)';
814
- }
815
- catch { /* not resolvable from here */ }
816
- add('node version', 'PASS', `node ${process.version}; better-sqlite3 declares engines.node=${sqliteRange}`, 'If a native module fails to load after a Node major upgrade, reinstall holmes-kit.');
834
+ checks.push(nodeVersionCheck(packageRoot));
817
835
  // 3. tree-sitter + EACH grammar — PARSED, not merely resolved. `require.resolve` only proves the
818
836
  // package directory exists; a grammar whose prebuilt binding is missing for this platform
819
837
  // resolves fine and dies at `setLanguage`. language-parser.ts loads them at module scope, so
@@ -1041,6 +1059,29 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1041
1059
  return v === 'refused' || v === 'unknown' ? 'unknown' : v;
1042
1060
  }));
1043
1061
  }
1062
+ // @implements A-SPEC-772.14 — what a failed PreToolUse hook does to the gate (onFailure "block" or not)
1063
+ // @implements A-SPEC-772.18 — a surface it cannot judge gets a not-judged line with its reason, never silence
1064
+ {
1065
+ const hf = require('./hook-failure-posture');
1066
+ if (routed)
1067
+ checks.push(hf.hookFailureNotJudgedCheck('routed'));
1068
+ else {
1069
+ const posture = hf.hookFailurePostureCheck(target);
1070
+ if (posture !== null)
1071
+ checks.push(posture);
1072
+ }
1073
+ if (codexWiredTarget(target))
1074
+ checks.push(hf.hookFailureNotJudgedCheck('codex'));
1075
+ const agyFile = path.join(target, '.agents', 'hooks.json');
1076
+ let agyText = '';
1077
+ try {
1078
+ if (fs.statSync(agyFile).size <= agents_1.AGY_HOOKS_MAX_BYTES)
1079
+ agyText = fs.readFileSync(agyFile, 'utf8');
1080
+ }
1081
+ catch { /* not wired */ }
1082
+ if (agyText.includes('holmes-kit'))
1083
+ checks.push(hf.hookFailureNotJudgedCheck('antigravity'));
1084
+ }
1044
1085
  }
1045
1086
  // @implements A-SPEC-142
1046
1087
  // Recovery layer. WARN and never FAIL: no gate decision reads a playbook, so their absence changes
@@ -2406,7 +2447,9 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
2406
2447
  const drifted = wired.filter((m) => m !== init_1.MATCHERS.guardrail);
2407
2448
  add('hook matcher', drifted.length === 0 ? 'PASS' : 'WARN', drifted.length === 0
2408
2449
  ? `The wired matcher equals the shipped default (${init_1.MATCHERS.guardrail})`
2409
- : `wired ${drifted.slice(0, 10).map((m) => (0, codex_oracle_1.clipText)(String(m), 80)).join(' | ')}${drifted.length > 10 ? ` and ${drifted.length - 10} more` : ''} / shipped default ${init_1.MATCHERS.guardrail} — a tool the matcher does not catch never reaches the hook`, drifted.length === 0 ? undefined : 'Run holmes-kit init --target <dir> --force to refresh it, and restart Claude Code.');
2450
+ : `wired ${drifted.slice(0, 10).map((m) => (0, codex_oracle_1.clipText)(String(m), 80)).join(' | ')}${drifted.length > 10 ? ` and ${drifted.length - 10} more` : ''} / shipped default ${init_1.MATCHERS.guardrail} — a tool the matcher does not catch never reaches the hook`,
2451
+ // A-SPEC-772.16: widening needs no approval (`--force` kept the narrowed matcher after 772.15)
2452
+ drifted.length === 0 ? undefined : 'Run holmes-kit init --target <dir> --matcher ".*" to widen it (no approval needed), and restart Claude Code.');
2410
2453
  }
2411
2454
  catch { /* an unreadable settings file is `target wiring`'s business, not this check's */ }
2412
2455
  }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Which hook commands are Holmes's — one place. Before 772.18 the same patterns were copied into settings-merge
3
+ * (`isHolmesCommand`) and claude-switches (`namesGate`, `holdsHolmes`), and the hook failure posture used the wider one
4
+ * as if it named the gate (`holmes-kit status` under PreToolUse counted as a gate entry).
5
+ */
6
+ /** A hook command belongs to holmes-kit iff it references our hook scripts or binaries. */
7
+ export declare function isHolmesCommand(command: unknown): boolean;
8
+ /** A hook entry (command text or exec-form `args`) that runs Holmes's gate. */
9
+ export declare function namesHolmesGate(h: Record<string, unknown>): boolean;
@@ -0,0 +1,22 @@
1
+ "use strict";
2
+ // @implements A-SPEC-772.18
3
+ /**
4
+ * Which hook commands are Holmes's — one place. Before 772.18 the same patterns were copied into settings-merge
5
+ * (`isHolmesCommand`) and claude-switches (`namesGate`, `holdsHolmes`), and the hook failure posture used the wider one
6
+ * as if it named the gate (`holmes-kit status` under PreToolUse counted as a gate entry).
7
+ */
8
+ Object.defineProperty(exports, "__esModule", { value: true });
9
+ exports.isHolmesCommand = isHolmesCommand;
10
+ exports.namesHolmesGate = namesHolmesGate;
11
+ /** Any Holmes hook command: the three hook scripts, or a Holmes binary by name. */
12
+ const HOLMES_HOOK = /dist[/\\]holmes[/\\]hooks[/\\](pre-tool-use|stop|session-start)\.js|\bholmes-(kit|mcp|pre-tool-use|stop)\b/;
13
+ /** Holmes's PreToolUse gate only. */
14
+ const HOLMES_GATE = /dist[/\\]holmes[/\\]hooks[/\\]pre-tool-use\.js|\bholmes-pre-tool-use\b/;
15
+ /** A hook command belongs to holmes-kit iff it references our hook scripts or binaries. */
16
+ function isHolmesCommand(command) {
17
+ return typeof command === 'string' && HOLMES_HOOK.test(command);
18
+ }
19
+ /** A hook entry (command text or exec-form `args`) that runs Holmes's gate. */
20
+ function namesHolmesGate(h) {
21
+ return [h.command, ...(Array.isArray(h.args) ? h.args : [])].some((x) => typeof x === 'string' && HOLMES_GATE.test(x));
22
+ }
@@ -0,0 +1,44 @@
1
+ /**
2
+ * 772.14-2 — what happens to the gate when Holmes's Claude Code PreToolUse hook fails. Measured 2026-11-16 (Claude Code
3
+ * 2.1.325, `claude -p` × 8): with `onFailure` unset, a hook that exits 1, times out or cannot start lets Read, Bash and
4
+ * Edit through and the model sees no error; with `"block"` all three are refused with the hook's stderr.
5
+ *
6
+ * 772.18 — read from `claudeSwitches`, the reader `claude hook switches` uses: every settings file Claude applies
7
+ * (managed, user, project, local, the canonical git root's local), only Holmes's gate entries, and never PASS while those
8
+ * switches say the gate does not run. File reads only — no process, no network. A module of its own: doctor.ts is past
9
+ * the 1,500-line rule.
10
+ */
11
+ import { type ClaudeSwitchEnv } from './claude-switches';
12
+ export type HookFailureState = 'not-wired' | 'not-running' | 'fail-open' | 'fail-closed' | 'unreadable';
13
+ export interface HookFailurePosture {
14
+ state: HookFailureState;
15
+ entries: number;
16
+ blocking: number;
17
+ files: string[];
18
+ }
19
+ export declare function hookFailurePosture(target: string, env?: ClaudeSwitchEnv): HookFailurePosture;
20
+ /** The sentence both surfaces say, or null when no Holmes PreToolUse gate is wired where Claude reads it. */
21
+ export declare function hookFailureSentence(p: HookFailurePosture): {
22
+ open: boolean;
23
+ detail: string;
24
+ fix?: string;
25
+ } | null;
26
+ /** doctor's line. */
27
+ export declare function hookFailurePostureCheck(target: string, env?: ClaudeSwitchEnv): {
28
+ name: string;
29
+ level: 'PASS' | 'WARN';
30
+ detail: string;
31
+ fix?: string;
32
+ } | null;
33
+ /** A-SPEC-772.18 — the surfaces this check does not judge, each with its reason (silence read as "nothing to say"). */
34
+ declare const NOT_JUDGED: {
35
+ readonly routed: "the Claude Code gate runs through the runtime router (~/.holmes/runtime), whose settings entries this check does not read";
36
+ readonly codex: "no failure-behaviour setting for Codex hooks is documented or measured here";
37
+ readonly antigravity: "no failure-behaviour setting for Antigravity hooks is documented or measured here";
38
+ };
39
+ export declare function hookFailureNotJudgedCheck(surface: keyof typeof NOT_JUDGED): {
40
+ name: string;
41
+ level: 'WARN';
42
+ detail: string;
43
+ };
44
+ export {};