@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,470 @@
1
+ # shellcheck shell=sh
2
+ # Reading worktree state for the fleet's shell scripts: the porcelain listing,
3
+ # path predicates more than one script asks, and in-progress operation state.
4
+ # Sourced, never executed — no shebang, and the `shell=sh` directive above is
5
+ # what tells shellcheck what to check it as.
6
+ #
7
+ # Source it as:
8
+ #
9
+ # wt_lib="$(dirname "$0")/worktree.sh"
10
+ # [ -r "$wt_lib" ] || die "cannot read $wt_lib"
11
+ # # shellcheck source-path=SCRIPTDIR
12
+ # # shellcheck source=worktree.sh
13
+ # . "$wt_lib" || die "$wt_lib failed to load"
14
+ #
15
+ # The `[ -r ]` is not belt-and-braces and the `|| die` alone is not enough. `.`
16
+ # is a POSIX *special builtin*, so failing to open its operand aborts a
17
+ # non-interactive shell outright and the `||` never runs. json.sh carries that
18
+ # measurement across five shells; it is the same builtin and the same trap here,
19
+ # and this file is sourced by the same scripts.
20
+ #
21
+ # Not folded into json.sh, which is scoped to JSON escaping: a filesystem
22
+ # predicate and a `git` reader are neither. #725
23
+
24
+ # The byte `wt_listing` substitutes for a newline found INSIDE a worktree path.
25
+ #
26
+ # \001 because the listing's own STRUCTURE cannot produce one, which is the
27
+ # property the swap actually needs: nothing git emits to hold the format
28
+ # together carries a control byte — the attribute keywords are fixed words, an
29
+ # object id is hex, and a ref name rejects them outright (`git check-ref-format`
30
+ # exits 1, `git branch` refuses). So a \001 reaching `$wt_list` is never part of
31
+ # the format, and can never be read as a delimiter or an attribute.
32
+ #
33
+ # That is the whole guarantee. Two things it deliberately does NOT claim, both
34
+ # load-bearing:
35
+ #
36
+ # It is not a claim that no byte anywhere in the listing can be a \001.
37
+ # `locked <reason>` carries free-form text the operator wrote, and git neither
38
+ # rejects nor sanitizes a control byte in it — measured, git 2.50.1: `git
39
+ # worktree lock --reason` accepts a \001 and the listing hands it straight back.
40
+ # Inert here, for reasons worth stating rather than assuming: a lock reason is
41
+ # never a path, no caller passes one to `nl_path`, and after the `tr` it sits on
42
+ # its own line that no `/^worktree /` or `/^branch /` matches. (`prunable`'s
43
+ # reason is git's own fixed prose, so it has no such hole.)
44
+ #
45
+ # And it is not a claim that a \001 in a PATH proves a newline was there. A path
46
+ # may hold one natively; `nl_path` says so, and says why refusing on both is the
47
+ # answer rather than guessing which it was. What the byte does establish is the
48
+ # only thing any caller needs: this is a path the reader cannot hand back to the
49
+ # filesystem byte for byte.
50
+ wt_nl=$(printf '\001')
51
+
52
+ # Does $1 carry the byte `wt_listing` substituted for a newline?
53
+ #
54
+ # The substitution is not injective: a path that really holds a \001 answers
55
+ # true here too. Deliberate, and it is why the answer is a refusal rather than a
56
+ # repair — both inputs are paths this reader cannot reproduce byte for byte, and
57
+ # refusing on both is correct where guessing which one it was is not.
58
+ nl_path() {
59
+ case $1 in
60
+ *"$wt_nl"*) return 0 ;;
61
+ esac
62
+ return 1
63
+ }
64
+
65
+ # Read the worktree listing into `$wt_list`, in a form where a newline inside a
66
+ # path cannot end a record. On success `$wt_err` is empty; on failure `$wt_list`
67
+ # is empty and `$wt_err` names the cause.
68
+ #
69
+ # A worktree path may legally contain a newline (APFS and ext4 both allow it),
70
+ # and the plain porcelain terminates every attribute with one — so one record
71
+ # split into two and every consumer's `substr($0,10)` truncated the path at the
72
+ # newline. Measured on a real linked worktree at `.../wt/fix-33<LF>slug`, git
73
+ # 2.50.1: three scripts each handed a downstream consumer a path not on disk,
74
+ # and none of them refused. #551, the defect #185 fixed in inflight.sh.
75
+ #
76
+ # `--porcelain -z` terminates every attribute with NUL instead, which needs git
77
+ # 2.36.0 — a floor this repo already exceeds through no-undo-audit.sh's
78
+ # `git merge-tree --write-tree --name-only -z`.
79
+ #
80
+ # NOT `awk -v RS='\0'`. That is a gawk/BWK extension, and the awk this fleet
81
+ # actually runs on macOS — /usr/bin/awk, BWK awk 20200816 — does not merely
82
+ # ignore it: it stops dead at the first NUL and reports ONE record for a listing
83
+ # of any length. Measured under #185, all three spellings, `-v RS='\0'`,
84
+ # `-v RS='\000'` and `BEGIN{RS="\0"}`, every one of them `count=1`. No awk
85
+ # program can hold a NUL byte either, so the swap has to happen before awk sees
86
+ # the stream at all.
87
+ #
88
+ # One `tr` pass does it, exactly as inflight.sh's probe 3 does: NUL becomes the
89
+ # newline every awk here already splits on, and a newline inside a path becomes
90
+ # `$wt_nl`. `tr` translates simultaneously from one table, so the two mappings
91
+ # cannot feed each other the way two piped stages would. Every existing
92
+ # `/^worktree /`, `/^branch /` and `substr($0,10)` reads the result unchanged,
93
+ # and git's own `\0\0` record separator arrives as the blank line the plain
94
+ # porcelain already emitted — so an ordinary path parses byte for byte as
95
+ # before.
96
+ #
97
+ # A temp file, and it is not incidental: `-z`'s separator is NUL and no shell
98
+ # variable can hold one, so the swap cannot happen inside a command
99
+ # substitution around git. It also keeps git's status readable on its own — a
100
+ # pipeline reports only its last stage, so `$(git … | tr …)` would report `tr`'s
101
+ # and a git that could not run at all would read as an empty listing, which is
102
+ # an answer several callers act on.
103
+ #
104
+ # `LC_ALL=C` on the `tr` rather than inherited: under a UTF-8 locale BSD `tr`
105
+ # exits 1 on a byte that is not valid UTF-8, and such a byte reaches a worktree
106
+ # path from any filesystem that does not police names. Every caller pins the
107
+ # locale globally already; a sourced helper does not get to assume that.
108
+ #
109
+ # `wt_list` and `wt_err` are this function's OUTPUT, read by the sourcing script
110
+ # and never again in here, which is what SC2034 sees when it checks this file on
111
+ # its own — `check-tracked.sh '*.sh' shellcheck -x -S warning` runs it standalone
112
+ # as well as through each caller.
113
+ # shellcheck disable=SC2034
114
+ wt_listing() {
115
+ wt_list=
116
+ wt_err=
117
+ wt_tmp=$(mktemp) || {
118
+ wt_err="could not create a temporary file to hold the worktree list"
119
+ return 1
120
+ }
121
+ # `2>&1 >"$wt_tmp"` in that order: stderr is duplicated onto the substitution
122
+ # FIRST, then stdout is pointed at the file. The substitution's status is
123
+ # git's own, so a git that could not run is distinguishable from one that
124
+ # produced a listing — and the cause is git's own prose rather than a guess.
125
+ if ! wt_err=$(git worktree list --porcelain -z 2>&1 >"$wt_tmp"); then
126
+ rm -f "$wt_tmp"
127
+ [ -n "$wt_err" ] || wt_err="git worktree list failed"
128
+ return 1
129
+ fi
130
+ if ! wt_list=$(LC_ALL=C tr '\n\000' '\001\n' <"$wt_tmp"); then
131
+ rm -f "$wt_tmp"
132
+ wt_list=
133
+ wt_err="could not read the worktree list from $wt_tmp"
134
+ return 1
135
+ fi
136
+ # git writes on stderr at rc 0 too, and that text is not a failure — clear it
137
+ # so `[ -n "$wt_err" ]` never reads a warning as one.
138
+ wt_err=
139
+ rm -f "$wt_tmp"
140
+ # Explicit, because `rm` would otherwise be the last command and hand its own
141
+ # status to every caller: a temp file that could not be unlinked is a leak,
142
+ # never a reason to tell a caller the listing failed to read.
143
+ return 0
144
+ }
145
+
146
+ # Is $1 established ABSENT, or merely a path this script cannot stat? A bare
147
+ # `[ -e ]` failure is both — an unreadable parent (dropped mount, chmod'd
148
+ # ancestor) fails it identically to a directory that was actually removed — and
149
+ # only the second is nothing to protect. Walk up to the nearest ancestor that is
150
+ # there and require THAT to be searchable: only then is "not there" a
151
+ # measurement rather than a guess. The walk is what keeps `rm -rf .worktrees`
152
+ # answerable — the parent goes with the child, and testing the immediate parent
153
+ # alone reads its absence as unknown, which is the permanent refusal the callers
154
+ # exist to stop producing.
155
+ #
156
+ # `[ ! -L "$look" ]` in the loop condition, and it is the whole of #725. Every
157
+ # `test` primary except `-L` STATS, so it follows a symlink: on a dangling one
158
+ # `-e` is false while `-L` is true, and the predicate answered established-absent
159
+ # for a path `git worktree add` treats as occupied. Measured — worktree-audit.sh
160
+ # reported such a path as `MISSING on disk` with `ahead=0, dirty=0`, which is
161
+ # what the fleet controller reads to decide whether a replacement member would
162
+ # redo work or destroy it. Same `-e`/lstat split #188 fixed one layer up in
163
+ # claim-ticket.sh.
164
+ #
165
+ # In the LOOP condition rather than as a fourth clause on the result, because
166
+ # that placement answers a second shape for free: a dangling symlink standing in
167
+ # for an ANCESTOR. The walk stops on it, `[ -x ]` through it is false, and the
168
+ # answer is unknown — where a `[ ! -L "$1" ]` bolted onto the result would still
169
+ # have called `/dangling/child` established-absent. For $1 itself the walk never
170
+ # starts, `look` stays `$1`, and `[ -x "$1" ]` through the dangling link is
171
+ # false, so the existing result line needs no change at all.
172
+ #
173
+ # A dangling worktree link arrives by two routes with OPPOSITE claim states, and
174
+ # this predicate must hold under both: rc-0 residue behind a `git worktree
175
+ # remove` that deleted a symlink's target, with no live claim; and
176
+ # release-ticket.sh's rc-255 halt path, which leaves the link with the branch and
177
+ # the `in-progress` label still alive — a live claim, mid-release, that failed
178
+ # partway. "Not established-absent" is the only answer true of both. #728
179
+ #
180
+ # `look=${look:-/}` INSIDE the loop, and that placement is the whole of #178:
181
+ # `${p%/*}` on `/x` yields the empty string, not `/`, so a path whose every
182
+ # ancestor below the root is gone used to fall out on "" and answer unknown about
183
+ # an absence the searchable root proves. The same restore written AFTER the loop
184
+ # reads identically and is wrong — nothing enters the loop on an empty `$1`, so
185
+ # it would rewrite that to `/` too and turn `gone ""` into established-absent.
186
+ # Inside, it only ever rewrites what the loop just truncated. gone-walk.test.mjs
187
+ # holds that matrix, `gone ""` included, because no caller can reach it: the
188
+ # callers test the path non-empty first, and worktree-audit.sh reads its own off
189
+ # `git worktree list`, which never emits an empty one — so a caller-level suite
190
+ # alone cannot tell the two placements apart.
191
+ #
192
+ # `!=`, not a non-empty test: `${p%/*}` returns p unchanged when p holds no
193
+ # slash, so the emptiness form spins forever on one. git emits absolute paths to
194
+ # every caller, but a delete script may not hang on the input that proves
195
+ # otherwise.
196
+ #
197
+ # One definition, in one file, because every caller asks one question. Answered
198
+ # separately they drift, and the halves of this fleet that protect a member's
199
+ # work stop agreeing about whether there is any work there to protect — which is
200
+ # exactly what #725 found: three copies, and only one compensating, at a call
201
+ # site rather than in the predicate.
202
+ #
203
+ # 0 ONLY for established absent; 1 covers present AND cannot-stat, so a caller
204
+ # needing those apart pairs this with its own `[ ! -e ]`, as release-ticket.sh's
205
+ # dirty check does. Condition context only: a bare `gone` returns 1 on the
206
+ # ordinary present answer and `set -e` exits.
207
+ #
208
+ # $1 must be absolute; a relative operand can answer 1 for a path that is
209
+ # genuinely absent.
210
+ gone() {
211
+ # A path carrying the byte `wt_listing` substituted does not name the file git
212
+ # named, so every `test` below asks about a DIFFERENT path — one that is
213
+ # reliably not there, which is why the walk answered established-absent for it
214
+ # and each caller then acted on that. Measured: release-ticket.sh emitted its
215
+ # newline refusal and then a second blocker on the same path asserting the
216
+ # directory "is gone" and naming `git worktree prune` as the remedy, for a
217
+ # worktree on disk holding an uncommitted file and for which prune is a no-op
218
+ # — the permanent-refusal shape the surrounding guards exist to prevent.
219
+ # Refused in the predicate rather than at each call site for the reason the
220
+ # rest of this comment gives: answered separately, the callers drift. #551
221
+ nl_path "$1" && return 1
222
+ look=$1
223
+ while [ ! -e "$look" ] && [ ! -L "$look" ] && [ "$look" != "${look%/*}" ]; do
224
+ look=${look%/*}
225
+ look=${look:-/}
226
+ done
227
+ [ ! -e "$1" ] && [ -x "$look" ]
228
+ }
229
+
230
+ # Which git operation does the worktree at $1 have in progress, and which
231
+ # branch does that operation hold?
232
+ #
233
+ # Sets `wt_op` to the in-progress marker found in its admin dir (empty: none),
234
+ # and `wt_op_held` to the space-separated `refs/heads/<b>` a stopped rebase or
235
+ # bisect holds (empty: none). Returns 1 when the admin dir cannot be read —
236
+ # "cannot tell", never "nothing in progress" — and every caller fails closed on
237
+ # it. Condition context only, like `gone`.
238
+ #
239
+ # The in-progress markers are the states git records while an operation runs.
240
+ # Measured, git 2.50.1 (Apple Git-155): `git worktree remove` WITHOUT `--force`
241
+ # removes a worktree holding an interrupted rebase, and one holding a bisect, at
242
+ # exit 0 — both leave `git status --porcelain` empty, so the sequencer state,
243
+ # the todo list and the original head go with the directory. The remaining
244
+ # sequencer states leave staged or unmerged paths behind, so a dirty check
245
+ # already answers for them; they are listed anyway because a state git records
246
+ # is cheaper to test than to argue about.
247
+ #
248
+ # The held branch is the half `git worktree list --porcelain` cannot give.
249
+ # Only a rebase and a bisect DETACH HEAD, and a detached worktree's porcelain
250
+ # record carries `detached` instead of a `branch refs/heads/<b>` line — yet git
251
+ # still counts the branch as that worktree's: measured, git 2.50.1, `git branch
252
+ # -D` refuses "used by worktree" for a sibling stopped at a `rebase -i` edit
253
+ # step and for one mid-bisect, both listed `detached`. git answers out of the
254
+ # admin dir: `rebase-merge/head-name` or `rebase-apply/head-name` hold the full
255
+ # `refs/heads/<b>`, `BISECT_START` holds the SHORT name `<b>` the bisect started
256
+ # from. `MERGE_HEAD`, `CHERRY_PICK_HEAD` and `REVERT_HEAD` leave HEAD on its
257
+ # branch, so the porcelain `branch` line already names what they hold. A
258
+ # head-name of `detached HEAD` names no branch and is not collected. A bisect
259
+ # started from a detached HEAD is different: `BISECT_START` holds that HEAD's
260
+ # full SHA, which the code below still turns into `refs/heads/<sha>` and
261
+ # collects — matching only a branch literally named with that 40-hex string,
262
+ # which nothing in this fleet's naming ever produces. #2218
263
+ #
264
+ # `2>/dev/null` on the admin-dir read, NOT the `2>&1` the fleet's message-text
265
+ # captures fold in, because this capture is used as a PATH. Measured (PR #985
266
+ # review): a `~/.gitconfig` with a key outside any section makes every git
267
+ # command print `error: key does not contain a section: …` to stderr AT EXIT 0,
268
+ # so `2>&1` returns that line glued in front of the git dir, every `[ -e ]`
269
+ # below then matches nothing, and a worktree holding an interrupted rebase reads
270
+ # as holding nothing at all.
271
+ #
272
+ # A rebase state dir that exists but cannot be searched is "cannot tell" too:
273
+ # `[ -e ]` on the `head-name` inside it fails exactly as it does on a head-name
274
+ # that is not there, and only the second is an answer.
275
+ #
276
+ # `wt_op` is this function's OUTPUT, read by the sourcing script; so is
277
+ # `wt_op_held`, read by `wt_holding` below and by worktree-audit.sh (#2220) —
278
+ # SC2034, as for `wt_listing`.
279
+ #
280
+ # The admin dir is normally found by asking git FROM $1 (`rev-parse
281
+ # --absolute-git-dir`), which needs nothing but $1's own `.git` pointer file —
282
+ # so a worktree this reader cannot even enter (a bare permission bit on $1
283
+ # itself) answers "cannot read" exactly as intended: nothing about $1 being
284
+ # unreadable says anything about whether its admin dir agrees, and this
285
+ # function must not go looking behind that refusal. Pass a non-empty $2 only
286
+ # when the CALLER has independently established $1 does not exist AT ALL —
287
+ # `[ -e "$1" ]`, never git's own `prunable`: measured, git 2.50.1, a worktree
288
+ # chmod 000'd (still there, merely unreadable) is marked `prunable` in the
289
+ # porcelain too, identically to one `rm -rf`'d out from under git, so
290
+ # `prunable` cannot tell the two apart and a reader keyed on it would reopen
291
+ # the chmod-000 case this function must keep closed. Only once $1 is
292
+ # confirmed gone does this function look for the admin dir a different way:
293
+ # `worktrees/*/gitdir` under THIS repo's own git dir names every admin dir by
294
+ # the worktree path it was registered for, and that registry lives under this
295
+ # repo's `.git`, never under the worktree — a directory `rm -rf`'d out from
296
+ # under git leaves its bookkeeping, and whatever rebase or bisect state it
297
+ # held, untouched. #2218
298
+ # shellcheck disable=SC2034
299
+ wt_op_state() {
300
+ wt_op=
301
+ wt_op_held=
302
+ if [ -n "${2:-}" ]; then
303
+ wt_op_dir=
304
+ wt_op_common=$(git rev-parse --git-common-dir 2>/dev/null) || return 1
305
+ for wt_op_gitdir in "$wt_op_common"/worktrees/*/gitdir; do
306
+ [ -e "$wt_op_gitdir" ] || continue
307
+ wt_op_reg=$(cat "$wt_op_gitdir" 2>/dev/null) || continue
308
+ [ "$wt_op_reg" = "$1/.git" ] || continue
309
+ wt_op_dir=${wt_op_gitdir%/gitdir}
310
+ break
311
+ done
312
+ [ -n "$wt_op_dir" ] || return 1
313
+ else
314
+ wt_op_dir=$(git -C "$1" rev-parse --absolute-git-dir 2>/dev/null) || return 1
315
+ [ -n "$wt_op_dir" ] || return 1
316
+ fi
317
+ for wt_op_m in rebase-merge rebase-apply MERGE_HEAD CHERRY_PICK_HEAD REVERT_HEAD BISECT_LOG; do
318
+ if [ -e "$wt_op_dir/$wt_op_m" ]; then wt_op=$wt_op_m; fi
319
+ done
320
+ for wt_op_m in rebase-merge rebase-apply; do
321
+ if [ -d "$wt_op_dir/$wt_op_m" ] && [ ! -x "$wt_op_dir/$wt_op_m" ]; then return 1; fi
322
+ done
323
+ for wt_op_f in rebase-merge/head-name rebase-apply/head-name BISECT_START; do
324
+ [ -e "$wt_op_dir/$wt_op_f" ] || continue
325
+ wt_op_ref=$(cat "$wt_op_dir/$wt_op_f") || return 1
326
+ case $wt_op_f in BISECT_START) wt_op_ref=refs/heads/$wt_op_ref ;; esac
327
+ case $wt_op_ref in
328
+ refs/heads/?*) wt_op_held="${wt_op_held:+$wt_op_held }$wt_op_ref" ;;
329
+ esac
330
+ done
331
+ return 0
332
+ }
333
+
334
+ # Which registered worktree holds branch ref $1 (`refs/heads/<b>`), by either
335
+ # route git itself counts: checked out, per its porcelain `branch` line, or held
336
+ # by a rebase or bisect stopped in a detached worktree, per `wt_op_state`. Reads
337
+ # `$wt_list` as `wt_listing` last left it, so a caller wanting a fresh answer
338
+ # re-reads the listing first.
339
+ #
340
+ # 0: held — `wt_holder` names the worktree and `wt_holder_how` the route, as a
341
+ # clause (`is checked out`, …) to follow the branch name in a message.
342
+ # 1: no worktree holds it.
343
+ # 2: cannot tell — `wt_holder` names a worktree whose record this reader
344
+ # cannot resolve even through `wt_op_state`'s registry route: its listed
345
+ # path cannot be handed back to git (`nl_path`), or its admin dir cannot be
346
+ # found or read there either.
347
+ #
348
+ # Detached records only go to `wt_op_state`, deliberately: a worktree whose
349
+ # record carries a `branch` line is answered by that line, and an unreadable
350
+ # one of those holds nothing a stopped rebase or bisect could add — so it is
351
+ # never allowed to turn into a "cannot tell" that halts every caller.
352
+ #
353
+ # A worktree `rm -rf`'d out from under git keeps its detached record — git
354
+ # marks it `prunable` — and keeps its admin dir, which lives under THIS
355
+ # repo's `.git`, never under the worktree itself. `[ -e ]` on the listed path,
356
+ # not git's own `prunable` (measured: a merely chmod-000'd worktree, still
357
+ # there, is marked `prunable` too — the two are not the same fault), is what
358
+ # tells `wt_op_state` it may look for that admin dir a different way; the
359
+ # ordinary route — asking git FROM the worktree's own directory — cannot,
360
+ # because there is no directory left to ask from. #2218
361
+ #
362
+ # A record naming neither a `branch` nor the literal `detached` line is a HEAD
363
+ # git itself could not classify from the worktree's own directory — measured,
364
+ # git 2.50.1: an admin `HEAD` file holding garbage (not a ref, not a SHA)
365
+ # emits neither line, exactly the shape a corrupted mid-rebase HEAD produces.
366
+ # That corruption is confined to the `HEAD` FILE's bytes; the admin dir
367
+ # holding it, and whatever `rebase-merge`/`BISECT_START` state sits beside it,
368
+ # is untouched — so this case resolves through the SAME registry route as a
369
+ # gone worktree, unconditionally, rather than answering "cannot tell" for a
370
+ # worktree that may hold nothing of this caller's at all. Only once even that
371
+ # route cannot read an admin dir does this fall back to "cannot tell". #2218
372
+ #
373
+ # Each record is read whole before it is judged — `branch`, `detached`, and
374
+ # the boundary that ends it — never decided line by line, because a record's
375
+ # `branch` line can arrive for ANY branch, not just $1, and only the full
376
+ # absence of both `branch` and `detached` means the record itself could not
377
+ # be classified. A record is settled at the next `worktree` line, or after
378
+ # the loop for the last one, since the trailing blank line `wt_listing`'s
379
+ # `$(...)` capture strips is not there to trigger it.
380
+ #
381
+ # A plain line loop, no awk: the listing's records are one attribute per line
382
+ # and `wt_listing` has already swapped any newline inside a path for `$wt_nl`,
383
+ # so `read -r` sees one attribute at a time. The heredoc keeps the loop in this
384
+ # shell, so its `return` answers for the function.
385
+ #
386
+ # Condition context only: 1 and 2 would exit a `set -e` caller.
387
+ # shellcheck disable=SC2034
388
+ wt_holding() {
389
+ wt_holder=
390
+ wt_holder_how=
391
+ wt_h_path=
392
+ wt_h_branch=
393
+ wt_h_detached=
394
+ wt_h_seen=
395
+ while IFS= read -r wt_h_line; do
396
+ case $wt_h_line in
397
+ "worktree "*)
398
+ if [ -n "$wt_h_seen" ]; then
399
+ wt_h_settle "$1"; wt_h_rc=$?
400
+ [ "$wt_h_rc" -eq 1 ] || return "$wt_h_rc"
401
+ fi
402
+ wt_h_path=${wt_h_line#worktree }
403
+ wt_h_branch=
404
+ wt_h_detached=
405
+ wt_h_seen=1
406
+ ;;
407
+ "branch $1") wt_h_branch=$1 ;;
408
+ "branch "*) wt_h_branch=${wt_h_line#branch } ;;
409
+ detached) wt_h_detached=1 ;;
410
+ esac
411
+ done <<EOF
412
+ $wt_list
413
+ EOF
414
+ if [ -n "$wt_h_seen" ]; then
415
+ wt_h_settle "$1"; wt_h_rc=$?
416
+ [ "$wt_h_rc" -eq 1 ] || return "$wt_h_rc"
417
+ fi
418
+ return 1
419
+ }
420
+
421
+ # Shared tail for `wt_h_settle`'s `detached` and unclassified-HEAD arms:
422
+ # resolve `$wt_h_path`'s in-progress state — passing $2 through as
423
+ # `wt_op_state`'s registry-route flag — and report whether it holds branch
424
+ # ref $1. Returns 0/1/2 exactly as `wt_h_settle` does, and sets
425
+ # `wt_holder`/`wt_holder_how` the same way.
426
+ # shellcheck disable=SC2034
427
+ wt_h_check_op() {
428
+ if nl_path "$wt_h_path" || ! wt_op_state "$wt_h_path" "${2:-}"; then
429
+ wt_holder=$wt_h_path
430
+ return 2
431
+ fi
432
+ case " $wt_op_held " in
433
+ *" $1 "*)
434
+ wt_holder=$wt_h_path
435
+ wt_holder_how="is held by a rebase or bisect in progress"
436
+ return 0
437
+ ;;
438
+ esac
439
+ return 1
440
+ }
441
+
442
+ # Decide whether the worktree record `wt_holding` just finished reading
443
+ # (`$wt_h_path`, `$wt_h_branch`, `$wt_h_detached`) holds branch ref $1.
444
+ # Returns 0 (held — sets `wt_holder`/`wt_holder_how`), 1 (this record does not
445
+ # hold it, keep reading) or 2 (cannot tell — sets `wt_holder`). Never called
446
+ # with `$wt_h_path` empty. Split out of `wt_holding` so a record can be
447
+ # settled from two call sites (mid-loop, and after it for the last record)
448
+ # without duplicating the decision.
449
+ # shellcheck disable=SC2034
450
+ wt_h_settle() {
451
+ if [ -n "$wt_h_branch" ]; then
452
+ [ "$wt_h_branch" = "$1" ] || return 1
453
+ wt_holder=$wt_h_path
454
+ wt_holder_how="is checked out"
455
+ return 0
456
+ fi
457
+ if [ -n "$wt_h_detached" ]; then
458
+ wt_h_gone=
459
+ [ -e "$wt_h_path" ] || wt_h_gone=1
460
+ wt_h_check_op "$1" "$wt_h_gone"
461
+ return $?
462
+ fi
463
+ # Neither a `branch` line nor the literal `detached` line: git could not
464
+ # classify this record's HEAD from the worktree's own directory at all (a
465
+ # corrupted admin HEAD is the shape #2218 measured) — go straight to the
466
+ # registry route, unconditionally, since the ordinary one already failed by
467
+ # definition of being here.
468
+ wt_h_check_op "$1" 1
469
+ return $?
470
+ }
@@ -0,0 +1,138 @@
1
+ ---
2
+ name: next-ticket
3
+ description: Use when user wants pick up new work — "what's next", "next ticket", "start a new issue", "what should I work on", or asks to grab/start an issue by intent rather than number.
4
+ ---
5
+
6
+ # Next Ticket
7
+
8
+ Suggest ready tickets, maintainer picks, mark in-progress, implement at depth ticket needs, end with PR rebased on `origin/main`.
9
+
10
+ **Never grab ticket unilaterally.** Labels and git state record only some claims; others live in maintainer's head or another agent session.
11
+
12
+ ## 1. Candidates
13
+
14
+ ```bash
15
+ ~/.fleet/bin/fleet-run candidates.mjs --require-label ready-for-agent --allow-fallback
16
+ ```
17
+
18
+ Script owns the query: label exclusions server-side, raw `body` never fetched for
19
+ whole list (~97% of payload) — reduced to dependency refs, to-spec specs dropped
20
+ by shape and named on stderr, survivors oldest first.
21
+
22
+ `--allow-fallback` re-runs unfiltered (`ready-for-human` / untriaged) when
23
+ `ready-for-agent` comes back empty **after specs are dropped** — a queue of
24
+ nothing but to-spec specs counts as empty. Solo only — flag exists for this
25
+ caller. Fleet never passes it: empty means no work, and an unattended fleet has
26
+ no channel to the human `ready-for-human` needs.
27
+
28
+ Exit 1 = query fine, queue empty. Exit 3 = query fine, rows came back and the
29
+ to-spec filter took every one — specs are to-tickets' input, so run to-tickets
30
+ rather than reading it as no work. Exit 2 = query broke. Different facts.
31
+
32
+ Exit 3 judges the LAST pass alone, so with `--allow-fallback` it is the
33
+ unfiltered pass's verdict: a labeled pass the filter emptied that falls back to a
34
+ genuinely empty one is exit 1, which is the fallback trigger's "counts as empty"
35
+ read off the exit code rather than a second rule.
36
+
37
+ ## 2. Dependencies
38
+
39
+ Use `d` array. Blocker open → drop ticket, or surface blocker instead. Cut to oldest 3–5 here — step 3 runs per candidate. Count is next-ticket's own; fleet Phase 0 sets its own.
40
+
41
+ Cut runs on step 1 data alone — number, title, labels, `d` — never the Agent Brief; a candidate the Brief would have promoted into survivors is dropped here, before that Brief is ever fetched (#22).
42
+
43
+ ## 3. In-flight check (all three, per candidate) — then fetch
44
+
45
+ ```bash
46
+ ~/.fleet/bin/fleet-run inflight.sh <N> # 0 free, 1 taken, 2 unanswerable
47
+ ```
48
+
49
+ Runs all three — a PR about the ticket, a remote branch, a local worktree or branch. Exit 1 → taken. "Shipped" memory not proof; open PR means unmerged. Exit 2 is not free: the question went unanswered (`gh` failed, no such issue, not a repo), so treat it as taken until you know.
50
+
51
+ Title + body + comments, survivors only: `gh issue view <N> --json title,body,comments --jq '.title, .body, (.comments[]|.author.login + ": " + .body)'`. `## Agent Brief` comment outranks body. Blocker named only in brief still drops ticket — step 1 `d` array won't have it. Not `--json body` (body only, brief invisible) nor bare `--comments` (comments only, nothing at all when none, exit 0 — silent loss).
52
+
53
+ Probes take only `<N>`, so they go first — fetching first spends ~6.4 KB (measured once, on #7) on a candidate about to be dropped. Step 1 already excludes `in-progress`, so step 3 catches the claim that never reached the label rather than the common case; the reorder is cheaper either way. They do not go earlier than this: the script makes three network round-trips (`gh issue view`, `gh pr list`, `git ls-remote`; the local probe is free) — so it stays behind step 2's cut and never runs over the whole step 1 list.
54
+
55
+ ## 4. Suggest — then stop
56
+
57
+ 3–5 survivors, **oldest first**, one line each:
58
+
59
+ `#N — <title> — <why now: adjacent to current branch, or nothing>`
60
+
61
+ FIFO. Never rank by size — that axis is gone. Never by "unblocks #X" either:
62
+ step 2 already dropped anything with an open blocker named in the body — heading,
63
+ bold-label, or inline form (#58) — or wired as a native blocked-by edge (#1741),
64
+ so everything here is free to start unless the blocker lives only in a native
65
+ sub-issue link, which the scan does not read, or it is body text alone whose
66
+ phrase and `#N` sit on different lines — both body passes are line-local.
67
+ "Adjacent to current branch" survives because solo session has one worktree;
68
+ means nothing to the fleet, whose members each get their own.
69
+
70
+ Ask which. **Wait for answer.** Maintainer says taken → drop, re-suggest.
71
+
72
+ ## 5. Claim it
73
+
74
+ ```bash
75
+ gh label create in-progress --color FBCA04 --force # first time only
76
+ gh issue edit <N> --add-label in-progress
77
+ ```
78
+
79
+ Infer branch/worktree convention from `git worktree list` / `git branch -r` — commonly `feat|fix|refactor/<N>-slug` and `.worktrees/<N>-slug`. Branch off fresh `origin/main`, install deps, run test baseline.
80
+
81
+ Abandoned before PR opens → remove `in-progress`.
82
+
83
+ ## 6. Size the ticket, then pick a path
84
+
85
+ Run `sizing-a-ticket`, follow path it returns. Both rows work solo — heavy row means more process, not blocked ticket.
86
+
87
+ ## 7. When the superpowers path reports done — open the PR
88
+
89
+ Come back here. Implementation skill hands off; this step always follows.
90
+
91
+ ```bash
92
+ git fetch origin && git rebase origin/main # rebase, never merge main in
93
+ <test command> # re-run after rebasing
94
+ git push --force-with-lease -u origin HEAD
95
+ gh pr create --base main --body "…
96
+
97
+ Closes #N"
98
+ gh pr edit --add-label <patch|minor|major> # own command, own exit status
99
+ ```
100
+
101
+ **In a detached worktree, push by refspec.** `run-team`'s runbook re-creates an
102
+ already-open PR's worktree with `git worktree add --detach <path> origin/<branch>`,
103
+ and a member sent into one is on `## HEAD (no branch)`, where the push above exits
104
+ 1 — `error: The destination you provided is not a full refname`. The flag is not
105
+ the cause, so no `-u`/force combination reaches it: the unqualified `HEAD`
106
+ destination is, and plain `git push origin HEAD` fails the same way while a bare
107
+ `git push` exits 128 (`fatal: You are not currently on a branch`). Name the branch
108
+ instead — `git push --force-with-lease origin HEAD:<branch>` (measured 2026-09-18,
109
+ git 2.50.1: exit 0). A worktree `claim-ticket.sh` claimed is on its branch, where
110
+ the push above is the correct one.
111
+
112
+ `--force-with-lease` matters only on a re-push: step 7 rebases immediately before pushing, so re-entering step 7 after an earlier push needs the force to land the rebased commits. On a re-push the force is load-bearing: stop and report the denial, never retry with a plain `--force`; a denial on a branch that has never been pushed is safe to route around with a plain `git push -u origin HEAD` instead.
113
+
114
+ `Closes #N` closes issue on merge — as does any closing keyword (`close`, `fixes`, `resolved`, …) sitting directly before an issue reference, wherever it appears in the body. Write one `Closes #M` per issue you mean to close, so `Closes #971, closes #864` closes both; give every other issue mention a word in front of it — `closed issue #M`, or the issue named without the `#`. A keyword before a list links only the first reference in that list, never the rest: `Closes #971, #864` closes only issue 971.
115
+
116
+ Repo gating on release label → exactly one of `patch`/`minor`/`major`; `validate-release-label` fails without it.
117
+
118
+ **Never fold `--label` into the create.** A `gh pr create` that outruns the caller's tool timeout is backgrounded with the PR already open and its flags unapplied, and a timeout carries no exit status for anything to react to — so the label goes missing and every later gate reads the PR as correctly opened (#375). Written as its own command it has its own exit status and fails loudly; `gh pr edit` with no PR argument resolves the current branch's PR, so it lands even when the create's own output was lost to the timeout. Failed → run it again before reporting the PR.
119
+
120
+ **Session ends here.** Merge happens later, elsewhere: `/review-and-fix` → maintainer adds `ready-to-merge` → `/run-merge-bot` merges in numeric order. Never merge, never add `ready-to-merge` (author's sign-off), never watch CI for merge that won't happen this session.
121
+
122
+ `in-progress` stays until that out-of-session merge closes issue — harmless, step 1 lists open issues only. Report PR URL, stop.
123
+
124
+ ## Red flags
125
+
126
+ - "I'll pull all bodies and filter in my head" → `--search` narrows server-side, `--jq` reduces inside `gh`; bodies for shortlist only. `candidates.mjs` already does it.
127
+ - "I'll inline the `gh` query instead of calling `candidates.mjs`" → don't. A hand-copied duplicate drifts: the copy that lived here missed the to-spec drop and the FIFO sort for a full release, so the solo path shortlisted specs newest-first while the fleet path did neither.
128
+ - "Label says ready-for-agent, so it's free" → run step 3.
129
+ - "I'll run the three probes inline instead of the script" → don't. Bare `gh pr list --search "<N>"` is a full-text match, so nearly every ticket reads as taken and free work gets skipped silently and permanently; a branch regex demanding a delimiter on both sides misses `fix/<N>` and `<N>-slug`; grepping a worktree's full path false-hits when a parent directory carries the digits. `inflight.sh` handles all three and shows its measurements.
130
+ - "Read the issues first, then check what's taken" → probes first; a dropped candidate's full read is pure waste. Probes still stay behind step 2's cut — two of the three hit the network (three round-trips).
131
+ - "Only one candidate, I'll just start" → still ask.
132
+ - "Blocker is nearly done" → still blocked.
133
+ - "I can size this myself, it's obvious" → run `sizing-a-ticket`; its red flags are ones you'd skip.
134
+ - "Rebase conflicts are messy, I'll merge main in" → rebase; PR sits on `origin/main`.
135
+ - "Tests passed before the rebase" → re-run after.
136
+ - "The implementation skill said done, so I'm done" → step 7 always runs; PR is deliverable.
137
+ - "I'll wait for CI, then merge it myself" → merge is another session's job. Open PR = done.
138
+ - "It's green and obviously fine, I'll add `ready-to-merge`" → maintainer's sign-off, never yours.