@holmes-lab/holmes-kit 0.40.0 → 0.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +79 -5
  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 +394 -267
  10. package/dist/holmes/cli/init.js +17 -6
  11. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  12. package/dist/holmes/cli/interactive-prompt.js +98 -16
  13. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  14. package/dist/holmes/cli/ledger-witness.js +212 -0
  15. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  16. package/dist/holmes/cli/playbook-skills.js +26 -349
  17. package/dist/holmes/config/config.d.ts +21 -0
  18. package/dist/holmes/config/config.js +22 -3
  19. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  20. package/dist/holmes/governance/approval-queue.js +279 -9
  21. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  22. package/dist/holmes/governance/autonomous-shell.js +157 -4
  23. package/dist/holmes/governance/autonomy.d.ts +216 -0
  24. package/dist/holmes/governance/autonomy.js +1162 -10
  25. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  26. package/dist/holmes/governance/install-manifest.js +144 -14
  27. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  28. package/dist/holmes/governance/ledger-witness.js +296 -0
  29. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  30. package/dist/holmes/governance/provenance-chain.js +23 -4
  31. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  32. package/dist/holmes/governance/push-gate-runner.js +40 -3
  33. package/dist/holmes/governance/push-gate.d.ts +13 -2
  34. package/dist/holmes/governance/push-gate.js +106 -14
  35. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  36. package/dist/holmes/governance/recorded-pairs.js +25 -1
  37. package/dist/holmes/governance/session-context.d.ts +7 -0
  38. package/dist/holmes/governance/session-context.js +34 -6
  39. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  40. package/dist/holmes/guardrail/advisory-line.js +718 -0
  41. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  42. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  43. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  44. package/dist/holmes/guardrail/command-traits.js +379 -0
  45. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  46. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  47. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  48. package/dist/holmes/guardrail/impact-gate.js +32 -5
  49. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  50. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  51. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  52. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  53. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  54. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  55. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  56. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  57. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  58. package/dist/holmes/guardrail/write-target.js +7 -1
  59. package/dist/holmes/hooks/pre-tool-use.d.ts +71 -0
  60. package/dist/holmes/hooks/pre-tool-use.js +1466 -14
  61. package/dist/holmes/hooks/session-start.js +27 -1
  62. package/dist/holmes/hooks/stop.d.ts +7 -0
  63. package/dist/holmes/hooks/stop.js +39 -2
  64. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  65. package/dist/holmes/mcp/elicit-approval.js +5 -2
  66. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  67. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  68. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  69. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  70. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  71. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  72. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  73. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  74. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  75. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  76. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  77. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  78. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  79. package/dist/holmes/mcp/handlers/test-execution.js +201 -21
  80. package/dist/holmes/mcp/handlers.d.ts +473 -8
  81. package/dist/holmes/mcp/handlers.js +6 -1
  82. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  83. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  84. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  85. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  86. package/dist/holmes/mcp/tool-schemas.js +16 -10
  87. package/dist/holmes/project/baseline.d.ts +15 -2
  88. package/dist/holmes/project/baseline.js +11 -6
  89. package/dist/holmes/project/bounded-io.d.ts +1 -0
  90. package/dist/holmes/project/bounded-io.js +4 -2
  91. package/dist/holmes/project/change-source.d.ts +4 -0
  92. package/dist/holmes/project/change-source.js +13 -5
  93. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  94. package/dist/holmes/project/playbook-reference.js +259 -0
  95. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  96. package/dist/holmes/project/playbook-skill-states.js +396 -0
  97. package/dist/holmes/project/root.d.ts +9 -1
  98. package/dist/holmes/project/root.js +26 -3
  99. package/dist/holmes/project/running-package.d.ts +15 -0
  100. package/dist/holmes/project/running-package.js +87 -0
  101. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  102. package/dist/holmes/review/evidence-mode.js +33 -0
  103. package/dist/holmes/review/head-worktree.d.ts +55 -0
  104. package/dist/holmes/review/head-worktree.js +329 -0
  105. package/dist/holmes/review/mrp.js +13 -3
  106. package/dist/holmes/review/run-provenance.d.ts +45 -0
  107. package/dist/holmes/review/run-provenance.js +314 -0
  108. package/dist/holmes/review/test-evidence.d.ts +174 -0
  109. package/dist/holmes/review/test-evidence.js +330 -2
  110. package/dist/holmes/review/test-reports.d.ts +94 -0
  111. package/dist/holmes/review/test-reports.js +382 -0
  112. package/dist/holmes/review/test-runner.d.ts +178 -65
  113. package/dist/holmes/review/test-runner.js +551 -319
  114. package/dist/holmes/review/test-units.d.ts +159 -0
  115. package/dist/holmes/review/test-units.js +814 -0
  116. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  117. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  118. package/package.json +5 -2
  119. package/playbooks/publish/PLAYBOOK.md +2 -1
package/README.md CHANGED
@@ -11,10 +11,53 @@
11
11
  <!-- holmes-kit:attest:begin -->
12
12
  ![traced files](.ax/badges/traced.svg)
13
13
 
14
- **536/536** source files (100%) trace to an approved spec · **1170/1266** approved A-SPECs (92.4%) are anchored from code.
15
- Measured at `b487a60cb479` (specs `sha256:4432137ee912`) — reproduce with `holmes-kit attest --exclude docs/goals/probes/`.
14
+ **565/565** source files (100%) trace to an approved spec · **1263/1370** approved A-SPECs (92.1%) are anchored from code.
15
+ Measured at `c4a016695ba7` (specs `sha256:ac5e4f7df00f`) — reproduce with `holmes-kit attest --exclude docs/goals/probes/`.
16
16
  <!-- holmes-kit:attest:end -->
17
17
 
18
+ ### 0.40.x push evidence: the supported surface
19
+
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
+
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.
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
+ - 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
+ - **The run must read only HEAD, judged by what it loaded.**
27
+ - A symbolic link anywhere in a linked `node_modules` that resolves into your work tree (a workspace package, at any depth) is `environment`, naming the link.
28
+ - Before any test, the pytest interpreter is started in HEAD's worktree (`python -P`, so 3.11 or later) and asked where every dotted module name of HEAD's python files resolves (every layout and namespace package; capped by `testRun.pythonNames`, default 20000). An import-path entry or a `NODE_PATH` entry inside your work tree is `environment` by itself. A name that resolves into your work tree is `environment`, naming it, whatever the tests later do: subprocesses, xdist workers, a `sys.modules` restore. Typical causes are an editable install, a `.pth` finder or `PYTHONPATH`.
29
+ - pytest also runs with a holmes plugin that records every module it loaded, judged the same way. The exempt locations are the interpreter's own library directories.
30
+ - node is asked the same question for HEAD's package names, `NODE_PATH` included. The `node_modules` walk is bounded by `ax.config.json` `testRun.linkWalk` (`{ "entries": 500000, "seconds": 20 }` by default), and a directory it cannot read is `environment`.
31
+ - Named limits:
32
+ - a HEAD conftest that rewrites the plugin's record (a forgery; the environment question still holds);
33
+ - a package that requires your work tree by absolute path;
34
+ - a legacy sparse checkout (`core.sparseCheckout` in the shared config) keeps the worktree sparse, since turning it off would write your shared git configuration;
35
+ - a JavaScript workspace monorepo whose `node_modules` links into the work tree, and a `NODE_PATH` entry inside the work tree, are refused as `environment`;
36
+ - the environment question imports HEAD's packages to find their submodules, so a package `__init__` runs during it;
37
+ - xdist is judged by the environment question; no xdist run was measured.
38
+ - After upgrading to 0.40.1, run `test_run({ root, full: true })` once at the commit you push: records of 0.40.0 and scoped runs are no longer push evidence. A pytest project needs python 3.11 or later.
39
+ - pytest reads HEAD's own configuration file, pinned with `-c`.
40
+ - `PYTEST_ADDOPTS` and `PYTEST_PLUGINS` are dropped.
41
+ - `GOFLAGS` with `-run` or `-skip` (also `-test.run`, and also set through `go env -w`) is `environment`.
42
+ - The pytest interpreter is still the work tree's (a `.venv` is not in HEAD).
43
+ - A scoped run stays in the work tree.
44
+
45
+ | Runner | Evidenced in 0.40.x | Refused as `environment` |
46
+ |---|---|---|
47
+ | jest | One jest configuration source (the root's, or one directory's) with one project. holmes passes jest no ignore argument. Passed means exit 0 **and** no failure in the report. | `projects`; jest tests at the root beside another directory's configuration, or two configurations; a package.json script that runs jest with `--config`/`-c`; a configured `testNamePattern`; output `--showConfig` cannot print |
48
+ | pytest | Default test names (`test_*.py`, `*_test.py`), outside pytest's default norecursedirs. `--rootdir` and `--confcutdir` are the unit, and `--ignore` adds your exclusions. Passed means exit 0 **and** no JUnit failure or error. | a declared `python_files`, `python_functions` or `python_classes`; `-k`/`-m` in `addopts` |
49
+ | go | The `_test.go` files `go list` builds on this platform with no tags, per package. Passed means exit 0 **and** no failed test event. Files go does not build here are named in `notBuilt`. | go test files under no `go.mod` |
50
+ | cargo, maven/gradle, dotnet | — | a build root holding tests or code; test files of those languages under no build root |
51
+ | others | — | a build file 0.40.x has no runner for (Gemfile, composer.json, Package.swift, build.sbt, mix.exs, CMakeLists.txt, pubspec.yaml) |
52
+
53
+ - **Exclusions** (`.gitignore`, `ax.config.json` `testRun.excludeDirs`, git submodules) differ by runner:
54
+ - pytest takes them as `--ignore`, and go leaves those packages out;
55
+ - jest is told nothing, and the tests it reports under an excluded tree leave the judgement. If such a test ran red, the push is `environment`, naming the file: the runner's own configuration must leave it out too;
56
+ - a git submodule is empty in HEAD's worktree, and named.
57
+ - **Code** is tested only by an executed test of the scanned universe whose own nearest build root is the code's. That a unit ran is not evidence, and a test outside the repository credits nothing.
58
+ - **A push without evidence** is allowed only when there is nothing to test: no test file and no implementation code.
59
+ - **Named limits:** a red behind a go build tag; a `-k` deselection that is not declared in configuration; a linked `node_modules` that differs from the lockfile.
60
+
18
61
  ---
19
62
 
20
63
  ## 🕵️ Philosophy & Vision: Beyond Code Generation
@@ -42,7 +85,7 @@ Measured at `b487a60cb479` (specs `sha256:4432137ee912`) — reproduce with `hol
42
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.
43
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/`.
44
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.
45
- - **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.
46
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.
47
90
  - **Revoking.** `--revoke` ends the profile.
48
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.
@@ -53,6 +96,12 @@ Measured at `b487a60cb479` (specs `sha256:4432137ee912`) — reproduce with `hol
53
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.
54
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.
55
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.
56
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.
57
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.
58
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.
@@ -127,7 +176,7 @@ Measured at `b487a60cb479` (specs `sha256:4432137ee912`) — reproduce with `hol
127
176
  - 📋 **Requirements & specification governance**: strict **"No Spec, No Code"** across a 4-tier chain (`REQ ➔ H-SPEC ➔ A-SPEC ➔ T-SPEC`) with `// @implements A-SPEC-XXX` code anchors — comma-lists and every anchor in a file participate in the gate.
128
177
  - 🔴 **Inbuilt TDD — RED-first, recorded and judged** *(0.9.0)*: constitution article **ART-8** reads a recorded `red-assertion → green` sequence in the ledger, and a `red-error` (a test that could not run) is not a valid RED — so "the covering test failed *correctly*" is judged from the record, not on trust. It ships observe-first (`redFirstEvidence: track`): it reports, and blocks only under `strict`. Where superpowers *asks* for RED-first, holmes-kit *records* whether it happened.
129
178
  - 🧱 **Deterministic gate** *(0.8.0, 0.13.0)*: shell writes are judged at the segment's **effective working directory**, the governing anchor is the whole set rather than the first match, a project is governed when **any** spec exists, and `cp`/`mv` are classified by **destination**.
130
- - 🤖 **Autonomous approval — three layers** *(0.8.0, reworked 0.13.0; session UX 0.29.0)*: a project default (`init --autonomy`) and an expiring per-session envelope let the agent seal **low-risk** specs itself under an `autonomous:<client>` actor. Ordinary unclassified HITL work queues without a form; governance-critical, high-risk or irreversible work asks for an in-session confirmation (an approval the same user's agent shell can forge: Known limitations); a form that is not answered returns to the approval queue *(since 0.35.3 — it was recorded as an approval before)*. No holmes-kit tool grants autonomy to the agent (its own shell writing approval files is the Known limitation above: not a security boundary), the posture is surfaced at every session start, and off is byte-identical to a human-gated project.
179
+ - 🤖 **Autonomous approval — three layers** *(0.8.0, reworked 0.13.0; session UX 0.29.0)*: a project default (`init --autonomy`, or Enter at `init`'s question: since 0.41 the default is Y on a first install at a person's own terminal, the current value on a re-init (Enter then writes nothing), and the current value or off under an agent harness or CI; only low-risk specs approve themselves, governance-critical, high-risk and irreversible ones still ask; `holmes-kit init --no-autonomy`, or removing `HOLMES_AUTONOMOUS_APPROVAL` from `.mcp.json`, turns it off, while `holmes-kit autonomy off` ends session autonomy only) and an expiring per-session envelope let the agent seal **low-risk** specs itself under an `autonomous:<client>` actor. Ordinary unclassified HITL work queues without a form; governance-critical, high-risk or irreversible work asks for an in-session confirmation (an approval the same user's agent shell can forge: Known limitations); a form that is not answered returns to the approval queue *(since 0.35.3 — it was recorded as an approval before)*. No holmes-kit tool grants autonomy to the agent (its own shell writing approval files is the Known limitation above: not a security boundary), the posture is surfaced at every session start, and off is byte-identical to a human-gated project.
131
180
  - 🧭 **Compatibility and evolution gates** *(0.14.0, 0.15.0)*: a new A-SPEC seals only with `harness_impact:` and `os_impact:` declared and machine-cross-checked against Files-to-Touch; separately, a changed in-scope source that **newly introduces an external dependency** raises a spec-reappraisal — a warning when manual, a queued item under autonomy, never a blocked turn.
132
181
  - 🚢 **Release autonomy + docs-currency gate** *(0.13.0, machine-checked in 0.23.2)*: `npm publish` runs `verify-release` through `prepublishOnly`, which refuses a dirty tree, a missing or old release test-lane receipt and a badge that has not moved, and checks the docs — a stale doc is a false claim. Without a full profile the hook gives `npm publish` no decision (measured on a scratch project); under one, it follows `--allow-publish`. The risk rules for a release are in the publish playbook and are a procedure: nothing runs the classifier for you.
133
182
  - 🧠 **3-tier semantic layer** *(local preparation default in 0.29.0)*: BGE-M3 is prepared and verified locally during a normal npm installation (zero repository-text egress); `HOLMES_SKIP_MODEL_INSTALL=1` is the explicit opt-out. `cloud` remains the opt-in `gemini-embedding-001` tier. Measured on 305 traceability cases: recall 0.486 → 0.667 → **0.887**; on lexical-zero requests 0% → 52% → **92%**. Surfaced additively, never as a hard filter.
@@ -138,7 +187,30 @@ Measured at `b487a60cb479` (specs `sha256:4432137ee912`) — reproduce with `hol
138
187
  - 🔔 **Approval UX** *(0.3.1; inbox split 0.15.0; in-session recovery 0.29.0)*: the agent-session UI is primary; the tracked queue is the fallback when the client cannot present it. A form timeout is distinguished from cancel/unavailable, and in every mode it returns the request to the queue. The queue holds **decision-seeking requests only** — plain gate refusals live in a local per-machine log (raw commands never leave the machine), after 1,404 single-shot refusals were measured burying a 2-item inbox.
139
188
  - ⬆️ **Zero-config upgrades & session banner** *(0.8.0–0.12.2)*: `holmes-kit upgrade` re-pins **every** recorded workspace in one command (`--dry-run`/`--yes`), and every session start states the version, the governance rule and any newer published version — from every harness's MCP startup, not just Claude's. The write stays your explicit choice, never a silent auto-install.
140
189
  - 🧰 **Governance UX tools** *(0.10.0)*: `spec_unseal` (return a sealed spec to editable `draft` in one act, out-of-band approval required), `approval_status` and `ledger_timeline` for read-only observability, and a structured `conflict` on optimistic-concurrency refusal.
141
- - 🚦 **Push & server-side re-validation** *(hardened in 0.8.0)*: a local `pre-push` evidence gate (test-run ledger head == push HEAD, green, executed > 0) plus a server-side workflow that re-runs `npm ci → build → full suite → tarball install probe`. Where that workflow runs, a `--no-verify` push or a hook-less clone shows as a failed run; it detects, it does not prevent, and write access can change or cancel it.
190
+ - 🚦 **Push & server-side re-validation** *(hardened in 0.8.0)*: a local `pre-push` evidence gate (a FULL test run — `test_run({root, full: true})` — at the push HEAD, green, with at least one executed test in every detected test ecosystem; a scoped run is never push evidence, and an unreadable or mis-shaped ledger is refused) plus a server-side workflow that re-runs `npm ci → build → full suite → tarball install probe`. Where that workflow runs, a `--no-verify` push or a hook-less clone shows as a failed run; it detects, it does not prevent, and write access can change or cancel it.
191
+ - **What a full run runs.** HEAD, checked out in a temporary worktree outside the repository (see the top of this README). The files are what git sees there minus `ax.config.json` `testRun.excludeDirs`. A tracked file stays in even under a later ignore pattern. The record carries `ranIn: head-worktree` and the times of creation, preparation and run; the push gate accepts no full record without that marker.
192
+ - Every execution unit runs with its own directory as cwd.
193
+ - The supported surface is the table at the top of this README; everything outside it is refused as `environment`.
194
+ - The jest unit is the root, or the one directory with its own jest configuration (a `jest.config.*` or package.json `jest` field). pytest units are the root and each directory with pytest configuration (`pytest.ini`, pyproject `[tool.pytest…]`, setup.cfg `[tool:pytest]`, tox.ini `[pytest]`); a parent skips its configured children.
195
+ - A go unit is each `go.mod` holding go code.
196
+ - Holmes never replaces your runner configuration. jest gets no ignore argument; pytest gets `--ignore` (it adds to your configuration) and `--rootdir=<unit>`.
197
+ - Runner output is read from jest's `--outputFile` report or from well-shaped JSON only, so your own console output cannot break it. An output that cannot be read is refused as `environment`, never replaced by a default.
198
+ - A git submodule is always outside the evidence and named in `notDetected`. A sparse work tree does not matter: HEAD's worktree is a whole checkout.
199
+ - **What is checked after the run.** Every detected test must have run, at the granularity its runner reports: jest and pytest per file, go per package. Every build root holding code must have an executed test whose own nearest build root is that root: neither a nested package's tests nor a unit having run stands for its parent's code.
200
+ - The expected tests are named by default naming only (jest's testMatch, pytest's `test_*.py` / `*_test.py`, go's `_test.go`). A runner rule that narrows collection, such as pytest `testpaths`, never removes one, so a test it leaves unrun is refused as `collect`.
201
+ - go: a package whose tests all skip counts as run; a `_test.go` with no test function is named in `notTests`; test names are Unicode identifiers.
202
+ - Named limits: a pytest `-k` deselection inside a file is below file granularity, and go build tags are below package granularity.
203
+ - **What a refusal says.** It names one of four acts. It never recommends hiding a red test.
204
+ - `fix-tests`: a red run, a unit that ran no test, code without tests in a build root, or code with no build file (it names the file to add);
205
+ - `collect`: detected tests that did not run, named. Make the runner collect them, or exclude them if they are not the project's.
206
+ - `rerun`: run the full call at the pushed head, pushing branches one at a time;
207
+ - `environment`: the runner itself is missing, its output cannot be read, the configuration is outside the 0.40.x surface, an excluded tree's test ran red, a test outside the repository ran, HEAD's worktree could not be made or prepared (a run location that is a link or another user's, a failing or installing `testRun.prepare`, a linked work-tree package or import path), or the run stopped at the 180-minute ceiling (split the suite or ask the owner).
208
+ - **Nothing to test.** A repository with no test file and no implementation code (README, settings, docs, configuration files such as `*.config.*`, `conf.py`, `.eslintrc.*`, `setup.py`) pushes with a notice and a `{ts, head, reason: "no-tests"}` line in `.ax/ledger/no-evidence-pushes.jsonl`.
209
+ - **Exclusions are yours.** `.gitignore` and `testRun.excludeDirs` keep a tree out of the universe. An ignored, uncommitted tree is not in HEAD's worktree at all. For a committed excluded tree, pytest and go do not run it; jest is told nothing, and its report of the tree leaves the judgement (a red there is `environment`).
210
+ - An `excludeDirs` entry with a `/` is a root-relative path, so `test/fixtures/pyproj`, `./vendor` and `fixtures/` all start at the root. One without is a directory name at any depth (`pyproj`).
211
+ - Absolute entries, entries that leave the root, and entries that name nothing are ignored and named in `excludeDirsIgnored`.
212
+ - **pytest collection.** Every `test_*.py` / `*_test.py` outside pytest's default norecursedirs is expected; `testpaths` does not narrow the list, and a declared `python_files`, `python_functions`, `python_classes` or `-k`/`-m` in `addopts` is outside the 0.40.x surface. A `test_*.py` that holds no test function is not a test: it is named in `notTests` and never required.
213
+ - **Limit.** If the evidence file and the ledger directory are both made read-only, a red run cannot replace an older green record. The answer names that failure in `recordFailed`.
142
214
  - 🧪 **Self-healing & diagnostic doctor**: integrity checks that name the fix for each failing one (`doctor`), repair of the recovery skills (`holmes-kit skills refresh`) and of a blocked spec (`spec_remediate`), plus a live report of holmes-kit's own advertised MCP schema token cost.
143
215
  - 🔢 **Sensible spec numbering** *(0.12.1)*: a brand-new project's first slice is **REQ-100**; existing projects keep `max(existing)+1` exactly, and 4-digit ids (including `ADR-1000+`) work cleanly.
144
216
  - 🌐 **English CLI & hook surface** *(0.13.0)*: the operator-facing CLI, `doctor` output, hook `deny` reasons and interactive prompts are English, guarded by a hangul-absence test over the **rendered runtime output** rather than a source scan. Not yet English: a few strings outside that test (a truncation marker, one `init --dry-run` hint) and the comments in the files `init` writes for roles and `.gitattributes`; planned for 0.41.
@@ -341,6 +413,8 @@ flowchart LR
341
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 |
342
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 |
343
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 compares the chain with the pushed one and lists the rows to recognise *(new in 0.41)* |
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) |
344
418
  | `holmes-kit autonomy status` | Show the current autonomous-approval posture (project default + session envelope) |
345
419
  | `holmes-kit autonomy on --for 2h` | Self-drive low-risk specs for this session only (expiring; needs a TTY or `HOLMES_APPROVAL`) |
346
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
- bf78b204-mw2004s8
1
+ f30ee53d-mwegud15
@@ -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
  }
@@ -75,7 +75,7 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
75
75
  exports.semanticCoverageCheck = semanticCoverageCheck;
76
76
  exports.semanticTierVerdict = semanticTierVerdict;
77
77
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
78
- // @implements A-SPEC-794.59, A-SPEC-794.55, A-SPEC-792.46, A-SPEC-792.48, A-SPEC-245.8, A-SPEC-251.5, A-SPEC-476.1, A-SPEC-476.5, A-SPEC-751.4, A-SPEC-751.9, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.9, A-SPEC-770.10,A-SPEC-733,A-SPEC-727, A-SPEC-774.22, A-SPEC-781.2, A-SPEC-182.3, A-SPEC-182.4,A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-102.28, A-SPEC-102.29
78
+ // @implements A-SPEC-794.113, A-SPEC-794.110, A-SPEC-794.59, A-SPEC-794.55, A-SPEC-792.46, A-SPEC-792.48, A-SPEC-245.8, A-SPEC-251.5, A-SPEC-476.1, A-SPEC-476.5, A-SPEC-751.4, A-SPEC-751.9, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.9, A-SPEC-770.10,A-SPEC-733,A-SPEC-727, A-SPEC-774.22, A-SPEC-781.2, A-SPEC-182.3, A-SPEC-182.4,A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-102.28, A-SPEC-102.29
79
79
  // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712, A-SPEC-769.14, A-SPEC-769.16, A-SPEC-769.17, A-SPEC-769.18, A-SPEC-769.19, A-SPEC-769.20, A-SPEC-769.21
80
80
  const doctor_guidance_1 = require("./doctor-guidance");
81
81
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
@@ -718,6 +718,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
718
718
  const add = (name, level, detail, fix) => checks.push({ name, level, detail, fix });
719
719
  const runtimeRegistry = opts?.runtimeRegistryPath ?? (0, runtime_binding_1.defaultRuntimeRegistry)();
720
720
  let routed;
721
+ // A-SPEC-794.113 (review A, M2) — the package the sessions' gate loads, when it is not the one doctor runs from
722
+ let gatePackage = null;
721
723
  if (fs.existsSync(runtimeRegistry)) {
722
724
  try {
723
725
  // @implements A-SPEC-769.8 — the Codex home the duplicate-route check reads is the one doctor was pointed at.
@@ -744,6 +746,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
744
746
  const routedReal = real(s.packageRoot);
745
747
  const ownReal = real(packageRoot);
746
748
  let own = '';
749
+ if (routedReal !== null && ownReal !== null && routedReal !== ownReal)
750
+ gatePackage = routedReal;
747
751
  if (routedReal === null || ownReal === null || routedReal !== ownReal) {
748
752
  let ownBuild = 'unknown';
749
753
  try {
@@ -1050,7 +1054,14 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1050
1054
  // the all-current PASS too (the count check never counted them either), but the wording keeps
1051
1055
  // ownership distinct and never promises that init will fix what init deliberately skips.
1052
1056
  const skillsDir = path.join(target, '.claude', 'skills');
1053
- const states = (0, playbook_skills_1.playbookSkillStates)(packageRoot, target);
1057
+ // @implements A-SPEC-794.110 — the reference the gate's product-installed judgement reads, from the one function it
1058
+ // calls (doctor read the working tree's playbooks while the gate read the recorded build: "7 current … PASS" here,
1059
+ // seven skills named there — re-check of d77e59d9, A-M1 and B-M2)
1060
+ const judgedSkills = (0, playbook_skills_1.judgedSkillStates)(packageRoot, target);
1061
+ const states = judgedSkills.states;
1062
+ const skillReference = judgedSkills.reference;
1063
+ // the drifted skills whose playbook is not the one the recorded build held: a refresh alone cannot make them current
1064
+ const movedSkills = judgedSkills.moved.filter((n) => states.some((x) => x.name === n && x.state === 'drifted'));
1054
1065
  const of = (s) => states.filter((x) => x.state === s).map((x) => (0, playbook_skills_1.invocableSkillName)(x.name));
1055
1066
  // Orphan rows already carry the RAW directory name (round-6: re-prefixing a case-variant
1056
1067
  // produced the CURRENT skill's name in a delete instruction).
@@ -1074,7 +1085,15 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1074
1085
  'This holmes-kit package ships no playbooks — reinstall or upgrade holmes-kit itself.');
1075
1086
  }
1076
1087
  else if (current === states.length) {
1077
- add('recovery skills', 'PASS', `${states.length} recovery skill(s) current under ${skillsDir}`);
1088
+ // review B (low 6) — against what: the package doctor runs from (the ledger and closed cases have their own row)
1089
+ const against = skillReference.kind !== 'package' ? ''
1090
+ : ` — judged against the playbooks of holmes-kit ${(() => { try {
1091
+ return String(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version ?? 'unknown');
1092
+ }
1093
+ catch {
1094
+ return 'unknown';
1095
+ } })()} at ${packageRoot}`;
1096
+ add('recovery skills', 'PASS', `${states.length} recovery skill(s) current under ${skillsDir}${against}`);
1078
1097
  }
1079
1098
  else {
1080
1099
  const KNOWN_STATES = new Set(['current', 'drifted', 'missing', 'foreign', 'orphaned', 'source-unreadable', 'aliased']);
@@ -1093,11 +1112,21 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1093
1112
  // The remedy must actually WORK: `init --target` on a wired target exits 2 (self-disarm
1094
1113
  // guard) and --force demands governance approval — a refusal loop for three advisory files
1095
1114
  // (round-1 HIGH). `skills refresh` touches only marker-owned skills, never wiring.
1115
+ // A-SPEC-794.110 — with no reference a refresh cannot make a skill current, and a playbook that left the recorded
1116
+ // build needs the build that records it: the remedy named is the one that works for the state found
1117
+ const refreshable = drifted.length - movedSkills.length + missing.length;
1118
+ // review B (confirming, L2) — a path with a space is quoted where a command is shown
1119
+ const sq = (p) => (/[\s"'$`\\]/.test(p) ? `'${p.replace(/'/g, '\'\\\'\'')}'` : p);
1096
1120
  const fixes = [
1097
- drifted.length + missing.length > 0
1098
- ? `Run \`holmes-kit skills refresh --target ${target}\` to refresh the skills holmes-kit owns.` : '',
1121
+ // review B (low 1) — the reason is said once, on the reference row
1122
+ skillReference.kind === 'closed'
1123
+ ? 'No recorded build to judge against — the `recovery skills reference` row says why and what makes one.' : '',
1124
+ skillReference.kind !== 'closed' && movedSkills.length > 0
1125
+ ? `${movedSkills.map((n) => path.join(packageRoot, 'playbooks', n, 'PLAYBOOK.md')).join(', ')} ${movedSkills.length === 1 ? 'is' : 'are'} not what the gate last recorded there, and the recorded one is the reference (the recorded digest is an earlier build's: at the last build no person's window naming ${movedSkills.length === 1 ? 'it' : 'them'} was open): if the change is wanted, a person seals an A-SPEC naming ${movedSkills.length === 1 ? 'it' : 'them'} in a session in that checkout — \`spec_approve\` again on the A-SPEC that names ${movedSkills.length === 1 ? 'it' : 'them'} (the form says it is a re-seal), or a new one; in Holmes-Kit's own repository the spec names the SKILL.md under .claude/skills too — a build run in a governed agent session inside that window records it (a build run outside such a session records nothing), then \`holmes-kit skills refresh --target ${sq(target)}\` and the refreshed SKILL.md is committed; if it is not wanted, restore the playbook.` : '',
1126
+ skillReference.kind !== 'closed' && refreshable > 0
1127
+ ? `Run \`holmes-kit skills refresh --target ${sq(target)}\` to refresh the skills holmes-kit owns.` : '',
1099
1128
  foreign.length > 0 && drifted.length + missing.length === 0
1100
- ? `A file holmes-kit cannot prove it owns occupies it (no readable marker); holmes-kit leaves it untouched — if it is not yours, restore permissions or remove it and re-run \`holmes-kit skills refresh --target ${target}\`.` : '',
1129
+ ? `A file holmes-kit cannot prove it owns occupies it (no readable marker); holmes-kit leaves it untouched — if it is not yours, restore permissions or remove it and re-run \`holmes-kit skills refresh --target ${sq(target)}\`.` : '',
1101
1130
  orphaned.length > 0
1102
1131
  ? 'holmes-kit no longer ships it; delete the directory if you no longer want it.' : '',
1103
1132
  sourceUnreadable.length > 0
@@ -1109,6 +1138,29 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1109
1138
  ].filter(Boolean).join(' ');
1110
1139
  add('recovery skills', 'WARN', `${current} of ${states.length} recovery skill(s) current under ${skillsDir} — ${parts}`, fixes);
1111
1140
  }
1141
+ // A-SPEC-794.110 — what the skills were judged against, when it is not simply this package's own files
1142
+ // A-SPEC-794.113 (review A, M2; review B, low 6) — and when it is, which package: doctor judges with the package
1143
+ // it runs from, the gate with the package the sessions load, and the two can be different installs
1144
+ const quoted = (p) => (/[\s"'$`\\]/.test(p) ? `'${p.replace(/'/g, '\'\\\'\'')}'` : p);
1145
+ const elsewhere = gatePackage === null ? ''
1146
+ : `. This project's sessions load the gate from ${gatePackage}: the gate judges against that install's reference, which this doctor did not read — run \`node ${quoted(path.join(gatePackage, 'bin', 'holmes-kit.js'))} doctor --target ${quoted(target)}\` for its answer`;
1147
+ if (skillReference.kind === 'ledger') {
1148
+ // review B (confirming, L6 and M1) — the row is the place the digests are read from, not the build that made each
1149
+ // of them (a digest no window moved is carried from an earlier build); and which chain was read
1150
+ add('recovery skills reference', gatePackage === null ? 'PASS' : 'WARN', `judged against the playbook digests in the build the gate recorded at ${skillReference.recordedAt} (${skillReference.commit.slice(0, 12)}, chain ${skillReference.replica}) in ${packageRoot}, not against the working tree's playbooks — a digest there is the one a person's window last recorded, carried from an earlier build when none moved it; it is the reference the gate's product-installed judgement reads when it runs from this install${elsewhere}`);
1151
+ }
1152
+ else if (skillReference.kind === 'closed') {
1153
+ add('recovery skills reference', 'WARN', `no recorded build to judge against, so no skill is shown current (the gate's product-installed judgement reads the same when it runs from this install): ${skillReference.reason}${elsewhere}`);
1154
+ }
1155
+ else if (gatePackage !== null) {
1156
+ const version = (() => { try {
1157
+ return String(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version ?? 'unknown');
1158
+ }
1159
+ catch {
1160
+ return 'unknown';
1161
+ } })();
1162
+ add('recovery skills reference', 'WARN', `judged against the playbooks of holmes-kit ${version} at ${packageRoot}${elsewhere}`);
1163
+ }
1112
1164
  }
1113
1165
  else {
1114
1166
  // @implements A-SPEC-190 (round 7) — without --target this check simply did not appear, so the