@feigi/fleet-ctl 3.24.13 → 3.24.15

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.24.13",
3
+ "version": "3.24.15",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -42,23 +42,31 @@
42
42
  // Only the refusal of conflicting ticket-features rows names a session and an
43
43
  // agent, and it prints nothing on stdout.
44
44
  //
45
- // STOPPING RULE (exported as `stoppingRule`, not printed by this CLI). For a
46
- // cell X other than slow-high whose definition is live, a VERDICT is a ticket
47
- // with an admissible Pull at X dated on or after the day X's
48
- // `fleet-implementer-<cell>` definition was most recently added, ruled by its
49
- // last tier-outcomes.tsv row (a `+`-joined `ticket` field rules each ticket
50
- // it names) dated on or after the ticket's last such Pull: a ruling never
51
- // predates the Pull it rules, and a row with both verdict columns blank was
52
- // never ruled, so it is skipped. A ticket with no such row is no verdict.
53
- // A ticket counts once however many Pulls it took. A verdict FAILS
54
- // the quality floor on `minted_false_claim=yes` or `closed_own_ticket=no`; a
55
- // counted ruling holding anything but `yes` or `no` in either column, one
56
- // blank included, is refused rather than read as a pass. So is a non-blank
57
- // ruling row of such a ticket whose `run_date` is not `YYYY-MM-DD`: it cannot
58
- // be placed against the Pull, and dropping it would uncount the ticket. So is
59
- // an admissible Pull at X whose `run_date` is not `YYYY-MM-DD`: it cannot be
60
- // placed against the day X's definition was added, and dropping it would
61
- // uncount its ruling.
45
+ // STOPPING RULE (exported as `stoppingRule`, not printed by this CLI). A
46
+ // ticket's RULING is its last tier-outcomes.tsv row in file order (a
47
+ // `+`-joined `ticket` field rules each ticket it names); a row with both
48
+ // verdict columns blank was never ruled, so it is skipped. Its CARRIER is
49
+ // the ticket's last Pull in file order, at any cell, slow-high included,
50
+ // dated on or before the ruling. Dates only set that floor: a ruling counts
51
+ // for a Pull only when dated on or after it, and neither pick is the
52
+ // latest-dated row. A Pull at X is
53
+ // COUNTABLE when X is a cell other than slow-high whose definition is live
54
+ // and the Pull is admissible and dated on or after the day X's
55
+ // `fleet-implementer-<cell>` definition was most recently added. The ruling
56
+ // is a VERDICT for the carrier's cell only, and only when the carrier is
57
+ // countable. Otherwise it is no verdict for any cell, never one for an
58
+ // earlier Pull of the ticket. A ticket with no ruling, or no Pull dated on or
59
+ // before it, is no verdict. A ticket counts once however many Pulls it took,
60
+ // at however many cells. A verdict FAILS the quality floor on
61
+ // `minted_false_claim=yes` or `closed_own_ticket=no`. For a ticket with a
62
+ // countable Pull, a ruling holding anything but `yes` or `no` in either
63
+ // column, one blank included, is refused rather than read as a pass. So is a
64
+ // non-blank ruling row of such a ticket whose `run_date` is not `YYYY-MM-DD`,
65
+ // and, once it is ruled, a Pull of it at any cell whose `run_date` is not
66
+ // `YYYY-MM-DD`: either cannot be placed to find the carrier, and dropping it
67
+ // could move the verdict to another cell or uncount it. So is an admissible
68
+ // Pull at X whose `run_date` is not `YYYY-MM-DD`: it cannot be placed against
69
+ // the day X's definition was added, and dropping it would uncount its ruling.
62
70
  // X is to be withdrawn once it has at least STOP.verdicts verdicts and
63
71
  // floor failures ÷ verdicts is at least STOP.failRate.
64
72
  //
@@ -169,35 +177,50 @@ export function readout({ features, members }) {
169
177
  * `[{ ticket, pr, run_date, closed_own_ticket, minted_false_claim, failed }]`
170
178
  * sorted by ticket, `run_date` the ruling's; `stop` is whether the stopping
171
179
  * rule withdraws the cell. `verdicts` are parsed tier-outcomes.tsv rows.
172
- * Throws on a counted ruling whose `closed_own_ticket` or `minted_false_claim`
173
- * is not `yes` or `no`, on a non-blank ruling row of a Pulled ticket whose
174
- * `run_date` is not `YYYY-MM-DD`, on an admissible Pull at a cell named in
175
- * `added` whose `run_date` is not `YYYY-MM-DD`, and on a member-outcomes
176
- * session+agent repeated with different fields.
180
+ * A ticket's ruling is its last ruling row in file order, charged to the cell
181
+ * of its carrier, the ticket's last Pull in file order at any cell dated on or
182
+ * before the ruling, and only when that Pull is
183
+ * countable: admissible, at a cell named in `added` other than the policy
184
+ * cell, and dated on or after the day that cell's definition was added.
185
+ * Throws on the ruling of a ticket with a countable Pull whose
186
+ * `closed_own_ticket` or `minted_false_claim` is not `yes` or `no`, on a
187
+ * non-blank ruling row of such a ticket whose `run_date` is not `YYYY-MM-DD`,
188
+ * on an admissible Pull at a cell named in `added` whose `run_date` is not
189
+ * `YYYY-MM-DD`, on any Pull of a ruled ticket with a countable Pull whose
190
+ * `run_date` is not `YYYY-MM-DD`, and on a member-outcomes session+agent
191
+ * repeated with different fields.
177
192
  */
178
193
  export function stoppingRule({ features, members, verdicts, added }) {
179
194
  const byKey = indexMembers(members);
180
195
  const rulings = rulingsByTicket(verdicts);
181
- // Per cell, each ticket's last admissible Pull: the one its ruling must follow.
182
- const charged = new Map(Object.keys(added).filter((c) => c !== POLICY_CELL).map((c) => [c, new Map()]));
183
- for (const p of features) {
184
- const pulls = charged.get(p.chosen_cell);
185
- if (!pulls || !admissibleMember(p, byKey)) continue;
196
+ const charged = new Map(Object.keys(added).filter((c) => c !== POLICY_CELL).map((c) => [c, []]));
197
+ const dated = (p) => {
186
198
  if (!DATE.test(p.run_date)) throw new Error(`ticket #${p.ticket} (Pull ${p.agent} at ${p.chosen_cell}): run_date is '${p.run_date}', expected YYYY-MM-DD`);
187
- if (p.run_date < added[p.chosen_cell]) continue;
188
- pulls.set(p.ticket, p);
199
+ return p.run_date;
200
+ };
201
+ const countable = new Set();
202
+ const pullsByTicket = new Map();
203
+ for (const p of features) {
204
+ (pullsByTicket.get(p.ticket) ?? pullsByTicket.set(p.ticket, []).get(p.ticket)).push(p);
205
+ if (!charged.has(p.chosen_cell) || !admissibleMember(p, byKey)) continue;
206
+ if (dated(p) >= added[p.chosen_cell]) countable.add(p);
189
207
  }
190
- return [...charged].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([cell, pulls]) => {
191
- const list = [];
192
- for (const p of pulls.values()) {
193
- const v = rulingFor(rulings, p.ticket, p.run_date);
194
- if (!v) continue;
195
- list.push({
196
- ticket: p.ticket, pr: v.pr, run_date: v.run_date,
197
- closed_own_ticket: v.closed_own_ticket, minted_false_claim: v.minted_false_claim,
198
- failed: v.minted_false_claim === "yes" || v.closed_own_ticket === "no",
199
- });
200
- }
208
+ for (const [ticket, pulls] of pullsByTicket) {
209
+ if (!pulls.some((p) => countable.has(p))) continue;
210
+ // The ticket's ruling: its last ruling row in file order (every date clears a "" floor).
211
+ const v = rulingFor(rulings, ticket, "");
212
+ if (!v) continue;
213
+ // Its carrier: the ticket's last Pull in file order dated on or before the ruling.
214
+ let carrier = null;
215
+ for (const p of pulls) if (dated(p) <= v.run_date) carrier = p;
216
+ if (!carrier || !countable.has(carrier)) continue;
217
+ charged.get(carrier.chosen_cell).push({
218
+ ticket: carrier.ticket, pr: v.pr, run_date: v.run_date,
219
+ closed_own_ticket: v.closed_own_ticket, minted_false_claim: v.minted_false_claim,
220
+ failed: v.minted_false_claim === "yes" || v.closed_own_ticket === "no",
221
+ });
222
+ }
223
+ return [...charged].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([cell, list]) => {
201
224
  list.sort((a, b) => Number(a.ticket) - Number(b.ticket));
202
225
  const failures = list.filter((v) => v.failed).length;
203
226
  const stop = list.length >= STOP.verdicts && failures / list.length >= STOP.failRate;
@@ -12,8 +12,7 @@ Run `next-ticket`, `review-and-fix`, `run-merge-bot` as one fleet. You are the
12
12
  hard cap — they become the tick's `--implementer-cap` and `--reviewer-cap`.
13
13
  Merge bot is at most one, not configurable.
14
14
 
15
- Rationale: `docs/specs/2026-07-22-run-team-agent-fleet-design.md`. The
16
- war story behind a rule ending `See references/<file>` lives in that file; load
15
+ The war story behind a rule ending `See references/<file>` lives in that file; load
17
16
  it only when a member needs the *why*. A rule without that line carries its
18
17
  reasoning inline — nothing is missing.
19
18
 
@@ -93,8 +92,8 @@ See references/member-lifecycle.md.
93
92
  them before every gate decision.** Per-member worktrees and `./agent-test`'s port
94
93
  derivation protect members from each other; neither protects the main checkout,
95
94
  which you run every gate probe out of and which any member can edit — except
96
- through a `write`/`edit`/`ast_edit` the `member-write-guard` extension refuses
97
- (ADR 0020); a `bash` or `eval` write still lands (#2210). Measured: a
95
+ through a `write`/`edit`/`ast_edit` the `member-write-guard` extension refuses;
96
+ a `bash` or `eval` write still lands. Measured: a
98
97
  member edited two files there instead of in its worktree while the CI monitor was
99
98
  polling one of them every 120s and a live finisher was using it to decide a
100
99
  label. It caught itself; nothing in the fleet would have. That is the silent
@@ -172,7 +171,7 @@ against `849`, `850`, `852` on three lines:
172
171
  **Word the rule against the first row.** A warning spelled *never `for x in
173
172
  $(…)`* names the safe form as the hazard, so a reader avoids the form that works,
174
173
  keeps the one that collapses, and rewrites correct bounded polls on the way.
175
- #854 was filed carrying that inversion in its own remedy clause and in its title,
174
+ A ticket was once filed carrying that inversion in its own remedy clause and in its title,
176
175
  and its filer measured both forms and retracted it; the corrected rule is this
177
176
  row. `$(…)` splits. Leave it alone.
178
177
 
@@ -233,7 +232,7 @@ restate this block there.
233
232
 
234
233
  ## Phase 0 — shortlist
235
234
 
236
- Once per run, at start. Supply is automatic after that (ADR 0013): the tick
235
+ Once per run, at start. Supply is automatic after that: the tick
237
236
  refreshes the Shortlist itself, and every admission is a **Pull** — one ticket
238
237
  into one free implementer slot, the moment it frees (phase 1). Nothing in this
239
238
  phase, or in any later one, asks the maintainer which tickets to take.
@@ -273,7 +272,7 @@ phase, or in any later one, asks the maintainer which tickets to take.
273
272
  -uall` entries plus a content hash of every path they name. Your own
274
273
  uncommitted work is fine — it is in the baseline and holds nothing. From
275
274
  then on every `fleet-tick.mjs` compares the main checkout against it and
276
- holds dispatch on any change (#2210): the backstop for the stray member
275
+ holds dispatch on any change: the backstop for the stray member
277
276
  writes `member-write-guard` cannot see — an `eval` cell, a `bash` that
278
277
  `cd`s or `git -C`s into this checkout. `.fleet/`, `.worktrees/` and
279
278
  `.agent-brain/` are gitignored and never trip it. Nor does this run's own
@@ -304,11 +303,11 @@ phase, or in any later one, asks the maintainer which tickets to take.
304
303
  write to the gate protecting this repo, so it needs the maintainer.
305
304
  Surface the diff and carry on. What it changes is what you may then claim:
306
305
  every statement this run makes about which checks must pass before a merge
307
- is sourced from the spec plus ADR 0007 and is true of the live gate only
306
+ is sourced from the checked-in spec and is true of the live gate only
308
307
  while this check is green, so a 3 means saying "the gate requires X"
309
308
  without naming the drift is a false claim, and a 2 means you never learned
310
- either way. Measured 2026-09-23 (#1710): four contexts ADR 0007 had
311
- selected were required by the spec and by nothing live, and the gap sat
309
+ either way. Measured 2026-09-23: four contexts the spec required were
310
+ enforced by nothing live, and the gap sat
312
311
  there unnoticed because the only thing that ever read the live gate was a
313
312
  person choosing to.
314
313
 
@@ -318,9 +317,9 @@ phase, or in any later one, asks the maintainer which tickets to take.
318
317
  feed or update it, and it survives your own compaction. The launch is
319
318
  idempotent per workspace when the running cockpit answers the identity
320
319
  handshake: an already-served workspace's launch finds the running server
321
- over HTTP, prints its URL, and exits 0 without starting a second one
322
- (#1585) — nothing to skip. It opens nothing either: `--open` opens a tab
323
- only from the launch that binds a port and starts the server (#1714), so a
320
+ over HTTP, prints its URL, and exits 0 without starting a second one —
321
+ nothing to skip. It opens nothing either: `--open` opens a tab
322
+ only from the launch that binds a port and starts the server, so a
324
323
  re-shortlist leaves the board tab you already have alone. A second fleet
325
324
  on another workspace collides with none of that: its own launch derives
326
325
  that workspace's own port and binds it when free, or scans to the next
@@ -328,9 +327,9 @@ phase, or in any later one, asks the maintainer which tickets to take.
328
327
  else — either way it gets its own board, just not always on the port its
329
328
  hash predicts.
330
329
 
331
- The spend panel reads this workspace's own `~/.omp/agent/sessions` tree
332
- (#1716), and is pinned to whichever session first writes a transcript on this
333
- cockpit's own watch (#1583/#1679): it will not follow a workspace that
330
+ The spend panel reads this workspace's own `~/.omp/agent/sessions` tree,
331
+ and is pinned to whichever session first writes a transcript on this
332
+ cockpit's own watch: it will not follow a workspace that
334
333
  already had another session's transcripts sitting there at launch. If the
335
334
  panel is reading someone else's numbers, relaunch with `--spend-dir <path>`
336
335
  naming this run's own session directory to override the heuristic outright —
@@ -417,17 +416,17 @@ phase, or in any later one, asks the maintainer which tickets to take.
417
416
  both are reviewable work no member otherwise picks up, because the Shortlist
418
417
  holds ISSUES and nothing looks at inherited PRs. Queue each for review exactly as
419
418
  ticket work: same review workflow, same fix-applier, same finisher. Measured
420
- 2026-09-03 — #1222 arrived this way and its review found a defect its own PR
421
- body called unreviewed, and #1237's review then caught two metrics rows the
419
+ 2026-09-03 — a prior run's ticket PR arrived this way and its review found a defect its own PR
420
+ body called unreviewed, and a chore PR's review then caught two metrics rows the
422
421
  controller had missed in its own close-out, so a chore PR is not exempt from
423
422
  being wrong. Reviewing them next run is also what stops one pinning
424
- `fleet-tick`'s backlog forever (#590): unreviewable AND uncounted is the state
423
+ `fleet-tick`'s backlog forever: unreviewable AND uncounted is the state
425
424
  that strands it.
426
425
 
427
426
  1. **Build the Shortlist** — `~/.fleet/bin/fleet-run shortlist.mjs`, then read
428
427
  `.fleet/shortlist.json`. The script runs the cheap filters and nothing else
429
428
  — no ticket body is read here, because a Pull reads one ticket in full at
430
- the moment it admits it (ADR 0013 §1):
429
+ the moment it admits it:
431
430
 
432
431
  - **Candidate scan** — `candidates.mjs --require-label ready-for-agent`,
433
432
  oldest-first, never re-ranked. Its row count is `scanned`, the supply.
@@ -478,7 +477,7 @@ phase, or in any later one, asks the maintainer which tickets to take.
478
477
  **No multi-select, no maintainer tick.** Selection and ordering are batched —
479
478
  one scan, oldest first; admission never is. The invariant this replaces — one
480
479
  human decision per batch of admissions, zero unilateral grabs — is retired
481
- (ADR 0013): zero human decisions per admission, and every non-admission is a
480
+ is retired: zero human decisions per admission, and every non-admission is a
482
481
  label or a premise the maintainer can read.
483
482
 
484
483
  ## Phase 1 — Pull: judge, then claim or relabel
@@ -486,9 +485,9 @@ label or a premise the maintainer can read.
486
485
  Serial, main checkout, one Pull at a time. Never parallel, never inside a member —
487
486
  concurrent `worktree add` and label writes race.
488
487
 
489
- One free implementer slot is one Pull. The tick names the heads — `PULL #412
490
- #415`, one per free slot — and each Pull runs this sequence on its head,
491
- terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
488
+ One free implementer slot is one Pull. The tick names the heads — `PULL #<n>
489
+ #<m>`, one per free slot — and each Pull runs this sequence on its head,
490
+ terminating in exactly one dispatch or an empty shortlist:
492
491
 
493
492
  1. **Take the shortlist head** — the next `.fleet/shortlist.json` entry with no
494
493
  `impl-` row and no `excluded` row whose premise still holds, which is the
@@ -569,24 +568,24 @@ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
569
568
  that no longer exists. Separate its two non-zero answers before citing
570
569
  either — exit 1 is the answer *not reachable*, while exit 128 with `Not a
571
570
  valid object name` is a sha this clone does not have at all, a probe that
572
- could not look rather than an orphan (measured: #640's comment cites
571
+ could not look rather than an orphan (measured: one ticket's comment cited
573
572
  `35c0845` on a since-deleted branch, and 128 is what it exits here).
574
573
 
575
574
  **Both halves of that command are load-bearing.** Drop the `origin/main`
576
575
  argument and `git log -S` searches `HEAD`, contradicting the rule a paragraph
577
576
  up — and the two searches fail differently there. On a checkout behind the
578
577
  fix the prescribed **old**-string search names a *wrong* commit at exit 0,
579
- the old string still being present in that tree: measured at #206's
578
+ the old string still being present in that tree: measured at
580
579
  `0dc39ef^`, `| head -1` names the rename `4fd2f73`, not the fix. It is the
581
580
  **new**-string search the paragraph above forbids that prints nothing at exit
582
581
  0 there, indistinguishable from "the change never landed"; the old-string
583
582
  search goes empty on a checkout that predates the old string's own arrival
584
- at that path — behind that rename in #206's case, and with no rename in play
583
+ at that path — behind that rename in that case, and with no rename in play
585
584
  at all in this file's: measured at `647ae44^`, which already tracks this
586
585
  path under this name, `git log -S 'ls-tree origin/main'` prints nothing at
587
586
  exit 0.
588
587
  Add `--reverse` and you get the *oldest* count-changing commit, which is the
589
- file's last rename whenever the string predates one — measured on #206's old
588
+ file's last rename whenever the string predates one — measured on a ticket's old
590
589
  wording, `--reverse` names `4fd2f73` ("move next-ticket and sizing-a-ticket
591
590
  into the plugin"), a refactor that clears an ancestry gate exactly as
592
591
  well as the real fix, while newest-first `| head -1` names `0dc39ef`, the
@@ -597,28 +596,28 @@ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
597
596
  before citing it in the close, and treat empty output as an answer you did
598
597
  not get rather than a commit.
599
598
 
600
- Measured, one run: #132's one-line remedy had shipped in `e7b11e6` ten days
601
- earlier and #134's AC-2 asked for an exit code a later design (#64)
599
+ Measured, one run: one ticket's one-line remedy had shipped in `e7b11e6` ten days
600
+ earlier and another's AC-2 asked for an exit code a later design
602
601
  deliberately changed — neither commit carried a trailer back, so the tracker
603
- showed both as open work. #132 cost a full claim, worktree and implementer
604
- dispatch to learn this; #134 would have shipped a test asserting the opposite
602
+ showed both as open work. The one-line-remedy ticket cost a full claim, worktree and implementer
603
+ dispatch to learn this; the exit-code ticket would have shipped a test asserting the opposite
605
604
  of the shipped behaviour. The two probes that settled both took seconds.
606
605
  **A ticket deferred from a review is a claim about a tree that has since
607
606
  moved** — and the older the ticket, the more it has moved, so this bites
608
607
  hardest at exactly the head of an oldest-first queue.
609
608
 
610
609
  Measured again 2026-08-19: four stale in the 20 oldest, and the construct
611
- probe caught **none** of the four. It **missed** #156 — the two pins and the
610
+ probe caught **none** of the four. It **missed** a ticket whose two pins and the
612
611
  `contentWords()` extraction it asks for had all landed (`d016414`, `1abd6c8`)
613
612
  while `overlap()`, the construct, sat right where the ticket said, so the
614
613
  probe passed the ticket through as live work and it cost a claim, a worktree
615
- and a dispatch. It **missed** #205, whose `d:` scan `candidates.test.mjs`
614
+ and a dispatch. It **missed** a ticket whose `d:` scan the candidates test suite
616
615
  already pinned — `6d94451` and `43d6ac5` both added `.d` assertions, and the
617
- ticket's own closing comment cites both. It **missed** #206, whose wording
616
+ ticket's own closing comment cites both. It **missed** a ticket whose wording
618
617
  defect `0dc39ef` had already fixed — by an **equivalent rewording**, not by
619
618
  the literal string the ticket proposed, which appears nowhere in
620
619
  `origin/main`; the ticket's **line number** had drifted too, `:95` → `:98`.
621
- And #187 it could not read at all: that ticket's file is untracked in
620
+ And one ticket it could not read at all: that ticket's file is untracked in
622
621
  `origin/main`, the fatal-not-empty case above.
623
622
 
624
623
  **`staleness.mjs` runs that check for you, and answers in THREE values.**
@@ -632,7 +631,7 @@ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
632
631
  for. Give exactly one — the direction is not inferable from the string, and
633
632
  the wrong one answers the opposite verdict with full confidence.
634
633
 
635
- A needle that itself starts with `--` — #240's `--label ready-for-agent`
634
+ A needle that itself starts with `--` — `--label ready-for-agent`
636
635
  is one this backlog carries — needs the end-of-options separator: `--gone
637
636
  -- '<string>'`/`--present -- '<string>'`. Given bare, with no `--`
638
637
  immediately before it, the value guard still refuses it — `staleness:
@@ -654,7 +653,7 @@ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
654
653
 
655
654
  What it refuses to answer is the point of it. It reads `origin/main` and
656
655
  nothing else — never the working tree, never anything on disk — so a path
657
- this repo does not track is exit 2 rather than a clean read: that is #187's
656
+ this repo does not track is exit 2 rather than a clean read: that is the untracked-file
658
657
  case and the generated-artifact case together, `agent-test` being written
659
658
  into a claimed worktree by `claim-ticket.sh`'s heredoc, which makes every
660
659
  copy under `.worktrees/` a snapshot of whenever that worktree was claimed.
@@ -666,9 +665,9 @@ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
666
665
  the string closes a live ticket.
667
666
 
668
667
  It does not run a reproduction. The general "is this still reproducible?"
669
- oracle over the whole backlog is what #238 ruled out, and a reproduction run
668
+ oracle over the whole backlog is ruled out, and a reproduction run
670
669
  without a positive and a negative control misattributes causes rather than
671
- merely missing defects — the #230 check needed a purpose-built fixture plus
670
+ merely missing defects — one such check needed a purpose-built fixture plus
672
671
  both. A ticket no single string settles is a `could not check`: admitted,
673
672
  annotated in the dispatch prompt (phase 2), never quietly dropped.
674
673
 
@@ -689,8 +688,7 @@ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
689
688
 
690
689
  **This is a consumption gate**, priced for the seat where implementer
691
690
  divergence costs a claim, a worktree and a dispatch; the filing-time
692
- counterpart was repriced to *is the defect confirmed* and states its own bar
693
- inline — see `docs/adr/0001-filing-label-bar-is-defect-confirmed.md`.
691
+ counterpart was repriced to *is the defect confirmed* and states its own bar inline.
694
692
 
695
693
  No sizing agent here. `sizing-a-ticket` picks the *process path*, and that is
696
694
  phase 2's call, after the ticket is claimed.
@@ -724,7 +722,7 @@ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
724
722
  refuses refuses every Pull.
725
723
 
726
724
  **The Pull table** — every verdict a Pull can reach, and the one thing each
727
- does (ADR 0013 Decision 2 and 4):
725
+ does:
728
726
 
729
727
  | At the Pull | Action |
730
728
  |---|---|
@@ -908,12 +906,12 @@ still reads `refs/heads/<branch>` first and falls back to
908
906
  `refs/pull/<number>/head` only when that comes back empty; a cross-repo PR (a
909
907
  fork) skips the branch-ref read entirely and goes straight to the pull ref,
910
908
  because a fork's branch NAME can collide with an unrelated branch the base
911
- repo already carries under that name (#1616) — so a fork PR now gets this
909
+ repo already carries under that name — so a fork PR now gets this
912
910
  operand populated in the ordinary case, and the skip is rare rather than the
913
911
  norm for forks. Its run log names the skip: `head ref (absent): head check
914
912
  SKIPPED`. A worktree you hand to an agent directly is not backstopped at all.
915
913
  Verify here anyway. **That backstop now compares against the same ref this
916
- bullet does** — #1513 moved its operand off `headRefOid` for the reason
914
+ bullet does** — it moved its operand off `headRefOid` for the reason
917
915
  above — so it is a second
918
916
  chance to notice a stale snapshot on the one path it covers, never a reason
919
917
  to skip the ref compare here.
@@ -937,7 +935,7 @@ kernel and needs a `wait`, while a `task` job is process-level and its report
937
935
  auto-delivers on its own, like every other member's.
938
936
 
939
937
  **No per-call tier or effort anywhere on this path**: tier stays the agent
940
- definition's own frontmatter (ADR 0005), whichever `fleet-implementer-<cell>`
938
+ definition's own frontmatter, whichever `fleet-implementer-<cell>`
941
939
  definition the Pull names, and a member's Resolved tier stays readable from its transcript.
942
940
 
943
941
  **Claim what you are about to dispatch; dispatch what you have just claimed.**
@@ -959,9 +957,9 @@ definition suffix — or names one with no `agents/<definition>.agent.md`,
959
957
  before the member is live; fix the row with `row` first.
960
958
 
961
959
  **The prompt carries only what varies.** Everything shared — the
962
- unattended-member block, the `edit`/`read` absolute-path rule (#1727), the
960
+ unattended-member block, the `edit`/`read` absolute-path rule, the
963
961
  issue re-read and re-derive backstop, commit incrementally, no `git stash`, the
964
- shared `eval` kernel (#1447), enumerate-and-declare, sizing and the PR steps —
962
+ shared `eval` kernel, enumerate-and-declare, sizing and the PR steps —
965
963
  is the body of every `agents/fleet-implementer-<cell>.agent.md`, byte-identical
966
964
  across all of them, and each harness injects it as the
967
965
  member's system prompt. Never re-paste it. The prompt fills that body's
@@ -980,7 +978,7 @@ controller's probe could not look.
980
978
  member to re-fetch it, and this still costs one `gh issue view` per ticket,
981
979
  never one per member.** The fresh-context design's isolation rationale — "every
982
980
  implementer re-reads its Agent Brief... from scratch"
983
- (`docs/specs/2026-07-22-run-team-agent-fleet-design.md:178-179`) — is about a member
981
+ — is about a member
984
982
  never inheriting another ticket's context, not about where the bytes come from.
985
983
  Pasting the Pull's own read into the prompt keeps that: the member still gets the
986
984
  brief verbatim and re-derives nothing from a sibling. What it drops is the
@@ -1086,8 +1084,7 @@ a vendor id.** `@slow`, `@task`, `@smol` resolve through the operator's
1086
1084
  `modelRoles`, so an install with no Anthropic model still runs the fleet
1087
1085
  at whatever each role points at; the explicit `:<level>` suffix wins over
1088
1086
  the role's baked one, and the tier check judges a member against the
1089
- role's own target (`modelRoles.<role>`), never a model family (ADR 0011,
1090
- ADR 0014).
1087
+ role's own target (`modelRoles.<role>`), never a model family.
1091
1088
 
1092
1089
  Before the run's first dispatch run `~/.fleet/bin/fleet-run tier-roles.mjs
1093
1090
  --check`; exit 1 names every definition whose `model:` is not a route,
@@ -1097,7 +1094,7 @@ would clamp it silently), every
1097
1094
  `task.agentModelOverrides` entry that would shadow a fleet definition, and
1098
1095
  an `--agents` directory holding no `*.agent.md` definition,
1099
1096
  prints the exact remedy, and **stops the run** before any member is
1100
- dispatched — the fleet reads that config and never writes it (ADR 0003).
1097
+ dispatched — the fleet reads that config and never writes it.
1101
1098
 
1102
1099
  **Every 5th Pull by ledger count goes at an exploration cell.** Count the `impl-`
1103
1100
  rows in `.fleet/ledger.md` at Pull time; the Pull that creates row 5, 10, 15 …
@@ -1157,8 +1154,8 @@ effort, because a deliberate dispatch whose two sides resolve to the same model
1157
1154
 
1158
1155
  **Why one in five within the run, not a week of one tier then a week of the other:**
1159
1156
  tier would then be confounded with calendar date and therefore with prompt
1160
- evolution, which is exactly the state #864 documents and the reason the rows
1161
- already on disk cannot answer the question they were collected for.
1157
+ evolution, which is exactly the state the rows already on disk are in, and why
1158
+ they cannot answer the question they were collected for.
1162
1159
 
1163
1160
  The raw split still favours the top tier — 3 failures in 11 `routine`/`sonnet`
1164
1161
  rows against 3 in 55 `routine`/`opus`. **Do not read that as a tier result.**
@@ -1166,9 +1163,9 @@ Tier remains largely confounded with calendar date and therefore with prompt
1166
1163
  evolution: 8 of the 11 `sonnet` rows fall on 2026-08-13 to 08-17, before the
1167
1164
  window in which 54 of the 55 `opus` rows were run, and the dispatch prompts
1168
1165
  gained rules throughout. The confound is **weakened, not resolved.** Three
1169
- `sonnet` rows now break it rather than one — **#714** (2026-08-20, a
1170
- maintainer-authorized deliberate control) and **#750** and **#751**
1171
- (2026-08-21) — all three run against prompts of the same vintage as the `opus`
1166
+ `sonnet` rows now break it rather than one — a maintainer-authorized
1167
+ deliberate control (2026-08-20) and two more (2026-08-21) —
1168
+ all three run against prompts of the same vintage as the `opus`
1172
1169
  rows, and **all three passed**, which is the direction opposite the raw split.
1173
1170
  Three is still not a result. **What replaces this argument going forward is the
1174
1171
  within-run pairing above**: one implementer in five at the alternate tier makes
@@ -1182,7 +1179,7 @@ exist: condition a pair comparison on `sizing`/`profile`/`loc`/`files` before
1182
1179
  reading it as a tier result, never on the raw split.
1183
1180
 
1184
1181
  `minted_false_claim` **discriminates and no longer reads "always yes"** — 20 of
1185
- the 66 `routine` rows carry `no`, 18 at `opus` and 2 at `sonnet` (#714, #750).
1182
+ the 66 `routine` rows carry `no`, 18 at `opus` and 2 at `sonnet`.
1186
1183
  Read it as a property of the TICKET before the tier: a pure code simplification
1187
1184
  need not add prose, while a correction ticket adds prose by construction. The
1188
1185
  honest summary is unchanged and is the reason this paragraph exists: the guard
@@ -1195,8 +1192,8 @@ they are gone, with only `rewrote row #N` on stderr to say so.
1195
1192
 
1196
1193
  `ledger.mjs read` is safe on a pipe as well as a redirect: its payload used to
1197
1194
  be abandoned at the pipe buffer and still exit 0, which is what left `board.mjs`
1198
- reporting `ledger read parse failed` and serving a blind cockpit for a whole run
1199
- (#246). Every use above is a recovery path, so a payload that arrives short
1195
+ reporting `ledger read parse failed` and serving a blind cockpit for a whole run.
1196
+ Every use above is a recovery path, so a payload that arrives short
1200
1197
  lands exactly where a settled `ruled:` is unrecoverable — which is why the
1201
1198
  script's own suite pins that `read`, `row`, `filed` and `ruled` each reach a
1202
1199
  pipe whole.
@@ -1204,8 +1201,8 @@ pipe whole.
1204
1201
  `check` reaches a pipe whole at both of its exits too. Its ALREADY FILED exit
1205
1202
  sits mid-branch, where falling through would run the near-miss ranking and the
1206
1203
  tracker search that exit exists to skip — so `check`'s branch is a function now,
1207
- where `process.exitCode` carries the code and a `return` is what skips them
1208
- (#808). No payload this script prints is abandoned to `process.exit()` any more,
1204
+ where `process.exitCode` carries the code and a `return` is what skips them.
1205
+ No payload this script prints is abandoned to `process.exit()` any more,
1209
1206
  and the suite drives both of `check`'s arms through a pipe on a payload the
1210
1207
  ledger sizes rather than argv. So trust that payload — and read `verdict`,
1211
1208
  because a searched-and-clean tracker and one that was never read share exit 0.
@@ -1214,12 +1211,12 @@ The consumer side raised its cliff rather than removing it. `board.mjs` reads
1214
1211
  `ledger.mjs read` with an explicit `maxBuffer`, so a payload past node's
1215
1212
  default is carried rather than killed mid-flight and reported as an
1216
1213
  unreachable tool — which is how the blind cockpit came back at HTTP 200 even
1217
- after the pipe cut was gone (#807). That cap is deliberately bounded, so a
1214
+ after the pipe cut was gone. That cap is deliberately bounded, so a
1218
1215
  payload past it lands in the same blind cockpit — and so does a ledger that
1219
1216
  cannot be read at all, at any size. The read fails open to an empty ledger, and
1220
1217
  `board.json`'s `ledgerState` field now distinguishes a read that failed or
1221
- didn't parse from one that succeeded (`unread`/`unparsed`/`read`, #816) —
1222
- `spend` in the same payload carries its own error the same way (#874). Zeroes
1218
+ didn't parse from one that succeeded (`unread`/`unparsed`/`read`) —
1219
+ `spend` in the same payload carries its own error the same way. Zeroes
1223
1220
  on the cockpit are not yet proof the pipeline is idle.
1224
1221
 
1225
1222
  **Guard: accumulate per PR, never conclude inside one run.** The unit is the PR —
@@ -1249,7 +1246,7 @@ has to travel in the PR body rather than being something you already hold.
1249
1246
  `Sizing:` line typed in before the skill ever ran is byte-identical to one the
1250
1247
  skill produced, so the body cannot settle this alone and the member's report
1251
1248
  carries the second source: when it ran `sizing-a-ticket` relative to opening the
1252
- PR (#1070, measured on a member that wrote the line first, caught itself, and
1249
+ PR (measured on a member that wrote the line first, caught itself, and
1253
1250
  corrected it). **Record `sizing` only when the report places that run before the
1254
1251
  PR AND the line carries its signal.** Ordering clause missing, verdict authored
1255
1252
  before the run with no corrected value reported, or body and report naming
@@ -1417,11 +1414,11 @@ one of the same class broken — a CRLF body **broken by** the fix for depth and
1417
1414
  split headings, a symlinked worktree after fixing locked and regular-file ones,
1418
1415
  an unreadable `refs/heads/<type>/` after fixing `refs/heads` itself, a bracketed
1419
1416
  file path after fixing typos and vendored ones. **All four failed to close their
1420
- own ticket** — #65's acceptance criterion went unmet, and the other three left
1417
+ own ticket** — one's acceptance criterion went unmet, and the other three left
1421
1418
  the named defect reachable by a sibling spelling. Every one was caught by
1422
1419
  review, at review cost, which runs 3-5x the implementation it checks.
1423
1420
 
1424
- **Prose-first** and **wrongly-REFUSE** are not padding — they are the #394 case,
1421
+ **Prose-first** and **wrongly-REFUSE** are not padding — they are the case
1425
1422
  which shipped with **enumerate-and-declare** already in its prompt. It missed a
1426
1423
  shape its own ticket named in passing, because it enumerated from the mechanism
1427
1424
  instead of the text; and it introduced a regression refusing every `node --test`
@@ -1532,7 +1529,7 @@ owes beyond its row:
1532
1529
  - **Monitor: `ready-to-merge` appears** → nothing to record; run the tick, and
1533
1530
  on `DISPATCH merge-bot` dispatch the next `merge-bot-<n>` (**Merge bot**).
1534
1531
  Catches hand-added labels as well as a finisher's own. The bot does not wait
1535
- for that finisher's report (ADR 0012 Decision 2): its rebase is server-side,
1532
+ for that finisher's report: its rebase is server-side,
1536
1533
  `gh pr update-branch --rebase`, so nothing on the finisher's worktree has to
1537
1534
  happen first.
1538
1535
  - **Merge-bot pass reports done** → write each `held-behind-#<lower>` it reports
@@ -1605,7 +1602,7 @@ owes beyond its row:
1605
1602
  exactly the PR that needed no fixes.
1606
1603
  - **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → no workflow run will ever
1607
1604
  complete for this repo, so the CI-run-completion edge above never fires and
1608
- waiting for it stalls the whole PR — the same silent-stall shape #111 reported
1605
+ waiting for it stalls the whole PR — the same silent-stall shape reported
1609
1606
  before this verdict existed. Dispatch the finisher off the reviewer's final
1610
1607
  verdict instead, the moment it lands — and, same as above, never while you still
1611
1608
  owe it a ruling — or hold anything else it has not received, a ruling you have
@@ -1654,7 +1651,7 @@ depth** guard table applied in code. Act on each line as it reads:
1654
1651
  - `DISPATCH merge-bot` — the next `merge-bot-<n>` (**Merge bot**).
1655
1652
  - `DISPATCH finisher PR#<M> …` — a finisher settled `labelled`, yet the open
1656
1653
  list shows PR M without `ready-to-merge`, and no `label-off=` (**Run ledger**)
1657
- accounts for the removal (#2331). Apply the finisher gate (**Reviewers**: the
1654
+ accounts for the removal. Apply the finisher gate (**Reviewers**: the
1658
1655
  `check` job green on the current head), then dispatch the next-suffix
1659
1656
  finisher at that head — `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`, one
1660
1657
  letter past the highest the PR has used. Never add the label yourself. A head
@@ -1709,7 +1706,7 @@ the `HOLD (tier unchecked impl-<N>)`. Nothing else in the loop owns it.
1709
1706
  the reviewer cap. It defaults to the reviewer cap, and the reviewer slots it
1710
1707
  leaves still serve fix-appliers. Leave it at its default: every review unit
1711
1708
  already counts against the session's single `task.maxConcurrency` semaphore,
1712
- which queues at its ceiling rather than refusing (#1771), so reviews run up
1709
+ which queues at its ceiling rather than refusing, so reviews run up
1713
1710
  to the reviewer cap without a tighter explicit bound.
1714
1711
 
1715
1712
  **Why every wake.** A merge cascade is a firehose of merges, CI greens and
@@ -1718,7 +1715,7 @@ drains to 0 and stays there — 0 implementers emit no completion event, so a
1718
1715
  refill that waited for one would never fire. A tick on every wake you are
1719
1716
  already handling is what makes that drain visible. **Every wake is still an
1720
1717
  edge, so none covers a fully drained queue**: no members and no open PRs is no
1721
- event at all, and the tick goes unrun. That state is the heartbeat's (#357).
1718
+ event at all, and the tick goes unrun. That state is the heartbeat's.
1722
1719
 
1723
1720
  **Beat when there is nothing to do, and never end your turn on a drained
1724
1721
  queue.** You cannot be woken. A backgrounded Monitor does not wake an idle
@@ -2003,7 +2000,7 @@ it assembles the result, and has `agent()` return **into the script**, so no
2003
2000
  report can go undelivered and you relay nothing — the delivery failure that
2004
2001
  cost one fleet five reports on one PR and four on another. None of it runs on
2005
2002
  your turn: a review takes 20-40 minutes, and a controller that held its turn
2006
- for each one, one at a time, was what left implementer slots empty (map #1768).
2003
+ for each one, one at a time, was what left implementer slots empty.
2007
2004
 
2008
2005
  **Know the trim before you rely on it — it is wider than `docsOnly` suggests.**
2009
2006
  `diff-stats.mjs` calls a PR docs-only only when it touches **no** src, tests *or*
@@ -2015,17 +2012,17 @@ too big for the size tier now runs correctness+silent-failure+comments, not
2015
2012
  correctness+comments; and any `single-file` or `small` profile trims to
2016
2013
  correctness+silent-failure+comments, keeping tests only when a test file is in
2017
2014
  the diff. `comments` is on that floor
2018
- unconditionally since #218 — it used to need a docs FILE, and `classify()` scores
2015
+ unconditionally — it used to need a docs FILE, and `classify()` scores
2019
2016
  any code extension `src` before it checks docs, so five production PRs whose whole
2020
2017
  substance was prose inside a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and ran
2021
2018
  without the one specialist that fit them, `dimensionsUnrun` empty every time.
2022
- That floor holds **regardless of `hasSrc`** (#236) — a one-file `.yml` or
2019
+ That floor holds **regardless of `hasSrc`** — a one-file `.yml` or
2023
2020
  `.github/` shell change gets silent-failure too, not correctness alone.
2024
2021
  It is the size **tier's** floor,
2025
2022
  so `tests-only` outranks it when the diff has no config file: that profile is
2026
2023
  assigned ahead of `single-file`/`small`, so a no-src, no-config diff that also
2027
2024
  touches a test file gets no silent-failure-hunter — a tests-only diff that also
2028
- carries a config file keeps it (#739). `single-file` means one file at **any** size, so a
2025
+ carries a config file keeps it. `single-file` means one file at **any** size, so a
2029
2026
  one-file rewrite trims too. An unknown profile widens to the full six, the safe
2030
2027
  direction, so a trim is never something to count on in advance — and a full six
2031
2028
  is never something to assume.
@@ -2062,7 +2059,7 @@ reads every one off the file and makes every ruling on them
2062
2059
  and it is present on a healthy run as well as a degraded one, so there is
2063
2060
  nothing to notice by its absence. The snapshot is `git archive`d and then
2064
2061
  `git init`ed with one commit, and the block that cuts it compares that commit's
2065
- tree hash against the reviewed commit's (#1056): verified, a suite run in the
2062
+ tree hash against the reviewed commit's: verified, a suite run in the
2066
2063
  snapshot collects and runs what a checkout does, and a red is a fact about the
2067
2064
  tree. UNVERIFIED, it is not — tests that ask git what ships decline or fail for
2068
2065
  the environment, and this field carries which line of the cut failed. The
@@ -2089,7 +2086,7 @@ evidence in `reason`, and you copy those entries to the ledger's `ruled` line
2089
2086
  specialist that dies contributes zero findings while its key stays in
2090
2087
  `dimensionsRun`; a review whose one shared test run executed nothing — the
2091
2088
  review runs the test command once, and every specialist reads that run instead
2092
- of running its own (#2315) — leaves every key there with no suite behind it. So
2089
+ of running its own — leaves every key there with no suite behind it. So
2093
2090
  read the two together. A key
2094
2091
  in `dimensionsRun` and NOT in `dimensionsUnrun` ran a suite; every
2095
2092
  `dimensionsUnrun` entry is `{dimension, reason}` naming which failure it was.
@@ -2101,7 +2098,7 @@ the fallback below states for a killed specialist, for the same reason.
2101
2098
  The rule this replaces — treat any dimension with nothing in
2102
2099
  `survived`/`refuted`/`unverified` as unrun — was the workaround for having no
2103
2100
  such field, and it over-refuses in the direction that costs work: a dimension
2104
- that ran clean has nothing in those three either (#137, #138).
2101
+ that ran clean has nothing in those three either.
2105
2102
 
2106
2103
  **`cwdAudit` is the specialist's own inherited-checkout audit, one entry per
2107
2104
  dispatched dimension: `{dimension, state, line}`, `state` one of**
@@ -2111,7 +2108,7 @@ returning and fold the result into a `CWD-AUDIT:` line — a convention, not
2111
2108
  schema, so a specialist that never emits it or misspells it still validates
2112
2109
  clean. This field is the runtime backstop that reads for the line regardless:
2113
2110
  `missing` is exactly as loud as `dirty`, and both name a checkout you should
2114
- treat as a live scratch write until you have checked it (#1433/#1673).
2111
+ treat as a live scratch write until you have checked it.
2115
2112
 
2116
2113
  **A throw, an empty return, or a notification whose status is not `completed`
2117
2114
  is a failure event, not a clean review.** The review throws on missing
@@ -2162,7 +2159,7 @@ what lifts the tick's merge hold; a dispatched-but-live one does not, and
2162
2159
  hold and nothing else: survivors of a returned review the row also carries
2163
2160
  stay unanswered through its settle, so the tick prints `DISPATCH fix-pr
2164
2161
  PR#<M>` again once it lands, and that one — `dispatch` now prints `null` —
2165
- is a review fix-applier, dispatched as above (#2328). The push moves the
2162
+ is a review fix-applier, dispatched as above. The push moves the
2166
2163
  head after `ready-to-merge`, so the next merge bot refuses it
2167
2164
  `head-moved-after-label-#<M>`: a fresh finisher, per **Failure handling**.
2168
2165
 
@@ -2554,8 +2551,8 @@ the current one.
2554
2551
  dispatch with the same weight as a ruling you have already made.** It does not
2555
2552
  feel like one — you have decided nothing yet, so the outbox reads empty — but a
2556
2553
  member waiting on you is a member that will push once you answer, and the SHA
2557
- you are about to pin is exactly what that push moves. Measured on #488's run:
2558
- `fix-pr-488` asked whether to add two pins, and the finisher was held until the
2554
+ you are about to pin is exactly what that push moves. Measured on one run:
2555
+ a `fix-pr-<M>` member asked whether to add two pins, and the finisher was held until the
2559
2556
  member acknowledged the answer. That worked because the controller chose to
2560
2557
  hold, not because a rule required it. Answer it, or tell the member you are not
2561
2558
  ruling and it should proceed on its own default — either empties the outbox.
@@ -2579,7 +2576,7 @@ a minute apart showed *different* mutants, so a member's report and any single
2579
2576
  healthy worktree. Two checks, each with the instrument that can answer it.
2580
2577
  **Dirty:** the row's `dirty` field, or `git status --porcelain -unormal`
2581
2578
  inside the worktree itself — the explicit mode, never bare `--porcelain`, or
2582
- `status.showUntrackedFiles = no` reads a dirty worktree as clean (#730). The
2579
+ `status.showUntrackedFiles = no` reads a dirty worktree as clean. The
2583
2580
  row is the better read: in a worktree whose `.git` linkage is missing,
2584
2581
  `git status` answers for the enclosing repo at rc 0, where the audit reports
2585
2582
  the worktree unreadable. **Diverged:** the worktree's `HEAD` against your
@@ -2629,7 +2626,7 @@ a minute apart showed *different* mutants, so a member's report and any single
2629
2626
 
2630
2627
  **That range is right for the positive check and wrong for a negative one.**
2631
2628
  It spans the implementer's commits too, so a constraint of the form *file X
2632
- was not touched* has to be scoped to the apply commit. Measured on PR #776:
2629
+ was not touched* has to be scoped to the apply commit. Measured on one PR:
2633
2630
  a controller wrote "neither document was touched" against
2634
2631
  `origin/main...HEAD` on a two-commit branch whose documents the IMPLEMENTER
2635
2632
  had correctly edited — the PR's whole point — and a finisher reading that
@@ -2641,7 +2638,7 @@ a minute apart showed *different* mutants, so a member's report and any single
2641
2638
  regex, delete the guard clause, flip the per-entry reset, run `<testCmd>`,
2642
2639
  watch it redden, discard — is the half of this duty reading a diff cannot
2643
2640
  do, and it stays. But it **writes**, and the PR's worktree belongs to
2644
- another member. Measured on #380: a finisher was inside that worktree at the
2641
+ another member. Measured once: a finisher was inside that worktree at the
2645
2642
  instant the fix-applier announced one more clause to land, and neither
2646
2643
  ordering is detectable afterwards from the diff — a restore lands on the
2647
2644
  uncommitted clause and destroys it silently, or the mutant is still in the
@@ -2692,7 +2689,7 @@ a minute apart showed *different* mutants, so a member's report and any single
2692
2689
  that, and it is no licence to skip the read where they exist.
2693
2690
  - **(b) Add the label:** `gh pr edit <pr> --add-label ready-to-merge`. (a)
2694
2691
  passing labels nothing — it is the precondition, and this command is the
2695
- duty. Two finishers in one run (#2331) stopped at (a) and reported
2692
+ duty. Two finishers in one run stopped at (a) and reported
2696
2693
  `labelled` on PRs that sat out of the merge queue.
2697
2694
  4. Report you the label (its post-add read-back: `gh pr view <pr> --json labels`
2698
2695
  run after 3(b), output as printed), the deferral issue numbers — a
@@ -2772,7 +2769,7 @@ it reached, so reading that summary alone reads a partial suite as a whole one:
2772
2769
 
2773
2770
  **Give the finisher duty 3 verbatim as well, as its two steps.** The finisher's
2774
2771
  agent definition carries no duty text, so this brief is the whole of duty 3 it
2775
- sees. Two finishers in one run (#2331) read the release-label check as the
2772
+ sees. Two finishers in one run read the release-label check as the
2776
2773
  whole duty and reported `labelled` on a PR that never got the label:
2777
2774
 
2778
2775
  > **Duty 3 is two steps, and only the second one labels.**
@@ -2787,7 +2784,7 @@ whole duty and reported `labelled` on a PR that never got the label:
2787
2784
 
2788
2785
  **Once the label is on, take it off before you approve any push.** The label is a
2789
2786
  verdict on the tree the finisher read, and a GitHub label does not follow the
2790
- branch — on #180 it survived a push and came to sit on a commit nobody had
2787
+ branch — on one PR it survived a push and came to sit on a commit nobody had
2791
2788
  audited. Write `label-off=<latest finisher attempt>` onto the PR's row first
2792
2789
  (`ledger.mjs row`, the row's whole text plus the token — **Run ledger**), then
2793
2790
  remove `ready-to-merge`, then approve. The token is how the tick tells your
@@ -2834,8 +2831,8 @@ finisher this verbatim, so it derives the cause itself instead of asking anyone:
2834
2831
  > still differs from your pin, and `git reflog` in the worktree reads a plain
2835
2832
  > `commit` at the move — no `reset`/rebase entry there, any of those sitting
2836
2833
  > at or behind the pin as provenance. A member kept working and committed
2837
- > after you were dispatched. Measured 2026-08-28 on #983, where the finisher
2838
- > matched neither cause above and halted on its own judgement (#997).
2834
+ > after you were dispatched. Measured 2026-08-28 on one PR, where the finisher
2835
+ > matched neither cause above and halted on its own judgement.
2839
2836
  > Halt, name `past-pin`, and report **the commit, and whether it
2840
2837
  > is pushed, unpushed, or unknown**: `git log -1 --format='%h %s'` names it,
2841
2838
  > and `git ls-remote origin <branch>` answers the rest — a non-zero exit or
@@ -2953,7 +2950,7 @@ after the same command finds a line known to match.** Prose fragments and
2953
2950
  code snippets routinely carry `\`, `.`, `*`, `[` or `$`, and without `-F` those
2954
2951
  are read as a pattern rather than as the text itself, so the command answers
2955
2952
  for a different string from the one the claim names — and a wrong zero is the
2956
- benign-looking answer. Measured on #1087: `grep -c 'settled by:\s+x'` answers
2953
+ benign-looking answer. Measured once: `grep -c 'settled by:\s+x'` answers
2957
2954
  0 against a file holding that exact line, and `grep -cF` answers 1. A zero or
2958
2955
  an absence counts only after the same command, with the same flags, finds a
2959
2956
  line known to match: a command that cannot find a match settles nothing, and
@@ -3172,7 +3169,7 @@ ledger rows in the same step. See references/reaping.md.
3172
3169
 
3173
3170
  ## Worktree and claim model
3174
3171
 
3175
- Ruled on #1315, measured 2026-09-09 in a throwaway clone (`/tmp/fleet-probe`)
3172
+ Measured 2026-09-09 in a throwaway clone (`/tmp/fleet-probe`)
3176
3173
  that never touched the real checkout.
3177
3174
 
3178
3175
  **Claim, release and reap are unchanged on omp.** `claim-ticket.sh`,
@@ -3208,24 +3205,24 @@ that session, so the recipe is the dispatch-prompt absolute path, plus
3208
3205
  `bash`'s own `cwd` parameter set to it on every call and absolute paths for
3209
3206
  `write`/`edit`.
3210
3207
 
3211
- **The one open gap this ticket measured: `task` does not accept a per-dispatch
3208
+ **The one open gap that probe measured: `task` does not accept a per-dispatch
3212
3209
  working directory.** `omp://tools/task.md` documents non-isolated spawns as
3213
3210
  running `runSubprocess(...)` "directly with parent cwd" — no `cwd` field
3214
3211
  appears anywhere in the item schema — and the probe above confirms it in
3215
3212
  practice: the recipe is the absolute-path discipline above, not a placeholder
3216
3213
  for a `cwd` field that does not exist. The gap is now enforced rather than only
3217
- written down: the plugin's `member-write-guard` omp extension (ADR 0020)
3214
+ written down: the plugin's `member-write-guard` omp extension
3218
3215
  refuses a fleet member's `write`/`edit`/`ast_edit` into the main checkout's
3219
3216
  non-ignored tree and an implementer's `bash` from a main-checkout cwd, and the
3220
- missing field itself is requested upstream as can1357/oh-my-pi#13754.
3217
+ missing field itself is requested upstream in `can1357/oh-my-pi`.
3221
3218
 
3222
3219
  **The same gap reaches past the filesystem: `task`-dispatched members share one
3223
- `eval` kernel.** Measured 2026-09-21 on #1447, in a live run rather than a
3220
+ `eval` kernel.** Measured 2026-09-21, in a live run rather than a
3224
3221
  probe clone: two sibling implementers dispatched in the same batch, and the
3225
3222
  controller that dispatched both, reported the same Python kernel pid and the
3226
3223
  same runner file under `$TMPDIR/omp-python-runner/`, and each read the others'
3227
3224
  top-level bindings out of its own `eval` cell — a bare `WT` bound by one member
3228
- was read back by a sibling and by the controller, the collision #1447 was filed
3225
+ was read back by a sibling and by the controller, the collision a ticket was filed
3229
3226
  on as an unproven self-report. `omp://tools/eval.md` states the mechanism:
3230
3227
  retained kernels are keyed by `python:${sessionId}`, normalized cwd and
3231
3228
  interpreter — `js:${sessionId}` for the JS VM — and "Parent and ordinary task
@@ -3287,9 +3284,9 @@ where the controller itself runs from.
3287
3284
  yourself closes nothing and is left unlabelled for the maintainer, so no
3288
3285
  member of the fleet will ever review it, and counting it floors the backlog at
3289
3286
  a depth nothing in the run can drain — the implementer gate then holds for the
3290
- rest of the run against a queue of nothing (#590). GitHub's own linked-issue
3291
- set decides that, not a keyword regex over the body; see
3292
- `docs/agents/issue-tracker.md`. **That exemption is for the chore PR THIS run
3287
+ rest of the run against a queue of nothing. GitHub's own linked-issue
3288
+ set decides that, not a keyword regex over the body.
3289
+ **That exemption is for the chore PR THIS run
3293
3290
  authors, never one a PRIOR run left open** — step 0 folds those into this
3294
3291
  run's review queue, so count one when you reason about backlog BY HAND. **The
3295
3292
  `fleet-tick.mjs` number still excludes it**: nothing in its filter
@@ -3352,7 +3349,7 @@ A main checkout that is not `clean` against its Phase 0 baseline outranks all
3352
3349
  of them, and every dispatching row besides: `HOLD (main checkout dirty)`,
3353
3350
  `HOLD (main checkout unknown)` or `HOLD (main checkout no baseline)` on the
3354
3351
  implementer, reviewer and merge-bot rows alike, beside the `MAIN-CHECKOUT-*`
3355
- line that says why (#2210).
3352
+ line that says why.
3356
3353
 
3357
3354
  `/triage` is user-invoked only — suggest, never run. The suggestion is a report,
3358
3355
  not a blocking prompt. Counts come from cheap `gh issue list --search`, no bodies.
@@ -3405,9 +3402,9 @@ ticket over a failure a re-run would have cleared.
3405
3402
  held by another worktree, or strands the feature worktree on `main`. After the
3406
3403
  merge, `delete-merged-branch.sh <pr>` deletes the branch from `origin` and reads
3407
3404
  the deletion back; `reap.sh` takes the `[gone]` local branch and its worktree.
3408
- No repo setting is relied on to do it (#2196). A branch another open PR still
3405
+ No repo setting is relied on to do it. A branch another open PR still
3409
3406
  uses as its head or base is kept instead — `branch-kept-#<that PR>` in the bot's
3410
- report, a deliberate keep and not a failure (#2295).
3407
+ report, a deliberate keep and not a failure.
3411
3408
  The branch-delete step also releases the claim label: it drops `in-progress` from
3412
3409
  every issue the PR closes.
3413
3410
 
@@ -3416,7 +3413,7 @@ every issue the PR closes.
3416
3413
  Non-empty `git status --porcelain -unormal` → stop and report — the explicit
3417
3414
  mode, never bare `--porcelain`, or `status.showUntrackedFiles = no` reads an
3418
3415
  empty answer here and licenses the rebase over work this check exists to
3419
- protect (#730). Stashing empties it either way, so that check and
3416
+ protect. Stashing empties it either way, so that check and
3420
3417
  `no-undo-audit.sh` both go quiet on work nothing else holds.
3421
3418
 
3422
3419
  **Cross-check what members report about their environment.** Wrong often enough
@@ -3435,8 +3432,8 @@ failures arrive as *wrong findings*, not errors:
3435
3432
  separate worktrees, but the process table is not partitioned by them and a
3436
3433
  test file's name is identical in every one, so a pattern naming a test file
3437
3434
  matches whichever member happens to be running it. Measured: an implementer
3438
- chasing its own stalled run issued `pkill -f "claim-ticket.test.mjs"` and
3439
- killed a `node --test claim-ticket.test.mjs inflight.test.mjs` that was not
3435
+ chasing its own stalled run issued a `pkill -f` on its test file's name and
3436
+ killed a `node --test` over two test files that was not
3440
3437
  its own.
3441
3438
 
3442
3439
  **What the victim's output looks like depends on the signal — and one of the
@@ -3574,7 +3571,6 @@ end of a 7-PR run. A mid-run tooling fix goes through a PR like every other
3574
3571
  change, and that PR faces every required check any other PR faces — the set
3575
3572
  `.github/rulesets/main.json` declares — so it carries a release label too.
3576
3573
  Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
3577
- ADR 0007 records the gate and why it has no exemption.
3578
3574
 
3579
3575
  ## Failure handling
3580
3576
 
@@ -3613,7 +3609,7 @@ still holding its claim and its worktree, so the killed row above does not
3613
3609
  apply to it; mtimes unchanged at both are the dead signature.** Only the first
3614
3610
  of those two verdicts is conclusive — a member wedged on a call that writes
3615
3611
  nothing freezes its scratch dir too — so settle the dead one on the liveness
3616
- read below, never on the two listings alone. Measured on #503: a refuter
3612
+ read below, never on the two listings alone. Measured once: a refuter
3617
3613
  wedged forever on `until grep -q` for a marker `node --test` never writes, its
3618
3614
  transcript's record counts unchanged across two polls while its own scratch
3619
3615
  files carried fresh mtimes throughout — alive the entire time it read as dead.
@@ -3657,11 +3653,11 @@ wrote it. Never rotate mid-run: it is phase 0's step alone.
3657
3653
  One line per ticket, rewritten in place (`ledger.mjs row <ticket> <text>`):
3658
3654
 
3659
3655
  ```
3660
- #332 impl-332=PR#344 → PR#344 → MERGED 73b356de
3661
- #324 impl-324=PR#346 → PR#346 · fix-pr-346 · ports=16324 · ruled:6-applies · held-behind:#313
3662
- #351 impl-351 · tier=task-high
3663
- #358 excluded · behind-pr:#346
3664
- #360 excluded · behind-issue:#351
3656
+ #<t1> impl-<t1>=PR#<p1> → PR#<p1> → MERGED 73b356de
3657
+ #<t2> impl-<t2>=PR#<p2> → PR#<p2> · fix-pr-<p2> · ports=16<t2> · ruled:6-applies · held-behind:#<t3>
3658
+ #<t3> impl-<t3> · tier=task-high
3659
+ #<t4> excluded · behind-pr:#<p2>
3660
+ #<t5> excluded · behind-issue:#<t3>
3665
3661
  ```
3666
3662
 
3667
3663
  **A member's token is `<member>` while it is live and `<member>=<outcome>` once
@@ -3748,7 +3744,7 @@ Plus two append-only lists:
3748
3744
  filers append filings with `filed`; all writes are serialized by `<file>.lock`.**
3749
3745
  Every write rewrites the whole file from what it read, so without the lock two
3750
3746
  concurrent writers are last-writer-wins — measured, 8 concurrent `filed` kept
3751
- 2–5 of 8 rows (#531). A writer that cannot take the lock within 10 s exits 2
3747
+ 2–5 of 8 rows. A writer that cannot take the lock within 10 s exits 2
3752
3748
  naming the holder's pid, having written nothing; a lock whose holder is dead is
3753
3749
  taken over, and a leftover `<file>.lock.reap` is never reclaimed. One other
3754
3750
  shape wedges the lock permanently the same way, needing the same fix: an empty
@@ -3768,7 +3764,7 @@ removal needed. The other two shapes do not clear on their own — remove
3768
3764
  **The gap the lock does not close:** `check` → `gh issue create` → `filed` is
3769
3765
  three commands, and the lock covers each one alone, so two filers can both read
3770
3766
  `clean` in the seconds before either records. Accepted — the measured
3771
- same-run accidental duplicate, #298 → #302, was filed minutes apart — and no
3767
+ same-run accidental duplicate was filed minutes apart — and no
3772
3768
  claim/reserve step exists to close it.
3773
3769
 
3774
3770
  `check` exits **0** clean, **1** already in this run's filed list, **2** usage
@@ -3777,7 +3773,7 @@ those and decide. Exit **3** is scored: some row gh returned has to score above
3777
3773
  zero against the subject, because the ANDed query also matches issues the
3778
3774
  overlap rates 0.00, and every measured stop over those was survived only by a
3779
3775
  reader who overrode it and searched the tracker by hand — obeying it would have
3780
- dropped a real deferral (#388). It also prints the closest filed rows with an overlap score.
3776
+ dropped a real deferral. It also prints the closest filed rows with an overlap score.
3781
3777
  Those never move the exit code — the same finding gets worded differently by
3782
3778
  whoever finds it second — but once the tracker read succeeds, a filed row at or
3783
3779
  above `NEAR_SOFT_HIT` in `ledger.mjs` does move the verdict to `soft-hit`, as
@@ -3795,8 +3791,7 @@ that was never read and from one whose rows you have to read yourself.
3795
3791
  The ledger half reports its own readability as its own field, `ledger.ok`, the
3796
3792
  peer of `tracker.ok`: false when the file did not exist, and false too when the
3797
3793
  path led to something that did not parse as a ledger — which is what tells a
3798
- ledger that was read and held nothing filed from one there was nothing to read
3799
- (#231). The absent case is the normal one for a run's first `check` — `.fleet/`
3794
+ ledger that was read and held nothing filed from one there was nothing to read. The absent case is the normal one for a run's first `check` — `.fleet/`
3800
3795
  is git-ignored and created lazily by the first write — so it stays `clean` at
3801
3796
  exit 0, and `ledger.ok` is the field that says why rather than the verdict
3802
3797
  moving. The stderr warning is deliberately narrower than the field: it fires on
@@ -44,7 +44,7 @@ never that anyone verified anything.
44
44
 
45
45
  Why controller needs the verdict by name: no workflow run will ever complete
46
46
  here, so the CI-run-completion edge never fires and waiting on it stalls the
47
- whole PR — the silent-stall shape #111 reported before this verdict existed.
47
+ whole PR — the silent-stall shape reported before this verdict existed.
48
48
  SKILL.md's `no-ci` edge therefore dispatches the finisher off the reviewer's
49
49
  final verdict instead — that edge, not this file, carries the conditions on it.
50
50
  Under `no-ci` the script reads no run list and no run view: no workflow, nothing
@@ -14,11 +14,11 @@ Fix text **paraphrases the issue body's framing** instead of being checked claus
14
14
 
15
15
  ## Second mechanism: minted, not inherited — scope creep in the prose
16
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.
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 fix PR 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
18
 
19
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
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.
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: measured here, `always()` reds the named assertion, and only the narrower `always() && steps.mutate.outcome == 'success'` reds the true one.
22
22
 
23
23
  Two rules for the implementer, both cheap: **write no prose the ticket did not ask for** — 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
24
 
@@ -28,10 +28,10 @@ Put check on **implementer**, not only reviewer: every factual claim the diff re
28
28
 
29
29
  ## Citing evidence from another repo's run
30
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:
31
+ A bare `#N` copied from another repo's run reads as **this** repo's N — 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
32
 
33
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.
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/<owner>/<repo>` returns 404 for a repo that lives only on a GHE host, so `owner/repo#N` would point at nothing.
35
35
  - **This repo's own issues and PRs stay bare `#N`.** Convention covers foreign evidence only; qualifying local reference is noise.
36
36
 
37
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.
@@ -16,7 +16,7 @@ Holding the dispatch tool does not authorize using it: a reviewer not told the f
16
16
 
17
17
  ## The coordination contract
18
18
 
19
- Stated once, in the vocabulary #1316 fixed — *dispatch* (start a member),
19
+ Stated once, in this fixed vocabulary — *dispatch* (start a member),
20
20
  *send* (message a live one), *wake* (a send that resumes a finished
21
21
  member's transcript), *settle* (a member's job reaching a terminal
22
22
  outcome), *consume* (the controller deliberately taking a settled result):
@@ -22,25 +22,25 @@ Every precondition recomputed **inside** same command as delete:
22
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
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
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 by a fresh check, re-read immediately before the delete, that no worktree holds the branch.** 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.
25
+ - **The delete is `git update-ref -d`'s compare-and-swap on a tip read once, authorized by that cherry check and by a fresh check, re-read immediately before the delete, that no worktree holds the branch.** 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`, the delete this replaced. `--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. 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
27
  - **A worktree that checked the branch out while the delete ran is caught after it, and the branch is put back.** git has no lock that stops `git worktree add <p> <b>` between that holder check and the delete, and such an add writes only the new worktree's `HEAD` — the ref does not move, so the compare-and-swap succeeds and leaves the worktree on a branch that no longer exists (measured, git 2.50.1). So worktree.sh's `wt_recheck_delete` re-reads the listing right after the delete — and again, up to 20 times 0.1s apart, while an add in progress is listed `locked initializing` — and when a worktree holds the branch, or the wait runs out, recreates it at the tip with a create-only `git update-ref`. The branch is a KEEP naming the worktree or the entry, and its config section stays. A restore that fails is a KEEP naming the tip, git's error and the command that restores it by hand — or, when something recreated the branch since the delete, the commit it now sits at, left as it is, since the create-only restore never overwrites it. The branch's reflog does not come back.
28
28
  - **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.
29
- - **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.
30
- - **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.
29
+ - **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. 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.
30
+ - **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). 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.
31
31
  - **`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.
32
32
 
33
33
  ## Why a second sweep, over worktrees rather than branches
34
34
 
35
35
  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.
36
36
 
37
- **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
+ **Route not established — shape is.** Do not repeat that merge bot's server-side rebase detaches worktree: measured false. Bot reported `path=rebase` on three PRs, `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.
38
38
 
39
39
  So `reap.sh` enumerates worktrees git lists with **no `branch` line at all** and decides each on own state:
40
40
 
41
- - **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
+ - **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 in review). Bound is ownership, never contents.
42
42
  - **`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.
43
- - **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
+ - **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`. 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.
44
44
  - **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).
45
45
  - **Every decline is a `kept` entry, `branch` null.** No branch to name. Gap was invisible precisely because nothing was reported.
46
46
  - **A fleet worktree whose branch no longer exists is reported, never acted on.** It keeps its `branch` line, so the enumeration above never sees it, and its `HEAD` reads as the null object id. Under `.worktrees/` only, a `kept` entry names the worktree, the missing ref, the tip its own `HEAD` reflog last named (unverified) and the `git update-ref` command that restores it. Never removed: a `git worktree add --orphan` checkout looks the same.
@@ -60,7 +60,7 @@ So nothing in the run cleans it up. Next run, the in-flight probe's local-worktr
60
60
  - **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.
61
61
  - **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.
62
62
 
63
- **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), plus a fresh check, re-read immediately before the delete, that no worktree holds the branch (`update-ref` consults no worktree, where `-D` refused a held branch; a worktree it cannot resolve, or a listing that will not re-read, stops the delete too), 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.
63
+ **The delete is `git update-ref -d`'s compare-and-swap 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), plus a fresh check, re-read immediately before the delete, that no worktree holds the branch (`update-ref` consults no worktree, where `-D` refused a held branch; a worktree it cannot resolve, or a listing that will not re-read, stops the delete too), 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; now `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.
64
64
 
65
65
  **A checkout that lands between that fresh check and the delete halts the release after it.** `git worktree add` of an existing branch does not move the ref, so the compare-and-swap succeeds under it. The same `wt_recheck_delete` reap uses then finds the worktree, recreates the branch at the tip, and the release halts with exit 2, `released:false` and a blocker naming that worktree — the shape of a holder caught before the delete. A restore that fails halts the same way, with the tip and the repair command in the blocker.
66
66