@feigi/fleet-ctl 3.71.0 → 3.71.1

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.
@@ -17,165 +17,24 @@ The war story behind a rule ending `See references/<file>` lives in that file; l
17
17
  it only when a member needs the *why*. A rule without that line carries its
18
18
  reasoning inline — nothing is missing.
19
19
 
20
- ## Rules that fail silently
21
-
22
- **A report is delivered, not implied by ending a turn.** Every member owes
23
- the controller one report naming its outcome before it exits — including a
24
- member whose prompt carries no explicit report line. The "report the SHA",
25
- "report PR number" and "stop and report" instructions below *are* that
26
- report, not a second obligation on top of it. A member that does the work
27
- correctly and ends its turn has reported nothing: the controller learns the
28
- outcome only by re-reading artifacts and pinging, and a finding held only in
29
- that member's context is lost. Members did exactly this in one run —
30
- finishers, a reviewer and merge bots alike, the work done and only the
31
- delivery missing. Every brief's report paragraph says it. See
32
- references/member-lifecycle.md.
33
-
34
- **The implementer, fix-applier, finisher, merge-bot and review-runner briefs
35
- each tell the member you do not acknowledge reports; you never write that line
36
- yourself.** A member cannot see whether its report arrived, so silence
37
- from you is indistinguishable from loss and it re-sends — three members did in
38
- one run, each burning a turn, and in all three the original had in fact arrived.
39
- Each of those templates under `briefs/` carries the line: *"The controller does
40
- not acknowledge reports. Send once and exit; never re-send unless the controller
41
- asks by name."*
42
-
43
- So when a report is missing, **ask by name — that is what the "unless the controller asks by name" clause is for — and do not attribute the gap to the member until it answers.** See references/member-lifecycle.md.
44
-
45
- The ask is the controller's move, not the member's. See references/member-lifecycle.md.
46
-
47
- **Your OWN messages can vanish the same way, and that half is not recoverable by
48
- a re-send.** Two controller rulings were lost in one run, both with a
49
- `success: true` receipt: a member proceeded on its stated default and filed a
50
- tracker issue the lost ruling had said not to file. So **never read a member's
51
- silence as assent**, and require members to report their *confirmation state*
52
- alongside results — "I escalated X, received no ruling, proceeded on default Y".
53
- That sentence is the only thing that made either loss visible. After any ruling
54
- you cannot confirm was received, re-check the artifacts it governed.
55
-
56
- **Name every member.** The name is the ledger token and the hub address; omit
57
- it and the ledger cannot match the member.
58
- Names follow the unit of work: `impl-<issue#>`, `fix-pr-<pr#>`,
59
- `review-pr-<pr#>`, `finisher-pr-<pr#>`, `merge-bot-<n>`. See
60
- references/member-lifecycle.md.
61
-
62
- **Fresh context per member.** One member, one unit of work, gone. Never
63
- re-task a finished member — waking it drags the old ticket back in. Refill =
64
- **new** member, **new** name. Sending is still right for pinging a live
65
- member for a report it owes, or resuming a truncated reply — never for
66
- handing a finished member the next ticket.
67
-
68
- `hub send` to an idle peer wakes it into its old transcript the same way; re-dispatching under the same name does not reset it — omp auto-suffixes a fresh peer (`name-2`) instead.
69
-
70
- See references/member-lifecycle.md.
71
-
72
- **You read your instruments out of a tree every member can write to — re-check them before every gate decision.** See references/instruments.md.
73
-
74
- - **Pin once**, at phase 0 step 0 below, from the main checkout you are
75
- running this from — never from a member's worktree, which is gitignored
76
- and carries no baseline:
77
- `~/.fleet/bin/fleet-run instruments.sh --pin`. On a workspace that does not
78
- track `plugin/…`, the pin names the plugin checkout once — `--pin --audit
79
- <plugin-checkout>` — and every check after it follows the recorded tree.
80
- - **Re-check before you act on any instrument reading** — a SHA acceptance, a CI
81
- verdict, the reconcile, a reap, a label gate — from that same main checkout:
82
- `~/.fleet/bin/fleet-run instruments.sh`. **Exit 0 is the only code that
83
- lets a gate proceed. Exit 1 (the set changed) and exit 2 (the check could not
84
- answer) both refuse: report what it printed and do NOT re-read the
85
- instrument** — a guard that fails open on "could not look" protects nothing.
86
- **A label gate and a CI verdict are also taken by dispatched members, not
87
- only by you** — the finisher labels, and the merge bot merges on its own
88
- reading — and neither is dispatched to read this file, so neither can be
89
- reached by stating the rule here. Each carries its own copy: the finisher's
90
- in the instrument re-check block of `agents/fleet-finisher.agent.md`, the merge bot's inside
91
- `merge-gate.mjs`, step 3 of `run-merge-bot.md`.
92
- - **Re-pin only after a change you made deliberately.** The mid-run tooling fix
93
- below is the one legitimate writer. Re-pinning to clear a refusal you cannot
94
- explain discards the check.
95
-
96
- It covers every tracked file under this repo's own plugin component directories
97
- — `plugin/commands/`, `plugin/scripts/`, `plugin/skills/`, `plugin/agents/`,
98
- `plugin/workflows/` — the probes, the libraries they source, and these runbooks,
99
- which you also read from that tree. Not the whole repo: `docs/metrics/` is
100
- appended by THIS run, so covering it would refuse on the run's own bookkeeping
101
- every time. It does not cover refs, deliberately: `claim-ticket.sh` creates a
102
- branch per ticket and `reap.sh` deletes them in the ref store every worktree
103
- shares, so ordinary work moves refs several times a run and a per-gate
104
- refusal on that is noise.
105
-
106
- **A member runs its test suite in the foreground and blocks on it.** See references/member-lifecycle.md.
107
-
108
- **The scratch root is computed, never invented and never recorded.** No harness
109
- supplies a scratch directory to a member, so a member left to name its own
110
- invents one — and the liveness read below, which looks at the files under the
111
- directory a member's own prompt assigned it, then watches a directory nobody
112
- else can find. You run `~/.fleet/bin/fleet-run scratch-root.mjs`: it prints one
113
- absolute path, `~/.fleet/scratch/<repo-key>/`, the same from the main checkout
114
- and from every linked worktree, and the same again when a compacted or
115
- re-invoked controller runs it, so nothing writes it down. It exits non-zero,
116
- with its reason, when the root would sit inside a git work tree that does not
117
- ignore it; that is an environment to fix, not a cue to pick another root.
118
- `<scratch>` in this file is that path, resolved before you send anything: every
119
- brief that carries one carries the absolute path you passed it — an
120
- implementer's `<scratch>/impl-<N>/`, the recipe deriver's
121
- `<scratch>/derive-recipe/`, a fix-applier's, a finisher's and a merge bot's
122
- `<scratch>/pr<N>/…`, and a review runner's `scratch` argument, which is the
123
- root itself. A member whose prompt names no path asks you by name and never
124
- makes one up.
125
-
126
- ## Shell traps
127
-
128
- Monitor and Bash commands run under **zsh**, and the shell in this file is
129
- prescriptive — copied verbatim into a watcher or into the merge bot's agent
130
- body. So every trap here is a zsh-vs-bash difference that ships as a
131
- green-looking gate: correct in the shell you tested in, silently wrong in the
132
- one it runs in. Phase 3's monitor paragraph points here instead of restating
133
- any of it. The merge bot's agent body is the one place this block is copied
134
- whole (see **Merge bot**); the other deliberate copy is named at the end.
135
-
136
- **zsh word-splits an unquoted command substitution's result; it does NOT split an unquoted parameter expansion.** See references/shell-traps.md.
137
-
138
- **Word the rule against the first row.** See references/shell-traps.md.
139
-
140
- **Capture-then-loop needs `while IFS= read -r` fed by a heredoc**, which is
141
- line-exact under every shell:
142
-
143
- ```sh
144
- while IFS= read -r pr; do
145
- [ -n "$pr" ] || continue # a blank line from an empty capture, not a probe that could not look
146
- node …/ci-state.mjs --pr "$pr" </dev/null # every inner call, per the trap below
147
- done <<EOF
148
- $prs
149
- EOF
150
- ```
151
-
152
- The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase 3's block uses, but it splits on *every* whitespace character, so it is safe only for values that cannot contain one — PR numbers cannot, branch names and paths can. See references/shell-traps.md.
153
-
154
- **`</dev/null` every command inside a `while read` loop.** See references/shell-traps.md.
155
-
156
- **A probe that could not look emits an event; it never `continue`s.** Stated in
157
- full at *A probe that cannot read is a transition event, not silence* in Phase 3,
158
- and it binds every watcher in this file rather than that one block: the third
159
- value beside pass and fail is what turns a broken loop into a loud failure
160
- instead of a quiet one. A guard that drops an unreadable probe — `[ -n "$json" ]
161
- || continue` — makes *could not look* indistinguishable from *nothing to report*.
20
+ ## Invariants
162
21
 
163
- **`$?`/`PIPESTATUS` is unconditionally-TRUE in zsh.** zsh has no `PIPESTATUS`
164
- (its array is lowercase `pipestatus`, 1-indexed), so `${PIPESTATUS[0]}` is always
165
- empty and `[ "" -eq 0 ]` passes. A bot's merge gate opened without ever reading
166
- an exit code.
22
+ These hold in every phase: check a wake against them before you act on it, and report any evidence that one is broken.
167
23
 
168
- **`status` is a READ-ONLY variable in zsh**, an alias for `$?`. Name the variable anything else (`ci_status`). See references/shell-traps.md.
24
+ - In-flight tickets at most the bound (default 5), at most one merge bot; the bound counts tickets, not live agents.
25
+ - A grandchild surfaces as its own task-notification; an unrecognized task-id is not a member reporting done.
26
+ - A reviewer never reviews a PR it implemented.
27
+ - The merge bot only touches PRs whose implementer reported done; rebasing a worktree someone is working in destroys uncommitted work.
28
+ - `ready-to-merge` is added by a reviewer only — never an implementer, never you — but for the run's own artifact PR, which this line does not reach: label and merge that one yourself.
29
+ - Every member acts through the maintainer's `gh` credentials, so no write is attributable: when a label moves unexpectedly, ask members directly, rule out automation with `grep -rn '<label>' .github/workflows/`, and do not re-add it.
30
+ - Phase 1 is serial; everything else may run concurrently.
169
31
 
170
- **The other deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
171
- mechanism bites argv as well as loops, and that instance stays written out in the
172
- fix-applier body and every refuter brief rather than here,
173
- because the seats that inject faults are the ones that need it and a bot reads
174
- gates without ever injecting one. Do not fold it into this block, and do not
175
- restate this block there.
32
+ The reasoning behind each line is in references/invariants.md.
176
33
 
177
34
  ## Phase 0 — shortlist
178
35
 
36
+ This phase is done when `phase0.mjs` exits 0: run it again after an exit 3 (a step failed) or an exit 4 (a `NEED` line asks you to act), and dispatch nothing before.
37
+
179
38
  Once per run, at start. Supply is automatic after that: the tick
180
39
  refreshes the Shortlist itself, and every admission is a **Pull** — one ticket
181
40
  into one free implementer slot, the moment it frees (phase 1). Nothing in this
@@ -300,8 +159,132 @@ human decision per batch of admissions, zero unilateral grabs — is retired
300
159
  is retired: zero human decisions per admission, and every non-admission is a
301
160
  label or a premise the maintainer can read.
302
161
 
162
+ ## The wake table
163
+
164
+ A wake is done when its one `fleet-event.mjs` call has run and you have acted on every line it printed, the tick's last; with nothing left to act on, arm the heartbeat and hold rather than end your turn. What a wake owes beyond its call is under **Phase 3 — event loop**.
165
+
166
+ React to events; never block on one.
167
+
168
+ **React to artifacts, not agents.** `idle` means "not currently executing", not
169
+ "done", and a finished member's finding may never arrive. Read `gh pr view`,
170
+ `gh run view`, `git -C <worktree> status` **before** messaging; when you message,
171
+ send the specific next action, never "what is your status".
172
+ See references/member-lifecycle.md.
173
+
174
+ **Do not ask permission to run the loop.** Dispatching a reviewer, spawning a
175
+ merge bot, Pulling a ticket, re-verifying a SHA, filing a follow-up — all proceed
176
+ unconfirmed. Invoking the command was the opt-in. One exception: **a judgement the
177
+ evidence cannot settle**.
178
+
179
+ **Rule: record, tick, act, beat.** Every wake — a member report, a review
180
+ notification, a label, a CI run reaching a terminal state, a `CONFLICT` line, a
181
+ heartbeat, the maintainer's drain — is one `fleet-event.mjs` call, which makes
182
+ the wake's writes and ends in one `fleet-tick.mjs` invocation, and you do what
183
+ it prints. There are no hand-run
184
+ refill or dispatch edges left. Record first, because the tick reads the run off
185
+ `.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
186
+ one it cannot see, and it names the same dispatch again. Every record goes
187
+ through `ledger.mjs` (**Run ledger**), which `fleet-event.mjs` drives — never a
188
+ hand edit. What each kind writes is in the header comment of `fleet-event.mjs`.
189
+
190
+ Run each as `~/.fleet/bin/fleet-run fleet-event.mjs <kind> <args>`, from the main checkout:
191
+
192
+ | Wake | Command |
193
+ |---|---|
194
+ | Implementer report | `fleet-event.mjs impl-report impl-<N>` |
195
+ | Review result file written (workflow notification / `review-pr-<n>` report) | `fleet-event.mjs review-result <pr> <path>` |
196
+ | Review launch failed | `fleet-event.mjs review-failed <pr> <launch>` |
197
+ | Fix-applier report | `fleet-event.mjs fix-report fix-pr-<M>` |
198
+ | Finisher report | `fleet-event.mjs finisher-report finisher-pr-<M>` |
199
+ | Merge-bot pass report | `fleet-event.mjs merge-bot-report merge-bot-<n>` |
200
+ | CI run terminal | `fleet-event.mjs ci <pr>` |
201
+ | Label seen (persistent Monitor) | `fleet-event.mjs label <pr>` |
202
+ | `CONFLICT` line | `fleet-event.mjs conflict <pr>` |
203
+ | Heartbeat | `fleet-event.mjs heartbeat` |
204
+ | Drain | `fleet-event.mjs drain --reason "<reason>"` |
205
+
206
+ ### Nothing to do: arm the beat
207
+
208
+ - **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
209
+ below. A turn that ends on a drained queue is #3's stall itself: nothing
210
+ external will wake you, and the level-check you are one command away from
211
+ never runs. Listed on its own because it is the only wake with no trigger —
212
+ every other row above arrives; this one is the absence of one.
213
+
214
+ **Beat when there is nothing to do, and never end your turn on a drained queue.** See references/ci-and-staleness.md.
215
+
216
+ ```bash
217
+ ~/.fleet/bin/fleet-run fleet-heartbeat.mjs \
218
+ [--base 300] [--ceiling 1200] [--multiplier 2] [--hold 240]
219
+ ```
220
+
221
+ It blocks, then prints one line. Which line it is, is the whole protocol:
222
+
223
+ - `… interval elapsed (quiet=<n>) → run fleet-event.mjs heartbeat` — the level-check
224
+ is due. Run that command and act on what the tick it ends in prints.
225
+ Then arm the beat again.
226
+ - `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
227
+ command blocks for a whole interval (omp backgrounds one at 60s, which is
228
+ why the CI gate holds its wait in one `eval` cell polling `gh run view`).
229
+ Issue it again. That is still one blocking call per turn, never an idle turn.
230
+
231
+ ## The tick's rows
232
+
233
+ Act on each line the tick prints as its row reads here, then stop: the next wake runs the tick again, and a row marked advice or not actionable asks nothing of you. The full text of each row is in references/tick-rows.md.
234
+
235
+ **In one line, every wake is one `fleet-event.mjs` call, which ends in the tick.** One tick invocation, and you act on what it prints:
236
+
237
+ ```
238
+ ~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--in-flight <n>]
239
+ ```
240
+
241
+ It reads the run itself, and nobody states a count. The In-flight count —
242
+ every open PR that closes an issue off `gh`, plus every claimed ticket whose
243
+ newest implementer is live or owed a replacement and has no such PR yet, off
244
+ the ledger — sits beside the live review units (in-flight `review=` tokens
245
+ plus unsettled `fix-pr-` ones), the merge bot, merge holds, tier mismatches
246
+ and the drain marker, all off `.fleet/ledger.md`; the unclaimed heads and the
247
+ supply come off `.fleet/shortlist.json`, which it refreshes itself when the
248
+ unclaimed count is below the In-flight bound, when the file is missing or
249
+ empty, when an Exclusion's premise has lifted, or when a branch-named
250
+ `behind-pr` or a `behind-issue` Exclusion still not lifted names a ticket the
251
+ file carries — never while the bound holds; the open PRs come off `gh`. A
252
+ ledger token it
253
+ cannot read, it refuses rather than guessing — a member counted live or gone on
254
+ a guess is the over- or under-dispatch it exists to prevent — so correct that
255
+ row with `ledger.mjs row` and tick again. The In-flight bound defaults to 5
256
+ and is fixed for the run: pass `--in-flight` on every tick when `$ARGUMENTS`
257
+ set it, and never otherwise.
258
+
259
+ It prints `actual/target` and a named ACTION per role, with the whole **Queue
260
+ depth** guard table applied in code. Act on each line as it reads:
261
+
262
+ - `PULL #<N> …` — one Pull per named ticket, in the order printed: `pull.mjs next --head <N>`, or the `pull.mjs answer` the row names (phase 1), then phase 2's dispatch.
263
+ - `REFRESHED shortlist: <n> entries; <k> lifted` — the tick refreshed the shortlist itself, and its `PULL` row already reads the result; `REFRESH FAILED` is yours, since `shortlist.mjs` could not run.
264
+ - `SUGGEST /triage, hold idle` — nothing is admissible after the refresh: suggest `/triage` in the report, never run it.
265
+ - `specs-dropped=#<N> …` — never actionable: log those tickets as specs awaiting to-tickets, not as no work.
266
+ - `DISPATCH fix-pr PR#<M> …` — a fix-applier for that PR (review findings, a dispositions mismatch no retry has answered, or a conflict hold): render its brief with `dispatch-prompt.mjs render fix-applier --kind <kind>`, `ledger.mjs dispatch <M> fix-pr-<M>` (the next suffix when that name is already on record), then the `task` call.
267
+ - `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn: record `review=member:review-pr-<M>` with `ledger.mjs review <M> …`, then dispatch `review-pr-<M>`.
268
+ - `DISPATCH merge-bot` — the next `merge-bot-<n>`: render its brief with `dispatch-prompt.mjs render merge-bot --member merge-bot-<n> …`, `ledger.mjs dispatch merge-bot`, then the `task` call.
269
+ - `DISPATCH finisher PR#<M> …` — a finisher settled `labelled` with no label on the PR and no `label-off=` to account for it: apply the finisher gate, render the next-suffix finisher's brief with `dispatch-prompt.mjs render finisher --kind repair --member finisher-pr-<M>-<x> …`, `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`, and never add the label yourself.
270
+ - `ESCALATE unlabelled PR#<M> …` — a second finisher settled `labelled` and the label is still off: not actionable, the maintainer's.
271
+ - `CONFLICT PR#<M> …` — record the hold with `fleet-event.mjs conflict <M>`, never with the `ledger.mjs row` form; the tick then prints `DISPATCH fix-pr`.
272
+ - `ESCALATE conflict PR#<M> …` — PR M reads CONFLICTING again after two conflict fix-appliers: comment on the PR and flag it for a human, write no hold, dispatch no fix-applier.
273
+ - `HOLD (…)` — the row is held and its detail names the clearing step: dispatch nothing on that row until it clears; a tier mismatch is yours to clear by dispatching the replacement.
274
+ - `AT CAP`, `IDLE OK` — nothing to do on that row.
275
+ - `MAIN-CHECKOUT-DIRTY …` — dispatch nothing new and tell the maintainer; once they have resolved the paths, `main-checkout.mjs --record`; never revert the paths or re-baseline over them yourself.
276
+ - `MAIN-CHECKOUT-UNKNOWN …` — the tick could not look: fix what the line names and tick again, and never `--record` over it unless the line itself says re-record (an older-format baseline, or a baseline commit missing from this repository), and then only after resolving the stray paths.
277
+ - `MAIN-CHECKOUT-NO-BASELINE …` — yours: run `main-checkout.mjs --record`, after reporting a baseline that vanished mid-run.
278
+ - `PHASE0-INCOMPLETE <step>…` — every dispatching row is held: run the `phase0.mjs` command the line names; advice lines hold nothing.
279
+ - `CHECK-LIVENESS <member> (…)` — advice, never an action: take the census the **Member unaccounted** row of **Failure handling** gives before you touch the token.
280
+ - `UNRECORDED <stem> (…)` — record it with `ledger.mjs dispatch`, or confirm it is a stranger's member.
281
+ - `NO-TRANSCRIPT <member> (…)` — make the `task` call, or settle the token `killed`.
282
+ - `SETTLE <member> (report on disk …)` — a live token whose report is on disk: run that member's report wake from the wake table, which runs the `ledger.mjs settle <member> --from-report` the line prints plus the follow-on work its report calls for; `REPORT-MISMATCH`, `REPORT-UNREADABLE` and `REPORT-INVALID` name a report file that cannot be settled from, and the tick settles nothing itself.
283
+
303
284
  ## Phase 1 — Pull: judge, then claim or relabel
304
285
 
286
+ A Pull is done when `pull.mjs next` exits 0 with its `DISPATCH` line, which phase 2 acts on, or exits 1 with the ticket gone from the Pull: answer each question it stops at, and take the next entry after an exit 1.
287
+
305
288
  Serial, main checkout, one Pull at a time. Never parallel, never inside a member —
306
289
  concurrent `worktree add` and label writes race.
307
290
 
@@ -319,6 +302,8 @@ usage mistake, or an answer the question does not take, and records nothing.
319
302
  The record is `<scratch>/impl-<N>/pull.json`. See references/pull.md for what
320
303
  each step does, and why.
321
304
 
305
+ ### The tick's PULL rows
306
+
322
307
  **The tick's `PULL` rows name the command.** One free implementer slot is one
323
308
  Pull, and each head a free slot Pulls gets its own row, read off that head's
324
309
  `pull.json` and never folded:
@@ -330,10 +315,7 @@ Pull, and each head a free slot Pulls gets its own row, read off that head's
330
315
  | `… (stale)` appended | that question has stood longer than `--pull-stale-minutes` (120 by default) |
331
316
  | `PULL #N (dispatched, row missing — ledger.mjs row N "…")` | dispatched, yet the head holds no `impl-` row: write the row it names |
332
317
 
333
- A head whose Pull already ended in this run — the ticket left, or the router
334
- refused it and its claim was released — gets no row: `next` without `--head`
335
- skips it, `next --head <N>` would start the ticket over, and the next head
336
- fills the slot.
318
+ ### The questions
337
319
 
338
320
  **The questions**, each answered with `pull.mjs answer <N> <qid> <token> …`:
339
321
 
@@ -391,9 +373,19 @@ fills the slot.
391
373
  branch with no PR yet by its name; `behind-issue:#M`, an open issue that
392
374
  section sequences this one after; or `paths <p>…`, which scans again.
393
375
 
376
+ ### How a Pull ends
377
+
378
+ A head whose Pull already ended in this run — the ticket left, or the router
379
+ refused it and its claim was released — gets no row: `next` without `--head`
380
+ skips it, `next --head <N>` would start the ticket over, and the next head
381
+ fills the slot.
382
+
394
383
  **A Pull never re-admits a ticket already relabelled**: the issue step reads the
395
384
  labels fresh and exits 1 `relabelled elsewhere` once `ready-for-agent` is gone.
396
385
 
386
+ Relabelling by cause, exclusion rows and claiming are in references/pull.md; a
387
+ worktree re-created for an already-open PR is in references/isolation.md.
388
+
397
389
  **The exit table** — how a Pull ends, and what follows:
398
390
 
399
391
  | `pull.mjs` | At the Pull | Then |
@@ -409,10 +401,11 @@ labels fresh and exits 1 `relabelled elsewhere` once `ready-for-agent` is gone.
409
401
  | 3 | a usage mistake, or a token the question does not take | correct it; nothing was recorded |
410
402
  | 10 `QUESTION <qid>:` | a question pending | answer it |
411
403
 
412
- Relabelling by cause, exclusion rows and claiming are in references/pull.md; a
413
- worktree re-created for an already-open PR is in references/isolation.md.
404
+ ## Phase 2 — dispatch every member
414
405
 
415
- ## Phase 2 — dispatch the Pull's implementer
406
+ A dispatch is done when its `task` call is made, in the background, with the `agent` and the name `ledger.mjs dispatch` printed, and — for an implementer — the tier check has written its verdict: dispatch nothing on top of an unchecked one.
407
+
408
+ ### The implementer
416
409
 
417
410
  **A Pull is one claim followed by one dispatch of a new member under a name no
418
411
  member has held; nothing holds a queue.** The In-flight bound is the fleet's
@@ -484,31 +477,218 @@ that the tier it resolves to is now declared and pinned rather than inherited by
484
477
  accident. Keep `name: impl-<N>`: the name is what makes a member, and both the
485
478
  spend classifier and `member-outcomes.mjs` read it.
486
479
 
487
- **After every Pull's dispatch, the tier check runs — a scripted step, never a
488
- prose reminder.** `tick --apply` runs it itself, a batch of one apiece, on every
489
- implementer it would print `HOLD (tier unchecked impl-<N>)` for, `session` off
490
- the phase-0 receipt, and prints `APPLIED tier-check impl-<N>: <verdict>`. By
491
- hand it is `~/.fleet/bin/fleet-run tier-check.mjs --batch <path-to-batch.json>`,
492
- which judges the implementer just dispatched on the ledger's terms. The definition it
493
- should have run under comes off its ticket row's `tier=` token: none means the
494
- policy cell, `fleet-implementer-slow-high`; `tier=<cell>` means
495
- `fleet-implementer-<cell>` — the same mapping `ledger.mjs dispatch` prints its
496
- `agent` from, so a call that names the printed `agent` passes this half. It
497
- fails the member two ways, one line each —
498
- `member: dispatched <agent>, expected <definition>` when its transcript says
499
- it was dispatched as anything else (a generic `task` dispatch fails even when
500
- its model happens to match), and `member: declared <m>/<l> resolved <m>/<l>`
501
- when the harness resolved a different model or level than that definition
502
- declares. The verdict lands on the ledger either way, written by the check
503
- itself: exit 0 appends `tier-ok=impl-<N>:<definition>` to the row, once
504
- however often it runs; exit 1 runs `ledger.mjs settle impl-<N> tier-mismatch`
505
- — or, for a member already settled another way, which `settle` will not
506
- re-settle, appends `tier-mismatch=impl-<N>:<definition>` instead. Exit 3 is
507
- the third verdict, `tier-unverifiable=impl-<N>:no-transcript`, appended once
508
- for a member settled `killed` or `released` anywhere on the ledger — a row
509
- or `## Dispatched` — whose `session` names an existing directory holding no
510
- `<member>.jsonl`: a dispatch that failed before a transcript was written. It
511
- says nothing about the tier and only clears the unchecked hold. Exit 2
480
+ ### The reviewer
481
+
482
+ **Dispatch the review, never wait on it, and act when its result lands. That is the default path.**
483
+ The tick names every PR owed one — `DISPATCH review PR#<M>`, oldest first —
484
+ and each gets one review, once per PR:
485
+
486
+ a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch` — it loads `review-eval.mjs` through the Resolver (`~/.fleet/bin/fleet-run --path review-eval.mjs`), awaits `runReviewOnOmp` in its own kernel, writes the result file into the review's own run root and reports its path and `reviewed=` token; record `review=member:review-pr-<pr#>` on the PR's row before the dispatch call. **`scratch` is the scratch root itself, the absolute path `scratch-root.mjs` prints, never the review side's `<scratch>/pr<N>` partition:** the review creates `pr<N>/` under it, so a `pr<N>` passed in nests every run root at `pr<N>/pr<N>/`, and the review refuses a `scratch` whose last component is `pr` plus digits before dispatching anything.
487
+
488
+ Write the `review=` token with `ledger.mjs review <pr> <token>`, which appends
489
+ it to the **PR's row** — the ticket row once `settle impl-<N>=PR#M` has run,
490
+ else `#M`, created when neither exists — and prints that row's key. `review`
491
+ is the only writer of `review=`/`reviewed=` tokens, so a PR's tokens sit on
492
+ one row in the order you wrote them. The tick counts in-flight reviews off the
493
+ ledger and nowhere else, so a review you launched and never recorded is one it
494
+ names again. `review` reads the PR's review record across every row that maps
495
+ to the PR, in ledger order, and refuses a write that adds a `reviewed=` with no
496
+ open launch before it, a launch identity the PR already used, a second launch
497
+ while one is open, or an unparseable `review=`/`reviewed=` (the ledger's token
498
+ grammar, below), or any token that is not a review token. `row` refuses a
499
+ write that adds a review token (one the row holds is carried), drops an open
500
+ launch, names a member twice on the line, or makes a PR map to a second row. A
501
+ bad token the ledger already holds is carried, never re-judged.
502
+
503
+ ### The fix-applier
504
+
505
+ **Then dispatch a fix-applier** — on `DISPATCH fix-pr PR#<M>`, which the tick
506
+ prints for a PR whose `reviewed=` counts survived or unverified findings that
507
+ no review fix-applier
508
+ has landed `applied:`/`no-op` on since, with no fix-applier live on it — one
509
+ named member per PR, `fix-pr-<pr#>` (the next suffix when that name is already
510
+ on record), never the PR's
511
+ implementer, its brief rendered with `dispatch-prompt.mjs render fix-applier
512
+ --kind review --member fix-pr-<pr#> …` and then recorded with `ledger.mjs
513
+ dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch,
514
+ the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`,
515
+ `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>`
516
+ in that brief is the absolute path `scratch-root.mjs` printed, the
517
+ `dispositions-<its name>.json` record's included. The fix-applier owns every per-PR ruling you once made
518
+ before dispatch: both mutual-exclusion scans, the suggested-fix re-derivation,
519
+ `refuted=false` ≠ apply, per-site measurement for a sibling-site extension, and
520
+ `testEnvironment`/`cwdAudit` before any result of the shared test run. It
521
+ holds every finding and you hold none, so there is nothing for you to rank,
522
+ relay or pre-rule — and a report from a refuter it spawns that surfaces to you
523
+ is its to retrieve, never yours to scan or pass on.
524
+
525
+ **A `DISPATCH fix-pr PR#<M>` on a conflict hold** — the row carries an
526
+ unresolved `conflict-hold:#<M>`, the merge bot's (`run-merge-bot.md` step 1's
527
+ fallback) or one you recorded off the tick's `CONFLICT` line —
528
+ is the same slot with a different job, and no review file to hand
529
+ over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
530
+ already on record — `dispatch` refuses a reused one — render its brief with
531
+ `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`,
532
+ and dispatch it with the
533
+ `agent` that `ledger.mjs dispatch` printed, in the PR's existing worktree.
534
+ `dispatch` prints this member's definition, `fleet-fix-applier` whatever the
535
+ row's `tier=` — read it off that output, never recall it. Its `conflict` brief carries the
536
+ same worktree and branch identity paragraph, but in place of the review paragraphs:
537
+ bring `<branch>` current with `origin/main`, resolving every conflict by
538
+ `run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
539
+ head. Settle it `applied:<head>` — `no-op` if no conflict was left — which is
540
+ what lifts the tick's merge hold; a dispatched-but-live one does not, and
541
+ `failed`/`killed` leave the PR fix-due for a replacement. It answers the
542
+ hold and nothing else: survived or unverified findings of a returned review the row also carries
543
+ stay unanswered through its settle, so the tick prints `DISPATCH fix-pr
544
+ PR#<M>` again once it lands, and that one is a review fix-applier, dispatched
545
+ as above. On a PR carrying
546
+ `ready-to-merge`, the push moves the head after the label, so the next merge
547
+ bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure
548
+ handling**.
549
+
550
+ **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the
551
+ PR's current head that is not **solely** staleness: a `rebase-check` red, or
552
+ heavy jobs `skipped`, that comes only off the behind-count gets no fixer (the
553
+ five-condition note in the fix-applier body states how to establish
554
+ that). The tick prints no `DISPATCH` for it, so you reconcile it yourself, and
555
+ it always goes after the review, never before. Take the common case, the
556
+ implementer's own first CI firing turning red before any review exists: the
557
+ review is still dispatched against that head as normal, because a red suite is
558
+ review evidence and not a blocker. While a review or a review fix-applier on
559
+ the PR is live or still owes its report — a dispositions mismatch awaiting its
560
+ retry and a conflict hold awaiting its fix-applier included — the red-check
561
+ fixer does not fire: their push starts a new run, and a fixer racing them
562
+ would work on a SHA that is still moving. These edges dispatch it, each the
563
+ finisher's own: **Monitor: CI run completes** binding a red on a head
564
+ whose review has returned and whose fix-applier, if any, has reported;
565
+ **A fix-applier reports `no-op`**, or a SHA you have already bound, when that
566
+ head's bound conclusion is red; and **A review result lands** with no finding
567
+ and nothing to file, when that head's bound conclusion is red. The Monitor is
568
+ edge-keyed on `<run-id>:<attempt>:<conclusion>`, so a red that fired before the
569
+ review never fires again, and with no push there is no new run — the other
570
+ edges are the only route there, so do not wait for an event. Edit one of these
571
+ bullets without the others and what strands is exactly the red-only PR.
572
+
573
+ Name it `fix-pr-<M>`, or the next free suffix (`-b`, `-c` …) — `dispatch`
574
+ refuses a reused name — render its brief with `dispatch-prompt.mjs render
575
+ fix-applier --kind red-check --member <name> …`, record it with `ledger.mjs dispatch <pr#> <name>`
576
+ before the call, and dispatch it with the `agent` that command printed
577
+ (`fleet-fix-applier`, as for a review fix-applier), in the PR's
578
+ existing worktree. Its `red-check` brief carries the same worktree and branch
579
+ identity paragraph, but in place of the review paragraphs: read the failing job's
580
+ log, fix the cause, run `<testCmd>`, push, report the new head, and **stop**.
581
+ It is told outright not to watch, poll or wait for CI: your persistent Monitor
582
+ owns the next run on the pushed head, and the finisher gate — review returned
583
+ AND fix-applier report sent — applies to this member the same way. Settle it
584
+ `applied:<head>` once a fix is pushed. Settle it `no-op` only when the red
585
+ turns out not to be this member's to fix — a flake that passes on rerun, or
586
+ staleness — with nothing pushed; `no-op` counts as landed, so it never stands
587
+ for "could not fix". Settle it `failed` when it cannot reach green, which the
588
+ **Failure handling** row "Reviewer, fix-applier or red-check fixer cannot
589
+ reach green" covers.
590
+
591
+ **What a fix-applier receives.** Its standing text — the worktree and
592
+ session-root discipline, the review result file and every ruling on it, the
593
+ claim discipline, the refuter prompt, the kill rule, the stash prohibition, the
594
+ dispositions record and the report rules — is the body of
595
+ `agents/fleet-fix-applier.agent.md`, which the harness injects as its system
596
+ prompt, so none of it is pasted. The brief carries what varies, and the
597
+ renderer prints it: `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
598
+ fix-applier --kind <review|conflict|dispositions-retry|red-check> --member <name>
599
+ --worktree <abs-path> --branch <branch> --testCmd <testCmd> --scratch <scratch>`,
600
+ plus `--pr <pr#> --run <run>` for a review or a dispositions retry and
601
+ `--mismatched-record <path> --violations <list>` for a retry. Then
602
+ `ledger.mjs dispatch <pr#> <name>` records it before the call.
603
+
604
+ ### The finisher
605
+
606
+ **What a finisher receives.** The instrument re-check, the test-run verdict
607
+ rule, duty 1's audit script and what each of its exits means, duty 3's script
608
+ and the halt-cause rule are the body of `agents/fleet-finisher.agent.md`, which
609
+ the harness injects as its system prompt; none of them is pasted. The
610
+ instrument-set rule is stated once, in **Rules that fail silently**, which no finisher
611
+ is dispatched to read, so it reaches one through that body. The brief carries
612
+ the PR, the worktree, the dispatch pin, `<testCmd>` and the scratch root:
613
+ `~/.fleet/bin/fleet-run dispatch-prompt.mjs render finisher --kind <fresh|repair>
614
+ --member finisher-pr-<pr#> --pr <pr#> --pin <sha> --worktree <abs-path>
615
+ --testCmd <testCmd> --scratch <scratch>`, which `ledger.mjs dispatch <pr#>
616
+ finisher-pr-<pr#>` records.
617
+
618
+ ### The merge bot
619
+
620
+ Per pass, named `merge-bot-<n>`, never two at once. `ledger.mjs dispatch
621
+ merge-bot` names it before the dispatch call — `n` is 1 + the highest
622
+ `merge-bot-<n>` the session holds, in the ledger's `## Dispatched` list, on a
623
+ row or in `## Retired`, so it restarts at 1 only when none was carried or
624
+ retired (a `dead` or `none` rotate, or a fresh start), a replacement for a
625
+ dead bot takes the next `n`, and nobody counts. With no brief rendered for
626
+ that name it refuses, naming the bot and the `dispatch-prompt.mjs render
627
+ merge-bot --member merge-bot-<n> …` to run — render it, then run `ledger.mjs
628
+ dispatch merge-bot` again. Dispatch
629
+ it on the tick's `DISPATCH merge-bot`: the first `ready-to-merge` label is
630
+ enough, and it never waits for the finisher's report. Its body
631
+ (`agents/fleet-merge-bot.agent.md`) tells it to read
632
+ `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
633
+ pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
634
+ for late labels, then report once and exit — and that you dispatched it,
635
+ which is what makes it hold that grace instead of arming its own watcher. Its
636
+ brief is `~/.fleet/bin/fleet-run dispatch-prompt.mjs render merge-bot --member
637
+ merge-bot-<n> --n <n> --scratch <scratch>`, `<scratch>` the absolute
638
+ `scratch-root.mjs` output: the bot writes only under `<scratch>/pr<N>/merge-bot-<n>/`. **Dispatch
639
+ it with the `agent` that `ledger.mjs dispatch merge-bot` printed and omit
640
+ `model` on the call** — the tier lives in that definition's frontmatter,
641
+ `agents/fleet-merge-bot.agent.md`, as the `@smol:low` route, which resolves
642
+ through the operator's `modelRoles`.
643
+
644
+ Rebase, wait for green, check the
645
+ label, merge is checklist work, and a bad merge still needs the label and the
646
+ per-job CI state to have been read correctly, which is exactly what a wrong
647
+ merge later surfaces and a human resolves; `no-undo-audit.sh` is the
648
+ deterministic, script-driven backstop run before every push specifically to
649
+ catch a wrongly-resolved conflict, so the tier buys nothing that backstop
650
+ doesn't already cover.
651
+
652
+ **The shell traps live in the merge bot's agent body, not in its brief and not
653
+ in a follow-up message.** A bot already looping cannot be corrected — the loop
654
+ consumes the turns a correction would land in — so
655
+ `agents/fleet-merge-bot.agent.md` carries **every entry in
656
+ `references/shell-traps.md`'s Shell traps**, each written out in full: the rules
657
+ with the measurements from that file beside them, and the bot has them before its first
658
+ turn. The bot reads an exit code off `gh pr update-branch`, `merge-gate.mjs` and
659
+ `prove-merge.sh`, which is the `PIPESTATUS` and read-only-`status` pair, and its
660
+ grace poll captures `gh pr list` output and loops over it, which is the
661
+ assigned-variable trap. Its brief names the bot and `<scratch>`, plus the
662
+ one-line no-acknowledgement notice; do not paste the traps there. An edit to
663
+ `references/shell-traps.md` lands in that body in the same change.
664
+
665
+ ### The tier check
666
+
667
+ **After every Pull's dispatch, the tier check runs — a scripted step, never a
668
+ prose reminder.** `tick --apply` runs it itself, a batch of one apiece, on every
669
+ implementer it would print `HOLD (tier unchecked impl-<N>)` for, `session` off
670
+ the phase-0 receipt, and prints `APPLIED tier-check impl-<N>: <verdict>`. By
671
+ hand it is `~/.fleet/bin/fleet-run tier-check.mjs --batch <path-to-batch.json>`,
672
+ which judges the implementer just dispatched on the ledger's terms. The definition it
673
+ should have run under comes off its ticket row's `tier=` token: none means the
674
+ policy cell, `fleet-implementer-slow-high`; `tier=<cell>` means
675
+ `fleet-implementer-<cell>` — the same mapping `ledger.mjs dispatch` prints its
676
+ `agent` from, so a call that names the printed `agent` passes this half. It
677
+ fails the member two ways, one line each —
678
+ `member: dispatched <agent>, expected <definition>` when its transcript says
679
+ it was dispatched as anything else (a generic `task` dispatch fails even when
680
+ its model happens to match), and `member: declared <m>/<l> resolved <m>/<l>`
681
+ when the harness resolved a different model or level than that definition
682
+ declares. The verdict lands on the ledger either way, written by the check
683
+ itself: exit 0 appends `tier-ok=impl-<N>:<definition>` to the row, once
684
+ however often it runs; exit 1 runs `ledger.mjs settle impl-<N> tier-mismatch`
685
+ — or, for a member already settled another way, which `settle` will not
686
+ re-settle, appends `tier-mismatch=impl-<N>:<definition>` instead. Exit 3 is
687
+ the third verdict, `tier-unverifiable=impl-<N>:no-transcript`, appended once
688
+ for a member settled `killed` or `released` anywhere on the ledger — a row
689
+ or `## Dispatched` — whose `session` names an existing directory holding no
690
+ `<member>.jsonl`: a dispatch that failed before a transcript was written. It
691
+ says nothing about the tier and only clears the unchecked hold. Exit 2
512
692
  writes nothing — a usage error, which includes a LIVE member with no
513
693
  transcript; a member settled `PR#M`, `bailed` or `tier-mismatch` with none,
514
694
  which ran, so the `session` is the wrong directory — pass the one that
@@ -597,6 +777,8 @@ queues at its ceiling rather than refusing, and is session-wide): below
597
777
  exits 0, so the notice is the operator's to read and report, never a reason to
598
778
  stop the run.
599
779
 
780
+ ### The exploration rule
781
+
600
782
  **Every 5th Pull by ledger count goes at an exploration cell.** See references/pull.md.
601
783
 
602
784
  **The router's arguments, and nothing past its line.** `--impl-row` is the
@@ -701,219 +883,434 @@ didn't parse from one that succeeded (`unread`/`unparsed`/`read`) —
701
883
  `spend` in the same payload carries its own error the same way. Zeroes
702
884
  on the cockpit are not yet proof the pipeline is idle.
703
885
 
704
- **Guard: accumulate per PR, never conclude inside one run.** The unit is the PR —
705
- supply is one Pull per free slot, so there are no implementer batches. **Append one row to
706
- `docs/metrics/tier-outcomes.tsv` when you rule each PR's review, with
707
- `~/.fleet/bin/fleet-run tier-outcomes.mjs append <pr> --closed-own-ticket yes|no --minted-false-claim yes|no --note "<text>"`,
708
- never by hand** (that file's header carries the column meanings). The script
709
- fills `run_date`, `pr`, `ticket` and `tier` itself — `tier` from what actually
710
- ran, off the implementer's `tier-ok=` ledger verdict or else its one
711
- member-outcomes row (a `tier-unverifiable=` member has no ledger verdict, so
712
- its one member-outcomes row decides), and BLANK with a WARNING naming why
713
- when neither settles
714
- it; never type a tier in over that. A PR that already has a row is left
715
- untouched, so re-running it is safe. That append is the whole duty.
716
-
717
- The row's last four fields are the ticket's difficulty, and they are what lets a
718
- tier comparison condition on the thing that swamps it. `sizing` is the
719
- **member's** own `light`/`heavy` verdict from its phase-2 `sizing-a-ticket`
720
- run, which `append` reads itself off the member's report file
721
- (`<scratch>/reports/impl-<ticket>[-x].json`, its `sizing.verdict`, the highest
722
- retry letter's when there are several), so you pass no `--sizing`; the member
723
- also puts it in the PR body's `Sizing:` line, with the signal it turned on;
724
- `profile`, `loc` and `files` all come from `diff-stats.mjs` over the merged
725
- diff. **Phase 0 does not size anything** — it shortlists, a Pull claims, and
726
- the sizing run happens inside the member after both, which is why the verdict
727
- has to travel in the member's report rather than being something you already hold.
728
-
729
- **A verdict is a measurement only if it post-dates the run that produced it.** See references/reviewers.md.
730
-
731
- The member-facts scrape, the drain of the pending ticket-features rows and the
732
- commit of the metrics files are steps of `closeout.mjs finish`, which **End of
733
- run** (Phase 3) drives. See references/close-out.md.
886
+ ## The finisher gate
734
887
 
735
- **Why not decide inside one run.** A run holds 2-3 implementer PRs, and ticket
736
- difficulty swamps the tier effect — a gojq parity harness and a two-statement
737
- shell reorder are not comparable units. Finding-counts are not comparable either:
738
- `selectDimensions` trims the fan-out by diff profile, so one PR fields 29 agents
739
- over six dimensions and its sibling fields 8 over three. And the fleet is not
740
- stationary — this prompt gets edited mid-run when a defect earns it. Hence a
741
- binary outcome per PR, accumulating, rather than a per-run verdict.
888
+ Dispatch a finisher only when every test here passes at once — the review returned, the fix-applier's report arrived, your outbox to it is empty and no ruling is owed; hold otherwise, and on a repo with no CI and no declaration report it and add no label.
742
889
 
743
- **Why the rows this guard fired on could not answer the tier question, and this
744
- is the load-bearing part.** Until the 2026-08-16 revert, `class` and `tier` were
745
- perfectly confounded: routine always ran `sonnet`, correction always ran top
746
- tier. So the comparison the file invites — routine-at-sonnet against
747
- correction-at-top-tier — measures **class, not tier**, because those classes fail
748
- in different ways by construction: corrections ship false claims in prose,
749
- routines ship incomplete or regressing code. A run that "mixes both" does not fix
750
- it. **Only a same-class comparison across tiers is informative**, and the old
751
- rule could not produce one, since no routine ticket ever ran at top tier.
890
+ ### The tests
752
891
 
753
- **That last sentence is no longer true, and this is the part to re-read.** Since
754
- the revert every routine ticket runs at top tier, so the file now holds 55
755
- `routine`/`opus` rows against 11 `routine`/`sonnet` (as of 2026-08-28, 103 rows
756
- — recount before citing). The same-class comparison the paragraph above calls
757
- the only informative one therefore EXISTS now. It is still not clean: the two
758
- groups are split almost entirely by calendar date, so it measures prompt
759
- evolution at least as much as tier. The counter-evidence paragraph earlier in
760
- this section carries the split and the three rows that cut against it. Recount
761
- both, and every other figure in this section, with:
892
+ - **Monitor: CI run completes** → `fleet-event.mjs ci <pr>`, which binds the run
893
+ (`ci-state.mjs --pr <N>`) and **records it as
894
+ `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
895
+ ticket's ledger row, which outlives your context. The key is what the sibling
896
+ bullet below turns on: it tells an edge already spent from one that never
897
+ fired. The whole key, never the conclusion alone: **a
898
+ conclusion is not stable** (below), because a rerun rewrites the run in
899
+ place. The diff-validating `check` job green with no heavy job (the
900
+ diff-validating suites, not the `rebase-check` currency gate) in `failure`
901
+ → a finisher CANDIDATE (gated below), a `check`
902
+ **failure** that is not solely staleness → the **red-check fixer** (**Then
903
+ dispatch a red-check fixer**, above), behind the same review-returned and
904
+ fix-applier-reported gate as a finisher. A `check`-green board whose heavy jobs are merely
905
+ `skipped` (behind-count staleness, the normal case after a merge) still labels — do NOT
906
+ gate on `ci-state --quiet` exit 0, which a behind PR never reaches. **This
907
+ edge fires for every CI run the PR produces, and the implementer's own
908
+ firing comes first for every PR** — `ci.yml` triggers on `pull_request`, so
909
+ opening the PR at the end of `next-ticket` step 7 starts a run within seconds,
910
+ while the review returns 20-40 minutes later. That first firing is
911
+ the ordinary case for every PR, not a rarity, and no review has run at all
912
+ when it arrives. **Green is therefore not the gate: dispatch a finisher only
913
+ once the PR's review has returned AND its fix-applier, if one was dispatched,
914
+ has sent its report — pushed is not reported**, and a push before that report
915
+ is mid-work on a SHA the member may still move, which its own prompt tells it
916
+ not to hand over. A push is therefore not an exit, and a report that has not
917
+ arrived is asked for by name rather than read as one. Neither shape is caught
918
+ by an empty outbox: on the implementer's firing there is no fix-applier to owe
919
+ anything to, so the outbox is *vacuously* empty, and on a fix-applier's
920
+ mid-work push nothing has been sent since the dispatch, so it is *genuinely*
921
+ empty. **The outbox is the last test, not the only one, and it stands wherever
922
+ a fix-applier exists** — that is exactly where a ruling you still owe it is
923
+ outstanding, so never dispatch off it while you do. Empty your outbox to it
924
+ first — including any ruling you have withdrawn or reversed — then dispatch
925
+ (below); a final report is not proof it stopped. A PR that needs nothing fixed
926
+ reaches a finisher through the **fix-applier reports `no-op`** bullet below,
927
+ never by waiting for a second CI event this head will never produce. The
928
+ same goes for a red one: a red that fired before the review never fires
929
+ again, so the **fix-applier reports `no-op`** and **review result lands**
930
+ bullets are also the only routes to the red-check fixer there.
931
+ Then run the tick.
932
+ - **A fix-applier reports `no-op`, or a SHA you have already bound** → dispatch
933
+ the finisher **now**, against the existing head — when that head's bound
934
+ conclusion is red, the red-check fixer instead (**Then dispatch a red-check
935
+ fixer**, above), never a finisher and never a wait. No push means no new run, and
936
+ the Monitor above is edge-keyed on `<run-id>:<attempt>:<conclusion>` — that
937
+ head's terminal state already fired once and will never fire again, so waiting
938
+ for the CI event waits forever. This stays a common outcome on a clean PR:
939
+ `suggestion` is the band a clean diff produces, and every out-of-scope or
940
+ refuted one is filed as an issue rather than committed. An edge-only label path
941
+ therefore strands exactly the PRs with nothing wrong with them. **Reconcile, do
942
+ not wait for an event** governs here too, not only the implementer row. **This
943
+ bullet and the one above are a pair, and on a clean PR this one carries the
944
+ whole route to a finisher**: a `no-op` report satisfies the gate above by
945
+ itself — the review has returned, because a fix-applier exists only after it
946
+ did, and the member has reported — so nothing further is owed and no further
947
+ event is coming. Edit either bullet without the other and what strands is
948
+ exactly the PR that needed no fixes.
949
+ - **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → no workflow run will ever
950
+ complete for this repo, so the CI-run-completion edge above never fires and
951
+ waiting for it stalls the whole PR — the same silent-stall shape reported
952
+ before this verdict existed. Dispatch the finisher off the reviewer's final
953
+ verdict instead, the moment it lands — and, same as above, never while you still
954
+ owe it a ruling — or hold anything else it has not received, a ruling you have
955
+ withdrawn or reversed included. The finisher's gate is then the
956
+ `--declare-no-ci` declaration, not a `check` job: with it, label off the
957
+ reviewer's verified suite run; **without it, do not label** — report that this
958
+ repo has no CI configured and no declaration, and stop. Absence never reads as
959
+ pass. See `review-and-fix.md` step 6.
762
960
 
763
- ```bash
764
- grep -vc '^#' docs/metrics/tier-outcomes.tsv
765
- awk -F'\t' '!/^#/ && $4=="routine" {n++; d[$1]=1; if($6=="no") no++} \
766
- END{print n, length(d), no+0}' docs/metrics/tier-outcomes.tsv
767
- awk -F'\t' '!/^#/ && $4=="routine" {t[$5]++; if($6=="no") f[$5]++} \
768
- END{for(k in t) print k, t[k], f[k]+0}' docs/metrics/tier-outcomes.tsv
769
- ```
961
+ Gate on the `check` job, **not** on `ci-state --quiet` exit 0: a behind PR never
962
+ reaches full green, so an exit-0 gate strands it unlabelled. The finisher reads
963
+ per-job state (`ci-state.mjs` without `--quiet`, or its `jobs`), since `--quiet`
964
+ drops `jobs`, `missing` and `dropped`. Normal path, not only kill-recovery.
770
965
 
771
- **These rows are the historical corpus, and nothing appended to them fixes the
772
- confound.** What fixes it is the exploration draw in the dispatch rule above:
773
- one implementer in every five — every one, during burn-in — runs at a drawn
774
- cell beside the policy cell's, against the same prompts on the same day, so
775
- the comparison stops depending on which tier history happened to leave in
776
- which week. Read each cell's comparisons, not the whole-file split, once there
777
- are enough of them.
966
+ **`ci-state.mjs` reads `verdict: "no-ci"`** — no `check` job exists in this repo
967
+ to gate on, and that is not a third way to skip the wait. **The
968
+ `--declare-no-ci` declaration is caller-side, and reading it back out of the
969
+ payload verifies nothing**: the flag is echoed into `reasons` and flips the exit
970
+ code, so re-running with it and finding it there confirms only that you passed
971
+ it. Passing it yourself is not a second opinion. Check the two facts it stands
972
+ for instead:
778
973
 
779
- **So read what the guard actually established: routine tickets sometimes fail to
780
- close their own ticket. Not that `sonnet` caused it.** The revert is the
781
- pre-committed rule being honoured, not a measurement. Restoring a cheap tier is
782
- still the maintainer's call and still a change to the dispatch rule — but the
783
- deliberate control it used to require is no longer something anyone has to
784
- authorize one ticket at a time: the exploration draw above produces one in
785
- every five Pulls by construction. **Do not read a cell early.** A cell's
786
- comparison is one session holding an admissible row at that cell — its tier
787
- check passed and its resolved effort is the cell's level — and one at
788
- `slow-high` whose resolved model and effort differ. Count them per cell, never
789
- pooled across cells, and stop until
790
- there are at least ten of them across five or more distinct `run_date`s; below
791
- that, a comparison count is a number, not evidence, and the last guard fired
792
- with n=1 on the control side. **Report the count the per-cell readout prints,
793
- never one from any other query:** `~/.fleet/bin/fleet-run cell-readout.mjs`
794
- prints `<cell> <comparisons> <run_dates> <resolved models>` for each cell past
795
- that floor and a cell below it only as a count on stderr; a `mixed (…)` models
796
- column means the cell's history spans more than one model behind its role.
797
- The pre-cell pair query counted pairs that are no cell's comparisons, and the
798
- query before that one counted every session whose implementers merely
799
- differed, so it cleared this floor by an order of magnitude while the
800
- controlled comparison did not exist yet.
974
+ 1. `ci-state.mjs` **without** the flag still reads `verdict: "no-ci"`. A repo
975
+ whose CI is merely misconfigured — workflow files present under other names,
976
+ or `.github/workflows/` not a directory — exits 2 there rather than reading no-ci,
977
+ so this is the check that separates real absence from misconfiguration, the
978
+ case that must never ship silently.
979
+ 2. The reviewer's own final verdict reports a green `testCmd` run on the SHA it
980
+ pushed. `review-and-fix.md` step 3 requires it to, and that run is the only
981
+ gate this repo actually has.
801
982
 
802
- Why the agent body carries what it does — read this before editing any `fleet-implementer-<cell>` file, and keep every cell's body byte-identical. See references/pull.md.
983
+ Both → add the label, and say it rests on the reviewer's suite run, not on CI.
984
+ Either missing → halt here, same as a dirty worktree: report `no CI configured,
985
+ no verified suite run on record` and add no label.
803
986
 
804
- **Prose-first** and **wrongly-REFUSE** are not padding — they are the case
805
- which shipped with **enumerate-and-declare** already in its prompt. It missed a
806
- shape its own ticket named in passing, because it enumerated from the mechanism
807
- instead of the text; and it introduced a regression refusing every `node --test`
808
- flag, because it enumerated what the guard should catch and never what it could
809
- wrongly refuse.
987
+ ### The dispatch and its refusals
810
988
 
811
- The commit-incrementally block is not optional. A member that goes idle mid-task
812
- leaves its diff only in the worktree, and the controller cannot reap, replace,
813
- or even see it — `worktree-audit.sh`'s committed-vs-uncommitted split is exactly
814
- what decides whether a replacement redoes or destroys work. Observed twice in
815
- one run.
989
+ **The fix-applier pushes and exits — it does not hold the CI wait.** You own the
990
+ persistent Monitor; a turn-based member re-reading `gh pr checks` each idle cycle
991
+ rebuilds a 100k-token context for nothing the Monitor lacks. The body
992
+ carries the report-last rule and the brief says to push, write the report and exit; you do not have to restate either. When the
993
+ diff-validating `check` job is green **and no
994
+ heavy job is in `failure`** (the heavy diff-validating suites — not the
995
+ `rebase-check` currency gate; a `skipped` heavy job is behind-count staleness and
996
+ fine — **solely** off that count, which is a condition to establish rather than
997
+ infer, see the five-condition note in the fix-applier body) — or
998
+ `ci-state.mjs` reads `verdict: "no-ci"`, see above — **and once the PR's review
999
+ has returned and its fix-applier, if one was dispatched, has sent its report,
1000
+ which the CI-completes edge above states in full** — dispatch a
1001
+ **finisher** — a fresh small agent, not the fix-applier resumed. Render its brief
1002
+ with `dispatch-prompt.mjs render finisher --kind fresh --member finisher-pr-<pr#> …`
1003
+ (`--kind repair` once an earlier finisher reported `labelled` without the label landing), record it with
1004
+ `ledger.mjs dispatch <pr#> finisher-pr-<pr#>` before the call, then **dispatch
1005
+ it with the `agent` that command printed and omit `model` on the call** — the
1006
+ tier lives in that definition's frontmatter, `agents/fleet-finisher.agent.md`,
1007
+ as the `@smol:low` route, which resolves through the operator's `modelRoles`.
1008
+ Its four duties are a checklist — audit the
1009
+ worktree, confirm every deferral has a tracker home and re-run the acceptance
1010
+ mutation, apply one release label, report — and the
1011
+ merge gate downstream still catches whatever it gets wrong, the same argument
1012
+ that puts the merge bot on the same tier above. **Never dispatch
1013
+ one while you still owe the fix-applier a ruling**: the pinned SHA is only as good
1014
+ as the guarantee nothing else is inbound. **The test is your OUTBOX, not the
1015
+ member's last message** — anything you have decided that it has not received,
1016
+ including a ruling you have since **withdrawn or reversed**. **That is the test
1017
+ of THIS condition only**: an empty outbox says nothing is inbound from you, and
1018
+ nothing about whether the member considers itself finished, which is what the
1019
+ report condition above is for. A withdrawal you
1020
+ recorded only in the ledger is undelivered: the member still holds the original
1021
+ and will act on it. Relay everything — reversals too — then dispatch.
816
1022
 
817
- **The identity block is what makes `sizing-a-ticket`'s fleet entry reachable.**
818
- That skill conditions its heavy-row process on the reader being a fleet member;
819
- a solo reader settles the open design choices with its user before planning,
820
- while a fleet member's `## Agent Brief` already is that settlement. A member
821
- that takes itself for a solo session waits on a user to settle design — a user
822
- no unattended member has, so it parks rather
823
- than fails. Nothing else you carry says what the member is — an incidental
824
- mention of the controller is not a statement that the reader is one of its
825
- members. That skill keeps its condition, so a solo session still runs the
826
- interactive path; this block is what puts a member on the fleet side of it.
1023
+ **That `dispatch` refuses a finisher — exit 2, nothing written — on a PR whose
1024
+ latest `reviewed=` counts a survived or unverified finding, unless the
1025
+ dispositions verdict answering that review's run is `ok`**: among the
1026
+ `dispositions-*=fix-pr-<M>[-x]:<run>` tokens naming its run, the one
1027
+ from the highest-suffixed fix-applier — so a second review at the same head is
1028
+ answered by none of the first one's verdicts. A PR whose latest review counts
1029
+ `0/<n>/0` is not gated. One counting `0/<n>/<u>` with `<u>` above zero is
1030
+ gated like survivors, and the tick prints `DISPATCH fix-pr PR#<M>` for it: that
1031
+ fix-applier's `no-op` and its `ok` verdict are what open the finisher. The
1032
+ refusal names its cause. `dispositions
1033
+ unchecked` — no verdict answers that review: run `dispositions-check.mjs` for
1034
+ the fix-applier that answered the review, as `fleet-event.mjs`'s `fix-report`
1035
+ entry states, then dispatch again. It names a `dispositions-unchecked=` verdict too —
1036
+ no rule broke, but the check could not read where a deferral was filed, `gh`
1037
+ unreachable or an issue unreadable: run the check again for that fix-applier
1038
+ once `gh` answers (an issue that does not exist is unreadable too, and no re-run
1039
+ answers that one: the check's stderr names it, and the record's issue number
1040
+ needs correcting); the tick offers no fix-applier for it. `dispositions
1041
+ mismatch` — no finisher: the tick prints `DISPATCH fix-pr PR#<M>` for it, and
1042
+ the next-suffix fix-applier answers it (**Then dispatch a fix-applier**).
1043
+ `dispositions escalate` — no finisher, no
1044
+ retry and no further fix-applier: either a `critical` or `important` finding was
1045
+ deferred `remedy-outside-diff`, or a second mismatch was drawn on one review, and
1046
+ only a human can rule on either. Post the check's output, which names each
1047
+ escalated finding or violating entry, with `gh pr comment <M>`, and flag the PR
1048
+ for a human; re-running the check reprints it. Dispatch no fix-applier and no
1049
+ finisher for that review, and expect no `fix-due` row for it; a new
1050
+ review of the PR starts the check again. **On any PR with a
1051
+ returned review, `0/<n>/0` included, it refuses too while a fix-applier on the
1052
+ PR is still live, verdict or not** —
1053
+ `fix-pr-<M>[-x] still live`: settle it, run the check for it, then dispatch
1054
+ again. A re-review at the same head is a run of its own, so the earlier
1055
+ round's verdict never answers it; once the check has run for the fix-applier
1056
+ answering the new round, its verdict is the current one.
827
1057
 
828
- A member that bails demotes nothing itself; demotion by cause is yours
829
- (**Implementer bails before implementing**).
1058
+ **It refuses a finisher, too, while the PR sits on a conflict hold no
1059
+ fix-applier has cleared** — the same per-PR fold the tick prints `DISPATCH
1060
+ fix-pr` off, ahead of the dispositions verdict. A PR known to conflict cannot
1061
+ merge, and a finisher on it would race the conflict fix-applier rebasing it.
1062
+ Dispatch that fix-applier, let it settle `applied:`/`no-op`, then dispatch the
1063
+ finisher again.
830
1064
 
831
- ## Phase 3 — event loop
1065
+ **An unanswered question from the member is an outbox item, and it blocks dispatch with the same weight as a ruling you have already made.** See references/finisher.md.
832
1066
 
833
- React to events; never block on one.
1067
+ **A final report is not proof the member stopped.** Observed twice: a ruling
1068
+ relayed after dispatch produced a new commit mid-audit, and a fix-applier that
1069
+ reported "nothing outstanding" resumed on a ledger-only withdrawal and was
1070
+ cycling mutants through the worktree when the finisher audited it. Both finishers
1071
+ correctly halted. Note what that costs to detect: two reads of the same worktree
1072
+ a minute apart showed *different* mutants, so a member's report and any single
1073
+ `git status` are each valid only at their instant.
834
1074
 
835
- **React to artifacts, not agents.** `idle` means "not currently executing", not
836
- "done", and a finished member's finding may never arrive. Read `gh pr view`,
837
- `gh run view`, `git -C <worktree> status` **before** messaging; when you message,
838
- send the specific next action, never "what is your status".
839
- See references/member-lifecycle.md.
1075
+ ## Judgement rules the drivers stop for
840
1076
 
841
- **Do not ask permission to run the loop.** Dispatching a reviewer, spawning a
842
- merge bot, Pulling a ticket, re-verifying a SHA, filing a follow-up — all proceed
843
- unconfirmed. Invoking the command was the opt-in. One exception: **a judgement the
844
- evidence cannot settle**.
1077
+ Each rule here is a judgement a driver stops for: answer it by the cause it names, then run the tick, and report to the maintainer what the evidence cannot settle.
845
1078
 
846
- **Rule: record, tick, act, beat.** Every wake — a member report, a review
847
- notification, a label, a CI run reaching a terminal state, a `CONFLICT` line, a
848
- heartbeat, the maintainer's drain — is one `fleet-event.mjs` call, which makes
849
- the wake's writes and ends in one `fleet-tick.mjs` invocation, and you do what
850
- it prints. There are no hand-run
851
- refill or dispatch edges left. Record first, because the tick reads the run off
852
- `.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
853
- one it cannot see, and it names the same dispatch again. Every record goes
854
- through `ledger.mjs` (**Run ledger**), which `fleet-event.mjs` drives — never a
855
- hand edit. What each kind writes is in the header comment of `fleet-event.mjs`.
1079
+ ### Relabel causes
856
1080
 
857
- Run each as `~/.fleet/bin/fleet-run fleet-event.mjs <kind> <args>`, from the main checkout:
1081
+ - **Implementer bails before implementing** → `fleet-event.mjs impl-report impl-<N>`
1082
+ settles `impl-<N>=bailed` and demotes by cause:
858
1083
 
859
- | Wake | Command |
1084
+ | Cause | Label |
1085
+ |---|---|
1086
+ | brief does not decide *what* to build | `needs-triage` |
1087
+ | genuine fork — options named, none ruled | `ready-for-human` |
1088
+ | needs human hands — external access, manual testing, judgment during the work | `ready-for-human` |
1089
+
1090
+ The call relabels, comments the cause and releases the claim, then ticks:
1091
+ the head the tick names next is a *different* ticket.
1092
+ `needs-triage` routes back to `/triage`, which can return it as
1093
+ `ready-for-agent`; `ready-for-human` for hands or a fork; `needs-triage` for a
1094
+ brief that names no *what*.
1095
+
1096
+ The same causes relabel an unclaimed ticket at the Pull (phase 1), where there
1097
+ is no `in-progress` to drop — the causes and labels are one table, applied at
1098
+ whichever point the ticket fails them.
1099
+
1100
+ ### Resolving a finisher halt
1101
+
1102
+ A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
1103
+ and the causes `finisher-audit.mjs` names are the ones seen so far, not a
1104
+ closed list; the finisher's agent body gives it the cause from one script
1105
+ instead of asking anyone.
1106
+
1107
+ **Resolving a finisher halt.** A halt is the finisher working correctly — it
1108
+ refused to label — so it is never `failed`, which stays for a finisher that
1109
+ crashed or gave up. Record it `ledger.mjs settle finisher-pr-<M>=halted:<cause>`,
1110
+ `<cause>` the word the report names; the ledger refuses any other. Every halt
1111
+ escalates two ways: the cockpit flags the PR `halted:<cause>` at severity 4 off
1112
+ that token, and you post the finisher's halt report — cause and evidence — with
1113
+ `gh pr comment <M>`, so it outlives the run. **No label**: the missing
1114
+ `ready-to-merge` already keeps the PR out of the merge queue. Then the cause
1115
+ decides the rest — two resolve automatically, every other one escalates:
1116
+
1117
+ | Cause | Resolution |
860
1118
  |---|---|
861
- | Implementer report | `fleet-event.mjs impl-report impl-<N>` |
862
- | Review result file written (workflow notification / `review-pr-<n>` report) | `fleet-event.mjs review-result <pr> <path>` |
863
- | Review launch failed | `fleet-event.mjs review-failed <pr> <launch>` |
864
- | Fix-applier report | `fleet-event.mjs fix-report fix-pr-<M>` |
865
- | Finisher report | `fleet-event.mjs finisher-report finisher-pr-<M>` |
866
- | Merge-bot pass report | `fleet-event.mjs merge-bot-report merge-bot-<n>` |
867
- | CI run terminal | `fleet-event.mjs ci <pr>` |
868
- | Label seen (persistent Monitor) | `fleet-event.mjs label <pr>` |
869
- | `CONFLICT` line | `fleet-event.mjs conflict <pr>` |
870
- | Heartbeat | `fleet-event.mjs heartbeat` |
871
- | Drain | `fleet-event.mjs drain --reason "<reason>"` |
1119
+ | `live-editor` | **Automatic.** Ask the live member **by name** for its report, wait for it, then dispatch `finisher-pr-<M>-b` at the current head. If the head moved in the meantime, resolve it as `past-pin` instead. |
1120
+ | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate. |
1121
+ | `rebase` | **Escalate** — comment and flag, nothing more. Read the report's `git cherry <pin> HEAD origin/main`: only `-` lines is a clean rebase, and a `+` line is a conflict resolution that changed content or a commit past the pin. No automatic rule until a live halt shows the case recurring. |
1122
+ | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
1123
+
1124
+ ### Why a `past-pin` halt needs the tick
1125
+
1126
+ `past-pin` needs the tick because the dead-review path cannot reach it: once a
1127
+ review has **returned**, its `reviewed=` token holds the PR out of `review-due=`,
1128
+ and settling that review `=failed` re-queues nothing — that path covers only a
1129
+ review that died before returning. A head that moved past `reviewed=` with no
1130
+ such halt — a fix-applier's push — stays not due: duty 2 verifies what it
1131
+ applied. **A rebase never gets a `reviewed=`:** the earlier review still
1132
+ counts, because dispositions verdicts are tied to its head. Never write a
1133
+ `reviewed=` you did not read off a review result file.
1134
+
1135
+ ### Resolving a finisher that died
1136
+
1137
+ **Resolving a finisher that died.** A finisher settled `failed` or `killed` left
1138
+ its PR without `ready-to-merge`, and nothing else notices: the PR is out of the
1139
+ merge queue, and the tick dispatches no finisher for it. The cockpit flags a
1140
+ REVIEW-column open PR without the label, whose latest finisher attempt settled
1141
+ so, `finisher:failed` or `finisher:killed` at severity 4 — one token per
1142
+ outcome, neither the implementer's bare `killed` flag nor `unlabelled`. You
1143
+ resolve it by hand: investigate why the finisher died, or dispatch the
1144
+ next-suffix finisher after the finisher gate: render its brief with
1145
+ `dispatch-prompt.mjs render finisher --kind fresh --member finisher-pr-<M>-<x>
1146
+ …` (`--kind repair` once an earlier finisher reported `labelled` without the
1147
+ label landing), then `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`. The flag
1148
+ clears when a later attempt settles — `labelled`
1149
+ (then `unlabelled` takes over while the label is still off), `halted:<cause>`,
1150
+ or a live `-b` — or when the PR carries `ready-to-merge`, merges or closes.
1151
+ You never add the label yourself, and the tick does not retry.
1152
+
1153
+ ### Dispositions escalation
1154
+
1155
+ **A `DISPATCH fix-pr PR#<M>` on a dispositions mismatch** — the PR's row carries
1156
+ `dispositions-mismatch=<member>:<run>` for its latest review's run, and no later
1157
+ fix-applier has landed — is one automatic retry, a review fix-applier named the
1158
+ next suffix (`fix-pr-<M>-b`) and dispatched like the first, its brief rendered with `--kind dispositions-retry`. Its prompt is the
1159
+ first one's with the retry paragraph added: `--mismatched-record`, the mismatched member's record
1160
+ `<scratch>/dispositions-<member>.json` it starts from, and `--violations`, the check's
1161
+ violation list as printed — the lines
1162
+ `dispositions-check.mjs` printed, each naming a bucket, an index and a rule;
1163
+ re-run the check for the mismatched member to reprint them. It writes its own
1164
+ record, and when it reports you run the check for it exactly as for the first
1165
+ one. `ok` ends it. A second failure on the same review is written as
1166
+ `dispositions-escalate=fix-pr-<M>-b:<run>` in place of a mismatch: the tick
1167
+ prints no `DISPATCH fix-pr` for it, `dispatch` refuses the finisher naming
1168
+ `dispositions escalate`, and you post the check's output with `gh pr comment <M>`
1169
+ and flag the PR for a human. A new review of the PR counts again from none.
1170
+
1171
+ ### The main-gain hit
1172
+
1173
+ | Failure | Response |
1174
+ |---|---|
1175
+ | Merge bot's gate finds the merge would remove lines `main` gained after the PR's work began (`main-gain-removed:<path>`, exit 1) | Relay `main-gain-removed:<path>-#<pr>` to a human with the hit list and the acknowledgement keys the bot printed. PR stays queued, label untouched, nothing written to the ledger, and no member is dispatched to restore the lines — the removal may be deliberate. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for each hit |
1176
+ | Merge bot's gate cannot answer the main-gain check (`main-gain-unanswerable`, exit 2) | Report `main-gain-unanswerable-#<pr>` with what it printed, PR stays queued, label untouched |
1177
+
1178
+ ## Rules that fail silently
1179
+
1180
+ These rules fail silently when they are skipped: check each before you act on a member's silence, and stop reading silence as a report or as assent.
1181
+
1182
+ **A report is delivered, not implied by ending a turn.** Every member owes
1183
+ the controller one report naming its outcome before it exits — including a
1184
+ member whose prompt carries no explicit report line. The "report the SHA",
1185
+ "report PR number" and "stop and report" instructions below *are* that
1186
+ report, not a second obligation on top of it. A member that does the work
1187
+ correctly and ends its turn has reported nothing: the controller learns the
1188
+ outcome only by re-reading artifacts and pinging, and a finding held only in
1189
+ that member's context is lost. Members did exactly this in one run —
1190
+ finishers, a reviewer and merge bots alike, the work done and only the
1191
+ delivery missing. Every brief's report paragraph says it. See
1192
+ references/member-lifecycle.md.
1193
+
1194
+ **The implementer, fix-applier, finisher, merge-bot and review-runner briefs
1195
+ each tell the member you do not acknowledge reports; you never write that line
1196
+ yourself.** A member cannot see whether its report arrived, so silence
1197
+ from you is indistinguishable from loss and it re-sends — three members did in
1198
+ one run, each burning a turn, and in all three the original had in fact arrived.
1199
+ Each of those templates under `briefs/` carries the line: *"The controller does
1200
+ not acknowledge reports. Send once and exit; never re-send unless the controller
1201
+ asks by name."*
1202
+
1203
+ So when a report is missing, **ask by name — that is what the "unless the controller asks by name" clause is for — and do not attribute the gap to the member until it answers.** See references/member-lifecycle.md.
1204
+
1205
+ The ask is the controller's move, not the member's. See references/member-lifecycle.md.
1206
+
1207
+ **Your OWN messages can vanish the same way, and that half is not recoverable by
1208
+ a re-send.** Two controller rulings were lost in one run, both with a
1209
+ `success: true` receipt: a member proceeded on its stated default and filed a
1210
+ tracker issue the lost ruling had said not to file. So **never read a member's
1211
+ silence as assent**, and require members to report their *confirmation state*
1212
+ alongside results — "I escalated X, received no ruling, proceeded on default Y".
1213
+ That sentence is the only thing that made either loss visible. After any ruling
1214
+ you cannot confirm was received, re-check the artifacts it governed.
1215
+
1216
+ **Name every member.** The name is the ledger token and the hub address; omit
1217
+ it and the ledger cannot match the member.
1218
+ Names follow the unit of work: `impl-<issue#>`, `fix-pr-<pr#>`,
1219
+ `review-pr-<pr#>`, `finisher-pr-<pr#>`, `merge-bot-<n>`. See
1220
+ references/member-lifecycle.md.
1221
+
1222
+ **Fresh context per member.** One member, one unit of work, gone. Never
1223
+ re-task a finished member — waking it drags the old ticket back in. Refill =
1224
+ **new** member, **new** name. Sending is still right for pinging a live
1225
+ member for a report it owes, or resuming a truncated reply — never for
1226
+ handing a finished member the next ticket.
1227
+
1228
+ `hub send` to an idle peer wakes it into its old transcript the same way; re-dispatching under the same name does not reset it — omp auto-suffixes a fresh peer (`name-2`) instead.
1229
+
1230
+ See references/member-lifecycle.md.
1231
+
1232
+ **You read your instruments out of a tree every member can write to — re-check them before every gate decision.** See references/instruments.md.
1233
+
1234
+ - **Pin once**, at phase 0 step 0 above, from the main checkout you are
1235
+ running this from — never from a member's worktree, which is gitignored
1236
+ and carries no baseline:
1237
+ `~/.fleet/bin/fleet-run instruments.sh --pin`. On a workspace that does not
1238
+ track `plugin/…`, the pin names the plugin checkout once — `--pin --audit
1239
+ <plugin-checkout>` — and every check after it follows the recorded tree.
1240
+ - **Re-check before you act on any instrument reading** — a SHA acceptance, a CI
1241
+ verdict, the reconcile, a reap, a label gate — from that same main checkout:
1242
+ `~/.fleet/bin/fleet-run instruments.sh`. **Exit 0 is the only code that
1243
+ lets a gate proceed. Exit 1 (the set changed) and exit 2 (the check could not
1244
+ answer) both refuse: report what it printed and do NOT re-read the
1245
+ instrument** — a guard that fails open on "could not look" protects nothing.
1246
+ **A label gate and a CI verdict are also taken by dispatched members, not
1247
+ only by you** — the finisher labels, and the merge bot merges on its own
1248
+ reading — and neither is dispatched to read this file, so neither can be
1249
+ reached by stating the rule here. Each carries its own copy: the finisher's
1250
+ in the instrument re-check block of `agents/fleet-finisher.agent.md`, the merge bot's inside
1251
+ `merge-gate.mjs`, step 3 of `run-merge-bot.md`.
1252
+ - **Re-pin only after a change you made deliberately.** The mid-run tooling fix
1253
+ below is the one legitimate writer. Re-pinning to clear a refusal you cannot
1254
+ explain discards the check.
1255
+
1256
+ It covers every tracked file under this repo's own plugin component directories
1257
+ — `plugin/commands/`, `plugin/scripts/`, `plugin/skills/`, `plugin/agents/`,
1258
+ `plugin/workflows/` — the probes, the libraries they source, and these runbooks,
1259
+ which you also read from that tree. Not the whole repo: `docs/metrics/` is
1260
+ appended by THIS run, so covering it would refuse on the run's own bookkeeping
1261
+ every time. It does not cover refs, deliberately: `claim-ticket.sh` creates a
1262
+ branch per ticket and `reap.sh` deletes them in the ref store every worktree
1263
+ shares, so ordinary work moves refs several times a run and a per-gate
1264
+ refusal on that is noise.
1265
+
1266
+ **A member runs its test suite in the foreground and blocks on it.** See references/member-lifecycle.md.
1267
+
1268
+ **The scratch root is computed, never invented and never recorded.** No harness
1269
+ supplies a scratch directory to a member, so a member left to name its own
1270
+ invents one — and the liveness read in **The tick's rows**, which looks at the files under the
1271
+ directory a member's own prompt assigned it, then watches a directory nobody
1272
+ else can find. You run `~/.fleet/bin/fleet-run scratch-root.mjs`: it prints one
1273
+ absolute path, `~/.fleet/scratch/<repo-key>/`, the same from the main checkout
1274
+ and from every linked worktree, and the same again when a compacted or
1275
+ re-invoked controller runs it, so nothing writes it down. It exits non-zero,
1276
+ with its reason, when the root would sit inside a git work tree that does not
1277
+ ignore it; that is an environment to fix, not a cue to pick another root.
1278
+ `<scratch>` in this file is that path, resolved before you send anything: every
1279
+ brief that carries one carries the absolute path you passed it — an
1280
+ implementer's `<scratch>/impl-<N>/`, the recipe deriver's
1281
+ `<scratch>/derive-recipe/`, a fix-applier's, a finisher's and a merge bot's
1282
+ `<scratch>/pr<N>/…`, and a review runner's `scratch` argument, which is the
1283
+ root itself. A member whose prompt names no path asks you by name and never
1284
+ makes one up.
1285
+
1286
+ ## Phase 3 — event loop
1287
+
1288
+ The loop has no exit but the run's own end: act on each wake as the wake table gives it, keep the standing duties below between wakes, and drain the run when it ends (**End of run**).
1289
+
1290
+ ### What a wake owes beyond its call
872
1291
 
873
1292
  Act on every line the call prints, the tick's last, and arm the beat. What a wake
874
1293
  owes beyond its call:
875
1294
 
876
- - **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
877
- below. A turn that ends on a drained queue is #3's stall itself: nothing
878
- external will wake you, and the level-check you are one command away from
879
- never runs. Listed first because it is the only wake with no trigger —
880
- every other row above arrives; this one is the absence of one.
881
1295
  - **Implementer report** → the PR is owed a review from here on:
882
1296
  the tick names it as `DISPATCH review PR#<M>`, and it names the next
883
1297
  shortlist head whenever the In-flight count is below the bound. Pull
884
1298
  nothing the tick did not name.
885
1299
  - **Finisher reports halted** → the per-cause rule (**Resolving a finisher
886
- halt**, below).
1300
+ halt**, above).
887
1301
  - **A finisher failed or was killed** → `ledger.mjs settle finisher-pr-<M>=failed` for a
888
1302
  finisher that crashed or gave up, `=killed` for one that was killed; no label,
889
1303
  and the tick prints no dispatch for it. The cockpit flags the PR
890
1304
  `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand
891
- (**Resolving a finisher that died**, below), then run the tick.
892
- - **Implementer bails before implementing** → `fleet-event.mjs impl-report impl-<N>`
893
- settles `impl-<N>=bailed` and demotes by cause:
894
-
895
- | Cause | Label |
896
- |---|---|
897
- | brief does not decide *what* to build | `needs-triage` |
898
- | genuine fork — options named, none ruled | `ready-for-human` |
899
- | needs human hands — external access, manual testing, judgment during the work | `ready-for-human` |
900
-
901
- The call relabels, comments the cause and releases the claim, then ticks:
902
- the head the tick names next is a *different* ticket.
903
- `needs-triage` routes back to `/triage`, which can return it as
904
- `ready-for-agent`; `ready-for-human` for hands or a fork; `needs-triage` for a
905
- brief that names no *what*.
906
-
907
- The same causes relabel an unclaimed ticket at the Pull (phase 1), where there
908
- is no `in-progress` to drop — the causes and labels are one table, applied at
909
- whichever point the ticket fails them.
1305
+ (**Resolving a finisher that died**, above), then run the tick.
1306
+ - **Implementer bails before implementing** → `fleet-event.mjs impl-report impl-<N>`; the causes and the labels they take are under **Relabel causes**.
910
1307
  - **A review result lands** → see the result file written (by you or by the
911
1308
  runner — **Reviewers** says which, per harness), then
912
1309
  `fleet-event.mjs review-result <pr> <path>`: a PR with survived or unverified findings prints as
913
1310
  `DISPATCH fix-pr PR#<M>`. No survived or unverified finding and nothing to file → skip the
914
1311
  fix-applier and dispatch the **finisher** directly — or, when that head's
915
1312
  bound conclusion is red and not solely staleness, the red-check fixer
916
- instead (**Then dispatch a red-check fixer**, below): no member will touch that
1313
+ instead (**Then dispatch a red-check fixer**, above): no member will touch that
917
1314
  PR, so no push is coming and nothing will wake you. A review that failed is
918
1315
  not a result — **Reviewers** says who retries it and what takes over.
919
1316
  - **Monitor: `ready-to-merge` appears** → `fleet-event.mjs label <pr>`, and
@@ -952,257 +1349,9 @@ owes beyond its call:
952
1349
  the ledger marks reviewed with no verdict row: append it with the verdict
953
1350
  you rule (**Guard: accumulate per PR**) and run `finish` again. A step it
954
1351
  fails is explained in references/close-out.md. Exit 0 is the run closed.
955
- - **Monitor: CI run completes** → `fleet-event.mjs ci <pr>`, which binds the run
956
- (`ci-state.mjs --pr <N>`) and **records it as
957
- `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
958
- ticket's ledger row, which outlives your context. The key is what the sibling
959
- bullet below turns on: it tells an edge already spent from one that never
960
- fired. The whole key, never the conclusion alone: **a
961
- conclusion is not stable** (below), because a rerun rewrites the run in
962
- place. The diff-validating `check` job green with no heavy job (the
963
- diff-validating suites, not the `rebase-check` currency gate) in `failure`
964
- → a finisher CANDIDATE (gated below), a `check`
965
- **failure** that is not solely staleness → the **red-check fixer** (**Then
966
- dispatch a red-check fixer**, below), behind the same review-returned and
967
- fix-applier-reported gate as a finisher. A `check`-green board whose heavy jobs are merely
968
- `skipped` (behind-count staleness, the normal case after a merge) still labels — do NOT
969
- gate on `ci-state --quiet` exit 0, which a behind PR never reaches. **This
970
- edge fires for every CI run the PR produces, and the implementer's own
971
- firing comes first for every PR** — `ci.yml` triggers on `pull_request`, so
972
- opening the PR at the end of `next-ticket` step 7 starts a run within seconds,
973
- while the review returns 20-40 minutes later. That first firing is
974
- the ordinary case for every PR, not a rarity, and no review has run at all
975
- when it arrives. **Green is therefore not the gate: dispatch a finisher only
976
- once the PR's review has returned AND its fix-applier, if one was dispatched,
977
- has sent its report — pushed is not reported**, and a push before that report
978
- is mid-work on a SHA the member may still move, which its own prompt tells it
979
- not to hand over. A push is therefore not an exit, and a report that has not
980
- arrived is asked for by name rather than read as one. Neither shape is caught
981
- by an empty outbox: on the implementer's firing there is no fix-applier to owe
982
- anything to, so the outbox is *vacuously* empty, and on a fix-applier's
983
- mid-work push nothing has been sent since the dispatch, so it is *genuinely*
984
- empty. **The outbox is the last test, not the only one, and it stands wherever
985
- a fix-applier exists** — that is exactly where a ruling you still owe it is
986
- outstanding, so never dispatch off it while you do. Empty your outbox to it
987
- first — including any ruling you have withdrawn or reversed — then dispatch
988
- (below); a final report is not proof it stopped. A PR that needs nothing fixed
989
- reaches a finisher through the **fix-applier reports `no-op`** bullet below,
990
- never by waiting for a second CI event this head will never produce. The
991
- same goes for a red one: a red that fired before the review never fires
992
- again, so the **fix-applier reports `no-op`** and **review result lands**
993
- bullets are also the only routes to the red-check fixer there.
994
- Then run the tick.
995
- - **A fix-applier reports `no-op`, or a SHA you have already bound** → dispatch
996
- the finisher **now**, against the existing head — when that head's bound
997
- conclusion is red, the red-check fixer instead (**Then dispatch a red-check
998
- fixer**, below), never a finisher and never a wait. No push means no new run, and
999
- the Monitor above is edge-keyed on `<run-id>:<attempt>:<conclusion>` — that
1000
- head's terminal state already fired once and will never fire again, so waiting
1001
- for the CI event waits forever. This stays a common outcome on a clean PR:
1002
- `suggestion` is the band a clean diff produces, and every out-of-scope or
1003
- refuted one is filed as an issue rather than committed. An edge-only label path
1004
- therefore strands exactly the PRs with nothing wrong with them. **Reconcile, do
1005
- not wait for an event** governs here too, not only the implementer row. **This
1006
- bullet and the one above are a pair, and on a clean PR this one carries the
1007
- whole route to a finisher**: a `no-op` report satisfies the gate above by
1008
- itself — the review has returned, because a fix-applier exists only after it
1009
- did, and the member has reported — so nothing further is owed and no further
1010
- event is coming. Edit either bullet without the other and what strands is
1011
- exactly the PR that needed no fixes.
1012
- - **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → no workflow run will ever
1013
- complete for this repo, so the CI-run-completion edge above never fires and
1014
- waiting for it stalls the whole PR — the same silent-stall shape reported
1015
- before this verdict existed. Dispatch the finisher off the reviewer's final
1016
- verdict instead, the moment it lands — and, same as above, never while you still
1017
- owe it a ruling — or hold anything else it has not received, a ruling you have
1018
- withdrawn or reversed included. The finisher's gate is then the
1019
- `--declare-no-ci` declaration, not a `check` job: with it, label off the
1020
- reviewer's verified suite run; **without it, do not label** — report that this
1021
- repo has no CI configured and no declaration, and stop. Absence never reads as
1022
- pass. See `review-and-fix.md` step 6.
1023
-
1024
- **In one line, every wake is one `fleet-event.mjs` call, which ends in the tick.** One tick invocation, and you act on what it prints:
1025
-
1026
- ```
1027
- ~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--in-flight <n>]
1028
- ```
1029
-
1030
- It reads the run itself, and nobody states a count. The In-flight count —
1031
- every open PR that closes an issue off `gh`, plus every claimed ticket whose
1032
- newest implementer is live or owed a replacement and has no such PR yet, off
1033
- the ledger — sits beside the live review units (in-flight `review=` tokens
1034
- plus unsettled `fix-pr-` ones), the merge bot, merge holds, tier mismatches
1035
- and the drain marker, all off `.fleet/ledger.md`; the unclaimed heads and the
1036
- supply come off `.fleet/shortlist.json`, which it refreshes itself when the
1037
- unclaimed count is below the In-flight bound, when the file is missing or
1038
- empty, when an Exclusion's premise has lifted, or when a branch-named
1039
- `behind-pr` or a `behind-issue` Exclusion still not lifted names a ticket the
1040
- file carries — never while the bound holds; the open PRs come off `gh`. A
1041
- ledger token it
1042
- cannot read, it refuses rather than guessing — a member counted live or gone on
1043
- a guess is the over- or under-dispatch it exists to prevent — so correct that
1044
- row with `ledger.mjs row` and tick again. The In-flight bound defaults to 5
1045
- and is fixed for the run: pass `--in-flight` on every tick when `$ARGUMENTS`
1046
- set it, and never otherwise.
1047
-
1048
- It prints `actual/target` and a named ACTION per role, with the whole **Queue
1049
- depth** guard table applied in code. Act on each line as it reads:
1352
+ - **The finisher-gate wakes** — a CI run reaching a terminal state, a fix-applier reporting `no-op`, a `no-ci` verdict → each is a bullet of **The finisher gate**.
1050
1353
 
1051
- - `PULL #<N> …` — one Pull per named ticket, in the order printed: phase 1's
1052
- read, then phase 2's dispatch. A ticket that fails the read is relabelled or
1053
- excluded (phase 1), and the next tick names the next head.
1054
- - `REFRESHED shortlist: <n> entries; <k> lifted` — the tick refreshed the
1055
- shortlist itself, and its `PULL` row already reads the result. `REFRESH
1056
- FAILED` is yours: `shortlist.mjs` could not run, and the implementer row is
1057
- blind until it can.
1058
- - `SUGGEST /triage, hold idle` — nothing is admissible after the refresh.
1059
- Suggest, never run (**Queue depth**).
1060
- - `specs-dropped=#<N> … (to-spec: User Stories heading)` at the end of the
1061
- implementer row's counts, whatever its ACTION — the tickets the to-spec
1062
- filter kept out of `supply`, read off the shortlist's `dropped`. Never
1063
- actionable. Log them as specs awaiting to-tickets (phase 0), not as no work.
1064
- - `DISPATCH fix-pr PR#<M> …` — a fix-applier per PR, for a review's survived or unverified findings,
1065
- a dispositions mismatch no retry has answered, or a `conflict-hold:#<M>` — the merge bot's, or one you recorded off a `CONFLICT` line (**Reviewers**). Printed
1066
- ahead of reviews on purpose: finishing what is started beats starting more.
1067
- - `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn
1068
- (**Reviewers**).
1069
- - `DISPATCH merge-bot` — the next `merge-bot-<n>` (**Merge bot**).
1070
- - `DISPATCH finisher PR#<M> …` — a finisher settled `labelled`, yet the open
1071
- list shows PR M without `ready-to-merge`, and no `label-off=` (**Run ledger**)
1072
- accounts for the removal. Apply the finisher gate (**Reviewers**: the
1073
- `check` job green on the current head), then dispatch the next-suffix
1074
- finisher at that head, one letter past the highest the PR has used: render
1075
- its brief with `dispatch-prompt.mjs render finisher --kind repair --member
1076
- finisher-pr-<M>-<x> …`, then `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`.
1077
- Never add the label yourself. A head
1078
- that moved is caught by the new finisher's duty 1 `past-pin` halt and the
1079
- re-review path that follows it. Finishers are not review units, so this
1080
- prints whatever the unit count reads.
1081
- - `ESCALATE unlabelled PR#<M> …` — a second finisher since the last `label-off=`
1082
- settled `labelled` and the label is still not on: the tick dispatches no
1083
- third. Not actionable; the maintainer's, through the cockpit's `unlabelled`
1084
- flag and the comment the repair finisher's report left (`fleet-event.mjs`'s
1085
- `finisher-report` entry).
1086
- - `CONFLICT PR#<M> …` — GitHub reads PR M `mergeable=CONFLICTING`, the ledger
1087
- tracks it, no conflict hold stands on it, no fix-applier, finisher or
1088
- implementer on it is live, and, if it carries `ready-to-merge`, no merge bot
1089
- is live: a queued PR is the bot's while one runs, and its own fallback records
1090
- the hold. Record it with `fleet-event.mjs conflict <M>`, not with the `ledger.mjs
1091
- row` form the row's detail prints: `row` replaces the whole line. The call
1092
- refuses a PR whose row already carries a hold no fix-applier has answered.
1093
- The tick then reads the hold as `DISPATCH fix-pr
1094
- PR#<M>`, a conflict fix-applier (**A `DISPATCH fix-pr PR#<M>` on a conflict
1095
- hold**), and that row obeys every hold. A review in flight does not stop the
1096
- line: `fix-due` waits for the review to return. It prints under a
1097
- main-checkout hold and a drain too, since it writes a record and dispatches
1098
- nothing.
1099
- - `ESCALATE conflict PR#<M> …` — PR M reads CONFLICTING again after two
1100
- conflict fix-appliers landed on it: a rebase treadmill. Comment on the PR
1101
- and flag it for a human; write no hold and dispatch no fix-applier. Not
1102
- actionable; it repeats while the PR reads CONFLICTING and clears once it
1103
- stops, closes or merges.
1104
- - `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
1105
- unchecked tier, the In-flight bound reached (`HOLD (in-flight <n>/<B>)` —
1106
- nothing to do unless its detail names a replacement to dispatch, else a
1107
- merge brings n below B), or every
1108
- queued merge candidate held behind a lower PR or on a conflict hold no
1109
- fix-applier has cleared. An unchecked tier is `tick --apply`'s to check, and
1110
- the hold stays while the check writes no verdict (its `tier-ok=`, or
1111
- `tier-unverifiable=` for a member settled `killed` or `released` with no
1112
- transcript, clears it); a mismatch is yours to clear, by dispatching the
1113
- replacement at the right tier (phase 2). Each prints its clearing step in
1114
- the row's detail. For a mismatch that is the replacement's name —
1115
- `impl-<N>-b` on a first retry, else one letter past the highest the ticket
1116
- has used, or that no retry letter is left. For an unchecked tier, which
1117
- `tick --apply` has already tried, it is the `tier-check.mjs` command to run
1118
- by hand when the tick ran without `--apply` or the check wrote no verdict,
1119
- with a batch entry per member it names (fill in `<file>`; `<session>` too
1120
- when no receipt of this run records one).
1121
- - `AT CAP`, `IDLE OK` — nothing to do on that row.
1122
- - `MAIN-CHECKOUT-DIRTY <paths> …`, printed above the rows, with every
1123
- dispatching row (implementers, reviewers, merge-bot) reading
1124
- `HOLD (main checkout dirty)` — the main checkout changed since the Phase 0
1125
- baseline. The line names the changed paths, or a `HEAD <was> → <now>` entry
1126
- when HEAD moved, and every live member; it
1127
- attributes nothing, because concurrent members make that a guess. Dispatch
1128
- nothing new and tell the maintainer: they resolve the stray paths FIRST,
1129
- then re-baseline with `~/.fleet/bin/fleet-run main-checkout.mjs --record`.
1130
- A path entry holds until that re-baseline, tick after tick; a `HEAD …` entry
1131
- clears itself once HEAD reads clean again, and is never re-baselined while
1132
- HEAD is off the run's branch. Never revert the
1133
- paths yourself, and never re-baseline over paths nobody has resolved. The
1134
- changes of yours that trip it are a mid-run tooling fix edited in this
1135
- checkout and the close-out commit's round trip through a branch; **Fix the
1136
- tooling mid-run** and the commit section of references/close-out.md say how
1137
- each is cleared.
1138
- - `MAIN-CHECKOUT-UNKNOWN …` with `HOLD (main checkout unknown)` — the tick
1139
- could not look: a git or hash read failed (`could not look:`), or the
1140
- baseline exists but cannot be read (`baseline unreadable:`). Never clean,
1141
- and **never re-baseline over it** — `--record` overwrites, so that certifies
1142
- a tree nobody read. Fix what the line names and tick again. `baseline v<n>
1143
- written by a newer plugin` is a baseline a newer plugin version wrote:
1144
- `--record` refuses over it too — run the plugin that wrote it. The
1145
- exceptions are the two whose remedy is `--record`: `baseline v<n> —
1146
- re-record`, an older-format baseline this plugin cannot compare; and
1147
- `baseline commit <oid> is missing from this repository`, which an amend or
1148
- reset followed by gc leaves — examine HEAD against `origin/main` FIRST,
1149
- since HEAD moved off that commit and nobody has looked at the move, and
1150
- resolve any stray paths, which the line does not name; only then re-record.
1151
- - `MAIN-CHECKOUT-NO-BASELINE …` with `HOLD (main checkout no baseline)` — no
1152
- baseline was recorded. Yours to fix: run
1153
- `~/.fleet/bin/fleet-run main-checkout.mjs --record`, which references/phase-0.md
1154
- describes under "Record the main-checkout baseline". A baseline
1155
- that vanished mid-run is not a fresh run — report it to the maintainer
1156
- before recording over whatever the tree now holds.
1157
- - `PHASE0-INCOMPLETE <step>[, <step>…] …`, printed first above the rows,
1158
- with every dispatching row (implementers, reviewers, merge-bot) reading
1159
- `HOLD (phase 0 incomplete)` — this run's phase-0 receipt
1160
- `.fleet/phase0.json` names a step `failed` or `pending`, or lacks one. In
1161
- place of the steps the line says the receipt is missing, unreadable,
1162
- another run's (its `run` is not the `at` in the controller record), or a
1163
- run whose controller has exited — the previous run's finished receipt, in
1164
- a session that has not yet run its own phase 0. It outranks every
1165
- other reason on those rows, `MAIN-CHECKOUT-*` included, whose lines still
1166
- print; a `baseline` step not `ok` is one of the steps it names.
1167
- `CONFLICT` rows and the stall report still print. Run the
1168
- `phase0.mjs` command the line names and act on what it prints: a re-run
1169
- resumes at the step that stopped. A `drift` or `unanswered` step and a
1170
- `fold-in` `NEED` are advice, named after `; advice:` on the line, or alone
1171
- on a `PHASE0-ADVICE …` line when nothing is incomplete; advice holds
1172
- nothing.
1173
- - `CHECK-LIVENESS <member> (<family> > p99 <t>m)`, printed above the rows — a
1174
- live ledger token has stayed live past its family's p99 run time, counted
1175
- from the first tick that saw it (`> 2×p99 …` from the second multiple of the
1176
- threshold on; `review:PR#<n>` names an in-flight `review=` launch). Advice,
1177
- not an action: it is not actionable, resets no `quiet`, changes no row and
1178
- frees no slot, and the tick settles and kills nothing. Take the census the
1179
- **Member unaccounted** row of **Failure handling** gives before you touch the
1180
- token. It repeats every tick while the token stays live past the threshold.
1181
- `--liveness-impl`, `--liveness-fix-pr`, `--liveness-finisher`,
1182
- `--liveness-merge-bot` and `--liveness-review` set the thresholds, in minutes.
1183
- - `UNRECORDED <stem> (transcript exists, no ledger token)`, printed above the
1184
- rows — the session directory holds a `<stem>.jsonl` whose stem is a member
1185
- name no row token, `## Dispatched` entry or `## Retired` line names: a
1186
- dispatch whose ledger write was forgotten. Record it with `ledger.mjs
1187
- dispatch`, or confirm it is a stranger's member.
1188
- Advice, like `CHECK-LIVENESS`: it resets no `quiet`, changes no row and
1189
- frees no slot, it repeats every tick while it holds, and the folded line
1190
- names it (`…; UNRECORDED <stem> persists — …`).
1191
- - `NO-TRANSCRIPT <member> (live <age>m, no <session>/<member>.jsonl)`, printed
1192
- above the rows — a live ledger token first seen more than
1193
- `--no-transcript-after` minutes ago (default 5) has no transcript in the
1194
- session directory: a dispatch whose `task` call was never made. Make the
1195
- `task` call, or settle the token `killed`. Advice the same way, folded as
1196
- `…; NO-TRANSCRIPT <member> persists — …`. Both lines read the session
1197
- directory this run's phase-0 receipt names, else `--session <dir>`; with
1198
- neither the tick skips them with one stderr line. A heartbeat state file
1199
- that exists but cannot be used — unreadable, not JSON, not a JSON object,
1200
- or holding a `controller` that cannot be judged — holds no first-seen
1201
- ages, and the tick never rewrites it, so every live token reads as first
1202
- seen that tick and neither `CHECK-LIVENESS` nor `NO-TRANSCRIPT` can fire.
1203
- The tick says so with one stderr line, `fleet-tick: CHECK-LIVENESS and
1204
- NO-TRANSCRIPT not checked — <file> <cause>, so first-seen ages are
1205
- unavailable`, naming only the checks that would have run that tick.
1354
+ ### Tick notes
1206
1355
 
1207
1356
  **Tier guards under Pull.** The per-dispatch `tier-check.mjs --batch` is
1208
1357
  phase 2's own step, run by `tick --apply`: a mismatch it finds is the
@@ -1221,22 +1370,7 @@ already handling is what makes that drain visible. **Every wake is still an
1221
1370
  edge, so none covers a fully drained queue**: no members and no open PRs is no
1222
1371
  event at all, and the tick goes unrun. That state is the heartbeat's.
1223
1372
 
1224
- **Beat when there is nothing to do, and never end your turn on a drained queue.** See references/ci-and-staleness.md.
1225
-
1226
- ```bash
1227
- ~/.fleet/bin/fleet-run fleet-heartbeat.mjs \
1228
- [--base 300] [--ceiling 1200] [--multiplier 2] [--hold 240]
1229
- ```
1230
-
1231
- It blocks, then prints one line. Which line it is, is the whole protocol:
1232
-
1233
- - `… interval elapsed (quiet=<n>) → run fleet-event.mjs heartbeat` — the level-check
1234
- is due. Run that command and act on what the tick it ends in prints.
1235
- Then arm the beat again.
1236
- - `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
1237
- command blocks for a whole interval (omp backgrounds one at 60s, which is
1238
- why the CI gate holds its wait in one `eval` cell polling `gh run view`).
1239
- Issue it again. That is still one blocking call per turn, never an idle turn.
1373
+ ### The beat's standing rules
1240
1374
 
1241
1375
  The interval doubles while the fleet asks for nothing and stops at `--ceiling`,
1242
1376
  so a quiet night costs ~26 wakes instead of ~96. **The ceiling is a real bound,
@@ -1317,6 +1451,8 @@ It is that run's end, not a verdict on yours, and no later tick prints it.
1317
1451
  Read the line and carry on; nothing in the fleet releases, relabels or
1318
1452
  reaps the stranded tickets for you, and nothing restarts the run that stranded them.
1319
1453
 
1454
+ ### Own the CI waits
1455
+
1320
1456
  **Own the CI waits.** Members are turn-based and cannot hold across a ten-minute
1321
1457
  run — they rebase, push, stop. Arm a second persistent Monitor over open PRs'
1322
1458
  latest runs, keyed `<run-id>:<attempt>:<conclusion>` so each terminal state fires once, and
@@ -1461,8 +1597,8 @@ line — total silence per tick, which is exactly what this section exists to
1461
1597
  remove. Capture its status (`prs=$(…) || prs=ERR`), latch it globally, and fall
1462
1598
  through to the same tail sleep. **Then iterate with the inline `$(printf '%s\n'
1463
1599
  "$prs")` form, never a bare `for pr in $prs`** — the assigned-variable trap in
1464
- **Shell traps**, which carries the mechanism, with its measurements in
1465
- references/shell-traps.md. It
1600
+ **Shell traps**, in references/shell-traps.md, which carries the mechanism and its
1601
+ measurements. It
1466
1602
  applies to **every** loop in this block, the `blind`-latch removal included:
1467
1603
  under a bare `for b in $blind` a recovered PR never leaves the list and the block
1468
1604
  emits a fresh RECOVERED every tick thereafter — the per-tick volume the latch
@@ -1502,27 +1638,6 @@ report recovery, never the exit code alone.
1502
1638
 
1503
1639
  ### Reviewers
1504
1640
 
1505
- **Dispatch the review, never wait on it, and act when its result lands. That is the default path.**
1506
- The tick names every PR owed one — `DISPATCH review PR#<M>`, oldest first —
1507
- and each gets one review, once per PR:
1508
-
1509
- a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch` — it loads `review-eval.mjs` through the Resolver (`~/.fleet/bin/fleet-run --path review-eval.mjs`), awaits `runReviewOnOmp` in its own kernel, writes the result file into the review's own run root and reports its path and `reviewed=` token; record `review=member:review-pr-<pr#>` on the PR's row before the dispatch call. **`scratch` is the scratch root itself, the absolute path `scratch-root.mjs` prints, never the review side's `<scratch>/pr<N>` partition:** the review creates `pr<N>/` under it, so a `pr<N>` passed in nests every run root at `pr<N>/pr<N>/`, and the review refuses a `scratch` whose last component is `pr` plus digits before dispatching anything.
1510
-
1511
- Write the `review=` token with `ledger.mjs review <pr> <token>`, which appends
1512
- it to the **PR's row** — the ticket row once `settle impl-<N>=PR#M` has run,
1513
- else `#M`, created when neither exists — and prints that row's key. `review`
1514
- is the only writer of `review=`/`reviewed=` tokens, so a PR's tokens sit on
1515
- one row in the order you wrote them. The tick counts in-flight reviews off the
1516
- ledger and nowhere else, so a review you launched and never recorded is one it
1517
- names again. `review` reads the PR's review record across every row that maps
1518
- to the PR, in ledger order, and refuses a write that adds a `reviewed=` with no
1519
- open launch before it, a launch identity the PR already used, a second launch
1520
- while one is open, or an unparseable `review=`/`reviewed=` (the ledger's token
1521
- grammar, below), or any token that is not a review token. `row` refuses a
1522
- write that adds a review token (one the row holds is carried), drops an open
1523
- launch, names a member twice on the line, or makes a PR map to a second row. A
1524
- bad token the ledger already holds is carried, never re-judged.
1525
-
1526
1641
  **`selectDimensions` sizes the fan-out to the diff and the verify budget
1527
1642
  follows severity.** It cuts one immutable
1528
1643
  snapshot, verifies every critical/important finding adversarially,
@@ -1609,141 +1724,39 @@ The review already re-dispatched each crashed specialist once, so what
1609
1724
  report and re-runs nothing — an absence of findings is not coverage.
1610
1725
 
1611
1726
  The rule this replaces — treat any dimension with nothing in
1612
- `survived`/`refuted`/`unverified` as unrun — was the workaround for having no
1613
- such field, and it over-refuses in the direction that costs work: a dimension
1614
- that ran clean has nothing in those three either.
1615
-
1616
- **`cwdAudit` is the specialist's own inherited-checkout audit, one entry per
1617
- dispatched dimension: `{dimension, state, line}`, `state` one of**
1618
- `clean`/`dirty`/`unrepo`/`missing`. The prompt asks every specialist to run
1619
- `git status --porcelain -uall` against the directory it inherited before
1620
- returning and fold the result into a `CWD-AUDIT:` line — a convention, not
1621
- schema, so a specialist that never emits it or misspells it still validates
1622
- clean. This field is the runtime backstop that reads for the line regardless:
1623
- `missing` is exactly as loud as `dirty`, and both name a checkout you should
1624
- treat as a live scratch write until you have checked it.
1625
-
1626
- **A throw, an empty return, or a notification whose status is not `completed`
1627
- is a failure event, not a clean review.** The review throws on missing
1628
- `args.pr`/`args.worktree` and on a snapshot agent that returned no tree, and a
1629
- failure surfaces mid-loop, where "react, never block" makes it easy to log and
1630
- carry on — leaving a PR that *reads* as reviewed and is not. **Retry once
1631
- under the next runner letter, then stop:** the `review-pr-<pr#>` runner
1632
- already retried once inside its cell and reports `failed` with both errors, so
1633
- the retry is a second runner under the next letter the PR's rows do not carry
1634
- yet — `review-pr-<pr#>-b` after a first runner — recorded as
1635
- `review=member:<that name>`. A second failure is reported, and the PR stays at
1636
- review-due. Settle the dead review by appending `=failed` to its `review=`
1637
- token, then append `review=member:<that name>` after it, both in one
1638
- `ledger.mjs review <pr> review=<dead launch>=failed review=member:<that name>`
1639
- call — `review` settles the dead launch in place, and refuses a new launch
1640
- while the dead one still reads open, and the tick takes the last `review=`
1641
- token on a row as the one in flight, so that order is what keeps the retry
1642
- counted as the live review unit. A
1643
- runner member that is killed rather than failed follows **Failure
1644
- handling** (fresh name, inherited state stated).
1645
-
1646
- **Then dispatch a fix-applier** — on `DISPATCH fix-pr PR#<M>`, which the tick
1647
- prints for a PR whose `reviewed=` counts survived or unverified findings that
1648
- no review fix-applier
1649
- has landed `applied:`/`no-op` on since, with no fix-applier live on it — one
1650
- named member per PR, `fix-pr-<pr#>` (the next suffix when that name is already
1651
- on record), never the PR's
1652
- implementer, its brief rendered with `dispatch-prompt.mjs render fix-applier
1653
- --kind review --member fix-pr-<pr#> …` and then recorded with `ledger.mjs
1654
- dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch,
1655
- the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`,
1656
- `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>`
1657
- in that brief is the absolute path `scratch-root.mjs` printed, the
1658
- `dispositions-<its name>.json` record's included. The fix-applier owns every per-PR ruling you once made
1659
- before dispatch: both mutual-exclusion scans, the suggested-fix re-derivation,
1660
- `refuted=false` ≠ apply, per-site measurement for a sibling-site extension, and
1661
- `testEnvironment`/`cwdAudit` before any result of the shared test run. It
1662
- holds every finding and you hold none, so there is nothing for you to rank,
1663
- relay or pre-rule — and a report from a refuter it spawns that surfaces to you
1664
- is its to retrieve, never yours to scan or pass on.
1665
-
1666
- **A `DISPATCH fix-pr PR#<M>` on a conflict hold** — the row carries an
1667
- unresolved `conflict-hold:#<M>`, the merge bot's (`run-merge-bot.md` step 1's
1668
- fallback) or one you recorded off the tick's `CONFLICT` line —
1669
- is the same slot with a different job, and no review file to hand
1670
- over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
1671
- already on record — `dispatch` refuses a reused one — render its brief with
1672
- `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`,
1673
- and dispatch it with the
1674
- `agent` that `ledger.mjs dispatch` printed, in the PR's existing worktree.
1675
- `dispatch` prints this member's definition, `fleet-fix-applier` whatever the
1676
- row's `tier=` — read it off that output, never recall it. Its `conflict` brief carries the
1677
- same worktree and branch identity paragraph, but in place of the review paragraphs:
1678
- bring `<branch>` current with `origin/main`, resolving every conflict by
1679
- `run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
1680
- head. Settle it `applied:<head>` — `no-op` if no conflict was left — which is
1681
- what lifts the tick's merge hold; a dispatched-but-live one does not, and
1682
- `failed`/`killed` leave the PR fix-due for a replacement. It answers the
1683
- hold and nothing else: survived or unverified findings of a returned review the row also carries
1684
- stay unanswered through its settle, so the tick prints `DISPATCH fix-pr
1685
- PR#<M>` again once it lands, and that one is a review fix-applier, dispatched
1686
- as above. On a PR carrying
1687
- `ready-to-merge`, the push moves the head after the label, so the next merge
1688
- bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure
1689
- handling**.
1690
-
1691
- **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the
1692
- PR's current head that is not **solely** staleness: a `rebase-check` red, or
1693
- heavy jobs `skipped`, that comes only off the behind-count gets no fixer (the
1694
- five-condition note in the fix-applier body states how to establish
1695
- that). The tick prints no `DISPATCH` for it, so you reconcile it yourself, and
1696
- it always goes after the review, never before. Take the common case, the
1697
- implementer's own first CI firing turning red before any review exists: the
1698
- review is still dispatched against that head as normal, because a red suite is
1699
- review evidence and not a blocker. While a review or a review fix-applier on
1700
- the PR is live or still owes its report — a dispositions mismatch awaiting its
1701
- retry and a conflict hold awaiting its fix-applier included — the red-check
1702
- fixer does not fire: their push starts a new run, and a fixer racing them
1703
- would work on a SHA that is still moving. These edges dispatch it, each the
1704
- finisher's own: **Monitor: CI run completes** binding a red on a head
1705
- whose review has returned and whose fix-applier, if any, has reported;
1706
- **A fix-applier reports `no-op`**, or a SHA you have already bound, when that
1707
- head's bound conclusion is red; and **A review result lands** with no finding
1708
- and nothing to file, when that head's bound conclusion is red. The Monitor is
1709
- edge-keyed on `<run-id>:<attempt>:<conclusion>`, so a red that fired before the
1710
- review never fires again, and with no push there is no new run — the other
1711
- edges are the only route there, so do not wait for an event. Edit one of these
1712
- bullets without the others and what strands is exactly the red-only PR.
1727
+ `survived`/`refuted`/`unverified` as unrun — was the workaround for having no
1728
+ such field, and it over-refuses in the direction that costs work: a dimension
1729
+ that ran clean has nothing in those three either.
1713
1730
 
1714
- Name it `fix-pr-<M>`, or the next free suffix (`-b`, `-c` …) — `dispatch`
1715
- refuses a reused name — render its brief with `dispatch-prompt.mjs render
1716
- fix-applier --kind red-check --member <name> …`, record it with `ledger.mjs dispatch <pr#> <name>`
1717
- before the call, and dispatch it with the `agent` that command printed
1718
- (`fleet-fix-applier`, as for a review fix-applier), in the PR's
1719
- existing worktree. Its `red-check` brief carries the same worktree and branch
1720
- identity paragraph, but in place of the review paragraphs: read the failing job's
1721
- log, fix the cause, run `<testCmd>`, push, report the new head, and **stop**.
1722
- It is told outright not to watch, poll or wait for CI: your persistent Monitor
1723
- owns the next run on the pushed head, and the finisher gate — review returned
1724
- AND fix-applier report sent — applies to this member the same way. Settle it
1725
- `applied:<head>` once a fix is pushed. Settle it `no-op` only when the red
1726
- turns out not to be this member's to fix — a flake that passes on rerun, or
1727
- staleness — with nothing pushed; `no-op` counts as landed, so it never stands
1728
- for "could not fix". Settle it `failed` when it cannot reach green, which the
1729
- **Failure handling** row "Reviewer, fix-applier or red-check fixer cannot
1730
- reach green" covers.
1731
+ **`cwdAudit` is the specialist's own inherited-checkout audit, one entry per
1732
+ dispatched dimension: `{dimension, state, line}`, `state` one of**
1733
+ `clean`/`dirty`/`unrepo`/`missing`. The prompt asks every specialist to run
1734
+ `git status --porcelain -uall` against the directory it inherited before
1735
+ returning and fold the result into a `CWD-AUDIT:` line — a convention, not
1736
+ schema, so a specialist that never emits it or misspells it still validates
1737
+ clean. This field is the runtime backstop that reads for the line regardless:
1738
+ `missing` is exactly as loud as `dirty`, and both name a checkout you should
1739
+ treat as a live scratch write until you have checked it.
1731
1740
 
1732
- **A `DISPATCH fix-pr PR#<M>` on a dispositions mismatch** — the PR's row carries
1733
- `dispositions-mismatch=<member>:<run>` for its latest review's run, and no later
1734
- fix-applier has landed — is one automatic retry, a review fix-applier named the
1735
- next suffix (`fix-pr-<M>-b`) and dispatched like the first, its brief rendered with `--kind dispositions-retry`. Its prompt is the
1736
- first one's with the retry paragraph added: `--mismatched-record`, the mismatched member's record
1737
- `<scratch>/dispositions-<member>.json` it starts from, and `--violations`, the check's
1738
- violation list as printed — the lines
1739
- `dispositions-check.mjs` printed, each naming a bucket, an index and a rule;
1740
- re-run the check for the mismatched member to reprint them. It writes its own
1741
- record, and when it reports you run the check for it exactly as for the first
1742
- one. `ok` ends it. A second failure on the same review is written as
1743
- `dispositions-escalate=fix-pr-<M>-b:<run>` in place of a mismatch: the tick
1744
- prints no `DISPATCH fix-pr` for it, `dispatch` refuses the finisher naming
1745
- `dispositions escalate`, and you post the check's output with `gh pr comment <M>`
1746
- and flag the PR for a human. A new review of the PR counts again from none.
1741
+ **A throw, an empty return, or a notification whose status is not `completed`
1742
+ is a failure event, not a clean review.** The review throws on missing
1743
+ `args.pr`/`args.worktree` and on a snapshot agent that returned no tree, and a
1744
+ failure surfaces mid-loop, where "react, never block" makes it easy to log and
1745
+ carry on — leaving a PR that *reads* as reviewed and is not. **Retry once
1746
+ under the next runner letter, then stop:** the `review-pr-<pr#>` runner
1747
+ already retried once inside its cell and reports `failed` with both errors, so
1748
+ the retry is a second runner under the next letter the PR's rows do not carry
1749
+ yet — `review-pr-<pr#>-b` after a first runner — recorded as
1750
+ `review=member:<that name>`. A second failure is reported, and the PR stays at
1751
+ review-due. Settle the dead review by appending `=failed` to its `review=`
1752
+ token, then append `review=member:<that name>` after it, both in one
1753
+ `ledger.mjs review <pr> review=<dead launch>=failed review=member:<that name>`
1754
+ call — `review` settles the dead launch in place, and refuses a new launch
1755
+ while the dead one still reads open, and the tick takes the last `review=`
1756
+ token on a row as the one in flight, so that order is what keeps the retry
1757
+ counted as the live review unit. A
1758
+ runner member that is killed rather than failed follows **Failure
1759
+ handling** (fresh name, inherited state stated).
1747
1760
 
1748
1761
  **A refutation resting on an injection nothing proved landed is not a refutation — it is a cell that never ran.** See references/reviewers.md.
1749
1762
 
@@ -1803,108 +1816,11 @@ substituting `<testCmd>` with nothing leaves it no gate at all.
1803
1816
 
1804
1817
  **Where `<branch>` comes from:** the PR's head branch — `gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut the worktree from. See references/reviewers.md.
1805
1818
 
1806
- **What a fix-applier receives.** Its standing text — the worktree and
1807
- session-root discipline, the review result file and every ruling on it, the
1808
- claim discipline, the refuter prompt, the kill rule, the stash prohibition, the
1809
- dispositions record and the report rules — is the body of
1810
- `agents/fleet-fix-applier.agent.md`, which the harness injects as its system
1811
- prompt, so none of it is pasted. The brief carries what varies, and the
1812
- renderer prints it: `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
1813
- fix-applier --kind <review|conflict|dispositions-retry|red-check> --member <name>
1814
- --worktree <abs-path> --branch <branch> --testCmd <testCmd> --scratch <scratch>`,
1815
- plus `--pr <pr#> --run <run>` for a review or a dispositions retry and
1816
- `--mismatched-record <path> --violations <list>` for a retry. Then
1817
- `ledger.mjs dispatch <pr#> <name>` records it before the call.
1818
-
1819
1819
  **The standing CI facts are in the fix-applier body, not in per-event messages** —
1820
1820
  otherwise you send "your red is staleness, do not rebase" once per member per
1821
1821
  merge. `review-and-fix.md` states them; the body says they apply.
1822
1822
 
1823
- **The fix-applier pushes and exits — it does not hold the CI wait.** You own the
1824
- persistent Monitor; a turn-based member re-reading `gh pr checks` each idle cycle
1825
- rebuilds a 100k-token context for nothing the Monitor lacks. The body
1826
- carries the report-last rule and the brief says to push, write the report and exit; you do not have to restate either. When the
1827
- diff-validating `check` job is green **and no
1828
- heavy job is in `failure`** (the heavy diff-validating suites — not the
1829
- `rebase-check` currency gate; a `skipped` heavy job is behind-count staleness and
1830
- fine — **solely** off that count, which is a condition to establish rather than
1831
- infer, see the five-condition note in the fix-applier body) — or
1832
- `ci-state.mjs` reads `verdict: "no-ci"`, see below — **and once the PR's review
1833
- has returned and its fix-applier, if one was dispatched, has sent its report,
1834
- which the CI-completes edge above states in full** — dispatch a
1835
- **finisher** — a fresh small agent, not the fix-applier resumed. Render its brief
1836
- with `dispatch-prompt.mjs render finisher --kind fresh --member finisher-pr-<pr#> …`
1837
- (`--kind repair` once an earlier finisher reported `labelled` without the label landing), record it with
1838
- `ledger.mjs dispatch <pr#> finisher-pr-<pr#>` before the call, then **dispatch
1839
- it with the `agent` that command printed and omit `model` on the call** — the
1840
- tier lives in that definition's frontmatter, `agents/fleet-finisher.agent.md`,
1841
- as the `@smol:low` route, which resolves through the operator's `modelRoles`.
1842
- Its four duties are a checklist — audit the
1843
- worktree, confirm every deferral has a tracker home and re-run the acceptance
1844
- mutation, apply one release label, report — and the
1845
- merge gate downstream still catches whatever it gets wrong, the same argument
1846
- that puts the merge bot on the same tier below. **Never dispatch
1847
- one while you still owe the fix-applier a ruling**: the pinned SHA is only as good
1848
- as the guarantee nothing else is inbound. **The test is your OUTBOX, not the
1849
- member's last message** — anything you have decided that it has not received,
1850
- including a ruling you have since **withdrawn or reversed**. **That is the test
1851
- of THIS condition only**: an empty outbox says nothing is inbound from you, and
1852
- nothing about whether the member considers itself finished, which is what the
1853
- report condition above is for. A withdrawal you
1854
- recorded only in the ledger is undelivered: the member still holds the original
1855
- and will act on it. Relay everything — reversals too — then dispatch.
1856
-
1857
- **That `dispatch` refuses a finisher — exit 2, nothing written — on a PR whose
1858
- latest `reviewed=` counts a survived or unverified finding, unless the
1859
- dispositions verdict answering that review's run is `ok`**: among the
1860
- `dispositions-*=fix-pr-<M>[-x]:<run>` tokens naming its run, the one
1861
- from the highest-suffixed fix-applier — so a second review at the same head is
1862
- answered by none of the first one's verdicts. A PR whose latest review counts
1863
- `0/<n>/0` is not gated. One counting `0/<n>/<u>` with `<u>` above zero is
1864
- gated like survivors, and the tick prints `DISPATCH fix-pr PR#<M>` for it: that
1865
- fix-applier's `no-op` and its `ok` verdict are what open the finisher. The
1866
- refusal names its cause. `dispositions
1867
- unchecked` — no verdict answers that review: run `dispositions-check.mjs` for
1868
- the fix-applier that answered the review, as `fleet-event.mjs`'s `fix-report`
1869
- entry states, then dispatch again. It names a `dispositions-unchecked=` verdict too —
1870
- no rule broke, but the check could not read where a deferral was filed, `gh`
1871
- unreachable or an issue unreadable: run the check again for that fix-applier
1872
- once `gh` answers (an issue that does not exist is unreadable too, and no re-run
1873
- answers that one: the check's stderr names it, and the record's issue number
1874
- needs correcting); the tick offers no fix-applier for it. `dispositions
1875
- mismatch` — no finisher: the tick prints `DISPATCH fix-pr PR#<M>` for it, and
1876
- the next-suffix fix-applier answers it (**Then dispatch a fix-applier**).
1877
- `dispositions escalate` — no finisher, no
1878
- retry and no further fix-applier: either a `critical` or `important` finding was
1879
- deferred `remedy-outside-diff`, or a second mismatch was drawn on one review, and
1880
- only a human can rule on either. Post the check's output, which names each
1881
- escalated finding or violating entry, with `gh pr comment <M>`, and flag the PR
1882
- for a human; re-running the check reprints it. Dispatch no fix-applier and no
1883
- finisher for that review, and expect no `fix-due` row for it; a new
1884
- review of the PR starts the check again. **On any PR with a
1885
- returned review, `0/<n>/0` included, it refuses too while a fix-applier on the
1886
- PR is still live, verdict or not** —
1887
- `fix-pr-<M>[-x] still live`: settle it, run the check for it, then dispatch
1888
- again. A re-review at the same head is a run of its own, so the earlier
1889
- round's verdict never answers it; once the check has run for the fix-applier
1890
- answering the new round, its verdict is the current one.
1891
-
1892
- **It refuses a finisher, too, while the PR sits on a conflict hold no
1893
- fix-applier has cleared** — the same per-PR fold the tick prints `DISPATCH
1894
- fix-pr` off, ahead of the dispositions verdict. A PR known to conflict cannot
1895
- merge, and a finisher on it would race the conflict fix-applier rebasing it.
1896
- Dispatch that fix-applier, let it settle `applied:`/`no-op`, then dispatch the
1897
- finisher again.
1898
-
1899
- **An unanswered question from the member is an outbox item, and it blocks dispatch with the same weight as a ruling you have already made.** See references/finisher.md.
1900
-
1901
- **A final report is not proof the member stopped.** Observed twice: a ruling
1902
- relayed after dispatch produced a new commit mid-audit, and a fix-applier that
1903
- reported "nothing outstanding" resumed on a ledger-only withdrawal and was
1904
- cycling mutants through the worktree when the finisher audited it. Both finishers
1905
- correctly halted. Note what that costs to detect: two reads of the same worktree
1906
- a minute apart showed *different* mutants, so a member's report and any single
1907
- `git status` are each valid only at their instant. Its duties, in this order:
1823
+ The finisher's duties, in this order:
1908
1824
 
1909
1825
  1. **Audit the worktree** by running one script, `finisher-audit.mjs` — the row
1910
1826
  lookup, the dirty check, the head-equality check and the cause derivation
@@ -1990,108 +1906,23 @@ refuses a finisher brief rendered without it.
1990
1906
  printed, the JSON line, so a `rebase` halt's report carries the output of
1991
1907
  `git cherry <pin> HEAD origin/main` that its `evidence` holds.
1992
1908
 
1993
- **What a finisher receives.** The instrument re-check, the test-run verdict
1994
- rule, duty 1's audit script and what each of its exits means, duty 3's script
1995
- and the halt-cause rule are the body of `agents/fleet-finisher.agent.md`, which
1996
- the harness injects as its system prompt; none of them is pasted. The
1997
- instrument-set rule is stated once, at the top of this file, which no finisher
1998
- is dispatched to read, so it reaches one through that body. The brief carries
1999
- the PR, the worktree, the dispatch pin, `<testCmd>` and the scratch root:
2000
- `~/.fleet/bin/fleet-run dispatch-prompt.mjs render finisher --kind <fresh|repair>
2001
- --member finisher-pr-<pr#> --pr <pr#> --pin <sha> --worktree <abs-path>
2002
- --testCmd <testCmd> --scratch <scratch>`, which `ledger.mjs dispatch <pr#>
2003
- finisher-pr-<pr#>` records.
2004
-
2005
- **Once the label is on, take it off before you approve any push.** The label is a
2006
- verdict on the tree the finisher read, and a GitHub label does not follow the
2007
- branch — on one PR it survived a push and came to sit on a commit nobody had
2008
- audited. Write `label-off=<latest finisher attempt>` onto the PR's row first
2009
- (`ledger.mjs token <PR number> label-off=<latest finisher attempt>`, which keeps
2010
- every token the row already has — **Run ledger**), then
2011
- remove `ready-to-merge`, then approve. The token is how the tick tells your
2012
- removal from a finisher that never labelled — a tick run between a removal and
2013
- its token re-dispatches a finisher into your take-off window. The label goes
2014
- before the approval because removing the artifact the merge bot gates on is
2015
- the reliable stop, where messaging the bot races it, and a label has been
2016
- observed holding until after an abort message arrived. Then
2017
- dispatch a **fresh** finisher against the new head; the first audit does not
2018
- transfer, since it verified a different tree. The merge bot refuses that head on
2019
- its own (`run-merge-bot.md`, **The labelled head**), so this is not the only
2020
- guard — but its refusal costs a pass and leaves the label lying, which is yours
2021
- to clear either way, the same way: `label-off=` first, then the removal.
2022
-
2023
- A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
2024
- and the causes `finisher-audit.mjs` names are the ones seen so far, not a
2025
- closed list; the finisher's agent body gives it the cause from one script
2026
- instead of asking anyone.
2027
-
2028
- **Resolving a finisher halt.** A halt is the finisher working correctly — it
2029
- refused to label — so it is never `failed`, which stays for a finisher that
2030
- crashed or gave up. Record it `ledger.mjs settle finisher-pr-<M>=halted:<cause>`,
2031
- `<cause>` the word the report names; the ledger refuses any other. Every halt
2032
- escalates two ways: the cockpit flags the PR `halted:<cause>` at severity 4 off
2033
- that token, and you post the finisher's halt report — cause and evidence — with
2034
- `gh pr comment <M>`, so it outlives the run. **No label**: the missing
2035
- `ready-to-merge` already keeps the PR out of the merge queue. Then the cause
2036
- decides the rest — two resolve automatically, every other one escalates:
2037
-
2038
- | Cause | Resolution |
2039
- |---|---|
2040
- | `live-editor` | **Automatic.** Ask the live member **by name** for its report, wait for it, then dispatch `finisher-pr-<M>-b` at the current head. If the head moved in the meantime, resolve it as `past-pin` instead. |
2041
- | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate. |
2042
- | `rebase` | **Escalate** — comment and flag, nothing more. Read the report's `git cherry <pin> HEAD origin/main`: only `-` lines is a clean rebase, and a `+` line is a conflict resolution that changed content or a commit past the pin. No automatic rule until a live halt shows the case recurring. |
2043
- | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
2044
-
2045
- `past-pin` needs the tick because the dead-review path cannot reach it: once a
2046
- review has **returned**, its `reviewed=` token holds the PR out of `review-due=`,
2047
- and settling that review `=failed` re-queues nothing — that path covers only a
2048
- review that died before returning. A head that moved past `reviewed=` with no
2049
- such halt — a fix-applier's push — stays not due: duty 2 verifies what it
2050
- applied. **A rebase never gets a `reviewed=`:** the earlier review still
2051
- counts, because dispositions verdicts are tied to its head. Never write a
2052
- `reviewed=` you did not read off a review result file.
2053
-
2054
- **Resolving a finisher that died.** A finisher settled `failed` or `killed` left
2055
- its PR without `ready-to-merge`, and nothing else notices: the PR is out of the
2056
- merge queue, and the tick dispatches no finisher for it. The cockpit flags a
2057
- REVIEW-column open PR without the label, whose latest finisher attempt settled
2058
- so, `finisher:failed` or `finisher:killed` at severity 4 — one token per
2059
- outcome, neither the implementer's bare `killed` flag nor `unlabelled`. You
2060
- resolve it by hand: investigate why the finisher died, or dispatch the
2061
- next-suffix finisher after the finisher gate: render its brief with
2062
- `dispatch-prompt.mjs render finisher --kind fresh --member finisher-pr-<M>-<x>
2063
- …` (`--kind repair` once an earlier finisher reported `labelled` without the
2064
- label landing), then `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`. The flag
2065
- clears when a later attempt settles — `labelled`
2066
- (then `unlabelled` takes over while the label is still off), `halted:<cause>`,
2067
- or a live `-b` — or when the PR carries `ready-to-merge`, merges or closes.
2068
- You never add the label yourself, and the tick does not retry.
2069
-
2070
- Gate on the `check` job, **not** on `ci-state --quiet` exit 0: a behind PR never
2071
- reaches full green, so an exit-0 gate strands it unlabelled. The finisher reads
2072
- per-job state (`ci-state.mjs` without `--quiet`, or its `jobs`), since `--quiet`
2073
- drops `jobs`, `missing` and `dropped`. Normal path, not only kill-recovery.
2074
-
2075
- **`ci-state.mjs` reads `verdict: "no-ci"`** — no `check` job exists in this repo
2076
- to gate on, and that is not a third way to skip the wait. **The
2077
- `--declare-no-ci` declaration is caller-side, and reading it back out of the
2078
- payload verifies nothing**: the flag is echoed into `reasons` and flips the exit
2079
- code, so re-running with it and finding it there confirms only that you passed
2080
- it. Passing it yourself is not a second opinion. Check the two facts it stands
2081
- for instead:
2082
-
2083
- 1. `ci-state.mjs` **without** the flag still reads `verdict: "no-ci"`. A repo
2084
- whose CI is merely misconfigured — workflow files present under other names,
2085
- or `.github/workflows/` not a directory — exits 2 there rather than reading no-ci,
2086
- so this is the check that separates real absence from misconfiguration, the
2087
- case that must never ship silently.
2088
- 2. The reviewer's own final verdict reports a green `testCmd` run on the SHA it
2089
- pushed. `review-and-fix.md` step 3 requires it to, and that run is the only
2090
- gate this repo actually has.
2091
-
2092
- Both → add the label, and say it rests on the reviewer's suite run, not on CI.
2093
- Either missing → halt here, same as a dirty worktree: report `no CI configured,
2094
- no verified suite run on record` and add no label.
1909
+ **Once the label is on, take it off before you approve any push.** The label is a
1910
+ verdict on the tree the finisher read, and a GitHub label does not follow the
1911
+ branch — on one PR it survived a push and came to sit on a commit nobody had
1912
+ audited. Write `label-off=<latest finisher attempt>` onto the PR's row first
1913
+ (`ledger.mjs token <PR number> label-off=<latest finisher attempt>`, which keeps
1914
+ every token the row already has — **Run ledger**), then
1915
+ remove `ready-to-merge`, then approve. The token is how the tick tells your
1916
+ removal from a finisher that never labelled — a tick run between a removal and
1917
+ its token re-dispatches a finisher into your take-off window. The label goes
1918
+ before the approval because removing the artifact the merge bot gates on is
1919
+ the reliable stop, where messaging the bot races it, and a label has been
1920
+ observed holding until after an abort message arrived. Then
1921
+ dispatch a **fresh** finisher against the new head; the first audit does not
1922
+ transfer, since it verified a different tree. The merge bot refuses that head on
1923
+ its own (`run-merge-bot.md`, **The labelled head**), so this is not the only
1924
+ guard — but its refusal costs a pass and leaves the label lying, which is yours
1925
+ to clear either way, the same way: `label-off=` first, then the removal.
2095
1926
 
2096
1927
  **Every implementer body carries the claim discipline, because tickets that restate facts ship new wrong claims** — inherited from the ticket, and minted in prose nobody asked for. See references/correction-tickets.md.
2097
1928
 
@@ -2108,52 +1939,6 @@ from any spelling of the grep.
2108
1939
 
2109
1940
  ### Merge bot
2110
1941
 
2111
- Per pass, named `merge-bot-<n>`, never two at once. `ledger.mjs dispatch
2112
- merge-bot` names it before the dispatch call — `n` is 1 + the highest
2113
- `merge-bot-<n>` the session holds, in the ledger's `## Dispatched` list, on a
2114
- row or in `## Retired`, so it restarts at 1 only when none was carried or
2115
- retired (a `dead` or `none` rotate, or a fresh start), a replacement for a
2116
- dead bot takes the next `n`, and nobody counts. With no brief rendered for
2117
- that name it refuses, naming the bot and the `dispatch-prompt.mjs render
2118
- merge-bot --member merge-bot-<n> …` to run — render it, then run `ledger.mjs
2119
- dispatch merge-bot` again. Dispatch
2120
- it on the tick's `DISPATCH merge-bot`: the first `ready-to-merge` label is
2121
- enough, and it never waits for the finisher's report. Its body
2122
- (`agents/fleet-merge-bot.agent.md`) tells it to read
2123
- `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
2124
- pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
2125
- for late labels, then report once and exit — and that you dispatched it,
2126
- which is what makes it hold that grace instead of arming its own watcher. Its
2127
- brief is `~/.fleet/bin/fleet-run dispatch-prompt.mjs render merge-bot --member
2128
- merge-bot-<n> --n <n> --scratch <scratch>`, `<scratch>` the absolute
2129
- `scratch-root.mjs` output: the bot writes only under `<scratch>/pr<N>/merge-bot-<n>/`. **Dispatch
2130
- it with the `agent` that `ledger.mjs dispatch merge-bot` printed and omit
2131
- `model` on the call** — the tier lives in that definition's frontmatter,
2132
- `agents/fleet-merge-bot.agent.md`, as the `@smol:low` route, which resolves
2133
- through the operator's `modelRoles`.
2134
-
2135
- Rebase, wait for green, check the
2136
- label, merge is checklist work, and a bad merge still needs the label and the
2137
- per-job CI state to have been read correctly, which is exactly what a wrong
2138
- merge later surfaces and a human resolves; `no-undo-audit.sh` is the
2139
- deterministic, script-driven backstop run before every push specifically to
2140
- catch a wrongly-resolved conflict, so the tier buys nothing that backstop
2141
- doesn't already cover.
2142
-
2143
- **The shell traps live in the merge bot's agent body, not in its brief and not
2144
- in a follow-up message.** A bot already looping cannot be corrected — the loop
2145
- consumes the turns a correction would land in — so
2146
- `agents/fleet-merge-bot.agent.md` carries **every entry in Shell traps**, each
2147
- written out in full: the rules in that section with the measurements from
2148
- `references/shell-traps.md` beside them, and the bot has them before its first
2149
- turn. The bot reads an exit code off `gh pr update-branch`, `merge-gate.mjs` and
2150
- `prove-merge.sh`, which is the `PIPESTATUS` and read-only-`status` pair, and its
2151
- grace poll captures `gh pr list` output and loops over it, which is the
2152
- assigned-variable trap. Its brief names the bot and `<scratch>`, plus the
2153
- one-line no-acknowledgement notice; do not paste the traps there. An edit to
2154
- Shell traps or to `references/shell-traps.md` lands in that body in the same
2155
- change.
2156
-
2157
1942
  **Its merge gate is one script, run twice.** Step 3 of `run-merge-bot.md` is
2158
1943
  `merge-gate.mjs --pr <n> --pre <sha> [--post <sha>]`: read-only, it runs the
2159
1944
  instrument re-check, the label and review-decision read and a run-bound
@@ -2288,6 +2073,8 @@ ledger rows in the same step. See references/reaping.md.
2288
2073
 
2289
2074
  ## Worktree and claim model
2290
2075
 
2076
+ Run none of this by hand: act through `claim-ticket.sh`, `release-ticket.sh`, `reap.sh` and `inflight.sh` as their phases say, and dispatch every member into its claimed worktree by absolute path.
2077
+
2291
2078
  **Claim, release and reap are unchanged on omp.** `claim-ticket.sh`,
2292
2079
  `release-ticket.sh`, `reap.sh` and `inflight.sh` are git-native and operate on
2293
2080
  the single shared ref store every worktree and the main checkout read and
@@ -2312,6 +2099,8 @@ where the controller itself runs from.
2312
2099
 
2313
2100
  ## Queue depth
2314
2101
 
2102
+ Read the depth off the tick and never derive it by hand: act on the row it prints, and when it prints `SUGGEST /triage, hold idle`, hold the implementer row idle and suggest `/triage` in the report.
2103
+
2315
2104
  - **shortlist** — `.fleet/shortlist.json`'s entries with no `impl-` row and no
2316
2105
  live `excluded` row: admissible, not yet pulled. The tick's `unclaimed=`.
2317
2106
  - **supply** — `scanned`, the open `ready-for-agent` tickets `shortlist.mjs`'s
@@ -2382,6 +2171,8 @@ never as a second, hand-run copy of it.
2382
2171
  | below the In-flight bound, missing or empty | the tick refreshes first — `REFRESHED shortlist: n entries; k lifted` — and Pulls from what it found |
2383
2172
  | 0 after that refresh | `SUGGEST /triage, hold idle` |
2384
2173
 
2174
+ ### Specs, the refresh bound and the holds
2175
+
2385
2176
  Whatever the row prints, a `specs-dropped=#<N> (…)` at the end of its counts
2386
2177
  names the tickets the to-spec filter kept out of the shortlist — specs
2387
2178
  awaiting to-tickets, so an empty shortlist carrying one is not "no work".
@@ -2417,153 +2208,145 @@ line that says why.
2417
2208
  not a blocking prompt. Counts come from cheap `gh issue list --search`, no bodies.
2418
2209
  A starved implementer queue never stalls the review or merge side.
2419
2210
 
2420
- ## Invariants
2421
-
2422
- - In-flight tickets at most the bound (default 5), ≤ 1 merge bot. The bound
2423
- counts tickets, not live agents — members fan out and their children consume
2424
- slots you never dispatched.
2425
- - A grandchild surfaces as its own task-notification. An unrecognized task-id is
2426
- not a member reporting done.
2427
- - A reviewer never reviews a PR it implemented.
2428
- - The merge bot only touches PRs whose implementer reported done. Rebasing a
2429
- worktree someone is working in destroys uncommitted work.
2430
- - `ready-to-merge` is added by a reviewer only — never an implementer, never you.
2431
- **The run's own artifact PR is exempt, and it is exempt because this invariant
2432
- does not reach it:** what the line forbids is a fleet member signing off its own
2433
- ticket work, which presupposes an issue, an implementer, a `review-pr` run and a
2434
- finisher, and the metrics PR you author has none of them. Label and
2435
- merge that one yourself instead of re-deriving a blocker from this line and
2436
- stranding the rows behind it. The exemption belongs to the run that authors the
2437
- PR and does not outlive it: one still open when the run ends is a PR a prior run
2438
- left open, which phase 0 folds into the next run's review queue as ticket work —
2439
- and a PR is not exempt from being wrong, only from waiting on a reviewer
2440
- no phase of this run will ever dispatch against it.
2441
- - **Every member acts through the maintainer's `gh` credentials, so no write is
2442
- attributable.** Any invariant about *who* did something is unenforceable after
2443
- the fact: when a label moves unexpectedly, ask members directly, rule out
2444
- automation with `grep -rn '<label>' .github/workflows/`, and do not re-add it.
2445
- - Phase 1 is serial. Everything else may run concurrently.
2446
-
2447
- ## Guards
2448
-
2449
- **Verify every reported SHA.** `~/.fleet/bin/fleet-run verify-sha.sh
2450
- <branch> <sha>` before enqueueing — a member can commit in a nested worktree,
2451
- leaving the SHA on a stray branch while its report reads normally. Exit codes as
2452
- `inflight.sh`: `# 0 reachable, 1 not reachable, 2 unanswerable`. Not reachable
2453
- (exit 1) → flag, do not enqueue, do not return the ticket to the shortlist until the
2454
- maintainer rules. **Exit 2 is not a verdict** — the question could not be
2455
- answered, and every cause of it reaches you as one shape: no JSON on stdout at
2456
- all, the cause on stderr alone. Read that stderr, fix what it names and re-run;
2457
- escalate if it repeats. Never read exit 2 as `not reachable`, and never record it
2458
- as a stray commit — the flag and the maintainer's ruling above are what exit 1
2459
- earns, and spending them on a probe that never answered costs a member its
2460
- ticket over a failure a re-run would have cleared.
2461
-
2462
- **Never `--delete-branch` — the merge bot deletes the head branch itself.**
2463
- `gh pr merge <n> --merge` alone: the flag's local cleanup errors on a `main`
2464
- held by another worktree, or strands the feature worktree on `main`. After the
2465
- merge, `delete-merged-branch.sh <pr>` deletes the branch from `origin` and reads
2466
- the deletion back; `reap.sh` takes the `[gone]` local branch and its worktree.
2467
- No repo setting is relied on to do it. A branch another open PR still
2468
- uses as its head or base is kept instead — `branch-kept-#<that PR>` in the bot's
2469
- report, a deliberate keep and not a failure.
2470
- The branch-delete step also releases the claim label: it drops `in-progress` from
2471
- every issue the PR closes.
2472
-
2473
- **Never force a rebase to start.** No `git clean`, `git checkout .`,
2474
- `git reset --hard`, `git stash`. Uncommitted changes may exist nowhere else.
2475
- Non-empty `git status --porcelain -unormal` → stop and report — the explicit
2476
- mode, never bare `--porcelain`, or `status.showUntrackedFiles = no` reads an
2477
- empty answer here and licenses the rebase over work this check exists to
2478
- protect. Stashing empties it either way, so that check and
2479
- `no-undo-audit.sh` both go quiet on work nothing else holds.
2211
+ ## Tier outcomes guard
2480
2212
 
2481
- **Cross-check what members report about their environment.** Wrong often enough
2482
- to matter, and a confident wrong report from a reviewer flips a verdict.
2213
+ This guard is done when you have run `tier-outcomes.mjs append` once for each PR whose review you rule; never conclude a tier result inside one run.
2483
2214
 
2484
- **Distrust negative claims hardest.** "Nothing else references this", "the sweep
2485
- is clean" — most likely false, least likely checked: a grep that found nothing
2486
- looks like a grep never run. Make members state their search scope. Negative claim
2487
- vs specific finding with paths → paths win.
2215
+ **Guard: accumulate per PR, never conclude inside one run.** The unit is the PR —
2216
+ supply is one Pull per free slot, so there are no implementer batches. **Append one row to
2217
+ `docs/metrics/tier-outcomes.tsv` when you rule each PR's review, with
2218
+ `~/.fleet/bin/fleet-run tier-outcomes.mjs append <pr> --closed-own-ticket yes|no --minted-false-claim yes|no --note "<text>"`,
2219
+ never by hand** (that file's header carries the column meanings). The script
2220
+ fills `run_date`, `pr`, `ticket` and `tier` itself — `tier` from what actually
2221
+ ran, off the implementer's `tier-ok=` ledger verdict or else its one
2222
+ member-outcomes row (a `tier-unverifiable=` member has no ledger verdict, so
2223
+ its one member-outcomes row decides), and BLANK with a WARNING naming why
2224
+ when neither settles
2225
+ it; never type a tier in over that. A PR that already has a row is left
2226
+ untouched, so re-running it is safe. That append is the whole duty.
2488
2227
 
2489
- **Members share one filesystem, one docker stack and one process table**, and the
2490
- failures arrive as *wrong findings*, not errors:
2228
+ The row's last four fields are the ticket's difficulty, and they are what lets a
2229
+ tier comparison condition on the thing that swamps it. `sizing` is the
2230
+ **member's** own `light`/`heavy` verdict from its phase-2 `sizing-a-ticket`
2231
+ run, which `append` reads itself off the member's report file
2232
+ (`<scratch>/reports/impl-<ticket>[-x].json`, its `sizing.verdict`, the highest
2233
+ retry letter's when there are several), so you pass no `--sizing`; the member
2234
+ also puts it in the PR body's `Sizing:` line, with the signal it turned on;
2235
+ `profile`, `loc` and `files` all come from `diff-stats.mjs` over the merged
2236
+ diff. **Phase 0 does not size anything** — it shortlists, a Pull claims, and
2237
+ the sizing run happens inside the member after both, which is why the verdict
2238
+ has to travel in the member's report rather than being something you already hold.
2491
2239
 
2492
- - **A pattern kill reaches siblings — the implementer, fix-applier and finisher briefs forbid it.** See references/isolation.md.
2240
+ **A verdict is a measurement only if it post-dates the run that produced it.** See references/reviewers.md.
2493
2241
 
2494
- **What the victim's output looks like depends on the signal — and one of the cases is a clean green.** See references/isolation.md.
2242
+ The member-facts scrape, the drain of the pending ticket-features rows and the
2243
+ commit of the metrics files are steps of `closeout.mjs finish`, which **End of
2244
+ run** (Phase 3) drives. See references/close-out.md.
2495
2245
 
2496
- So **a complete summary block proves the runner survived, not that the run was
2497
- uncontaminated.** Scrutinize reds, short counts *and* greens from inside the
2498
- incident window; a killed **baseline** compared against a clean mutant is a
2499
- wrong measurement that reads exactly like a real result.
2246
+ **Why not decide inside one run.** A run holds 2-3 implementer PRs, and ticket
2247
+ difficulty swamps the tier effect — a gojq parity harness and a two-statement
2248
+ shell reorder are not comparable units. Finding-counts are not comparable either:
2249
+ `selectDimensions` trims the fan-out by diff profile, so one PR fields 29 agents
2250
+ over six dimensions and its sibling fields 8 over three. And the fleet is not
2251
+ stationary — this prompt gets edited mid-run when a defect earns it. Hence a
2252
+ binary outcome per PR, accumulating, rather than a per-run verdict.
2500
2253
 
2501
- **The command line is no partition either — not reliably.** See references/isolation.md.
2254
+ **Why the rows this guard fired on could not answer the tier question, and this
2255
+ is the load-bearing part.** Until the 2026-08-16 revert, `class` and `tier` were
2256
+ perfectly confounded: routine always ran `sonnet`, correction always ran top
2257
+ tier. So the comparison the file invites — routine-at-sonnet against
2258
+ correction-at-top-tier — measures **class, not tier**, because those classes fail
2259
+ in different ways by construction: corrections ship false claims in prose,
2260
+ routines ship incomplete or regressing code. A run that "mixes both" does not fix
2261
+ it. **Only a same-class comparison across tiers is informative**, and the old
2262
+ rule could not produce one, since no routine ticket ever ran at top tier.
2502
2263
 
2503
- Members report a stalled run to the controller instead of pattern-killing it,
2504
- and the controller re-checks any measurement taken in the window.
2264
+ **That last sentence is no longer true, and this is the part to re-read.** Since
2265
+ the revert every routine ticket runs at top tier, so the file now holds 55
2266
+ `routine`/`opus` rows against 11 `routine`/`sonnet` (as of 2026-08-28, 103 rows
2267
+ — recount before citing). The same-class comparison the paragraph above calls
2268
+ the only informative one therefore EXISTS now. It is still not clean: the two
2269
+ groups are split almost entirely by calendar date, so it measures prompt
2270
+ evolution at least as much as tier. The counter-evidence paragraph earlier in
2271
+ this section carries the split and the three rows that cut against it. Recount
2272
+ both, and every other figure in this section, with:
2505
2273
 
2506
- **Do not guess the victim — the blast radius is the machine, not the Pull.**
2507
- In that incident the controller reasoned from dispatch scope to "almost
2508
- certainly `impl-<N>`" and told the maintainer so; the named member then proved
2509
- it was not the victim (it had never invoked those files standalone, and its
2510
- mutation baselines post-dated the window). Idle members of *previous* runs,
2511
- other omp sessions on the same machine, and the maintainer's own shell are
2512
- all `pkill -f` targets and none of them appear in your ledger. Warn every live
2513
- member, record the incident as unattributed, and re-check measurements by
2514
- timestamp rather than by who you think was running.
2274
+ ```bash
2275
+ grep -vc '^#' docs/metrics/tier-outcomes.tsv
2276
+ awk -F'\t' '!/^#/ && $4=="routine" {n++; d[$1]=1; if($6=="no") no++} \
2277
+ END{print n, length(d), no+0}' docs/metrics/tier-outcomes.tsv
2278
+ awk -F'\t' '!/^#/ && $4=="routine" {t[$5]++; if($6=="no") f[$5]++} \
2279
+ END{for(k in t) print k, t[k], f[k]+0}' docs/metrics/tier-outcomes.tsv
2280
+ ```
2515
2281
 
2516
- - **A warning acted on silently is indistinguishable from one that never
2517
- arrived.** The same incident: the controller's warning DID reach the member,
2518
- which re-ran, found nothing changed, and said nothing — correctly reading
2519
- "send once, never re-send" as covering it. The controller then had to spend a
2520
- round trip asking whether its own outbox was lossy. So the briefs say that
2521
- **confirmation state includes warnings received and acted on, even
2522
- when the outcome is no change** — one line, in the report the member already
2523
- owes. That is the cheap half of the *never read silence as assent* rule, paid
2524
- by the member rather than by the controller's guesswork.
2282
+ **These rows are the historical corpus, and nothing appended to them fixes the
2283
+ confound.** What fixes it is the exploration draw in the dispatch rule above:
2284
+ one implementer in every five — every one, during burn-in — runs at a drawn
2285
+ cell beside the policy cell's, against the same prompts on the same day, so
2286
+ the comparison stops depending on which tier history happened to leave in
2287
+ which week. Read each cell's comparisons, not the whole-file split, once there
2288
+ are enough of them.
2525
2289
 
2526
- - **Specialist tree isolation is `review-and-fix.md`'s job — do not restate it.**
2527
- It owns the object-store rule, the two-tree split, snapshot provisioning, and
2528
- which suites a snapshot cannot validly run. Your only duty is to *not*
2529
- contradict it.
2530
- - **Filesystem isolation is not stack isolation.** A private copy of the
2531
- tree and a test command solve different problems; the compose project
2532
- name comes from the environment, not the working directory, so three
2533
- agents on three snapshots still collide on one postgres. "I'm on my own
2534
- copy" is exactly the intuition that skips the command — say both, every
2535
- time. Which command depends on the audience: a member in a worktree
2536
- uses `./agent-test`; a specialist on a snapshot does not, and takes the
2537
- one `review-and-fix.md` hands out. Which runner the worktree holds
2538
- decides why: the runner a claim writes is untracked, so a `git archive`
2539
- snapshot never carries it; one the repository tracks does ride along,
2540
- but no claim exported ports into it — its isolation is whatever that
2541
- repository built, not one triple per snapshot. See
2542
- references/isolation.md.
2543
- - **Scratchpad paths need two levels — the member's own partition, then one
2544
- directory per child it dispatches — and nothing outside them.** An
2545
- implementer partitions at `<scratch>/impl-<N>/`; the review side's partition
2546
- is `<scratch>/pr<N>/…`, which the review core creates itself, so a review
2547
- runner is handed the scratch root, never that partition; any member that
2548
- dispatches a child writes an absolute directory under its own partition into
2549
- that child's prompt, one per child and never shared, and a child never
2550
- derives its own. Finding ids restart at 1 every review, so two fix-appliers
2551
- on different PRs both reach for `unv1`; one
2552
- agent overwrote a sibling's `package.json`, and a probe built a git repo at
2553
- the *checkout root*. Read from the object store at a pinned ref, write only
2554
- under your own path. See references/isolation.md.
2555
- - **IDE/harness diagnostics attribute by bare filename, with no path.** **Never
2556
- relay a diagnostic without reproducing it in that member's specific worktree**
2557
- (re-run the check that raised it from there): probe copies carry the real
2558
- tree's filenames, so a sibling's throwaway mutation reads exactly like a live
2559
- worktree's error.
2560
- See references/isolation.md.
2290
+ **So read what the guard actually established: routine tickets sometimes fail to
2291
+ close their own ticket. Not that `sonnet` caused it.** The revert is the
2292
+ pre-committed rule being honoured, not a measurement. Restoring a cheap tier is
2293
+ still the maintainer's call and still a change to the dispatch rule — but the
2294
+ deliberate control it used to require is no longer something anyone has to
2295
+ authorize one ticket at a time: the exploration draw above produces one in
2296
+ every five Pulls by construction. **Do not read a cell early.** A cell's
2297
+ comparison is one session holding an admissible row at that cell — its tier
2298
+ check passed and its resolved effort is the cell's level — and one at
2299
+ `slow-high` whose resolved model and effort differ. Count them per cell, never
2300
+ pooled across cells, and stop until
2301
+ there are at least ten of them across five or more distinct `run_date`s; below
2302
+ that, a comparison count is a number, not evidence, and the last guard fired
2303
+ with n=1 on the control side. **Report the count the per-cell readout prints,
2304
+ never one from any other query:** `~/.fleet/bin/fleet-run cell-readout.mjs`
2305
+ prints `<cell> <comparisons> <run_dates> <resolved models>` for each cell past
2306
+ that floor and a cell below it only as a count on stderr; a `mixed (…)` models
2307
+ column means the cell's history spans more than one model behind its role.
2308
+ The pre-cell pair query counted pairs that are no cell's comparisons, and the
2309
+ query before that one counted every session whose implementers merely
2310
+ differed, so it cleared this floor by an order of magnitude while the
2311
+ controlled comparison did not exist yet.
2561
2312
 
2562
- Suspect a neighbour before a member's own diff — for unexplained failures, and
2563
- equally for any **finding** that came from reading source.
2313
+ ## Why the implementer body carries what it does
2314
+
2315
+ Read this before you edit any `fleet-implementer-<cell>` file, and stop editing when every cell's body is byte-identical again.
2316
+
2317
+ Why the agent body carries what it does — read this before editing any `fleet-implementer-<cell>` file, and keep every cell's body byte-identical. See references/pull.md.
2318
+
2319
+ **Prose-first** and **wrongly-REFUSE** are not padding — they are the case
2320
+ which shipped with **enumerate-and-declare** already in its prompt. It missed a
2321
+ shape its own ticket named in passing, because it enumerated from the mechanism
2322
+ instead of the text; and it introduced a regression refusing every `node --test`
2323
+ flag, because it enumerated what the guard should catch and never what it could
2324
+ wrongly refuse.
2325
+
2326
+ The commit-incrementally block is not optional. A member that goes idle mid-task
2327
+ leaves its diff only in the worktree, and the controller cannot reap, replace,
2328
+ or even see it — `worktree-audit.sh`'s committed-vs-uncommitted split is exactly
2329
+ what decides whether a replacement redoes or destroys work. Observed twice in
2330
+ one run.
2331
+
2332
+ **The identity block is what makes `sizing-a-ticket`'s fleet entry reachable.**
2333
+ That skill conditions its heavy-row process on the reader being a fleet member;
2334
+ a solo reader settles the open design choices with its user before planning,
2335
+ while a fleet member's `## Agent Brief` already is that settlement. A member
2336
+ that takes itself for a solo session waits on a user to settle design — a user
2337
+ no unattended member has, so it parks rather
2338
+ than fails. Nothing else you carry says what the member is — an incidental
2339
+ mention of the controller is not a statement that the reader is one of its
2340
+ members. That skill keeps its condition, so a solo session still runs the
2341
+ interactive path; this block is what puts a member on the fleet side of it.
2342
+
2343
+ A member that bails demotes nothing itself; demotion by cause is yours
2344
+ (**Implementer bails before implementing**).
2564
2345
 
2565
2346
  ## Fix the tooling mid-run
2566
2347
 
2348
+ A tooling fix is done when it is re-pinned, written onto the ledger, reported to the maintainer in one line and landed as a PR through the run's own merge queue.
2349
+
2567
2350
  Two members failing the same way is the instruction, not the agents. Fix the file
2568
2351
  during the run — deferring loses the evidence that found it.
2569
2352
 
@@ -2603,49 +2386,10 @@ hold the old text — re-brief only if it changes what they do *now*.
2603
2386
 
2604
2387
  Plan it as a PR the run's own merge queue lands, never as an edit-and-continue. See references/merge-bot.md.
2605
2388
 
2606
- ## Failure handling
2607
-
2608
- | Failure | Response |
2609
- |---|---|
2610
- | SHA not on expected branch | Flag, do not enqueue, report |
2611
- | Implementer bails before implementing | → `needs-triage` if under-specified, `ready-for-human` if it needs human hands or leaves a fork open; drop `in-progress`, comment the cause, release the claim, refill (phase 3) |
2612
- | Implementer blocked or ambiguous *mid-implementation* | Free the slot, `ledger.mjs settle impl-<N> blocked`, leave `in-progress`, report — the ticket is not In flight and waits for a human; the row above is the pre-code bail, not this one |
2613
- | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
2614
- | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — a fix-applier or red-check fixer settles `failed` |
2615
- | Merge bot hits the hold rule | Report `held-behind-#<lower>`, PR stays queued |
2616
- | Merge bot finds the worktree ahead of the PR head **on the local-rebase fallback** | `worktree-diverged-#<pr>`, PR stays queued. Read the stray commit; push-or-discard is yours, and the maintainer's if the evidence cannot settle it |
2617
- | Merge bot finds the head moved after `ready-to-merge` was applied | The label binds to the head's net change, not to one SHA: a proven rebase-carry keeps the label — the bot proceeds and reports `rebase-carry-#<pr>` with the labelled and accepted SHAs, and nothing is dispatched. Any other move is `head-moved-after-label-#<pr>`, PR stays queued, label untouched. Dispatch a **fresh** finisher against the new head — the first audit verified a different tree |
2618
- | Merge bot's gate finds the merge would remove lines `main` gained after the PR's work began (`main-gain-removed:<path>`, exit 1) | Relay `main-gain-removed:<path>-#<pr>` to a human with the hit list and the acknowledgement keys the bot printed. PR stays queued, label untouched, nothing written to the ledger, and no member is dispatched to restore the lines — the removal may be deliberate. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for each hit |
2619
- | Merge bot's gate cannot answer the main-gain check (`main-gain-unanswerable`, exit 2) | Report `main-gain-unanswerable-#<pr>` with what it printed, PR stays queued, label untouched |
2620
- | Merge bot cannot resolve a rebase safely | Stop that PR, report, continue. On a conflict the bot has already appended `conflict-hold:#<pr>` to the PR's row; the tick prints `DISPATCH fix-pr PR#<pr>` and holds the merge until that fix-applier settles. A PR that conflicts before any bot reaches it is the tick's `CONFLICT PR#<pr>` line, whose hold you record |
2621
- | Merge bot's gate refuses on its instrument re-check (`instrument-set-changed` or `instruments-unanswerable`, exit 2) | Report `<reason>-#<pr>` with what it printed, PR stays queued, label untouched. Do not re-run the gate |
2622
- | Merge bot's CI wait reaches its per-PR time bound with the run's `status` still not `completed` | The bot skips that PR and reports `ci-wait-timeout-#<pr>` with the run id and its status. PR stays queued, label untouched |
2623
- | Member silent or truncated | Send to ping or resume — same unit of work; see the state machine below |
2624
- | Member idle with work outstanding | Read the PR first, *then* ping. Idle ≠ done |
2625
- | Member **killed** (spend limit, API error, crash) | Confirm it is dead first — a frozen transcript does not establish that; see below — then new member, new name, prompt carries inherited state |
2626
- | Member **unaccounted** (a live token the tick flags `CHECK-LIVENESS`, or any live token nothing has reported on) | Registry census first: `read history://` once. A row other than `running` → `read agent://<member>` and the artifacts (PR head, worktree, labels), settle the real outcome with the existing vocabulary, and resume a `parked` member with `write agent://<member>` when its work is worth continuing. A `running` row → the mtime discriminator below, two polls: moved means BLOCKED and alive; frozen at both polls **and** no artifact movement → `write proc://<member>/kill`, `ledger.mjs settle <member> killed`, fresh name. Three independent alive-signals — the first poll, the second poll, the artifacts — must all be silent before a kill; the tick settles and kills nothing |
2627
-
2628
- A red PR never silently becomes `ready-to-merge`.
2629
-
2630
- **A frozen transcript does not establish that a member is dead — the discriminator is its scratch dir.** See references/failure-handling.md.
2631
-
2632
- Settle outcome and liveness are different facts, not the same table with two
2633
- spellings. Recovery is a fresh member, fresh name (`impl-<N>-b`,
2634
- `fix-pr-<M>-b`, and for a reviewer the next letter PR M's rows do not carry
2635
- yet) whose prompt states what it inherits.
2636
-
2637
- `hub cancel` leaves a peer hard-aborted and unmessageable, but a `failed` job's peer can stay `idle` and answer normally. No distinct truncated state exists.
2638
-
2639
- Reviewers that went idle on CI recover as a **finisher, not a re-review** once
2640
- commits are pushed. See references/member-lifecycle.md.
2641
-
2642
- Audit every worktree before dispatching replacements with
2643
- `~/.fleet/bin/fleet-run worktree-audit.sh` — it reports each worktree's
2644
- ahead-count and uncommitted files, the committed-vs-uncommitted distinction that
2645
- decides whether a replacement redoes or destroys work.
2646
-
2647
2389
  ## Run ledger
2648
2390
 
2391
+ Write each state change through `ledger.mjs` before you act on it, never by hand: this section is done when no row, filing or ruling lives only in your context.
2392
+
2649
2393
  One git-ignored `.fleet/ledger.md` per run, updated at **every** state change via
2650
2394
  `~/.fleet/bin/fleet-run ledger.mjs` subcommands (`row`, `filed`, `ruled`,
2651
2395
  `check`, `read`, `dispatch`, `settle`, `review`, `drain`, `rotate`). Your context is the least
@@ -2846,20 +2590,173 @@ silent `ok:false` with nothing on stderr. Gate on the field, not on the warning.
2846
2590
  **Write the ledger line before dispatching, not after.** A member that dies
2847
2591
  between spawn and write is invisible — and members die in batches.
2848
2592
 
2849
- ## Report
2593
+ ## Failure handling
2850
2594
 
2851
- One running table, updated as events land:
2595
+ Match the failure to its row in the table below and run that response; where the row says report or flag, stop there.
2852
2596
 
2853
- ```
2854
- #N ticket impl-<N> PR #M fix-pr-<M> label:yes merged
2855
- #N ticket impl-<N> PR #M fix-pr-<M> label:no - red CI
2856
- #N ticket impl-<N> - - - - blocked: SHA off-branch
2857
- ```
2597
+ | Failure | Response |
2598
+ |---|---|
2599
+ | SHA not on expected branch | Flag, do not enqueue, report |
2600
+ | Implementer bails before implementing | → `needs-triage` if under-specified, `ready-for-human` if it needs human hands or leaves a fork open; drop `in-progress`, comment the cause, release the claim, refill (phase 3) |
2601
+ | Implementer blocked or ambiguous *mid-implementation* | Free the slot, `ledger.mjs settle impl-<N> blocked`, leave `in-progress`, report — the ticket is not In flight and waits for a human; the row above is the pre-code bail, not this one |
2602
+ | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
2603
+ | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — a fix-applier or red-check fixer settles `failed` |
2604
+ | Merge bot hits the hold rule | Report `held-behind-#<lower>`, PR stays queued |
2605
+ | Merge bot finds the worktree ahead of the PR head **on the local-rebase fallback** | `worktree-diverged-#<pr>`, PR stays queued. Read the stray commit; push-or-discard is yours, and the maintainer's if the evidence cannot settle it |
2606
+ | Merge bot finds the head moved after `ready-to-merge` was applied | The label binds to the head's net change, not to one SHA: a proven rebase-carry keeps the label — the bot proceeds and reports `rebase-carry-#<pr>` with the labelled and accepted SHAs, and nothing is dispatched. Any other move is `head-moved-after-label-#<pr>`, PR stays queued, label untouched. Dispatch a **fresh** finisher against the new head — the first audit verified a different tree |
2607
+ | Merge bot cannot resolve a rebase safely | Stop that PR, report, continue. On a conflict the bot has already appended `conflict-hold:#<pr>` to the PR's row; the tick prints `DISPATCH fix-pr PR#<pr>` and holds the merge until that fix-applier settles. A PR that conflicts before any bot reaches it is the tick's `CONFLICT PR#<pr>` line, whose hold you record |
2608
+ | Merge bot's gate refuses on its instrument re-check (`instrument-set-changed` or `instruments-unanswerable`, exit 2) | Report `<reason>-#<pr>` with what it printed, PR stays queued, label untouched. Do not re-run the gate |
2609
+ | Merge bot's CI wait reaches its per-PR time bound with the run's `status` still not `completed` | The bot skips that PR and reports `ci-wait-timeout-#<pr>` with the run id and its status. PR stays queued, label untouched |
2610
+ | Member silent or truncated | Send to ping or resume — same unit of work; see the state machine below |
2611
+ | Member idle with work outstanding | Read the PR first, *then* ping. Idle ≠ done |
2612
+ | Member **killed** (spend limit, API error, crash) | Confirm it is dead first — a frozen transcript does not establish that; see below — then new member, new name, prompt carries inherited state |
2613
+ | Member **unaccounted** (a live token the tick flags `CHECK-LIVENESS`, or any live token nothing has reported on) | Registry census first: `read history://` once. A row other than `running` → `read agent://<member>` and the artifacts (PR head, worktree, labels), settle the real outcome with the existing vocabulary, and resume a `parked` member with `write agent://<member>` when its work is worth continuing. A `running` row → the mtime discriminator below, two polls: moved means BLOCKED and alive; frozen at both polls **and** no artifact movement → `write proc://<member>/kill`, `ledger.mjs settle <member> killed`, fresh name. Three independent alive-signals — the first poll, the second poll, the artifacts — must all be silent before a kill; the tick settles and kills nothing |
2858
2614
 
2859
- Plus a queue-depth line: shortlist, supply, whether triage was suggested.
2615
+ ### Recovery
2616
+
2617
+ A red PR never silently becomes `ready-to-merge`.
2618
+
2619
+ **A frozen transcript does not establish that a member is dead — the discriminator is its scratch dir.** See references/failure-handling.md.
2620
+
2621
+ Settle outcome and liveness are different facts, not the same table with two
2622
+ spellings. Recovery is a fresh member, fresh name (`impl-<N>-b`,
2623
+ `fix-pr-<M>-b`, and for a reviewer the next letter PR M's rows do not carry
2624
+ yet) whose prompt states what it inherits.
2625
+
2626
+ `hub cancel` leaves a peer hard-aborted and unmessageable, but a `failed` job's peer can stay `idle` and answer normally. No distinct truncated state exists.
2627
+
2628
+ Reviewers that went idle on CI recover as a **finisher, not a re-review** once
2629
+ commits are pushed. See references/member-lifecycle.md.
2630
+
2631
+ Audit every worktree before dispatching replacements with
2632
+ `~/.fleet/bin/fleet-run worktree-audit.sh` — it reports each worktree's
2633
+ ahead-count and uncommitted files, the committed-vs-uncommitted distinction that
2634
+ decides whether a replacement redoes or destroys work.
2635
+
2636
+ ## Guards
2637
+
2638
+ Each guard here is a check to run before the step it guards: run it, and where it fails, stop and report rather than go on.
2639
+
2640
+ **Verify every reported SHA.** `~/.fleet/bin/fleet-run verify-sha.sh
2641
+ <branch> <sha>` before enqueueing — a member can commit in a nested worktree,
2642
+ leaving the SHA on a stray branch while its report reads normally. Exit codes as
2643
+ `inflight.sh`: `# 0 reachable, 1 not reachable, 2 unanswerable`. Not reachable
2644
+ (exit 1) → flag, do not enqueue, do not return the ticket to the shortlist until the
2645
+ maintainer rules. **Exit 2 is not a verdict** — the question could not be
2646
+ answered, and every cause of it reaches you as one shape: no JSON on stdout at
2647
+ all, the cause on stderr alone. Read that stderr, fix what it names and re-run;
2648
+ escalate if it repeats. Never read exit 2 as `not reachable`, and never record it
2649
+ as a stray commit — the flag and the maintainer's ruling above are what exit 1
2650
+ earns, and spending them on a probe that never answered costs a member its
2651
+ ticket over a failure a re-run would have cleared.
2652
+
2653
+ **Never `--delete-branch` — the merge bot deletes the head branch itself.**
2654
+ `gh pr merge <n> --merge` alone: the flag's local cleanup errors on a `main`
2655
+ held by another worktree, or strands the feature worktree on `main`. After the
2656
+ merge, `delete-merged-branch.sh <pr>` deletes the branch from `origin` and reads
2657
+ the deletion back; `reap.sh` takes the `[gone]` local branch and its worktree.
2658
+ No repo setting is relied on to do it. A branch another open PR still
2659
+ uses as its head or base is kept instead — `branch-kept-#<that PR>` in the bot's
2660
+ report, a deliberate keep and not a failure.
2661
+ The branch-delete step also releases the claim label: it drops `in-progress` from
2662
+ every issue the PR closes.
2663
+
2664
+ **Never force a rebase to start.** No `git clean`, `git checkout .`,
2665
+ `git reset --hard`, `git stash`. Uncommitted changes may exist nowhere else.
2666
+ Non-empty `git status --porcelain -unormal` → stop and report — the explicit
2667
+ mode, never bare `--porcelain`, or `status.showUntrackedFiles = no` reads an
2668
+ empty answer here and licenses the rebase over work this check exists to
2669
+ protect. Stashing empties it either way, so that check and
2670
+ `no-undo-audit.sh` both go quiet on work nothing else holds.
2671
+
2672
+ **Cross-check what members report about their environment.** Wrong often enough
2673
+ to matter, and a confident wrong report from a reviewer flips a verdict.
2674
+
2675
+ **Distrust negative claims hardest.** "Nothing else references this", "the sweep
2676
+ is clean" — most likely false, least likely checked: a grep that found nothing
2677
+ looks like a grep never run. Make members state their search scope. Negative claim
2678
+ vs specific finding with paths → paths win.
2679
+
2680
+ **Members share one filesystem, one docker stack and one process table**, and the
2681
+ failures arrive as *wrong findings*, not errors:
2682
+
2683
+ - **A pattern kill reaches siblings — the implementer, fix-applier and finisher briefs forbid it.** See references/isolation.md.
2684
+
2685
+ **What the victim's output looks like depends on the signal — and one of the cases is a clean green.** See references/isolation.md.
2686
+
2687
+ So **a complete summary block proves the runner survived, not that the run was
2688
+ uncontaminated.** Scrutinize reds, short counts *and* greens from inside the
2689
+ incident window; a killed **baseline** compared against a clean mutant is a
2690
+ wrong measurement that reads exactly like a real result.
2691
+
2692
+ **The command line is no partition either — not reliably.** See references/isolation.md.
2693
+
2694
+ Members report a stalled run to the controller instead of pattern-killing it,
2695
+ and the controller re-checks any measurement taken in the window.
2696
+
2697
+ **Do not guess the victim — the blast radius is the machine, not the Pull.**
2698
+ In that incident the controller reasoned from dispatch scope to "almost
2699
+ certainly `impl-<N>`" and told the maintainer so; the named member then proved
2700
+ it was not the victim (it had never invoked those files standalone, and its
2701
+ mutation baselines post-dated the window). Idle members of *previous* runs,
2702
+ other omp sessions on the same machine, and the maintainer's own shell are
2703
+ all `pkill -f` targets and none of them appear in your ledger. Warn every live
2704
+ member, record the incident as unattributed, and re-check measurements by
2705
+ timestamp rather than by who you think was running.
2706
+
2707
+ - **A warning acted on silently is indistinguishable from one that never
2708
+ arrived.** The same incident: the controller's warning DID reach the member,
2709
+ which re-ran, found nothing changed, and said nothing — correctly reading
2710
+ "send once, never re-send" as covering it. The controller then had to spend a
2711
+ round trip asking whether its own outbox was lossy. So the briefs say that
2712
+ **confirmation state includes warnings received and acted on, even
2713
+ when the outcome is no change** — one line, in the report the member already
2714
+ owes. That is the cheap half of the *never read silence as assent* rule, paid
2715
+ by the member rather than by the controller's guesswork.
2716
+
2717
+ - **Specialist tree isolation is `review-and-fix.md`'s job — do not restate it.**
2718
+ It owns the object-store rule, the two-tree split, snapshot provisioning, and
2719
+ which suites a snapshot cannot validly run. Your only duty is to *not*
2720
+ contradict it.
2721
+ - **Filesystem isolation is not stack isolation.** A private copy of the
2722
+ tree and a test command solve different problems; the compose project
2723
+ name comes from the environment, not the working directory, so three
2724
+ agents on three snapshots still collide on one postgres. "I'm on my own
2725
+ copy" is exactly the intuition that skips the command — say both, every
2726
+ time. Which command depends on the audience: a member in a worktree
2727
+ uses `./agent-test`; a specialist on a snapshot does not, and takes the
2728
+ one `review-and-fix.md` hands out. Which runner the worktree holds
2729
+ decides why: the runner a claim writes is untracked, so a `git archive`
2730
+ snapshot never carries it; one the repository tracks does ride along,
2731
+ but no claim exported ports into it — its isolation is whatever that
2732
+ repository built, not one triple per snapshot. See
2733
+ references/isolation.md.
2734
+ - **Scratchpad paths need two levels — the member's own partition, then one
2735
+ directory per child it dispatches — and nothing outside them.** An
2736
+ implementer partitions at `<scratch>/impl-<N>/`; the review side's partition
2737
+ is `<scratch>/pr<N>/…`, which the review core creates itself, so a review
2738
+ runner is handed the scratch root, never that partition; any member that
2739
+ dispatches a child writes an absolute directory under its own partition into
2740
+ that child's prompt, one per child and never shared, and a child never
2741
+ derives its own. Finding ids restart at 1 every review, so two fix-appliers
2742
+ on different PRs both reach for `unv1`; one
2743
+ agent overwrote a sibling's `package.json`, and a probe built a git repo at
2744
+ the *checkout root*. Read from the object store at a pinned ref, write only
2745
+ under your own path. See references/isolation.md.
2746
+ - **IDE/harness diagnostics attribute by bare filename, with no path.** **Never
2747
+ relay a diagnostic without reproducing it in that member's specific worktree**
2748
+ (re-run the check that raised it from there): probe copies carry the real
2749
+ tree's filenames, so a sibling's throwaway mutation reads exactly like a live
2750
+ worktree's error.
2751
+ See references/isolation.md.
2752
+
2753
+ Suspect a neighbour before a member's own diff — for unexplained failures, and
2754
+ equally for any **finding** that came from reading source.
2860
2755
 
2861
2756
  ## Red flags
2862
2757
 
2758
+ Stop when a thought of yours matches one of these, and act on the line it carries instead.
2759
+
2863
2760
  - "Fork the controller so the member has context" → fork inherits everything.
2864
2761
  - "This member finished, send it the next ticket" → resumes its transcript.
2865
2762
  - "The name is cosmetic" → the name is the ledger token and the hub address.
@@ -2889,3 +2786,17 @@ Plus a queue-depth line: shortlist, supply, whether triage was suggested.
2889
2786
  about uncommitted files, and the reviewer may still be in there.
2890
2787
  - "Reap once at the end of the run" → stale worktrees make phase 0 read merged
2891
2788
  tickets as taken, so the starvation compounds with every Pull.
2789
+
2790
+ ## Report
2791
+
2792
+ Report as one running table, updated as events land, and end it with the queue-depth line.
2793
+
2794
+ One running table, updated as events land:
2795
+
2796
+ ```
2797
+ #N ticket impl-<N> PR #M fix-pr-<M> label:yes merged
2798
+ #N ticket impl-<N> PR #M fix-pr-<M> label:no - red CI
2799
+ #N ticket impl-<N> - - - - blocked: SHA off-branch
2800
+ ```
2801
+
2802
+ Plus a queue-depth line: shortlist, supply, whether triage was suggested.