@holmes-lab/holmes-kit 0.30.0 → 0.31.1

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 (139) hide show
  1. package/CHANGELOG.md +505 -0
  2. package/README.md +10 -1
  3. package/bin/holmes-hook-antigravity.js +4 -0
  4. package/bin/holmes-kit.js +4 -0
  5. package/bin/holmes-pre-push.js +3 -0
  6. package/bin/holmes-stop-antigravity.js +4 -0
  7. package/dist/.build-id +1 -1
  8. package/dist/holmes/cli/agents.d.ts +41 -0
  9. package/dist/holmes/cli/agents.js +382 -2
  10. package/dist/holmes/cli/attest.d.ts +2 -0
  11. package/dist/holmes/cli/attest.js +66 -15
  12. package/dist/holmes/cli/ci-gate.js +16 -1
  13. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  14. package/dist/holmes/cli/claude-switches.js +967 -0
  15. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  16. package/dist/holmes/cli/codex-hooks.js +802 -0
  17. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  18. package/dist/holmes/cli/codex-oracle.js +1245 -0
  19. package/dist/holmes/cli/codex-toml.d.ts +35 -0
  20. package/dist/holmes/cli/codex-toml.js +321 -52
  21. package/dist/holmes/cli/doctor.d.ts +98 -8
  22. package/dist/holmes/cli/doctor.js +1328 -94
  23. package/dist/holmes/cli/index.js +26 -11
  24. package/dist/holmes/cli/init.d.ts +11 -0
  25. package/dist/holmes/cli/init.js +736 -44
  26. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  27. package/dist/holmes/cli/mcp-launcher.js +189 -6
  28. package/dist/holmes/cli/mcp-version.js +13 -2
  29. package/dist/holmes/cli/settings-merge.js +8 -2
  30. package/dist/holmes/cli/upgrade.d.ts +18 -0
  31. package/dist/holmes/cli/upgrade.js +129 -24
  32. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  33. package/dist/holmes/cli/workspace-scope.js +375 -0
  34. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  35. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  36. package/dist/holmes/cpg/cycle-detect.js +2 -1
  37. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  38. package/dist/holmes/cpg/required-calls.js +8 -1
  39. package/dist/holmes/governance/constitution-debt.js +3 -2
  40. package/dist/holmes/governance/constitution.js +15 -3
  41. package/dist/holmes/governance/provenance-chain.js +3 -2
  42. package/dist/holmes/governance/push-gate-runner.js +4 -3
  43. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  44. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  45. package/dist/holmes/guardrail/linear-match.js +256 -0
  46. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  47. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  48. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  49. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  50. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  51. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  52. package/dist/holmes/guardrail/shell-words.js +1720 -0
  53. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  54. package/dist/holmes/guardrail/write-target.js +2379 -87
  55. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  56. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  57. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  58. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  59. package/dist/holmes/hooks/rtm-refresh-child.js +3 -1
  60. package/dist/holmes/hooks/rtm-refresh.js +8 -4
  61. package/dist/holmes/hooks/session-start.d.ts +10 -0
  62. package/dist/holmes/hooks/session-start.js +31 -7
  63. package/dist/holmes/hooks/stop.d.ts +2 -1
  64. package/dist/holmes/hooks/stop.js +197 -91
  65. package/dist/holmes/mcp/approval-commit.d.ts +5 -6
  66. package/dist/holmes/mcp/approval-commit.js +18 -2
  67. package/dist/holmes/mcp/elicit-approval.js +4 -2
  68. package/dist/holmes/mcp/handlers/graph-operations.js +3 -2
  69. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  70. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  71. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  72. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  73. package/dist/holmes/mcp/handlers/requirement-triage.js +5 -3
  74. package/dist/holmes/mcp/handlers/review-evidence.js +8 -2
  75. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +11 -0
  76. package/dist/holmes/mcp/handlers/slice-orchestration.js +115 -16
  77. package/dist/holmes/mcp/handlers/spec-approval.d.ts +9 -0
  78. package/dist/holmes/mcp/handlers/spec-approval.js +110 -17
  79. package/dist/holmes/mcp/handlers/spec-authoring.js +17 -2
  80. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  81. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  82. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  83. package/dist/holmes/mcp/handlers.d.ts +81 -9
  84. package/dist/holmes/mcp/handlers.js +70 -23
  85. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  86. package/dist/holmes/mcp/harness-attestation.js +179 -0
  87. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +36 -0
  88. package/dist/holmes/mcp/requirement-triage-evidence.js +160 -4
  89. package/dist/holmes/mcp/server.js +20 -1
  90. package/dist/holmes/mcp/tool-schemas.js +26 -9
  91. package/dist/holmes/mcp/validate-args.js +12 -0
  92. package/dist/holmes/project/bounded-io.d.ts +102 -0
  93. package/dist/holmes/project/bounded-io.js +212 -0
  94. package/dist/holmes/project/change-source.js +3 -1
  95. package/dist/holmes/project/ci-runs.js +3 -2
  96. package/dist/holmes/project/ignore.d.ts +31 -2
  97. package/dist/holmes/project/ignore.js +409 -50
  98. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  99. package/dist/holmes/project/regular-file-guard.js +149 -0
  100. package/dist/holmes/project/root.js +12 -3
  101. package/dist/holmes/reverse/anchor.js +4 -3
  102. package/dist/holmes/reverse/scan.js +6 -2
  103. package/dist/holmes/review/commit-text.js +3 -2
  104. package/dist/holmes/review/condition-hunk-replay.js +3 -2
  105. package/dist/holmes/review/failed-test-names.js +13 -10
  106. package/dist/holmes/review/findings.js +3 -1
  107. package/dist/holmes/review/kills-check.js +6 -1
  108. package/dist/holmes/review/point-in-time-replay.js +5 -4
  109. package/dist/holmes/review/replay-corpus.js +5 -4
  110. package/dist/holmes/review/run-replay.js +3 -2
  111. package/dist/holmes/review/temporal-prior.js +3 -2
  112. package/dist/holmes/review/test-evidence.js +3 -2
  113. package/dist/holmes/review/test-outcomes.js +3 -2
  114. package/dist/holmes/review/test-runner.d.ts +6 -0
  115. package/dist/holmes/review/test-runner.js +36 -15
  116. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  117. package/dist/holmes/rtm/anchor-ids.js +42 -2
  118. package/dist/holmes/rtm/file-anchors.js +4 -1
  119. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  120. package/dist/holmes/rtm/git-changes.js +3 -1
  121. package/dist/holmes/rtm/graph-store.js +3 -2
  122. package/dist/holmes/rtm/test-scope.js +9 -4
  123. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  124. package/dist/holmes/spec/compat-impact.js +682 -11
  125. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  126. package/dist/holmes/spec/entity-integration.js +3 -2
  127. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  128. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  129. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  130. package/dist/holmes/spec/renumber.js +25 -10
  131. package/dist/holmes/spec/spec-parser.js +9 -3
  132. package/dist/holmes/spec/yaml-scalar.js +2 -2
  133. package/dist/holmes/update/refresh.d.ts +5 -0
  134. package/dist/holmes/update/refresh.js +26 -1
  135. package/dist/holmes/update/update-notice.d.ts +6 -0
  136. package/dist/holmes/update/update-notice.js +18 -1
  137. package/dist/holmes/update/upgrade-plan.d.ts +28 -0
  138. package/dist/holmes/update/upgrade-plan.js +31 -2
  139. package/package.json +11 -4
package/CHANGELOG.md CHANGED
@@ -5,6 +5,511 @@ 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.31.1] - 2026-09-29
9
+
10
+ ### Fixed
11
+
12
+ - **`holmes-kit upgrade` asks the registry for the latest version** (A-SPEC-543.2, amended). It read only the update
13
+ cache, which SessionStart refreshes at most once a day, so right after 0.31.0 was published it answered `already up
14
+ to date (current 0.31.0, latest 0.30.0)` and a newer release would not have been installed for up to a day. The
15
+ command now queries the registry (5 s, the same public `dist-tags` the banner uses) and refreshes the cache; when the
16
+ registry cannot be reached it says it used the cache and how old that answer is; an installed version newer than the
17
+ latest is no longer called "already up to date". `--dry-run` asks and shows, and writes nothing.
18
+
19
+ ## [0.31.0] - 2026-09-29
20
+
21
+ Post-0.30 hardening (H1–H12) and a new rule for Codex: whether Codex loads its own files is now
22
+ Codex's answer. Every item went through its own REQ and repeated adversarial review waves. The
23
+ shell gate and its walkers were reviewed in 51 waves and ended with two consecutive waves on the
24
+ same code that found nothing CRITICAL or HIGH (waves 50 and 51); the install wiring and diagnosis
25
+ (`init`, `doctor`, `upgrade`) in 65 waves, ending likewise (waves 64 and 65). "HIGH" there follows
26
+ owner decisions recorded in the goal log: a gate miss is at most MEDIUM; doctor or init starting a
27
+ program the workspace controls is HIGH in an ordinary environment and MEDIUM where a variable, PATH
28
+ or install path must be arranged; a contrived oversized input's time-out is at most MEDIUM. The
29
+ MEDIUM and LOW findings of those last waves are listed under Known limitations
30
+ (`docs/goals/GOAL-post-0.30-hardening-2026-09-23.md`).
31
+
32
+ ### Added
33
+
34
+ - **Codex load verdicts come from the installed Codex** (REQ-738, A-SPEC-738). Where `codex` is on PATH,
35
+ `holmes-kit init` and `doctor` copy only `config.toml` and `hooks.json` into a temporary
36
+ `CODEX_HOME` and ask a short-lived local `codex app-server` (`config/read`, `hooks/list`) whether
37
+ they load. Measured isolation: plugin sync off (`--disable plugins --disable remote_plugin`),
38
+ telemetry exporters and analytics off, `sqlite_home` pinned to the copy, an environment allowlist,
39
+ every proxy pointed at a closed local port, and the whole process group killed — no connection and
40
+ no file outside the copy. Without codex, the previous reading is used and every Codex line says it
41
+ is `approximate`. Hook trust stays unverifiable (Codex keys it by the real path).
42
+ - **`phase_status` answers a bounded summary** (REQ-735, A-SPEC-735): counts by type and status, filters
43
+ (`ids`/`type`/`status`) and cursor pages; this repository's default response went from 153,888 to
44
+ ~8,900 characters.
45
+ - **`spec_next` names the slice's next actions** (REQ-736, A-SPEC-736): seal (only where `spec_approve` would),
46
+ fill-then-seal, fix-then-seal, after-parent, create-parent, author-tspec.
47
+
48
+ ### Changed
49
+
50
+ - **The gate only ever denies — an action it does not deny goes through your harness's own permission flow**
51
+ (REQ-739, A-SPEC-739; owner decision). The PreToolUse hook used to answer `permissionDecision: "allow"` for every
52
+ action it did not deny, and Claude Code handles a hook allow as "Hook approved tool use …, bypassing permission
53
+ prompt" (read from the installed 2.1.281 binary): every command the shell model missed —
54
+ `{rm,-rf,/usr/local}`, `/bin/[r]m -rf .git`, `x=rm; $x -rf /usr/local`, `find .ax … -exec rm {} +` — ran without
55
+ asking, so installing Holmes made Claude ask less. Now a deny is still a deny with its reason, and anything else
56
+ carries no permission decision for Claude Code and Codex (Codex already ignored `allow`; a warning travels as
57
+ `additionalContext`); Antigravity, whose hook contract requires a decision, gets `ask` (your Always-Allow still
58
+ applies), or `allow` only for a read inside the workspace that git does not ignore — resolved as the kernel resolves
59
+ it (a workspace link followed by `..` reads outside) and by the tool's own path argument; its `run_command` is judged
60
+ in the `Cwd` it runs in (a removal inside `.ax` through `Cwd` was not). **Cost:** in Claude Code's default mode you see its own confirmations
61
+ again for Bash, edits and Holmes's MCP tools, as you would without Holmes — use your harness's allow rules or
62
+ modes for the ones you trust.
63
+
64
+ - **An install is wired with `node`, not `npx`** (REQ-251, A-SPEC-251.1/.2). `init` from a global or
65
+ project-local install writes `node <install>/bin/holmes-mcp.js` for Claude, Codex and Antigravity; only a
66
+ zero-install run from a temporary exec cache (npm `_npx`, pnpm `dlx`, bun, yarn) is wired through `npx`,
67
+ and `init` says what that hands the workspace; a temporary cache is recognised by its shape (`_npx/<hash>`,
68
+ `pnpm…/dlx/`, `bunx-<uid>-…`, `xfs-<8 hex>/dlx-<n>`), not by a directory name. `holmes-kit upgrade` lets the new
69
+ install choose (it forced `--mcp-launcher npx`) and re-pins only the project a project-local install went into.
70
+ doctor's version drift check covers the Codex and Antigravity wirings too; a project-local upgrade re-pins the
71
+ workspaces that resolve to the new install (the nearest `node_modules/@holmes-lab/holmes-kit`) and leaves Codex's
72
+ user-level wiring alone (it is shared by every workspace), saying so; the plan shown before "Continue?" is the
73
+ run's own decisions, names the install location, and re-pins only after checking that the planned version landed
74
+ there. `init` refuses any file it reads before writing that it cannot read (a directory, a link to a device)
75
+ instead of crashing, and claims nothing when it refuses — the two Claude settings files and `.mcp.json` included,
76
+ which it refuses before writing anything; a write that fails part way names the files already written, only
77
+ files actually written are reported, and harness links are made in the write phase. doctor's wiring handshake
78
+ starts the server with its update check off (the probe reached the registry), and every npm child doctor and
79
+ `upgrade` start runs with `--no-update-notifier` (npm's own update check raced each command and reached the
80
+ registry a target's `.npmrc` named); `upgrade --yes` works (it was refused as a flag missing its value). `init` never
81
+ writes, removes or links through a symlink that leads out of the target — skills included, whether or not the
82
+ repository tracks it (a cloned repo's `.agents -> ../../.codex`, and then a case-variant `.AGENTS` and a submodule's
83
+ link, turned the Codex gate off everywhere); the one exception is a Claude settings file linked to your own dotfiles
84
+ — a settings file by name, outside every harness configuration home, not carried by the repository (a git that is
85
+ missing where `.git` exists refuses).
86
+ It refuses an unreadable Codex `config.toml` before writing, claims Codex's tools only when their registration was
87
+ written, and honours `--no-mcp` for Antigravity. The update cache and `upgrade` accept only a plain semver as the latest
88
+ version — no build metadata, nothing npm reads as a file name (`9.0.0.tgz` and `9.0.0-x.tgz` were installed as local
89
+ packages and ran their install scripts). doctor runs a Claude, Antigravity or Codex node wiring only when it is
90
+ exactly `node <this install's bin/holmes-mcp.js>`, however it is spelled otherwise (`/opt/homebrew/bin/node`, `sh`,
91
+ `env`, a script, a workspace program named `node` or `npx`): a workspace file in its place is a FAIL, another install
92
+ a WARN, and neither is run. The command is found where the launcher finds it — a bare name along PATH from the
93
+ target (a `.` entry ran the target's `node`; on Windows the target directory comes first), a relative path is always
94
+ the workspace's (`sl/../node`, `../../tools/node` from a monorepo, submodule or archive package ran a wrapper), and an
95
+ absolute path is node only when its real file is node or the very file a bare `node` finds (a committed link
96
+ `bin/node -> …/make` ran the repository's Makefile; Volta and mise shims still work), a process-dependent path such
97
+ as `/proc/self/cwd/…` counts as relative however it is spelled (`//proc`, `/usr/../proc`) — and "the workspace" is
98
+ every repository around the target plus the one owning a submodule's `.git` file and every checkout whose `.git` shares
99
+ its common git directory, found from the command's own directories (a symlinked `.git` followed) and, only when needed, from
100
+ the common directory's own worktree list (the 65th sibling worktree's wrapper ran; a 200,000-entry listing took 88 s), and
101
+ never a repository at or above the home directory (a dotfiles repository made nvm's `node` "the workspace's"); the walk
102
+ stays bounded (`.git` files pointing at one `.git`-less directory took minutes; `.git` files are read to 64 KiB; the
103
+ worktree list is matched as written first and walked parent by parent within a 20,000-component budget — walked entry
104
+ by entry, 1,250 worktrees used it up and turned every node wiring into a FAIL; entries that are links are walked within
105
+ the same kind of budget, 4,096 of them took 53 s). A path read from a wiring or a
106
+ `.git` file, and its arguments, is walked one component at a time and never looked up on the network (`/net/<host>`,
107
+ `//host`, `\\host`, or a committed link to one) — its last component too: a worktree's `gitdir` and `commondir` files, the
108
+ `package.json` beside a node wiring argument and the hook scripts every harness's wiring names were opened through links
109
+ to `/net`, and a hook path or node wiring is judged by its walked form (`lnk/../x` was re-resolved through the link);
110
+ such a command is not run. A wiring or settings file that is itself a
111
+ link to the network, and PATH look-ups, are named residuals. init reads an empty or BOM-only settings file as `{}` and
112
+ refuses to write one Claude would not read (over 2 MiB). A new `claude hook switches` check reads Claude's `disableAllHooks` (in
113
+ managed, user, project and local settings — a committed one switched every hook off while init said "enforced" and
114
+ doctor passed), a managed `allowManagedHooksOnly` (a non-boolean one too) or `strictPluginOnlyCustomization`, and
115
+ `disabledMcpjsonServers` / `permissions.deny` / MCP allow and deny lists for Holmes's tools, where Holmes's Claude
116
+ wiring is, read as Claude 2.1.281 reads them (an invalid allow list is an empty one; a list with command entries
117
+ admits Holmes only by its exact command; `managed-mcp.json` takes exclusive control; a user or project list that is not
118
+ an array is dropped), and a settings file Claude drops — judged by Claude 2.1.281's own loader, transcribed: a
119
+ PreToolUse/PermissionRequest entry it cannot load (`"type": "comand"`, `timeout: 0`, `shell: "zsh"`, `matcher: null`, a
120
+ prompt without `prompt`) or one declared outside `hooks` (24 such shapes read PASS), while what Claude only warns about
121
+ (an unknown event, a stray `"matcher"` key) no longer fails or refuses init — read after Claude's own cleaning (`isolation`,
122
+ the marketplace aliases, non-string permission entries), with zod v4's URL trimming, `__proto__` skipping and finite numbers
123
+ (`"timeout": 1e999` drops a file), never for a managed file (Claude salvages those), and for a file over 2 MiB, which Claude
124
+ does not read; a dropped file's own switches do not count, and it is a FAIL only when no applied file holds Holmes's gate
125
+ in a PreToolUse group Claude loads (an unrelated `holmes-kit status` hook no longer hides it). A gate entry Claude does not
126
+ wait for is not enforcing: `async`/`asyncRewake` runs it in the background and a non-empty `if` condition runs it only
127
+ when the condition matches, so a target whose only gates are such entries is a FAIL (it passed and init said
128
+ "enforced"). Only the gate entry init writes is confirmed to block — any other shape of it (a later async copy, a
129
+ `shell`, another launcher, the exec form) or a `CLAUDE_CODE_SHELL_PREFIX` in settings or the environment is reported
130
+ as not confirmed (WARN), and init does not say "enforced" over it: doctor does not transcribe Claude's hook runner. So is
131
+ any settings or global `env` key outside a list of harmless ones — Claude's own model, authentication, time-limit,
132
+ telemetry and output settings, display keys and proxies (`SHELLOPTS=noexec`, an empty `PATH`, `NODE_OPTIONS` and a `TZ`
133
+ naming a FIFO each kept the gate from blocking); the global config is the one file Claude reads — `.config.json` in its
134
+ config home (`~/.claude`) when it exists, else `.claude.json` — and the key list is capped (a 70,000-character key cut
135
+ `doctor --json` mid-object) — a matcher that does not see every tool, a path the shell rewrites (`$`, backticks, a UNC
136
+ `\\host`), or a script named by a relative path, which each harness resolves against the session's current directory
137
+ (after `cd src` the gate failed to load; the three wiring checks also flipped with doctor's own directory); Holmes's other
138
+ hooks with no gate, or a gate running a missing script, are a FAIL, a script on a network path doctor does not look up is
139
+ a WARN, and a managed gate under a switch that spares managed hooks is a WARN, not a FAIL. The Antigravity wiring is judged
140
+ by the command string agy runs (it ignores `args` and keeps quotes — a command running another file passed on its
141
+ `args`); each wiring-derived script is walked once, at most 4,096 components and 16 distinct scripts per check (1,000
142
+ committed gate entries behind a link chain held doctor for 106 s); the global config home is computed from the raw
143
+ `CLAUDE_CONFIG_DIR` as Claude computes it (an empty value is the session's directory), the user settings file too;
144
+ control characters, line separators and bidirectional controls from a file are escaped in doctor's and init's output
145
+ and in `doctor --json`. A walk past its bound is never opened as spelled (a twelve-link chain ending on `/net` was
146
+ opened), wiring arguments are walked at most 16 (4,000 through a link chain took 25.6 s), the Antigravity PreToolUse and
147
+ Stop entries must run this install's own two scripts (the Stop script as the gate read PASS), and the SessionStart
148
+ version nudge reads a node wiring's `package.json` only above its walked local path, each `package.json` at its walked
149
+ path (a committed link to `/net` was opened). Antigravity runs a hook command through `sh -c` (`cmd /c` on Windows), so
150
+ only an install path of characters both shells read literally is confirmed and init warns that the gate is NOT enforced
151
+ otherwise (`inst'q` was an sh syntax error and `R&D` two commands, both read PASS); an entry switched off with
152
+ `"enabled": false` is FAIL; an install on a path doctor never looks up is judged by its spelling (a false FAIL). Every
153
+ `..` of a wiring command shares one walk budget (300 `L/..` pairs through a self-looping link held doctor for 26.8 s),
154
+ and values quoted from a file — including init's preview lines — have control, line-separator and bidirectional
155
+ characters escaped (a newline in a wiring value printed a forged PASS line). An Antigravity hooks file is confirmed only
156
+ when the whole file is in the shape agy's parser loads — agy drops every hook of a file one named hook of which fails
157
+ (a sibling's `"timeout": "10"` read PASS) and reads field names case-insensitively (`"ENABLED": false` read PASS); a
158
+ `holmes-kit` entry switched off in the user-level `~/.gemini/config/hooks.json` is FAIL; a gate `node` the launcher finds
159
+ inside the workspace (agy runs hooks from `.agents`, Claude from the target) is FAIL and init says the gate is NOT
160
+ enforced; managed Claude settings whose value 2.1.281 and 2.1.283 read differently are "not confirmed"; `upgrade`'s plan
161
+ escapes registry values. agy's `SessionStart` event and its other workspace roots (`.agent`, `_agents`, `_agent`, up to the
162
+ repository root) are read too; a switch counts only in a file agy loads; hooks files are read up to 2 MiB; a gate `node`
163
+ found through a relative PATH entry is FAIL, one inside the workspace through an absolute entry "not confirmed". By owner
164
+ decision Antigravity is confirmed as Claude is: only the hooks file `holmes-kit init` writes reads PASS — other named hooks,
165
+ other keys or values, a hooks file in another agy root or a `holmes-kit` entry in the user-level file read "not confirmed"
166
+ (WARN), and evidence that no gate runs stays FAIL. init and doctor judge the gate's `node` by one workspace rule (the
167
+ target, the repository around it, its worktrees), by where the file lies as well as what it is, and say "not confirmed"
168
+ when no `node` is on PATH; doctor starts its wiring probes through its own node (the word `node` is the file that runs
169
+ doctor), and the children of the wiring probe and of the 'MCP server' check get doctor's node's directory and the
170
+ absolute PATH entries outside the workspace, and no `HOLMES_MCP_AUTORELOAD` (a probe starts no supervisor). **doctor no
171
+ longer starts an npx wiring** (owner decision): the npx launch `init` writes reads PASS by its shape, any other npx
172
+ launch WARN — npx runs npm, and npm read the `.npmrc` and `node_modules/.bin` of wherever doctor started it (the target,
173
+ a shared temporary directory). An `npm-cli.js` inside the workspace is not taken. What the harness would find on its own
174
+ PATH is said without running it, and so is a PATH that holds no launcher; init judges the Claude settings it is about to
175
+ write; doctor starts one wiring launch once per run; on Windows agy's user-level file is looked for under
176
+ `USERPROFILE`. The local settings of the
177
+ canonical git root (a monorepo root, a worktree's main checkout) are read as Claude 2.1.281 finds it — a usable `.git`, and
178
+ for a worktree plain `commondir`/`gitdir` files under `<common>/worktrees/` whose back-pointer is this checkout, compared as text as Claude compares them (a moved
179
+ worktree and a `--separate-git-dir` directory are not canonical).
180
+ init no longer says
181
+ "enforced" under such a switch, over a settings file it cannot read, or for a harness whose hooks file it refused,
182
+ and refuses by name a settings file or `.mcp.json` whose shape it cannot merge (they crashed with a TypeError or were
183
+ rewritten into index keys), reading a null `hooks` as empty as Claude does. `$CLAUDE_CONFIG_DIR` is a harness home for the settings
184
+ link exception, and a missing git is also looked for from the link's real directory.
185
+ Doctor reads wiring files as untrusted input: a non-string argument, a deeply nested `cmd /c` or a very long
186
+ node path neither crashes nor stalls it. Measured: the npx launch runs npm in each session
187
+ workspace, and that workspace's `.npmrc` (`node-options=--require ./evil.js`) or a package planted in
188
+ its `node_modules` ran in place of the Holmes server; an `npm_config_node_options=""` override does not
189
+ help (npm reads an empty value as unset). `doctor` WARNs every Holmes wiring launched through a package runner
190
+ (`npx`, `bunx`, `npm exec`, `pnpm dlx`, `yarn dlx`, `cmd /c npx`) as `<harness> wiring launcher`, and a
191
+ trusted Codex layer's npx launch is a FAIL (REQ-738). Existing wirings change when `init --force` is re-run.
192
+ - **Codex gate on codex-cli 0.155** (REQ-727, A-SPEC-727): plugin hooks were removed upstream; `init --agent
193
+ codex` wires the PreToolUse and Stop kernels into the user-level `$CODEX_HOME/hooks.json`,
194
+ preserving foreign hooks and trust identities.
195
+ - **In-session approval is offered only to an attested harness** (REQ-732, A-SPEC-732): the MCP server's parent
196
+ must be the harness's own executable image (native claude/codex/agy), not a name; the slice and
197
+ remediation tools act only on the bound store; `spec_remediate` writes only a spec id, never into
198
+ `.ax/`, through a symlink or a hard link. Named residual: a binary copied under a harness name.
199
+ - **Requirement triage evidence is ledger-issued and single-use** (REQ-729, A-SPEC-729); a REQ's first seal is
200
+ read from the ledger and follows recorded renames.
201
+ - **Compatibility cross-check** (REQ-733, A-SPEC-733): refusals carry the accepted vocabulary and the matched
202
+ line; OS signals are judged by language and shape (JS/TS, Python, Go, Rust, Java/Kotlin, C#, C/C++,
203
+ Swift, Ruby, shell, Makefile, PowerShell); the check reads what the edit gate admits.
204
+ - **`.ax` read loops are reads** (REQ-737, A-SPEC-737; the A-SPEC-226 loop pin is amended); programmable readers that write (`sed w`, `awk >`,
205
+ `sort -o`, `find -fprint`, `git --output`, `perl`) are not, in every spelling getopt and BSD accept (`sed -E -i.bak`, `sed -I ''`,
206
+ `sed --in`, `sort --o=`, `sort --outp=` edited `.ax/specs` while read as reads — measured on macOS).
207
+ - **Walkers skip nested git working trees** (REQ-734, A-SPEC-734) — only when git says the directory is not the
208
+ project's (tracks nothing under it, and ignores it or registered it as a worktree).
209
+ - ART-6 clears when a later current-build record answers a diverged finding (REQ-726, A-SPEC-726); REQ intake
210
+ names the freshness cause and recovery (REQ-730, A-SPEC-730); protected harness configuration
211
+ includes the active Codex config (REQ-728, A-SPEC-728).
212
+ - **The shell gate judges by identity, and a `cd` moves its base only when certain** (REQ-728):
213
+ wiring files and directories (`.mcp.json`, `.claude/settings*.json`, `.agents/*`, `.codex/*`,
214
+ `~/.codex/config.toml|hooks.json`, `~/.claude/settings*.json`) and **`.ax` as a whole** are judged
215
+ as shell words after quoting, brace lists, `$HOME`/`$CODEX_HOME`, wrappers, `find`/`xargs`, `git`,
216
+ archive and copy forms; a `cd` the shell may skip, fail, run in a subshell or resolve elsewhere
217
+ (`cd /nope && true;`, `false && cd`, `(cd …);`, `true | cd`, `~-`, `pushd +1`, `CDPATH`, a link
218
+ made in the same command, `then cd`, `eval`, `source`) leaves the base unknown, where wiring and
219
+ code writes are refused by name. Every evaluation runs under a deadline wall (20 s, 2 GB) whose
220
+ overrun is the gate-error decision — deny where governed, never allow.
221
+ The `.ax` text rules follow every certain `cd` (a second `cd` into `.ax` was flattened only for
222
+ the first), and an uncertain `cd` still contributes its lexical target as a possible base, so a
223
+ relative write after `git log; cd sub; cd ../.ax` is refused as well.
224
+ - **Every trailing-run trim on a gate path is linear** (`trimTrailing`): 17 sites that took 2.8–3.7 s
225
+ on an 80 KB run (approval blockers, the C-SPEC rule readers, the spec parser, `.gitignore`); the spec
226
+ heading, the hook's quote scan, the `.gitignore` class test and `**` matcher, `posix.normalize` on
227
+ `../` runs and the redirect strip are linear too.
228
+ - **Every gate verdict up to the 256 KB parse limit arrives within 2 s** (A-SPEC-728 rule 37, measured on the built
229
+ hook): a glob is matched by simulating its automaton (22 `**/` groups in a deletion glob took the 20 s deadline); a brace
230
+ body holding a comma skips the cubic range test; loop expansion has one budget per command, past which a loop too large
231
+ to judge is refused (four nested 64-word loops reached the deadline); `cd` look-ups, the segment flattening's `realpath`
232
+ and the shell-write patterns are made once per command (131,000 lines took 4.8 s); `open(…, 'w')` evidence is read
233
+ linearly and an interpreter program's call arguments within one 16 MiB budget; and a missing path's nearest real
234
+ ancestor is found by halving (a 200 KB Write `file_path` took 6.6 s). Named residual: a command naming `/net/<host>`
235
+ is looked up before the user is asked. Whenever the gate cannot place a command's directories, a literal `cd` that lands in
236
+ the `.ax` store (a link to it included) still makes the writes it recognises be judged there, glob words too (64 no-op
237
+ `cd`s before `eval 'cd axl/specs/01_req'` let `sed -i` into the store; reading the store for every command with many
238
+ `cd`s refused `(cd client && npm test) && … | tee test.log`); the call-argument
239
+ budget is the whole command's; trailing-slash trims, the self-approval `status: approved` test and the store-candidate
240
+ ancestor search are linear (a 96 KB slash run, 48 KB of blank lines and 16,000 missing components took seconds or ran
241
+ out of heap); a refusal of an input too large to judge says so. A spec edit is judged on its result — an Edit of `draft`
242
+ into `approved` no longer self-approves, and a MultiEdit whose result would pass 16 MiB is refused instead of aborting
243
+ the hook; the result is computed once, within a work budget across all its edits (a 2.9 KB MultiEdit of length-preserving
244
+ `replace_all` edits took 16 s with no verdict); Antigravity's `replace_file_content` is judged on its result too (its
245
+ replacement was read as the whole file, so `draft` → `approved` was `ask` there and a deny for Claude — a target not in the
246
+ file, and a Write carrying a stray pair, are still judged on the content as a whole file); the curl/wget URL
247
+ tail strip is linear, and a glob like `[(])` is literal text again instead of a thrown error. Every verdict up to the
248
+ 256 KB parse limit arrives within 2 s again: the string-literal strip every anchor rule shares and the `.ax` scope
249
+ rewrite are linear scanners equal to the regexes they replace (48 KB of `\"` in a code Write took 3.5 s, 256 KB of
250
+ `=/` met the 20 s wall); a shell command is split once and refused past 4,096 segments or 4,096 distinct write targets
251
+ (seventeen shapes of repeated separators took 2.4–6.1 s — the refusal says to split the command, and an ungoverned project
252
+ is not refused for code targets it never judges); the children of one stdin or `-c` program share their possible bases,
253
+ whether a text names wiring is remembered per text, and `git -C` values are resolved once (each took seconds to the 20 s
254
+ wall; a base unknown past 4,096 characters on the way let a 17-hop walk back into `.ax` through); `tar`'s `-C` values
255
+ compose as `cd`s do — by position, as bsdtar and GNU tar each read them, and an empty `-C ""` changes nothing — and a
256
+ composed directory past 4,096 characters is refused where pathspecs or members land in it; answers about a text are kept
257
+ for the 256 most recently asked long texts (257 quoted literals evicted the whole command's answer: 10.7 s), and a quoted
258
+ shell command inside a program is judged once, at most 4,096 of them; identical words are judged once; `git --work-tree`
259
+ is judged beside the `-C` directory, not instead of it; tar's old-style bundles (`tar xfC e.tar dir`) and glued `-f` values
260
+ are read; a path that passed is not judged again within one command (16 loops over one tar command took 10.6 s), and a
261
+ command naming more than 65,536 distinct paths, or more than 16 MiB of path text, is refused as too large to judge; with
262
+ `--strip-components`, `--transform` or `-s` a tar member holding a wiring file's or directory's name is refused by name,
263
+ wherever it lands (a harmless `tar -xzf theme.tgz --strip-components=1 -C dist package/settings.json` needs an approval);
264
+ a tar `-C` directory is not composed past 4,096 characters; under an
265
+ unknowable `git -C` the work tree is resolved from the command's own directory; a candidate's place under `.ax` is computed once per
266
+ judgement; whether a `find` runs unfiltered is decided in one pass; a segment is judged at no more than 8 climb bases, and
267
+ the classifier's per-segment flattening stays within 32 MiB — past either the command is refused as too large to judge;
268
+ a long pattern in a spec edit is searched linearly; and an Antigravity read is auto-allowed only without `Includes` (one
269
+ can name an ignored file), with plain relative `Excludes`, and with no key that differs from the one it reads only in case.
270
+ - **The files inside `.ax` are protected by identity, not spelling** (REQ-728): a quoted, escaped,
271
+ globbed or case-variant path, reached through any `cd` — certain or not — is resolved against the
272
+ segment's real or possible base; a `#` comment no longer opens a quote for the next line. A
273
+ segment whose base is unknown is judged at every `.ax` base the command could have produced,
274
+ keyed by the store's layout (bounded whatever the command's length); a `cd` whose target cannot
275
+ be resolved, in a command that mentions `.ax` (a link made in the same command, `X=.ax; cd "$X"`),
276
+ is judged inside `.ax`; and a mention is a **spelling** — `.a?`, `.[a]x`, `$'\056ax'`, `"."ax`,
277
+ `.\ax`, `{.ax,}`, `.{a..z}x` — as bash and zsh read it, while `[.]ax`, `?ax`, `*` and a numeric
278
+ `{1..3}` are not. A `cd` argument the shell would EXPAND (`cd .a?`, `cd .ax/led*`) has an
279
+ unknowable target (it resolved to a literal `<root>/.a?` and the store was deleted through it —
280
+ measured); a candidate base is placed by identity first (a link `axlink → .ax` already on disk,
281
+ reached by an uncertain cd, was dropped for its spelling); and the shell base is the directory
282
+ the harness RUNS the command in — the payload `cwd`, or a Codex `tool_input.workdir` — when it
283
+ lies inside the project, so `rm ../.mcp.json` from `sub/` is refused (it was judged at the root,
284
+ where `..` leaves the project); a relative `workdir` is anchored at the `cwd`. A wrapper that
285
+ changes directory for the command it runs (`env -C DIR`, `env --chdir=DIR`, `sudo -D DIR`) moves
286
+ that command's base like a `cd` — the option used to be stripped as a wrapper argument, and
287
+ `env -C .ax rm ledger/provenance.jsonl` deleted the ledger while judged at the root (measured);
288
+ nested wrappers compose (`env -C .ax env -C ledger …` runs in `.ax/ledger`), an `env -S` string
289
+ is read in place and split by env's own grammar (a `#` comment, `\c`, `\_`; a `${VAR}` leaves the
290
+ base unknown), several `-C` in one `env` leave the base unknown, wrapper options are read the way
291
+ getopt reads them (`timeout -s KILL 5`, bundled `env -iC`, `env -P`, `sudo -R`, `--ch=` prefixes; an
292
+ option the gate does not know leaves the base unknown), and redirects are judged at the shell's own
293
+ directory wherever they sit in the command.
294
+ - **Every walker that reads source, tests or specs skips nested trees and reads regular files only**
295
+ (REQ-734): the Stop hook's known-defect walk (an un-ignored agent worktree's expired
296
+ `@known-defect` blocked the root session, 2–7 s per Stop), `entity_renumber`'s source plan, the seal's
297
+ kills advisory, `test_run`'s mutation target and the hooks' spec reader; renumber reads `.gitignore`
298
+ through the same non-blocking, capped reader as `loadIgnore`. Every git child of the Stop hook, and
299
+ the work-tree reads of `maintenance_analyze` and `attest`, run under a 5 s timeout (a FIFO
300
+ `.gitignore` kept `git status` blocked: the Stop hook never finished and `maintenance_analyze` wedged
301
+ the MCP server — measured); a timed-out query is remembered, so a walk waits at most once; a file git
302
+ lists is read only when it is a regular file; worktrees are listed with `-z`; and a link into a
303
+ skipped nested tree is not followed. Every git child in the source tree now carries a timeout and a
304
+ 256 MiB output buffer (a census test reads the tree): Node's 1 MiB default made the Stop hook's
305
+ ART-1/ART-2 checks read "no signal" on a large repository — this repository's own 15.3 MB ledger
306
+ was never checked for rollback. A root whose git timed out is remembered once for the hooks, the
307
+ walkers and `maintenance_analyze`; a Stop signal that could not be judged is named on stderr; the
308
+ `.ax` state files and `reverse_anchor`'s mapped files are read as regular files only (a FIFO in
309
+ their place hung the hooks and the MCP server).
310
+ - **No product process blocks on a file that is not a regular file** (REQ-734, round 13). The hooks
311
+ (both PreToolUse threads, Stop, SessionStart, the refresh child, the Antigravity entry points), the MCP
312
+ server and the CLI install one guard at start: `readFileSync`, `writeFileSync` and `appendFileSync` of a
313
+ path open it non-blocking and refuse anything but a regular file, and `openSync` never waits. Measured
314
+ before: a FIFO at `ax.config.json`, the Write target, `go.mod`, a ledger, `.ax/state/replica-id`,
315
+ `.ax/ledger/stop-guard.json` or `.mcp.json` held a hook past its deadline — the PreToolUse worker printed
316
+ its deadline deny and the process still did not exit. A test traces every path each hook opens and puts
317
+ a FIFO at each one in turn. The git timeout memory is kept per kind of query (a slow `status` no longer
318
+ silences `worktree list`, which had the Stop hook judge three agent worktrees' files), every Stop git child
319
+ goes through it (one wait per kind; `include.path` → FIFO took 27–32 s), every article the Stop hook
320
+ could not judge is named, `test_run`'s runners are bounded (30 min; jest `--forceExit`; an open handle
321
+ after a passing test wedged the server; a stopped run says so at the end of its result), and doctor's
322
+ `npm config get prefix` has a timeout. The shipped `bin/holmes-kit.js` and `bin/holmes-pre-push.js` install the
323
+ guard too. Index-only git queries skip the `core.fsmonitor` hook (a slow hook made the Stop hook judge a
324
+ registered worktree again), and when git does not answer, PreToolUse judges every `rm` target as tracked in
325
+ the project instead of treating the tree as "not a repository" (`rm -r <tracked dir>` was allowed silently).
326
+ Only a git that says "not a git repository" (or no git) counts as no repository: a refusal inside one —
327
+ dubious ownership (common with container bind mounts), an unknown `extensions.*`, a corrupt index — is "did
328
+ not answer", judged strictly and named. A directory holding `.git` whose nesting git cannot answer is skipped
329
+ by every walker and named, and what was skipped is not called judged: `ci` fails and names it, `attest` marks the
330
+ commit `+unknown` (walking it instead let `entity_renumber` plan a registered worktree's files and `test_run`'s
331
+ scope take its tests). `attest` marks a commit `+unknown` when the status did not answer, and says `unknown` for a
332
+ repository git refuses to read. Whether a directory is a repository is read from the tree
333
+ (a `.git` above it), not from git's message, which is translated under a non-English locale; every product
334
+ process drops `GIT_DIR`-style variables from its own environment at start (the scanner kept an exported
335
+ `GIT_DIR` and listed a registered worktree's files). The rm gate takes a signal that makes it stricter (tracked,
336
+ outside the repository) from any repository, and "ignored ⇒ regenerable" only from the repository that tracks the
337
+ project's specs (a parent ignoring `*` — the dotfiles pattern — allowed `rm -rf src`); it compares NFC and
338
+ case-folded paths, treats a target under a submodule as tracked, and judges each relative target from every
339
+ directory the command may run any part in — a flow-insensitive set (loops, functions, `trap` strings and variables
340
+ run text after a later `cd`; `cd src && rm -r lib` and `for …; do rm -r lib; cd src; done` deleted tracked `src/lib`
341
+ unasked), with the literal `cd`s of a loop, function or trap applied until the set settles (`until [ -d .git ]; do
342
+ cd ..; done && rm -r src` climbed past a single pass), unknown (and so strict) only where a `cd` cannot be placed
343
+ (`cd${IFS}src` included), so ordinary cleanups such as `source .venv/bin/activate && rm -rf build` stay allowed;
344
+ a segment the model places with certainty keeps its own directory (`rm -rf build; cd ..` was refused as
345
+ out-of-project), one it cannot place is judged from the whole set, a backtick next to a cd argument is unknown, and
346
+ any function definition and zsh `repeat`/`foreach` repeat (`repeat 2 cd ..; rm -r .ax` was allowed; quoted text
347
+ such as `git commit -m "call build()"` does not count), a removal of an ordered command is judged from where the cds
348
+ written before it can lead (`cd web && npm ci && cd .. && rm -rf build` was refused), the unknown-set store rule
349
+ applies to a command the gate recognises as writing — a writer by name behind any wrappers, precommands or leading
350
+ redirects, a programmable reader's write form, a tree-writing `git`, an interpreter's own one-liner flag, a shell running
351
+ a program in any spelling (`bash -lc`, `su -c`, a here-string, `eval`), and every stage of a pipeline into a shell or an
352
+ `xargs` that runs a shell or a writer (`echo rm ledger/x | sh`), and a `>`, `>>` or `<>` redirect into the store; a segment
353
+ recognised only by its redirect has only the redirect's target read (`terraform plan -state=state/x > plan.txt` passes) —
354
+ while a command it does not recognise passes to the harness, an unrecognised wrapper or runner (`taskset`, `script -c`,
355
+ `tmux`) included (owner decision:
356
+ `npx playwright test specs/…`, `git add specs` and `ls specs 2>/dev/null` were refused, and a listed-verbs version let
357
+ `perl -pi`, `/bin/rm` and `git checkout -- ./specs` through), a relative `cd` after one the model cannot place is
358
+ unknown too (`cd nope; cd src && rm -r lib` deleted `src/lib`), a physical `cd -P`/`set -P`
359
+ and a harness working directory go through links as the kernel does, an `&&` chain's failed cd stops its
360
+ successors, and a subshell's `)` is not part of an rm target — and
361
+ by its real path too (an untracked link aliasing a tracked directory). The shell model reads a quoted or escaped
362
+ `cd`/`pushd`/`env`/`eval` word (`\cd`, `"cd"`, `$'\x63d'`), a backslash-newline, a brace-listed `{cd,…}` and zsh's
363
+ `noglob`/`nocorrect` as the shell does, and a command word the shell expands (`$C`) as a possible cd; every rule reads
364
+ a quote-removed plain word as itself and an escaped `eval`/`sh -c` program as the one program it is (`r''m -rf
365
+ /usr/local`, `r\m -rf .git`, `g''it reset --hard`, `eval rm\ -rf\ src` were allowed while their plain forms were
366
+ denied); the `.ax` rules judge every segment from every `.ax` directory the command may visit, and, where that set is
367
+ unknown, a path starting with a protected `.ax` child under `.ax` too (`cd "$(printf '.%s' ax)" && echo x >
368
+ ledger/provenance.jsonl`). Each of these deleted `.ax/specs`, the ledger or tracked source unasked before; the
369
+ brace reading is linear (a 200 KB minified-JSON heredoc hit the hook's deadline). A governed monorepo package is
370
+ judged on its own paths: the Stop hook's and `attest`'s status is read relative to the package and limited to it
371
+ (the whole-repository status of a 200k-file monorepo cost 20–25×), its prefix matched NFC and case-folded (ART-1/5/8
372
+ returned nothing and `attest` called a dirty tree clean, also after a case-only rename of the package directory),
373
+ and the status is read with `-z` (a name holding ` -> ` or a quote was read as another path); `attest` counts a
374
+ deleted source and a spec renamed out of the store as dirty. The Stop hook resolves its project root once (1,000 test files took
375
+ 16.7 s; now 0.75 s) and reads tests from the project root. The Antigravity adapters relay the hooks' notices.
376
+ - **`.gitignore` matching memory and fairness are bounded** (REQ-733): the required-literal index keeps
377
+ at most 16 characters per distinct literal (a shared-literal file built 407 MB), a query visits each
378
+ index node once and confirms a rule's full literal before charging it (9,996 rules sharing a literal
379
+ cost 11.6 s over 1,000 paths; 120 generated-stub names tripped the budget), the per-path budget is
380
+ spent only on candidates that survive the prefix test and scales with the path length, a darwin path is ignored only when both its
381
+ given and its NFC spelling are (git precomposes only under `core.precomposeunicode`), and OS signals are read
382
+ at every shell command position (`if`/`while`/`!`, behind `nohup`/`time`/`env VAR=`/`xargs`/`sudo -E`,
383
+ inside `$(…)`), for `require('os').userInfo` and namespace `os` bindings, and for Ruby backticks
384
+ outside strings; Python's `from platform import (` scan is linear.
385
+ - **Walkers read gitlinks by mode** (REQ-734, A-SPEC-734): only a mode-160000 entry is a submodule; a tracked file
386
+ whose case-fold equals a directory's no longer hides that directory's tracked code.
387
+ - **The Codex oracle attributes a layer's refusal by asking again from a neutral cwd**, exits only
388
+ after its answer is flushed (answers over 64 KiB were cut on macOS), reads `[hooks.state]` in `init`
389
+ as `doctor` does, points a kept user-level `[otel]` exporter endpoint at a closed address without
390
+ changing its shape (project-layer `otel` is ignored, as Codex ignores it), asks about the target by
391
+ its real path, and names the LAYER — not the user file — when a trusted project's
392
+ `.codex/config.toml` refuses, disables or overrides the server; every claim `init` makes without
393
+ Codex is labelled `approximate`. The oracle no longer imitates Codex's URI parser: a kept
394
+ `[otel]` exporter is redirected only when it is `http(s)://host[:port][/path]` with exactly one
395
+ kind (and `protocol` `binary`/`json` for `otlp-http`); any other exporter table means Codex is not
396
+ started and the verdict is `approximate`. Its answer is decoded across chunk boundaries (a
397
+ multi-megabyte Hangul `hooks.json` came back intact), it sweeps only temporary homes carrying its
398
+ own marker, it dies with its parent, and it asks about the target by both the given and the real
399
+ path, keeping the stricter answer (the Holmes PreToolUse hook's absence counts) and naming both
400
+ refusals. `sqlite_home` and `analytics` isolation is judged from the USER COPY alone; a workspace
401
+ layer carrying a value Codex would refuse (a non-string `sqlite_home`) makes the oracle decline
402
+ before codex starts, labelled approximate — an untrusted layer's `sqlite_home = 5` had skipped the
403
+ override and Codex created and migrated its SQLite databases at the user's absolute path
404
+ (measured). The user file itself is not a workspace layer, the worker forwards only the fields
405
+ the verdict reads (a 25 MB hooks file overflowed the pipe buffer), doctor and init name
406
+ `[features] hooks = false`, and `_` is allowed in a collector's host label. Isolation cannot be
407
+ repaired by a layer: when the user copy's `sqlite_home` (or `analytics.enabled`) is a value the
408
+ override must not mask, any workspace layer setting that key makes the oracle decline — Codex
409
+ merged a trusted layer's valid path over the copy's invalid one and created its databases there
410
+ (measured). Layers are read for both spellings of the target, an unreadable or oversized layer
411
+ declines rather than reading as absent, and of the two asks (as given, by real path) the stricter
412
+ answer is kept per aspect, a replaced server table included. The entry Codex will run is judged
413
+ beyond `command`/`args`: a trusted layer's `env.HOLMES_SPECS` or `cwd` (which bind the server's
414
+ spec store elsewhere) is a `codex wiring env` WARN naming the layer, and a `disabled_tools` (or a
415
+ non-empty `enabled_tools`) that takes a gate tool away is a FAIL — Codex deep-merges these and
416
+ doctor said PASS (measured). init prints a layer's refusal only while it still holds after the
417
+ write; a copy the oracle cannot parse that Codex loads declines; the copy is capped at 1 MiB.
418
+ Authority is judged in the environment Codex hands the server: a layer's approval, autonomy, gate
419
+ or egress-consent key (`HOLMES_APPROVAL`, `HOLMES_AUTONOMOUS_APPROVAL`, `GEMINI_API_KEY` …, compared
420
+ without case), in `env` or in `env_vars` of either form, is a FAIL and init does not say "active";
421
+ one the user file carries itself is a WARN. Every other enabled MCP server handed such a key is
422
+ judged whatever its command, a Holmes table only a layer provides is judged instead of reported
423
+ "not active", both spellings' environments are merged, and a relative `HOLMES_SPECS` or a
424
+ `CLAUDE_PROJECT_DIR` from a layer is a redirect WARN. A trusted layer's server runs arbitrary code, so
425
+ launches and environments are judged by class: a Holmes server launch another layer provides or
426
+ changes must be one of the two shapes init writes (and, for `node`, this install's entry) — an
427
+ `env` wrapper, `--env-file` or `--require` handed a recording server a forged key (measured) — and a
428
+ changed launch makes every authority key the server holds the layer's; any other key a layer puts in
429
+ a Holmes server's environment (`HOME`, `PATH`, `NODE_OPTIONS`, proxies, and every `HOLMES_*` key
430
+ that does not merely switch a feature off — `HOLMES_PYTHON` picked `test_run`'s interpreter) is a
431
+ FAIL, judged by the name the process receives (a key `"HOLMES_AUTONOMOUS_APPROVAL=1"` reached the
432
+ server as `HOLMES_AUTONOMOUS_APPROVAL`); every layer-provided `node` launch — second servers and a
433
+ layer-only table included — must resolve to this install's entry. Holmes servers are recognised
434
+ lexically and no file is opened for that (a real-path check took 46 s on a symlink chain).
435
+ A layer's `npx` launch must pin exactly this install's version (a layer pinning `0.20.0+x` read PASS);
436
+ a layer's `node` launch path is resolved the way node resolves `argv[1]` — `.`/`..` removed as text,
437
+ then links walked one component at a time, never into a network or automounter path (`/net`, `//`,
438
+ `\\?\`), at most 4,096 characters — so `<ws>/link/../bin/holmes-mcp.js` pointing at a wrapper is not
439
+ "this install"; every value a layer or Codex supplies in a doctor or init line is clipped; the user's own
440
+ `/opt/homebrew/bin/node` launch is node (`.exe`/`.cmd` only on Windows).
441
+ - **Walkers and readers are linear** (REQ-733/734): `.gitignore` patterns match by a token
442
+ table-walk (a `**`-heavy pattern no longer backtracks; star runs coalesce into single sweeps —
443
+ 20 KB of `*` cost 138 ms per file), a class the engine refuses (`[a-Z]`) makes one line
444
+ unsupported instead of dropping every rule of the file, the hook's top-level splitter is comment
445
+ aware, the redirect strip scans by index, the Files-to-Touch normalizer is a linear segment stack
446
+ (`x/` + 170,000 `../` took 5 s per Edit through the gate), and an OS signal needs a real `os`
447
+ binding (`'os'` in a string is none).
448
+ - **Walkers read regular files only, and ask git once** (REQ-734): a FIFO named `src/pipe.ts`
449
+ blocked the graph scan and test discovery forever (a non-regular entry is now a recorded skip);
450
+ the ignored-directory question is answered once per root from `git ls-files -o -i --directory`
451
+ (NFC on both sides) instead of one `check-ignore` spawn per directory holding a `.git` entry
452
+ (2,000 planted `.git` files: 26 s per scan); worktrees are matched by on-disk case; `..x/` is
453
+ inside the root; the file-anchor census skips nested trees; and Jest collects tests from
454
+ `roots: ["<rootDir>/src"]` — the earlier unanchored ignore pattern excluded every test when the
455
+ project root itself was an agent worktree, and a `<rootDir>`-anchored one broke under a path
456
+ holding `+` or `(`.
457
+ - **`.gitignore` matching is linear in the rule count and bounded at the reader** (REQ-733):
458
+ rules are tried last-to-first with early exit and indexed by their literal tail (100,000 rules
459
+ cost 387 ms per file), `loadIgnore` reads a regular file non-blocking under a 2 MB cap (a FIFO
460
+ named `.gitignore` blocked every act), `**` follows git (a double star only when bounded by `/`),
461
+ and a class starting with `]` keeps it literal.
462
+ - **The compatibility cross-check knows the wiring and more shapes** (REQ-733): `.codex/`,
463
+ `.claude/settings|hooks|skills`, `.agents/`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` are harness
464
+ surfaces; OS signals cover `shelljs`/`zx`/`execa` imports and bindings, tagged-template process
465
+ calls, named `os`/`path`/`process`/`fs` imports across lines, POSIX signals, Python
466
+ `os.popen|fork|exec*` and platform-only modules, Rust `std::os`/`libc`, Go `syscall`, and more;
467
+ measured false signals are gone (clap's `Command::new`, a Django `platform` instance, `path.posix`,
468
+ a method `.system(`, the `os.type` property, docstrings and `=begin` blocks); refusals quote at
469
+ most 200 characters of a token.
470
+
471
+ ### Fixed
472
+
473
+ - The edit gate's Files-to-Touch extractor was quadratic (a 160 KB section took 15 s); it is linear
474
+ and returns exactly the previous matches.
475
+ - Codex `config.toml`/`hooks.json` readers: escaped keys, multi-line pins, CRLF, BOMs, depth,
476
+ integer ranges, `env_vars` tables (REQ-731, A-SPEC-731, rounds 1–10).
477
+
478
+ ### Known limitations
479
+
480
+ - Hook trust in Codex cannot be verified offline.
481
+ - A binary copied or hard-linked under a harness name still attests (a code-signature check was
482
+ declined).
483
+ - Directory or glob Files-to-Touch entries are not read for OS signals.
484
+ - **doctor does not start an npx wiring** (owner decision): the npx launch `init` writes reads PASS by
485
+ its shape, so a canonical npx wiring that pins a version the registry does not have, or whose local
486
+ npx cache entry is damaged beyond its root `package.json`, reads PASS ('mcp server version' still
487
+ compares the pin with this CLI; the 'npx cache' check reads only Claude's pin).
488
+ - Shell gate (MEDIUM, named): a colon in a tar bundle (`tar -:xf`), `-W` inside bundles, a directory
489
+ member under a strip option inside a wiring directory, location-only targets after a literal `cd`,
490
+ bash `$"…"`, GNU `--one-top-level`/`--to-command`, interpreter one-liners that run tar or unzip, tar's
491
+ neighbours (`unzip -j`, `pax -s`, `git archive -o`, gunzip, cpio); under a strip option a value of
492
+ another option (`--exclude settings.json`) is read as a member and refused (over-refusal).
493
+ - doctor and init (MEDIUM, named): the `git` doctor finds through PATH; a PATH entry on a network path
494
+ (`/net/…`, `\\server\…`) is resolved when the probe environment is built; run through `npm run
495
+ doctor`, the `npm_config_*` and `INIT_CWD` npm exports reach doctor's children; a wiring naming the
496
+ user's version-manager shim by absolute path is started in the target; a PATH entry whose directory
497
+ part passes through a workspace link and lands outside reads PASS; on Windows the bare words
498
+ `taskkill.exe`, `where.exe`, `powershell.exe` and `cmd` (a requirement of its own, to be measured on
499
+ Windows — nothing of the Windows paths in this release was measured on Windows); doctor's npm probes
500
+ fall back to the bare word `npm`; init's keychain query.
501
+ - Named residuals: `entity_integrate`'s destination walk still reports an un-ignored foreign worktree's
502
+ files as untracked conflicts; `.gitignore` re-inclusion under an excluded directory and `core.ignorecase` err toward
503
+ scanning more; the Codex oracle does not judge an ancestor layer of a target that is not wired for
504
+ Codex, `tool_timeout_sec = 0`, or a trusted layer's `[hooks.state]`; a Holmes server launched through
505
+ a path that names neither `holmes-mcp`, its dist entry nor the package is recognised only by its
506
+ `HOLMES_*` keys; after a `cd` the shell gate cannot resolve (`cd "$X"`, `source`/`.` of a script,
507
+ `eval`) in a command that does not spell `.ax`, a bare relative path into a store child
508
+ (`ledger/…`) is judged at the project root only; the compatibility check's OS signals miss a
509
+ paren-less Ruby `system "…"`, a tool behind value-taking wrapper options (`sudo -u X`, `timeout N`,
510
+ `xargs -n N`) or inside `{ …; }`, and an `os` default import under another name, and count backticks
511
+ inside Ruby heredoc prose.
512
+
8
513
  ## [0.30.0] - 2026-09-23
9
514
 
10
515
  New requirements now start from fresh, prompt-bound triage evidence in every supported harness,
package/README.md CHANGED
@@ -23,6 +23,9 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - 🚦 **The gate only ever denies** *(changed in 0.31.0)*: an action Holmes does not deny is left to your harness's own permission flow — Claude Code and Codex get no permission decision, Antigravity gets `ask` (or `allow` for a read inside the workspace that git does not ignore). Earlier versions answered `allow`, which Claude Code treats as "bypassing permission prompt", so anything the shell model missed ran unconfirmed. In Claude Code's default mode you now see its confirmations again, as without Holmes.
27
+ - 🪝 **The Codex gate loads again on codex-cli 0.155** *(new in 0.31.0)*: plugin hooks were removed upstream, so `init --agent codex` wires the Holmes PreToolUse and Stop kernels into the user-level `$CODEX_HOME/hooks.json`, keeps every hook it does not own, and `--remove` takes away only its own groups. Codex runs a user hook only after you trust it once with `/hooks`; Holmes never forges that trust, and `doctor` says so instead of claiming enforcement.
28
+ - 🧭 **The shell gate judges by identity, from where the command really runs** *(new in 0.31.0)*: wiring files, the whole `.ax` store and the files inside it are protected as shell WORDS resolved against each segment's real base — a `cd` moves the base only when it is certain to have run, an uncertain or expanded one (`cd .a?`, a link made in the same command, `cd "$X"`) leaves it unknown and the command is judged at every base it could have produced, and the base starts at the harness's own working directory (the payload `cwd`, a Codex `workdir`), not the project root. Every evaluation runs under a fail-closed deadline wall. The Codex oracle asks the installed Codex whether your config loads — locally, over copies, with plugins and every proxy closed, `sqlite_home`/`analytics`/`otel` isolated from the user copy alone, and a verdict it could not obtain labelled `approximate`. Source walkers skip nested git working trees only when git says the tree is not the project's, read regular files only, and ask git once per scan; every reader on a gate path is linear in its input.
26
29
  - 🪟 **Approval stays inside the agent session** *(new in 0.29.0)*: Claude Code, Codex, and Antigravity use the same capability-negotiated route. Holmes opens a direct MCP form only when that live client advertises `elicitation.form`; otherwise it exposes one sensitive, challenge-bound `approval_commit` continuation in the same agent session. The host may render its native tool confirmation, but its arrival is recorded as `host-gated`, never claimed as proof that a human answered. The server issues an opaque, memory-only intent bound to the action kind, target, subject digest, workspace and MCP run; only one matching retry can consume it. No `config.toml` value or persisted `HOLMES_APPROVAL` is authority. The `holmes-kit approve` TUI is recovery-only when a session cannot present approval. Under autonomous mode, eligible low-risk work stays automatic and an ordinary unclassified HITL request queues without interrupting the agent; only an observable direct-form timeout on high-risk or irreversible work takes the auditable `autonomous-timeout:<harness>` route. Cancel, deny, malformed and unavailable outcomes never auto-approve.
27
30
  - 🧾 **A new prompt is checked against governed intent before it becomes a new spec** *(new in 0.29.0)*: `requirement_triage` reads the approved REQ/H-SPEC/A-SPEC/T-SPEC lineage, a receipt-bound current RTM graph, source and requirement-document semantic coverage, code anchors, and exact-HEAD execution evidence before recommending `fulfilled`, `existing-change`, `new`, or `ambiguous`. BM25 is always present; a verified local BGE-M3 cache and explicit Gemini opt-in add candidates and also enter the ranking score, so when lexical evidence is weak or tied a semantic match can decide which lineage leads — every such answer shows its semantic coverage, and a run that used no semantic score says `lexicalOnly: true`. A cold, stale, unreadable, failed, partial, or absent lane remains visible as ambiguity; a workspace with no semantic tier, or with transfer switched off by `HOLMES_NO_SEMANTIC_WARM`, runs **lexical-only** — it can still author a new REQ, and the answer and its evidence say `lexicalOnly: true` (set it in the environment of both your harness — its hooks spawn the background refresh — and the Holmes MCP server; a refresh recorded as suppressed also keeps triage from embedding. The switch stops automatic transfer: the background refresh embeds neither source nor requirement documents, and `requirement_triage` does not embed the prompt; tools you invoke explicitly under an opted-in cloud tier — `maintenance_analyze`, `issue_localize`, `rtm_reindex` — still embed their query or index as before). The detached refresh worker warms both versioned semantic populations under existing cloud-consent rules; a persisted v2 artifact binds prompt, workspace, HEAD, and receipt generation. New REQ creation — through `spec_create` or `spec_slice_init` — verifies that evidence at one shared MCP boundary, so no supported harness or tool can bypass it.
28
31
  - 🧭 **One governed operating contract survives every harness** *(new in 0.28.0)*: the common managed block in `AGENTS.md` carries the same No Spec, No Code rules to Claude Code, Codex CLI, and Antigravity while leaving the repository's own rules outside the block intact. `holmes-kit guidance check` names a stale or locally conflicted managed block, `guidance refresh` first plans the change and then replaces only the Holmes-owned region, and `doctor` runs the same check. An installer or upgrader cannot silently discard local guidance.
@@ -108,7 +111,7 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
108
111
  | :--- | :--- | :--- |
109
112
  | 🤖 **Claude Code CLI** | 🥇 Tier 1 (Native) | OS PreToolUse & Stop hooks (`.claude/settings.local.json`), MCP server (`.mcp.json`) |
110
113
  | 🚀 **Antigravity CLI (AGY)** | 🥇 Tier 1 (Native) | AGY Hooks (`hooks.json`), MCP config (`.agents/mcp_config.json`), Governance Skills |
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`). |
114
+ | 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (user-level `$CODEX_HOME/config.toml`, normally `~/.codex/config.toml`, shared by every workspace), plugin-packaged gate hooks at the marketplace path Codex reads (`.claude-plugin/marketplace.json`). Hard-gate enforcement was verified on codex-cli 0.152.x; codex-cli 0.155.x removed plugin hooks (`plugin_hooks: removed`), so `init --agent codex` also wires the pre-tool and Stop gates into the user-level `$CODEX_HOME/hooks.json`, preserving your own hooks (REQ-727). **Codex runs that hook only after you trust it once: open `codex` and run `/hooks`.** Holmes never writes that trust, and `doctor` WARNs because it cannot verify it offline (live evidence: `docs/goals/EVIDENCE-live-sessions-2026-09-23.md`). |
112
115
  | 🧩 **Google Antigravity SDK** | 🥇 Tier 1 (Native) | Autonomous Agent SDK bindings and cryptographic provenance verification |
113
116
 
114
117
  > **Note**: Holmes-Kit focuses strictly on CLI-based autonomous agents to guarantee 100% deterministic OS hook gating (`deny` enforcement) before file modifications occur.
@@ -140,6 +143,12 @@ Add `-DryRun` to see what it would do without installing. Exit codes: `0` ok / a
140
143
  | CI / container | none | same, plus `--prefer-online` right after a release |
141
144
  | CLI across many projects (`-g`) | depends | run `npm config get prefix` first — see below |
142
145
 
146
+ **How the MCP server is wired** *(0.31.0)*: from an install (`--save-dev` or `-g`), `init` wires every
147
+ harness as `node <install>/bin/holmes-mcp.js`. A zero-install `npx` run has no lasting path, so it is
148
+ wired through `npx` — and npx runs npm in each session workspace, whose `.npmrc` (`node-options`,
149
+ registry) and `node_modules` can replace the Holmes server. `init` and `doctor` say so; install, then
150
+ re-run `holmes-kit init --force`.
151
+
143
152
  **Stale global shadowing** *(field-measured on Windows, 2026-08-31)*: an old global install makes the
144
153
  bare `holmes-kit` command run the OLD version while `npx holmes-kit` runs the local one — and
145
154
  Windows has TWO global roots (`C:\Program Files\nodejs` and `%APPDATA%\npm`), so `npm uninstall -g`
@@ -1,5 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  // @implements A-SPEC-193
3
+ // @implements A-SPEC-734
3
4
  // Antigravity PreToolUse 진입점 — 번역만 한다. 판정은 dist 의 훅 프로그램이 내린다.
4
5
  //
5
6
  // 가드는 require 앞에서 Node 내장만으로 돈다(bin/holmes-kit.js 와 같은 이유). 그리고 가드가
@@ -23,6 +24,9 @@ let buf = '';
23
24
  process.stdin.on('data', (c) => { buf += c; });
24
25
  process.stdin.on('end', () => {
25
26
  try {
27
+ // A-SPEC-734 (round 13): the adapters run in this process, so the guard is installed here — a FIFO in the
28
+ // workspace must never hold this hook (the other harnesses' hook processes install it themselves).
29
+ require(path.join(__dirname, '..', 'dist', 'holmes', 'project', 'regular-file-guard.js')).installProcessGuards();
26
30
  const { adaptPreToolUse } = require(entry);
27
31
  process.stdout.write(JSON.stringify(adaptPreToolUse(buf, process.cwd())));
28
32
  } catch (e) {
package/bin/holmes-kit.js CHANGED
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  // @implements A-SPEC-100.2
3
3
  // @implements A-SPEC-173
4
+ // @implements A-SPEC-734
4
5
  // The guard runs BEFORE the require, using only Node built-ins. `runInit` carries the same guidance
5
6
  // but lives inside `dist` — measured 2026-08-12, a package whose `prepare` was blocked emitted
6
7
  // `node:internal/modules/cjs/loader` from every entry point and that guidance never ran.
@@ -17,6 +18,9 @@ if (!fs.existsSync(entry)) {
17
18
  process.exit(1);
18
19
  }
19
20
 
21
+ // A-SPEC-734 (round 14): this entry requires the CLI as a module, so the CLI's own `require.main` block never
22
+ // runs — the guard is installed here (a FIFO `.env` held `doctor` past 45 s — measured).
23
+ require('../dist/holmes/project/regular-file-guard.js').installProcessGuards();
20
24
  require('../dist/holmes/cli/index.js')
21
25
  .main(process.argv.slice(2))
22
26
  .then((code) => process.exit(code))