@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,357 @@
1
+ ---
2
+ description: merge every ready-to-merge open PR in numeric order — rebase, wait green, merge, never jumping a related PR
3
+ ---
4
+
5
+ Set the goal, then work it until no open PR is left:
6
+
7
+ `/goal Merge all of this repo's open PRs in numeric order if labeled ready-to-merge. Rebase -> Wait for checks green -> check for the ready-to-merge label -> merge if labeled. Never merge past a lower-numbered PR whose work is related — wait for its label instead.`
8
+
9
+ Only `ready-to-merge` PRs are in scope — it is the author's sign-off. Never add the label yourself.
10
+
11
+ ## Order, and the hold rule
12
+
13
+ Lowest number first. But the label alone does not authorize a merge: **a labeled PR must not jump a lower-numbered open PR touching related work.** Numeric order is the author's intended order; jumping it silently rebases the lower PR onto changes it was never written against.
14
+
15
+ Before touching labeled PR `N`, list every open PR below `N` lacking the label. For each, decide related or not:
16
+
17
+ ```bash
18
+ ~/.fleet/bin/fleet-run pr-overlap.mjs --a <lower-pr> --b <N>
19
+ ```
20
+
21
+ **Any** of its four signals (`files`, `modules`, `dirs`, `prose`) firing means related. Path equality alone is too weak: a repo mid-migration has `src/…/foo.test.ts` in one PR and `tests/unit/…/foo.test.ts` in the other — same module, zero shared paths.
22
+
23
+ Two false positives in signal 3:
24
+
25
+ - **Repo root (`.`) is excluded above.** Every top-level file shares it, so it fires on PRs with nothing in common.
26
+ - **A bare top-level directory (`docs`, `tests`, `src`) is weak evidence.** Two PRs editing different documents under `docs/` are unrelated. Look at the actual files first: same document, module, or config → related. Different subjects sharing an ancestor → not related; proceed and say so.
27
+
28
+ **Signal 4, `prose`, is the one `signal=none` used to miss, and the only one that reads content rather than paths.** It fires when one PR changes a data file (`.tsv`, `.json`, `.yml`, …) whose path or basename appears in the other PR's own diff — the append-vs-rewrite collision `docs/metrics/tier-outcomes.tsv` has with `run-team/SKILL.md`'s tier guard by construction, since the file is append-only and every run produces a PR touching it. Weak evidence, on a par with a directory hit, and it prints its witness — the cited file, the citing file, the token and the line — because one read disproves it. It is ranked LAST, so it only ever converts a `none`: a `files`, `modules` or `dirs` verdict still reads exactly as it did before, with `prose=<n>` on the summary line beside it.
29
+
30
+ **`prose=0` is a clear only when `proseUnrun` is `null`.** A non-null `proseUnrun` means the scan was reached and could not cover the diff, so an empty `prose[]` there is silence rather than data — read the reason it names and settle the pair by hand.
31
+
32
+ Directory-only and prose-only hits prompt investigation. Shared *files* and *module names* are verdicts.
33
+
34
+ - **Related → HOLD `N`.** Do not rebase, do not merge. Report `held-behind-#<lower>` and move on. The watcher picks it up once the lower PR is signed off and merged.
35
+ - **Unrelated → proceed**, and report that it went ahead of `#<lower>` and on what evidence.
36
+
37
+ Also **related** even with an empty file intersection when:
38
+
39
+ - both reference the same issue, or were split from one
40
+ - one branch is stacked on the other, or their names share an issue/cluster
41
+ - they change the same exported symbol, config key, or docs section from different files — signal 4 mechanises the half of this where the section is a **data file** cited by name, so read `prose` before reaching for this bullet; a bare symbol or key name is still yours to read, and the measurement in the next paragraph is why it stays that way
42
+
43
+ Genuinely unclear → **hold**. Waiting costs a label; merging out of order costs a conflict resolution on someone else's branch, and the loser is the PR already reviewed.
44
+
45
+ **A fired signal is not a verdict — disprove it.** Soft signals fire on deliberately-partitioned PRs. Observed: two PRs sharing two issue refs and all of `reset_hint=` / `resetHint` / `terminalFailure`, provably unrelated — one handed the other a specific emit site in its own body, their exact-string pins were punctuation-distinct so neither could match the other's site, and **both were test-only**. That generalizes: **a test-only PR cannot invalidate what another PR asserts**, and neither can a docs-only one.
46
+
47
+ **`git merge-tree --write-tree <branch-a> <branch-b>` disproves a fired signal without inference.** It performs the merge in-memory and writes a tree, exiting non-zero with the conflicting paths on stdout only when the merge genuinely conflicts. That is a real answer, not an inference from a behind-count — being behind is not evidence of conflict. `rc=0` with a written tree means the two branches merge clean; run it on `files` before holding. It answers only whether the two trees conflict textually, not whether one PR's content invalidates the other's — the same-issue, stacked-branch, and shared-symbol conditions still decide that.
48
+
49
+ Obeying a fired signal blindly stalls the queue on a non-conflict; ignoring one is sloppy. Do the work, report which evidence settled it.
50
+
51
+ ## The labelled head
52
+
53
+ `ready-to-merge` is a finisher's verdict on one tree, and it does not expire when that tree does. **A GitHub label does not follow the branch** — #180 is the record, and the query below is what reads it: `labeled ready-to-merge`, then commits and a `head_ref_force_pushed`, then `merged`, with no `unlabeled` anywhere between. The label stayed put while the head moved out from under it. Every other guard in this chain — the finisher's dispatch pin, the halt on a moved head, the worktree audit — runs *before* the label exists, so none of them is watching this window. You are the last gate, and **re-deriving the head is a requirement here, not bot discretion**: merge only a head that still carries the audit the label stands for.
54
+
55
+ **Read the timeline before `gh pr update-branch` and before anything else that can move the head.** Your own rebase lands commits after the label by construction, so once you have rebased this read can no longer tell your commits from someone else's:
56
+
57
+ ```bash
58
+ gh api "repos/{owner}/{repo}/issues/<pr>/timeline?per_page=100" --paginate \
59
+ -q '.[] | select((.event == "labeled" and .label.name == "ready-to-merge")
60
+ or .event == "committed" or .event == "head_ref_force_pushed")
61
+ | .event + " " + (.sha // .label.name // "")'
62
+ ```
63
+
64
+ A `committed` or `head_ref_force_pushed` line after the last `labeled ready-to-merge` means the head moved after the audit. **Refuse: report `head-moved-after-label-#<pr>` and stop on that PR.** Leave the label where it is — you audited nothing and removing another member's verdict is not yours to do. What clears it is a **fresh** finisher against the new head; the first audit does not transfer, because it verified a different tree.
65
+
66
+ **Nothing after that label line is the normal case, and it proceeds untouched** — label applied, head unchanged, merge goes ahead exactly as it did before this gate existed. Record the head before you rebase — `gh pr view <pr> --json headRefOid -q .headRefOid` — because step 3 hands it to the merge gate as `--pre` and nothing later can reconstruct it. Where step 1 runs, that is its `pre`; on an already-current PR it is simply the head you merge.
67
+
68
+ What this gate deliberately does not answer. It does not ask *who* audited — a hand-added `ready-to-merge` with no finisher behind it reads clean here, and the reviewer-only rule in `run-team/SKILL.md` is what owns that. And a head rebased after the label by an **earlier, abandoned pass of this command** refuses too: that tree is one no finisher audited either, so the halt is correct rather than a false positive.
69
+
70
+ ## Per-PR sequence
71
+
72
+ For each labeled PR clearing the hold rule, lowest first:
73
+
74
+ **Before step 1, check the ledger for an unresolved conflict hold on this PR (#2064).** Read the ticket row that names it — the same lookup step 4 below uses (`ledger.mjs read`). A `conflict-hold:#<pr>` token with no `fix-pr-<n>` settled (`applied:`/`no-op`) *after* it — reading the row left to right, past whatever dispatched after the LATEST hold token — is unresolved: a fix-applier already owns this PR's conflict, from this pass or an earlier one. **Skip it**: do not rebase, do not touch the row, do not report `rebase-fallback-#<pr>` again. Report `conflict-held-#<pr>` and move to the next labeled PR. Only once a fix-applier dispatched after the hold has settled does it clear — proceed through the sequence below as normal from there.
75
+
76
+ 1. If the PR is behind `origin/main`, update it **server-side first**: `gh pr update-branch <pr> --rebase`. That's an API call, not a push — no local git command runs, so the force-push classifier denial this step used to hit (`git push --force-with-lease`, judged and intermittently denied per invocation — 2 allowed / 2 denied on byte-identical invocations in one session; `settings.json` has since gained an `autoMode.allow` entry for exactly that command, so adding one is not the missing fix) never enters. The call is async, so this is two blocks. The fire block reads the head the rebase starts from and makes the call, in seconds:
77
+
78
+ ```bash
79
+ branch=$(gh pr view <pr> --json headRefName -q .headRefName)
80
+ ref="refs/heads/$branch"
81
+ pre=$(git ls-remote origin "$ref" | cut -f1)
82
+ [ -n "$pre" ] || { echo "no such remote ref: $ref"; exit 2; }
83
+ out=$(gh pr update-branch <pr> --rebase 2>&1); rc=$?
84
+ printf 'rc=%s branch=%s pre=%s\n%s\n' "$rc" "$branch" "$pre" "$out"
85
+ ```
86
+
87
+ The poll block waits for the head to move, handed `rc`, `branch` and `pre` off the fire block's report line:
88
+
89
+ ```bash
90
+ rc=<rc>; branch=<branch>; pre=<pre> # off the fire block's report line, never re-derived here
91
+ [ -n "$rc" ] && [ -n "$branch" ] && [ -n "$pre" ] || { echo "rc, branch and pre come from the fire block"; exit 2; }
92
+ ref="refs/heads/$branch"
93
+ post=$pre
94
+ if [ "$rc" -eq 0 ]; then
95
+ for _ in $(seq 1 60); do # 5 min cap, never an unbounded `until`
96
+ post=$(git ls-remote origin "$ref" | cut -f1)
97
+ [ -n "$post" ] && [ "$post" != "$pre" ] && break
98
+ sleep 5
99
+ done
100
+ fi
101
+ pr_head=$(gh pr view <pr> --json headRefOid -q .headRefOid)
102
+ if [ "$rc" -eq 0 ] && [ -n "$post" ] && [ "$post" != "$pre" ]; then
103
+ for _ in $(seq 1 60); do # PR object lags the ref (measured 84s-2min); same cap as above
104
+ [ -n "$pr_head" ] && [ "$pr_head" != "$pre" ] && break
105
+ sleep 5
106
+ pr_head=$(gh pr view <pr> --json headRefOid -q .headRefOid)
107
+ done
108
+ fi
109
+ printf 'rc=%s branch=%s pre=%s post=%s pr_head=%s\n' \
110
+ "$rc" "$branch" "$pre" "$post" \
111
+ "$pr_head"
112
+ ```
113
+
114
+ **Fire once; only the poll is ever re-issued.** `pre` is the one reading nothing after the rebase can reconstruct: once the rebase lands, the ref it was read from *is* the rebased head. So a fire block run a second time reads the rebased head as its `pre`, `gh pr update-branch` answers `UNPROCESSABLE: There are no new commits on the base branch`, and a rebase that landed reports as the already-current row below, never verified. The poll only reads, so re-issuing it with the same `rc` and `pre` is safe — and it is the half that gets cut off. Each of its loops is capped at 60 × 5s, and the PR object's measured lag alone outruns that cap on the common landed-with-lag path (#1895's own repro: 75.6s wall-clock at re-poll attempt 14, 129.2s at attempt 24 — a separate measurement from the pr_head-catchup pass below, whose attempt 14/24 wall-clock times differ from these). One re-issue is enough, never a loop of them: the ref poll alone ends inside the 600000 ceiling below, so a re-issued poll finds the ref already moved on its first read and waits out only the PR object's cap. The poll:
115
+
116
+ `bash` backgrounds any call past about 60s even with `timeout` set — so run the poll block in one Python `eval` cell through `subprocess.run`, its cell `timeout` at 900s or more, above both caps back to back; never `bash` plus `wait`.
117
+
118
+ **Poll `git ls-remote`, not `gh pr view headRefOid`** — the PR object's head is precisely the field that desyncs, so polling it asks the one source that can be wrong about the thing you are waiting for. Measured, feigi/claude-config#903: the rebase landed and moved the branch ref, `headRefOid` stayed on the pre-rebase SHA with `mergeable_state: unknown` and no CI run on the new head, and the loop burned all 60 iterations reading a landed rebase as un-landed — straight into the fallback, whose local rebase would then have replayed commits the remote already carried. `ls-remote` reads the ref itself and carries no local state, the same reason the `fetch.prune` note below re-derives a reading from `git ls-remote origin` rather than trusting a number measured while the ref was missing. Keep the `headRefOid` read, as the `pr_head` the printf reports: it is no longer the gate, and its *disagreement* with `post` is the desync signal you want on the record. That is why the poll block re-polls it only once the ref has moved — to let the PR object catch up, never to decide whether the rebase landed.
119
+
120
+ **Check the call's exit status before polling, and bound the poll.** The head never moving *is* the failure case, so an `until` that waits for it to move spins forever in exactly the states the fallback exists for — the escapes named below are unreachable from a loop that never exits. Read the four outcomes off `rc` and `post`:
121
+
122
+ - `rc=0`, `post` **non-empty**, and `post != pre` → the rebase landed. Hold `pre` and `post`, step 4's proof needs both.
123
+ - Non-zero `rc` carrying `UNPROCESSABLE: There are no new commits on the base branch` → it was already current, so `pre` and `post` are simply equal. Shouldn't happen here since you only call this when behind.
124
+ - Any other non-zero `rc`, **or** `post` still equal to `pre` once the cap runs out → the fallback below, not a retry.
125
+ - **`post` empty once the cap runs out** → the ref read failed; this is never "the rebase landed". An empty `post` satisfies `post != pre` all by itself, so without this row a failed `ls-remote` is classified as success — the same hole `[ -n "$pre" ]` closes on the way in, and the loop's own `[ -n "$post" ]` is why an empty read cannot break out early. Take the fallback below, and report the ref as unreadable rather than as a head that never moved.
126
+
127
+ **`post != pre` with `pr_head` still on `pre` is not a desync until it SURVIVES a bounded re-poll.** The PR object lags the ref move, so a `headRefOid` read taken in the same instant as the rebase reproduces the desync signature exactly while nothing is wrong. Measured twice in one run on 2026-09-01: it cleared on re-poll attempt 24 (~2 min) in one pass and attempt 14 (~84s) in the next, both after `gh pr update-branch --rebase` returned `rc=0`. So re-poll `headRefOid` on the same bounded cap you already use for `ls-remote` before calling this, and report the desync only if `pr_head` is still on `pre` when that cap runs out. The poll block's second loop is that re-poll: a `pr_head` it prints still on `pre` beside a moved `post` has already survived the cap, so report it as printed and never poll a second round. Reporting it on a single read costs a pass for a state that fixes itself, and it is the reading a bot gets when it does everything else right.
128
+
129
+ **`pr_head` still empty once the re-poll cap runs out is neither outcome above — and the empty value alone does not say why.** The break condition (`[ -n "$pr_head" ] && [ "$pr_head" != "$pre" ]`) needs a read to succeed before it can even compare to `pre`, the same hole `[ -n "$post" ]` closes for the ref poll above; each pass overwrites `pr_head` with its own re-read, so an empty value here only proves the LAST read of the cap failed — a `gh pr view` outage on every call (API, auth, or network) prints identically to one that failed only on that final call after 59 reads that would otherwise have shown a real desync. Either way an empty string is not "still on `pre`" — the desync case above needs `pr_head` to actually read `pre`, and this one produced no reading at all on its last try. Report the PR-object read as unreadable rather than folding it into either the desync above or the landed row it prints beside, and do not feed an empty `pr_head` into the close-and-reopen check below — there is no head there for `git merge-base --is-ancestor` to place.
130
+
131
+ **A desync that DOES survive the cap is the one state that needs a controller.** The rebase landed; GitHub's PR object did not follow. CI is bound to the stale head or absent entirely, so the merge gate cannot clear no matter how long you wait, and no merge-bot action fixes it — do not retry the rebase, and do not rebase locally, because the remote is already correct. Report it and stop.
132
+
133
+ **The controller's remedy is close-and-reopen, and it has a precondition that must be checked FIRST.** Reopening requires the PR's recorded head to still be reachable from the branch — and a rebase orphans it by construction, which is the very event that produced the desync. So before closing anything, run `git merge-base --is-ancestor <pr_head> origin/<branch>`. Non-ancestor → **do not close**: GitHub refuses to reopen a PR whose head is unreachable (measured on #903 — three reopen attempts, `Could not open the pull request` each time), and the only recovery is opening a replacement PR from the same branch, which loses the review thread and every label on it. Close-and-reopen is normally reversible; past an orphaning rebase it is a one-way door.
134
+
135
+ This also repairs a branch carrying a merge commit — GitHub's rebase drops those too.
136
+
137
+ **A worktree for this branch, if one exists, goes stale here** — the API rebased the remote, not your checkout. Expected, not a divergence. To prove it holds nothing unique, run `git cherry origin/<branch> HEAD` from the worktree **before the merge, never after**, and **not** `git cherry origin/main HEAD`: `main` never contained this PR's commits before the merge either, so it reads `+` for all of them regardless of staleness and proves nothing (measured, feigi/claude-config#149). The window is the point: GitHub deletes the remote branch when the PR lands — the same reason step 4 never passes `--delete-branch` — so `origin/<branch>` outlives the merge only until the next pruning fetch, and step 4's `prove-merge.sh` runs one seconds later (`grep -n 'git fetch --quiet origin' scripts/prove-merge.sh`, plain, which prunes under the `fetch.prune=true` this machine's global config sets — `git config --show-origin --get fetch.prune`). Past that fetch the probe fails on a missing ref, an error easy to misread as the divergence it was meant to rule out.
138
+
139
+ **Neither result halts this path, and a `+` here is not the diverged-worktree STOP.** The clean answer is the absence of a `+`, not the absence of output: `git cherry` prints a line per commit in `origin/<branch>..HEAD`, `-` where the upstream already holds an equivalent patch and `+` where it does not, so it never goes silent merely because the rebase superseded everything. A worktree that has not fetched since the API rebase — the state this step leaves it in, since no local git command runs here — reads nothing; one that has fetched reads `-` for every rebased commit. Both are clean (measured 2026-08-29 in a scratch repo: a bare remote, a branch rebased onto an advanced `main` and force-pushed, and a clone left at the pre-rebase head — `git cherry origin/feat HEAD` printed nothing before that clone fetched and a `-` per rebased commit after, while an unpushed commit added on top raised a `+` in both). A `+` names a commit the worktree holds and that branch does not — say so alongside the merge, since it is the only signal that something local is unpushed, but it does not stop the merge, because nothing local reaches the remote from here: this step rebases through the API and pushes nothing, and step 4 merges the remote head, so an unpushed local commit is structurally unable to enter the merge. That STOP lives in the fallback (server-side rebase unavailable) and does not halt for the reason just ruled out here: neither path can carry a local commit to the remote, because neither pushes. What differs is what gets verified — the fallback rebases the worktree and verifies *that* head, so a commit only the worktree holds makes the verified tree something other than the reviewed head; here the worktree is only read, never rebased, so a `+` is a report, not a halt.
140
+
141
+ **Two, and only two, reasons this can't be used:** a real conflict, or `allow_update_branch` off on the repo. Both are whole-branch failures — GitHub's rebase replays every commit or none, no partial credit. Either → the fallback below, not a retry.
142
+
143
+ **Fallback (server-side rebase unavailable).** Rebase locally, for verification only — this rebase never needs to reach the remote. The branch usually lives in a worktree (`git worktree list`) — rebase there, not the main checkout.
144
+
145
+ **Confirm the worktree head *is* the reviewed remote PR head before rebasing** — a mismatch means the rebase would fold an unreviewed local commit into the tree you verify, while the merge takes the remote head without it:
146
+
147
+ ```bash
148
+ git -C <worktree> rev-parse HEAD
149
+ git ls-remote origin refs/heads/<branch> | cut -f1 # the operand the arms below turn on
150
+ gh pr view <pr> --json headRefOid -q .headRefOid # recorded, NOT the gate (-q, or you compare a SHA to JSON)
151
+ ```
152
+
153
+ **Compare the worktree head against the branch REF, and never against `gh pr view <pr> --json headRefOid -q .headRefOid`** — the PR object's head is the field that desyncs from the branch, which is why step 1 polls `git ls-remote` rather than it. Never `git rev-parse origin/<branch>` either: that is this clone's cached copy of the ref, so a worktree sitting on a stale copy agrees with it by construction and every tree this check exists to catch passes. The `headRefOid` read stays, and stays demoted — a value disagreeing with the ref is the PR-object desync above, a fact for the report, never the operand this check turns on. **An empty ref read is neither equal nor a mismatch**: the read failed, or the head branch is not on `origin` at all (a fork PR), so report the ref as unreadable and stop, `blocked` — an empty string compares unequal to every sha, so without this clause a failed read renders as a diverged worktree, the same hole `[ -n "$pre" ]` closes on the way into the poll above.
154
+
155
+ **Why the ref and not `headRefOid`: during the PR object's lag both operands go stale in the SAME direction, so that compare fails OPEN as readily as it fails closed.** The false STOP is the visible half — the worktree holds the rebased head, the PR object still holds the pre-rebase sha, and a correct tree comes back `worktree-diverged-#<pr>`, costing a pass. The silent half is the one that ships: a worktree that has not fetched since the rebase sits on that same pre-rebase sha, so BOTH sides read it, the check reads **Equal**, and this fallback verifies a tree the remote no longer has while step 4 merges the head it does — a green measured against a tree no merge will take, which is the exact failure the STOP arm below exists to prevent, reached through the arm that passes. Measured at the sibling site (`run-team/SKILL.md` phase 1, #1168) in a scratch repo: a clone unfetched since the rebase resolved `origin/<branch>` to the pre-rebase commit with its subject unchanged, while `git ls-remote origin refs/heads/<branch>` read the true tip from that same clone. **Re-reading `headRefOid` on a settle window does not reach that half at all** — it fires only where the two disagree — which is why the operand changes here rather than the verdict gaining a window.
156
+
157
+ **Unequal → `git fetch origin` and read the ref once more, then decide on that second reading. Bounded at one re-read, never a third.** Neither operand is a cached value, so a stable second reading cannot flip the verdict; what the re-read is for is the ref MOVING while you verify, which is live here because one way into this fallback is a step-1 poll whose cap ran out with the ref unmoved, and that call is async — it can land a moment after you gave up on it. The two readings differ → the head is not settled and the audit behind the label verified a tree that is already gone, so **refuse: report `head-moved-after-label-#<pr>` and stop**, label untouched, the same verdict and the same remedy — a fresh finisher against the new head — the gate above reaches for a head that moved after the audit. Do not read a third time; that is the unbounded wait step 1 had to be written out of. The two readings agree → the mismatch is real and belongs to one of the two arms below. **`Equal` is not among the outcomes a surviving mismatch can reach**: a worktree that is not on the branch ref never passes this check, whatever the PR object says.
158
+
159
+ **Ahead or behind is `git cherry origin/<branch> HEAD` from the worktree, run after that fetch — not the sha compare.** A rebase orphans the pre-rebase head, so the ref does not carry the worktree's commits BY SHA even where it carries every patch in them; read the mismatch as "commits the ref lacks" and a worktree holding no work of its own answers yes and takes the STOP. Patch equivalence is the question, and `git cherry` is the instrument this step already uses for it: a `+` → ahead; no `+` → behind, a worktree the rebase superseded included.
160
+
161
+ - **Equal** → proceed.
162
+ - **Worktree ahead** → STOP, report `worktree-diverged-#<pr>`. A fix-agent that committed locally but never pushed, or was aborted mid-fix, leaves an unpushed, unreviewed commit that a clean-tree audit passes. Nothing on this path pushes, so that commit cannot enter the merge — what it corrupts is the verification: rebase on top of it and both the `origin/main...HEAD` diff and the suite run against a tree that is not the reviewed head, while any merge takes the remote head, so the content-equivalence this path depends on is gone and a green says nothing about what would land. It fails silently, which is why this halts rather than proceeding on the green. The reviewed head lives on the remote, not here; hand the choice back with the PR.
163
+ - **Worktree behind, or no worktree at all** → not a divergence. Rebase from the remote head (`git fetch` first) and say which you used.
164
+
165
+ **Plain `git fetch origin` only — never `git fetch origin <src>:<dst>`.** `fetch.prune=true` is
166
+ in effect here, set in `~/.gitconfig` rather than by anything this repo ships — `git config
167
+ --show-origin --get fetch.prune` prints the file it came from, where a bare `git config --get`
168
+ only says it is on. So it travels with this machine, not with the clone: it applies in every
169
+ repo this operator fetches in, and not at all for anyone whose global config lacks it. Pairing
170
+ prune with an explicit refspec **deletes the very ref the refspec names**. Reproduced
171
+ 2026-08-19 in a scratch clone: `git fetch origin main:refs/remotes/origin/main` printed
172
+ `- [deleted] (none) -> origin/main`, took the remote-tracking refs from 10 to 8, and left
173
+ `refs/remotes/origin/HEAD` dangling; in the live checkout the next `git rev-list` failed with
174
+ `unknown revision`. Do not reason about which refs are "outside" the refspec — the destination
175
+ itself goes. A plain `git fetch origin` restores it. Re-derive whatever reading you were taking
176
+ from `git ls-remote origin`, which carries no local state, rather than trusting a number
177
+ measured while the ref was missing.
178
+
179
+ Run the **no-undo audit**, then before merging: diff `origin/main...HEAD` hunk by hunk — nothing but this PR's own change may appear — suite green on the rebased head, and `gh pr view <pr> --json mergeable,mergeStateStatus` reading `MERGEABLE`/`CLEAN` with the label still present, re-checked at the merge instant. Step 4 then merges whatever is actually on the remote — the pre-rebase head, since nothing here was pushed — content-equivalent to what you just verified, not graph-identical to it. Report this path as `rebase-fallback-#<pr>` with the reason; see step 4 for why its proof comes back disproved on purpose.
180
+
181
+ **A repo that gates on currency cannot merge from this path — and this one does.** The fallback leaves the remote head behind `origin/main` on purpose, which is the exact condition `rebase-check` fails on: `.github/workflows/ci.yml` checks out `pull_request.head.sha` and exits 1 when the merge-base is not the base tip. It is an expected job, so `ci-state.mjs` reports non-green, step 3's gate never opens, and `mergeStateStatus` cannot read `CLEAN` either. The four checks above are still the honest verification of the *content*, but they do not clear that gate. So here the fallback **ends without merging**: report `rebase-fallback-#<pr>` as blocked and hand it back — choosing between resolving the conflict and turning `allow_update_branch` on is a human's call. Step 4's merge is reachable from this path only where no expected job gates on currency.
182
+
183
+ **When that hand-back is a conflict, record it on the ledger before you report — your report is gone when you exit, and nothing else durable says the PR is stuck (#2064).** It is a conflict when the fallback's local rebase stopped on conflicting paths, whether you then resolved them for verification or aborted: nothing on this path pushes, so the remote head still carries the conflict either way. Not when the server-side rebase failed only because `allow_update_branch` is off and the local rebase applied clean — there is nothing for a fix-applier to resolve. The stopped rebase already named the conflicting paths — read them before you resolve or abort (`git -C <worktree> diff --name-only --diff-filter=U`) — so a later auditor can tell what collided from the row text alone, without re-reading this report (#2064 story 15). Append the hold to the ticket row that names the PR — the row whose first `PR#` mention is `PR#<pr>`, or the row keyed `#<pr>` when none does — as one rewrite of that row's own text, never a bare line — **unless it already carries one unresolved.** Read the row fresh (below) before writing: if its last `conflict-hold:#<pr>` has no `fix-pr-<n>` settled after it, the row already says what you are about to say — a duplicate write teaches the tick nothing new and can reset a live fix-applier's `fixSince` out from under it. Report `rebase-fallback-#<pr>` and stop there; only write when the row's last hold (if any) has a settled fix-pr after it, or carries no hold at all.
184
+
185
+ ```bash
186
+ ~/.fleet/bin/fleet-run ledger.mjs read # the row: `#<key> <text>`
187
+ ~/.fleet/bin/fleet-run ledger.mjs row <key> "<text> · conflict-hold:#<pr> (conflict: <path1>, <path2>)"
188
+ ```
189
+
190
+ `<text>` is everything after the key, verbatim — `row` rewrites the whole line, so a token you drop is gone. `#<pr>` is this PR, never the one it conflicts with; the tick refuses a hold naming another PR. The `(conflict: …)` note is free text, comma-joined paths from the `diff --name-only` read above — placed *after* the token, never before, so it cannot fall inside `PR_MENTION`'s first-match binding or `CONFLICT_HOLD`'s own pattern. From then on the tick prints `DISPATCH fix-pr PR#<pr>` for it and counts it in `held=` until a fix-applier dispatched after the hold settles `applied:`/`no-op`. Skip the `row` write on an already-unresolved hold, per the paragraph above — nothing else about this path changes: still report `rebase-fallback-#<pr>`, still hand it back.
191
+
192
+ 2. Watch checks settle **on the rebased head**. A missing release label (`patch`/`minor`/`major`) fails `validate-release-label` — add the one matching; `release-label.yml` defines that job and exits 1 when the count of those three is zero. A stale `rebase-check` failure usually means step 1 has not landed. Where a repo chains jobs behind that check with `needs:`, they come back `skipped` rather than red and the currency check is the only thing to fix — check `ci.yml` for a `needs:` chain before assuming that: it declares none as of this reading, so no job is currently skipped behind `rebase-check`.
193
+
194
+ **Hold the wait inside one blocking call — you are turn-based and cannot "keep an eye on" a run.** If you push and then end your turn, your pass stops there and nothing resumes it: whatever wakes you is external and may never come. Observed repeatedly — a bot rebases, pushes, goes idle, and the queue silently stalls with the PR one command from merging. Block instead, on the run step 3's first gate reading names — its `ci.runId` — the wait:
195
+
196
+ `bash` backgrounds any call past about 60s even with `timeout` set, so hold the wait in one Python `eval` cell that polls `gh run view <run-id> --json status,conclusion` through `subprocess.run` until `status` reads `completed`, its cell `timeout` well above the CI cycle.
197
+
198
+ A CI cycle here runs ~5-6 minutes. Never `sleep`-poll in a loop you exit early.
199
+
200
+ **The wait returning is permission to look, not a verdict.** It tells you the run reached a terminal state, not which one — and that state can still change under you afterwards (step 3's second run exists for that). The decision is step 3's gate, run again, never the wait's own exit status.
201
+
202
+ **You are the only place currency is proven, so never merge on a green from before your rebase.** The reviewer's green attests the diff was correct against *its* base — that claim does not expire and does not cover yours. Only a run on the rebased head shows it is still correct against current `main`.
203
+
204
+ **Triage a post-rebase red by what the pre-rebase run did.** Green before, red after, with no change of your own between, means a sibling merge broke this PR semantically — a rebase applies cleanly and still breaks the build when someone renamed a symbol it uses. That is a **finding, not a chore**: report it and hand it back to the reviewer with the failing job. Red both before and after is also the reviewer's. You fix only the mechanical failures you caused: conflict resolution and the release label.
205
+
206
+ 3. **Gate the merge with `merge-gate.mjs`, run twice, and merge only on the second run's exit 0.**
207
+
208
+ ```bash
209
+ ~/.fleet/bin/fleet-run merge-gate.mjs --pr <pr> --pre <pre> --post <post> \
210
+ --out <scratch>/pr<N>/merge-bot-<n>/ci.json; rc=$?
211
+ ```
212
+
213
+ `--pre` is the head you recorded at **The labelled head**; `--post` is the head step 1's rebase produced — omit it when no rebase ran, which is the same as passing `pre` twice. `pr<N>` is this PR and `merge-bot-<n>` is your own name, so the reading lands under a directory only you write, never in the scratch root by itself: that root is injected into every dispatched member and shared with every sibling. The gate is read-only — it runs the instrument re-check, `gh pr view <pr> --json labels,reviewDecision,headRefOid` and `ci-state.mjs --pr <pr>`, answers their conjunction, and never merges, labels, rebases or waits. Stdout is exactly one JSON line, `{pr, verdict, reason, head, pre, post, behind, instruments, ci}`; stderr is its children's diagnostics, so never fold `2>&1` into the line you read. Read `rc` straight off the call, as above — never through a pipe.
214
+
215
+ 1. **Run it.** Exit 0 → go to 2. 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. 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 — right after `gh pr update-branch --rebase`, the id step 2's wait blocks on does not exist yet, so never route this into step 2's `gh run watch`/`gh run view <run-id>` with a null id. 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>`, the same as any other exit 1. Any other exit 1 → skip the PR, report `<reason>-#<pr>` (`head-moved-after-label-#<pr>`, `label-pulled-#<pr>`, `changes-requested-#<pr>` …), leave the label where it is, and move on. Exit 2 → stop on that PR and report `<reason>-#<pr>`: the gate could not evaluate — a finding about the tree, the tooling or the API, never about the PR. Re-run once only for `rate-limited`, a quota refusal that clears by itself.
216
+ 2. **Run it again immediately before `gh pr merge`, and merge only on that second exit 0.** Anything else takes the same arms as 1, and nothing merges.
217
+
218
+ Each `reason` is a fact the gate now enforces, not a step you run:
219
+
220
+ - **`head-moved-after-label`** — the PR head is neither `pre` nor `post`. **Any third SHA is a push that landed while you waited on CI, and no CI check can see it**: `ci-state.mjs` selects the run whose `headSha` equals the *current* PR head (`scripts/ci-state.mjs`, the `r.headSha === prHead` filter), so a member's push plus its own green run satisfies every CI check while the audit behind the label belongs to a tree that is gone. The remedy is a fresh finisher against the new head, label untouched.
221
+ - **`behind:<n>`** — you are the only place currency is proven, and a sibling merge since your rebase expires it (the staleness below).
222
+ - **`instrument-set-changed` / `instruments-unanswerable`** — the instrument re-check the controller runs before its own gates (`run-team/SKILL.md`, **You read your instruments out of a tree every member can write to**), taken at this seat because nothing dispatches a merge bot to read that rule. Report `<reason>-#<pr>` with what the gate printed, leave the label alone, and do **not** re-run the gate.
223
+ - **`ci:…`** — bound to the *run*, not to check conclusions. `gh pr checks` aggregates across runs and reports a `pass` inherited from a **cancelled** run on a superseded SHA; head-SHA binding alone misses it, since the head is right and only the conclusions belong elsewhere. `ci-state.mjs` binds run head, `status`, and every expected job from one query, and reports non-green unless the run's head matches the PR head, `status` is **completed**, and every expected job is present and succeeded. That presence requirement is what catches the case above — a force-push cancels the run under you, its finished jobs go on reporting what they concluded, and whatever never ran is missing from the run entirely, which reads as `pending` in an aggregating checks summary, never here: `ci-state.mjs` names it in the reason `expected jobs absent from the run: …` and refuses green.
224
+
225
+ **Why twice: a conclusion can invert under a fixed run id.** A rerun rewrites the *existing* run rather than creating a new one, so a run id you read as `success` can later read `failure` with nothing pushed to the branch. Observed twice in one fleet run, on two PRs: a refresh workflow re-ran the currency check after `main` advanced and flipped the same id on the same SHA. And a CI wait puts minutes between the first reading and the merge — minutes in which the label can be pulled and the instrument set can change. Never carry a reading across a wait; the second run is the reading the merge rests on.
226
+
227
+ 4. `gh pr merge <pr> --merge` (no-ff). It can exit silently — confirm with `gh pr view <pr> --json state,mergedAt,mergeCommit` before claiming it merged. **Never `--delete-branch`**; GitHub removes the remote branch anyway.
228
+
229
+ **`--merge` (no-ff) is load-bearing, not stylistic — and do not let a content claim reach you worded as a graph-shape one.** It always writes a **two-parent** merge commit, even where the branch is trivially fast-forwardable, and step 5's proof *requires* that: `prove-merge.sh` dies at `has no second parent — not a merge commit` and exits **2** on a single-parent merge. Exit 2 is "could not evaluate the claim at all", not "the claim is false" — so a real fast-forward leaves you with no proof to report and a halt, not a failed proof. Measured on #908: a controller brief predicted "the merge will be a fast-forward", and the merge tree *was* byte-identical to the reviewed head (`988f29d1`, `git diff <pin> <merge>` empty) — but the commit still had two parents, which is the only reason the proof was available. "The merge adds nothing" is a statement about content; **never write it as "fast-forward", which is a statement about shape, and which would have broken step 5.**
230
+
231
+ **Prove which head landed.** A rebase-then-merge leaves no trace of *which* version went in, and "I rebased" is exactly the claim asserted without doing it:
232
+
233
+ ```bash
234
+ ~/.fleet/bin/fleet-run prove-merge.sh <pre-rebase-head> <rebased-head> <merge-commit>
235
+ ```
236
+
237
+ **No rebase happened because the PR was already current? Pass the head twice.** That is the normal case in a pass, not an edge case, and `pre == post` selects a proof path built for it. Never invent a plausible-looking `pre` to make the arguments differ — a `pre` that never landed satisfies the pre-rebase leg by construction, and passing one is the single easiest way to turn a stale merge into `proved=true`.
238
+
239
+ **Read `gates`, not the flat fields.** The payload's flat fields are observations, and one of them being true or false says nothing about the verdict on its own. `gates` is the verdict's own working: `proved` is true exactly when every value in it is true. Membership is per-invocation — on the rebase path it carries `preDidNotLand` (leg 1), on the no-rebase path it does not, because leg 1 is dropped there. That is why `preIsAncestor:true` sits next to `proved:true` on the no-rebase path and is **not** a contradiction: leg 1 wants it false, and leg 1 is not a gate on that path (#18). A sanity check written against `preIsAncestor === false` rejects correct merges; write it against `gates` instead.
240
+
241
+ Exit **0** proved, **1** disproved, **2** the script could not evaluate the claim at all — the merge is unreachable from `origin/main`, is not a merge commit, or an argument does not resolve. Treat 2 as "ask a human", not as a disproof.
242
+
243
+ **A `rebase-fallback-#<pr>` merge is expected to disprove here.** Step 1's fallback never lands a rebased head on the remote, so `pre == post` and `headWasCurrent` reads false — `prove-merge.sh` exits **1**, correctly (`prove-merge.test.mjs`'s `ATTACK: un-rebased head that merged cleanly still proves false` pins exactly this shape). That is the honest answer, not a script fault. Report the merge as **argued** — backed by the fallback's four checks — and never as `proved`; a merge whose ancestry was not proved is never reported as proved.
244
+
245
+ **Drop `in-progress` from every issue this PR closes** — the merge is the only point where the ticket number and the fact of completion are known together, and nothing else clears it:
246
+
247
+ ```bash
248
+ ~/.fleet/bin/fleet-run drop-merged-label.sh <pr> --apply
249
+ ```
250
+
251
+ Exit 0 done or nothing to close, **1 a removal failed — report it as `label-drop-failed-#<issue>`, never swallow it**: a merged ticket that keeps the label is invisible the moment it is reopened. Exit 2 means the PR was not actually MERGED yet — call this only after the merge is confirmed at the top of this step.
252
+
253
+ Then re-fetch and **re-evaluate the queue from scratch** — labels and numbers move while CI runs, and a merge newly unblocks or blocks others.
254
+
255
+ **Staleness fires *within* a pass, and it compounds.** The first merge makes every other PR behind — including the second of this same pass, verified green minutes ago. The gate's `behind` re-reads currency before **each** merge, and refuses a behind head as `behind:<n>` — step 3.1's ordinary skip-and-report arm, same as any other exit 1: label untouched, report `behind:<n>-#<pr>`, move on to the next candidate. That PR is rebased again only if it is still labelled when a **later** merge in this pass drives the next queue re-evaluation from scratch (step 4's last line) and selects it fresh from step 1 — nothing retries it on the strength of the skip alone, and a pass that merges nothing else after skipping it reports the skip, not a retry. Any behind-count handed to you at dispatch is already expired.
256
+
257
+ Measured over one three-merge pass: the next queue member went 0 → 2 → 7 → **10 behind** without ever changing, because each merge adds its own commits plus a merge commit. So the *last* PR in a pass pays the largest rebase and the longest CI cycle, and a PR rebased early pays again for every sibling that lands after it — so never rebase a PR before it is the actual merge candidate.
258
+
259
+ **A PR whose heavy jobs have only ever `skipped` is getting its first real verification from your rebase.** Reviewers may legitimately have labelled on the checks that did run plus local evidence, saying so explicitly. When your post-rebase run finally executes those suites, treat a red there as a **genuine first result**, not a regression you caused — read the failing job before concluding, and do not hand it back as "the rebase broke it".
260
+
261
+ Report merged / skipped-unlabeled / held-behind-#X / worktree-diverged-#X / head-moved-after-label-#X / label-drop-failed-#X / rebase-fallback-#X / instrument-set-changed-#X / `<reason>-#X` for any other gate refusal / blocked after the pass — a dispatched bot once, at exit, after its grace (**Grace, then one report**, below).
262
+
263
+ ## No-undo audit (before every rebase)
264
+
265
+ A rebase resolved the wrong way silently reverts work already in `main`. It looks like an ordinary conflict resolution and passes CI, because the branch's own tests never covered what it undid. Never resolve blind.
266
+
267
+ **1-3. Do not destroy unpushed work, preview conflicts, and name the work at risk** — what `main` gained in the conflicting files since the branch forked:
268
+
269
+ ```bash
270
+ ~/.fleet/bin/fleet-run no-undo-audit.sh <worktree> <branch>
271
+ ```
272
+
273
+ It refuses (exit 1) on a dirty worktree. Exit **2** is not that refusal: it means the audit could not answer at all — a bad argument, no such worktree, a worktree git does not answer for (its linkage is broken, and git still answers at rc 0 — for the enclosing repo when the `.git` is gone, from another worktree's HEAD and index when it names that worktree's admin dir, against another directory's files when `core.worktree` moves the working tree there), `BASE_REF` is not spelled `origin/<branch>` or `refs/remotes/<path>` (#1565), `BASE_REF` names the audited branch (#1565), a ref that does not resolve, a probe that could not run, or a conflicting path no pathspec can name — and it emits no payload. What it will **not** do is spend a 2 on the formatting of `worktree` or `branch`: those two echo the arguments you handed it rather than reporting a finding, so an escaper that cannot render one leaves that field and its `*Rewritten` flag as JSON `null` and the run still delivers `clean`, `stash`, `conflicts[]` and `atRisk[]` at its own exit code, naming the field and the escaper on stderr. Read a `null` there as "this run could not render the path or branch you passed in" — it is **never** "there is no worktree", and never a path: pasting it into a command builds a pathspec matching nothing, the same empty-reads-as-proven trap the `conflictsRewritten[]` note below describes. Treat 2 as "ask a human", never as "the worktree is dirty"; there is nothing to commit and hunting for it wastes the pass. **Never** `git clean`, `git checkout .`, `git reset --hard`, or `git stash` to make it pass — that work is unrecoverable and is not on the remote, and stashing it clears `porcelain` so the audit passes on the next run without the work ever shipping. The stash count it prints is reported, not gated: the stack is repo-global across worktrees, so a nonzero count is usually the maintainer's. It can also come back `unknown` rather than a number. Usually the list came back empty and the audit cannot call that an empty stash: `refs/stash` is not absent, which an unreadable ref, an unreadable reflog, or a ref pointing at a missing object each produce just as a genuinely empty stash would. The fourth cause is the opposite shape: `refs/stash` **is** absent while its reflog is not, so the entries it names are unreachable rather than gone. One cause is neither shape: `git stash list` printed entries and then exited nonzero, so what it printed is short — a corrupt loose object behind an entry that is not the tip does this, and the audit reports `unknown` there rather than the number it could have counted. The audit's line says which of them you have. None is the same thing as an empty stash and the audit no longer conflates them. The number it prints is a floor, not a proof: a reflog that is merely truncated — some entries lost, the rest still parsing — drops the missing entries from `git stash list` itself, so the audit and your own read of the list come up short by the same ones and neither reports it. Read `git stash list` yourself when the count is nonzero **or `unknown`** — an entry naming this branch may be a dead member's only copy — and never pop, drop or apply an entry you did not create. On `unknown` do not stop at that list: the causes git stays silent about leave it empty at rc 0, so the list alone shows you nothing. 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`, naming that cause outright, so read that line first. The corrupt loose object is named outright too — `fatal: loose object … is corrupt`, printed after the entries git could read — and the audit's own line carries that text for you either way. For the causes it stays silent on, read the files behind it. Set `c=$(git rev-parse --git-common-dir)` — the stack is repo-global, and a linked worktree's `.git` is a file, so `.git/refs/stash` reaches nothing — then `ls -l "$c"/refs/stash "$c"/logs/refs/stash`, where a mode of `----------` on either, or a `Permission denied` from `ls` itself, is the fault, and `cat "$c"/logs/refs/stash`, which still names the branch when `refs/stash` is the unreadable one. `No such file or directory` for `refs/stash` alone, with the reflog listing beside it, is the fourth cause: recover from the SHAs `cat` prints, do not rebase over it. A missing `refs/stash` file is not an empty stash: `git gc` packs it into `packed-refs`. When both reads instead come back with nothing to recover from — `cat` denied, or a reflog that is present but blank — `git show refs/stash` still resolves the ref whether loose or packed, printing the `WIP on <branch>` label; 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. 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. 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: `git stash list` is still empty at rc 0, `git show refs/stash` answers `ambiguous argument` and `git stash show -p refs/stash` answers `not a valid reference`, and no SHA was printed to hand them instead. Restore read permission where the mode is yours to fix — on whichever of the two files `ls` gave a `----------`, or on the `logs/refs` directory when `ls` failed before printing a mode at all. Only the both-files-unreadable shape then has `git stash list` name the entry again on its own, measured, because the ref file's own content was never touched, only its permission. The other two shapes leave `refs/stash` itself broken — deleted, or holding garbage text — 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. `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. 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. Where there is no mode left to fix — both files are simply gone, with nothing in `packed-refs` and no reflog to read either — `git fsck` still prints a `dangling commit <sha>` line per stash entry, objects loose or packed — at a nonzero exit in the unreadable-ref shape, so read its lines and not its status — and `git stash show -p <that sha>` prints the hunk there, refusing anything that is not a stash (`is not a stash-like commit`). 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. Read the at-risk commits the audit lists first; those are what a careless resolution deletes.
274
+
275
+ **4. Take `main`'s side wholesale, then re-apply the branch's delta on top.** Never blanket `-X ours` / `-X theirs`. The branch's side is by definition *pre-merge* text — on a docs or comment hunk it carries claims a later PR already corrected, and keeping it reintroduces them silently.
276
+
277
+ **5. Before pushing, prove nothing was undone:**
278
+
279
+ ```bash
280
+ git diff origin/main...HEAD -- <conflicting files>
281
+ ```
282
+
283
+ Three dots, never two: a two-dot diff on a stale branch renders `main`'s gains as deletions and reads as a mass revert. Every hunk must be the PR's own intended change. A deletion of a line `main` introduced that this PR has no business touching means the resolution ate merged work — redo it. Re-derive any numbers, offsets or anchors the conflict touched rather than carrying stale ones.
284
+
285
+ `<conflicting files>` is the audit's `conflicts[]`, not typed by hand — and `conflictsRewritten[]` sits next to it for exactly this step. A path is reported at the same index in both arrays; `true` there means the path held a control byte the audit could not give a JSON short form to and replaced with a space, so the string in `conflicts[]` is not the byte-for-byte name of anything on disk. Pasting it into the command above builds a pathspec that matches nothing — the diff comes back empty, and empty reads as "nothing to prove", the opposite of unproven. Skip the command for any path flagged `true` and inspect it by hand (`git status`, or `ls` the worktree) instead of by pathspec.
286
+
287
+ ## Grace, then one report
288
+
289
+ **Only a bot a controller dispatched holds a grace** (`/skill:run-team`, or any caller that says it owns the watcher); the top-level invocation arms its Monitor instead (**Then stay armed**). You were dispatched on the first `ready-to-merge` label, never after anyone's report, and a label landing minutes after your last merge is the common case — so the pass does not end the moment the queue empties. It drains, then waits **15 minutes** for late labels, then reports once:
290
+
291
+ - Grace starts once no labelled PR is actionable — every one merged, skipped or held. Seed the labelled set then, the way **Then stay armed** seeds its Monitor, so a PR you already handled does not re-fire.
292
+ - Every 60s, poll `gh pr list --state open --label ready-to-merge --limit 200 --json number`. A number not in the seed → **re-run selection from the top**, hold rule included, drain what it makes actionable, and restart the grace after that drain. A failed poll is no reading: keep the seed and poll again. A poll that returns 200 numbers is not a whole reading either — gh stops at `--limit` with exit 0 and no warning, so a label past it is unseen: act on the numbers it did return, and name `poll-capped-at-200` in the report, so the controller knows the grace's silence covered only the first 200.
293
+ - 15 minutes with no new label → report and exit.
294
+
295
+ The wait:
296
+
297
+ `bash` backgrounds any call past about 60s even with `timeout` set — hold the whole grace in one Python `eval` cell that polls `gh` through `subprocess.run`, its cell `timeout` at 1000s or more; never `bash` plus `wait`, which then returns "Skipped due to a queued background completion".
298
+
299
+ **One report, at exit, and none before it** — every PR this pass touched, in the vocabulary above, a pass that merged nothing included. The controller reaps on that report and records each `held-behind-#<lower>` on the held ticket's row, so a report sent mid-pass is one it acts on too early.
300
+
301
+ Your `task` result is the report, delivered when you exit.
302
+
303
+ ## Then stay armed
304
+
305
+ **Skip this whole section if a controller dispatched you** (`/skill:run-team`, or any
306
+ caller that says it owns the watcher) — hold the grace above instead. A
307
+ monitor armed by a member dies with that member and the queue stops silently, so
308
+ the watcher belongs to whoever outlives the pass. Only arm one when you are the
309
+ top-level invocation.
310
+
311
+ The pass ends, the queue does not. Once no labeled PR is actionable, arm a persistent Monitor so a later sign-off restarts the loop without re-running this command:
312
+
313
+ ```bash
314
+ cap=200 # the poll's --limit; gh stops there with exit 0 and no warning
315
+ poll() { gh pr list --state open --label ready-to-merge --limit "$cap" --json number --jq '.[].number' 2>/dev/null; }
316
+ capped=
317
+ capcheck() { # a full page may have been cut there: say so once, and once when it clears
318
+ if [ "$(printf '%s\n' "$1" | grep -c .)" -ge "$cap" ]; then
319
+ [ -n "$capped" ] || echo "ready-to-merge monitor DEGRADED: labelled-PR list hit its --limit $cap — a label past it fires nothing, silence is NOT an empty queue"
320
+ capped=1
321
+ elif [ -n "$capped" ]; then
322
+ echo "ready-to-merge monitor RECOVERED: labelled-PR list under its --limit $cap — every label watched again"
323
+ capped=
324
+ fi
325
+ }
326
+ if seed=$(poll); then
327
+ seen=" $(printf '%s\n' "$seed" | tr '\n' ' ')"
328
+ capcheck "$seed"
329
+ else
330
+ echo 'ready-to-merge monitor: seed poll failed, not arming'
331
+ exit 1
332
+ fi
333
+ while true; do
334
+ sleep 60
335
+ if cur=$(poll); then
336
+ capcheck "$cur"
337
+ while IFS= read -r n; do # capture-then-loop: heredoc-fed, never `for n in $cur`
338
+ [ -n "$n" ] || continue # a blank line in OUR OWN list, not a probe that could not look
339
+ case "$seen" in *" $n "*) ;; *) echo "ready-to-merge label added: PR #$n" ;; esac
340
+ done <<EOF
341
+ $cur
342
+ EOF
343
+ seen=" $(printf '%s\n' "$cur" | tr '\n' ' ')"
344
+ fi
345
+ done
346
+ ```
347
+
348
+ Arm with `persistent: true`, description `ready-to-merge label on this repo's PRs`. Details that matter:
349
+
350
+ - Seed `seen` **before** the loop so PRs already handled — including ones skipped for `CHANGES_REQUESTED` or left on red CI — do not re-fire every minute. Only a label appearing after arming is an event. The seed poll is guarded the same way as every tick: a `gh` call failing on the very first poll must not arm on an empty `seen`, which would replay the whole labeled set as spurious events on tick one.
351
+ - The `if cur=$(poll)` guard — seed and every tick alike — keeps `seen` intact when a `gh` call fails transiently; without it a failed poll reads as an empty labeled set and either arms on nothing (the seed) or wipes `seen` (a tick), both replaying the full labeled set as events on the next successful poll. The guard depends on `poll` ending in the bare `gh` call, not in a pipe: `tr` sits at the call sites (not inside `poll`) precisely so a failing `gh` call's exit status reaches `cur=$(poll)` / `seed=$(poll)` instead of being swallowed by `tr`, which exits 0 regardless of what it reads.
352
+ - **A full page is not a whole reading either.** `gh pr list` stops at its `--limit` — 30 when the flag is absent — with exit 0 and no warning, so `poll` passes an explicit one (`cap`, one variable for the flag and the check), and `capcheck` says once when a poll fills it and once when one comes back under it: the DEGRADED/RECOVERED latch `run-team/SKILL.md`'s CI Monitor uses for the same cause, and never a line per tick. The numbers a capped poll did return are still real events; the line is for the labels past them, which fire nothing while it holds.
353
+ - **The per-PR loop is heredoc-fed on purpose — `for n in $cur` is the one form that cannot work here.** This runs under zsh, which word-splits an unquoted command substitution's result but *not* an unquoted parameter expansion, and `cur` is a parameter. Measured on zsh 5.9 with `seen="849 850 "` and `cur="849 850 852 "`: the bare form runs **one** iteration with the whole list glued into a single value and emits `ready-to-merge label added: PR #849 850 852`, one nonsense event naming no PR, while the real new PR is never reported; the heredoc form emits `PR #852` alone. `run-team/SKILL.md`'s **Shell traps** carries the mechanism, the remedy table and the `</dev/null` trap that bites the next command added inside this loop. Note the contrast with step 1's `for _ in $(seq 1 60)`: that is a command substitution, it splits, and it is correct as written.
354
+ - 60s poll — remote API, stay off rate limits.
355
+ - A held PR stays in `seen`, so its own label will not re-fire. Fine: what unblocks it is the **lower** PR getting labeled, which does fire, and step 4's re-evaluation picks up both in numeric order.
356
+
357
+ On an event, do not merge that PR on sight — **re-run selection from the top**, hold rule included. Report each outcome and leave the monitor armed. One watch per session; stop it with `proc://<id>/kill`.
@@ -0,0 +1,17 @@
1
+ ---
2
+ description: Print the exact command to start the fleet run. Does not start it. Use when `run-team` isn't showing up in your picker.
3
+ ---
4
+
5
+ This command only prints instructions — it never starts the fleet itself.
6
+
7
+ `run-team` is a `disable-model-invocation` skill, invoke-only by design (the
8
+ fleet writes to a live repo and must never start unasked). That flag also
9
+ hides it from the human `/` picker, not just from the model's own
10
+ auto-invoke list (#1381) — so there is nothing to browse to
11
+ there.
12
+
13
+ To start the fleet, type this exactly — don't pick it from a list, type it:
14
+
15
+ /skill:run-team [implementers] [reviewers]
16
+
17
+ Both arguments are optional, default 2 implementers and 6 reviewers, with no hard cap. Example: `/skill:run-team 3 2`.
package/package.json ADDED
@@ -0,0 +1,23 @@
1
+ {
2
+ "name": "@feigi/fleet-ctl",
3
+ "version": "0.0.0",
4
+ "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
+ "license": "Apache-2.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/feigi/fleet-plugin.git",
9
+ "directory": "plugin"
10
+ },
11
+ "files": [
12
+ "agents",
13
+ "commands",
14
+ "skills",
15
+ "scripts",
16
+ ".claude-plugin",
17
+ "LICENSE",
18
+ "NOTICE"
19
+ ],
20
+ "omp": {
21
+ "extensions": ["scripts/member-write-guard.mjs"]
22
+ }
23
+ }
@@ -0,0 +1,59 @@
1
+ // #102. PR #75 made `./agent-test <dir>` work, but the two documents that brief
2
+ // members still said `<file>`. Neither was falsified — a file argument works —
3
+ // so the capability stayed invisible to exactly the audience #75 was for: agents
4
+ // type a directory anyway, and before #75 the resulting MODULE_NOT_FOUND red got
5
+ // misread as a finding against the diff under review.
6
+ //
7
+ // Measured against this worktree's own runner before being written down: a
8
+ // directory holding one test file ran it (`ℹ tests 1`, exit 0), and an empty
9
+ // directory printed `agent-test: no test files under <dir>` and exited 1. The
10
+ // refusal is the half that has to be documented with the capability — appending
11
+ // nothing to argv leaves it empty, and bare `node --test` then discovers the
12
+ // whole worktree, a green for a suite nobody asked for.
13
+ //
14
+ // The clause is pinned VERBATIM in both documents, and by one regex set, because
15
+ // the two are the same brief written twice: run-team/SKILL.md's Phase 1 step and
16
+ // references/isolation.md's rationale for it. A fix landing in only one leaves
17
+ // whichever the reader reached still file-only.
18
+ //
19
+ // NOT pinned, deliberately — these mention `./agent-test` without claiming an
20
+ // argument shape, so they are not this ticket's class: the "filesystem isolation
21
+ // is not stack isolation" guard in both documents, the reused-worktree note in
22
+ // run-team/SKILL.md, review-and-fix.md's specialist test command, and
23
+ // references/reaping.md's note that the runner is an ignored file.
24
+ //
25
+ // THE CEILING, same as refuter-scratch-prose.test.mjs: PRESENCE pins over a
26
+ // bounded slice. A whole new sentence appended after the clause, carving out an
27
+ // exception, stays green; text spliced inside one does not. A reflow stays green
28
+ // by design — the words are pinned, not their layout.
29
+ import { test } from "node:test";
30
+ import assert from "node:assert/strict";
31
+ import { readFileSync } from "node:fs";
32
+ import { join } from "node:path";
33
+ import { between, phrase } from "./prose-pin.mjs";
34
+
35
+ const REPO = join(import.meta.dirname, "..");
36
+ const read = (...p) => readFileSync(join(REPO, ...p), "utf8");
37
+ const RUN_TEAM = read("skills", "run-team", "SKILL.md");
38
+ const ISOLATION = read("skills", "run-team", "references", "isolation.md");
39
+
40
+ const slices = [
41
+ ["run-team/SKILL.md", () =>
42
+ between(RUN_TEAM, "Materialize the isolation envelope as a file", "A reused worktree may lack the runner", "run-team/SKILL.md")],
43
+ ["references/isolation.md", () =>
44
+ between(ISOLATION, "## Materialize the isolation envelope as a file", "## Filesystem isolation is not stack isolation", "references/isolation.md")],
45
+ ];
46
+
47
+ for (const [name, slice] of slices) {
48
+ test(`${name} briefs the runner with a shape that admits a directory`, () => {
49
+ assert.match(slice(), phrase("`./agent-test <file-or-dir>`"));
50
+ });
51
+
52
+ test(`${name} says a directory expands to the test files under it`, () => {
53
+ assert.match(slice(), phrase("A directory works too and expands to the test files under it"));
54
+ });
55
+
56
+ test(`${name} says a directory with no test files refuses`, () => {
57
+ assert.match(slice(), phrase("one holding none refuses rather than passing vacuously"));
58
+ });
59
+ }