@holmes-lab/holmes-kit 0.40.1 → 0.41.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 (88) hide show
  1. package/CHANGELOG.md +86 -0
  2. package/README.md +12 -4
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-context.js +4 -3
  5. package/dist/holmes/cli/approve.js +22 -12
  6. package/dist/holmes/cli/autonomy.d.ts +21 -0
  7. package/dist/holmes/cli/autonomy.js +35 -5
  8. package/dist/holmes/cli/doctor.js +58 -6
  9. package/dist/holmes/cli/index.js +371 -250
  10. package/dist/holmes/cli/init.js +26 -6
  11. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  12. package/dist/holmes/cli/ledger-witness.js +252 -0
  13. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  14. package/dist/holmes/cli/playbook-skills.js +63 -354
  15. package/dist/holmes/cli/test-platform.d.ts +6 -0
  16. package/dist/holmes/cli/test-platform.js +12 -0
  17. package/dist/holmes/config/config.d.ts +9 -1
  18. package/dist/holmes/config/config.js +10 -3
  19. package/dist/holmes/governance/approval-grants.d.ts +2 -0
  20. package/dist/holmes/governance/approval-grants.js +6 -5
  21. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  22. package/dist/holmes/governance/approval-queue.js +279 -9
  23. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  24. package/dist/holmes/governance/autonomous-shell.js +157 -4
  25. package/dist/holmes/governance/autonomy.d.ts +209 -0
  26. package/dist/holmes/governance/autonomy.js +1129 -6
  27. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  28. package/dist/holmes/governance/install-manifest.js +159 -15
  29. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  30. package/dist/holmes/governance/ledger-witness.js +296 -0
  31. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  32. package/dist/holmes/governance/provenance-chain.js +23 -4
  33. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  34. package/dist/holmes/governance/recorded-pairs.js +25 -1
  35. package/dist/holmes/governance/session-context.d.ts +7 -0
  36. package/dist/holmes/governance/session-context.js +34 -6
  37. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  38. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  39. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  40. package/dist/holmes/guardrail/command-traits.js +379 -0
  41. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  42. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  43. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  44. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  45. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  46. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  47. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  48. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  49. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  50. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  51. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  52. package/dist/holmes/guardrail/write-target.js +7 -1
  53. package/dist/holmes/hooks/pre-tool-use.d.ts +60 -0
  54. package/dist/holmes/hooks/pre-tool-use.js +1423 -10
  55. package/dist/holmes/hooks/session-start.js +11 -1
  56. package/dist/holmes/hooks/stop.d.ts +7 -0
  57. package/dist/holmes/hooks/stop.js +39 -2
  58. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  59. package/dist/holmes/mcp/elicit-approval.js +5 -2
  60. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  61. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  62. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  63. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  64. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  65. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  66. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  67. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  68. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  69. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  70. package/dist/holmes/mcp/handlers/test-execution.d.ts +6 -0
  71. package/dist/holmes/mcp/handlers/test-execution.js +37 -9
  72. package/dist/holmes/mcp/handlers.d.ts +5 -5
  73. package/dist/holmes/mcp/handlers.js +2 -1
  74. package/dist/holmes/mcp/tool-schemas.js +4 -4
  75. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  76. package/dist/holmes/project/playbook-reference.js +259 -0
  77. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  78. package/dist/holmes/project/playbook-skill-states.js +396 -0
  79. package/dist/holmes/project/root.d.ts +9 -1
  80. package/dist/holmes/project/root.js +23 -2
  81. package/dist/holmes/project/running-package.d.ts +15 -0
  82. package/dist/holmes/project/running-package.js +87 -0
  83. package/dist/holmes/review/head-worktree.js +9 -1
  84. package/dist/holmes/review/test-runner.d.ts +2 -0
  85. package/dist/holmes/review/test-runner.js +38 -11
  86. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  87. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  88. package/package.json +5 -2
package/CHANGELOG.md CHANGED
@@ -7,6 +7,92 @@ 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.1] - 2026-11-13
11
+
12
+ ### Fixed
13
+ - **Removing a backup `init` left no longer closes governance staging (A-SPEC-794.121; 0.41.0 Known limitation, present since 0.40.1).** `init` recorded every file under a recovery skill's directory in the install manifest, so its own backup of a user's edited skill (`SKILL.md.holmes-bak-<id>`) became a product file: removed, it was `missing`, and under a full autonomy profile governance staging was refused with no request. `init` now records only what the package ships there, each skill's `SKILL.md`, and the next `init` drops an earlier record of anything else inside a recovery skill's directory — by location, not by file name. A workspace whose manifest already records a removed backup stays closed until a person runs `holmes-kit init` once; the refusal now says so. `init` and `skills refresh` now keep the backup of a rewritten recovery skill under `.ax/state/skill-backups/holmes-<name>/` (git-ignored, outside everything the gate watches) instead of beside the skill, and the report names that path (A-SPEC-794.126). A backup an earlier version left beside a skill stays where it is and is no longer recorded; in Holmes-Kit's own checkout principle 7 still counts it, as every file under `.claude`, until a person moves or deletes it. The settings backup `init` writes beside `.claude/settings*.json` is unchanged.
14
+ - **The ledger-witness form leads with the witness's verdict (A-SPEC-794.125; 0.41.0 Known limitation, supervisor review M1).** The form a person reads before vouching opened with the comparison against the pushed chain, read through the local upstream ref (`@{u}`), which a session can move — so its first line could be made to say "This chain is the pushed one". Line 1 is now the witness's own verdict, and every verdict but `ok` carries a warning: "Do not vouch unless you mean this chain, as it is, to be the reference", or, for `no-witness`, that this is either the first vouch or a removed witness (the witness lives under `.git`, which a shell can delete) — and that it was removed when the chain records a vouch decided in the session form. The lists cover the whole chain for every verdict (A-SPEC-794.127, 794.129): the witness checks the witnessed row and the length, not the rows before it, so no verdict vouches for a prefix; under `ok` they say so, and under every other verdict a list cut at 40 rows says to check the chain file itself (A-SPEC-794.130). Resistance to a forged witness file is not verified; the form is as strong as the witness (A-SPEC-794.114's same-uid limit), and a vouch made at a person's own terminal leaves no record, so there a removed witness reads as a first vouch. Line 2 is the comparison, prefixed "By the local ref <ref> (a session can move it; compare with the remote yourself if it matters)". The rows the form lists ("Rows a person acts on", "Gate rows") no longer depend on the ref; a ref pointed at a copy of the chain used to hide them. The request's subject, the grant and the judgement are unchanged.
15
+ - **A full test_run's `testRun.prepare` and a mutate run's jest are told the tree they run in (A-SPEC-794.123).** 0.41.0 gave a test run's children `CLAUDE_PROJECT_DIR` naming the tree that runs (A-SPEC-794.119), and named two children as left out: the prepare (a build in HEAD's worktree) still saw the server's checkout, and `test_run` with `mutate` ran its jest outside the run's scope. Both now take the test environment: `CLAUDE_PROJECT_DIR`, where the server carries it, names the worktree (prepare) or the run's root (mutate). The prepare also no longer receives the keys an evidence run never hands a test child: newly `HOLMES_SPECS`, `HOLMES_MCP_AUTORELOAD`, `HOLMES_MCP_PROFILE`, `npm_config_dry_run`, `PYTEST_ADDOPTS` and `PYTEST_PLUGINS` (the approval, ledger-key and gate-bypass keys were already removed from every child). `PATH`, `HOME` and the npm registry settings reach it as before.
16
+ - **A full test_run no longer drops a declared `testRun.prepare` silently (A-SPEC-794.123).** A HEAD whose `ax.config.json` could not be parsed was read as the default configuration, so the run went ahead with no prepare and could record green evidence without the step the commit declared. Now such a config ends the run as not passed with the reason (`testRun.prepare could not be read: …`), and nothing is recorded. The contract (A-SPEC-794.128, replacing the clause the `config.ts` comment under A-SPEC-128.13 stated): `testRun.prepare` absent, `[]` or `null` declares none; any other value that is not a non-empty array of non-empty strings makes a full run fail with that reason.
17
+
18
+ ## [0.41.0] - 2026-11-12
19
+
20
+ ### Upgrading
21
+ - **Un-seal and retire are their own approval kinds.** A grant or an out-of-band approval scoped to `spec-approve` no longer covers `spec_unseal` or `spec_retire`; scope it to `spec-unseal` or `spec-retire` (an unscoped approval still covers them). A 0.40 `holmes-kit approve --list` does not list requests of the new kinds — decide them in the session form (`approval_ask`) or with the 0.41 CLI.
22
+ - **Requests close by themselves after 24 hours.** A hook's or the CLI's request that nobody decided is closed unrun (`closed-expired`) at the next session start; asking again files it anew. A 0.40 reader ignores the event and keeps such a request pending.
23
+ - **Principle 7.** Under a full profile, a spec whose Files to Touch names the gate and approval-processing category (now much wider — see Changed) goes to the person's form instead of sealing as full-autonomy, and a declared `gate-behavior: tightens|wording` no longer self-seals such a spec in any autonomy mode.
24
+ - **R1 sealed-spec staging is on by default under a full profile.** `"autonomy": { "specStaging": "off" }` in `ax.config.json` brings back the person's form for every spec path.
25
+ - **An autonomy command with an approval set in the command is refused (`profile.own-request`).** Run `holmes-kit autonomy full|on|delegate` without the variable: it files its own request for the session form.
26
+ - **Holmes-Kit's own checkout: vouch for the ledger once (A-SPEC-794.114).** The gate now reads its provenance chain only when a witness in the git directory says the chain is the one this repository wrote. A checkout upgraded from 0.40.x, a new clone or worktree, and a changed replica id start with no witness: Stop, commits and builds are closed there until a person runs `holmes-kit ledger witness` and approves its request in the session form. npm-installed consumers are not affected.
27
+ - **`holmes-kit ledger rechain` asks a person, and does not vouch (A-SPEC-794.114, 794.116).** The rewrite applies only to a plan a person approved in the session form or at their own terminal; `--dry-run` is unchanged. Measured 2026-11-12: inside a session it rechained a forked chain with no person, and the hook let `npx holmes-kit ledger rechain` through. The rechain's form shows how the judgement reads the chain now; approving it does not move the ledger witness — after a rechain that changed this writer's chain, run `holmes-kit ledger witness` (one more form), whose form compares the chain with the pushed one.
28
+
29
+ ### Known limitations
30
+ - The ledger witness (A-SPEC-794.114, 794.115) is as strong as the hook's refusal of writes to it: a script the command does not name, run with the same uid, can call the store's own append and write a witnessed row (without `HOLMES_LEDGER_KEY` the chain is a plain hash). Without an upstream branch the vouching form has no pushed chain to compare with and says so. The form's comparison with the pushed chain reads the local upstream ref (`@{u}`), which a session can move (`git branch -u`, `git update-ref refs/remotes/...`), so that line can be made to say the chain is the pushed one; the verdict line below it is the witness's and a session cannot move it — read the verdict, and do not approve `taken-back`, `extended` or `broken` (supervisor review M1, 2026-11-12; for 0.41.x).
31
+ - **Under full autonomy, removing a backup `init` left closes governance staging, with no request (present since 0.40.1; repair planned for 0.41.1).** When `init` overwrites a product recovery skill a user edited, it leaves `SKILL.md.holmes-bak-<id>` beside it and records that backup in the install manifest as a product file. If a person then removes the backup, the product-installed judgement reports it `missing`, and under a full autonomy profile the gate refuses a command that stages governance files (`full-autonomy.refused`) without filing a request — the agent has no route in the session. Workspaces without a full profile are not affected (their staging goes to a person's request as before). Ways out: put the backup back, run `holmes-kit init` at a person's terminal to refresh the install record, or stage the files at a person's terminal. Measured 2026-11-12 on consumer fixtures of 0.41.0 and of the published 0.40.1 (same result; the backup restored passes). In Holmes-Kit's own checkout, principle 7 also counts such an ignored backup as a change (it closes build, commit and Stop), so there it can neither stay nor go until a person refreshes the record. A rechain or a vouch run by a person at their own terminal is not shown in a form. Measured cost: reading and hashing a 30.6 MB chain takes 14 ms per judgement (no cache is kept).
32
+ - The hook judges `holmes-kit runtime-binding setup|remove` and `holmes-kit ledger rechain` by the words after the CLI word, behind any runner — not by the outward judgement's own unwrapping (A-SPEC-794.72), so a CLI word held in a variable, an alias or a pipe into a shell is not seen by the hook; the CLI's own person approval holds there (both commands ask for one). Measured on the recorded corpus (300 session commands, 500 commit messages, npm's commands): no false positive.
33
+ - The product-installed judgement of recovery skills (A-SPEC-794.100, 794.106) does not follow links: a linked skill file or directory keeps the digest judgement of the install record, and so do an aliased, unresolvable or orphaned skill and the case where the skills cannot be judged at all. What holds that record: only `init` rewrites it, and `init` refused in the two states measured (a drifted skill in a checkout; an unreadable playbook of a deployed package). In a checkout, a skill whose playbook is gone or unreadable is `drifted` and no longer goes to that record (A-SPEC-794.113). It judges only the `SKILL.md` of each skill, not other files in a skill directory. When the ledger file a command stages has not changed, the refusal text does not say so (review A-L1, A-L2, B-L3). The hook does not refuse a write to `.git/refs/replace/` or `.git/packed-refs`; the skills' judgement reads no git object, and principle 7 reads git with replacement objects off, so such a write does not reach either (A-SPEC-794.110, 794.113).
34
+ - **The runtime that dispatches the hooks was writable from a session (present in 0.40.1 — observed 2026-11-12 in the owner's terminal with the published 0.40.1 hook: a Write to `~/.holmes/runtime/bindings.json` and to a runtime launcher, and a shell redirect, copy and removal there, were all allowed).** Who: an agent session in any governed workspace. When: the session deliberately writes one of those files. Closed in 0.41.0: the hook refuses writes, moves and removals under `~/.holmes/runtime` (A-SPEC-794.113), and judges `holmes-kit runtime-binding setup|remove` and `holmes-kit ledger rechain` wherever the CLI word sits, behind any runner (`npx`, `npm exec`, `pnpm dlx`, `bunx`, `env`, `node …/holmes-kit.js`, a `sh -c` program). Upgrade to 0.41.0.
35
+ - In a deployed install — a package whose real path has a `node_modules` segment: global, npx, or under a project's `node_modules` — the reference playbooks, the launchers and the gate's own code live in one package, and the hook now refuses a write, move or removal from the session anywhere under that package's root (A-SPEC-794.113: the Write and Edit tools, and a shell copy, move, redirect, link, mode change, removal or interpreter write, judged where the write lands). **The gate's own code was writable from the session in 0.40.1 too** — measured 2026-11-12 before this: the playbooks by every route, the dist by the shell (and by the file tools for a package outside the project); closed in 0.41.0. The package manager is not affected (`npm install`, `update`, `uninstall`, `-g`, `holmes-kit upgrade` name no file of the package), nor is a checkout of Holmes-Kit used as its own package. What the hook does not see is still open: a program that writes the package without naming it in the command (a script, a package manager's lifecycle), a relative path after a `cd` whose target the gate cannot read, and the person's own terminal. Forgery resistance against the same user is not claimed (owner decision 11/03).
36
+ - A package that is not deployed is judged against the playbook digests its gate recorded in its own ledger (A-SPEC-794.110). A package unpacked by hand outside any `node_modules` (a vendor directory, an extracted tarball) has no such record, so the autonomous approval of governance staging is closed there with the reason named, and a person approves; installing holmes-kit with npm frees it. The record is a row of the provenance ledger, as a person's seal is: the hook refuses a shell append, copy, move, interpreter write and git checkout over the ledger, and a row added or rewritten without the chain's hash closes the judgement, but without `HOLMES_LEDGER_KEY` a chain-valid row written with the package's own API by the same user is not told apart (the limit `doctor` names for seals).
37
+ - The recorded digest of a playbook moves only at a build the hook judged, while a person's window naming that playbook is open on this machine (a window row of this writer's chain, recorded after its latest baseline, carries the bytes' sha256) — so a playbook changed outside a window, checked out from an earlier version, or brought by a pull keeps its earlier digest here and its skill is not shown current until a person seals an A-SPEC naming it on this machine and a build follows inside that window. A change committed inside a window and built after it closed is not recorded either — the way out is the same: `spec_approve` again on the A-SPEC that names the playbook (the form says it is a re-seal; one answer), or a new A-SPEC naming it, then the build inside that window. A build run outside a governed agent session records nothing (A-SPEC-794.113). A digest reaches a baseline row in those two ways only — carried from this chain's latest row that has digests, or under such a window; nothing is taken from a commit, and where the ledger or a playbook cannot be read no row is written.
38
+ - A chain with no baseline row of its own starts closed: a new clone, a linked worktree (its replica id is `<host>-wt-<name>`) and a `run` execution (`<host>-run-<id>`, a new id every run) each write a chain of their own. Its first playbook digests are written only by a build inside a person's seal window of that chain whose A-SPEC names the playbooks (`playbooks/**`, or each `playbooks/<name>/PLAYBOOK.md` — `playbooks` alone names nothing in Files to Touch), so in a checkout that is not an npm install the autonomous approval of governance staging goes to a person there until then — in every automated run, as each starts a new chain. Reading the host's chain for a run is a 0.41.x candidate.
39
+ - A package reached through a link (`npm link`, a `file:` dependency, a workspace) is the checkout the link points at, not a deployed install: it is judged against that checkout's own recorded build, and closed while it has none.
40
+ - `doctor` judges the recovery skills with the package it runs from, and the gate with the package the sessions load. Run from another install than the routed one, doctor's verdict is that install's; its `recovery skills reference` row says so and names the command that asks the gate's install. Principle 7's git reads ignore `core.worktree`, configured filters, `core.trustctime`, `core.checkStat` and inherited `GIT_*` variables; they still trust git's own comparison of tree objects, so the hook refuses a program that is not git writing under `.git/objects` (objects, packs, `info/alternates`), changing a mode there, or moving or replacing the `.git` entry — in every project, by the file tools and the shell, judged where the write lands and, for a linked worktree, over the store of the repository it belongs to (A-SPEC-794.113; all of these passed the hook before, measured 2026-11-12). Git's own commands, reads and copies out of `.git`, and `rm` are not touched by the rule: removing an object makes git fail, and a judgement git cannot answer is closed. `HEAD`, refs, `packed-refs` and the index are not refused to a program that is not git either — a git command moves them as well, and the judgement compares the state with the ledger's baseline whoever moved it (tested by writing them directly). The skills' reference reads no git object.
41
+ - In Holmes-Kit's own repository a build and a commit are refused, and the turn's end is held, while git cannot read the repository (an unknown format version, `.git` moved away, git missing, or no answer within 10 seconds): principle 7 cannot judge the tree then, and says which it was — after a timeout, only "run this again" (A-SPEC-794.113). In that repository, content a window saw before the baseline in force no longer opens a gate file after the window closed: going back to an earlier version of a gate file needs a person's window. A directory that holds neither `.git` nor a baseline row is not judged.
42
+ - In that repository the judgement also closes where something used to stand in (A-SPEC-794.113): when the latest baseline row's commit is not in the repository (history rewritten and collected, a shallow clone that does not reach it, a commit never pushed) no older baseline stands in — bring the commit back (`git fetch`, `git fetch --unshallow`), or a person seals an A-SPEC naming the principle 7 paths as they are and the build inside that window records the tree; when the provenance ledger cannot be read; and when git cannot hash a changed file (one file git cannot open closes the judgement — a new gate source beside it read as unchanged before). A shallow CI clone of a Holmes-Kit checkout whose ledger names a baseline outside its depth is closed by the first of these until it fetches the commit. A directory git cannot open is not listed by `git status`, so a new file inside it is not seen while it stays closed (not closed in this release).
43
+ - Upgrading a Holmes-Kit checkout to this gate takes two builds and a person's window: the baseline row is written by the hook that runs before the build, so the first build is recorded by the earlier gate without playbook digests and the new gate is closed, naming that; the build once more, inside a person's seal window whose A-SPEC names `playbooks/**`, records them. Reconnect the MCP server after each build (it keeps the code it started with).
44
+ - Principle 7 applies where the judged root lies inside the checkout the running gate is built from (A-SPEC-794.111). A Holmes-Kit clone governed by an npm-installed package is therefore not judged by principle 7 — its source is not the running gate's source — and neither is a consumer repository that happens to hold a directory `src/holmes`.
45
+ - The outward judgement closes 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, more than 900 ms, more than eight readings of unknown options, subshell groups nested more than 64 deep) under every flag; the 1-second bound is the judgement's, and the hook's whole time on a 1 MB command adds 1.3–1.8 s in other gates.
46
+ - 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.
47
+ - R1's session item for R8 (`session:<server instance>`) names the MCP server process, which sub-agents and a codex app-server daemon share; R8 itself (re-sealing what this session sealed) stays closed until a per-harness session key is measured (0.42).
48
+ - An approval read from a file the hook never sees (`set -a; . f; …`) is refused by the CLI only where the operator guard finds an agent; forgery resistance by the same user is not claimed.
49
+ - The principle 7 write rule reads the trusted ledger only when an approved A-SPEC names the file; the read is remembered within one process only (a cache other processes could write would forge seals). The hook runs one process per call, so an allowed write to a gate file costs about 1.2–1.5 s in this repository (0.52 s of it the ledger's verification), and a 1 MB Write about 1.13–1.19 s whether refused or allowed (review B's measurement; a refusal with no spec naming the file skips the ledger) (A-SPEC-794.95).
50
+ - The working-tree check (A-SPEC-794.96, 794.97) runs at Stop, at a `git commit` the gate reads and at a build the gate reads (through env, command, time, nohup, npx, npm exec, `sh -c`, eval, cd into the root or under it, the manager's options, package scripts five levels deep, `tsc` by any path): `bun`, a node script calling the compiler API or writing a gate file, make, just, task, concurrently, npm-run-all, `script -q`, a shell function or alias, a one-line `case`, `npm x tsc`, a package's lifecycle scripts, a build in a directory the gate cannot resolve (a variable it does not hold, `$(mktemp -d)`: left to Stop, so a variable pointing at the root is not caught before it acts), and the same user changing dist or the hooks on purpose are not caught before they act (the next Stop judges what they changed). A build in the same command after a step that changes the working tree (git pull, merge, checkout or switch to another tree, rebase, cherry-pick, am, revert, reset --hard/--keep/--merge, stash, restore of the working tree, apply; gh pr checkout, gh repo sync) is refused — run the build as its own command. A new branch at HEAD, a soft or mixed reset, unstaging and an index-only apply are not such steps. The walk reads the values a shell fixes — `$0` in a script, `$(dirname …)`, `$(cd … && pwd)`, `$(pwd)`, `$PWD`, `$OLDPWD`, `cd -`, `$(git rev-parse --show-toplevel)` and variables holding them — and a shell script under the root (by `bash`, `sh`, `.`, `source` or a path whose first line runs a shell); inside such a script a cd it cannot resolve is taken as the root — so a script under the root that builds in a temporary clone or a directory it was handed is also refused while a gate change is unopened. `popd` is not modelled: a build after it is judged where the walk last was, and Stop judges what it changed. `tsc -p X` is a build only where X's outDir (through relative `extends`) is dist and no config in the chain sets noEmit. With nothing changed in the category since the baseline, Stop, a commit and a build take a fast path that finds the baseline in this replica's tracked chain without verifying the row's chain (forging one needs a ledger write the gate refuses). The first baseline's check picks commits by committer date, so a commit made in the same second as the seal, or rewritten by rebase or amend, can fall on the wrong side — the gate prevents accidents; its forgery resistance is not verified (owner decision 11/03). SubagentStop is not wired in any harness: a subagent's change is judged when the parent's turn ends, so the gap is the time between the subagent's change and the parent's Stop (0.42 wires it in the three harnesses). The consecutive-block cap of the Stop hook still applies to this rule.
51
+ - A gate file changed inside a window but never passed through a Stop, a commit or a build before the window closed has no recorded blob, and needs a person's seal again (A-SPEC-794.97). A commit made outside the gate — an owner's terminal commit, a pull, a branch switch — and a person's own build in a terminal record no baseline: those changes stay judged until a person seals an A-SPEC naming the files, or the branch switch or pull is undone (a gate build is refused while they are unopened, so it cannot move the baseline past them; a restore from the baseline would also discard those commits). JavaScript a build emits through `allowJs` from files git ignores is not judged. The harness's runtime paths (`.claude/settings.local.json`, `.claude/worktrees/`, `.claude/scheduled_tasks.lock`) are excluded from the judgement; the repository's `.gitignore` does not list them yet.
52
+ - An approval read from a file the hook never sees (`set -a; . f; holmes-kit autonomy full`) is refused by the CLI, not by the hook (owner decision 11/10: a named limit under "forgery resistance not verified").
53
+ - The window record (`principle7-window-write`) is written when the gate opens the write, before the act: it records what a window opened, not that a write took place.
54
+ - Principle 7's category is named seams plus a census of the gate entry points' import closure (372 modules, 129 of them in the category). Modules outside the closure that use a seal judgement stay outside because no entry point reaches them — admission/core's admission-policy and change-classifier, and two test-support modules; the census turns red if an import makes one reachable (A-SPEC-794.94).
55
+ - A seal recorded under a plain operator name (4,127 rows in this repository, 368 of them the current seal of a gate-category spec) is not counted as a person's: it carries no channel or grant nonce and cannot be told from an approval an agent set in the environment. Only seals from the session form (or a host's approval dialog) count; the owner's terminal path (`holmes-kit approve` grants) opens no gate-file window in 0.41.
56
+ - `init --autonomy` refused for an environment approval names `grant.operator-only`, whose remediation mentions a request id, though init files none; `autonomyWideningGate` ignores its inputs (A-L3 and B-L3 of review round 2, next round). A path holding glob characters is judged by its literal prefix (B-L1).
57
+ - `git checkout .` or `git checkout -- <dir>` reaching the gate category is refused in Holmes-Kit's own repository; a branch switch that rewrites gate files is not judged as a principle 7 write.
58
+ - A request's occurrence count is read from this machine's refusal logs and the tracked queue; two machines that file the same request between syncs can count its occurrences differently, so a decision made on one may leave an occurrence filed on the other open (A-SPEC-794.92, L-1). Queue rows written by this repository's own pre-release build (98c58e31) carry the bound in `covered` without `through`.
59
+
60
+ ### Changed
61
+ - **A full profile's publish flag reads registry writes where a program takes its subcommand (A-SPEC-794.65, 794.66, 794.68, 794.69, 794.70).** With the publish flag off, a registry write is refused when it is a command: `npm publish`, `unpublish`, `deprecate`, `star`, and the writing forms of `dist-tag`, `owner`, `access`, `team`, `token`, `org`, `profile`, `stage` and `trust` (npm's own spellings: `npm pu`, `npm unp`, `npm own`, read from npm's command list), the same through `pnpm`, `yarn` (and `yarn npm`) and `bun`, release tools (semantic-release, np, release-it, `nx release`, `changeset publish`, `lerna publish`), behind wrappers (`sudo`, `env`, `corepack`, `npx`, `pnpm dlx`, `node …/npm-cli.js`, `"$NPM"`), and inside what a command runs: a command or process substitution, `eval`, a shell's `-c` string, `xargs`, `find -exec`, `rg --pre`, `git -c`, an editor variable, a shell's stdin program, a git hook a command writes, and the package scripts a run executes, read from the `package.json` npm would use. A `--dry-run` exempts only the write of the subcommands npm runs dry (publish, unpublish, deprecate, pack, and `stage publish`, whose class extends publish's); the lifecycle scripts a publish runs (prepublishOnly, postpublish, …) are still judged, as npm runs them under --dry-run. Only the programs listed as taking data (echo, printf, cat, grep, rg, jq, git, gh, test runners, file tools) have their arguments read as data: `git commit -m "…publish…"`, `gh pr create --body …`, `grep publish`, a quoted here-document. Wrappers (`timeout`, `caffeinate`, `op run --`, `doppler run`, `dotenv --`, `cross-env`, `aws-vault exec`, `nvm exec`, `nix develop -c`, `launchctl submit`, …) are unwrapped once, the same way for a push and a publish. A command string is judged only where the gate's table says a program runs one (`sh -c`, `doppler --command`, `nodemon --exec`, `concurrently`, `watch`, `watchexec`, `entr -s`, `ssh`, `tmux new`, `parallel`, `git rebase --exec`, `bisect run`, `submodule foreach`, `difftool -x`, `filter-branch` filters, `tar --to-command`, `zip -TT`, `wget --use-askpass`, `gh alias set --shell`). In any other program only standalone words are read: `npm`, `pnpm`, `yarn` or `bun` followed by a write subcommand, or `git` followed by `push`, is judged from there; a quoted string is data, so a prompt to an LLM CLI that mentions `npm publish` passes, and a release tool's name is a publish only where it is the program. `npm run <s> --ignore-scripts` still runs (and is judged for) the named script; only its pre and post scripts are skipped. The script name is read after the run's own options (`npm run --prefix pkg release`); `yarn <script>` and `bun <script>` run a script by its name; the version lifecycle of `yarn version`, the publish lifecycle of `yarn`/`pnpm`/`bun publish` and the install lifecycle of the install family (`npm install`, `ci`, `rebuild`, `link`, bare `yarn`, `pnpm install`, `bun install`) are judged; `pnpm m|multi|recursive` runs in every package; `npm exec --call=`, `mise exec <tool> --` and `mise x --` are read; a release tool's `--help` and `--version` pass; `--dry-run=<v>` is read as npm's option parser reads it (`false`, `null` and a numeric zero, the empty value included, are false). Valued options are skipped before `npm exec -c`/`--call` and before yarn's subcommand; `yarn workspaces run` and `foreach` are read; `publish <folder>` reads that folder's lifecycle; an install into a `--prefix` without a package.json and a global install read no lifecycle; a second publish or push later in an unknown program's arguments is found. A global install with no argument, `.` or a folder runs that folder's install lifecycle and is judged (a global install of registry names is not); an option the gate does not know never takes a following option as its value; yarn, pnpm and bun each have their own built-in commands (frozen from yarn 1.22.22's and pnpm 9.15.9's published bundles and the yarn 4 and bun 1 CLI references), so `yarn deploy` runs a script while `pnpm deploy` is pnpm's own. yarn's built-ins are the names both yarn 1 and yarn 4 own, so a script named after a command only one of them has (`patch`, `check`) is judged. Package scripts are judged for a push too (`postversion: git push --follow-tags`). A variable gives a directory only from a literal, unconditional assignment; any other assignment (`for`, `read`, `+=`, after `&&`) makes it unknown. A lone `&` and `|&` now end a clause for every shell reader of the gate. Measured on the committed fixtures: this repository's last 500 commit messages in seven forms (3,500 commands) give no refusal, and the 312 labelled commands of `fixtures/outward-commands.json` (this project's own session commands, masked, rebuilt by `scripts/outward-corpus.js`) are all judged as labelled.
62
+ - **Known limits of that judgement.** It prevents accidents; it is not a barrier against a determined agent. A script run in a directory the gate cannot resolve (a variable without a literal value, `~`, `-ws`, `pnpm -r`, `--filter`, `yarn workspace`, `lerna run`, `turbo run`) is looked up in the repository's `package.json` files as git lists them (tracked ones, submodules included, and untracked ones that are not ignored; node_modules excluded; outside a git work tree, a walk of at most 8,000 directories that skips hidden directories but `.github`, virtual environments and build output) and refused only when a script of that name publishes or pushes there; an unreadable `package.json` is skipped and named, not a reason to refuse. Closed, so refused with the reason named: a missing `--prefix` directory, a listing past its limit (the limit is named), a command whose structure the gate cannot read (an unclosed quote, nesting past the bound) when it names a registry program or git, a shell that runs the output of a program the gate cannot read when the command names a registry write, and an interpreter's inline or stdin program in which a registry tool is followed by a registry write — that last one is a text search inside another language, a named limit rather than an argv reading. Not read: a script file a command runs (`./release.sh`, `source ./release.sh`), `make release`, a program reached through an alias or a function, and a word assembled at run time (`npm ${V}lish`, `$(printf pub)lish`); quotes are removed as the shell removes them, so `npm "pub""lish"` is read as `npm publish`. The barrier to a registry write is the npm account's two-factor authentication and its token scopes: keep 2FA required for publishing and give agents a token without publish rights.
63
+ - **The outward judgement has a budget (A-SPEC-794.80).** Under a full profile without the publish or push flag, a command too large to judge — more than 400,000 words, more than 2,000 package directories read, or more than 900 ms — is refused with its size named and the advice to split it, instead of being judged slowly. The longest of this project's 14,531 session commands has 153 words. A global install of many folders, pnpm's recursive aliases, a `yarn workspace` chain and repeated unknown option pairs are judged in linear time; a 1 MB command of each of these shapes is judged in 0.2 s or less.
64
+ - **BREAKING: un-seal and retire are their own approval kinds (A-SPEC-794.81).** `spec_unseal` asks for kind `spec-unseal` and retiring a sealed spec for kind `spec-retire`; a grant or a `HOLMES_APPROVAL` scoped to `spec-approve` no longer covers either (an unscoped approval still does). A request filed as `spec-approve` for an un-seal or a retirement before this change stays pending and is not spent by the act, which files a request of its own kind. The session form asks both kinds, and `holmes-kit approve` shows the spec for them. A seal made through the MCP server records the server instance as `session:<instance>`, the last of the `spec-approved` event's inputs.
65
+ - **BREAKING: principle 7 — the gate and approval-processing source is sealed by a person only (A-SPEC-794.88).** The gate category now covers every module that reads or writes a grant, an actor, a seal or a decision judgement (the CLI's approve, autonomy, init and index; the MCP approval, lifecycle, entity, inspection, review and risk handlers; review verdicts; runtime dispatch; the spec transition policy, approval status and blockers), and a census test keeps it so. An A-SPEC whose Files to Touch names such a file, or a REQ or H-SPEC above one, is sealed only by a person: a declared `gate-behavior: tightens|wording` no longer self-seals it (owner decision Q4(b), 11/10, changing the decision of 10/05), a run delegation does not cover it, and under a full profile it goes to the person's form instead of sealing as full-autonomy.
66
+ - **Review repairs of the agent approval policy (A-SPEC-794.89, 794.90).** An autonomy command in a command that uses an out-of-band approval variable is refused as `profile.own-request` in any spelling; an approval read from the environment issues no profile or session autonomy where the operator guard finds an agent (a grant from the session form still does); a directory token at or above a gate root and the built gate (`dist/holmes/`) are in the gate category; R1 walks the whole chain to the REQ with trusted seal events and refuses a root-only scope. A decision records the bound of the occurrences it decided, so a second decision no longer reopens decided ones and a decision after a closed-expired request was filed again is recorded and stands; an integration's un-seal step needs `spec-unseal` before anything is published; `approval_status` advice names the act its request is for.
67
+ - **BREAKING: a sealed spec with an unbroken chain is staged without a person under a full profile (A-SPEC-794.86, R1).** This changes the 11/04 rule "spec staging is a person's form" (owner decision Q4(a), 11/10). Under a full profile with `autonomy.shellStaging` and the new `autonomy.specStaging` on (both on when absent), a staging command in the staging grammar is approved without a person when every staged spec is sealed (the seal holds and a spec-approved event names its digest), every parent is sealed and pinned by `parent_digests`, the file sits where its type and id say (REQ, H-SPEC, A-SPEC, T-SPEC), and its Files to Touch — a T-SPEC's A-SPECs' — names nothing in the gate category. Anything else still goes to the person's form, with the failed R1 condition named. `"autonomy": { "specStaging": "off" }` in `ax.config.json` brings back the form for every spec path.
68
+ - **A request no requester can follow up closes unrun after 24 hours (A-SPEC-794.84).** At session start, an approval request with no requester run or server (a hook's or a CLI's filing), not held by a person, more than 24 hours old (from the first filing of a decision-inbox request, whose repeats are not recorded, and from the last refusal of a refusal-log request), is closed with the queue event `closed-expired` (actor `policy:ttl`). Nothing runs; it is not a decision, so asking again files the request anew. It leaves the inbox and `approve --list`, a late grant of it is refused with the reason, and the session banner says how many were closed. The refusal log itself is not changed. A 0.40 reader ignores the event and keeps such a request pending, as before.
69
+ - **Every path names a spec transition's kind from one table (A-SPEC-794.85).** Entity recovery, the integration audit and renumber now resolve an un-seal by `spec-unseal` and a retirement by `spec-retire`, as the MCP tools do since 794.81 — a `spec-approve` authority no longer recovers an interrupted un-seal or retirement. `approval_status` reports a spec's un-seal and retirement requests as well as its seal request, naming the kind. Upgrading note: a 0.40 `holmes-kit approve --list` does not list `spec-unseal` or `spec-retire` requests; decide them in the session form (`approval_ask`) or with the 0.41 CLI.
70
+ - **An autonomy profile is issued only through its own request (A-SPEC-794.83).** A shell command that sets an out-of-band approval variable itself and runs `holmes-kit autonomy full`, `on` or `delegate` is refused with the code `profile.own-request` and files nothing, so no config-write grant opens it — before, it was filed as an "environment read" whose grant ran the command with the approval the agent wrote. Run the same command without the variable: it files its own request, and the session form now names what that request changes against the profile in force (`push off → on`, a new profile with its flags, or no flag change).
71
+ - **Deeply nested groups are closed too (A-SPEC-794.87).** A command whose subshell groups nest more than 64 deep (1,000 in 794.87; 64 since 794.92 — real commands nest at most 2) is unjudged and refused under a full profile, naming the depth (45,000 groups ran the hook to its 20-second deadline and the refusal blamed an internal error); group bookkeeping is linear; a refusal lists at most 200 findings and counts the rest.
72
+ - **A command too large to judge is refused whatever the flags (A-SPEC-794.82).** The budget's closure is a verdict of its own ("unjudged"), not a publish: a profile with the publish flag on and the push flag off no longer lets a push inside such a command through, and a profile with both flags on refuses it too. A clause of more than 20,000 words is not judged; recursive pnpm aliases and `yarn workspace` chains keep the options between their links in one loop (they ran out of memory at 1 MB); an unknown program before nine unknown option pairs and a registry write is closed again (794.80 let it pass); the clock is read in the global-install loop and per finding, and the clause text of a finding folds only a window.
73
+ - **A person's seal opens a gate file for 12 hours (A-SPEC-794.95).** The write rule below is bound to one seal: a principle 7 file is written only within `autonomy.sealWindowHours` (12; a setting from 1 to 12 shortens it, and a larger one is read as 12 — it was clamped to 1..24, and raising it in `ax.config.json` reopened a window that had closed, A-SPEC-794.113) of a person's seal of an approved A-SPEC whose Files to Touch names it, timed by the ledger; an older seal opens nothing (sealing the spec again is one answer in the session form). Each write a window opens is recorded (`principle7-window-write`: the file, the spec, the seal's time and actor). A person's seal is an allow-list: the session form's channel (or a host's approval dialog) only; autonomous, full-autonomy, delegated, plain-name and grant-spent seals do not count. A seal spent from a grant the person minted with `holmes-kit approve` records `channel:cli-terminal` and the grant's nonce for audit, but is not counted: a grant file can be written by a patch, and the server cannot tell the two apart (proving a grant's origin from the ledger is planned for 0.42). The rule judges where the write lands (a doubled slash, a symbolic link inside the project, a second hard link) and git writing a gate file from its store (`checkout`, `restore`, `apply`, `stash pop|apply`). The category gains the seams of the gate's decisions (spec parser, digest, store and succession, the anchor reader, configuration, the project root, the MCP server and supervisor, and others) and four seal judgements, held by a census of the entry points' imports (A-SPEC-794.94).
74
+ - **Principle 7 judges against the live gate's baseline (A-SPEC-794.97).** The working-tree check below compares with the commit the live gate was built from, recorded in the ledger when the gate allows a build with no unopened gate change — not with HEAD: a gate change committed without a person's window still blocks the turn's end, a commit and a build, whatever command made the commit. A window opens a committed file only for the content (blob) it saw at a Stop, commit or build inside it. The judgement reads the working tree, the index and HEAD, each against the baseline (staging a change and then restoring the working tree no longer hides it), untracked and ignored gate sources, and entries marked assume-unchanged or skip-worktree whose content differs; git is read with replacement objects off, and `git replace`, a refs/replace ref and `git update-index` on a gate file are refused. The refusal warns first that a restore from the baseline also discards other people's commits made after it, then names the ways out: a person's seal; undoing a branch switch or a pull; restoring from HEAD where a window saw HEAD's content; or making the file equal to the baseline (lists stop at 20 files). With no baseline row (a new clone or worktree) HEAD stands in, and the first baseline is recorded only by a build inside person-seal windows that name every gate file the commits since they opened changed — or the ledger holding the baseline row is committed or pulled. A latest baseline row whose commit this repository no longer holds closes the judgement and the text says so; it fell back to the latest baseline held, and moving a ref back and collecting the newer commit then made an older gate the baseline (A-SPEC-794.113). A window records the content it saw whether or not another file is unopened, and with nothing changed since a baseline at HEAD, Stop, a commit and a build skip the ledger's trusted read. A git apply or `patch` into `.ax/ledger` or `.ax/approvals`, and a shell write into a gate file without a window, are refused; a package script that reaches the build is a build.
75
+ - **The working tree is principle 7's seam (A-SPEC-794.96).** In Holmes-Kit's own repository, a change to a gate file (staged, unstaged or untracked; the gate's JSON tables and, there, `.claude/` and `.mcp.json` included) that no open person-seal window names keeps the agent's turn from ending, refuses `git commit` (its staged changes; with `-a`, its tracked ones) and refuses a build — with two ways out: a person seals an A-SPEC naming the file, or the file is restored from HEAD. The git-command pre-judgement is narrowed to fast feedback (a checkout or restore from another tree, an `apply` that writes the working tree, `stash pop|apply`); restoring from HEAD or the index, `--check`/`--stat`, a command run with `-C` or after `cd`, and `git` as an argument are left to the working-tree check. A window also opens the test files an approved T-SPEC of the open A-SPEC names. A 0.41 decision row writes `covered` as the absolute bound, equal to `through`, so a 0.40.1 reader no longer reopens decided occurrences.
76
+ - **Round-2 review repairs (A-SPEC-794.91, 794.92, 794.95).** A command substitution inside arithmetic (`$(( $(…) ))`, `(( x = $(…) ))`, `for (( … ))`) is read, and `$((cmd) )` is read as the subshell it is; a 0.40 or 0.40.1 decision row bounds no more occurrences than were filed by its time (on a 0.40.1 queue a request filed again after such rows stayed hidden); an integration retirement is judged by the spec id, and deleting a sealed spec's document is a retirement; the queue lock's re-entry is per root and a stale lock is reclaimed by renaming it; a sweep appends its closures in one write.
77
+ - **Principle 7 binds the write too (A-SPEC-794.91 N2).** Holmes-Kit's own gate and approval-processing source (the principle 7 paths under `src/`, and `bin/holmes-*`) has no tenure any more: an anchor already in the file does not open it. An Edit or Write needs an approved A-SPEC whose current seal a person made (the ledger's `spec-approved` actor is neither autonomous, full-autonomy, delegated nor a tool) and whose Files to Touch names the file; an environment code-write approval does not open it. `dist/holmes/` is refused to Edit and Write — the build writes it. This applies to paths only Holmes-Kit's own repository has. A scope that names a root-level configuration file among directory paths (any root file but a Markdown document; AGENTS.md, CLAUDE.md and GEMINI.md count as configuration) no longer self-seals and is not staged by R1 — measured over this repository's A-SPECs, 26 of the 221 scopes that mix a root file would have gone to a person, not the 195 that name only CHANGELOG.md or README.md. R1 stages a REQ or an H-SPEC only when every A-SPEC beneath it would be staged (one with none beneath goes to a person). `dist`, `dist/` and `dist/holmes` are gate tokens both ways. `profile.own-request` reads the command by words per clause: a subcommand the gate cannot read statically (`autonomy $S`, `${A}nomy full`, `autonomy $'\x66ull'`) is refused, and an `on` in another clause (`autonomy status; git commit -m "turn it on"`) no longer is.
78
+ - **Review repairs before release (A-SPEC-794.91 N1, 794.92).** One operator guard decides every autonomy widening: an environment approval issues no session autonomy, full profile, run delegation or `init --autonomy` where the guard finds an agent (a grant from the session form still does). A here-document holding a group nested too deep to read no longer hides the substitutions after it: the command is unjudged and refused under a full profile; group nesting is bounded at 64 (real commands nest at most 2 deep) and the group stack is no longer copied per clause. A decision row keeps 0.40's meaning of `covered` (the occurrences it decided) and records the occurrence bound in a new field `through`, so a 0.40 and a 0.41 CLI deciding on one queue no longer reopen each other's decided occurrences. An entity integration that retires a sealed spec needs a `spec-retire` authority (a `spec-unseal` one no longer completes it) and records `spec-retired`, as `spec_retire` does. The expiry sweep reads and closes under a queue lock that a person's decision or hold also takes, so a hold written during a sweep is not closed over; a lock not taken in 2 seconds closes nothing, and a lock older than 30 seconds is broken.
79
+
80
+ ### Fixed
81
+ - **A full `test_run` gives its tests the tree it runs in as `CLAUDE_PROJECT_DIR` (A-SPEC-794.119; present since 0.40.1).** A full run executes in a HEAD worktree, but its test children kept the MCP server's `CLAUDE_PROJECT_DIR`, which names the live checkout. A test that read it judged the live working tree, not the HEAD snapshot the evidence names. So did a test that started a process following it, such as the Holmes-Kit stdio server, whose spec store follows that variable. Measured 2026-11-12/13: Holmes-Kit's own surface-conformance suite failed only in MCP-run full runs, and only while the checkout held spec files HEAD did not. Where the server's environment carries the variable, the test children that `test_run`'s runners start for its units (jest, pytest, go and the others) now get the real path of the tree the run executes in: the HEAD worktree of a full run, the work tree of a scoped one. A server that does not carry the variable passes none, as before. Not reached (named limits): the project's `testRun.prepare` command, which runs in the worktree before the units with the server's variable unchanged; `test_run --mutate`, whose mutation runs keep the variable as the server carries it; and a test that reads the path from a file, or from a process it did not start.
82
+ - **Session usage is counted once per response (A-SPEC-564.5).** Claude Code writes one response as several transcript records, each carrying the same usage, and the Stop hook's session summary added every record — about 2.7 times the real tokens and turns on this repository's largest transcripts. It now counts one usage per distinct message id (the line with the largest output; ties go to the later line). Lines without an id still count on their own. `session-context` records written from 0.41 on are therefore about 1/2.7 of earlier ones; do not compare `tokenTotalsExact` across that boundary. Records already in the ledger are not rewritten.
83
+ - **The usage record names its counting rule (A-SPEC-564.7).** New `session-context` usage records carry `count: "per-message-id"`. The maintainer's field report adds only marked records into `tokenTotalsExact` and the `byModel` usage sums, and reports unmarked (older, per-record) ones as `legacyRecordCount`, so the two counts are never added together.
84
+ - **A refreshed recovery skill is no longer called changed (A-SPEC-794.100).** Under a full profile, the autonomous shell approval refused staging, saying the installed recovery skills were "product-installed … (changed)". In the same workspace, `doctor --target` called those skills current. The approval compared each skill with the digest the last `init` recorded in `.ax/state/install-manifest.json`, and `holmes-kit skills refresh` does not rewrite that record. Doctor compared each skill with the running build's own playbook. When the approval and doctor run from the same install, they now ask that one question through doctor's `playbookSkillStates` (A-SPEC-794.106: for a skill doctor calls current, drifted or missing). A skill that differs from the playbook is refused as `drifted`. The refusal names the install it was judged against (version and path) and the route: run `holmes-kit skills refresh --target <root>` with that install, then a person commits the file. A skill doctor calls foreign (user-owned, no holmes-kit marker), aliased, unresolvable or source-unreadable, and a linked skill file or directory, keeps the digest judgement it had before. All other manifest entries, the manifest-tampered and manifest-invalid checks and the staged and in-index checks are unchanged.
85
+ - **The reference cannot be chosen by the judged workspace (A-SPEC-794.106, 794.107, 794.110; review A critical three times).** In a checkout the package root is the workspace, so each reference the approval read was one the workspace could move: the working tree's playbooks (edit the playbook with the skill), HEAD (an agent commit of `playbooks/`, even with `--no-verify`), then a baseline commit behind a binding that read the target's git state (remove `package.json` from the index, or point `core.worktree` elsewhere, and the binding read "deployed"; move a ref back and garbage-collect the newer baseline, and an older commit became the reference).
86
+ - The binding reads one fact: the real path of the running package. It is deployed when that path has a `node_modules` segment, and judged against the package's own playbooks. No git command, index, HEAD, `core.worktree`, environment variable or file of the target decides it.
87
+ - Any other package is judged against the sha256 of each `PLAYBOOK.md` that the gate wrote into its ledger — in the `principle7-baseline` row, in this writer's own chain — when it last allowed a build. No git object is read. With no such row, a latest row without digests, or a chain that does not verify, no skill is shown current and the refusal names which of these it is; an older row never stands in.
88
+ - Doctor, init and the approval read that reference through one function, so they agree when they run from the same install; `doctor` prints a `recovery skills reference` row naming the recorded build it judged against, or why there is none (and, run from another install than the one the sessions load, that the gate judges against that one).
89
+ - `playbooks/` is a principle 7 write, commit and Stop path in Holmes-Kit's own repository. `src/holmes/project/playbook-skill-states.ts`, `playbook-reference.ts`, `running-package.ts`, `installer-markers.ts` and `bounded-io.ts` are category paths.
90
+ - The refusal names the route for the state found. A skill that differs from the reference playbook: `node <install>/bin/holmes-kit.js skills refresh --target <root>`, then a person commits the file. A playbook that is not the recorded one: if the change is wanted, a person seals an A-SPEC naming the playbook in a session in that checkout, a build run in a governed agent session inside that window records it (only a build the hook judged records; one run outside such a session does not), then refresh and commit the refreshed `SKILL.md` — in Holmes-Kit's own repository a `SKILL.md` under `.claude/skills` is itself a principle 7 path, so the sealed spec names it as well as the playbook; if the change is not wanted, restore the playbook. With no recorded build at all the reason is given once, with the skills it closes: a build inside a person's seal window, in a governed agent session, makes the baseline.
91
+ - **Principle 7 no longer turns off when `src/holmes` is moved (A-SPEC-794.111, 794.112).** Principle 7 applied "where a directory `src/holmes` exists under the root", and the hook allows `mv src/holmes src/h2`, `git mv` and replacing the directory by a link (measured 2026-11-12). While the directory was away, the write judgement no longer treated `.claude/`, `tsconfig*.json` and `playbooks/` as principle 7 paths, and the commit judgement and Stop were skipped. The predicate now reads the running package's real path — whether the judged root lies inside the checkout the running gate is built from — and holds no switch: the suites replace that module in jest's registry only, and a census test refuses a setter or an environment read on the predicate's path.
92
+ - **A test run no longer rebuilds the live gate (A-SPEC-794.109).** In Holmes-Kit's own checkout, the seven cpg inline-parser suites ran `tsc` in the repository whenever `dist` was older than the source. A plain `jest` run therefore replaced `dist` — the live gate of a development binding — with the working tree's code, without the hook's build gate, a build id or a principle 7 baseline (measured 2026-11-12: all 449 files under `dist/holmes` rewritten). The suites now build into a directory under the system's temporary directory, one per source state, and neither read nor write the repository's `dist`. A ratchet test refuses a test or test-support file that runs the compiler without `--outDir`. The build's parent is a directory of the user's own (mode 0700, the user id in its name), its lock names the process holding it so a holder that died is not waited on, and at most four builds are kept (A-SPEC-794.110). Consumers are not affected: the helper never shipped.
93
+ - **init records only the skills it owns (A-SPEC-794.107).** A skill init left untouched ("Left your own … untouched") is no longer written to the install record, and re-running init drops an earlier record of it. A recorded skill without the holmes-kit marker keeps the digest judgement, because a product skill stripped of its marker is changed bytes. When it changed, the refusal first warns that on a path holmes-kit installs (`holmes-*`) a skill stripped of its marker is a changed product file, then names the way out for your own skill: `node <install>/bin/holmes-kit.js init --force --target <root>`, which needs the operator's approval and rewrites the wiring with its defaults (A-SPEC-794.110).
94
+ - **Known limit, not a basis for judgement:** `tokenTotalsExact` is the value at a session's first Stop, not the whole session (the Stop hook writes usage once per session). A resumed session is counted under two session keys. A transcript larger than about 512 MB cannot be read as one string and is skipped without a record. The repair is planned after the 0.41 goals.
95
+
10
96
  ## [0.40.1] - 2026-11-09
11
97
 
12
98
  ### Upgrading
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
- **542/542** source files (100%) trace to an approved spec · **1210/1307** approved A-SPECs (92.5%) are anchored from code.
15
- Measured at `582e92298192` (specs `sha256:3fce6501f474`) — reproduce with `holmes-kit attest --exclude docs/goals/probes/`.
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/`.
16
16
  <!-- holmes-kit:attest:end -->
17
17
 
18
18
  ### 0.40.x push evidence: the supported surface
@@ -20,7 +20,7 @@ Measured at `582e92298192` (specs `sha256:3fce6501f474`) — reproduce with `hol
20
20
  The pre-push gate accepts a full `test_run` as evidence only where holmes can check the run afterwards without changing your runner configuration. Outside that surface the push is refused as `environment`, with one message: "이 구성은 0.40.x가 증빙하지 않습니다 — 0.41 / 오너 결정". General support is planned for 0.41.
21
21
 
22
22
  **A full run tests the commit, not your work tree.**
23
- - It checks HEAD out as a temporary git worktree **outside the repository**, in `<os tmp>/holmes-headwt-<user>/<repository key>/<id>/`, made with no git hooks and no write to your git configuration. It links your gitignored `node_modules`, runs `ax.config.json` `testRun.prepare` there if you declare one (for example `["npm", "run", "build"]`; nothing is guessed, and a package-manager install is refused because `node_modules` is your work tree's), runs the suite within the run's time budget, and removes the worktree.
23
+ - It checks HEAD out as a temporary git worktree **outside the repository**, in `<os tmp>/holmes-headwt-<user>/<repository key>/<id>/`, made with no git hooks and no write to your git configuration. It links your gitignored `node_modules`, runs `ax.config.json` `testRun.prepare` there if you declare one (for example `["npm", "run", "build"]`; nothing is guessed, and a package-manager install is refused because `node_modules` is your work tree's; `[]` or `null` declares none, and any other malformed value ends the run with the reason *(0.41.1)*), runs the suite within the run's time budget, and removes the worktree. The prepare and the tests are told that worktree as `CLAUDE_PROJECT_DIR` *(0.41.1)*.
24
24
  - holmes removes only a worktree git lists at that exact path, through `git worktree remove`; it never deletes a directory itself and never runs `git worktree prune`. A leftover of a run whose process is gone is removed by the next run.
25
25
  - Untracked, ignored, modified, assume-unchanged and skip-worktree files never reach the run, so a red commit cannot pass on a green work tree. Nothing is written inside your repository, and nothing has to be added to `.gitignore`.
26
26
  - **The run must read only HEAD, judged by what it loaded.**
@@ -85,7 +85,7 @@ The pre-push gate accepts a full `test_run` as evidence only where holmes can ch
85
85
  - 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
86
  - 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
87
  - 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. 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.
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.
89
89
  - **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
90
  - **Revoking.** `--revoke` ends the profile.
91
91
  - **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,6 +96,12 @@ The pre-push gate accepts a full `test_run` as evidence only where holmes can ch
96
96
  - **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
97
  - **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
98
  - **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.
99
+ - **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).
101
+ - **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
+ - **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
+ - **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.
104
+ - **A request no one can follow up closes by itself** *(new in 0.41)*: a request filed by a hook or the CLI (no requester run or server), not held, and not decided within 24 hours is closed unrun at the next session start (`closed-expired`, actor `policy:ttl`) — counted from the first filing of a decision-inbox request (its repeats are not recorded) and from the last refusal of a refusal-log request. Nothing runs, it is not a denial, and asking again files it anew; a person's decision after that is recorded and stands. The session banner counts the closures.
99
105
  - **A refusal you cannot see in the inbox is still answerable from its own hint** *(new in 0.35.18)*: six repairs measured in a Codex X1 runtime session and a field report. Every refusal line written to the refusal log ends with `run: holmes-kit approve --grant <id> --target <root>` carrying the actual id, the inbox (`approve --list` / `--watch`) prints a footer counting requests outside the inbox, and the `--refusals` closing line spells the same command (the positional `approve <id>` the first repair wrote is refused by the CLI, so it was measured and rewritten). An autonomy refusal on a parent spec names the child rule that forces the human decision (`upstream-has-human-aspec: <id> — <rule>`). A runtime deadline refusal ends with the per-phase millisecond split, and the Stop hook prints how much of its 18 s budget it used once it passes half. `runtime-binding status` separates `drift` (operator-config / stale-workspace) from `conflicts` and reports whether the router is intact. The `--autonomy` usage, the `init` refusal and the interactive prompt now say the same thing.
100
106
  - **An agent is told what to do after an approval, and a patch is judged the way the tool applies it** *(new in 0.35.17)*: five repairs measured on a Codex worker in a SWE-bench comparison. `approval_status` now carries `request { id, state, question?, reason?, ts? }` (pending / held / granted / consumed / denied / revoked, read from the approval queue, with the operator's LATEST hold question) and one `nextAction` sentence — a sealed spec says "stop polling", a held request relays the question; the pending-approval hint ends with an `Agent:` line beside the unchanged operator lines. `test_run` reports `anchorDiagnostics` for an `@implements` list joined by `;`, `|`, `&`, `/` or `and` (the comma grammar does not read them; attribution is unchanged, the omission is named). A Codex `apply_patch` update is applied chunk by chunk from the previous chunk's position, as the tool does, so a context line that recurs earlier in the file no longer makes it "unreadable", and a patch that does not apply is refused by a sentence naming the file and the chunk. A quoted or escaped glob (`rg ".*"`) is no longer read as a spelling of the `.ax` store (an unquoted `.*` still is). The background refresh child records `failure { stage, reason }` on its freshness receipt instead of failing silently.
101
107
  - **The analysis names the unchanged files a change has broken** *(new in 0.35.16)*: with `changedFiles` given, `maintenance_analyze` reports under `impacts.removedNameUsers` every unchanged file that imports a changed file and still uses a top-level name that file no longer defines (removed or renamed), and the files still importing a deleted TypeScript/JavaScript file. Deterministic and read-only; TypeScript/JavaScript and Python. Measured on public repositories: every file named was one the commit did change (22 of 22, 21 of 21). It fires rarely — 2–7% of the files an incomplete change set was missing. Member names and changed signatures are not read.
@@ -407,6 +413,8 @@ flowchart LR
407
413
  | `holmes-kit runtime-binding setup --workspace <root> --package <built-package> --release-package <release-install> --dry-run` | Preview explicit development/release routing; omit `--dry-run` only after reviewing the plan and satisfying its approval request |
408
414
  | `holmes-kit runtime-binding status --workspace <root>` | Inspect selected package, build, spec store and wiring conflicts, and whether this selection's PreToolUse gate was observed running (`activation`); an observation is evidence the hook ran, not a guarantee every call is judged |
409
415
  | `holmes-kit doctor --target <root> --registry <bindings.json>` | Diagnose the same operator registry used by custom routing installations |
416
+ | `holmes-kit ledger witness` | Vouch for this repository's provenance chain as it is — a person decides it in the session's approval form, which leads with the witness's verdict, compares the chain with the pushed one as the local ref names it, and lists the rows to recognise from row 0 *(new in 0.41; form order 0.41.1)* |
417
+ | `holmes-kit ledger rechain [--dry-run]` | Re-chain forked ledger files against the committed mainline; the rewrite applies only to a plan a person approved (`--dry-run` is free) |
410
418
  | `holmes-kit autonomy status` | Show the current autonomous-approval posture (project default + session envelope) |
411
419
  | `holmes-kit autonomy on --for 2h` | Self-drive low-risk specs for this session only (expiring; needs a TTY or `HOLMES_APPROVAL`) |
412
420
  | `holmes-kit autonomy full --scope <dir>` | Full autonomy inside `<dir>` (decided once in the session approval form): a judgment there ends at once, apart from spec staging; `--allow-push`, `--allow-publish` (without them the gate refuses the pushes and publishes it reads), `--no-architecture`; `--revoke` ends it |
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- b33d8589-mw8gsg6z
1
+ 35d54f07-mwfu2hez
@@ -34,9 +34,10 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.renderDecisionContext = renderDecisionContext;
37
- // @implements A-SPEC-262.1
37
+ // @implements A-SPEC-794.90, A-SPEC-794.81, A-SPEC-262.1
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
+ const approval_queue_1 = require("../governance/approval-queue");
40
41
  const screen_safe_1 = require("./screen-safe");
41
42
  /**
42
43
  * What is actually being approved.
@@ -160,8 +161,8 @@ function findingContext(root, id) {
160
161
  }
161
162
  function renderDecisionContext(root, entry) {
162
163
  try {
163
- if (entry.kind === 'spec-approve')
164
- return specContext(root, entry.target);
164
+ if ((0, approval_queue_1.isSpecTransitionKind)(entry.kind))
165
+ return specContext(root, entry.target); // A-SPEC-794.90 — the one table
165
166
  if (entry.kind === 'review-resolve')
166
167
  return findingContext(root, entry.target);
167
168
  // shell / config-write / anything else: the queue's target IS the subject.
@@ -55,7 +55,7 @@ exports.subjectDigest = subjectDigest;
55
55
  exports.renderRefusals = renderRefusals;
56
56
  exports.renderNonTtyHint = renderNonTtyHint;
57
57
  exports.runInteractive = runInteractive;
58
- // @implements A-SPEC-794.55, A-SPEC-246, A-SPEC-794.30, A-SPEC-794.31, A-SPEC-794.32, A-SPEC-794.33, A-SPEC-794.34, A-SPEC-794.35, A-SPEC-794.37, A-SPEC-794.41,A-SPEC-626,A-SPEC-532.5, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.12, A-SPEC-779.2, A-SPEC-792.2, A-SPEC-245.9, A-SPEC-245.15, A-SPEC-245.17
58
+ // @implements A-SPEC-794.96, A-SPEC-794.92, A-SPEC-794.90, A-SPEC-794.84, A-SPEC-794.55, A-SPEC-246, A-SPEC-794.30, A-SPEC-794.31, A-SPEC-794.32, A-SPEC-794.33, A-SPEC-794.34, A-SPEC-794.35, A-SPEC-794.37, A-SPEC-794.41,A-SPEC-626,A-SPEC-532.5, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.12, A-SPEC-779.2, A-SPEC-792.2, A-SPEC-245.9, A-SPEC-245.15, A-SPEC-245.17
59
59
  // @implements A-SPEC-549.4 — renderPending and renderNonTtyHint in this file are the English CLI
60
60
  // surface the Hangul-absence guard reads.
61
61
  const execution_context_1 = require("../project/execution-context");
@@ -112,10 +112,13 @@ const findPending = (root, id) => {
112
112
  // @implements A-SPEC-690 — the reopening rule and the queue-shape conversion live in ONE place
113
113
  // now (approval-queue). They used to be spelled out here as well, and a second copy of a
114
114
  // judgement is how two paths quietly disagree about whether a request is open.
115
- const { readRefusals, openOccurrences, asPendingRequest } = require('../governance/approval-queue');
116
- const mine = openOccurrences(readRefusals(root).filter((r) => r.id === id), state.decisions[id]);
115
+ const { readRefusals, openOccurrences, asPendingRequest, closingOf } = require('../governance/approval-queue');
116
+ // A-SPEC-794.84 — past the decision or the closure (closed-expired), whichever ended it last
117
+ const all = readRefusals(root).filter((r) => r.id === id);
118
+ const mine = openOccurrences(all, closingOf(state, id));
119
+ // A-SPEC-794.90 — the decision records the occurrence bound (all occurrences now), not the open count
117
120
  if (mine.length > 0)
118
- return { entry: asPendingRequest(id, mine), state };
121
+ return { entry: asPendingRequest(id, mine, all.length), state };
119
122
  }
120
123
  catch { /* a broken refusal log must not break the decision surface */ }
121
124
  return { entry: undefined, state };
@@ -138,7 +141,13 @@ const isWritablePath = (file) => {
138
141
  return true;
139
142
  } // absent is fine; it gets created
140
143
  };
144
+ // A-SPEC-794.92 (L-2) — a person's decision or hold is written under the queue lock, so the expiry sweep cannot read
145
+ // before it and close after it; a lock not taken in time does not stop the person's write
141
146
  const appendEvent = (root, event) => {
147
+ const written = (0, approval_queue_1.withQueueLock)(root, () => appendEventUnlocked(root, event), null);
148
+ return written === null ? appendEventUnlocked(root, event) : written;
149
+ };
150
+ const appendEventUnlocked = (root, event) => {
142
151
  try {
143
152
  const execution = (0, execution_context_1.executionForRoot)((0, root_1.resolveProjectRoot)(root).root);
144
153
  const file = path.join(root, approval_queue_1.QUEUE_RELPATH);
@@ -209,7 +218,7 @@ function grantRequest(root, id, opts) {
209
218
  if (typeof ttl !== 'number' || !Number.isFinite(ttl) || !Number.isInteger(ttl) || ttl <= 0 || ttl > MAX_TTL_MINUTES) {
210
219
  return { ok: false, reason: `TTL must be an integer number of minutes in 1..${MAX_TTL_MINUTES} — received: ${(0, screen_safe_1.rowField)(String(ttl), 40)}` };
211
220
  }
212
- const { entry } = findPending(root, id);
221
+ const { entry, state: found } = findPending(root, id);
213
222
  // @implements A-SPEC-532.5 — owner decision 2026-10-05: a grant bound to the content the operator read does not
214
223
  // expire by time; it ends when it is used, revoked, or the content changes (the subject no longer matches). Measured
215
224
  // 2026-10-04: five seal grants expired unused after 30 minutes. An explicit --ttl still bounds it; a request without
@@ -218,8 +227,9 @@ function grantRequest(root, id, opts) {
218
227
  // different id: the clock only re-asked the person about the identical act (field report 2026-10-22).
219
228
  const untilUsed = opts.ttlMinutes === undefined
220
229
  && ((typeof entry?.subject === 'string' && entry.subject !== '') || entry?.kind === 'shell');
230
+ // A-SPEC-794.84 — a late grant of a request closed unrun is refused and says why
221
231
  if (!entry)
222
- return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)} — check with ${(0, npx_bin_1.holmesKitCommand)(root)} approve --list` };
232
+ return { ok: false, reason: (0, approval_queue_1.closedExpiredNote)(found, id) ?? `no pending request ${(0, screen_safe_1.rowField)(id, 40)} — check with ${(0, npx_bin_1.holmesKitCommand)(root)} approve --list` };
223
233
  if (!recordIsSelfConsistent(entry))
224
234
  return { ok: false, reason: TAMPERED };
225
235
  // A "does this match what the operator saw" parameter was written here too and then removed: the
@@ -288,7 +298,7 @@ function grantRequest(root, id, opts) {
288
298
  // class round-6 closed in findingContext, three files over.
289
299
  return { ok: false, reason: `cannot write the grant file:\n ${(0, screen_safe_1.rowField)(e instanceof Error ? e.message : String(e), 76)}` };
290
300
  }
291
- if (!appendEvent(root, { event: 'granted', id, actor: opts.actor, expires, covered: entry.count, ...binding })) {
301
+ if (!appendEvent(root, { event: 'granted', id, actor: opts.actor, expires, covered: entry.through ?? entry.count, ...(entry.through !== undefined ? { through: entry.through } : {}), ...binding })) {
292
302
  try {
293
303
  fs.rmSync(tmp, { force: true });
294
304
  }
@@ -462,7 +472,7 @@ const closable = (root, id) => {
462
472
  function denyRequest(root, id, reason, actor) {
463
473
  const entry = closable(root, id);
464
474
  if (!entry)
465
- return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)}` };
475
+ return { ok: false, reason: (0, approval_queue_1.closedExpiredNote)((0, approval_queue_1.readQueue)(root, { includeAllKinds: true }), id) ?? `no pending request ${(0, screen_safe_1.rowField)(id, 40)}` }; // A-SPEC-794.84
466
476
  // @implements A-SPEC-262.1 — round-4: the derivation gate guarded grant only, so a tampered record
467
477
  // let the operator "deny" one subject while the denial was keyed to another id entirely.
468
478
  if (!recordIsSelfConsistent(entry))
@@ -470,7 +480,7 @@ function denyRequest(root, id, reason, actor) {
470
480
  // The event IS the decision here (there is no second artefact), so a failed append is a failed
471
481
  // decision — round-5: ✓ and exit 0 were printed over a read-only queue while nothing was recorded,
472
482
  // and the agent, never seeing the denial, retried forever.
473
- if (!appendEvent(root, { event: 'denied', id, reason, actor, covered: entry.count })) {
483
+ if (!appendEvent(root, { event: 'denied', id, reason, actor, covered: entry.through ?? entry.count, ...(entry.through !== undefined ? { through: entry.through } : {}) })) {
474
484
  return { ok: false, reason: 'could not write the denial record (queue event) — check write permission on .ax/approvals. Nothing was recorded' };
475
485
  }
476
486
  return { ok: true };
@@ -486,7 +496,7 @@ function withdrawRequest(root, id, reason, ctx) {
486
496
  return { ok: false, reason: 'a withdrawal needs --reason — it is what the operator reads in place of a decision' };
487
497
  const entry = closable(root, id);
488
498
  if (!entry)
489
- return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)}` };
499
+ return { ok: false, reason: (0, approval_queue_1.closedExpiredNote)((0, approval_queue_1.readQueue)(root, { includeAllKinds: true }), id) ?? `no pending request ${(0, screen_safe_1.rowField)(id, 40)}` }; // A-SPEC-794.84
490
500
  if (!recordIsSelfConsistent(entry))
491
501
  return { ok: false, reason: TAMPERED };
492
502
  // @implements A-SPEC-779.7 — the MCP server instance that filed a request withdraws it: an interactive session's
@@ -495,7 +505,7 @@ function withdrawRequest(root, id, reason, ctx) {
495
505
  if (ctx.server !== entry.requesterServer) {
496
506
  return { ok: false, reason: `only the session whose MCP server filed ${(0, screen_safe_1.rowField)(id, 40)} withdraws it: filed by server ${(0, screen_safe_1.rowField)(entry.requesterServer, 60)}; this is ${ctx.server ? `server ${(0, screen_safe_1.rowField)(ctx.server, 60)}` : 'not that server'} — if that session is gone, the operator denies it` }; // A-SPEC-794.41 (D8)
497
507
  }
498
- if (!appendEvent(root, { event: 'withdrawn', id, reason: reason.trim(), server: ctx.server, covered: entry.count })) {
508
+ if (!appendEvent(root, { event: 'withdrawn', id, reason: reason.trim(), server: ctx.server, covered: entry.through ?? entry.count, ...(entry.through !== undefined ? { through: entry.through } : {}) })) {
499
509
  return { ok: false, reason: 'could not write the withdrawal record (queue event) — check write permission on .ax/approvals. Nothing was recorded' };
500
510
  }
501
511
  return { ok: true };
@@ -508,7 +518,7 @@ function withdrawRequest(root, id, reason, ctx) {
508
518
  if (here !== entry.requesterRun) {
509
519
  return { ok: false, reason: `only the run that filed ${(0, screen_safe_1.rowField)(id, 40)} withdraws it: filed by run ${(0, screen_safe_1.rowField)(entry.requesterRun, 60)}; this is ${here ? `run ${(0, screen_safe_1.rowField)(here, 60)}` : 'not a run'}` };
510
520
  }
511
- if (!appendEvent(root, { event: 'withdrawn', id, reason: reason.trim(), run: here, covered: entry.count })) {
521
+ if (!appendEvent(root, { event: 'withdrawn', id, reason: reason.trim(), run: here, covered: entry.through ?? entry.count, ...(entry.through !== undefined ? { through: entry.through } : {}) })) {
512
522
  return { ok: false, reason: 'could not write the withdrawal record (queue event) — check write permission on .ax/approvals. Nothing was recorded' };
513
523
  }
514
524
  return { ok: true };
@@ -69,6 +69,26 @@ export declare function autonomyGrantGate(input: {
69
69
  now: string;
70
70
  envApproval?: Approval;
71
71
  }, deps: AutonomyGrantDeps): AutonomyGrantVerdict;
72
+ /**
73
+ * @implements A-SPEC-794.83 — what a profile request changes, in words, against the profile that covers the scope now:
74
+ * a new profile with its flags, each flag that turns on or off, or no flag change. The form shows it.
75
+ */
76
+ export declare function fullProfileChange(current: FullProfileFlags | null, next: FullProfileFlags): string;
77
+ /**
78
+ * @implements A-SPEC-794.91 — one guard for every autonomy widening (session autonomy, a full profile, a run delegation,
79
+ * init --autonomy): an environment approval counts only where the operator guard finds no agent. Review A of 98c58e31
80
+ * measured a 7-day delegation created from an agent ancestor with an environment approval; delegate and init skipped
81
+ * the guard. A grant from the session form does not come through here.
82
+ */
83
+ export declare function autonomyWideningGate(input: {
84
+ kind: string;
85
+ envApproval?: unknown;
86
+ }, deps: {
87
+ guard: () => string | null;
88
+ }): {
89
+ proceed: boolean;
90
+ why?: string;
91
+ };
72
92
  /** @implements A-SPEC-792.3 — the flags are the request's subject, so a grant for one set cannot issue another. */
73
93
  export declare function fullProfileSubject(flags: FullProfileFlags): string;
74
94
  /**
@@ -82,6 +102,7 @@ export declare function fullProfileGate(input: {
82
102
  flags: FullProfileFlags;
83
103
  now: string;
84
104
  envApproval?: Approval;
105
+ current?: FullProfileFlags | null;
85
106
  }, deps: AutonomyGrantDeps): AutonomyGrantVerdict;
86
107
  /** @implements A-SPEC-792.3 — write or revoke an entry once the gate (issue) has passed; revoking needs no proof. */
87
108
  export declare function runAutonomyFull(home: string, args: {
@@ -35,12 +35,14 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.parseForMinutes = parseForMinutes;
37
37
  exports.autonomyGrantGate = autonomyGrantGate;
38
+ exports.fullProfileChange = fullProfileChange;
39
+ exports.autonomyWideningGate = autonomyWideningGate;
38
40
  exports.fullProfileSubject = fullProfileSubject;
39
41
  exports.fullProfileGate = fullProfileGate;
40
42
  exports.runAutonomyFull = runAutonomyFull;
41
43
  exports.autonomyPostureLine = autonomyPostureLine;
42
44
  exports.runAutonomy = runAutonomy;
43
- // @implements A-SPEC-794.58, A-SPEC-794.57, A-SPEC-794.55, A-SPEC-553.1, A-SPEC-553.2, A-SPEC-771, A-SPEC-718.7, A-SPEC-792.3, A-SPEC-792.7, A-SPEC-245.9, A-SPEC-794.35
45
+ // @implements A-SPEC-794.91, A-SPEC-794.89, A-SPEC-794.83, A-SPEC-794.58, A-SPEC-794.57, A-SPEC-794.55, A-SPEC-553.1, A-SPEC-553.2, A-SPEC-771, A-SPEC-718.7, A-SPEC-792.3, A-SPEC-792.7, A-SPEC-245.9, A-SPEC-794.35
44
46
  const fs = __importStar(require("node:fs"));
45
47
  const full_autonomy_1 = require("../governance/full-autonomy");
46
48
  const autonomy_1 = require("../governance/autonomy");
@@ -106,7 +108,9 @@ function revokeDelegationQuietly(root, io, rationale) {
106
108
  function autonomyGrantGate(input, deps) {
107
109
  const action = { kind: 'autonomy-grant', target: input.root, subject: `for=${input.mins}m` };
108
110
  const covering = deps.resolve(input.askRoot, input.envApproval, action, input.now);
109
- if (covering !== undefined) {
111
+ // @implements A-SPEC-794.89, A-SPEC-794.91 — an environment approval counts only where the operator guard finds no
112
+ // agent (an agent can read one from a file the hook never sees); a grant from the session form counts as before
113
+ if (covering !== undefined && (covering.source === 'grant' || autonomyWideningGate({ kind: action.kind, envApproval: covering.approval }, deps).proceed)) {
110
114
  const nonce = covering.approval.nonce;
111
115
  return { proceed: true, approval: covering.approval, ...(covering.source === 'grant' && typeof nonce === 'string' ? { spend: nonce } : {}) };
112
116
  }
@@ -118,6 +122,29 @@ function autonomyGrantGate(input, deps) {
118
122
  const id = (0, approval_queue_1.approvalRequestId)(action.kind, action.target);
119
123
  return { proceed: false, id, message: `${why}${(0, approval_queue_1.pendingRequestLine)(id, action.kind, input.askRoot, title, input.root)}` };
120
124
  }
125
+ /**
126
+ * @implements A-SPEC-794.83 — what a profile request changes, in words, against the profile that covers the scope now:
127
+ * a new profile with its flags, each flag that turns on or off, or no flag change. The form shows it.
128
+ */
129
+ function fullProfileChange(current, next) {
130
+ const names = ['push', 'publish', 'architecture'];
131
+ const word = (on) => (on ? 'on' : 'off');
132
+ if (current === null)
133
+ return `new profile: ${names.map((n) => `${n} ${word(next[n])}`).join(', ')}`;
134
+ const changed = names.filter((n) => current[n] !== next[n]).map((n) => `${n} ${word(current[n])} → ${word(next[n])}`);
135
+ return changed.length === 0 ? 'no flag changes' : changed.join(', ');
136
+ }
137
+ /**
138
+ * @implements A-SPEC-794.91 — one guard for every autonomy widening (session autonomy, a full profile, a run delegation,
139
+ * init --autonomy): an environment approval counts only where the operator guard finds no agent. Review A of 98c58e31
140
+ * measured a 7-day delegation created from an agent ancestor with an environment approval; delegate and init skipped
141
+ * the guard. A grant from the session form does not come through here.
142
+ */
143
+ function autonomyWideningGate(input, deps) {
144
+ void input;
145
+ const why = deps.guard();
146
+ return why === null ? { proceed: true } : { proceed: false, why };
147
+ }
121
148
  /** @implements A-SPEC-792.3 — the flags are the request's subject, so a grant for one set cannot issue another. */
122
149
  function fullProfileSubject(flags) {
123
150
  return `push=${flags.push ? 1 : 0};publish=${flags.publish ? 1 : 0};architecture=${flags.architecture ? 1 : 0}`;
@@ -130,15 +157,18 @@ function fullProfileSubject(flags) {
130
157
  function fullProfileGate(input, deps) {
131
158
  const action = { kind: 'autonomy-profile', target: input.scope, subject: fullProfileSubject(input.flags) };
132
159
  const covering = deps.resolve(input.askRoot, input.envApproval, action, input.now);
133
- if (covering !== undefined) {
160
+ // @implements A-SPEC-794.89, A-SPEC-794.91 — an environment approval issues a profile only where no agent is found
161
+ if (covering !== undefined && (covering.source === 'grant' || autonomyWideningGate({ kind: action.kind, envApproval: covering.approval }, deps).proceed)) {
134
162
  const nonce = covering.approval.nonce;
135
163
  return { proceed: true, approval: covering.approval, ...(covering.source === 'grant' && typeof nonce === 'string' ? { spend: nonce } : {}) };
136
164
  }
137
165
  const why = deps.guard();
138
166
  if (why === null)
139
167
  return { proceed: true };
140
- const title = `full autonomy for ${input.scope} (${action.subject})`;
141
- deps.enqueue(input.askRoot, { ...action, why: `under ${input.scope}, ${autonomy_1.FULL_PROFILE_MEANING} (${action.subject})`, title });
168
+ // A-SPEC-794.83 — the form names what the request changes, not only the flag code
169
+ const change = fullProfileChange(input.current ?? null, input.flags);
170
+ const title = `full autonomy for ${input.scope} — ${change} (${action.subject})`;
171
+ deps.enqueue(input.askRoot, { ...action, why: `under ${input.scope}, ${autonomy_1.FULL_PROFILE_MEANING}; ${change} (${action.subject})`, title });
142
172
  const id = (0, approval_queue_1.approvalRequestId)(action.kind, action.target);
143
173
  return { proceed: false, id, message: `${why}${(0, approval_queue_1.pendingRequestLine)(id, action.kind, input.askRoot, title, input.scope)}` };
144
174
  }