@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,75 @@
1
+ # CI reading and staleness
2
+
3
+ Why green not verdict, why absence is its own verdict, why conclusion not
4
+ stable, why behind-count only honest signal. Assertions live in SKILL.md
5
+ Phase 3 event loop + Merge bot sections; evidence here.
6
+
7
+ ## Own the CI waits — members cannot hold across a run
8
+
9
+ Members turn-based, cannot hold across ten-minute run — rebase, push, stop. One
10
+ went idle three times in two minutes doing this; every re-ping told nothing I
11
+ could not read. So controller arms second persistent Monitor over open PRs'
12
+ latest runs, keyed `<run-id>:<attempt>:<conclusion>` so each terminal state
13
+ fires once, emits behind-count with it: `success` on branch 8 behind not
14
+ actionable, that distinction most of traffic.
15
+
16
+ ## Run-binding: take the whole row from one read
17
+
18
+ Take run id, head, conclusion from **one** `gh run list --json` row. Watcher
19
+ reading them separately stitches event from two moments, can stream
20
+ `RUN COMPLETE: success` under run id whose real job list is failure. This is the
21
+ four-way binding `ci-state.mjs` performs — `gh pr checks` aggregates conclusions
22
+ ACROSS runs, can report `pass` inherited from cancelled run on superseded SHA;
23
+ head-SHA binding alone misses it, because head right and only conclusions belong
24
+ elsewhere. Tell members monitor event is wake-up, never verdict — they re-query
25
+ `gh run view <rid> --json jobs` at labelling time.
26
+
27
+ ## `no-ci`: absence is its own verdict, never green and never red
28
+
29
+ Third verdict `ci-state.mjs` emits, alongside `green`/`not-green`. Only genuine
30
+ absence earns it: no `.github/workflows/` directory, or one holding no workflow
31
+ files. Every failure to *read* a workflow — directory unreadable, target
32
+ unreadable, files present under names other than `--workflow`, two readable
33
+ files sharing that name, no resolvable repo root — is exit 2, "could not be
34
+ answered", never `no-ci`. So a repo whose CI is merely misconfigured can never
35
+ borrow the declarable verdict.
36
+
37
+ Absence never means pass. `no-ci` alone exits **1**, same bucket as `not-green`
38
+ — nothing to be green, and not red either. Exit 0 comes only with the caller's
39
+ `--declare-no-ci`, saying the gate is satisfied by their own verified suite run.
40
+ That flag is caller-side: it is echoed into `reasons` and flips the exit code,
41
+ so re-running with it and finding it there confirms only that you passed it,
42
+ never that anyone verified anything.
43
+
44
+ Why controller needs the verdict by name: no workflow run will ever complete
45
+ here, so the CI-run-completion edge never fires and waiting on it stalls the
46
+ whole PR — the silent-stall shape #111 reported before this verdict existed.
47
+ SKILL.md's `no-ci` edge therefore dispatches the finisher off the reviewer's
48
+ final verdict instead — that edge, not this file, carries the conditions on it.
49
+ Under `no-ci` the script reads no run list and no run view: no workflow, nothing
50
+ to bind.
51
+
52
+ ## A conclusion is not stable, even for a fixed run id on an unchanged head
53
+
54
+ Rerun rewrites run **in place** — `attempt` increments, dependents re-marked
55
+ `skipped` in zero seconds, prior conclusions gone. Verified: three jobs went
56
+ `success` → `skipped` with nothing pushed, after refresh workflow re-ran
57
+ currency check. So never cache conclusion; key watchers on
58
+ `<run-id>:<attempt>:<conclusion>`. `started_at == completed_at` on job means
59
+ re-marked, not re-run. Nothing in `ci-state.mjs` cached for same reason: only
60
+ safe design is re-query at moment of decision.
61
+
62
+ ## `--limit 1` hides CI
63
+
64
+ Newest run on branch frequently *not* CI — label or policy workflow often lands
65
+ later, so `--limit 1` can hide CI result entirely.
66
+
67
+ ## Stale green: every merge invalidates every other open PR
68
+
69
+ `rebase-check` fails fast when behind, gates slow jobs, so rest show *stale
70
+ green* until something re-triggers, then flip to `rebase-check: FAILURE` with
71
+ `integration`/`mutation` **skipped**. `rebase-check` can itself be
72
+ stale-**green**. Behind-count only honest signal. And one rebase per PR at merge
73
+ time enough: reviewers label on own green without requiring currency, and
74
+ requiring it earlier costs full CI cycle per sibling merge — six wasted cycles
75
+ in one run. Any behind-count you hand bot expired on arrival.
@@ -0,0 +1,37 @@
1
+ # Correction tickets ship new wrong claims
2
+
3
+ Why ticket meant to correct fact tends to ship fresh wrong one, and why check belongs on implementer as much as reviewer. Two assertions in SKILL.md cite this: the Reviewers section, and phase 0 step 4's `class=correction` judgement. Evidence here.
4
+
5
+ Nothing below measures a **model tier**. The four-for-four ran at one tier and this file records no comparison, so it cannot support a claim that either tier is better or worse for this class — step 4 cites it as a precaution and says so.
6
+
7
+ ## The four-for-four finding
8
+
9
+ Four for four in one run — misattributed package, list at inverted polarity, commit body citing wrong line, banner refuting currently-true fact.
10
+
11
+ ## The mechanism is the ticket's framing, not implementer sloppiness
12
+
13
+ Fix text **paraphrases the issue body's framing** instead of being checked clause-by-clause against tree, so wrong premise in ticket becomes wrong claim in repo. Two of four came verbatim from their issue's wording, and that issue still wrong on two counts — so every ticket split from same source inherits them.
14
+
15
+ ## Second mechanism: minted, not inherited — scope creep in the prose
16
+
17
+ Second run, on **`CoCo/agent-brain`** — GHE-hosted (`bmw.ghe.com`), not github.com, so none of it can be settled from this repo; the numbers, ordinals and test vocabulary describing it are theirs, not ours. Its PR 574 shipped **two** fresh false claims, neither traceable to the issue. Issue asked for **one clause**; PR wrote **five lines**. Both errors entered in that expansion — so comparing fix text against the issue clause cannot catch them, there being no clause to compare against.
18
+
19
+ Both were **positional references**: "the *closing* `report-file verification` block" (4th of 5) and "the *second* assertion is the one with teeth" (3rd). Positional refs are one of the four classes in the four-for-four finding, and they re-rot the moment anyone inserts ahead of them.
20
+
21
+ Ordinals also **fake their own verification**: the wrong ordinal named an assertion earlier than the real one, and **a failing assertion aborts the rest of its test** (true of `node --test` + `assert.*` here, not only of their runner) — so the obvious mutation (setting the workflow step under test to `if: ${{ always() }}`) reds the named assertion and never reaches the true one, appearing to confirm the wrong claim. One mutation cannot discriminate an ordinal: PR #32 measured that `always()` reds the named assertion, and only the narrower `always() && steps.mutate.outcome == 'success'` reds the true one.
22
+
23
+ Two rules for the implementer, both cheap: **match the ticket's stated size** — added prose is where minted claims enter — and **never write a positional reference** (`the closing/second/last X`); name what the thing *is*, not where it sits.
24
+
25
+ ## The clause-by-clause duty
26
+
27
+ Put check on **implementer**, not only reviewer: every factual claim the diff restates must have settling command run against tree first. Issue body is lead, never citation. Tell reviewers same, and to read each corrected sentence literally, asking whether every clause true under that reading — nobody hunts this unprompted, because diff "obviously" improves accuracy.
28
+
29
+ ## Citing evidence from another repo's run
30
+
31
+ Bare `#574` reads as **this** repo's 574 — to a human and to an agent alike. Ambiguity is the whole defect; no hyperlink need be involved. Cite by host of the source:
32
+
33
+ - **github.com** → `owner/repo#N`. `gh pr view N --repo owner/repo` settles it.
34
+ - **Any other host** (GHE, GitLab, internal) → prose naming host and repo, plus explicit *cannot be settled from this repo*. Qualified form is inert there: `gh api repos/CoCo/agent-brain` returns 404, so `CoCo/agent-brain#574` would point at nothing.
35
+ - **This repo's own issues and PRs stay bare `#N`.** Convention covers foreign evidence only; qualifying local reference is noise.
36
+
37
+ Disclaimer must reach every foreign token it covers — numbers, ordinals, file names, test vocabulary — and must say unverifiable, because the clause-by-clause duty demands settling command and none exists to run. Where lesson itself is host-neutral, name behaviour generically instead of scoping it foreign: foreign-scoped lesson invites reader to discard one that does apply here.
@@ -0,0 +1,23 @@
1
+ # Isolation: filesystem vs stack
2
+
3
+ Why isolation envelope file not briefing, why private filesystem not private stack. Assertions these justify live in SKILL.md Phase 1 + Guards sections; evidence here.
4
+
5
+ ## Materialize the isolation envelope as a file, not a briefing
6
+
7
+ Env vars in prompt missed five times in one run — including briefed member, and specialist whose parent briefed but did not pass down. So the runner is a file, and since #55 a TRACKED one: `agent-test` sits at the repo root and comes with every checkout, worktree and clone. It is a bootstrap — it materializes the current runner from `claim-ticket.sh --write-runner` into the gitignored `.agent-test.sh` beside it and execs that — so there is still exactly one emitter, and no committed copy to freeze. Brief members with `./agent-test <file-or-dir>` and nothing else: anyone who finds worktree finds runner — including grandchildren you never dispatched. A directory works too and expands to the test files under it; one holding none refuses rather than passing vacuously — appending nothing leaves argv empty, and bare `node --test` then discovers whole worktree: green for suite nobody asked for. Ports derive from `<N>`, so collisions impossible not discouraged — difference between safeguard and rule.
8
+
9
+ The runner is re-materialized on every invocation, so no copy of it survives a run to go stale — which is what #55 bought beyond a runner in a fresh clone. Before it, the runner was written once at claim time and never rewritten, and every copy under `.worktrees/` was frozen at whenever that worktree was claimed; reading or measuring one measured that build, not what the current emitter produces. A copy that predates #55 is still such a build, and so is any runner a repo that tracks no bootstrap gets. Line 2 is what tells a reader which build they are holding: `# agent-test template: <cksum>`. Reproduce the number from the installed script (`cksum $(~/.fleet/bin/fleet-run --path claim-ticket.sh)`) or from any revision of it (`git show <rev>:plugin/scripts/claim-ticket.sh | cksum`) and compare the first field — `cksum` also prints a byte count, and the path when it is given a file. It checksums the whole emitting script, not the runner template inside it, so it over-reports: a mismatch means only that `claim-ticket.sh`'s bytes differ from the ones you checksummed — a reworded die message or an edited comment moves it while the runner it produces stays byte-identical — not "the template changed", and not "older" either, because `cksum` carries no order: over `claim-ticket.sh`'s own history both the checksum and the byte count fall as well as rise. It under-reports too, so a match is not the freshness proof it looks like. The stamp covers `claim-ticket.sh` and nothing else, while the entrypoint the runner `exec`s — and whether the directory-expansion shim is emitted at all — comes from the sibling `derive-testcmd.sh`, which is not checksummed: two byte-identical copies of `claim-ticket.sh` differing only in that sibling emit visibly different runners under one identical stamp. So read a match as "this runner came from these bytes of `claim-ticket.sh`", and re-materialize when you need the current runner rather than a matching number. Nothing reads the stamp and nothing refuses on a mismatch; it makes staleness legible to a human, it gates nothing.
10
+
11
+ ## Filesystem isolation is not stack isolation
12
+
13
+ Private copy and test command solve different problems; conflating them is how second gets skipped: compose project name comes from environment, not working directory, so three agents on three snapshots still collide on one postgres. Symlinking `node_modules` does not help. "I'm on my own copy" is exactly the intuition that skips command — say both, every time. Which command depends on audience: member in worktree uses `./agent-test`; specialist on snapshot does not — the runner that bootstrap (#55) materializes derives its isolation triple from the directory name, and a snapshot is not a claimed worktree, so every snapshot gets the same fixed ports (measured in a snapshot: `ports derive from the issue number: postgres=16000 ollama=22000`) — and takes one `review-and-fix.md` hands out. The bootstrap no longer FAILS there: since #1056 the snapshot is a git repository, so `claim-ticket.sh --write-runner` succeeds in it, and the reason to hand a specialist a different command is the stack rather than a missing repo.
14
+
15
+ ## Scratchpad paths need two levels — the member's own partition, then one directory per child it dispatches
16
+
17
+ One flat namespace, generic filenames (`b.min.js`, `probe.mjs`) — one agent overwrote sibling's `package.json`. And finding ids restart at 1 every review, so two fix-appliers on different PRs both reach for `unv1`. Two levels, and nothing outside them — a probe built a git repo at the *checkout root*.
18
+
19
+ The axis is two-sided: the member partitions, and the parent assigns each child's path. A member owns one directory — `<scratch>/impl-<N>/` for an implementer, `<scratch>/pr<N>/…` on the review side — and every agent it dispatches gets a directory under that one, unique to that child and never shared, written into the child's prompt as an absolute path; a child never derives its own. The review side is already laid out this way: `review-core.mjs` makes the run root `<scratch>/pr<N>/run-XXXXXXXX/` with `mktemp`, then writes `<run>/<dim>/` into each specialist's prompt and `<run>/verify-<dim>/f<i>-l<j>/` into each refuter's. A fix-applier makes its own run root the same way — `<scratch>/pr<N>/fix-XXXXXXXX/` with `mktemp` — then resolves `<run>/<finding>/` to an absolute path for the refuter it dispatches on a suggestion; the bare `<scratch>/pr<N>/<finding>/` is not that path, since finding ids restart at 1 each fix-applier round too, and a later round on the same PR would reach for the same directory a prior round's refuter left fixtures in. An implementer's child gets `<scratch>/impl-<N>/<childName>/`, named after its dispatch name. Refuters are grandchildren, not members, which is why the member partition alone is not the rule: the agents that actually collided were ones no member rule reaches, and a parent-assigned path is what reaches them. Read from the object store at a pinned ref, write only under own path.
20
+
21
+ ## IDE/harness diagnostics attribute by bare filename, with no path
22
+
23
+ Probe copies carry same filenames as real tree, so specialist's throwaway mutation surfaces as errors that read exactly like live worktree's — and line numbers can plausibly line up with real in-flight edits. Never relay diagnostic without reproducing it in that member's specific worktree (`npx tsc --noEmit` from there). Ran twice in one session: clean first time (sibling's probe), genuinely broken second. Telling implementer to chase phantom in file it is mid-rewrite on is expensive failure.
@@ -0,0 +1,73 @@
1
+ # Member lifecycle: naming, fresh context, recovery
2
+
3
+ Why member name load-bearing, why every member single-use, how killed/idle/truncated member recovered. Assertions these justify live in SKILL.md's "Rules that fail silently", Phase 3, Reviewers, Failure handling sections; evidence here.
4
+
5
+ ## Every member is named
6
+
7
+ The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (hand-dispatch fallback's reviewer), `finisher-pr-<pr#>` (Phase 3's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
8
+
9
+ ## A depth-2 member cannot dispatch further
10
+
11
+ `task` is absent at a depth-2 member's depth (`task.maxRecursionDepth: 2`). Must state in reviewer prompt — else reviewer concludes fan-out unavailable, silently downgrades to solo review, no error, no signal; ask the controller to dispatch the specialists and relay their reports instead.
12
+
13
+ ## Capability is not permission
14
+
15
+ Members inherit standing *"Do not call the AgentTool unless the user requested it."* Else reviewer declines to dispatch specialists — correctly — you get thinner solo review, no error, no signal. Having tool (capability) not authorization to use it (permission); reviewer prompt must state full specialist set IS requested work.
16
+
17
+ ## The coordination contract
18
+
19
+ Stated once, in the vocabulary #1316 fixed — *dispatch* (start a member),
20
+ *send* (message a live one), *wake* (a send that resumes a finished
21
+ member's transcript), *settle* (a member's job reaching a terminal
22
+ outcome), *consume* (the controller deliberately taking a settled result):
23
+
24
+ - A refill is a **new** member under a **new** name, never a wake back into the old one — waking a finished member drags its old ticket in.
25
+ - Liveness is not settlement. A member that is not currently executing is not thereby done (Settle and liveness, below).
26
+ - A settled result is consumed deliberately, never assumed — the discipline holds even where the *hazard* it guards against does not (Grandchildren, below).
27
+ - Every send is reconciled against its receipt; whoever holds the receipt is the only party that can detect a discrepancy (Grandchildren, below).
28
+
29
+ `hub send` is the omp messaging mechanism. It appears in the recipes below, never in this contract's own vocabulary.
30
+
31
+ ## Fresh context per member
32
+
33
+ One member, one unit of work, gone. Never re-task a finished member — waking it drags the old ticket back in. Refill = **new** member, **new** name. Sending is still right for pinging a live member for a report it owes, or resuming a truncated reply — never for handing a finished member the next ticket.
34
+
35
+ `hub send` to an idle peer wakes it into its old transcript the same way; re-dispatching under the same name does not reset it — omp auto-suffixes a fresh peer (`name-2`) instead.
36
+
37
+ ## Grandchildren surface to you, not to the member that spawned them
38
+
39
+ A specialist's report routes to *you*, the controller.
40
+
41
+ A depth-2 helper cannot dispatch further (`task.maxRecursionDepth: 2`); measured 2026-09-09 from an actual controller session: a `hub send` to a depth-2 helper's full dotted id (`<member>.<helper>`) delivered, woke it, and got a reply — the controller reaches a member's helper directly, no transcript workaround needed.
42
+
43
+ Reviewer retrieves first, relay is the backup — duplicate costs nothing, missed report costs a verdict. A completed member's result is consumed deliberately, never assumed silent:
44
+
45
+ Results auto-deliver, and a settled `hub jobs`/`wait` snapshot **is** the delivery itself.
46
+
47
+ So relay each: name source, send its *text* (ruling on it as "your finding" makes reviewer verify a report it never sent, or act on one it cannot check). Then **reconcile every verdict against your relay receipts** — verdict claims a dimension undelivered, receipts say relayed → re-send naming the specialist, hold the verdict until it lands. Do not require reviewer-side acknowledgement: compliance depends on the same failure it catches, and the receipt check needs nothing from the reviewer.
48
+
49
+ `hub send` returns a structured `delivered`/`failed` receipt inline, replies thread by a 16-hex message id, and `await: true` returns the reply in the same call — the bookkeeping is native.
50
+
51
+ Measured 2026-09 (pre-cutover), both halves, with quotes. `review-pr-11` was sent `code-reviewer`'s report, msg `58c6bef2`, before its verdict; verdict read *"`code-reviewer` — dispatched, never delivered. No report reached me and none was relayed. Dimension not covered by a specialist."* — then ruled that dimension solo, headline claim refuted by report already sent to it. `review-pr-12` composed its first verdict *before* relays landed and reported all four as delivering nothing, found same defects in own mutation pass, credited all four by name in second verdict — convergent discovery, not silent application. Naming gap honestly is necessary, not sufficient: relay sent ≠ relay read, and relay can land after verdict composed. Neither reviewer could tell "no report" from "not yet relayed" without the receipt check; the second's independent re-derivation is what makes the correction trustworthy, not the naming alone.
52
+
53
+ Grandchild surfaces as own task-notification; unrecognized task-id not a member reporting done.
54
+
55
+ ## Settle and liveness are different facts
56
+
57
+ A member's settle outcome and its liveness are different facts, not the same table with two spellings.
58
+
59
+ Two axes — job outcome (`completed`/`failed`/`cancelled`) crossed with peer liveness (`running`/`idle`/`parked`). `hub cancel` → `cancelled`, the peer hard-aborted and unmessageable, `history://` still readable. A **`failed` job's peer can stay `idle` and resumable**. No distinct truncated state exists.
60
+
61
+ Recovery = fresh member, fresh name (`impl-<N>-b`, `fix-pr-<M>-b`, `review-pr-<M>-b`), whose prompt states what it inherits:
62
+
63
+ - committed-and-pushed vs committed-only vs **uncommitted in the worktree**
64
+ - uncommitted work exists nowhere else — no `git clean`, `git checkout .`,
65
+ `git reset --hard`, `git stash`
66
+ - for half-finished review: which specialists already reported, so it doesn't
67
+ re-run 40-minute fan-out
68
+
69
+ Reviewers go idle waiting on CI, won't resume alone — rebased, pushed, stopped with run `in_progress`. Three of five in one run. Recovery there = **finisher, not a re-review**, whenever commits already pushed.
70
+
71
+ ## React to artifacts, not agents
72
+
73
+ Liveness says nothing: `idle` means "not currently executing", not "done"; finished member's finding may never arrive. In one run every member that looked dead had its work in git or on PR — pushed commits, self-removed label, applied ruling. Read `gh pr view`, `gh run view`, `git -C <worktree> status` before messaging: one command settles what round-trip usually doesn't, and member that ignored one ping tends to ignore second. When you message, send specific next action, never "what is your status".
@@ -0,0 +1,73 @@
1
+ # Reaping merged branches and worktrees
2
+
3
+ Why reap runs after each merge pass, why `commit-commands:clean_gone` disqualified, why hand-rolled reap shaped this way (implemented by `reap.sh`), and why a claim that never became a PR needs a different script (`release-ticket.sh`). Assertions these justify live in SKILL.md's "Reap after each merge pass" and "Release the claims that never became PRs" sections; evidence here.
4
+
5
+ ## Reap after each merge pass, not once at the end
6
+
7
+ Merge deletes remote branch, leaves local branch `[gone]` with worktree — and its `node_modules` — still on disk. Stale worktree still answers `git worktree list`, so the in-flight probe (`inflight.sh`, run by the Shortlist and again by every Pull) reads already-merged ticket as taken and queue quietly shrinks as run goes on.
8
+
9
+ ## Why `commit-commands:clean_gone` is disqualified
10
+
11
+ Its `[gone]` detection works fine — with upstream configured, `git branch -v` prints `[gone]` and grep matches (verified, git 2.50.1). Problem not detection. Problem what happens after match:
12
+
13
+ - Deletes with `git branch -D`, no merged check at all — nothing stops it deleting branch whose commits exist nowhere else.
14
+ - Removes worktrees with `git worktree remove --force`. Fatal here: members hold worktrees, `--force` discards uncommitted work that exists nowhere else. Same class as `git reset --hard` to start rebase.
15
+
16
+ Skill is maintainer's to fix. Do not patch it; do reap yourself.
17
+
18
+ ## Why the reap is shaped the way it is
19
+
20
+ Every precondition recomputed **inside** same command as delete:
21
+
22
+ - **`for-each-ref`, not `git branch | grep`.** `%(upstream:track)` emits exactly `[gone]` as own field. Nothing to pattern-match, no `-v`/`-vv` trap.
23
+ - **Recompute per branch, in this command.** Branch list from earlier tool call already false: one observed run listed 28 gone branches, two calls later 27 reaped by concurrent session. Benign direction is no-op; dangerous one is worktree that gained work *after* check.
24
+ - **`git cherry origin/main`, not `git diff main..`.** Against `origin/main` — local `main` you never fast-forwarded reads every merged branch as unmerged. Any `+` line is commit that exists nowhere else.
25
+ - **The delete is `git update-ref -d`'s compare-and-swap on a tip read once (ADR 0018), authorized by that cherry check and only by it.** Tip read before the cherry, cherry runs against that SHA, delete refuses unless ref still equals it — commit landing between check and delete is kept with git's own `cannot lock ref`, never force-deleted, as it was under `git branch -D` until #2219. `--no-deref`, so symref branch deletes the symref, not its target (measured). Branch's config section removed after, as `-D` did — left behind, re-created branch of same name inherits dead upstream and reads `[gone]` at once. `git branch -d` would refuse everything here: upstream gone, so falls back to comparing against `HEAD`, a possibly-behind local `main`. Never delete branch whose cherry output you did not just read.
26
+ - **A branch any worktree holds is a KEEP, checked right before the delete.** `update-ref` consults no worktree; `-D` did. So listing is re-read and worktree.sh's `wt_holding` asks: held by a `branch` line, or by detached worktree stopped mid `rebase -i` / mid `bisect` on it (admin dir's `head-name` / `BISECT_START`) — both routes `-D` refused on (#2218). Worktree it cannot resolve, or listing that will not re-read, is a KEEP. `--apply` only, like the delete: dry run cannot predict this refusal — not the same limitation `-D`'s dry run had, since an unrelated worktree elsewhere in the listing that this check cannot resolve keeps every `[gone]` branch in the pass (see below), a repo-wide case `-D` never produced.
27
+ - **A cherry that cannot answer is a KEEP.** Capture git's output; never pipe git itself: `cmd | grep -q` takes grep's exit status, never cmd's, so a `git cherry` that dies (rc 128 — one unreadable loose object is enough) prints nothing, grep exits 1, and a dead probe reads identical to "nothing unmerged" (verified, git 2.50.1). Unanswerable probe authorizes no delete — same fail-closed shape as `worktree remove` below. Read the `+` anchored, too: the capture folds stderr in, so an unanchored match reads a `+` in a diagnostic as a commit. Pinned by a test.
28
+ - **A worktree registry that cannot be read is a KEEP, for every `[gone]` branch in that pass.** The lookup decides whether the dirty, ignored-files and removal checks run at all; an unread registry reads identical to "no worktree", and `-D`, the delete then, needed no answer from the registry to delete a branch that has none — so failing open force-deleted merged branches blind (#622). The holder check before the delete asks only whether a worktree holds the branch, never those other questions, so the lookup still fails closed on its own. The listing is re-read per branch, so one repo-level failure keeps every `[gone]` branch in the pass, each with git's own cause. Reap runs after every merge pass, so the next one retries: nothing is lost, nothing is reaped blind.
29
+ - **A registry the listing does not match is a KEEP for the whole pass, not just one branch — if the fault is standing.** Eight real admin-directory faults leave `git worktree list` at rc 0 while the held entry loses its `branch` line (admin `HEAD` garbage, empty, missing or chmod 000) or leaves the listing (`gitdir` missing or chmod 000, admin dir chmod 000, `.git/worktrees` replaced by a file) — and git's own "used by worktree" `-D` refusal read the same admin state, so it deleted the branch a live worktree held (measured, git 2.50.1, #2078). The holder check that replaced that refusal reads the same listing and answers "not held" for seven of the eight (measured; "cannot tell" only for `HEAD` missing), so it is no backstop either. So before the lookup is trusted, linked entries listed are counted against entries under `<git-common-dir>/worktrees/` (inflight.sh's `count_registry`/`count_linked`, recount-before-refuse included), and any linked entry with a null `HEAD` and no `branch` line fails it too — the HEAD faults keep the counts equal. A dropped or nameless entry says nothing about which branch it held. The check re-reads the listing per branch, so a standing fault — one still there on every branch's own read — keeps every `[gone]` branch in the pass, the healthy ones included; a transient one, healed before the next branch's read, keeps only the branches whose listing it touched. Either way nothing is reaped blind, and the next pass retries once the registry reads consistent again.
30
+ - **`worktree remove` without `--force`.** Refuses on modifications *and* untracked files, so double-covers dirty check. Refusal is finding to report, never something to force past.
31
+
32
+ ## Why a second sweep, over worktrees rather than branches
33
+
34
+ Above walk finds branch's worktree by `branch refs/heads/<name>` line `git worktree list --porcelain` prints. Worktree at detached HEAD carries no such line — so it was not refused, it was **not considered**, which is why no-silent-caps rule did not fire either: branch reaped, no `would remove worktree` line, no `kept` entry, directory left on disk. Measured live during a merge pass.
35
+
36
+ **Route not established — shape is.** Do not repeat that merge bot's server-side rebase detaches worktree: measured false. Bot reported `path=rebase` for #969/#970/#972, `reap.sh` dry run right after printed `would remove worktree` for all three — line only ATTACHED worktree reaches. `run-merge-bot.md` agrees: API rebased remote, not your checkout, left attached and merely stale. `release-ticket.sh` names one route it did measure, interrupted rebase. Cost of shape is what matters and is measured: stale worktree still answers `git worktree list`, in-flight probe reads it as live claim, already-merged ticket reads as taken, queue quietly shrinks.
37
+
38
+ So `reap.sh` enumerates worktrees git lists with **no `branch` line at all** and decides each on own state:
39
+
40
+ - **Bounded to `*/.worktrees/*` — fleet's own worktree home — and everything outside it is a `kept` entry.** Branch sweep authorizes its branch delete on evidence PR merged (`%(upstream:track)` reads exactly `[gone]`). This sweep has none to read: branchless + clean + patch-equivalent also describes human's `git worktree add --detach` scratch checkout that was never ticket. Unbounded, `--apply` deleted it (measured, PR #985 review). Bound is ownership, never contents.
41
+ - **`git cherry` against `origin/main`, never `merge-base --is-ancestor`.** Branch was rebased before it merged, so tip fully upstream is patch-equivalent, not ancestor — ancestry answers no for exactly work that is safe. Subject is full object id off porcelain, so no refname shadows it.
42
+ - **Absent `branch` line is not by itself detached HEAD.** git prints none for worktree whose HEAD it cannot resolve either, reporting null object id instead — four measured corruption routes for admin `HEAD` (#179). Nothing about such worktree decidable, so report and leave. Null id alone is not the test: unborn branch is legitimate null id and DOES carry `branch` line.
43
+ - **A git operation in progress is a keep, and git is no backstop for it.** Measured, git 2.50.1 (Apple Git-155): `worktree remove` *without* `--force` removes worktree holding interrupted rebase, and one holding bisect, at rc 0. Both detach, both leave `status --porcelain` empty — so every other check passes them and sequencer state, todo list and original head go with directory. Interrupted rebase is exactly how fleet worktree wanders off its branch (see `release-ticket.sh`'s own stray guard).
44
+ - **Every decline is a `kept` entry, `branch` null.** No branch to name. Gap was invisible precisely because nothing was reported.
45
+ - **Removals join `worktreesRemoved[]`, from both sweeps.** One meaning, no qualifier: a key naming only removals no branch accounted for would leave reader unable to tell absent removal from unreported one.
46
+ - **Not fixed in merge bot.** Re-attaching worktree after rebase puts invariant where it only helps paths that remember to do it, and next permitted-command change moves problem again.
47
+
48
+ ## Why reap declines a claim that was never dispatched
49
+
50
+ Undispatched claim = `in-progress` label + worktree + branch, no PR. `reap.sh` skips it, correctly: no merge happened, so no remote branch was ever deleted, so branch is not `[gone]` and the `for-each-ref` filter never selects it. Forced past that, `git cherry` is empty and the delete unauthorized. Reap's evidence is "merged upstream"; this branch never went anywhere.
51
+
52
+ So nothing in the run cleans it up. Next run, the in-flight probe's local-worktree check sees the worktree and the local branch → hit → free ticket reads as taken, silently. Same failure as a stale merged worktree, opposite end of the lifecycle. Normal, not exotic: phase 1 claims ahead of dispatch, so collision-after-claim and drain both produce it.
53
+
54
+ `release-ticket.sh` covers it. Four preconditions, recomputed inside same invocation as delete, same reason reap recomputes — but the dirty check is the conditional one: it opens only when the worktree directory is there to read, and where that directory is established absent it does not run at all, leaving the absence measurement itself as what stands in for it:
55
+
56
+ - **`ahead` + dirty catch a member that did work.** `ahead` against `origin/main`. Not redundant with `git cherry`: commit already cherry-picked upstream is upstream-equivalent (`-` line, not `+`), and only `ahead` still sees it. Pinned by a test.
57
+ - **`git cherry` catches commits that exist only locally.** Against `origin/main`, never a local main — same trap reap has.
58
+ - **Remote check catches a pushed branch.** Live `git ls-remote`, so it cannot be stale. Its failure is an unknown answer, never a "not pushed" — swallow it and a release deletes the local copy of work already on the server.
59
+ - **Label read first, `gh` failure fatal.** Worktree and branch gone with `in-progress` left behind hides the ticket from `candidates.mjs` entirely — worse than not releasing. All three artefacts or none.
60
+
61
+ **The delete is `git update-ref -d`'s compare-and-swap (ADR 0018) here too, and for reap's reason** — authorized by the `ahead` and `git cherry` checks above, plus the `ahead` recount re-run against `origin/main` immediately before the delete itself (a commit can land across the `gh issue view` between the checks and the delete; `git cherry` is not re-run, because such a commit is ahead of `origin/main` by construction), and by nothing else. A claim used to carry `origin/main` as its upstream, so `-d` compared against *that* and forgave a behind local main; since #760 `claim-ticket.sh` passes `--no-track` (so `@{u}` cannot silently answer about main), a claim has no upstream until its first `push -u`, and `-d` falls back to comparing against local `HEAD`. Measured: with local `main` behind `origin/main`, `-d` refuses a pristine claim — half-releasing it, worktree deleted and branch stranded with `in-progress` still on the ticket. The two checks above are strictly stronger than what `-d` would have asked, and both measure against `origin/main` rather than a local ref.
62
+
63
+ **`worktree remove` without `--force`** refuses on modified and untracked files and deletes ignored files silently (verified, git 2.50.1). Ignored-silently is what is wanted: `./agent-test` materializes `.agent-test.sh` beside itself in every worktree it runs in (and before #55, `claim-ticket.sh` wrote an untracked `agent-test` into every worktree it claimed), so treating ignored files as dirt would strand every release. The same asymmetry is why the runner itself is tracked as a BOOTSTRAP rather than committed as a copy: a claim that overwrote a tracked `agent-test` would leave a modified tracked path, which this refusal does not forgive. Its refusal is the dirty check recomputed by git at the moment of the delete — for the live-directory case ONLY. `worktree remove` gates that clean check on the same `stat` the guard does, so it is not an independent second opinion: where the path cannot be stat'ed git reaches the same "gone" by the same means, accepts the entry at rc 0 and deregisters a worktree whose files are still on disk (measured, git 2.50.1: an untracked file in a worktree under a `chmod 000` parent). There the `gone` guard is sole arbiter — which is why it establishes absence instead of inferring it from a failed `-e`, and why the fail-open fixed in `1e54bac` survived being reasoned about: guard and backstop fail on the same inputs.
64
+
65
+ **A worktree that wandered off the branch blocks too.** The worktree is located by the branch it has checked out, and it does not stay there — an interrupted rebase leaves it detached, a member can switch it. The lookup then finds nothing, which reads as "no worktree of ours": the dirty check is skipped entirely and the release reports success while the worktree stands with the member's work in it, so the next run's probe still reads the ticket as taken. So a linked worktree at `claim-ticket.sh`'s `.worktrees/<issue>-<slug>` that is *not* on the branch is its own blocker — which remedy it names is the next paragraph, and is not always a hand-release. The path is read as the whole rest of the `worktree list --porcelain` line, never the first whitespace field, or every checkout under a directory with a space in its name reads as a different path.
66
+
67
+ **Which remedy depends on whether that directory still exists.** The registration outlives it: `worktree list --porcelain` keeps the entry, annotated `prunable`, after an `rm -rf`, so the blocker named a hand-release nobody could perform and every later run repeated it. When the directory is established gone the blocker names `git worktree prune` instead — that clears the entry and the next run releases (verified, git 2.50.1). Still a blocker, never a release: the worktree is not on the claim's branch, so releasing would delete a different ref and then reach the prune every `--apply` ends with, unanchoring a detached HEAD's commits as a side effect. Absence is established by walking up to the nearest ancestor that exists and requiring it to be searchable — the same predicate the dirty check uses, because `-e` is false both for a directory that is gone and for one inside a prefix we may not search, and pruning the second unregisters a worktree still holding uncommitted work.
68
+
69
+ Check: `node --test plugin/scripts/release-ticket.test.mjs` — real throwaway repos, no mocked git history, one case per precondition proving it blocks on its own.
70
+
71
+ ## Never reap a branch a live member is on
72
+
73
+ Cross-check `.fleet/ledger.md` before running: row without terminal state means someone may still be in that worktree — merged PR can still have reviewer filing follow-ups. Dirty check does not see member that committed but not pushed. Update reaped tickets' ledger rows in same step, report reaped and kept counts. Kept-with-reason is half worth reading.
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: sizing-a-ticket
3
+ description: Use before implementing ticket — decides how much process work needs, returns light or heavy plus path to follow.
4
+ ---
5
+
6
+ # Sizing a Ticket
7
+
8
+ Judge ticket **as written**, not as hoped. Torn between rows → take heavier —
9
+ process depth, not admissibility.
10
+
11
+ Read first: `gh issue view <N> --json title,body,comments --jq '.title, .body, (.comments[]|.author.login + ": " + .body)'`. `## Agent Brief` comment outranks body. Not `--json body` (body only, brief invisible) nor bare `--comments` (comments only, nothing at all when none, exit 0 — silent loss).
12
+
13
+ | Row | Signal | Path |
14
+ |---|---|---|
15
+ | **light** | States exactly what to change, one-two files, no design choice open | `superpowers:test-driven-development` |
16
+ | **heavy** | Ambiguity in *what* to build, >~3 files, new API/schema/UX, or several viable approaches | `superpowers:brainstorming` → `superpowers:writing-plans` → `superpowers:subagent-driven-development` |
17
+
18
+ **Fleet member on heavy: enter at `superpowers:writing-plans`.**
19
+ `superpowers:brainstorming` is the maintainer-present step — its `<HARD-GATE>`
20
+ waits on user approval no unattended member gets, and a `ready-for-agent`
21
+ ticket's `## Agent Brief` already is that output. Solo session has a user: run full path.
22
+
23
+ Bug reports: `superpowers:systematic-debugging` first, either row.
24
+
25
+ Report row, path, one-line why. **Process depth only** — no admissibility call
26
+ here, for anyone. Both rows workable, solo and in fleet; heavy means more process,
27
+ never blocked ticket.
28
+
29
+ Tie-break here: torn → take the heavier row. Right for process depth, **opposite** of
30
+ fleet's admissibility tie-break, where torn → surface to maintainer. Two
31
+ questions, two biases. Never carry this one across.
32
+
33
+ ## Red flags
34
+
35
+ - "Body is short, so it's simple" → short bodies hide most design ambiguity. Size by unknowns, not word count.
36
+ - "Brainstorming is overkill here" → that thought is heavy row.
37
+ - "The Agent Brief is thorough, so it's light now" → brief quality never promotes
38
+ a heavy row *for process depth*. Says nothing about admissibility — thorough
39
+ brief is exactly what makes big ticket safe to run unattended.