@feigi/fleet-ctl 0.0.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 (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,1391 @@
1
+ // Pins the #170 addition to run-merge-bot.md's step 4: dropping `in-progress`
2
+ // from every issue a merged PR closes. Same discipline as
3
+ // issue-tracker-prose.test.mjs — a positive match on a whole file is a
4
+ // vacuous pin, so this slices to step 4 alone before asserting.
5
+ //
6
+ // THE CEILING: this proves the phrase is PRESENT in step 4. It cannot prove
7
+ // the rule is not negated by a sentence added beside it, and it does not run
8
+ // the step — drop-merged-label.test.mjs owns the script's own behavior.
9
+ import { test } from "node:test";
10
+ import assert from "node:assert/strict";
11
+ import { execFileSync, spawnSync } from "node:child_process";
12
+ import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
13
+ import { tmpdir } from "node:os";
14
+ import { join } from "node:path";
15
+ import { between, paragraph, phrase } from "./prose-pin.mjs";
16
+
17
+ const REPO = join(import.meta.dirname, "..");
18
+ const DOC = readFileSync(join(REPO, "commands", "run-merge-bot.md"), "utf8");
19
+
20
+ // Bounded to step 4 alone: unbounded to EOF the slice runs through staleness,
21
+ // the no-undo audit and the watcher loop, and a mention of `in-progress`
22
+ // anywhere in those would satisfy the assertions with step 4 itself untouched.
23
+ function step4() {
24
+ const start = "4. `gh pr merge <pr> --merge`";
25
+ const at = DOC.indexOf(start);
26
+ assert.notEqual(at, -1, `'${start}' moved — update this test`);
27
+ const rest = DOC.slice(at + start.length);
28
+ const end = rest.indexOf("**Staleness fires");
29
+ assert.notEqual(end, -1, "step 4's end marker moved — update this test");
30
+ return start + rest.slice(0, end);
31
+ }
32
+
33
+ test("step 4 drops in-progress from every issue the merged PR closes", () => {
34
+ assert.match(step4(), /Drop `in-progress` from every issue this PR closes/);
35
+ assert.match(step4(), /drop-merged-label\.sh <pr> --apply/);
36
+ });
37
+
38
+ test("step 4 says a failed removal must be reported, never swallowed", () => {
39
+ assert.match(step4(), /a removal failed — report it as `label-drop-failed-#<issue>`, never swallow it/);
40
+ });
41
+
42
+ test("the drop runs only after the merge is confirmed, never before", () => {
43
+ assert.match(step4(), /call this only after the merge is confirmed/);
44
+ });
45
+
46
+ // #303: on `unknown` the runbook used to send the operator to `git stash list`
47
+ // alone, which is empty at rc 0 in two of the three states that produce
48
+ // `unknown` (measured: `chmod 000` on `refs/stash`, and on `logs/refs/stash`).
49
+ // Sliced to the audit section, same discipline as step4(): it pins the text to
50
+ // the section that has to carry it, so a later paragraph naming `refs/stash`
51
+ // somewhere else in the doc can never stand in for this one.
52
+ function noUndoAudit() {
53
+ const start = "## No-undo audit (before every rebase)";
54
+ const at = DOC.indexOf(start);
55
+ assert.notEqual(at, -1, `'${start}' moved — update this test`);
56
+ const rest = DOC.slice(at + start.length);
57
+ const end = rest.indexOf("**4. Take `main`'s side wholesale");
58
+ assert.notEqual(end, -1, "the audit section's end marker moved — update this test");
59
+ return rest.slice(0, end);
60
+ }
61
+
62
+ // THE CEILING: presence of the instruction, not its correctness. The paths are
63
+ // pinned as written — `--git-common-dir`, not `.git/` — because a linked
64
+ // worktree's `.git` is a file and `.git/refs/stash` reaches nothing there.
65
+ test("the `unknown` path sends the operator to both stash files, via the common dir", () => {
66
+ // The instruction is pinned by its rule, not by a tally of the causes: the
67
+ // sentence used to count them, and #482 added one, which is how a count
68
+ // written into prose goes stale.
69
+ assert.match(noUndoAudit(), /On `unknown` do not stop at that list: the causes git stays silent about leave it empty at rc 0/);
70
+ assert.match(noUndoAudit(), /c=\$\(git rev-parse --git-common-dir\)/);
71
+ assert.match(noUndoAudit(), /ls -l "\$c"\/refs\/stash "\$c"\/logs\/refs\/stash`/);
72
+ assert.match(noUndoAudit(), /cat "\$c"\/logs\/refs\/stash`/);
73
+ });
74
+
75
+ // #482: the cause whose whole shape is that the list did NOT come back empty —
76
+ // `git stash list` printed entries, then exited nonzero, and the audit answers
77
+ // `unknown` instead of the number it could have counted. The runbook has to
78
+ // carry both halves: that the state exists at all, since an operator who reads
79
+ // `unknown` as "the list was empty" goes looking for the wrong thing, and that
80
+ // git's own words are already on the audit's line, since the earlier
81
+ // instruction sends them to re-read a list whose stderr they have.
82
+ test("the `unknown` path names the cause where the list printed entries and then failed", () => {
83
+ assert.match(noUndoAudit(), /`git stash list` printed entries and then exited nonzero, so what it printed is short/);
84
+ assert.match(noUndoAudit(), /a corrupt loose object behind an entry that is not the tip does this, and the audit reports `unknown` there/);
85
+ assert.match(noUndoAudit(), /the audit's own line carries that text for you/);
86
+ });
87
+
88
+ // `----------` alone is under-inclusive: an unreadable logs/refs DIRECTORY
89
+ // (`chmod 000 .git/logs/refs`) produces the same `unknown`, but `ls` fails
90
+ // before it prints a mode column — `ls: .git/logs/refs/stash: Permission
91
+ // denied`, with `refs/stash` beside it at a healthy `-rw-r--r--`. Both halves
92
+ // of the tell are pinned, or the second silently rots back out.
93
+ test("the fault tell covers a Permission denied from `ls`, not only a `----------` mode", () => {
94
+ assert.match(noUndoAudit(), /a mode of `----------` on either, or a `Permission denied` from `ls` itself, is the fault,/);
95
+ });
96
+
97
+ test("the `unknown` path warns that a missing refs/stash file is not an empty stash", () => {
98
+ assert.match(noUndoAudit(), /A missing `refs\/stash` file is not an empty stash: `git gc` packs it into `packed-refs`/);
99
+ });
100
+
101
+ // Whitespace-normalized so a same-words reflow of the audit paragraph cannot
102
+ // false-red these two pins: they hold the two longest spans in this file, and
103
+ // the paragraph is currently one unwrapped line, so a future hard-wrap landing
104
+ // inside a span is the live hazard. Scoped to the #437 pins below on purpose —
105
+ // converting the file's other pins is a separate change.
106
+ const flat = (s) => s.replace(/\s+/g, " ");
107
+
108
+ // #437 item 3: of the four `unknown` causes, the stash-object-missing one is
109
+ // the one `git stash list` itself refuses to stay silent about. Measured, git
110
+ // 2.50.1: `stash list` against a repo with `rm .git/objects/<stash-sha>`
111
+ // prints nothing on stdout but exits 1 with stderr `fatal: bad object
112
+ // refs/stash`, while the other three causes (unreadable ref file, unreadable
113
+ // reflog, absent ref beside a live reflog) are each rc 0 with no stdout and no
114
+ // stderr. The doc names the cause rather than counting to it: this paragraph
115
+ // already spends "the fourth" on the absent-ref/live-reflog case, so an
116
+ // ordinal here would bind the same word to two members of the same set.
117
+ test("the `unknown` path says the missing-object cause names itself in git's own stderr", () => {
118
+ assert.match(
119
+ flat(noUndoAudit()),
120
+ /The missing-object cause is the one git is not silent about: `git stash list`'s own stderr there already ends `fatal: bad object refs\/stash`/,
121
+ );
122
+ });
123
+
124
+ // #437 item 1: `git show refs/stash` recovers the entry in the states where
125
+ // `ls -l`/`cat` come back with nothing — measured, git 2.50.1, over the twelve
126
+ // states {staged, unstaged} x {loose, packed} x {reflog unreadable, reflog
127
+ // blank, reflog removed}: `git show refs/stash` printed the `WIP on <branch>`
128
+ // label in all twelve, but printed NO diff in all six staged ones, because the
129
+ // stash tree equals the index-commit parent and the default `--cc` combined
130
+ // diff suppresses every hunk. `git stash show -p refs/stash` printed the hunk
131
+ // in all twelve, so it is the command the doc names for the content.
132
+ // Both fail only where the ref FILE is the broken one — chmod 000 (`git show`
133
+ // rc 128 `ambiguous argument`, `git stash show -p` rc 1) or `printf
134
+ // 'not-a-sha' > refs/stash` (both, after `ignoring broken ref`) — and measured
135
+ // in both of those the reflog is untouched and still names the stash SHA as
136
+ // its second field, where `git stash show -p <that sha>` printed the hunk
137
+ // staged or not, while `git show <that sha>` again printed none when staged.
138
+ // #1055 added the third member of that enumeration: measured, git 2.50.1, `rm
139
+ // refs/stash` with no `packed-refs` fails both the same way (`ambiguous
140
+ // argument` / `refs/stash is not a valid reference`) while the reflog still
141
+ // names the SHA, and after `git pack-refs --all` both succeed at rc 0 — so the
142
+ // clause enumerates the UNPACKED absence, not absence as such.
143
+ test("the `unknown` path names git show refs/stash as the recovery when the file reads come back empty", () => {
144
+ assert.match(
145
+ flat(noUndoAudit()),
146
+ /`git show refs\/stash` still resolves the ref whether loose or packed, printing the `WIP on <branch>` label/,
147
+ );
148
+ assert.match(
149
+ flat(noUndoAudit()),
150
+ /it prints no diff beside that label when the stashed change was staged before `git stash`, so read the content with `git stash show -p refs\/stash`, which prints the hunk either way/,
151
+ );
152
+ assert.match(
153
+ flat(noUndoAudit()),
154
+ /Both fail only where the ref FILE is itself the broken one — unreadable, holding text that is not a SHA, or gone with nothing in `packed-refs` — and there the SHA `cat` already printed, in the reflog's second field, is what `git stash show -p <that sha>` recovers instead/,
155
+ );
156
+ });
157
+
158
+ // #1055: the fallback above IS a SHA `cat` printed, so it is unavailable in the
159
+ // double fault — where the premise clause ("`cat` denied") fires and the ref is
160
+ // also unresolvable — and the paragraph went on offering it there. Measured,
161
+ // git 2.50.1, all three shapes (`chmod 000` on `refs/stash` AND
162
+ // `logs/refs/stash`; `printf 'not-a-sha' > refs/stash` plus `chmod 000` on
163
+ // `logs/refs/stash`; `rm refs/stash` with no `packed-refs` plus `chmod 000`
164
+ // on `logs/refs`): `git stash list` empty at rc 0, `git show refs/stash`
165
+ // `ambiguous argument`, `git stash show -p refs/stash` `refs/stash is not a
166
+ // valid reference`, and `cat` rc 1 printing no SHA to fall back on.
167
+ //
168
+ // The recovery SPLITS by shape, measured, not inferred — an earlier draft
169
+ // claimed one outcome for all three, which is the defect #1055 fixed here.
170
+ // `chmod 644` on the two files (`chmod 755` on an unsearchable `logs/refs`)
171
+ // puts the entry straight back in `git stash list` ONLY where the ref FILE's
172
+ // own content survived — the both-unreadable shape. Where the ref file's
173
+ // content is itself gone or garbage, restoring the reflog's mode only makes
174
+ // `cat` print the SHA again; `git stash list` stays empty at rc 0 until the
175
+ // ref is re-pointed by hand: `git update-ref refs/stash <sha>` succeeds
176
+ // directly once the file is gone, but on garbage text it answers `fatal: …
177
+ // reference broken` even with `-d` — measured — so the file has to be `rm`'d
178
+ // first either way. Once re-pointed, both land the entry as a NEW
179
+ // `stash@{0}` (empty subject, the update's own reflog line) with the
180
+ // recovered one pushed down to `stash@{1}`, never restored to its original
181
+ // slot — measured with `git stash list` before and after `git update-ref`.
182
+ //
183
+ // Failing all of that, `git fsck` prints `dangling commit <sha>` per stash
184
+ // entry — 3 of 3 entries in a three-stash fixture, and still with every
185
+ // object packed by `repack -ad` — at rc 10 in the unreadable-ref shape while
186
+ // printing them, and still at rc 0 with both files simply deleted and
187
+ // nothing in `packed-refs`. `git stash show -p <that sha>` printed the hunk
188
+ // there, including for an entry staged before `git stash`, refusing a
189
+ // non-stash dangling commit with `is not a stash-like commit`. Its measured
190
+ // limits are why the doc calls it a lead: fsck hands back no `stash@{N}`,
191
+ // and an entry dropped by `git stash drop` is dangling with the same `WIP on
192
+ // <branch>:` subject and the same rc 0 from `git stash show -p` as a live
193
+ // one.
194
+ //
195
+ // `git gc --prune=now` is deliberately NOT mentioned either way: measured, it
196
+ // dies `fatal: bad object refs/stash` / `failed to run repack` at rc 128 in the
197
+ // unreadable-ref shape, so the obvious "recover before something prunes it"
198
+ // warning would be false for the shape it reads as being about.
199
+ //
200
+ // Six claims pinned separately, never one span: the STATE (now three
201
+ // shapes), the permission fix's SCOPE (one shape names it back outright),
202
+ // the re-point recovery the other two shapes need instead, the stash@{0}/
203
+ // stash@{1} shape that re-point leaves behind, the fsck lead, and the lead's
204
+ // unreliability — each rots independently. Dropping the state turns the
205
+ // caveat into unscoped advice; dropping the last one promotes a lead to a
206
+ // listing, which is the specific rewrite this paragraph's history predicts;
207
+ // widening the permission fix back across all three shapes silently
208
+ // reintroduces the exact false promise #1055 corrected, which is why its
209
+ // scope is pinned as a short span rather than folded into the fix
210
+ // instruction's own sentence.
211
+ test("the double fault leaves no ref-based recovery, and names the mode fix, the re-point fallback and the fsck lead in their place", () => {
212
+ assert.match(
213
+ flat(noUndoAudit()),
214
+ /That fallback is a SHA `cat` printed, so it is gone where the reflog is the denied read too — both files unreadable, `refs\/stash` holding text that is not a SHA while the reflog cannot be read, or `refs\/stash` gone with nothing in `packed-refs` while the reflog cannot be read — and nothing ref-based recovers there/,
215
+ );
216
+ assert.match(
217
+ flat(noUndoAudit()),
218
+ /Only the both-files-unreadable shape then has `git stash list` name the entry again on its own/,
219
+ );
220
+ assert.match(
221
+ flat(noUndoAudit()),
222
+ /so restoring the reflog's mode only unlocks the SHA `cat` now prints; `git stash list` stays empty at rc 0 until you clear the broken ref and re-point it yourself/,
223
+ );
224
+ assert.match(
225
+ flat(noUndoAudit()),
226
+ /`git update-ref refs\/stash <that sha>` works directly once `refs\/stash` is already gone; where it instead holds garbage text, `git update-ref` refuses that too \(`reference broken`, even with `-d`\) until you `rm` the file first/,
227
+ );
228
+ assert.match(
229
+ flat(noUndoAudit()),
230
+ /Either path is measured to list the entry again as a new `stash@\{0\}` \(an empty-subject entry the update itself adds\), pushing the recovered one down to `stash@\{1\}` rather than restoring it to its original slot/,
231
+ );
232
+ assert.match(
233
+ flat(noUndoAudit()),
234
+ /`git fsck` still prints a `dangling commit <sha>` line per stash entry, objects loose or packed/,
235
+ );
236
+ assert.match(
237
+ flat(noUndoAudit()),
238
+ /refusing anything that is not a stash \(`is not a stash-like commit`\)/,
239
+ );
240
+ assert.match(
241
+ flat(noUndoAudit()),
242
+ /Treat it as a lead, not a listing: no `stash@\{N\}` comes back with it, and an entry someone dropped on purpose is indistinguishable from a live one/,
243
+ );
244
+ assert.match(flat(noUndoAudit()), /Restore read permission where the mode is yours to fix/);
245
+ });
246
+
247
+ // #376 added a fourth cause whose `ls -l` signature is the OPPOSITE of the
248
+ // three above — the ref file is gone rather than unreadable, so neither the
249
+ // `----------` mode nor the `Permission denied` tell fires, and an operator
250
+ // reading only those two concludes the audit was wrong and rebases. The
251
+ // reflog beside it is what makes the entries recoverable, so the instruction
252
+ // has to name both halves: the signature, and that the SHAs are the recovery.
253
+ //
254
+ // Two matches, not one on the whole sentence, and `\s+` between the words: a
255
+ // single literal spanning the clause reds on a pure reflow or on bolding
256
+ // `fourth cause` in place, neither of which changes what it guards. Measured —
257
+ // the first draft of this pin did exactly that.
258
+ test("the fourth cause — an absent refs/stash beside a live reflog — is named with its own ls signature", () => {
259
+ assert.match(noUndoAudit(), /`No\s+such\s+file\s+or\s+directory`\s+for\s+`refs\/stash`\s+alone/);
260
+ assert.match(noUndoAudit(), /recover\s+from\s+the\s+SHAs\s+`cat`\s+prints,\s+do\s+not\s+rebase\s+over\s+it/);
261
+ });
262
+
263
+ // #149: step 1 used to rebase locally and `git push --force-with-lease`,
264
+ // denied unpredictably by the auto-mode classifier — 2 allowed / 2 denied on
265
+ // byte-identical invocations in one session — sometimes stranding a rebased
266
+ // head that never reached the remote, so `gh pr merge` landed the stale one.
267
+ // settings.json has carried an `autoMode.allow` entry for that exact command
268
+ // since 1dadc5d, so adding one is not the fix for a denial here; the classifier
269
+ // judges per invocation. Step 1 now rebases server-side first: an API call, not
270
+ // a push, so the classifier is never consulted for it.
271
+ //
272
+ // THE CEILING: same as step4() above — presence, not correctness, and not
273
+ // that the fallback runs the way it's written.
274
+ function step1() {
275
+ const start = "1. If the PR is behind";
276
+ const at = DOC.indexOf(start);
277
+ assert.notEqual(at, -1, `'${start}' moved — update this test`);
278
+ const rest = DOC.slice(at + start.length);
279
+ const end = rest.indexOf("2. Watch checks settle");
280
+ assert.notEqual(end, -1, "step 1's end marker moved — update this test");
281
+ return start + rest.slice(0, end);
282
+ }
283
+
284
+ test("step 1 rebases server-side first, not with a local force-push", () => {
285
+ assert.match(step1(), /`gh pr update-branch <pr> --rebase`/);
286
+ assert.match(step1(), /no local git command runs/);
287
+ });
288
+
289
+ test("step 1 falls back to a local, unpushed rebase when the server-side path can't run", () => {
290
+ assert.match(step1(), /a real conflict, or `allow_update_branch` off/);
291
+ assert.match(step1(), /Rebase locally, for verification only — this rebase never needs to reach the remote/);
292
+ assert.match(step1(), /Report this path as `rebase-fallback-#<pr>`/);
293
+ });
294
+
295
+ // #408: a controller once told its merge bot to prove a post-rebase stale
296
+ // worktree safe with `git cherry origin/main HEAD` — trivially `+` for any
297
+ // unmerged PR, since main never had the PR's commits merged rebase or not.
298
+ // Measured directly (two local clones, one simulating the server-side rebase
299
+ // the other never sees) before writing this: origin/<branch> reads `-`
300
+ // (nothing unique), origin/main reads `+` on the identical stale HEAD.
301
+ test("step 1 names the correct upstream for proving a post-rebase worktree stale but safe", () => {
302
+ assert.match(step1(), /`git cherry origin\/<branch> HEAD`/);
303
+ assert.match(step1(), /\*\*not\*\* `git cherry origin\/main HEAD`/);
304
+ });
305
+
306
+ // #447. The probe above told the bot to run `git cherry` and then stopped:
307
+ // neither result had an instruction, on the path that is now the default. Two
308
+ // separate rots follow from that, and each is pinned to its own contiguous
309
+ // string rather than to a word appearing somewhere in step 1.
310
+ //
311
+ // (a) The ORDERING must ride in the same sentence as the command. GitHub
312
+ // deletes the remote branch when the PR lands, so `origin/<branch>` stops
313
+ // existing at the merge and a probe run afterwards dies on a missing ref —
314
+ // which reads like the divergence it was meant to rule out. A constraint
315
+ // parked in a later paragraph is one a reader can reach the command without
316
+ // having read, so the assertion below spans command and constraint as one
317
+ // literal run of text and reds if they are split apart.
318
+ test("step 1's staleness probe carries its ordering constraint in the same sentence as the command", () => {
319
+ assert.match(
320
+ step1(),
321
+ /run `git cherry origin\/<branch> HEAD` from the worktree \*\*before the merge, never after\*\*/,
322
+ );
323
+ // the reason, without which the constraint is an unexplained rule
324
+ assert.match(step1(), /GitHub deletes the remote branch when the PR lands/);
325
+ assert.match(step1(), /fails on a missing ref/);
326
+ });
327
+
328
+ // (b) The OUTCOME. `+` must be answered on the server-side path, and answered
329
+ // with the structural reason — the path rebases through the API and pushes
330
+ // nothing, and step 4 merges the remote head, so an unpushed local commit
331
+ // cannot enter the merge. The reason is pinned with the verdict on purpose: a
332
+ // bare "no STOP here" is exactly the sentence a later reader would delete for
333
+ // looking unjustified.
334
+ test("step 1 answers a `+` on the server-side path, with the structural reason", () => {
335
+ assert.match(step1(), /Neither result halts this path/);
336
+ assert.match(step1(), /this step rebases through the API and pushes nothing/);
337
+ assert.match(step1(), /structurally unable to enter the merge/);
338
+ });
339
+
340
+ // (c) WHICH output is clean. An earlier draft of this paragraph called silence
341
+ // the clean answer, which is false for the case the paragraph is about:
342
+ // git-cherry emits a line per commit in `origin/<branch>..HEAD` and marks a
343
+ // patch-equivalent one `-` rather than dropping it, so a worktree that has
344
+ // fetched the rebase reads all-`-` and only an un-fetched one reads nothing
345
+ // (measured 2026-08-29 against real git — scratch repo, branch rebased onto an
346
+ // advanced main and force-pushed, clone left at the pre-rebase head; nothing
347
+ // before that clone fetched, a `-` per rebased commit after, a `+` in both
348
+ // once an unpushed commit was added). Pinned to the rule, not to the shape of
349
+ // either listing: `+` is the signal, its absence is clean.
350
+ test("step 1 defines the probe's clean answer by the absence of `+`, not by silence", () => {
351
+ assert.match(step1(), /The clean answer is the absence of a `\+`, not the absence of output/);
352
+ assert.match(step1(), /one that has fetched reads `-` for every rebased commit\. Both are clean/);
353
+ });
354
+
355
+ // The other half of (b), and the one that costs real work if it rots: the new
356
+ // wording must NOT license skipping the STOP where the hazard is real. The
357
+ // verdict and the identifier are pinned here, inside the block that carries
358
+ // them; the RATIONALE gets its own tighter slice below, because the two rot
359
+ // independently — #1038 corrected a false reason while the verdict stayed
360
+ // right, and a pin holding both in one span cannot tell those apart.
361
+ //
362
+ // Sliced to the fallback, not to step 1: the server-side paragraph discusses
363
+ // this same STOP, so a step1()-wide assertion stayed green with the bullet
364
+ // gutted (measured by mutation, 2026-08-29).
365
+ function fallbackBlock() {
366
+ const start = "**Fallback (server-side rebase unavailable).**";
367
+ const at = DOC.indexOf(start);
368
+ assert.notEqual(at, -1, `'${start}' moved — update this test`);
369
+ const rest = DOC.slice(at + start.length);
370
+ const end = rest.indexOf("2. Watch checks settle");
371
+ assert.notEqual(end, -1, "the fallback block's end marker moved — update this test");
372
+ return start + rest.slice(0, end);
373
+ }
374
+
375
+ test("the fallback's diverged-worktree STOP survives the primary path's `+` answer", () => {
376
+ assert.match(fallbackBlock(), /\*\*Worktree ahead\*\* → STOP, report `worktree-diverged-#<pr>`/);
377
+ });
378
+
379
+ // The same false mechanism stated a third time, in the sentence that sends the
380
+ // bot to compare the two heads at all — "the rebase would carry an unreviewed
381
+ // local commit into the merge". Pinned positively in its own paragraph.
382
+ const headCheck = () =>
383
+ paragraph(DOC, "**Confirm the worktree head", "run-merge-bot.md's fallback head check");
384
+
385
+ test("the fallback's head check states the mismatch as a corrupted verification, not a push into the merge", () => {
386
+ assert.match(
387
+ headCheck(),
388
+ phrase("the rebase would fold an unreviewed local commit into the tree you verify, while the merge takes the remote head without it"),
389
+ );
390
+ });
391
+
392
+ // #1512. The fallback's head check read `gh pr view <pr> --json headRefOid` as
393
+ // its SOLE comparison operand — the one field that lags the branch ref it is
394
+ // meant to describe, which is why step 1's own poll was moved off it (#903)
395
+ // and why the phase-1 dispatch site was moved off it (#1168). Both failure
396
+ // directions are live at this site: a false `worktree-diverged` STOP on a
397
+ // just-rebased worktree, and — the half that ships — a false EQUAL, because a
398
+ // worktree unfetched since the rebase and a PR object lagging the rebase hold
399
+ // the SAME pre-rebase sha, so the two stale values agree and the fallback
400
+ // verifies a tree the remote no longer has.
401
+ //
402
+ // These pins hold WHICH SOURCE the check turns on, not that a comparison
403
+ // exists. Measured: with the operand swapped, this file was 48/48 green on
404
+ // both the pre-fix and post-fix doc — `rev-parse HEAD` survives the swap, the
405
+ // `headRefOid` command survives in the block as the recorded diagnostic, and
406
+ // every arm's wording is unchanged. That is the shape the pins above cannot
407
+ // tell apart, and the reason these are mappings and bounded negatives rather
408
+ // than presences.
409
+ //
410
+ // MUTATION RECORD — #1512, scratch-copy method (`cp -R plugin/` to a tmp dir,
411
+ // mutate the copy, `node --test` the copy, read counts, discard; one mutant
412
+ // per copy, so the real checkout is never the subject). 18 semantic mutants,
413
+ // 9 controls, run against this file's 56 tests. 17 of 18 red, every red a
414
+ // true positive naming the pin whose claim was actually lost:
415
+ //
416
+ // The `ls-remote` line deleted from the command block; the block's "NOT the
417
+ // gate" comment reverted to the old one; the compare rule's re-admitting
418
+ // clause in all three wordings (naming `headRefOid` with and without
419
+ // "against", and naming "the PR object's head" with neither); the empty-read
420
+ // clause rewritten to fall back to the PR object; the `Equal` arm rewritten
421
+ // to accept either source; the one-re-read bound deleted; the refusal flipped
422
+ // to "take the newer reading and proceed"; the `Equal`-is-unreachable clause
423
+ // deleted; the fail-open clause deleted; the settle-window clause deleted;
424
+ // the `rev-parse origin/<branch>` prohibition deleted; the arm-discriminator
425
+ // paragraph deleted; the false-EQUAL clause deleted. Reverting the whole
426
+ // block to its pre-#1512 form reds 7.
427
+ //
428
+ // THE SURVIVOR, recorded rather than patched — see the count guard's own
429
+ // ceiling note: a re-admitting clause naming neither `headRefOid` nor
430
+ // "against" ("the PR object's value is also fine to use here") passes both
431
+ // counts, and is denied only by the block and the arms, which is where the
432
+ // instruction is actually executed.
433
+ //
434
+ // Controls all stayed 56/56 green: the compare rule rewrapped at 80 columns,
435
+ // the re-read paragraph at 70, the fail-open paragraph at 90 and the arm
436
+ // discriminator at 75; the unpinned measurement sentence reworded with
437
+ // different shas and a different git version; the unpinned "costing a pass"
438
+ // tail and the unpinned re-read rationale reworded; the block's operand
439
+ // comment reworded; and the out-of-scope `Worktree behind` arm's TRAILING
440
+ // SENTENCE reworded, its bolded head left untouched — that is the mutant
441
+ // that stayed green. Rewording the bolded head instead reds two tests this
442
+ // record does not own: the `arms()` test above, which pins
443
+ // "`**Worktree behind, or no worktree at all** → not a divergence`"
444
+ // verbatim, and the pre-existing `stopArm()` slice below, whose end bound is
445
+ // the literal string "- **Worktree behind". The pins refuse operand drift,
446
+ // not layout, and a tail-only reword of that arm does not reach them —
447
+ // its bolded head is owned by tests outside this record.
448
+
449
+ // The runnable half. A revert deletes the `ls-remote` line from the block, and
450
+ // the three-line block is the only place the operator is handed commands, so
451
+ // this is the one pin a revert cannot route around by rewording prose. Bounded
452
+ // to the block: `git ls-remote` recurs through step 1 above and `headRefOid`
453
+ // recurs through the whole file.
454
+ const headBlock = () =>
455
+ between(
456
+ DOC,
457
+ "git -C <worktree> rev-parse HEAD",
458
+ "**Compare the worktree head",
459
+ "run-merge-bot.md's fallback head-check command block",
460
+ );
461
+
462
+ test("the fallback reads the branch ref, and marks the PR-object read as not the gate", () => {
463
+ assert.match(headBlock(), phrase("git ls-remote origin refs/heads/<branch> | cut -f1"));
464
+ // The demotion travels with the command, not only in prose three paragraphs
465
+ // down: a reader who runs the block and stops reading must still not take
466
+ // `headRefOid` for the verdict.
467
+ assert.match(headBlock(), phrase("gh pr view <pr> --json headRefOid -q .headRefOid"));
468
+ assert.match(headBlock(), phrase("NOT the gate"));
469
+ });
470
+
471
+ // The operand as a MAPPING — which source the worktree head is compared
472
+ // AGAINST. The positive clause and the prohibition fail independently: a
473
+ // mutant that names the ref while leaving `headRefOid` admissible reds on the
474
+ // prohibition, one that drops the ref entirely reds on the mapping.
475
+ //
476
+ // `git rev-parse origin/<branch>` is the false fix waiting beside the real
477
+ // one, and the reason it is pinned separately: a reader who learns only "not
478
+ // the PR object" reaches for the local remote-tracking ref, which is the very
479
+ // value a stale worktree was cut from — it agrees by construction and passes
480
+ // every tree the check exists to catch. #1168 pinned the same prohibition at
481
+ // the sibling site for the same reason.
482
+ const compareRule = () =>
483
+ paragraph(DOC, "**Compare the worktree head", "run-merge-bot.md's fallback compare rule");
484
+
485
+ test("the fallback compares against the branch ref, and forbids both cheaper operands", () => {
486
+ assert.match(compareRule(), phrase("Compare the worktree head against the branch REF"));
487
+ assert.match(
488
+ compareRule(),
489
+ phrase("never against `gh pr view <pr> --json headRefOid -q .headRefOid`"),
490
+ );
491
+ assert.match(compareRule(), phrase("Never `git rev-parse origin/<branch>` either"));
492
+ assert.match(compareRule(), phrase("agrees with it by construction"));
493
+ assert.match(compareRule(), phrase("never the operand this check turns on"));
494
+ });
495
+
496
+ // COUNT guard, and the ceiling on the presences above. Every assertion in
497
+ // that test is a presence, so a mutant that keeps all five verbatim and
498
+ // appends one clause re-admitting the PR object satisfies every one of them:
499
+ // measured, "…never the operand this check turns on — though where the ref
500
+ // read is awkward, comparing against `headRefOid` is acceptable." left this
501
+ // file 55/55 green. #1168 measured three mutants of exactly this class
502
+ // escaping its own literal negative at the sibling site, and answered with a
503
+ // count; this is that answer, over the two tokens such a clause has to use.
504
+ //
505
+ // Both counts are the paragraph AS WRITTEN. `headRefOid` is 3, not 2 — the
506
+ // prohibition spells the whole command, so `--json headRefOid -q .headRefOid`
507
+ // is two of them, and "The `headRefOid` read stays" is the third. `against`
508
+ // is 2: the mapping and the prohibition. A re-admitting clause has to add one
509
+ // or the other, whichever way it is worded.
510
+ //
511
+ // THE CEILING, measured rather than assumed: a clause that names neither
512
+ // token — "the PR object's head is also acceptable here" — passes both counts.
513
+ // What denies it is not this test but the block and the arms: the compare
514
+ // rule is prose, while `headBlock()` pins the commands the operator actually
515
+ // runs and `arms()` pins the place the verdict is actually taken, and neither
516
+ // admits the field. A doc mutated that way contradicts itself in one
517
+ // paragraph and still routes the reader to the ref.
518
+ test("no second operand is admitted beside the branch ref", () => {
519
+ assert.equal(
520
+ (compareRule().match(/headRefOid/g) ?? []).length,
521
+ 3,
522
+ "the compare rule names headRefOid a fourth time — a re-admitting clause, under some wording the presences above all satisfy",
523
+ );
524
+ assert.equal(
525
+ (compareRule().match(/\bagainst\b/g) ?? []).length,
526
+ 2,
527
+ "a third compared-against clause entered the compare rule — the operand is no longer the ref and nothing else",
528
+ );
529
+ });
530
+
531
+ // MAPPING guard, ceiling on the pin above. The prohibition is a presence pin,
532
+ // so a mutant that keeps it verbatim and re-admits the field through a second
533
+ // clause satisfies it — #1168 measured three such mutants escaping its own
534
+ // literal `doesNotMatch` at the sibling site. Two bounded negatives close the
535
+ // two places such a clause can live and still be obeyed.
536
+ //
537
+ // The empty-read clause is the first: "if the ref reads empty, use
538
+ // `headRefOid` instead" is the exception that reinstates the whole defect,
539
+ // and is exactly the mutant that escaped at the sibling site. This slice is
540
+ // that clause alone, where the PR object has no legitimate business at all.
541
+ const emptyReadClause = () =>
542
+ between(
543
+ DOC,
544
+ "**An empty ref read is neither equal nor a mismatch**",
545
+ "**Why the ref and not",
546
+ "run-merge-bot.md's fallback empty-ref-read clause",
547
+ );
548
+
549
+ test("an unreadable ref refuses, and never falls back to the PR object", () => {
550
+ assert.match(emptyReadClause(), phrase("report the ref as unreadable and stop, `blocked`"));
551
+ assert.doesNotMatch(
552
+ emptyReadClause(),
553
+ /headRefOid/,
554
+ "the empty-ref-read clause hands the verdict to the PR object — the exception that reinstates the defect",
555
+ );
556
+ });
557
+
558
+ // The arms are the second place. They are where the verdict is actually
559
+ // taken, so a `headRefOid` named inside one ("**Equal** — against the ref or
560
+ // the PR head — → proceed") is the operand back, under a wording no literal
561
+ // negative above covers. The arms name no source today and need none: the
562
+ // paragraphs above resolve the operand before the reader reaches them.
563
+ const arms = () =>
564
+ between(DOC, "- **Equal** → proceed.", "**Plain `git fetch origin` only", "run-merge-bot.md's fallback arms");
565
+
566
+ test("no arm of the fallback names the PR object as a thing to compare against", () => {
567
+ assert.doesNotMatch(
568
+ arms(),
569
+ /headRefOid/,
570
+ "an arm names headRefOid — the verdict turns on the PR object again, whatever the paragraphs above say",
571
+ );
572
+ // Runs with the positives that make the negative mean something: a
573
+ // `doesNotMatch` alone is satisfied by arms that were deleted.
574
+ assert.match(arms(), phrase("**Equal** → proceed."));
575
+ assert.match(arms(), phrase("**Worktree ahead** → STOP"));
576
+ assert.match(arms(), phrase("**Worktree behind, or no worktree at all** → not a divergence"));
577
+ });
578
+
579
+ // The fail-open half, and the whole reason the OPERAND moved rather than the
580
+ // verdict gaining a settle window. Without it a reader is left with the false
581
+ // refusal alone — the cheap, visible half — and re-derives the settle-window
582
+ // remedy #1168's own ticket proposed, which fires only where the two operands
583
+ // disagree and so never reaches the pair that agrees. Pinned because that
584
+ // re-derivation restores the hole while looking like a fix.
585
+ //
586
+ // THE CEILING: the measurement sentence beside these clauses is deliberately
587
+ // unpinned — it is one run's reading at a sibling site, and re-measuring must
588
+ // not turn a test red.
589
+ const whyRef = () => paragraph(DOC, "**Why the ref and not", "run-merge-bot.md's fallback fail-open rationale");
590
+
591
+ test("the fallback says the PR-object compare fails open too, and that a re-read cannot fix it", () => {
592
+ assert.match(whyRef(), phrase("both operands go stale in the SAME direction"));
593
+ assert.match(whyRef(), phrase("fails OPEN as readily as it fails closed"));
594
+ assert.match(whyRef(), phrase("the check reads **Equal**"));
595
+ assert.match(
596
+ whyRef(),
597
+ phrase("Re-reading `headRefOid` on a settle window does not reach that half at all"),
598
+ );
599
+ });
600
+
601
+ // The remedy for a mismatch and its bound, in one paragraph but four clauses
602
+ // that fail independently:
603
+ //
604
+ // - no re-read at all, and a ref that moved mid-verification is read once
605
+ // and acted on as a divergence;
606
+ // - no bound, and the same instruction reads as "fetch until it agrees" —
607
+ // the unbounded loop step 1 already had to be written out of once, and
608
+ // the shape this doc forbids by name elsewhere;
609
+ // - no refusal, and a head that moved during verification proceeds on an
610
+ // audit of a tree that is gone;
611
+ // - no `Equal`-is-unreachable clause, and the surviving mismatch can still
612
+ // be let through as equal, which is #1512's own defect restored one
613
+ // paragraph later than where it was removed.
614
+ const reRead = () => paragraph(DOC, "**Unequal → `git fetch origin`", "run-merge-bot.md's fallback bounded re-read");
615
+
616
+ test("a mismatch is re-read exactly once, then refused rather than waited out", () => {
617
+ assert.match(reRead(), phrase("`git fetch origin` and read the ref once more"));
618
+ assert.match(reRead(), phrase("Bounded at one re-read, never a third"));
619
+ assert.match(reRead(), phrase("refuse: report `head-moved-after-label-#<pr>` and stop"));
620
+ assert.match(reRead(), phrase("Do not read a third time"));
621
+ assert.match(
622
+ reRead(),
623
+ phrase("**`Equal` is not among the outcomes a surviving mismatch can reach**"),
624
+ );
625
+ });
626
+
627
+ // The consequence of the operand swap that the swap alone does not settle.
628
+ // Against `headRefOid` the stale-plus-lagging worktree read EQUAL and never
629
+ // reached the arms; against the ref it reaches them, and the arms are labelled
630
+ // ahead/behind — a linear vocabulary the case does not fit, because a rebase
631
+ // orphans the pre-rebase head, so the ref does not carry the worktree's
632
+ // commits BY SHA even though it carries every patch in them. Read literally,
633
+ // "commits the ref lacks" sends a worktree holding no work of its own to the
634
+ // STOP: the false refusal, re-entering through the arm labels after being
635
+ // removed from the operand. The discriminator is `git cherry`, which this
636
+ // step already established two paragraphs up, and pinning it is what keeps
637
+ // the arms' unchanged behaviour actually reachable.
638
+ const armRouting = () => paragraph(DOC, "**Ahead or behind is", "run-merge-bot.md's fallback arm discriminator");
639
+
640
+ test("which arm a surviving mismatch takes is decided by patch equivalence, not by the sha compare", () => {
641
+ assert.match(armRouting(), phrase("`git cherry origin/<branch> HEAD` from the worktree"));
642
+ assert.match(armRouting(), phrase("not the sha compare"));
643
+ assert.match(armRouting(), phrase("a `+` → ahead; no `+` → behind"));
644
+ });
645
+
646
+ // #1038's AC-4 is a property of the whole block, not of the two sentences that
647
+ // carried the false claim: no sentence in the fallback may say a local commit
648
+ // reaches the remote. The three positive pins cover the spans it was written
649
+ // in; this sweeps the rest, which is what catches a restore that lands in a
650
+ // paragraph nobody pinned. The negative runs with the property that MAKES it
651
+ // true on the same slice — the rebase is verification-only — because a bare
652
+ // `doesNotMatch` also passes on a slice that no longer says anything at all.
653
+ test("no sentence in the fallback claims the local rebase can carry a commit into the merge", () => {
654
+ assert.match(
655
+ fallbackBlock(),
656
+ phrase("Rebase locally, for verification only — this rebase never needs to reach the remote"),
657
+ );
658
+ assert.doesNotMatch(fallbackBlock(), /carry[\s\S]{0,60}into the merge/);
659
+ });
660
+
661
+ // #1038. The STOP's verdict was right and its stated REASON was false: it
662
+ // justified halting because an unpushed commit is one "your rebase would
663
+ // carry into the merge", and the fallback contains no `git push`, no
664
+ // `--force` and no `--force-with-lease` at all. A refuter ran the documented
665
+ // sequence in a fixture: the unpushed commit appeared in neither the merge
666
+ // commit's ancestry nor its tree, while a control that pushed the rebased
667
+ // head did land it. The real hazard is the silent one — the fallback verifies
668
+ // the LOCAL rebased head, so a commit only the worktree holds moves the
669
+ // verified tree off the reviewed head and every green is measured against a
670
+ // tree no merge will take.
671
+ //
672
+ // Why the reason is load-bearing and not decoration: a bot that reasons from
673
+ // the old sentence, then observes that the fallback never pushes, can
674
+ // correctly conclude the stated hazard does not apply and proceed — the wrong
675
+ // action, reached from the page's own text. So the premise, the polarity
676
+ // clause and the wrong-tree clause are each pinned positively here, and the
677
+ // old reason's SHAPE is swept for one test above, over the whole fallback:
678
+ // a restore that replaces the corrected sentences reds these pins, while one
679
+ // that leaves both wordings standing — the two-sites-disagreeing shape this
680
+ // ticket exists to end — reds the sweep alone.
681
+ //
682
+ // Sliced to the arm itself, not to the whole fallback: `worktree-diverged`,
683
+ // the remote head and what gets verified all recur through the block's later
684
+ // paragraphs, and the sibling `Worktree behind` arm is the end bound, so a
685
+ // rationale lifted out of the bullet into prose below it reds here.
686
+ //
687
+ // MUTATION RECORD — #1038, scratch-copy method (`cp -R plugin/` to a tmp dir,
688
+ // mutate the copy, `node --test` the copy, read counts, discard; one mutant
689
+ // per copy, so the real checkout is never the subject). 16 semantic mutants,
690
+ // 8 controls, run against this file's 44 tests. Every mutant reds, and every
691
+ // red is a true positive:
692
+ //
693
+ // Red exactly one pin, the right one — the STOP rationale deleted; its
694
+ // polarity flipped to "can enter the merge"; the wrong-tree clause deleted;
695
+ // the rationale lifted out of the bullet into a paragraph below the arms (the
696
+ // slice bound); the fix-agent premise deleted; the verdict and identifier
697
+ // dropped (reds the verdict test alone, not the rationale one); the head
698
+ // check's verification clause softened to "the heads differ"; the old reason
699
+ // re-added BESIDE the corrected one at either site (reds the sweep alone);
700
+ // and each of the server-side paragraph's two corrected clauses deleted.
701
+ // Restoring the old reason by REPLACEMENT at either site reds two — that
702
+ // site's positive pin and the sweep — as does deleting the verification-only
703
+ // property, which reds the sweep and step 1's own fallback test.
704
+ //
705
+ // Controls all stayed 44/44 green: the STOP arm rewrapped at 80 columns, the
706
+ // premise at 60, the head check and the server-side paragraph at 70, the
707
+ // three unpinned sentences reworded (the silent-failure tail, the `+`-report
708
+ // tail, the head-check heading), and the sibling `Worktree behind` arm
709
+ // reworded — the pins refuse drift, not layout, and they do not reach the
710
+ // arm the ticket put out of scope.
711
+ const stopArm = () =>
712
+ between(DOC, "- **Worktree ahead**", "- **Worktree behind", "run-merge-bot.md's fallback arms");
713
+
714
+ test("the STOP halts on verification against the wrong tree, not on a commit carried into the merge", () => {
715
+ // the premise the old assertion carried on its true half: WHAT produces the
716
+ // divergence. Retained here, or correcting the reason would quietly drop it.
717
+ assert.match(stopArm(), phrase("leaves an unpushed, unreviewed commit that a clean-tree audit passes"));
718
+ assert.match(
719
+ stopArm(),
720
+ phrase("Nothing on this path pushes, so that commit cannot enter the merge — what it corrupts is the verification"),
721
+ );
722
+ assert.match(
723
+ stopArm(),
724
+ phrase("both the `origin/main...HEAD` diff and the suite run against a tree that is not the reviewed head"),
725
+ );
726
+ });
727
+
728
+ // The second site, and the reason a one-sentence fix would have been worse
729
+ // than the defect: the server-side paragraph did not merely omit the
730
+ // correction, it LAUNDERED the false reason — it told the reader that "your
731
+ // rebase would carry into the merge" names a hazard belonging to the fallback
732
+ // "where it still applies". Fix the STOP alone and that sentence stays on the
733
+ // page insisting the wrong reason is right, one paragraph above the bullet
734
+ // that now disagrees with it. Pinned inside the paragraph that carries the
735
+ // cross-reference, so the two sites cannot drift apart again in silence.
736
+ const plusOutcome = () =>
737
+ paragraph(DOC, "**Neither result halts this path", "run-merge-bot.md's `+` outcome paragraph");
738
+
739
+ test("the server-side paragraph routes no carry-into-the-merge rationale to the fallback", () => {
740
+ assert.match(plusOutcome(), phrase("neither path can carry a local commit to the remote, because neither pushes"));
741
+ assert.match(
742
+ plusOutcome(),
743
+ phrase("so a commit only the worktree holds makes the verified tree something other than the reviewed head"),
744
+ );
745
+ assert.doesNotMatch(plusOutcome(), /carry[\s\S]{0,60}into the merge/);
746
+ });
747
+
748
+ // #447 AC-3, and the reason this pin reaches across files: run-team's failure
749
+ // table promised `worktree-diverged-#<pr>` for "the worktree ahead of the PR
750
+ // head" with no path qualifier, while the halt itself lives only in the
751
+ // fallback. Whichever file is edited alone, the other goes back to lying.
752
+ const RUN_TEAM = readFileSync(join(REPO, "skills", "run-team", "SKILL.md"), "utf8");
753
+
754
+ // Sliced to the failure table alone. Unbounded, `worktree` and `fallback` both
755
+ // occur freely elsewhere in a file thousands of lines long.
756
+ function failureTable() {
757
+ const start = "## Failure handling";
758
+ const at = RUN_TEAM.indexOf(start);
759
+ assert.notEqual(at, -1, `'${start}' moved — update this test`);
760
+ const rest = RUN_TEAM.slice(at + start.length);
761
+ const end = rest.indexOf("A red PR never silently becomes");
762
+ assert.notEqual(end, -1, "the failure table's end marker moved — update this test");
763
+ return rest.slice(0, end);
764
+ }
765
+
766
+ test("run-team scopes the diverged-worktree row to the fallback, not to every merge path", () => {
767
+ assert.match(
768
+ failureTable(),
769
+ /\| Merge bot finds the worktree ahead of the PR head \*\*on the local-rebase fallback\*\* \|/,
770
+ );
771
+ });
772
+
773
+ // #903: the poll read `gh pr view <pr> --json headRefOid` — the one field that
774
+ // desyncs from the branch it is meant to be watching. Measured on this repo:
775
+ // `gh pr update-branch --rebase` landed and moved the ref to 221f4e9 while
776
+ // headRefOid stayed on the pre-rebase 8bc2cc4 with no CI run on the new head,
777
+ // so the poll read a landed rebase as un-landed for all 60 iterations and fell
778
+ // through to the local-rebase fallback — which would have replayed commits the
779
+ // remote already carried. Both halves pinned: the ref read must be PRESENT, and
780
+ // the sentence naming which source is authoritative must survive with it. The
781
+ // second assert is what stops a future edit reverting the mechanism while
782
+ // leaving a now-lying rationale behind.
783
+ test("step 1 polls the branch ref, not the PR object's head", () => {
784
+ // anchored to the POLL assignment inside the loop, not to any ls-remote in
785
+ // step 1 — the `pre=` line uses the same command, so a bare presence match
786
+ // stays green when only the loop body is reverted. Measured: it did.
787
+ assert.match(step1(), /\n\s+post=\$\(git ls-remote origin "\$ref" \| cut -f1\)/);
788
+ assert.match(step1(), /\*\*Poll `git ls-remote`, not `gh pr view headRefOid`\*\*/);
789
+ // The DETECTOR, not just the fix. Both prose rules above describe a `pr_head`
790
+ // field the printf has to actually emit, so deleting it leaves the doc
791
+ // describing a field it no longer prints. Measured: with only the two asserts
792
+ // above, deleting the printf field left this file 15/15 and the suite
793
+ // 1155/1155, byte-identical to baseline. Bare /pr_head/ and /headRefOid/
794
+ // matches were measured green on that same mutant too — `headRefOid` survives
795
+ // in the headline and in "Keep the `headRefOid` read", and `pr_head` in the
796
+ // desync verdict and the `<pr_head>` ancestry command — so both are anchored
797
+ // to their own line here. #1895 moved the rebase call's own output onto the
798
+ // fire block's report, so this line ends at `pr_head`.
799
+ assert.match(step1(), /\n\s+printf 'rc=%s branch=%s pre=%s post=%s pr_head=%s\\n'/);
800
+ // #910: the field is the re-poll's result, never a read of its own. This
801
+ // line used to carry an inline `"$(gh pr view <pr> --json headRefOid -q
802
+ // .headRefOid)"`, a single read of the PR object taken in the instant the
803
+ // ref poll broke, which is the lag window the settle paragraph measures.
804
+ // Anchored to its own line like the format string above: `pr_head` recurs
805
+ // through step 1, so a bare match survives the inline read being restored.
806
+ assert.match(step1(), /\n\s+"\$pr_head"\n/);
807
+ });
808
+
809
+ // The settle-window paragraph is bracketed in the doc by two rules that ARE
810
+ // pinned — the test above anchors the headline naming which source is
811
+ // authoritative, the ancestry test further below the precondition — and
812
+ // neither reaches the paragraphs between them. That gap is the shape #1147 was
813
+ // scored for in this branch's own tier row: every explanatory sentence around a
814
+ // mandate pinned, the mandate itself left bare, so inverting it to "either is
815
+ // fine" costs nothing. Measured against the doc as it stood before this test
816
+ // existed: inverting the imperative to "report the desync on the first
817
+ // `headRefOid` read … without any re-poll or cap", deleting the whole
818
+ // paragraph, and reverting the prose hunk outright each left the whole suite
819
+ // green. So this anchors the two imperative clauses and nothing else. The other
820
+ // two paragraphs in the narrower settle-window-to-ancestry stretch — the empty
821
+ // `pr_head` and the surviving desync — are pinned by the tests that follow it
822
+ // (#1948), so no paragraph from the settle window to the ancestry rule is bare
823
+ // now. The wider #1147 gap this paragraph opens with (headline to ancestry)
824
+ // still holds other unpinned paragraphs outside that stretch — #1948's own
825
+ // scope stops at the settle window and the surviving desync, not the whole gap.
826
+ //
827
+ // The clauses are split because they fail independently: dropping "on the same
828
+ // bounded cap" turns a bounded re-poll into an unbounded one while the "only if"
829
+ // clause still reads correctly, and dropping "only if … runs out" restores the
830
+ // single-read verdict while the re-poll instruction still stands.
831
+ //
832
+ // THE CEILING: the surrounding measurement sentence is deliberately unpinned —
833
+ // it reports one run's observed attempt numbers and wall clocks, and re-measuring
834
+ // must not turn a test red.
835
+ test("step 1 re-polls before calling a desync, and that mandate is pinned", () => {
836
+ assert.match(
837
+ step1(),
838
+ /re-poll `headRefOid` on the same bounded cap you already use for `ls-remote`/,
839
+ );
840
+ assert.match(
841
+ step1(),
842
+ /report the desync only if `pr_head` is still on `pre` when that cap runs out/,
843
+ );
844
+ });
845
+
846
+ // #1946 added the third outcome of that re-poll: `pr_head` still EMPTY when
847
+ // the cap runs out. It landed between the settle-window paragraph and the
848
+ // desync verdict with no pin, and #1948 measured the whole file green with the
849
+ // paragraph deleted and with its imperative inverted to fold the empty read
850
+ // into the desync and feed it to the ancestry check. Three clauses, each
851
+ // failing alone:
852
+ //
853
+ // - no "unreadable" report, and the empty read has no row of its own;
854
+ // - the "rather than folding it into" negation split from the "either the
855
+ // desync above or the landed row" list it governs, and the empty read
856
+ // gets filed as one of the two outcomes it is neither of — measured: two
857
+ // independent presence asserts here (one per side) both stayed green
858
+ // when "rather than folding it into" was reworded to "then fold it
859
+ // into", the exact inversion the test title forbids. Bound to one
860
+ // contiguous span instead so the negation and its list cannot drift
861
+ // apart;
862
+ // - no ancestry refusal, and `git merge-base --is-ancestor` is run with an
863
+ // empty operand, which has no head in it to place.
864
+ //
865
+ // Bounded by `paragraph()`, not `step1()`: step 1 runs ~60 lines through the
866
+ // fallback, and a copy of any of these clauses there would hold a step-1 pin
867
+ // green with this paragraph gone. Matched through `phrase()`, so a rewrap
868
+ // stays green. THE CEILING: the paragraph's rationale — why an empty value only
869
+ // proves the LAST read failed — is deliberately unpinned; it can be reworded
870
+ // freely.
871
+ const emptyPrHead = () =>
872
+ paragraph(DOC, "**`pr_head` still empty once the re-poll cap runs out", "run-merge-bot.md step 1 empty pr_head");
873
+
874
+ test("step 1 reports a pr_head still empty after the cap as unreadable, never as a desync or a landed rebase", () => {
875
+ assert.match(emptyPrHead(), phrase("Report the PR-object read as unreadable"));
876
+ assert.match(
877
+ emptyPrHead(),
878
+ phrase("unreadable rather than folding it into either the desync above or the landed row"),
879
+ );
880
+ });
881
+
882
+ test("step 1 never feeds an empty pr_head into the close-and-reopen ancestry check", () => {
883
+ assert.match(emptyPrHead(), phrase("do not feed an empty `pr_head` into the close-and-reopen check"));
884
+ });
885
+
886
+ // The verdict the settle window exists to delay, unpinned until #1948 though
887
+ // it is the one outcome the bot must not act on. Four clauses, each failing
888
+ // alone: the controller routing, the two forbidden repairs, and the stop. The
889
+ // reason the local rebase is forbidden is pinned apart from the prohibition, so
890
+ // "because" → "since" leaves both green while dropping either reds.
891
+ const survivingDesync = () =>
892
+ paragraph(DOC, "**A desync that DOES survive the cap", "run-merge-bot.md step 1 surviving desync");
893
+
894
+ test("step 1 hands a desync that survives the cap to the controller and repairs nothing itself", () => {
895
+ assert.match(survivingDesync(), phrase("is the one state that needs a controller"));
896
+ assert.match(survivingDesync(), phrase("do not retry the rebase"));
897
+ assert.match(survivingDesync(), phrase("do not rebase locally"));
898
+ assert.match(survivingDesync(), phrase("the remote is already correct"));
899
+ assert.match(survivingDesync(), phrase("Report it and stop"));
900
+ });
901
+
902
+ // #903's expensive half. Close-and-reopen is the usual remedy for a desynced PR
903
+ // and is normally reversible — but a rebase orphans the recorded head by
904
+ // construction, and that is the very event that produced the desync. Measured:
905
+ // three reopen attempts on #903 each returned `Could not open the pull request`,
906
+ // and the only recovery was a replacement PR (#908), losing the review thread
907
+ // and every label on it. The precondition is the whole rule, so it is pinned
908
+ // alongside the verdict it forces.
909
+ test("step 1 requires an ancestry check before closing a desynced PR", () => {
910
+ assert.match(step1(), /git merge-base --is-ancestor <pr_head> origin\/<branch>/);
911
+ assert.match(step1(), /Non-ancestor → \*\*do not close\*\*/);
912
+ });
913
+
914
+ // --- #910: step 1's block, lifted from the fence and executed ---------------
915
+ //
916
+ // The settle paragraph says a desync is not a desync until it survives a
917
+ // bounded re-poll, and the block used to read `headRefOid` once, inline in its
918
+ // printf, so a bot that ran the block and stopped reading reported one for a
919
+ // state that clears itself. The ruling on #910 put the re-poll in the block.
920
+ // The behaviour it asks for cannot be seen by a string pin: a loop's bound, its
921
+ // break condition, and which outcomes enter it. So these RUN the block, the way
922
+ // shell-traps-prose.test.mjs runs this document's monitor. `git`, `gh` and
923
+ // `sleep` are stubbed, each probe answers from a per-case sequence (its last
924
+ // value repeating), and every call is logged, so a case asserts what the block
925
+ // printed and how many times it asked.
926
+ //
927
+ // The stubs are shell functions defined ahead of the block, not executables on
928
+ // PATH. A function shadows a command in all three shells, `$(…)` and pipelines
929
+ // included, and a freshly written executable is scanned on its first exec under
930
+ // macOS: measured here at ~5s per stub, 15s a run for three, where the
931
+ // functions cost nothing.
932
+ //
933
+ // THE CEILING: nothing here contacts GitHub, and `sleep` is logged, not taken,
934
+ // so this measures the block's control flow and not real lag or wall time.
935
+ // `seq` and `cut` are the real ones. `<pr>` is filled in, because a bot fills
936
+ // it in, and left literal the shell reads it as two redirections.
937
+ //
938
+ // #1895 split the block in two: a fire block that reads `pre` and calls
939
+ // `gh pr update-branch`, and a poll block handed `rc`, `branch` and `pre` off
940
+ // the fire block's report line. Both run here, in sequence, against one case
941
+ // directory, and the poll's `<rc>`/`<branch>`/`<pre>` are filled from what the
942
+ // fire block PRINTED — the hand-off a bot makes — so a fire-to-poll value the
943
+ // report line drops
944
+ // reds here instead of being carried in by the test.
945
+ const BASH_BLOCKS = [...DOC.matchAll(/```bash\n([\s\S]*?)```/g)].map((m) => m[1]);
946
+ const STEP1_FIRE = BASH_BLOCKS.filter((b) => b.includes("gh pr update-branch <pr> --rebase"));
947
+ assert.equal(
948
+ STEP1_FIRE.length,
949
+ 1,
950
+ `expected exactly one bash block running gh pr update-branch, found ${STEP1_FIRE.length}; update this test`,
951
+ );
952
+ const STEP1_POLL = BASH_BLOCKS.filter((b) => b.includes("<pre>") && b.includes("seq 1 60"));
953
+ assert.equal(
954
+ STEP1_POLL.length,
955
+ 1,
956
+ `expected exactly one bash block polling from a handed-over <pre>, found ${STEP1_POLL.length}; update this test`,
957
+ );
958
+
959
+ // `next`: one value per line in "$1", one consumed per call, the last one
960
+ // repeating once the sequence runs out. Arithmetic, not a bare `[ -gt ]`, on
961
+ // wc's count: BSD wc pads it with spaces. The counters are files because most
962
+ // calls run in a `$(…)` subshell, where a variable would not survive. An empty
963
+ // `ls` value is a failed read: no line at all, which `cut -f1` turns into an
964
+ // empty `post`. `return`, never `exit`, with one exception: `sleep` runs in
965
+ // the block's own shell, so its `exit` is the harness-deadline stand-in — with
966
+ // `$CASE/kill` holding a count, the sleep that reaches it ends the whole block
967
+ // mid-poll, no report line printed, and clears the file so a re-issue runs on.
968
+ const STEP1_STUBS = `next() {
969
+ stub_n=$(cat "$1.n" 2>/dev/null || echo 0); stub_n=$((stub_n+1)); echo "$stub_n" >"$1.n"
970
+ stub_last=$(($(wc -l <"$1"))); [ "$stub_n" -gt "$stub_last" ] && stub_n=$stub_last
971
+ sed -n "\${stub_n}p" "$1"
972
+ }
973
+ git() {
974
+ [ "$1" = ls-remote ] || { echo "unexpected: git $*" >&2; return 97; }
975
+ echo ls-remote >>"$CASE/log"
976
+ stub_sha=$(next "$CASE/ls")
977
+ [ -z "$stub_sha" ] || printf '%s\\t%s\\n' "$stub_sha" "$3"
978
+ }
979
+ gh() {
980
+ case "$*" in
981
+ "pr view 42 --json headRefName -q .headRefName") echo feat ;;
982
+ "pr update-branch 42 --rebase")
983
+ echo update-branch >>"$CASE/log"
984
+ [ "$UPDATE_RC" -eq 0 ] || { echo "GraphQL: merge conflict" >&2; return "$UPDATE_RC"; }
985
+ echo "PR branch updated" ;;
986
+ "pr view 42 --json headRefOid -q .headRefOid")
987
+ echo headRefOid >>"$CASE/log"
988
+ next "$CASE/head" ;;
989
+ *) echo "unexpected: gh $*" >&2; return 97 ;;
990
+ esac
991
+ }
992
+ sleep() {
993
+ echo "sleep $*" >>"$CASE/log"
994
+ [ -f "$CASE/kill" ] && [ "$(grep -c '^sleep' "$CASE/log")" -ge "$(cat "$CASE/kill")" ] && { rm "$CASE/kill"; exit 137; }
995
+ return 0
996
+ }
997
+ `;
998
+ const STEP1_FIRE_SCRIPT = STEP1_STUBS + STEP1_FIRE[0].replaceAll("<pr>", "42");
999
+ const step1PollScript = ({ rc, branch, pre }) =>
1000
+ STEP1_STUBS + STEP1_POLL[0].replaceAll("<pr>", "42").replaceAll("<rc>", rc).replaceAll("<branch>", branch).replaceAll("<pre>", pre);
1001
+
1002
+ const STEP1_DIR = mkdtempSync(join(tmpdir(), "merge-bot-step1-"));
1003
+
1004
+ const step1HasShell = (s) => {
1005
+ try {
1006
+ execFileSync(s, ["-c", "exit 0"], { stdio: "ignore" });
1007
+ return true;
1008
+ } catch {
1009
+ return false;
1010
+ }
1011
+ };
1012
+ // sh and bash exist on every runner; zsh, the shell this document says it runs
1013
+ // under, is absent on ubuntu-latest and is skipped there rather than faked.
1014
+ const STEP1_SHELLS = ["sh", "bash", "zsh"].filter(step1HasShell);
1015
+
1016
+ const PRE = "a".repeat(40);
1017
+ const POST = "b".repeat(40);
1018
+ const THIRD = "c".repeat(40);
1019
+
1020
+ // The timeout is the bound's own witness: a re-poll rewritten as an unbounded
1021
+ // `until` spins on a PR object that never moves, and reds here instead of
1022
+ // hanging the suite.
1023
+ function step1Case({ ls, head, updateRc = 0 }) {
1024
+ const dir = mkdtempSync(join(STEP1_DIR, "case-"));
1025
+ const lines = (xs) => xs.map((x) => `${x}\n`).join("");
1026
+ writeFileSync(join(dir, "ls"), lines(ls));
1027
+ writeFileSync(join(dir, "head"), lines(head));
1028
+ writeFileSync(join(dir, "log"), "");
1029
+ return { dir, env: { ...process.env, CASE: dir, UPDATE_RC: String(updateRc) } };
1030
+ }
1031
+
1032
+ function step1Script(c, name, text) {
1033
+ const script = join(c.dir, name);
1034
+ writeFileSync(script, text);
1035
+ return script;
1036
+ }
1037
+
1038
+ const step1Run = (shell, c, script) => execFileSync(shell, [script], { encoding: "utf8", timeout: 30_000, env: c.env });
1039
+
1040
+ // The fire block's report line, parsed the way a bot reads it to fill the
1041
+ // poll's `<rc>` and `<pre>`.
1042
+ function fireStep1(shell, c) {
1043
+ const stdout = step1Run(shell, c, step1Script(c, "fire.sh", STEP1_FIRE_SCRIPT));
1044
+ const fired = /^rc=(\S*) branch=(\S*) pre=(\S*)$/m.exec(stdout);
1045
+ assert.ok(fired, `${shell}: the fire block printed no rc/pre line:\n${stdout}`);
1046
+ return { rc: fired[1], branch: fired[2], pre: fired[3] };
1047
+ }
1048
+
1049
+ function step1Report(shell, c, stdout) {
1050
+ const report = /^rc=(\S*) branch=\S* pre=(\S*) post=(\S*) pr_head=(\S*)$/m.exec(stdout);
1051
+ assert.ok(report, `${shell}: the poll block printed no report line:\n${stdout}`);
1052
+ const log = readFileSync(join(c.dir, "log"), "utf8").split("\n").filter(Boolean);
1053
+ const firstRead = log.indexOf("headRefOid");
1054
+ return {
1055
+ rc: report[1],
1056
+ pre: report[2],
1057
+ post: report[3],
1058
+ prHead: report[4],
1059
+ fires: log.filter((l) => l === "update-branch").length,
1060
+ reads: log.filter((l) => l === "headRefOid").length,
1061
+ sleeps: log.filter((l) => l.startsWith("sleep")),
1062
+ // The re-poll's own sleeps: every one after the first PR-object read. The
1063
+ // ref poll's sleeps all come before it.
1064
+ repollSleeps: firstRead === -1 ? 0 : log.slice(firstRead).filter((l) => l.startsWith("sleep")).length,
1065
+ };
1066
+ }
1067
+
1068
+ function runStep1(shell, fixture) {
1069
+ const c = step1Case(fixture);
1070
+ const poll = step1Script(c, "poll.sh", step1PollScript(fireStep1(shell, c)));
1071
+ return step1Report(shell, c, step1Run(shell, c, poll));
1072
+ }
1073
+
1074
+ test("step 1 re-polls a lagging PR object and reports the head it caught up to", () => {
1075
+ for (const shell of STEP1_SHELLS) {
1076
+ // The measured shape: the ref moved on the first poll, and the PR object
1077
+ // followed a few reads later. A single read reports `pre` here, and that is
1078
+ // a desync verdict for a state that cleared itself.
1079
+ const lag = runStep1(shell, { ls: [PRE, POST], head: [PRE, PRE, PRE, POST] });
1080
+ assert.equal(
1081
+ lag.prHead,
1082
+ POST,
1083
+ `${shell}: pr_head reported ${lag.prHead} after the PR object caught up on read 4; the block read it too early`,
1084
+ );
1085
+ assert.equal(lag.reads, 4, `${shell}: expected 4 PR-object reads (3 lagging, 1 caught up), got ${lag.reads}`);
1086
+ assert.equal(lag.repollSleeps, 3, `${shell}: expected one sleep between each pair of reads, got ${lag.repollSleeps}`);
1087
+ // An empty read is no answer, so it cannot end the wait either.
1088
+ const blank = runStep1(shell, { ls: [PRE, POST], head: ["", POST] });
1089
+ assert.equal(blank.prHead, POST, `${shell}: an empty PR-object read ended the re-poll`);
1090
+ assert.equal(blank.reads, 2, `${shell}: expected the empty read to be re-polled once, got ${blank.reads} reads`);
1091
+ }
1092
+ });
1093
+
1094
+ test("step 1 reports a desync only after the re-poll has run its 60 × 5s cap", () => {
1095
+ for (const shell of STEP1_SHELLS) {
1096
+ const stuck = runStep1(shell, { ls: [PRE, POST], head: [PRE] });
1097
+ assert.equal(stuck.post, POST, `${shell}: fixture: the ref moved, so this is the desync signature`);
1098
+ assert.equal(stuck.prHead, PRE, `${shell}: a PR object that never moved was reported as ${stuck.prHead}`);
1099
+ assert.equal(
1100
+ stuck.reads,
1101
+ 61,
1102
+ `${shell}: the desync was reported after ${stuck.reads} PR-object reads; the cap is one read plus 60 re-polls`,
1103
+ );
1104
+ assert.equal(stuck.repollSleeps, 60, `${shell}: expected 60 re-poll sleeps, got ${stuck.repollSleeps}`);
1105
+ assert.deepEqual(
1106
+ [...new Set(stuck.sleeps)],
1107
+ ["sleep 5"],
1108
+ `${shell}: every wait is the ref poll's own 5s, got ${[...new Set(stuck.sleeps)].join(", ")}`,
1109
+ );
1110
+ }
1111
+ });
1112
+
1113
+ // What the re-poll must NOT hold up. It is gated on the one outcome that can
1114
+ // produce the desync signature: `rc=0`, `post` non-empty, `post != pre`. The
1115
+ // other rows of the four-outcome list take the fallback, and a five-minute wait
1116
+ // on the PR object in front of each one would be spent on a question nobody
1117
+ // asked. A PR object already off `pre` has answered, even on a third sha: that
1118
+ // is merge-gate.mjs's `head-moved-after-label`, not this loop's to wait out.
1119
+ test("step 1 takes one plain PR-object read wherever the ref did not land, or the PR object already moved", () => {
1120
+ const cases = [
1121
+ ["a non-zero rc", { updateRc: 1, ls: [PRE], head: [PRE] }, { rc: "1", prHead: PRE }],
1122
+ ["a ref that never moved", { ls: [PRE], head: [PRE] }, { post: PRE, prHead: PRE }],
1123
+ ["an unreadable ref", { ls: [PRE, ""], head: [PRE] }, { post: "", prHead: PRE }],
1124
+ ["a PR object already on post", { ls: [PRE, POST], head: [POST] }, { post: POST, prHead: POST }],
1125
+ ["a PR object on a third sha", { ls: [PRE, POST], head: [THIRD] }, { post: POST, prHead: THIRD }],
1126
+ ];
1127
+ for (const shell of STEP1_SHELLS) {
1128
+ for (const [what, fixture, want] of cases) {
1129
+ const got = runStep1(shell, fixture);
1130
+ for (const [k, v] of Object.entries(want)) {
1131
+ assert.equal(got[k], v, `${shell}, ${what}: ${k} reported ${JSON.stringify(got[k])}`);
1132
+ }
1133
+ assert.equal(got.reads, 1, `${shell}, ${what}: expected one plain PR-object read, got ${got.reads}`);
1134
+ assert.equal(got.repollSleeps, 0, `${shell}, ${what}: the block waited on the PR object ${got.repollSleeps} times`);
1135
+ }
1136
+ }
1137
+ });
1138
+
1139
+ // #1895. The poll outlives omp's bash-backgrounding deadline on its COMMON
1140
+ // path: the PR object's measured 84s-2min lag alone runs past omp's ~60s
1141
+ // backgrounding, and a deadline kills the poll with
1142
+ // no report line. The recovery the doc names is re-issuing the poll with the
1143
+ // fire block's `pre`, and what has to hold is that the recovery reports the
1144
+ // rebase as LANDED. Before the split the block could only be re-run whole,
1145
+ // which re-read `pre` off a ref the rebase had already moved, and
1146
+ // `gh pr update-branch` then answered "no new commits": reproduced against the
1147
+ // pre-split doc with these stubs, the re-run fired the rebase twice and printed
1148
+ // `rc=1` with `pre` and `post` both the rebased head — the already-current row,
1149
+ // for a rebase that landed and was never verified. A poll that re-derives `pre`
1150
+ // itself reds here the same way, reporting `post` equal to `pre`.
1151
+ test("step 1's poll, cut off mid-re-poll and re-issued with the fire block's pre, reports the landed rebase", () => {
1152
+ for (const shell of STEP1_SHELLS) {
1153
+ // The ref moves at once; the PR object lags 12 reads, and the deadline
1154
+ // lands on the re-poll's 5th sleep, inside that lag.
1155
+ const c = step1Case({ ls: [PRE, POST], head: [...Array(12).fill(PRE), POST] });
1156
+ const poll = step1Script(c, "poll.sh", step1PollScript(fireStep1(shell, c)));
1157
+ writeFileSync(join(c.dir, "kill"), "5");
1158
+ const cut = spawnSync(shell, [poll], { encoding: "utf8", timeout: 30_000, env: c.env });
1159
+ assert.equal(cut.status, 137, `${shell}: the deadline stand-in did not end the poll:\n${cut.stdout}${cut.stderr}`);
1160
+ assert.doesNotMatch(cut.stdout, /^rc=/m, `${shell}: the cut-off poll printed a report line — the fixture no longer models a deadline`);
1161
+ const reissued = step1Report(shell, c, step1Run(shell, c, poll));
1162
+ assert.deepEqual(
1163
+ { rc: reissued.rc, pre: reissued.pre, post: reissued.post, prHead: reissued.prHead },
1164
+ { rc: "0", pre: PRE, post: POST, prHead: POST },
1165
+ `${shell}: the re-issued poll did not report the rebase as landed`,
1166
+ );
1167
+ assert.equal(reissued.fires, 1, `${shell}: recovering the poll fired the rebase again`);
1168
+ }
1169
+ });
1170
+
1171
+ // The deadline half of #1895, the way step 2's CI wait and the grace wait
1172
+ // carry theirs.
1173
+ test("step 1's poll runs in one eval cell, never bash plus wait", () => {
1174
+ const pair = between(DOC, "The poll:", "**Poll `git ls-remote`, not", "run-merge-bot.md step 1 poll rule");
1175
+ assert.match(pair, phrase("one Python `eval` cell"));
1176
+ assert.match(pair, phrase("its cell `timeout` at 900s or more"));
1177
+ assert.match(pair, phrase("never `bash` plus `wait`"), "the rule no longer forbids the bash+wait form that backgrounds past ~60s");
1178
+ });
1179
+
1180
+ // #908: a controller brief predicted the merge would be "a fast-forward". True
1181
+ // of the CONTENT (merge tree == pin tree == 988f29d1, `git diff` empty) and false
1182
+ // of the SHAPE — `gh pr merge --merge` wrote two parents. The distinction is not
1183
+ // cosmetic: prove-merge.sh guards the SHAPE with `[ "$parents" -ge 2 ]`, dying
1184
+ // at "has no second parent — not a merge commit", and die() exits 2 — so an
1185
+ // actual fast-forward yields no proof and a halt. Anchored on those strings
1186
+ // rather than a line number, which drifted repeatedly here (#1136). Pinned so
1187
+ // a future member cannot read the doc as permitting one.
1188
+ test("step 4 says why --merge is load-bearing, not merely which flag to type", () => {
1189
+ assert.match(step4(), /\*\*`--merge` \(no-ff\) is load-bearing, not stylistic/);
1190
+ assert.match(step4(), /has no second parent — not a merge commit/);
1191
+ // pins the VALUE, not the markdown around it: a cosmetic reflow dropping the
1192
+ // bold must not red a correct document. Still discriminating — measured,
1193
+ // `exits **1**` reds this assert both with and without the bold.
1194
+ assert.match(step4(), /exits\s+\**2\**/);
1195
+ });
1196
+
1197
+ // #18. Load-bearing like its sibling paragraphs in this section: without this
1198
+ // pin, a future edit could soften "write it against `gates` instead" or drop
1199
+ // it, and the doc would go on recommending a sanity check against a flat field
1200
+ // that flips its own polarity per proof path.
1201
+ test("step 4 says to read gates, not the flat fields", () => {
1202
+ assert.match(step4(), /Read `gates`, not the flat fields/);
1203
+ assert.match(step4(), /write it against `gates` instead/);
1204
+ });
1205
+
1206
+ test("step 4 expects the fallback path to disprove, not to silently count as proved", () => {
1207
+ assert.match(step4(), /A `rebase-fallback-#<pr>` merge is expected to disprove here/);
1208
+ assert.match(step4(), /never as `proved`/);
1209
+ });
1210
+
1211
+ // Bounded to the Report line itself. An unbounded whole-file match is the
1212
+ // vacuous pin this file's header forbids: the token surviving anywhere else in
1213
+ // the doc would mask its removal from the vocabulary list.
1214
+ test("the report vocabulary includes rebase-fallback", () => {
1215
+ assert.match(DOC, /^Report merged [^\n]*rebase-fallback-#X/m);
1216
+ });
1217
+
1218
+ // #1806 (spec 2026-09-24 § 5, ADR 0012 Decision 3). Step 3 is ONE script run
1219
+ // twice, and the merge rests on the second run: a conclusion can invert under
1220
+ // a fixed run id and a CI wait sits between the two readings. Sliced to step 3
1221
+ // alone — `merge-gate`, `exit 0` and `gh pr merge` all recur through step 4
1222
+ // and the report line, so an unbounded match survives the rule's deletion.
1223
+ // These replace the retired `gateProof()` block: that section's synthetic
1224
+ // fixtures and plain-`mkdir` claim moved into `merge-gate.test.mjs` as cases.
1225
+ const step3 = () =>
1226
+ between(DOC, "3. **Gate the merge with `merge-gate.mjs`", "4. `gh pr merge <pr> --merge`", "run-merge-bot.md step 3");
1227
+
1228
+ test("step 3 runs the merge gate twice and merges only on the second exit 0", () => {
1229
+ const s = step3();
1230
+ assert.match(s, /~\/\.fleet\/bin\/fleet-run merge-gate\.mjs --pr <pr> --pre <pre> --post <post>/);
1231
+ assert.match(
1232
+ s,
1233
+ phrase("**Run it again immediately before `gh pr merge`, and merge only on that second exit 0.**"),
1234
+ "step 3 no longer re-runs the gate at the merge instant — a conclusion that inverted under the same run id, or a label pulled during the CI wait, merges on the first reading",
1235
+ );
1236
+ });
1237
+
1238
+ test("step 3 waits on an unfinished run instead of skipping the PR, and only then", () => {
1239
+ // The one exit 1 that is not a skip. Collapsed into "any exit 1 → skip",
1240
+ // every freshly rebased PR is skipped, because its run is always in flight
1241
+ // on the first reading.
1242
+ assert.match(
1243
+ step3(),
1244
+ phrase("Exit 1 with a `ci:…` `reason`, `ci.runId` set and `ci.status` not `completed` → the run has started but not finished: wait on `ci.runId` (step 2), then run it again."),
1245
+ "step 3 no longer separates the not-yet-finished run from a real refusal",
1246
+ );
1247
+ });
1248
+
1249
+ // #1817. Right after `gh pr update-branch --rebase`, GitHub has not yet
1250
+ // registered a run for the rebased head: `ci.runId` and `ci.status` both read
1251
+ // `null`, which the arm above's "`ci.status` not `completed`" condition also
1252
+ // matches — collapsed together, a bot reading this prose is sent to wait on
1253
+ // `ci.runId` (step 2) with a `null` id, i.e. `gh run watch null` / `gh run
1254
+ // view null`. This pins the no-run case as its own arm, never routed through
1255
+ // step 2's blocking wait.
1256
+ test("step 3 waits and re-gates on a null ci.runId instead of routing it into step 2's wait", () => {
1257
+ const s = step3();
1258
+ assert.match(
1259
+ s,
1260
+ phrase("Exit 1 with `ci.runId` **null** (`reason` starts `no CI run whose headSha equals`) → GitHub has not yet registered a run for this head at all"),
1261
+ "step 3 no longer carves the no-run-yet case out of the unfinished-run wait",
1262
+ );
1263
+ assert.match(
1264
+ s,
1265
+ phrase("never route this into step 2's `gh run watch`/`gh run view <run-id>` with a null id"),
1266
+ "step 3 no longer warns against waiting on step 2's blocking call with a null run id",
1267
+ );
1268
+ assert.match(
1269
+ s,
1270
+ phrase("Wait 15s and run the gate again instead, capped at 20 attempts (~5 minutes); no run within that cap → skip the PR and report `<reason>-#<pr>`"),
1271
+ "step 3 no longer bounds the no-run-yet wait, or no longer reports when the cap is exhausted",
1272
+ );
1273
+ });
1274
+
1275
+ test("step 3 still skips a real refusal that is neither the unfinished-run wait nor the no-run-yet wait", () => {
1276
+ assert.match(
1277
+ step3(),
1278
+ phrase("the same as any other exit 1. Any other exit 1 → skip the PR"),
1279
+ "step 3 no longer distinguishes the two waits above from every other exit 1",
1280
+ );
1281
+ });
1282
+
1283
+ test("step 3 reads exit 2 as could-not-evaluate, never as a verdict about the PR", () => {
1284
+ const s = step3();
1285
+ assert.match(s, phrase("Exit 2 → stop on that PR and report `<reason>-#<pr>`: the gate could not evaluate"));
1286
+ assert.match(
1287
+ s,
1288
+ phrase("Re-run once only for `rate-limited`"),
1289
+ "step 3 no longer bounds the exit-2 retry to the one reason that clears by itself",
1290
+ );
1291
+ });
1292
+
1293
+ test("step 3 keys the gate's reading on both the PR and the bot's own name", () => {
1294
+ // `merge-bot-<n>` is 1 + the merge-bot entries in the ledger's
1295
+ // `## Dispatched` list, so no two bots in one run share it; `pr<N>` binds
1296
+ // the reading to the merge it licenses. Either key dropped puts two readings
1297
+ // at one path.
1298
+ assert.match(step3(), phrase("--out <scratch>/pr<N>/merge-bot-<n>/ci.json"));
1299
+ });
1300
+
1301
+ // #1806 (spec § 4 items 4, 6, 11). The dispatched bot's pass ends in a grace
1302
+ // and ONE report; the top-level invocation keeps its Monitor. Sliced to the
1303
+ // grace section, which ends where **Then stay armed** begins.
1304
+ const grace = () => between(DOC, "## Grace, then one report", "## Then stay armed", "run-merge-bot.md grace section");
1305
+
1306
+ test("a dispatched bot holds a 15-minute grace, polling every 60s, before its one report", () => {
1307
+ const s = grace();
1308
+ assert.match(s, phrase("**Only a bot a controller dispatched holds a grace**"));
1309
+ assert.match(s, phrase("then waits **15 minutes** for late labels, then reports once"));
1310
+ assert.match(s, phrase("Every 60s, poll `gh pr list --state open --label ready-to-merge --limit 200 --json number`"),
1311
+ "the grace poll lost its --limit, so it reads gh's bare default of 30 as the whole labelled queue (#2108)");
1312
+ assert.match(
1313
+ s,
1314
+ phrase("**re-run selection from the top**, hold rule included, drain what it makes actionable, and restart the grace after that drain"),
1315
+ "a label arriving in grace no longer re-enters selection with the hold rule, or no longer restarts the grace",
1316
+ );
1317
+ assert.match(s, phrase("**One report, at exit, and none before it**"));
1318
+ });
1319
+
1320
+ test("the grace wait holds in one eval cell, never bash plus wait", () => {
1321
+ const pair = between(DOC, "The wait:", "**One report, at exit", "run-merge-bot.md grace wait rule");
1322
+ assert.match(pair, phrase("hold the whole grace in one Python `eval` cell"));
1323
+ assert.match(pair, phrase("its cell `timeout` at 1000s or more"));
1324
+ assert.match(pair, phrase("never `bash` plus `wait`"), "the rule no longer forbids the bash+wait form that backgrounds past ~60s");
1325
+ });
1326
+
1327
+ test("the top-level invocation still arms its Monitor, and a dispatched bot still skips it", () => {
1328
+ assert.match(
1329
+ DOC,
1330
+ phrase("**Skip this whole section if a controller dispatched you** (`/skill:run-team`, or any caller that says it owns the watcher) — hold the grace above instead."),
1331
+ );
1332
+ });
1333
+
1334
+ // #705. `pr-overlap.mjs` grew a fourth signal, and a signal the runbook does
1335
+ // not name is a signal the bot never reads — which is the same silent failure
1336
+ // the ticket is about, moved from the script into its caller. The count is
1337
+ // pinned in both of the places this document states it, because they rot
1338
+ // independently: the invocation paragraph tells the bot what "firing" means,
1339
+ // and the verdict-strength line tells it how hard to hold. Sliced to the hold
1340
+ // rule alone — unbounded, "four signals" anywhere later in a 300-line
1341
+ // document would satisfy these with the rule itself reverted to three.
1342
+ const holdRule = () => between(DOC, "Before touching labeled PR `N`", "## The labelled head", "the hold rule");
1343
+
1344
+ test("the hold rule names all four signals, prose included", () => {
1345
+ const s = holdRule();
1346
+ assert.match(
1347
+ s,
1348
+ phrase("**Any** of its four signals (`files`, `modules`, `dirs`, `prose`) firing means related"),
1349
+ "the hold rule no longer names four signals — pr-overlap.mjs computes `prose` and a bot reading three ignores it",
1350
+ );
1351
+ assert.match(
1352
+ s,
1353
+ phrase("Directory-only and prose-only hits prompt investigation"),
1354
+ "the hold rule no longer rates a prose hit as weak evidence beside a directory one",
1355
+ );
1356
+ });
1357
+
1358
+ // The half that is not the count: an empty `prose[]` is a clear only when the
1359
+ // scan covered the diff, and the script reports that in its own field rather
1360
+ // than on stderr alone. A runbook that names the signal and not its unrun
1361
+ // field reintroduces #705's exact shape — the clearest-looking output being
1362
+ // the one that missed something — one level in.
1363
+ test("the hold rule says prose=0 clears only when proseUnrun is null", () => {
1364
+ assert.match(
1365
+ holdRule(),
1366
+ phrase("**`prose=0` is a clear only when `proseUnrun` is `null`.**"),
1367
+ "the hold rule no longer gates an empty prose result on the scan having run",
1368
+ );
1369
+ });
1370
+
1371
+ // The soft-signal bullet this mechanises. It predates the signal and stayed
1372
+ // pure judgement for years; what changed is that one third of it — a data
1373
+ // file cited by name — now has a mechanism, and the bullet has to point at it
1374
+ // or the bot re-derives by hand what the script already computed. The other
1375
+ // two thirds deliberately stay human: the paragraph below the bullet is the
1376
+ // measurement (two PRs sharing `reset_hint=`/`resetHint`/`terminalFailure`,
1377
+ // provably unrelated) that says mechanising a bare symbol name would cost
1378
+ // more than it buys.
1379
+ test("the same-docs-section bullet points at signal 4 and keeps symbols human", () => {
1380
+ const s = paragraph(DOC, "they change the same exported symbol", "the same-section bullet");
1381
+ assert.match(
1382
+ s,
1383
+ phrase("signal 4 mechanises the half of this where the section is a **data file** cited by name"),
1384
+ "the same-section bullet no longer names the signal that mechanises its data-file half",
1385
+ );
1386
+ assert.match(
1387
+ s,
1388
+ phrase("a bare symbol or key name is still yours to read"),
1389
+ "the same-section bullet no longer keeps bare symbol and config-key matching a human read",
1390
+ );
1391
+ });