@holmes-lab/holmes-kit 0.35.16 → 0.35.18

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 (43) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/README.md +4 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-watch.js +4 -0
  5. package/dist/holmes/cli/approve.d.ts +8 -1
  6. package/dist/holmes/cli/approve.js +27 -8
  7. package/dist/holmes/cli/doctor.js +14 -2
  8. package/dist/holmes/cli/index.js +9 -4
  9. package/dist/holmes/cli/init.js +3 -1
  10. package/dist/holmes/cli/interactive-prompt.d.ts +5 -0
  11. package/dist/holmes/cli/interactive-prompt.js +12 -4
  12. package/dist/holmes/cli/runtime-binding.d.ts +5 -0
  13. package/dist/holmes/cli/runtime-binding.js +42 -4
  14. package/dist/holmes/governance/approval-queue.d.ts +7 -1
  15. package/dist/holmes/governance/approval-queue.js +28 -3
  16. package/dist/holmes/governance/autonomy.js +13 -1
  17. package/dist/holmes/guardrail/write-target.d.ts +18 -0
  18. package/dist/holmes/guardrail/write-target.js +136 -35
  19. package/dist/holmes/hooks/pre-tool-use.js +15 -10
  20. package/dist/holmes/hooks/rtm-refresh-child.d.ts +12 -2
  21. package/dist/holmes/hooks/rtm-refresh-child.js +26 -4
  22. package/dist/holmes/hooks/stop-timing.d.ts +12 -0
  23. package/dist/holmes/hooks/stop-timing.js +22 -0
  24. package/dist/holmes/hooks/stop.js +28 -0
  25. package/dist/holmes/mcp/handlers/graph-operations.d.ts +1 -0
  26. package/dist/holmes/mcp/handlers/graph-operations.js +4 -4
  27. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +25 -0
  28. package/dist/holmes/mcp/handlers/operator-inspection.js +60 -1
  29. package/dist/holmes/mcp/handlers/test-execution.d.ts +7 -0
  30. package/dist/holmes/mcp/handlers/test-execution.js +9 -2
  31. package/dist/holmes/mcp/handlers.d.ts +9 -0
  32. package/dist/holmes/mcp/operator-recovery.js +5 -2
  33. package/dist/holmes/refresh/freshness-coordinator.d.ts +9 -0
  34. package/dist/holmes/refresh/freshness-coordinator.js +14 -4
  35. package/dist/holmes/rtm/anchor-ids.d.ts +15 -0
  36. package/dist/holmes/rtm/anchor-ids.js +45 -0
  37. package/dist/holmes/rtm/test-scope.d.ts +12 -0
  38. package/dist/holmes/rtm/test-scope.js +29 -4
  39. package/dist/holmes/runtime/dispatch.js +28 -3
  40. package/package.json +1 -1
  41. package/playbooks/publish/PLAYBOOK.md +29 -6
  42. package/dist/holmes/guardrail/write-verb-word.d.ts +0 -13
  43. package/dist/holmes/guardrail/write-verb-word.js +0 -55
package/CHANGELOG.md CHANGED
@@ -5,6 +5,70 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.35.18] - 2026-10-12
9
+
10
+ ### Fixed
11
+
12
+ - **An autonomy refusal names the child rule that forces the human decision** (A-SPEC-769). Measured 2026-10-12 in
13
+ the Codex X1 runtime session: `spec_approve` on a parent spec answered "autonomy hitl" with no reason an operator
14
+ could act on. `specApprovalAutonomyReason` now returns `upstream-has-human-aspec: <child id> — <child rule>` (the
15
+ `files-to-touch-root-only` policy of A-SPEC-654 was the rule in the measured case; the policy itself is unchanged).
16
+ - **The `--autonomy` usage entry, the `init` refusal line and the interactive prompt say the same thing** (A-SPEC-769.1).
17
+ The three texts had drifted apart; each now names the grade, what it decides alone, and what still asks a person.
18
+ - **A runtime deadline refusal says which phase spent the budget** (A-SPEC-769.2). `Selected hook runtime deadline
19
+ exceeded` now ends with `; phases (ms of <budget>): input <n|->, selection <n|->, hook child <n|->`, and the Stop hook
20
+ prints `[Holmes-Kit] Stop hook used <total> ms of its 18000 ms hook budget — …` with the per-stage clock
21
+ (`src/holmes/hooks/stop-timing.ts`) once a run passes half the budget. Measured: the `scan` stage alone is ≈7 s on
22
+ this workspace; the figure is now visible, not reduced — see Known issues.
23
+ - **`runtime-binding status` separates drift from conflict** (A-SPEC-769.3, A-SPEC-769.5, A-SPEC-769.6). The status carries
24
+ `drift [{ path, kind: 'operator-config' | 'stale-workspace' }]` beside `conflicts`, `router: 'intact' | 'changed'`
25
+ and `activation`; `doctor` reads the harness identity from the router rows. A receipt that differs only because
26
+ the operator edited `~/.claude/settings.json` stays a conflict as A-SPEC-752.5/752.6 pin it (owner decision pending).
27
+ - **A refusal written to the refusal log is answerable from its own hint** (A-SPEC-770, 770.1). Field report
28
+ 2026-10-12 (jarvis): "approval impossible" — the design was intact (REQ-563/690: a refusal outside the inbox is
29
+ granted with `approve --grant <id>`), but the hint carried no id and the inbox never said such requests existed.
30
+ Every refusal line now ends with `run: holmes-kit approve --grant <id> --target <root>` carrying the actual id, the
31
+ inbox (`--list`, `--watch`) prints a footer counting requests outside the inbox, and the `--refusals` closing line
32
+ spells the same command. The first repair had written the positional form `approve <id>`, which the CLI refuses
33
+ with `unexpected argument` — measured once on the released CLI before the hint was rewritten (A-SPEC-770.1).
34
+
35
+ ### Known issues
36
+
37
+ - The Stop hook `scan` stage still takes ≈7 s on a 440-file workspace; under a parallel full-suite load (≥ 9) the
38
+ 18 s hook budget is exceeded and the refusal is now explained but still a refusal. Reduction is a separate slice.
39
+ - The inbox footer glyph is `◆` (the file's bullet, pinned by A-SPEC-770.1); A-SPEC-770's text says `◇`. The spec
40
+ text is the stale side; it is amended with the next unseal of REQ-770, not by a code change.
41
+
42
+ ## [0.35.17] - 2026-10-11
43
+
44
+ ### Fixed
45
+
46
+ - **`approval_status` says what to do next and relays the operator's latest hold question** (A-SPEC-768). Measured
47
+ 2026-10-11 in the SWE-bench Sphinx 11510 comparison: a Codex worker read 58 `sealed: true` answers as "pending"
48
+ because the response carried no next action, and never saw the second question of a twice-held request because the
49
+ response reported the spec's seal only. The response now carries `request { id, state, question?, reason?, ts? }`
50
+ (pending / held / granted / consumed / denied / revoked, from the approval queue) and one `nextAction` sentence; the
51
+ pending-approval hint ends with one `Agent:` line beside the unchanged operator lines.
52
+ - **An `@implements` list joined by `;`, `|`, `&`, `/` or `and` is diagnosed, not silently truncated** (A-SPEC-768.1).
53
+ `test_run` returns `anchorDiagnostics [{ file, line, separator, dropped, hint }]` for test files whose anchor list the
54
+ comma grammar does not read; attribution itself is unchanged.
55
+ - **A Codex `apply_patch` update is applied chunk by chunk in file order, as the tool applies it** (A-SPEC-768.2). A
56
+ context line that recurs earlier in the file (`def run(self)`, eight times in the measured case) no longer makes the
57
+ patch "unreadable"; each chunk is sought at or after the previous one (exact, then white-space-loose), `@@ ctx`
58
+ headers are sought first, and a patch that genuinely does not apply is refused by a sentence naming the file and the
59
+ chunk instead of "file_path missing". Supersedes A-SPEC-163.3 rule 4.
60
+ - **A quoted or escaped glob character is not a spelling of the `.ax` store** (A-SPEC-768.3). `rg "… .* …" | … |
61
+ xargs sh -c '… "$0"'` was refused as a protected-path write because the `.*` of a quoted regex counted as a glob that
62
+ could expand to `.ax`; a shell never expands a quoted or escaped glob. `echo .* && sh -c …` stays refused.
63
+ - **The publish playbook proves the GitHub README and badge sync in the release report.** Measured 2026-10-11:
64
+ step 6 had said "sync the badge too" since 0.35.13, yet the GitHub `.ax/badges/traced.svg` still showed v0.27.0's
65
+ figure and the GitHub README stopped at v0.35.10 for six releases — a sentence nobody had to prove. The step now
66
+ requires three lines in the release report (remote sha before → after and re-read match for README and badge, or
67
+ the exact SKIP reason) and carries the one-loop command for both files.
68
+ - **The background refresh child publishes why a lane failed** (A-SPEC-768.4). The freshness receipt gains
69
+ `failure { stage, reason }` (reason bounded to 300 characters) and `refreshSemanticVectors` carries the embedder's
70
+ message as `detail`; a successful run writes no `failure`.
71
+
8
72
  ## [0.35.16] - 2026-10-08
9
73
 
10
74
  ### Added
package/README.md CHANGED
@@ -9,8 +9,8 @@
9
9
  <!-- holmes-kit:attest:begin -->
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
- **448/454** source files (98.6%) trace to an approved spec · **756/819** approved A-SPECs (92.3%) are anchored from code.
13
- Measured at `13ef32c36276` (specs `sha256:613dcd17da1a`) — reproduce with `holmes-kit attest`.
12
+ **439/441** source files (99.5%) trace to an approved spec · **769/832** approved A-SPECs (92.4%) are anchored from code.
13
+ Measured at `32936217f72e` (specs `sha256:889a6e38d4b1`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
@@ -23,6 +23,8 @@ Measured at `13ef32c36276` (specs `sha256:613dcd17da1a`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **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.
27
+ - **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.
26
28
  - **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.
27
29
  - **The analysis names the file a change still has to create** *(new in 0.35.15)*: with `changedFiles` given, `maintenance_analyze` reports under `impacts.missingNewFiles` every relative import a changed TypeScript/JavaScript file newly introduces that resolves to nothing — the importing file, the specifier and the candidate paths. Deterministic and read-only. On two unseen windows of a public TypeScript monorepo every naming was a file the change did create (precision 1.000), covering 78–86% of the not-yet-existing files an incomplete change set was missing. Only uncommitted changes in a git repository; other languages, bare package names and path aliases are not read.
28
30
  - **ES-module TypeScript projects get their import graph** *(new in 0.35.14 — fix)*: a specifier written `./x.js` for a `x.ts` source (the ESM convention) now resolves, where it used to emit no edge at all — on a public TypeScript monorepo the graph went from 3 import edges to 4,628 of 6,854 import relations. Extensionless projects are unchanged. The cycle ratchet sees the same edges. Workspace package names are still unresolved, and the graded impact list does not yet use import edges.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 68181d77-muyuet0q
1
+ 313705f8-mv4rnlmn
@@ -205,6 +205,10 @@ async function runWatch(root, io, actor, opts = {}) {
205
205
  if (!idleAnnounced) {
206
206
  io.print(exports.WATCH_IDLE);
207
207
  idleAnnounced = true;
208
+ // @implements A-SPEC-770 — once per idle announcement: the refusals this surface does not list, by count.
209
+ const footer = (0, approve_1.outsideInboxFooter)((0, approval_queue_1.refusalsOutsideInbox)(root));
210
+ if (footer !== null)
211
+ io.print(footer);
208
212
  }
209
213
  // No reset of `lastPresented` here (round-3): the top-of-pass prune above already intersects
210
214
  // it with the current pending set every pass, so on an empty queue it becomes empty before it
@@ -57,10 +57,17 @@ export declare function staleView(flags: Record<string, unknown>): {
57
57
  ttlMs: number;
58
58
  showAll: boolean;
59
59
  } | null;
60
+ /**
61
+ * @implements A-SPEC-770 — the one line an inbox screen ends with when this machine's refusal log holds open requests
62
+ * the screen does not list (A-SPEC-563.1 keeps gate refusals out of the inbox; A-SPEC-563.2 / A-SPEC-690 let
63
+ * `approve --grant <id>` reach them). A count and two commands — never a target. `null` when there is nothing to say.
64
+ * @implements A-SPEC-770.1 — the grant command is spelled with its flag: a positional id is refused by the CLI.
65
+ */
66
+ export declare function outsideInboxFooter(outside: number | undefined): string | null;
60
67
  export declare function renderPending(state: QueueState, view?: {
61
68
  staleHours: number;
62
69
  showAll: boolean;
63
- }): string;
70
+ }, outside?: number): string;
64
71
  /**
65
72
  * @implements A-SPEC-262.1
66
73
  * What a decision line must say. Round-1: `✓ approved — valid until <expires>` named NOTHING, so an index
@@ -39,6 +39,7 @@ exports.revokeGrant = revokeGrant;
39
39
  exports.denyRequest = denyRequest;
40
40
  exports.holdRequest = holdRequest;
41
41
  exports.staleView = staleView;
42
+ exports.outsideInboxFooter = outsideInboxFooter;
42
43
  exports.renderPending = renderPending;
43
44
  exports.subjectCells = subjectCells;
44
45
  exports.subjectRoom = subjectRoom;
@@ -86,7 +87,7 @@ const MAX_TTL_MINUTES = 7 * 24 * 60;
86
87
  const DEFAULT_RATIONALE = 'approved via holmes-kit approve';
87
88
  const findPending = (root, id) => {
88
89
  // @implements A-SPEC-576.1 — RESOLUTION reads everything; the human's LIST reads decisions only.
89
- // The inbox filter hides gate refusals from the screen, but `approve <id>` must still find one:
90
+ // The inbox filter hides gate refusals from the screen, but `approve --grant <id>` must still find one:
90
91
  // the fallback below only holds entries written after the REQ-563 split, so anything refused
91
92
  // before it lives in the queue alone. Filtering here would cut the out-of-band approval path the
92
93
  // deny message itself promises.
@@ -345,17 +346,34 @@ function staleView(flags) {
345
346
  return null;
346
347
  return { ttlMs: hours * 3_600_000, showAll: flags.all === true };
347
348
  }
348
- function renderPending(state, view) {
349
+ /**
350
+ * @implements A-SPEC-770 — the one line an inbox screen ends with when this machine's refusal log holds open requests
351
+ * the screen does not list (A-SPEC-563.1 keeps gate refusals out of the inbox; A-SPEC-563.2 / A-SPEC-690 let
352
+ * `approve --grant <id>` reach them). A count and two commands — never a target. `null` when there is nothing to say.
353
+ * @implements A-SPEC-770.1 — the grant command is spelled with its flag: a positional id is refused by the CLI.
354
+ */
355
+ function outsideInboxFooter(outside) {
356
+ if (!outside || outside <= 0)
357
+ return null;
358
+ // `◆` rather than the `◇` the spec sketched: §13 (approve-corpus) admits only the template's own glyphs on a decision
359
+ // row, and U+25C7 is of ambiguous width while U+25C6 is already furniture of this screen.
360
+ return `◆ ${outside} refusal(s) on this machine are outside this inbox (shell/gate refusals) — list them: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --refusals · grant one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>`;
361
+ }
362
+ function renderPending(state, view, outside) {
363
+ const withFooter = (lines) => {
364
+ const footer = outsideInboxFooter(outside);
365
+ return (footer === null ? lines : [...lines, footer]).join('\n');
366
+ };
349
367
  if (state.pending.length === 0) {
350
368
  // Round-7: this early return made the malformed-line row below UNREACHABLE in exactly the case
351
369
  // it exists for — a wholly corrupted queue printed "no requests waiting" and exited 0, which is
352
370
  // what an agent would see after destroying it. approval-queue.ts promises the opposite:
353
371
  // "an empty-looking queue must be distinguishable from a corrupted one".
354
372
  if (state.malformedLines > 0) {
355
- return ['No requests awaiting approval.',
356
- `(${state.malformedLines} unreadable line(s) in the queue — check for corruption)`].join('\n');
373
+ return withFooter(['No requests awaiting approval.',
374
+ `(${state.malformedLines} unreadable line(s) in the queue — check for corruption)`]);
357
375
  }
358
- return 'No requests awaiting approval.';
376
+ return withFooter(['No requests awaiting approval.']);
359
377
  }
360
378
  const lines = [`◆ ${state.pending.length} request(s) awaiting approval`, ''];
361
379
  // @implements A-SPEC-507.1 — the LIST VIEW sorts newest-activity-first and folds stale entries
@@ -396,7 +414,7 @@ function renderPending(state, view) {
396
414
  }
397
415
  if (state.malformedLines > 0)
398
416
  lines.push(`(${state.malformedLines} unreadable line(s) in the queue — check for corruption)`);
399
- return lines.join('\n');
417
+ return withFooter(lines);
400
418
  }
401
419
  /**
402
420
  * @implements A-SPEC-262.1
@@ -476,7 +494,8 @@ function renderRefusals(refusals, limit = 20) {
476
494
  lines.push(`${(0, screen_safe_1.rowField)(r.id, 20)} ${(0, screen_safe_1.rowField)(r.kind, screen_safe_1.KIND_COLS)} ${(0, screen_safe_1.rowField)(r.target, 40)}`);
477
495
  lines.push(` \u2502 ${(0, screen_safe_1.rowField)(r.why, 66)} ${(0, screen_safe_1.rowField)(r.ts, 24)}`);
478
496
  }
479
- lines.push('', `decide one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve <id>`);
497
+ // @implements A-SPEC-770.1 — `--grant <id>`: the positional form this line named since 2026-09-06 is refused.
498
+ lines.push('', `decide one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>`);
480
499
  return lines.join('\n');
481
500
  }
482
501
  function renderNonTtyHint(state) {
@@ -530,7 +549,7 @@ function renderNonTtyHint(state) {
530
549
  */
531
550
  async function runInteractive(root, io, actor) {
532
551
  const state = (0, approval_queue_1.readQueue)(root);
533
- io.print(renderPending(state));
552
+ io.print(renderPending(state, undefined, (0, approval_queue_1.refusalsOutsideInbox)(root))); // @implements A-SPEC-770
534
553
  if (state.pending.length === 0)
535
554
  return;
536
555
  const grantDefault = (p) => {
@@ -712,7 +712,11 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
712
712
  try {
713
713
  const report = (0, runtime_binding_1.runtimeBindingStatus)(runtimeRegistry, target ?? process.cwd());
714
714
  const s = report.selection;
715
- if (report.conflicts.length === 0) {
715
+ // @implements A-SPEC-769.6 — the identity is the ROUTER's: conferred when the receipt rows under the registry
716
+ // directory are intact, whatever a settings or workspace wiring row says (those are reported on their own rows
717
+ // and on the `runtime binding` line). Before: any receipt conflict withheld it, and an edited user settings file
718
+ // made doctor call the intact router "not this install's server" (measured 2026-10-12).
719
+ if (report.router === 'intact') {
716
720
  const script = (h, e) => path.join(path.dirname(runtimeRegistry), `${h}-${e}.js`);
717
721
  routed = { script, command: (h, e) => (0, runtime_binding_1.runtimeHookCommand)(runtimeRegistry, h, e),
718
722
  mcp: (h, e) => ['claude', 'codex', 'antigravity'].includes(h) && e?.command === process.execPath
@@ -737,8 +741,16 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
737
741
  catch { /* no build id */ }
738
742
  own = `; doctor runs from ${packageRoot} (build ${ownBuild}); sessions routed by this registry load the package named first`;
739
743
  }
744
+ // @implements A-SPEC-769.3 — drift outside the registry directory is named, not counted as a conflict: the routed
745
+ // identity above is conferred on an intact router, and the line says which operator-owned files changed and which
746
+ // receipt rows belong to a workspace that no longer exists.
747
+ const drift = report.drift ?? [];
748
+ const changedSinceInstall = drift.filter((d) => d.kind === 'operator-config').map((d) => d.path);
749
+ const staleRows = drift.filter((d) => d.kind === 'stale-workspace').map((d) => d.path);
740
750
  add('runtime binding', report.conflicts.length ? 'FAIL' : 'WARN', `${s.mode}: workspace=${s.workspaceRoot}; package=${s.packageRoot}; build=${s.buildId}${own}; specs=${s.specsRoot}; live activation unverified`
741
- + (report.conflicts.length ? `; ${report.conflicts.join('; ')}` : ''), 'Use runtime-binding status and setup --dry-run to inspect routed wiring. Native hook trust and enable state remain operator-controlled.');
751
+ + (report.conflicts.length ? `; ${report.conflicts.join('; ')}` : '')
752
+ + (changedSinceInstall.length ? `; changed since installation (operator-owned, still routed): ${changedSinceInstall.join(', ')}` : '')
753
+ + (staleRows.length ? `; stale receipt rows (workspace gone): ${staleRows.join(', ')}` : ''), 'Use runtime-binding status and setup --dry-run to inspect routed wiring. Native hook trust and enable state remain operator-controlled.');
742
754
  // @implements A-SPEC-751.4 — a source checkout whose sessions are routed to another package: say whether the
743
755
  // hooks it builds are the hooks those sessions run. A consumer project holds no package source and gets no row.
744
756
  const checkoutRoot = [target ?? process.cwd(), packageRoot].find((candidate) => {
@@ -214,9 +214,12 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
214
214
  --dry-run print the diff, write nothing
215
215
  --remove remove holmes-kit wiring (holmes-owned entries only)
216
216
  --force re-wire an already-wired target (requires HOLMES_APPROVAL)
217
- --autonomy grant autonomous spec approval (low-risk only; governance-critical
218
- still ask you). Non-interactive: requires HOLMES_APPROVAL. At a TTY,
219
- init asks instead. Off is default; turn off with --no-autonomy.
217
+ --autonomy grant autonomous spec approval (low-risk only; high-risk, architecture
218
+ and gate specs still ask you). This explicit flag is the
219
+ non-interactive spelling: never prompted, even at a terminal; it needs
220
+ an out-of-band HOLMES_APPROVAL of kind "autonomy-grant". To be ASKED,
221
+ run init at a terminal WITHOUT --autonomy. Off is default;
222
+ --no-autonomy keeps it off.
220
223
  --no-autonomy keep every spec approval human (default)
221
224
 
222
225
  holmes-kit ledger rechain re-chain forked ledger files against the committed mainline
@@ -999,7 +1002,9 @@ async function main(argv) {
999
1002
  const queueOpts = stale ? { now: Date.now(), ttlMs: stale.ttlMs } : undefined;
1000
1003
  const listView = stale ? { staleHours: stale.ttlMs / 3_600_000, showAll: stale.showAll } : undefined;
1001
1004
  if (flags.list) {
1002
- process.stdout.write(renderPending(readQueue(root, queueOpts), listView) + '\n');
1005
+ // @implements A-SPEC-770 — the list ends with the count of refusals outside it.
1006
+ const { refusalsOutsideInbox } = require('../governance/approval-queue');
1007
+ process.stdout.write(renderPending(readQueue(root, queueOpts), listView, refusalsOutsideInbox(root)) + '\n');
1003
1008
  return 0;
1004
1009
  }
1005
1010
  // @implements A-SPEC-650 — the whole picture, read-only; the list above stays script-clean.
@@ -570,7 +570,9 @@ function runInitUnguarded(opts) {
570
570
  if (opts.autonomy === true && !opts.autonomyInteractive
571
571
  && !(0, risk_gate_1.approvalCovers)(opts.approval, { kind: 'autonomy-grant', target: opts.target }, new Date().toISOString())) {
572
572
  return { ok: false, exitCode: 2, changes, messages: [
573
- 'Enabling autonomous spec approval needs a human: answer the interactive prompt at a terminal, or supply an out-of-band approval.',
573
+ // @implements A-SPEC-769.1 — the flag is never prompted (X1, 2026-10-12: the old line sent the operator to a prompt
574
+ // that does not open with the flag).
575
+ 'Enabling autonomous spec approval needs a human: --autonomy is the non-interactive spelling and is never prompted, even at a terminal. Run init at a terminal WITHOUT --autonomy to be asked, or supply an out-of-band approval.',
574
576
  `Set HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' (scoped approvals need kind "autonomy-grant") and re-run with --autonomy.`,
575
577
  ] };
576
578
  }
@@ -14,4 +14,9 @@ export declare function promptAgentSelection(availableAgents?: readonly Agent[],
14
14
  * Non-TTY returns false (leave HITL); the caller does not treat that as an interactive answer.
15
15
  * Default is NO — autonomy is opt-in.
16
16
  */
17
+ /**
18
+ * @implements A-SPEC-769.1 — what the prompt says matches the grader (X1, 2026-10-12: the old text said REQ/H-SPEC
19
+ * "ALWAYS ask", while A-SPEC-587 seals an upstream autonomously when every A-SPEC beneath it is low-risk).
20
+ */
21
+ export declare const AUTONOMY_PROMPT_TEXT: string;
17
22
  export declare function promptAutonomy(): Promise<boolean>;
@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.AUTONOMY_PROMPT_TEXT = void 0;
36
37
  exports.parseAgentList = parseAgentList;
37
38
  exports.promptAgentSelection = promptAgentSelection;
38
39
  exports.promptAutonomy = promptAutonomy;
@@ -157,15 +158,22 @@ async function promptAgentSelection(availableAgents = agents_1.AGENTS, currentWi
157
158
  * Non-TTY returns false (leave HITL); the caller does not treat that as an interactive answer.
158
159
  * Default is NO — autonomy is opt-in.
159
160
  */
161
+ /**
162
+ * @implements A-SPEC-769.1 — what the prompt says matches the grader (X1, 2026-10-12: the old text said REQ/H-SPEC
163
+ * "ALWAYS ask", while A-SPEC-587 seals an upstream autonomously when every A-SPEC beneath it is low-risk).
164
+ */
165
+ exports.AUTONOMY_PROMPT_TEXT = '\n 🔑 Autonomous spec approval\n'
166
+ + ' The agent may self-approve LOW-RISK specs (tests, benign changes). High-risk and irreversible\n'
167
+ + ' specs (C-SPEC/ADR, gate/security/architecture files, root-only or unbounded Files to Touch)\n'
168
+ + ' still ask you; a REQ or H-SPEC seals on its own only when every A-SPEC beneath it is low-risk,\n'
169
+ + ' and a REQ never admitted through requirement_triage always asks. You can turn this off\n'
170
+ + ' anytime: holmes-kit autonomy off.\n';
160
171
  async function promptAutonomy() {
161
172
  if (!process.stdin.isTTY || !process.stdout.isTTY)
162
173
  return false;
163
174
  return new Promise((resolve) => {
164
175
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
165
- process.stdout.write('\n 🔑 Autonomous spec approval\n'
166
- + ' The agent may self-approve LOW-RISK specs (tests, benign changes). Governance-critical,\n'
167
- + ' high-risk and irreversible specs (REQ/H-SPEC/C-SPEC, gate/security/architecture) ALWAYS\n'
168
- + ' ask you. You can turn this off anytime: holmes-kit autonomy off.\n');
176
+ process.stdout.write(exports.AUTONOMY_PROMPT_TEXT);
169
177
  rl.question(' Grant autonomous spec approval for this project? [y/N] ', (ans) => {
170
178
  rl.close();
171
179
  resolve(/^\s*y(es)?\s*$/i.test(ans));
@@ -36,6 +36,11 @@ export declare function registryOwnedWiring(file: string, registryPath?: string)
36
36
  export declare function runtimeBindingStatus(registryPath: string, workspace: string): {
37
37
  selection: import("../runtime/binding").RuntimeSelection;
38
38
  conflicts: string[];
39
+ drift: {
40
+ path: string;
41
+ kind: "operator-config" | "stale-workspace";
42
+ }[];
43
+ router: "changed" | "intact";
39
44
  activation: "unverified";
40
45
  };
41
46
  export declare function runRuntimeBinding(opts: RuntimeBindingOptions): unknown;
@@ -162,11 +162,30 @@ function registryOwnedWiring(file, registryPath) {
162
162
  return registryWiringOwnership(file, registryPath).owned;
163
163
  }
164
164
  function runtimeBindingStatus(registryPath, workspace) {
165
- const selection = (0, binding_1.selectRuntime)((0, binding_1.readRuntimeRegistry)(registryPath), { cwd: workspace });
165
+ const registry = (0, binding_1.readRuntimeRegistry)(registryPath);
166
+ const selection = (0, binding_1.selectRuntime)(registry, { cwd: workspace });
166
167
  const manifest = readOptional(path.join(path.dirname(registryPath), 'installation.json'));
167
168
  const conflicts = [];
168
- if (manifest === null)
169
+ // @implements A-SPEC-769.3 — a row that differs from the receipt is classified, not only counted. Measured 2026-10-12
170
+ // (X1): every router file under the registry directory matched, and the "conflicts" were operator-owned configuration
171
+ // that changes by design (hook trust state, Claude settings) plus six rows of a removed temporary workspace — on which
172
+ // doctor refused the routed identity and called the intact router "not this install's server".
173
+ // @implements A-SPEC-769.5 / A-SPEC-769.6 — what counts as operator drift is only what was MEASURED to change by
174
+ // design: the registry file (a dead binding is deleted by hand; the dispatcher reads the registry live) and the Codex
175
+ // USER config (Codex rewrites its `[projects.*]`, `[hooks.state.*]`, plugin and marketplace tables itself). Every
176
+ // other wiring file — Claude settings (A-SPEC-752.5/752.6: a digest cannot say which key changed, and some keys
177
+ // switch Holmes off), `.mcp.json`, the Codex hooks files, a project Codex config, the Antigravity files — keeps the
178
+ // receipt conflict. The ROUTER verdict is the receipt rows under the registry directory alone.
179
+ const drift = [];
180
+ const registryDir = path.dirname(registryPath);
181
+ const under = (dir, file) => { const rel = path.relative(dir, file); return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel); };
182
+ const workspaceRoots = registry.bindings.map((b) => b.workspaceRoot);
183
+ const codexUserConfig = (file) => path.basename(file) === 'config.toml' && path.basename(path.dirname(file)) === '.codex' && !workspaceRoots.some((w) => under(w, file));
184
+ let routerChanged = false;
185
+ if (manifest === null) {
169
186
  conflicts.push('No installation receipt; registry selection alone does not establish wiring');
187
+ routerChanged = true;
188
+ }
170
189
  else {
171
190
  const rows = document(manifest, 'installation.json').files;
172
191
  if (!Array.isArray(rows))
@@ -176,11 +195,30 @@ function runtimeBindingStatus(registryPath, workspace) {
176
195
  throw new Error('Invalid installation file record');
177
196
  const current = readOptional(row.path);
178
197
  // A-SPEC-752.5: the view's digest, or the whole file's for a row written before the view existed.
179
- if (current === null || (digest(wiringViewOf(row.path, current)) !== row.digest && digest(current) !== row.digest))
198
+ if (current !== null && (digest(wiringViewOf(row.path, current)) === row.digest || digest(current) === row.digest))
199
+ continue;
200
+ const registryFile = current !== null && path.resolve(row.path) === path.resolve(registryPath);
201
+ // 1. a router program (or the receipt's neighbours) under the registry directory: a conflict, and the router is changed.
202
+ if (under(registryDir, row.path) && !registryFile) {
180
203
  conflicts.push(`Wiring changed or incomplete: ${row.path}`);
204
+ routerChanged = true;
205
+ continue;
206
+ }
207
+ // 2./3. the registry file, or the Codex user config, present but changed: operator drift.
208
+ if (registryFile || (current !== null && codexUserConfig(row.path))) {
209
+ drift.push({ path: row.path, kind: 'operator-config' });
210
+ continue;
211
+ }
212
+ // 4. a missing file whose directory is gone: a stale row of a workspace that no longer exists.
213
+ if (current === null && !fs.existsSync(path.dirname(row.path))) {
214
+ drift.push({ path: row.path, kind: 'stale-workspace' });
215
+ continue;
216
+ }
217
+ // 5. everything else — a changed wiring file, or a living workspace that lost one: the receipt conflict as before.
218
+ conflicts.push(`Wiring changed or incomplete: ${row.path}`);
181
219
  }
182
220
  }
183
- return { selection, conflicts, activation: 'unverified' };
221
+ return { selection, conflicts, drift, router: routerChanged ? 'changed' : 'intact', activation: 'unverified' };
184
222
  }
185
223
  function runRuntimeBinding(opts) {
186
224
  if (opts.activateHooks !== undefined && (!Array.isArray(opts.activateHooks)
@@ -24,7 +24,7 @@ export declare const DECISION_KINDS: ReadonlySet<string>;
24
24
  * The line a refusal ends with to name its pending request and the operator command.
25
25
  * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
26
26
  */
27
- export declare function pendingRequestLine(id: string): string;
27
+ export declare function pendingRequestLine(id: string, kind?: string): string;
28
28
  export interface RefusalRecord {
29
29
  event: 'requested';
30
30
  id: string;
@@ -222,6 +222,12 @@ export declare function queueHint(root: string, req: {
222
222
  *
223
223
  * Measured 2026-09-19: `readRefusals` found req-9e92e52bd233 while `approve --grant` refused it.
224
224
  */
225
+ /**
226
+ * @implements A-SPEC-770 — how many open requests this machine's refusal log (and any pre-split queue row of a
227
+ * non-decision kind) holds that the inbox screen does not list. Information for a footer, never a lever: an
228
+ * unreadable store counts 0 (the list itself still renders as today).
229
+ */
230
+ export declare function refusalsOutsideInbox(root: string): number;
225
231
  export declare function grantableRequests(root: string): PendingRequest[];
226
232
  /**
227
233
  * @implements A-SPEC-690
@@ -45,6 +45,7 @@ exports.enqueueApprovalRequestDetailed = enqueueApprovalRequestDetailed;
45
45
  exports.appendQueueEvent = appendQueueEvent;
46
46
  exports.readQueue = readQueue;
47
47
  exports.queueHint = queueHint;
48
+ exports.refusalsOutsideInbox = refusalsOutsideInbox;
48
49
  exports.grantableRequests = grantableRequests;
49
50
  exports.openOccurrences = openOccurrences;
50
51
  exports.asPendingRequest = asPendingRequest;
@@ -96,8 +97,18 @@ exports.DECISION_KINDS = new Set([
96
97
  * The line a refusal ends with to name its pending request and the operator command.
97
98
  * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
98
99
  */
99
- function pendingRequestLine(id) {
100
- return `\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
100
+ function pendingRequestLine(id, kind) {
101
+ const command = `${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
102
+ // @implements A-SPEC-770 — a request outside the decision inbox (A-SPEC-563.1 routes gate refusals to the local
103
+ // refusal log) names the id-bearing command, because the bare command opens a screen that by design does not list
104
+ // it. Field report (jarvis, 2026-10-11): the operator ran the bare command, saw six old inbox requests, and the
105
+ // agent's shell command was refused again with the same id. A decision kind keeps the short line: it IS listed.
106
+ // @implements A-SPEC-770.1 — the id rides the `--grant` flag: the CLI refuses a positional id (`unexpected
107
+ // argument: req-…`, measured by the operator on 0.35.17 with the command this line used to name).
108
+ if (kind !== undefined && !exports.DECISION_KINDS.has(kind)) {
109
+ return `\n[승인 대기 ${id}] 운영자: ${command} --grant ${id} — 인박스 화면에는 뜨지 않는 거부입니다(${command} --refusals 로 조회)`;
110
+ }
111
+ return `\n[승인 대기 ${id}] 운영자: ${command}`;
101
112
  }
102
113
  const REFUSALS_FILE_RE = /^refusals\.([^.]+)\.jsonl$/;
103
114
  function refusalsFilename(replica) {
@@ -519,7 +530,7 @@ function queueHint(root, req, opts) {
519
530
  // @implements A-SPEC-564.2 — the hint is composed BEFORE the enqueue so the refusal record can
520
531
  // carry its own feedback cost: reasonBytes = the caller's base reason + this hint, i.e. the text
521
532
  // that actually re-enters the conversation. Observation only — nothing reads it on a gate path.
522
- const hint = denialLine + (opts?.pendingHint ? opts.pendingHint(id) : pendingRequestLine(id));
533
+ const hint = denialLine + (opts?.pendingHint ? opts.pendingHint(id) : pendingRequestLine(id, req.kind)); // @implements A-SPEC-770
523
534
  return enqueueApprovalRequest(root, { ...req, reasonBytes: (opts?.baseReasonBytes ?? 0) + hint.length })
524
535
  ? hint
525
536
  : denialLine;
@@ -537,6 +548,20 @@ function queueHint(root, req, opts) {
537
548
  *
538
549
  * Measured 2026-09-19: `readRefusals` found req-9e92e52bd233 while `approve --grant` refused it.
539
550
  */
551
+ /**
552
+ * @implements A-SPEC-770 — how many open requests this machine's refusal log (and any pre-split queue row of a
553
+ * non-decision kind) holds that the inbox screen does not list. Information for a footer, never a lever: an
554
+ * unreadable store counts 0 (the list itself still renders as today).
555
+ */
556
+ function refusalsOutsideInbox(root) {
557
+ try {
558
+ const inbox = new Set(readQueue(root).pending.map((p) => p.id));
559
+ return grantableRequests(root).filter((p) => !inbox.has(p.id)).length;
560
+ }
561
+ catch {
562
+ return 0;
563
+ }
564
+ }
540
565
  function grantableRequests(root) {
541
566
  const state = readQueue(root, { includeAllKinds: true });
542
567
  const seen = new Set(state.pending.map((p) => p.id));
@@ -185,6 +185,10 @@ function autonomyRuleMeaning(rule) {
185
185
  return 'the gate change does not declare its direction as tightens or wording';
186
186
  if (rule.startsWith('breaking-change-'))
187
187
  return rule === 'breaking-change-undeclared' ? 'breaking_change is not declared' : 'the breaking_change grade is not one the grader knows';
188
+ // @implements A-SPEC-769 — `upstream-has-human-aspec: <child id> — <child rule>` composes the child's own meaning.
189
+ const upstream = /^upstream-has-human-aspec: (\S+) — (.+)$/.exec(rule);
190
+ if (upstream)
191
+ return `an A-SPEC beneath it (${upstream[1]}) is the operator's to seal — ${autonomyRuleMeaning(upstream[2])}`;
188
192
  switch (rule) {
189
193
  case 'upstream-without-aspec': return 'no A-SPEC exists beneath it yet, so its scope is unknown';
190
194
  case 'upstream-has-human-aspec': return 'an A-SPEC beneath it is the operator\'s to seal';
@@ -209,7 +213,15 @@ function specApprovalAutonomyReason(spec, resolveParent, descendants) {
209
213
  const below = (descendants ?? []).filter((s) => s.type === 'A-SPEC');
210
214
  if (below.length === 0)
211
215
  return 'upstream-without-aspec'; // unknown scope stays human
212
- return below.every((a) => specApprovalAutonomyReason(a, resolveParent) === null) ? null : 'upstream-has-human-aspec';
216
+ // @implements A-SPEC-769 — the FIRST child that is the operator's, with its own rule: X1 (2026-10-12) handed a
217
+ // REQ and an H-SPEC to the operator over one A-SPEC's root-only Files to Touch, and the note said only that
218
+ // "an A-SPEC beneath it" was the operator's — neither the agent nor the operator could tell which, or why.
219
+ for (const a of below) {
220
+ const childRule = specApprovalAutonomyReason(a, resolveParent);
221
+ if (childRule !== null)
222
+ return `upstream-has-human-aspec: ${a.id} — ${childRule}`;
223
+ }
224
+ return null;
213
225
  }
214
226
  case 'C-SPEC':
215
227
  case 'ADR': // @implements A-SPEC-571.1 — a decision is the human's to seal
@@ -105,6 +105,24 @@ export declare function patchTargetsOf(text: string): PatchTarget[];
105
105
  * rule (below): its one place in the file, or no result.
106
106
  */
107
107
  export declare function applyPatchUpdate(original: string, hunk: string): string | null;
108
+ /**
109
+ * @implements A-SPEC-768.2
110
+ * The same application, with the reason when there is no result. Measured 2026-10-11 (SWE-bench Sphinx 11510, H0
111
+ * arm): a four-chunk Codex patch — two chunks context-only, one context line (`def run(self) -> list[Node]:`) occurring
112
+ * eight times earlier in the file — got no result under rule 4's "exactly once in the whole file", and the refusal
113
+ * said a file path was missing. The tool applies each chunk from where the previous one ended; so does this now:
114
+ * exact first, then white-space-loose, the FIRST match at or after the previous chunk. A `@@ ctx` header first seeks
115
+ * `ctx` the same way; an add-only chunk under such a header inserts directly after it. A kept line stays as the file
116
+ * has it. Supersedes A-SPEC-163.3 rule 4.
117
+ *
118
+ * @implements A-SPEC-163.3 (rules 1-3, 5-7: chunk grammar, ops, end-of-file, size), A-SPEC-163.4 — their rule 4 (one
119
+ * place in the whole file) is the part A-SPEC-768.2 replaces; everything else they pin still holds here.
120
+ */
121
+ export declare function applyPatchUpdateDetailed(original: string, hunk: string): {
122
+ result: string;
123
+ } | {
124
+ failure: string;
125
+ };
108
126
  /**
109
127
  * The file a raw path actually names.
110
128
  *