@feigi/fleet-ctl 0.0.0 → 3.16.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. package/agents/{fleet-implementer.agent.md → fleet-implementer-slow-high.agent.md} +23 -2
  2. package/agents/fleet-implementer-slow-medium.agent.md +231 -0
  3. package/agents/fleet-implementer-smol-high.agent.md +231 -0
  4. package/agents/{fleet-implementer-alt.agent.md → fleet-implementer-task-high.agent.md} +23 -2
  5. package/agents/fleet-implementer-task-max.agent.md +231 -0
  6. package/agents/fleet-review-comments.agent.md +4 -2
  7. package/agents/fleet-review-correctness.agent.md +2 -1
  8. package/agents/fleet-review-runner.agent.md +14 -10
  9. package/agents/fleet-review-silent-failure.agent.md +4 -3
  10. package/agents/fleet-review-simplify.agent.md +2 -1
  11. package/agents/fleet-review-snapshot.agent.md +2 -1
  12. package/agents/fleet-review-test-run.agent.md +29 -0
  13. package/agents/fleet-review-tests.agent.md +10 -5
  14. package/agents/fleet-review-types.agent.md +4 -2
  15. package/agents/fleet-review-verifier.agent.md +4 -3
  16. package/commands/review-and-fix.md +7 -6
  17. package/commands/run-merge-bot.md +14 -4
  18. package/package.json +4 -2
  19. package/scripts/agent-test.test.mjs +36 -32
  20. package/scripts/ambient-git-vars-mjs-prose.test.mjs +23 -13
  21. package/scripts/apply-ruleset.test.mjs +4 -3
  22. package/scripts/arg-header-probes-prose.test.mjs +1 -0
  23. package/scripts/arg.test.mjs +18 -18
  24. package/scripts/board-cli.test.mjs +18 -21
  25. package/scripts/board-identity.test.mjs +9 -9
  26. package/scripts/board-liveness-banner.test.mjs +6 -6
  27. package/scripts/board-prev-shape.test.mjs +12 -13
  28. package/scripts/board-tryparse-null.test.mjs +7 -7
  29. package/scripts/board.mjs +4 -7
  30. package/scripts/board.test.mjs +57 -61
  31. package/scripts/candidates.test.mjs +228 -17
  32. package/scripts/ci-completes-premise-prose.test.mjs +1 -1
  33. package/scripts/ci-state-prose.test.mjs +2 -2
  34. package/scripts/ci-state.mjs +389 -187
  35. package/scripts/ci-state.test.mjs +458 -165
  36. package/scripts/claim-lifecycle.test.mjs +2 -1
  37. package/scripts/claim-ticket.test.mjs +35 -34
  38. package/scripts/closing-keyword-prose.test.mjs +1 -1
  39. package/scripts/cockpit-tick-nonblocking.test.mjs +8 -8
  40. package/scripts/compute-board.mjs +13 -3
  41. package/scripts/compute-board.test.mjs +64 -1
  42. package/scripts/compute-spend.mjs +46 -8
  43. package/scripts/compute-spend.test.mjs +64 -10
  44. package/scripts/cross-repo-citation-prose.test.mjs +18 -19
  45. package/scripts/delete-merged-branch.sh +218 -0
  46. package/scripts/delete-merged-branch.test.mjs +576 -0
  47. package/scripts/derive-testcmd.sh +18 -7
  48. package/scripts/derive-testcmd.test.mjs +9 -8
  49. package/scripts/diff-stats.mjs +2 -2
  50. package/scripts/diff-stats.test.mjs +7 -11
  51. package/scripts/dispatch-block-golden-prose.test.mjs +111 -6
  52. package/scripts/dispatch-block-pins-prose.test.mjs +5 -5
  53. package/scripts/dispositions-check.mjs +507 -0
  54. package/scripts/dispositions-check.test.mjs +843 -0
  55. package/scripts/dispositions-gate-prose.test.mjs +114 -0
  56. package/scripts/drop-merged-label.test.mjs +3 -4
  57. package/scripts/exec-stub.mjs +93 -0
  58. package/scripts/exec-stub.test.mjs +69 -0
  59. package/scripts/filing-bar-seat-prose.test.mjs +1 -1
  60. package/scripts/finisher-test-verdict-prose.test.mjs +102 -0
  61. package/scripts/fix-applier-correction-rules-prose.test.mjs +11 -10
  62. package/scripts/fleet-bootstrap +5 -20
  63. package/scripts/fleet-bootstrap.test.mjs +75 -0
  64. package/scripts/fleet-heartbeat.mjs +2 -2
  65. package/scripts/fleet-provenance +15 -24
  66. package/scripts/fleet-provenance.test.mjs +86 -12
  67. package/scripts/fleet-run.test.mjs +5 -5
  68. package/scripts/fleet-state.mjs +33 -11
  69. package/scripts/fleet-state.test.mjs +90 -3
  70. package/scripts/fleet-tick.mjs +346 -70
  71. package/scripts/fleet-tick.test.mjs +566 -16
  72. package/scripts/force-with-lease-reason-prose.test.mjs +1 -1
  73. package/scripts/frontmatter-check.mjs +3 -2
  74. package/scripts/frontmatter-check.test.mjs +6 -6
  75. package/scripts/immutable-body-claim-prose.test.mjs +53 -262
  76. package/scripts/implementer-model-tier.test.mjs +98 -506
  77. package/scripts/inflight.test.mjs +18 -127
  78. package/scripts/is-cli.mjs +26 -0
  79. package/scripts/is-cli.test.mjs +99 -0
  80. package/scripts/json.test.mjs +3 -3
  81. package/scripts/ledger-dispatch.test.mjs +368 -7
  82. package/scripts/ledger-grammar.mjs +85 -1
  83. package/scripts/ledger-grammar.test.mjs +86 -1
  84. package/scripts/ledger-read-require-file.test.mjs +7 -7
  85. package/scripts/ledger-rotate.test.mjs +142 -0
  86. package/scripts/ledger.mjs +181 -17
  87. package/scripts/ledger.test.mjs +12 -130
  88. package/scripts/main-checkout.mjs +312 -0
  89. package/scripts/main-checkout.test.mjs +332 -0
  90. package/scripts/member-outcomes-header.test.mjs +3 -3
  91. package/scripts/member-outcomes.mjs +4 -5
  92. package/scripts/member-outcomes.test.mjs +92 -18
  93. package/scripts/member-prompt-prose.test.mjs +17 -13
  94. package/scripts/member-record.mjs +8 -3
  95. package/scripts/member-record.test.mjs +5 -5
  96. package/scripts/member-write-guard.mjs +5 -5
  97. package/scripts/member-write-guard.test.mjs +6 -3
  98. package/scripts/no-undo-audit.sh +24 -21
  99. package/scripts/no-undo-audit.test.mjs +9 -13
  100. package/scripts/pointer-target-prose.test.mjs +1 -1
  101. package/scripts/pr-overlap.test.mjs +6 -9
  102. package/scripts/prompt-renderer.mjs +10 -9
  103. package/scripts/prose-pin.mjs +10 -11
  104. package/scripts/prove-merge.test.mjs +3 -3
  105. package/scripts/quiet-payload-prose.test.mjs +1 -1
  106. package/scripts/reap.test.mjs +3 -4
  107. package/scripts/release-label-split-prose.test.mjs +17 -2
  108. package/scripts/release-ticket.test.mjs +35 -44
  109. package/scripts/review-core-cwd-isolation.test.mjs +7 -6
  110. package/scripts/review-core-reads.test.mjs +1 -1
  111. package/scripts/review-core-scratch-refusal.test.mjs +64 -0
  112. package/scripts/review-core-shared-test-run.test.mjs +238 -0
  113. package/scripts/review-core-snapshot-path.test.mjs +59 -12
  114. package/scripts/review-core-specialist-scratch.test.mjs +12 -10
  115. package/scripts/review-core-testcmd.test.mjs +76 -45
  116. package/scripts/review-core-unrun.test.mjs +154 -168
  117. package/scripts/review-core.mjs +250 -56
  118. package/scripts/review-eval.mjs +11 -4
  119. package/scripts/review-host-fixture.mjs +12 -3
  120. package/scripts/review-in-run-retry.test.mjs +27 -3
  121. package/scripts/review-runner-spawns.test.mjs +5 -3
  122. package/scripts/review-runner.test.mjs +14 -3
  123. package/scripts/review-tier-audit.test.mjs +1 -1
  124. package/scripts/run-merge-bot-prose.test.mjs +29 -6
  125. package/scripts/scratch-partition-invariant-prose.test.mjs +1 -1
  126. package/scripts/section-between-guard-prose.test.mjs +4 -3
  127. package/scripts/select-dimensions.test.mjs +1 -1
  128. package/scripts/shell-traps-prose.test.mjs +6 -9
  129. package/scripts/shortlist.mjs +4 -1
  130. package/scripts/shortlist.test.mjs +30 -16
  131. package/scripts/snapshot-repo.test.mjs +177 -4
  132. package/scripts/stash-prohibition-prose.test.mjs +1 -1
  133. package/scripts/temp-dir.mjs +47 -0
  134. package/scripts/tier-check.mjs +95 -28
  135. package/scripts/tier-check.test.mjs +131 -29
  136. package/scripts/tier-outcomes-header.test.mjs +11 -54
  137. package/scripts/tier-outcomes.mjs +34 -12
  138. package/scripts/tier-outcomes.test.mjs +157 -4
  139. package/scripts/tier-roles.mjs +118 -29
  140. package/scripts/tier-roles.test.mjs +226 -61
  141. package/scripts/tracker-block-copy-prose.test.mjs +3 -3
  142. package/scripts/verify-sha.test.mjs +4 -5
  143. package/scripts/watcher-degraded-block.test.mjs +5 -8
  144. package/scripts/within-run-pair-prose.test.mjs +43 -75
  145. package/scripts/worktree-audit.test.mjs +2 -1
  146. package/skills/next-ticket/SKILL.md +2 -2
  147. package/skills/run-team/SKILL.md +433 -303
  148. package/skills/run-team/references/ci-and-staleness.md +7 -6
  149. package/skills/run-team/references/correction-tickets.md +3 -3
  150. package/skills/run-team/references/isolation.md +1 -1
  151. package/skills/sizing-a-ticket/SKILL.md +8 -8
  152. package/scripts/tier-guard-gate-prose.test.mjs +0 -216
@@ -248,8 +248,7 @@ phase, or in any later one, asks the maintainer which tickets to take.
248
248
  lands the rules THIS run needs and nothing pulls them. Measured twice — 57
249
249
  commits stale in one run, 20 in another, the second shipping every dispatch
250
250
  prompt without two rules that had merged the day before. Silent by
251
- construction: stale text reads as authoritative, and the tier guard's own
252
- floor is re-derived from a stale `tier-outcomes.tsv` at the same time.
251
+ construction: stale text reads as authoritative.
253
252
 
254
253
  **Pin the instruments, after that fast-forward and before anything reads
255
254
  them, from this main checkout.** `~/.fleet/bin/fleet-run instruments.sh --pin`
@@ -268,6 +267,28 @@ phase, or in any later one, asks the maintainer which tickets to take.
268
267
  the tree once is the whole cross-workspace contract; never dispatch a
269
268
  member into a run whose phase-0 pin refused.
270
269
 
270
+ **Record the main-checkout baseline in the same step, right after the
271
+ pin.** `~/.fleet/bin/fleet-run main-checkout.mjs --record` writes
272
+ `.fleet/main-checkout.sha`: the main checkout's `git status --porcelain
273
+ -uall` entries plus a content hash of every path they name. Your own
274
+ uncommitted work is fine — it is in the baseline and holds nothing. From
275
+ then on every `fleet-tick.mjs` compares the main checkout against it and
276
+ holds dispatch on any change (#2210): the backstop for the stray member
277
+ writes `member-write-guard` cannot see — an `eval` cell, a `bash` that
278
+ `cd`s or `git -C`s into this checkout. `.fleet/`, `.worktrees/` and
279
+ `.agent-brain/` are gitignored and never trip it. Nor does this run's own
280
+ bookkeeping: `docs/metrics/tier-outcomes.tsv` and
281
+ `docs/metrics/member-outcomes.tsv`, which you write mid-run, are left out
282
+ by name — anything else under `docs/metrics/` still trips it. **The same
283
+ command is the clear, and it overwrites; it never compares.** On `MAIN-CHECKOUT-DIRTY`
284
+ the maintainer resolves the stray paths FIRST — inspect, keep or remove
285
+ them — and only then re-runs `--record`; re-recording over unresolved paths
286
+ certifies them. **Never re-record over `MAIN-CHECKOUT-UNKNOWN`**: that
287
+ walks the run from "could not look" to "certified clean" in one step, so
288
+ `--record` itself refuses over a baseline it cannot read and on any git
289
+ read that fails. `main-checkout.mjs --check` prints the same answer
290
+ without a tick.
291
+
271
292
  **Check the merge gate against its spec, once the fast-forward has put the
272
293
  ratified spec in front of you.** Where the workspace checks a ruleset spec
273
294
  in, `.github/scripts/apply-ruleset.sh --check` compares it to the live gate
@@ -316,6 +337,30 @@ phase, or in any later one, asks the maintainer which tickets to take.
316
337
  `~/.omp/agent/sessions/<encoded-cwd>/<ISO>_<uuid>` (the directory, never
317
338
  the `.jsonl` file of the same name beside it).
318
339
 
340
+ **Rotate the ledger before the fold-in below and before shortlisting —
341
+ every run, whatever way the previous one ended.** One ledger per run:
342
+ `~/.fleet/bin/fleet-run ledger.mjs rotate` moves the previous run's
343
+ `.fleet/ledger.md` byte-for-byte to `.fleet/ledger.<UTC
344
+ YYYY-MM-DDTHHMMSSZ>.md` and leaves none behind, so this run's first write
345
+ starts the empty skeleton. Nothing is carried forward — no row, exclusion,
346
+ `## Filed` or `## Ruled` entry — so an unchecked `impl-` row a prior run
347
+ left behind can no longer hold this run's tick. What an unclean end left in
348
+ flight comes back through the ordinary per-run path: open PRs through the
349
+ fold-in below, `behind-pr:`/`behind-issue:` exclusions through phase 1's
350
+ collision and sequence checks, and a killed member's ticket through a new
351
+ member under a new name. An exclusion that expires with the run that wrote
352
+ it (`deferred-to-session-end` and its like) must be restated if it still
353
+ holds. No ledger is exit 0, nothing to rotate. It refuses — exit 2,
354
+ nothing moved — when the stamped archive name already exists, and while
355
+ the heartbeat mark beside the ledger is still beating, naming the last
356
+ beat and when it would count as stalled; a stalled mark, a recorded
357
+ `--stop`, or no mark at all lets it rotate. **The guard proves "not
358
+ beating", never "dead":** a previous controller that is alive but busy
359
+ outside its heartbeat hold for longer than its recorded interval reads as
360
+ stalled, and its ledger is rotated out from under it. Run the rotation
361
+ before this run's own first tick or beat, either of which writes the mark
362
+ the guard reads. Older archives, hand-named ones included, are left alone.
363
+
319
364
  **Fold in every PR a prior run left open, before shortlisting.** A chore PR
320
365
  carrying that run's own metrics, or ticket work whose review was deferred —
321
366
  both are reviewable work no member otherwise picks up, because the Shortlist
@@ -597,35 +642,6 @@ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
597
642
 
598
643
  No sizing agent here. `sizing-a-ticket` picks the *process path*, and that is
599
644
  phase 2's call, after the ticket is claimed.
600
-
601
- **Class?** Second judgement off the same read, so it costs no extra tokens.
602
- Stale docs, wrong comments, bad citations → `class=correction`; everything
603
- else → `class=routine`. **Torn → correction**: a misjudged routine is a
604
- missed saving, a misjudged correction runs the one class that demonstrably
605
- ships new wrong claims.
606
-
607
- **The class no longer selects a model tier** — the phase-2 guard fired on
608
- 2026-08-16 and every class now dispatches at the session's tier. It still
609
- earns its read: it selects the **correction-ticket discipline** phase 2
610
- hands the implementer (settle every restated claim against the tree, keep
611
- the diff to the ticket's stated size, no positional references, never a
612
- count in prose, a settling command re-run and written inline for every
613
- claim that goes into the commit or PR body, and literal text grepped with
614
- `-F`, its zero trusted only after the same command, with the same flags,
615
- finds a known match), it partitions
616
- `docs/metrics/tier-outcomes.tsv`, and it is what any future tier
617
- control would be drawn from. A row with no class is still `class=unknown`,
618
- never a guess.
619
-
620
- The correction exception was always a **precaution, not a measurement.**
621
- references/correction-tickets.md records four tickets in one run each
622
- shipping a *new* wrong claim, and blames the ticket's framing and
623
- unasked-for prose — **not** implementer capability; it measures no tier at
624
- all. That reasoning is why the discipline survives the tiering that used to
625
- accompany it.
626
-
627
- Record the class in the Pull's ledger row (step 7); phase 2 reads it for
628
- the discipline, no longer for the tier.
629
645
  4. **Collision scan against open PRs and live branches** — the ticket is an
630
646
  *un-implemented issue* with no diff, so infer its target files from the brief
631
647
  (the paths it names) and compare them against each open PR's `gh pr diff <PR>
@@ -644,7 +660,7 @@ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
644
660
  two independent tickets.
645
661
  6. **Claim** — `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer
646
662
  --apply` (below). Exit 2 → treat it as taken, next entry.
647
- 7. **Row, then dispatch** — `ledger.mjs row <N> "impl-<N> · class=… [· tier=alt]"`,
663
+ 7. **Row, then dispatch** — `ledger.mjs row <N> "impl-<N>[ · tier=<cell>]"`,
648
664
  then phase 2 at once: claim what you are about to dispatch;
649
665
  dispatch what you have just claimed.
650
666
 
@@ -848,7 +864,7 @@ fresh and never a wake of one that already ran. Admission is per slot and
848
864
  never batched, so there is nothing to hand a freed slot its next ticket but
849
865
  the next Pull.
850
866
 
851
- a Pull dispatches its member with one more `task` call — definition `fleet-implementer`, or `fleet-implementer-alt` on every 5th Pull; name `impl-<N>`; in the background, so its report arrives on its own.
867
+ a Pull dispatches its member with one more `task` call — `agent` the definition `ledger.mjs dispatch` printed for it (below); name `impl-<N>`; in the background, so its report arrives on its own.
852
868
 
853
869
  **No workpool, and no kernel-resident handle.** A pool's only refill virtue —
854
870
  handing a queued item to a freed worker without a controller turn — is exactly
@@ -870,16 +886,21 @@ released by the end-of-run sweep rather than by a member that did the work.
870
886
  **Record the dispatch before you make it.** `ledger.mjs row` wrote the row at
871
887
  the Pull's step 7; `~/.fleet/bin/fleet-run ledger.mjs dispatch <N> impl-<N>`
872
888
  then marks `impl-<N>` live on it and in `## Dispatched`, and the call follows.
873
- Live implementers are the `impl-` tokens with no `=<outcome>` — the tick reads
874
- that count off the ledger, and nobody states it. `dispatch` refuses once the
875
- run is draining: drain stops supply.
889
+ Its JSON carries `agent`, the definition that call names — read it off that
890
+ output, never recall it. Live implementers are the `impl-` tokens with no
891
+ `=<outcome>` — the tick reads that count off the ledger, and nobody states
892
+ it. `dispatch` refuses once the
893
+ run is draining: drain stops supply. It also refuses a row whose `tier=`
894
+ names no single definition — two different values, or one that is not a
895
+ definition suffix — or names one with no `agents/<definition>.agent.md`,
896
+ before the member is live; fix the row with `row` first.
876
897
 
877
898
  **The prompt carries only what varies.** Everything shared — the
878
899
  unattended-member block, the `edit`/`read` absolute-path rule (#1727), the
879
900
  issue re-read and re-derive backstop, commit incrementally, no `git stash`, the
880
901
  shared `eval` kernel (#1447), enumerate-and-declare, sizing and the PR steps —
881
- is the body of `agents/fleet-implementer.agent.md`, byte-identical in
882
- `agents/fleet-implementer-alt.agent.md`, and each harness injects it as the
902
+ is the body of every `agents/fleet-implementer-<cell>.agent.md`, byte-identical
903
+ across all of them, and each harness injects it as the
883
904
  member's system prompt. Never re-paste it. The prompt fills that body's
884
905
  placeholders — the ticket number, the worktree abs path and branch
885
906
  (`<abs-path>`, `<branch>`), the scratch path `<scratch>/impl-<N>/`, and the
@@ -888,8 +909,7 @@ comment or the issue body, whichever carries the brief, and its `Out of
888
909
  scope`, pasted verbatim from the Pull's own read. Beyond those it carries only
889
910
  the lines **Rules that fail silently** above say every dispatch prompt
890
911
  carries — the report is a message, reports are not acknowledged, the suite
891
- runs in the foreground — the class's correction-ticket discipline when
892
- `class=correction`, and a `staleness.mjs` **could not check** verdict with its
912
+ runs in the foreground — and a `staleness.mjs` **could not check** verdict with its
893
913
  reason when the Pull got one, so the member's own re-derive step knows the
894
914
  controller's probe could not look.
895
915
 
@@ -919,9 +939,10 @@ merely-quiet member's silence never does. A confirmed-dead member recovers
919
939
  exactly as the Member-killed row says — new member, new name, the SAME ticket —
920
940
  never a demotion.
921
941
 
922
- **Dispatch every implementer as `agent: "fleet-implementer"`, and still
923
- omit `model` on the `task` call, whatever the class.** The tier now lives in that
924
- definition's frontmatter (`agents/fleet-implementer.agent.md`), which is what an
942
+ **Dispatch every implementer with the `agent` that `ledger.mjs dispatch`
943
+ printed, and still omit `model` on the `task` call.** The
944
+ tier lives in that definition's frontmatter (`agents/fleet-implementer-<cell>.agent.md`;
945
+ `slow-high`, the policy cell, for a row with no `tier=`), which is what an
925
946
  omitted `model` takes first — the session's tier applies only when the definition
926
947
  names none, and a member dispatched with `model` set does not get the declared
927
948
  tier back. Omitting `model` is therefore still the mechanism; what changed is
@@ -932,9 +953,11 @@ spend classifier and `member-outcomes.mjs` read it.
932
953
  **After every Pull's dispatch, run the tier check — a scripted step, never a
933
954
  prose reminder.** `~/.fleet/bin/fleet-run tier-check.mjs --batch <path-to-batch.json>`
934
955
  judges the implementer just dispatched on the ledger's terms. The definition it
935
- should have run under comes off its ticket row's `tier=` token: none means
936
- `fleet-implementer`, `tier=<x>` means `fleet-implementer-<x>` (`tier=alt` →
937
- `fleet-implementer-alt`). It fails the member two ways, one line each —
956
+ should have run under comes off its ticket row's `tier=` token: none means the
957
+ policy cell, `fleet-implementer-slow-high`; `tier=<cell>` means
958
+ `fleet-implementer-<cell>` — the same mapping `ledger.mjs dispatch` prints its
959
+ `agent` from, so a call that names the printed `agent` passes this half. It
960
+ fails the member two ways, one line each —
938
961
  `member: dispatched <agent>, expected <definition>` when its transcript says
939
962
  it was dispatched as anything else (a generic `task` dispatch fails even when
940
963
  its model happens to match), and `member: declared <m>/<l> resolved <m>/<l>`
@@ -943,21 +966,39 @@ declares. The verdict lands on the ledger either way, written by the check
943
966
  itself: exit 0 appends `tier-ok=impl-<N>:<definition>` to the row, once
944
967
  however often it runs; exit 1 runs `ledger.mjs settle impl-<N> tier-mismatch`
945
968
  — or, for a member already settled another way, which `settle` will not
946
- re-settle, appends `tier-mismatch=impl-<N>:<definition>` instead.
969
+ re-settle, appends `tier-mismatch=impl-<N>:<definition>` instead. Exit 3 is
970
+ the third verdict, `tier-unverifiable=impl-<N>:no-transcript`, appended once
971
+ for a member settled `killed` or `released` anywhere on the ledger — a row
972
+ or `## Dispatched` — whose `session` names an existing directory holding no
973
+ `<member>.jsonl`: a dispatch that failed before a transcript was written. It
974
+ says nothing about the tier and only clears the unchecked hold. Exit 2
975
+ writes nothing — a usage error, which includes a LIVE member with no
976
+ transcript; a member settled `PR#M`, `bailed` or `tier-mismatch` with none,
977
+ which ran, so the `session` is the wrong directory — pass the one that
978
+ dispatched it; a session directory that cannot be searched; and a `session`
979
+ that is omitted, empty, or not an existing directory, live member or settled.
980
+ A batch holding both a mismatch and an unverifiable member exits 1.
947
981
 
948
982
  **The tick holds the next Pull until that verdict exists.** Dispatching the
949
983
  next member on top of an unchecked or mismatched dispatch multiplies whatever
950
984
  silently degraded. The tick prints `HOLD (tier unchecked impl-<N>)` for the
951
- newest `impl-` member of a ticket whose row carries neither verdict, whether
952
- that member is still running or already settled `bailed`, `killed` or
953
- `released`, and `HOLD (tier mismatch impl-<N>)` for a mismatched one. Only the
954
- newest member counts, so a replacement (`impl-<N>-b`) is what clears a
955
- mismatch — and is then owed its own check. The tick never reads a
985
+ newest `impl-` member of a ticket whose row carries none of the three
986
+ verdicts, whether that member is still running or already settled `bailed`,
987
+ `killed` or `released`, and `HOLD (tier mismatch impl-<N>)` for a mismatched
988
+ one. Only the newest member counts, so a replacement (`impl-<N>-b`) is what
989
+ clears a mismatch — and is then owed its own check. The tick never reads a
956
990
  transcript: clear an unchecked hold by running the check on that member with
957
- `session`, which works after it has settled too, because its
958
- `<session>/<member>.jsonl` is written at dispatch. Clear a mismatch by fixing
959
- the definition or the dispatch and dispatching the replacement at the right
960
- tier.
991
+ `session`. A settled member's check works only when its transcript exists;
992
+ without one, the verdict is `tier-unverifiable` for a member settled `killed`
993
+ or `released`, and exit 2 naming the wrong session for any other. Clear a
994
+ mismatch by fixing the definition or the dispatch and dispatching the
995
+ replacement at the right tier.
996
+
997
+ **Run the check right after the dispatch, and never reinstall the plugin or
998
+ change `modelRoles` while any member is unchecked.** The check reads the
999
+ installed definition and the live `modelRoles` at check time, not at
1000
+ dispatch time, so a late check judges a member against a tier it was never
1001
+ dispatched under.
961
1002
 
962
1003
  **The batch file is a JSON array, one entry per dispatched member** — under
963
1004
  Pull, a batch of one, the member just dispatched: `{member, session}`.
@@ -985,17 +1026,23 @@ ADR 0014).
985
1026
 
986
1027
  Before the run's first dispatch run `~/.fleet/bin/fleet-run tier-roles.mjs
987
1028
  --check`; exit 1 names every definition whose `model:` is not a route,
988
- every unset `modelRoles.<role>` a definition needs, and every
989
- `task.agentModelOverrides` entry that would shadow a fleet definition,
1029
+ every unset `modelRoles.<role>` a definition needs, every definition whose
1030
+ `:<level>` its role's target does not run at (omp's model catalog — omp
1031
+ would clamp it silently), every
1032
+ `task.agentModelOverrides` entry that would shadow a fleet definition, and
1033
+ an `--agents` directory holding no `*.agent.md` definition,
990
1034
  prints the exact remedy, and **stops the run** before any member is
991
1035
  dispatched — the fleet reads that config and never writes it (ADR 0003).
992
1036
 
993
- **Every 5th Pull by ledger count goes at the alternate tier.** Count the `impl-`
1037
+ **Every 5th Pull by ledger count goes at an exploration cell.** Count the `impl-`
994
1038
  rows in `.fleet/ledger.md` at Pull time; the Pull that creates row 5, 10, 15 …
995
- dispatches `agent: "fleet-implementer-alt"` and records
996
- `tier=alt` in the row, and a replacement inherits the row's tier. The
997
- assignment rolls to the next Pull when the pulled ticket is `class=correction`
998
- or another open ticket sequences after it — a ticket the rest of the run
1039
+ records `tier=<cell>` in the row, and a replacement inherits the row's tier —
1040
+ written at the Pull's step 7, ahead of `ledger.mjs dispatch`, which reads it
1041
+ and prints `fleet-implementer-<cell>` as the `agent` to dispatch. Until the
1042
+ router draws the cell (spec 2026-09-28 § 2), `<cell>` is `task-high` — the
1043
+ retired alternate tier's own `@task:high` route. The
1044
+ assignment rolls to the next Pull when another open ticket sequences after
1045
+ it — a ticket the rest of the run
999
1046
  depends on. Do not tell the member it is a control: a member that
1000
1047
  knows it is being measured is not measuring the same thing.
1001
1048
 
@@ -1006,9 +1053,12 @@ ledger, not your memory, is what still holds the count after a compaction.
1006
1053
 
1007
1054
  **Do not label it anywhere — the dispatch record already carries it.** The
1008
1055
  pairing is a query over `docs/metrics/member-outcomes.tsv` (the exact awk sits
1009
- in that file's header): a `session` that ran BOTH implementer definitions at
1010
- DIFFERENT `model`s — one member whose `subagent_type` is
1011
- `fleet-implementer-alt`, another whose is `fleet-implementer`. That column is
1056
+ in that file's header): a `session` that ran BOTH pre-cutover implementer
1057
+ definitions at DIFFERENT `model`s — one member whose `subagent_type` is
1058
+ `fleet-implementer-alt`, another whose is `fleet-implementer`. Neither
1059
+ definition is dispatched any more, so the query counts pre-cutover history
1060
+ only: a session whose implementers ran as `fleet-implementer-<cell>` is not in
1061
+ it until #2133 replaces it with the per-cell readout. That column is
1012
1062
  the record of what each member was dispatched AS, scraped like every other
1013
1063
  column, so it survives the file's regeneration and mislabels no historical row
1014
1064
  — a pre-rule session carries no such dispatch to find. A hand-set column would
@@ -1032,27 +1082,6 @@ tier would then be confounded with calendar date and therefore with prompt
1032
1082
  evolution, which is exactly the state #864 documents and the reason the rows
1033
1083
  already on disk cannot answer the question they were collected for.
1034
1084
 
1035
- **`class=routine` → `sonnet` was REVERTED on 2026-08-16, by the guard below
1036
- firing.** Both halves were met on the accumulated `docs/metrics/tier-outcomes.tsv`:
1037
- the floor (8 `class=routine` PRs spanning 3 distinct `run_date`s) and the trigger
1038
- (2 rows carrying `closed_own_ticket` `no` — PR #452, which regressed the exact
1039
- defect its ticket existed to remove, and PR #466, which emitted invalid JSON in
1040
- the very payload its three tickets existed to make truthful). Per the guard's own
1041
- wording this reverts **`class=routine`**, never the rule wholesale: the Pull still
1042
- records the class, it still governs the correction-ticket discipline, and it is
1043
- still what a future control would be drawn from.
1044
-
1045
- **Read the counter-evidence before restoring it.** Recount from the file before
1046
- citing it — these figures are a snapshot, not a live count, and a doc-only
1047
- append lands a row without touching this paragraph. **As of 2026-08-28, 103
1048
- rows:** the file holds 66 `class=routine` PRs across 14 distinct `run_date`s,
1049
- so the floor is long since met, and 6 of them carry `closed_own_ticket` `no`,
1050
- so the trigger is met too. **Firing changes nothing: the action is "revert
1051
- `class=routine` to top tier" and that revert already happened on 2026-08-16.**
1052
- The guard is in its fired state and has no further move; the live question is
1053
- the opposite one, restoring a cheaper tier, which this guard does not decide
1054
- and which no row on file settles.
1055
-
1056
1085
  The raw split still favours the top tier — 3 failures in 11 `routine`/`sonnet`
1057
1086
  rows against 3 in 55 `routine`/`opus`. **Do not read that as a tier result.**
1058
1087
  Tier remains largely confounded with calendar date and therefore with prompt
@@ -1068,7 +1097,7 @@ within-run pairing above**: one implementer in five at the alternate tier makes
1068
1097
  tier orthogonal to date by construction, so the question stops depending on
1069
1098
  whichever rows history happened to leave. **Orthogonal to date, and to nothing
1070
1099
  else** — the alternate member is whichever ticket the 5th Pull draws, rolling
1071
- past every correction and every ticket another open one sequences after, while
1100
+ past every ticket another open one sequences after, while
1072
1101
  the top tier absorbs all of those, so the pairing trades the calendar confound
1073
1102
  for a difficulty one that runs in a known direction. That is why the four covariates
1074
1103
  exist: condition a pair comparison on `sizing`/`profile`/`loc`/`files` before
@@ -1082,38 +1111,17 @@ honest summary is unchanged and is the reason this paragraph exists: the guard
1082
1111
  fired on the criterion the maintainer chose in advance, not on a demonstration
1083
1112
  that the cheaper tier is worse.
1084
1113
 
1085
- **No class recorded → record `class=unknown`, never a guess.** Since the revert
1086
- every class dispatches the same way, so a lost class no longer misprices a
1087
- member — but it still costs the **correction-ticket discipline**, which phase 2
1088
- selects on the class and which is the half that caught real defects. Every path
1089
- that loses it lands here — a compaction, a Pull whose read did not survive
1090
- one, a killed member replaced from inherited state. Writing the gap down is what makes it visible; re-read the issue to
1091
- recover the class when a correction's discipline is worth one `gh issue view`.
1092
- **Never infer the class from the tier** — that inference is what the revert
1093
- removed, and a future control would break it again.
1094
-
1095
- Carry the class in the ticket's ledger row, written before dispatch like every
1096
- other field:
1097
-
1098
- ```
1099
- ledger.mjs row <N> "impl-<N> · class=routine"
1100
- ledger.mjs row <N> "impl-<N> · class=correction"
1101
- ledger.mjs row <N> "impl-<N> · class=unknown"
1102
- ```
1103
-
1104
1114
  `row` **replaces the whole line**, it does not append. Re-dispatching over a row
1105
1115
  that already carries `KILLED`, `ports=` or `→ PR#` must repeat those tokens or
1106
- they are gone, with only `rewrote row #N` on stderr to say so. Recover a class
1107
- after a compaction with `ledger.mjs read` — `class=` is a raw-row field, and the
1108
- cockpit does not parse or surface it.
1116
+ they are gone, with only `rewrote row #N` on stderr to say so.
1109
1117
 
1110
1118
  `ledger.mjs read` is safe on a pipe as well as a redirect: its payload used to
1111
1119
  be abandoned at the pipe buffer and still exit 0, which is what left `board.mjs`
1112
1120
  reporting `ledger read parse failed` and serving a blind cockpit for a whole run
1113
1121
  (#246). Every use above is a recovery path, so a payload that arrives short
1114
- lands exactly where a lost class or a settled `ruled:` is unrecoverable — which
1115
- is why the script's own suite pins that `read`, `row`, `filed` and `ruled` each
1116
- reach a pipe whole.
1122
+ lands exactly where a settled `ruled:` is unrecoverable — which is why the
1123
+ script's own suite pins that `read`, `row`, `filed` and `ruled` each reach a
1124
+ pipe whole.
1117
1125
 
1118
1126
  `check` reaches a pipe whole at both of its exits too. Its ALREADY FILED exit
1119
1127
  sits mid-branch, where falling through would run the near-miss ranking and the
@@ -1139,14 +1147,15 @@ on the cockpit are not yet proof the pipeline is idle.
1139
1147
  **Guard: accumulate per PR, never conclude inside one run.** The unit is the PR —
1140
1148
  supply is one Pull per free slot, so there are no implementer batches. **Append one row to
1141
1149
  `docs/metrics/tier-outcomes.tsv` when you rule each PR's review, with
1142
- `~/.fleet/bin/fleet-run tier-outcomes.mjs append <pr> --class <class> --closed-own-ticket yes|no --minted-false-claim yes|no --note "<text>"`,
1150
+ `~/.fleet/bin/fleet-run tier-outcomes.mjs append <pr> --closed-own-ticket yes|no --minted-false-claim yes|no --note "<text>"`,
1143
1151
  never by hand** (that file's header carries the column meanings). The script
1144
1152
  fills `run_date`, `pr`, `ticket` and `tier` itself — `tier` from what actually
1145
1153
  ran, off the implementer's `tier-ok=` ledger verdict or else its one
1146
- member-outcomes row, and BLANK with a WARNING naming why when neither settles
1154
+ member-outcomes row (a `tier-unverifiable=` member has no ledger verdict, so
1155
+ its one member-outcomes row decides), and BLANK with a WARNING naming why
1156
+ when neither settles
1147
1157
  it; never type a tier in over that. A PR that already has a row is left
1148
- untouched, so re-running it is safe. That append is the whole duty; the guard
1149
- fires on the accumulated file, across runs, not on the run in front of you.
1158
+ untouched, so re-running it is safe. That append is the whole duty.
1150
1159
 
1151
1160
  The row's last four fields are the ticket's difficulty, and they are what lets a
1152
1161
  tier comparison condition on the thing that swamps it. `sizing` is the
@@ -1226,9 +1235,13 @@ append`, as above. Once both files hold this run's rows, and before either is
1226
1235
  committed, run `~/.fleet/bin/fleet-run tier-outcomes.mjs check --live`. Exit 1
1227
1236
  names each row whose `tier` disagrees with the one implementer the member facts
1228
1237
  say ran for its ticket: correct that row's `tier` to the short name it prints,
1229
- or blank it and say why in `note`. Each WARNING names a PR this run's ledger
1230
- marks `reviewed=` that has no row yet — append it before committing if it is
1231
- an implementer PR.
1238
+ or blank it and say why in `note`. Exit 1 also names the PRs of the case where
1239
+ the latest `run_date`'s filled rows have no implementer row in the member file
1240
+ and none could be compared, so nothing from that run was checked: append the
1241
+ run's member rows if they are missing, or blank each named row's `tier` and say
1242
+ why in `note`.
1243
+ Each WARNING names a PR this run's ledger marks `reviewed=` that has no row yet
1244
+ — append it before committing if it is an implementer PR.
1232
1245
 
1233
1246
  Both files are the run's own artifacts and neither commits itself. Carry them to
1234
1247
  main the same way the run carries any other controller-authored change; leaving a
@@ -1245,9 +1258,7 @@ letter when the date already has one (`chore/run-artifacts-2026-08-23b`).
1245
1258
  **Data rows and rule-doc prose never share a PR — one branch each, and when the
1246
1259
  rules here compete this is the one to keep.** The two halves have opposite cost
1247
1260
  profiles, and bundling makes the cheap-to-strand half gate the expensive one.
1248
- Stranding a data row loses it: the tier guard re-derives its floor from the
1249
- undercount and re-fires, the same stale-file failure Phase 0's fast-forward step
1250
- exists to catch, and `member-outcomes.tsv` is regenerated from harness
1261
+ Stranding a data row loses it: `member-outcomes.tsv` is regenerated from harness
1251
1262
  transcripts this repo does not own, so re-running the scrape later is worth only
1252
1263
  what the harness still holds. Stranding a rule change costs the status quo, which
1253
1264
  is where it already was. So `chore/run-artifacts-<date>` carries the two
@@ -1292,8 +1303,8 @@ awk -F'\t' '!/^#/ && $4=="routine" {t[$5]++; if($6=="no") f[$5]++} \
1292
1303
 
1293
1304
  **These rows are the historical corpus, and nothing appended to them fixes the
1294
1305
  confound.** What fixes it is the within-run pairing in the dispatch rule above:
1295
- from now on one implementer in every five runs at `sonnet` beside the `opus`
1296
- ones, against the same prompts on the same day, so the comparison stops depending on
1306
+ from now on one implementer in every five runs at the alternate tier beside the
1307
+ top-tier ones, against the same prompts on the same day, so the comparison stops depending on
1297
1308
  which tier history happened to leave in which week. Read the pairs, not the
1298
1309
  whole-file split, once there are enough of them.
1299
1310
 
@@ -1314,25 +1325,6 @@ number from any other one:** the query it replaces (#1066) counted every
1314
1325
  session whose implementers merely differed, so it cleared this floor by an
1315
1326
  order of magnitude while the controlled comparison did not exist yet.
1316
1327
 
1317
- The risk being priced is economic, not shipped bugs. Reviews run 3-5x *longer*
1318
- than implementation (Red flags, below), so one extra fix-round costs an implementer slot
1319
- and eats the saving the cheaper implementer made. The revert needs a floor AND a
1320
- trigger, and neither alone. **Floor:** the file holds at least
1321
- three `class=routine` PRs spanning **two or more distinct `run_date`s**.
1322
- **Trigger, read only once the floor is met:** **two or more** of those rows carry
1323
- `closed_own_ticket` `no`, or the implementer
1324
- share in `board.mjs build`'s `.spend.roles` is climbing →
1325
- revert **`class=routine`** to top tier, never the rule wholesale. That floor is
1326
- over the accumulated file, never one run — and the `run_date` half is what makes
1327
- that literal instead of merely asserted: a PR count alone is satisfied by a
1328
- single run's rows, which is the state this file ships in. Without the floor a
1329
- single noisy PR reverts a class; without a `no` count, "trending" names no
1330
- threshold and whether the guard fires is undefined. Per-`impl-<N>`
1331
- spend is not available from `.spend.top`: it labels agents by the member
1332
- name, but holds only the eight largest spenders.
1333
-
1334
- **Never read the guard's silence as a pass** — and never read a single run's rows
1335
- as its verdict.
1336
1328
  Why the agent body carries what it does — read this before editing either agent
1337
1329
  file, and keep the two bodies byte-identical. Each rule in the body's
1338
1330
  enumerate-and-declare block is load-bearing, for a different reason.
@@ -1360,10 +1352,11 @@ what decides whether a replacement redoes or destroys work. Observed twice in
1360
1352
  one run.
1361
1353
 
1362
1354
  **The identity block is what makes `sizing-a-ticket`'s fleet entry reachable.**
1363
- That skill conditions its heavy-row entry on the reader being a fleet member; a
1364
- reader that takes itself for a solo session gets `superpowers:brainstorming`
1365
- instead, whose `<HARD-GATE>` withholds every implementation action until a human
1366
- partner approves — approval no unattended member can obtain, so it parks rather
1355
+ That skill conditions its heavy-row process on the reader being a fleet member;
1356
+ a solo reader settles the open design choices with its user before planning,
1357
+ while a fleet member's `## Agent Brief` already is that settlement. A member
1358
+ that takes itself for a solo session waits on a user to settle design — a user
1359
+ no unattended member has, so it parks rather
1367
1360
  than fails. Nothing else you carry says what the member is — an incidental
1368
1361
  mention of the controller is not a statement that the reader is one of its
1369
1362
  members. That skill keeps its condition, so a solo session still runs the
@@ -1400,8 +1393,8 @@ for a token on a ticket's line — never a hand edit.
1400
1393
  |---|---|
1401
1394
  | Implementer report | `verify-sha.sh`; `ledger.mjs settle impl-<N>=PR#<M>`, or `=bailed` and relabel by cause (**Implementer bails before implementing**, below) |
1402
1395
  | Review workflow notification / `review-pr-<n>` report | write `<scratch>/review-<pr>.json`; `reviewed=<head>:<survived>/<refuted>/<unverified>` on the PR's row (**Reviewers**) |
1403
- | Fix-applier report | `ledger.mjs settle fix-pr-<M>=…`; copy the refutations it reversed to `ruled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1404
- | Finisher report | `ledger.mjs settle finisher-pr-<M>=labelled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1396
+ | Fix-applier report | `ledger.mjs settle fix-pr-<M>=…`; for a fix-applier that answered a review — not one that cleared a conflict hold, which has no review file — `~/.fleet/bin/fleet-run dispositions-check.mjs --member <that member> --scratch <scratch>`, from the checkout root: it judges `<scratch>/dispositions-<M>.json` against `<scratch>/review-<M>.json`, writes `dispositions-ok=`, `dispositions-mismatch=` or `dispositions-escalate=<member>:<head>` onto the PR's row itself, and exits 1 on a mismatch or an escalation, naming each violating or escalated entry's bucket and index, a violation its rule too (an escalation is then the gate paragraph's, below); copy the refutations it reversed — the record's `refuted` entries — to `ruled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1397
+ | Finisher report | `ledger.mjs settle finisher-pr-<M>=labelled` as reported, even when its read-back lacks `ready-to-merge` — the tick's `DISPATCH finisher PR#<M>` catches that next. A **repair** finisher's (one sent on that line) read-back lacking it also gets `gh pr comment <M>` with both finishers' read-backs: the one-shot escalation, where halts comment. `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1405
1398
  | Finisher report (halted) | `ledger.mjs settle finisher-pr-<M>=halted:<cause>`; `gh pr comment <M>` with the finisher's halt report, cause and evidence; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line; then the per-cause rule (**Resolving a finisher halt**, below) |
1406
1399
  | Label seen (persistent Monitor) | nothing to record |
1407
1400
  | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
@@ -1477,7 +1470,7 @@ owes beyond its row:
1477
1470
  - **Monitor: CI run completes** → bind it (`ci-state.mjs --pr <N>`) and **record
1478
1471
  it as `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
1479
1472
  ticket's ledger row, which outlives your context. `row` **replaces the whole
1480
- line** (above), so repeat `class=`, `ports=` and `→ PR#` or they are gone.
1473
+ line** (above), so repeat `ports=` and `→ PR#` or they are gone.
1481
1474
  That key cannot be reconstructed once the head is superseded, so a
1482
1475
  controller holding only the colour cannot later tell an edge it has already
1483
1476
  spent from one that never fired, and that is the distinction the sibling
@@ -1575,27 +1568,55 @@ depth** guard table applied in code. Act on each line as it reads:
1575
1568
  - `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn
1576
1569
  (**Reviewers**).
1577
1570
  - `DISPATCH merge-bot` — the next `merge-bot-<n>` (**Merge bot**).
1571
+ - `DISPATCH finisher PR#<M> …` — a finisher settled `labelled`, yet the open
1572
+ list shows PR M without `ready-to-merge`, and no `label-off=` (**Run ledger**)
1573
+ accounts for the removal (#2331). Apply the finisher gate (**Reviewers**: the
1574
+ `check` job green on the current head), then dispatch the next-suffix
1575
+ finisher at that head — `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`, one
1576
+ letter past the highest the PR has used. Never add the label yourself. A head
1577
+ that moved is caught by the new finisher's duty 1 `past-pin` halt and the
1578
+ re-review path that follows it. Finishers take no reviewer slot, so this
1579
+ prints whatever the reviewer cap reads.
1580
+ - `ESCALATE unlabelled PR#<M> …` — a second finisher since the last `label-off=`
1581
+ settled `labelled` and the label is still not on: the tick dispatches no
1582
+ third. Not actionable; the maintainer's, through the cockpit's `unlabelled`
1583
+ flag and the comment the repair finisher's report left (**Finisher report**
1584
+ row above).
1578
1585
  - `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
1579
1586
  unchecked tier, a saturated review side, `--max-reviews` in flight, or every
1580
1587
  queued merge candidate held behind a lower PR or on a conflict hold no
1581
1588
  fix-applier has cleared. The two tier holds are yours to clear — an
1582
- unchecked tier by running `tier-check.mjs --batch` on the member it names,
1583
- a mismatch by dispatching the replacement at the right tier (phase 2). Each
1589
+ unchecked tier by running `tier-check.mjs --batch` on the member it names
1590
+ (its `tier-ok=`, or `tier-unverifiable=` for a member settled `killed` or
1591
+ `released` with no transcript, clears it), a mismatch by dispatching the
1592
+ replacement at the right tier (phase 2). Each
1584
1593
  prints its clearing step in the row's detail: the `tier-check.mjs` command
1585
1594
  with a batch entry per member it names (fill in `<file>` and `<session>`),
1586
1595
  or the replacement's name — `impl-<N>-b` on a first retry, else one letter
1587
1596
  past the highest the ticket has used, or that no retry letter is left.
1588
1597
  - `AT CAP`, `IDLE OK` — nothing to do on that row.
1589
-
1590
- **Tier guards under Pull.** An alt Pull — the Pull phase 2 routes to the
1591
- alternate tier — is where the tier floor is read. Run phase 2's tier guard
1592
- before choosing the alternate tier, on the floor phase 2 defines over the
1593
- accumulated `docs/metrics/tier-outcomes.tsv` and on no gate of this Pull's own:
1594
- a second threshold stated here is a second definition, free to drift from
1595
- the one that governs, and a throttle would need state nothing on disk records
1596
- — a schema change with its own ticket. A floor breach — the guard firing —
1597
- dispatches that Pull at the default tier instead, with no `tier=alt` in its
1598
- row; say why in your report. The per-dispatch `tier-check.mjs --batch` stays
1598
+ - `MAIN-CHECKOUT-DIRTY <paths> …`, printed above the rows, with every
1599
+ dispatching row (implementers, reviewers, merge-bot) reading
1600
+ `HOLD (main checkout dirty)` — the main checkout changed since the Phase 0
1601
+ baseline. The line names the changed paths and every live member; it
1602
+ attributes nothing, because concurrent members make that a guess. Dispatch
1603
+ nothing new and tell the maintainer: they resolve the stray paths FIRST,
1604
+ then re-baseline with `~/.fleet/bin/fleet-run main-checkout.mjs --record`.
1605
+ The hold lasts until that re-baseline, tick after tick. Never revert the
1606
+ paths yourself, and never re-baseline over paths nobody has resolved. The
1607
+ one change of yours that trips it is a mid-run tooling fix edited in this
1608
+ checkout; **Fix the tooling mid-run** says how that one is cleared.
1609
+ - `MAIN-CHECKOUT-UNKNOWN …` with `HOLD (main checkout unknown)` — the tick
1610
+ could not look: a git or hash read failed (`could not look:`), or the
1611
+ baseline exists but cannot be read (`baseline unreadable:`). Never clean,
1612
+ and **never re-baseline over it** — `--record` overwrites, so that certifies
1613
+ a tree nobody read. Fix what the line names and tick again.
1614
+ - `MAIN-CHECKOUT-NO-BASELINE …` with `HOLD (main checkout no baseline)` — no
1615
+ baseline was recorded. Yours to fix: run Phase 0's `--record`. A baseline
1616
+ that vanished mid-run is not a fresh run — report it to the maintainer
1617
+ before recording over whatever the tree now holds.
1618
+
1619
+ **Tier guards under Pull.** The per-dispatch `tier-check.mjs --batch` is
1599
1620
  phase 2's own step: a mismatch it finds is the
1600
1621
  `HOLD (tier mismatch impl-<N>)` above, and a member it has no verdict on is
1601
1622
  the `HOLD (tier unchecked impl-<N>)`. Nothing else in the loop owns it.
@@ -1657,7 +1678,10 @@ exactly what the last one said, which is what makes an unattended night
1657
1678
  affordable; a tick on any other wake is read by a controller that just acted and
1658
1679
  needs the rows. An unchanged `PULL` or `DISPATCH` is never folded — unclaimed work
1659
1680
  always prints in full, because folding it would hide the stall behind this
1660
- ticket's own remedy.
1681
+ ticket's own remedy. A dirty or unknown main checkout still folds — clearing it
1682
+ is the maintainer's, so it is nothing for you to act on — but the folded line
1683
+ names it (`…; HOLD (main checkout dirty) persists — …`) for as long as it holds
1684
+ dispatch.
1661
1685
 
1662
1686
  **When you stop on purpose, say why — one command, and it is the last thing
1663
1687
  you owe the next run.** The beat leaves a dated mark on every hold, so a run
@@ -1697,7 +1721,7 @@ run id, attempt, conclusion, behind-count and per-job conclusions, branch derive
1697
1721
  from the PR — including the `gh api --hostname <host>` a GHE compare call needs,
1698
1722
  without which the probe 404s and `behind` comes back `null`, never 0, so every
1699
1723
  event reads as unknown-behind. Call it **without `--quiet`** — that flag drops
1700
- `jobs` and `missing`.
1724
+ `jobs`, `missing` and `dropped`.
1701
1725
 
1702
1726
  A monitor event is a wake-up, never a verdict; members re-query at labelling
1703
1727
  time. See references/ci-and-staleness.md.
@@ -1879,7 +1903,7 @@ report recovery, never the exit code alone.
1879
1903
  The tick names every PR owed one — `DISPATCH review PR#<M>`, oldest first —
1880
1904
  and each gets one review, once per PR:
1881
1905
 
1882
- a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the same five args — 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 and reports; record `review=member:review-pr-<pr#>` on the PR's row before the dispatch call.
1906
+ 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 and reports; record `review=member:review-pr-<pr#>` on the PR's row before the dispatch call. **`scratch` is the scratch root itself, 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.
1883
1907
 
1884
1908
  Write the `review=` token with `ledger.mjs row`, which **replaces the whole
1885
1909
  line**, so carry every other field. The tick counts in-flight reviews off the
@@ -1970,13 +1994,17 @@ review's own in-run retry, and **resume beats handing a crash-heavy review
1970
1994
  on**: a deferred crash is a finding nobody ever looked at.
1971
1995
  No replay exists for a review that ran in a runner's own kernel — `resume` is reported, not acted on, and the fix-applier defers what it names.
1972
1996
  `refuted` comes back deliberately as well — a refutation is itself a claim, and
1973
- one has been reversed on new evidence. The fix-applier may reverse one; its
1974
- report lists every refutation it reversed, and you copy those to the ledger's
1975
- `ruled` line.
1997
+ one has been reversed on new evidence. The fix-applier may reverse one; it
1998
+ records each reversal as a `refuted` entry in its disposition record, the
1999
+ evidence in `reason`, and you copy those entries to the ledger's `ruled` line
2000
+ (the Fix-applier report edge).
1976
2001
 
1977
2002
  **`dimensionsRun` is the dispatch; `dimensionsUnrun` is what names a gap.** A
1978
- specialist that dies, and one that never executed the suite, both contribute zero
1979
- findings while the key stays in `dimensionsRun` — so read the two together. A key
2003
+ specialist that dies contributes zero findings while its key stays in
2004
+ `dimensionsRun`; a review whose one shared test run executed nothing — the
2005
+ review runs the test command once, and every specialist reads that run instead
2006
+ of running its own (#2315) — leaves every key there with no suite behind it. So
2007
+ read the two together. A key
1980
2008
  in `dimensionsRun` and NOT in `dimensionsUnrun` ran a suite; every
1981
2009
  `dimensionsUnrun` entry is `{dimension, reason}` naming which failure it was.
1982
2010
  The review already re-dispatched each crashed specialist once, so what
@@ -2014,8 +2042,10 @@ cap. A runner member that is killed rather than failed follows **Failure
2014
2042
  handling** (fresh name, inherited state stated).
2015
2043
 
2016
2044
  **Then dispatch a fix-applier** — on `DISPATCH fix-pr PR#<M>`, which the tick
2017
- prints for a PR whose `reviewed=` counts survivors and that has had no
2018
- fix-applier since — one named member per PR, `fix-pr-<pr#>`, never the PR's
2045
+ prints for a PR whose `reviewed=` counts survivors that no review fix-applier
2046
+ has landed `applied:`/`no-op` on since, with no fix-applier live on it — one
2047
+ named member per PR, `fix-pr-<pr#>` (the next suffix when that name is already
2048
+ on record), never the PR's
2019
2049
  implementer, recorded with `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the
2020
2050
  call. Its prompt carries the PR number, the worktree abs path, the PR's branch,
2021
2051
  the same `testCmd` you passed the review, and the **path** `<scratch>/review-<pr>.json`
@@ -2028,17 +2058,25 @@ report from a refuter it spawns that surfaces to you is its to retrieve, never
2028
2058
  yours to scan or pass on.
2029
2059
 
2030
2060
  **A `DISPATCH fix-pr PR#<M>` on a conflict hold** — the row carries the merge
2031
- bot's `conflict-hold:#<M>` (`run-merge-bot.md` step 1's fallback), not
2032
- survivors — is the same slot with a different job, and no review file to hand
2061
+ bot's unresolved `conflict-hold:#<M>` (`run-merge-bot.md` step 1's fallback) —
2062
+ is the same slot with a different job, and no review file to hand
2033
2063
  over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
2034
- already on record — `dispatch` refuses a reused one — and dispatch a
2035
- `fleet-implementer` in the PR's existing worktree with the prompt below's
2064
+ already on record — `dispatch` refuses a reused one — and dispatch it with the
2065
+ `agent` that `ledger.mjs dispatch` printed, in the PR's existing worktree.
2066
+ `dispatch` reads the unresolved hold off the tick's own per-PR state — every
2067
+ row naming the PR, not one — and prints this member's own definition, whatever
2068
+ the row's `tier=` — read it off that output, never recall it; a review
2069
+ fix-applier's is `null`. Its prompt takes the prompt below's
2036
2070
  worktree, branch and path discipline, but in place of its review paragraphs:
2037
2071
  bring `<branch>` current with `origin/main`, resolving every conflict by
2038
2072
  `run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
2039
2073
  head. Settle it `applied:<head>` — `no-op` if no conflict was left — which is
2040
2074
  what lifts the tick's merge hold; a dispatched-but-live one does not, and
2041
- `failed`/`killed` leave the PR fix-due for a replacement. The push moves the
2075
+ `failed`/`killed` leave the PR fix-due for a replacement. It answers the
2076
+ hold and nothing else: survivors of a returned review the row also carries
2077
+ stay unanswered through its settle, so the tick prints `DISPATCH fix-pr
2078
+ PR#<M>` again once it lands, and that one — `dispatch` now prints `null` —
2079
+ is a review fix-applier, dispatched as above (#2328). The push moves the
2042
2080
  head after `ready-to-merge`, so the next merge bot refuses it
2043
2081
  `head-moved-after-label-#<M>`: a fresh finisher, per **Failure handling**.
2044
2082
 
@@ -2315,6 +2353,27 @@ all.
2315
2353
  > that was two commits stale, and a finisher dispatched on either would have
2316
2354
  > halted on a diverged head.
2317
2355
  >
2356
+ > **Before you report, write every ruling to `<scratch>/dispositions-<pr>.json`**,
2357
+ > beside the review file — the record the controller checks with
2358
+ > `dispositions-check.mjs` before it dispatches any finisher. It is
2359
+ > `{"head": "<the review file's head>", "entries": [ … ]}`: one entry per
2360
+ > `survived` finding and per `unverified` finding, plus one per `refuted`
2361
+ > finding you reverse, its evidence in `reason`. Each entry carries `bucket`
2362
+ > (`survived|unverified|refuted`), `index` (its position in that bucket of the
2363
+ > review file), `scope` (`in|out`), `claimKind` (`behavior|shape`) and
2364
+ > `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the
2365
+ > number you filed it to or commented on), `verdictPath` (an in-scope
2366
+ > suggestion's refuter verdict file) and `remedyFiles` (the files its remedy
2367
+ > names). A finding with no `line`, or on a line the PR's diff touched —
2368
+ > `git diff` from its merge-base with `origin/main` to the review's head — is
2369
+ > in scope whatever its `scope` says. An in-scope `survived` finding you defer
2370
+ > carries `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or
2371
+ > `remedy-outside-diff`; the last needs `remedyFiles` to name a file the PR's
2372
+ > diff does not touch, and for a `critical` or `important` finding it sends the
2373
+ > PR to a human instead of passing. Any
2374
+ > other reason, none, or a `survived` or `unverified` finding with no entry is
2375
+ > a mismatch, and the PR gets no finisher.
2376
+ >
2318
2377
  > Then report to the controller the pushed SHA, your apply/defer split, and
2319
2378
  > the deferral issue numbers — a `filed: #N <subject>` line for every issue
2320
2379
  > step 5 created, and `unrecorded: #N <subject>` for one whose `ledger.mjs filed`
@@ -2341,13 +2400,11 @@ infer, see the five-condition note in the fix-applier block above) — or
2341
2400
  `ci-state.mjs` reads `verdict: "no-ci"`, see below — **and once the PR's review
2342
2401
  has returned and its fix-applier, if one was dispatched, has sent its report,
2343
2402
  which the CI-completes edge above states in full** — dispatch a
2344
- **finisher** — a fresh small agent, not the fix-applier resumed. **Dispatch it
2345
- by its own definition and omit `model` on the call** — the tier (`haiku`)
2346
- lives in `agents/fleet-finisher.agent.md`:
2347
-
2348
- `fleet-finisher`.
2349
-
2350
- Record it with `ledger.mjs dispatch <pr#> finisher-pr-<pr#>` before the call.
2403
+ **finisher** — a fresh small agent, not the fix-applier resumed. Record it with
2404
+ `ledger.mjs dispatch <pr#> finisher-pr-<pr#>` before the call, then **dispatch
2405
+ it with the `agent` that command printed and omit `model` on the call** — the
2406
+ tier lives in that definition's frontmatter, `agents/fleet-finisher.agent.md`,
2407
+ as the `@smol:low` route, which resolves through the operator's `modelRoles`.
2351
2408
  Its four duties are a checklist — audit the
2352
2409
  worktree, confirm every deferral has a tracker home and re-run the acceptance
2353
2410
  mutation, apply one release label, report — and the
@@ -2363,6 +2420,30 @@ report condition above is for. A withdrawal you
2363
2420
  recorded only in the ledger is undelivered: the member still holds the original
2364
2421
  and will act on it. Relay everything — reversals too — then dispatch.
2365
2422
 
2423
+ **That `dispatch` refuses a finisher — exit 2, nothing written — on a PR whose
2424
+ latest `reviewed=` counts a survived or unverified finding, unless the
2425
+ dispositions verdict answering that review's head is `ok`**: among the
2426
+ `dispositions-*=fix-pr-<M>[-x]:<head>` tokens whose head matches it, the one
2427
+ from the highest-suffixed fix-applier. A PR whose latest review counts
2428
+ `0/<n>/0` is not gated. The refusal names its cause. `dispositions
2429
+ unchecked` — no verdict answers that head: run `dispositions-check.mjs` for
2430
+ the fix-applier that answered the review, as the Fix-applier report edge
2431
+ states, then dispatch again. `dispositions mismatch` — no finisher: post the
2432
+ check's output, which names each violating entry, with `gh pr comment <M>`, and
2433
+ flag the PR for a human; re-running the check reprints it. `dispositions
2434
+ escalate` — no finisher, and no retry: a `critical` or `important` finding was
2435
+ deferred `remedy-outside-diff`, which only a human can rule on. Post the check's
2436
+ output, which names each escalated finding, with `gh pr comment <M>`, and flag
2437
+ the PR for a human; dispatch no fix-applier and no finisher for that review's
2438
+ head, and expect no `fix-due` row for it. **On any PR with a
2439
+ returned review, `0/<n>/0` included, it refuses too while a fix-applier on the
2440
+ PR is still live, verdict or not** —
2441
+ `fix-pr-<M>[-x] still live`: settle it, run the check for it, then dispatch
2442
+ again. That is what keeps a re-review at the same head from being answered by
2443
+ the earlier round's verdict while the fix-applier answering the new round is
2444
+ still working; once its check has run, its verdict, from the higher suffix, is
2445
+ the current one.
2446
+
2366
2447
  **An unanswered question from the member is an outbox item, and it blocks
2367
2448
  dispatch with the same weight as a ruling you have already made.** It does not
2368
2449
  feel like one — you have decided nothing yet, so the outbox reads empty — but a
@@ -2490,19 +2571,25 @@ a minute apart showed *different* mutants, so a member's report and any single
2490
2571
  silent-destruction ordering above — report it back, do not run it. One
2491
2572
  finisher refused exactly that instruction live, on the grounds it could not
2492
2573
  prove the diff was its own; that was judgement, and this is the rule.
2493
- 3. Add `ready-to-merge` — after reading the PR's labels back
2494
- (`gh pr view <pr> --json labels`) and finding **exactly one** release label,
2495
- `patch`/`minor`/`major`. Zero or more than one halts the finisher before the
2496
- label, naming which it found. This is the backstop for a label lost wherever
2497
- it was lost, a hand-created PR included: a `gh pr create` that outran its
2498
- caller's tool timeout leaves the PR open with the flag unapplied and no exit
2499
- status anywhere to notice, and nothing downstream re-derives the release
2500
- label. Count only those three — the PR carries other labels, `ready-to-merge`
2501
- itself among them once you add it, so a PR wearing one release label beside
2502
- them passes unchanged. A repo that defines none of the three does not gate on
2503
- one — `gh label list` settles that, and it is no licence to skip the read
2504
- where they exist.
2505
- 4. Report you the label, the deferral issue numbers — a
2574
+ 3. Add `ready-to-merge` — two steps, each checked on its own, in this order:
2575
+ - **(a) Exactly one release label.** Read the PR's labels back
2576
+ (`gh pr view <pr> --json labels`) and find **exactly one** release label,
2577
+ `patch`/`minor`/`major`. Zero or more than one halts the finisher before
2578
+ the label, naming which it found. This is the backstop for a label lost
2579
+ wherever it was lost, a hand-created PR included: a `gh pr create` that
2580
+ outran its caller's tool timeout leaves the PR open with the flag
2581
+ unapplied and no exit status anywhere to notice, and nothing downstream
2582
+ re-derives the release label. Count only those three — the PR carries
2583
+ other labels, `ready-to-merge` itself among them once you add it, so a PR
2584
+ wearing one release label beside them passes unchanged. A repo that
2585
+ defines none of the three does not gate on one — `gh label list` settles
2586
+ that, and it is no licence to skip the read where they exist.
2587
+ - **(b) Add the label:** `gh pr edit <pr> --add-label ready-to-merge`. (a)
2588
+ passing labels nothing — it is the precondition, and this command is the
2589
+ duty. Two finishers in one run (#2331) stopped at (a) and reported
2590
+ `labelled` on PRs that sat out of the merge queue.
2591
+ 4. Report you the label (its post-add read-back: `gh pr view <pr> --json labels`
2592
+ run after 3(b), output as printed), the deferral issue numbers — a
2506
2593
  `filed: #N <subject>` line for every issue duty 2 created, and
2507
2594
  `unrecorded: #N <subject>` for one whose `filed` failed twice — and anything
2508
2595
  it halted on — cause and evidence, below, never a bare "head moved". The
@@ -2538,17 +2625,76 @@ is dispatched to read, so it reaches one through this block or not at all:
2538
2625
  > tree — so an exit 2 naming a moved or unreadable audited tree is a halt
2539
2626
  > like every other, not a spelling for you to correct.
2540
2627
 
2628
+ **Give the finisher the test-run verdict rule verbatim too.** Duty 2 runs
2629
+ `<testCmd>` for the acceptance mutation, and the finisher's agent definition
2630
+ says nothing about what a run that was cut short looks like. A `node --test`
2631
+ stopped by an outside `timeout` still prints a summary, covering only the tests
2632
+ it reached, so reading that summary alone reads a partial suite as a whole one:
2633
+
2634
+ > **A test run is a verdict only if it ran to completion — and you read that
2635
+ > off the test command's own exit status.**
2636
+ > Redirect the run's output to a file in your scratch directory and read the
2637
+ > command's own `$?` straight after it, then read the file. In an `eval` cell
2638
+ > there is no `$?`: spawn `<testCmd>` with its output going to that file and
2639
+ > read the exit code and the signal off the spawn result — `exitCode` and
2640
+ > `signalCode` on Bun's `spawnSync`, `returncode` on Python's `subprocess.run`,
2641
+ > which is negative for a signal. Never read the status of
2642
+ > `<testCmd> | tail` or `<testCmd> | grep`: a pipeline's status is its
2643
+ > last stage's, so the filter's 0 hides the run's own exit, and the array that
2644
+ > holds the earlier stages' statuses is spelled differently per shell. A run is
2645
+ > a verdict only when that exit status is 0 **and** its summary shows `tests`
2646
+ > above 0 and `cancelled` 0. A summary line without that
2647
+ > is not a verdict, whatever pass count it prints.
2648
+ > **A run completed when the command itself returned on its own** — an exit
2649
+ > code, no signal, and no `timeout`, deadline or kill of yours having fired.
2650
+ > Judge that by how the run ended, never by its `cancelled` count: a failing
2651
+ > `before` hook or a per-test `timeout` cancels tests inside a run that
2652
+ > completed, and a SIGTERM'd `node --test` can exit 1 with `cancelled` above 0
2653
+ > in a run that did not.
2654
+ > **Any run that did not complete is a killed run** — 124 (`timeout`), 137
2655
+ > (SIGKILL), 143 (SIGTERM), a signal in the spawn result, an `eval` cell's
2656
+ > deadline — and read for green it is FAILED, the same bucket as
2657
+ > `tests 0`, however many tests had passed before the kill. Halt with cause
2658
+ > `other` and the exit code plus the summary line as evidence; label nothing.
2659
+ > The same holds for the mutation gate: a killed run is not a mutant that
2660
+ > reddened, and the files it cancelled are not failures — only a run that
2661
+ > completed can kill a mutant. A completed run that exits 1 is a plain failure,
2662
+ > not a killed run, whatever its `cancelled` count, and exit 0 with `tests 0`
2663
+ > stays FAILED.
2664
+ > Do not wrap `<testCmd>` in an external `timeout`. Run a long suite in one
2665
+ > `eval` cell with `timeout: 0`, as the review runner does, and wait for it.
2666
+
2667
+ **Give the finisher duty 3 verbatim as well, as its two steps.** The finisher's
2668
+ agent definition carries no duty text, so this brief is the whole of duty 3 it
2669
+ sees. Two finishers in one run (#2331) read the release-label check as the
2670
+ whole duty and reported `labelled` on a PR that never got the label:
2671
+
2672
+ > **Duty 3 is two steps, and only the second one labels.**
2673
+ > (a) `gh pr view <M> --json labels` — confirm exactly one of
2674
+ > `patch`/`minor`/`major`. Zero or more than one halts you before the label:
2675
+ > name which you found. A repo whose `gh label list` defines none of the three
2676
+ > does not gate on one.
2677
+ > (b) `gh pr edit <M> --add-label ready-to-merge`. Step (a) passing labels
2678
+ > nothing; this command is the duty.
2679
+ > Then run `gh pr view <M> --json labels` once more and put its output in your
2680
+ > report: that read-back is what tells the controller the label is on.
2681
+
2541
2682
  **Once the label is on, take it off before you approve any push.** The label is a
2542
2683
  verdict on the tree the finisher read, and a GitHub label does not follow the
2543
2684
  branch — on #180 it survived a push and came to sit on a commit nobody had
2544
- audited. Remove `ready-to-merge` *first*, then approve: removing the artifact the
2545
- merge bot gates on is the reliable stop, where messaging the bot races it, and a
2546
- label has been observed holding until after an abort message arrived. Then
2685
+ audited. Write `label-off=<latest finisher attempt>` onto the PR's row first
2686
+ (`ledger.mjs row`, the row's whole text plus the token — **Run ledger**), then
2687
+ remove `ready-to-merge`, then approve. The token is how the tick tells your
2688
+ removal from a finisher that never labelled — a tick run between a removal and
2689
+ its token re-dispatches a finisher into your take-off window. The label goes
2690
+ before the approval because removing the artifact the merge bot gates on is
2691
+ the reliable stop, where messaging the bot races it, and a label has been
2692
+ observed holding until after an abort message arrived. Then
2547
2693
  dispatch a **fresh** finisher against the new head; the first audit does not
2548
2694
  transfer, since it verified a different tree. The merge bot refuses that head on
2549
2695
  its own (`run-merge-bot.md`, **The labelled head**), so this is not the only
2550
2696
  guard — but its refusal costs a pass and leaves the label lying, which is yours
2551
- to clear either way.
2697
+ to clear either way, the same way: `label-off=` first, then the removal.
2552
2698
 
2553
2699
  A halt at step 1 reads identical from a bare SHA mismatch whatever caused it,
2554
2700
  and the causes below are the ones seen so far, not a closed list. Give the
@@ -2640,7 +2786,7 @@ applied.
2640
2786
  Gate on the `check` job, **not** on `ci-state --quiet` exit 0: a behind PR never
2641
2787
  reaches full green, so an exit-0 gate strands it unlabelled. The finisher reads
2642
2788
  per-job state (`ci-state.mjs` without `--quiet`, or its `jobs`), since `--quiet`
2643
- drops `jobs` and `missing`. Normal path, not only kill-recovery.
2789
+ drops `jobs`, `missing` and `dropped`. Normal path, not only kill-recovery.
2644
2790
 
2645
2791
  **`ci-state.mjs` reads `verdict: "no-ci"`** — no `check` job exists in this repo
2646
2792
  to gate on, and that is not a third way to skip the wait. **The
@@ -2652,7 +2798,7 @@ for instead:
2652
2798
 
2653
2799
  1. `ci-state.mjs` **without** the flag still reads `verdict: "no-ci"`. A repo
2654
2800
  whose CI is merely misconfigured — workflow files present under other names,
2655
- or `.github/workflows/` unreadable — exits 2 there rather than reading no-ci,
2801
+ or `.github/workflows/` not a directory — exits 2 there rather than reading no-ci,
2656
2802
  so this is the check that separates real absence from misconfiguration, the
2657
2803
  case that must never ship silently.
2658
2804
  2. The reviewer's own final verdict reports a green `testCmd` run on the SHA it
@@ -2663,79 +2809,16 @@ Both → add the label, and say it rests on the reviewer's suite run, not on CI.
2663
2809
  Either missing → halt here, same as a dirty worktree: report `no CI configured,
2664
2810
  no verified suite run on record` and add no label.
2665
2811
 
2666
- **Correction tickets ship new wrong claims — inherited from the ticket, and
2667
- minted in prose the ticket never asked for.** Put the check on the
2668
- **implementer**, not only the reviewer: every factual claim the diff restates
2669
- must have a settling command run against the tree first — the issue body is a
2670
- lead, never a citation — and the diff must **match the ticket's stated size**,
2671
- since added prose is where minted claims enter. No positional references (`the
2672
- closing/second/last X`); name the thing semantically. Evidence from a run on
2673
- **another repo** is cited by host: a github.com source as `owner/repo#N`;
2674
- anything else (GHE, GitLab, internal) as prose naming host and repo and saying
2675
- it cannot be settled from this repo — a bare `#N` stays bare only for this
2676
- repo's own issues and PRs. The workflow's `comments`
2677
- dimension checks every added assertion against the tree, including comments in
2678
- files the diff does not touch; a fallback reviewer has to be told that *and* told
2679
- to read each corrected sentence literally, clause by clause.
2680
- See references/correction-tickets.md.
2681
-
2682
- **But the discipline follows the DIFF, not the class — hand it to any
2683
- implementer whose diff writes prose.** Phase 2 selects it on `class=correction`,
2684
- and that selection is too narrow: a `routine` ticket that adds a test fixture, a
2685
- helper, or a coverage case writes comment prose too, and prose is where minted
2686
- claims live. Measured twice in one run, both `class=routine`, both therefore
2687
- dispatched WITHOUT this block: PR #756 added an unasked-for comment asserting a
2688
- silent-failure mode that does not exist (gross PATH damage is loud — 10 of 39
2689
- tests red), and PR #768 minted a false comparative ("the cheapest of the four to
2690
- tear down, not the dearest", when its route is the only one of four needing any
2691
- in-body teardown) **and** introduced two positional references replacing a
2692
- name-based one. Neither ticket asked for either sentence.
2693
-
2694
- Two of the rules above are what caught both, so give them to every implementer
2695
- regardless of class: **every factual claim the diff restates needs a settling
2696
- command first**, and **no positional references**. A third earns its place here
2697
- — **never write a COUNT or a tally into prose; state the property instead** —
2698
- unless it is a past-tense record of a measurement you performed, which stays
2699
- as written; a present-tense claim about a live property must be restated as a
2700
- property (`every other test in the file`), true at any count. A
2701
- count is false the moment the next commit lands, and #768 falsified two of them
2702
- (`the only other chmodSync(..., 0o644)`, already off by one before it; `fails 75
2703
- of the 85 cases`, measured 81 of 91) in a file whose own header records having
2704
- shipped a stale count once already. The immutable-body rule earns the same
2705
- place: **every claim a commit body or a PR body asserts needs its settling
2706
- command re-run at the commit that ships it, and written inline beside it.**
2707
- The literal-text `-F` rule earns the same place: **a settling command over
2708
- literal text uses `grep -F`, and its zero counts only after the same
2709
- command, with the same flags, finds a line known to match.** Measured on
2710
- #1087, the same false zero fired twice in one run. A relayed enumeration
2711
- delivers only what it names, so this list is the whole of what a controller
2712
- hands over, never a preface to it.
2713
-
2714
- **One more rule, and the one the diff cannot carry: a claim written into a
2715
- commit body or a PR body needs its settling command re-run at the commit that
2716
- ships it, not at the commit that motivated it — and the command goes inline,
2717
- beside the claim.** The rules above scope to prose the diff restates, and a
2718
- pushed commit body is not in the diff: it cannot be edited, only retracted by a
2719
- later commit, which is itself a fresh unverified historical claim. So the check
2720
- has to sit at write time, and review-time is already too late. The claim types
2721
- are wider than measurement — a line number, a SHA, an **attribution** of who
2722
- said what, a positional reference and a count all rot the same way, and an
2723
- attribution is the worst of them, because the argument it carries collapses
2724
- when it turns out false, while a wrong line number leaves the surrounding
2725
- reasoning standing. `Verified:` is the construct a later reader trusts
2726
- *instead of* re-deriving, so a wrong figure under that header is worse than no
2727
- figure at all. Measured on #399: `f961cf2` and `acce6ee` both close `Verified:`
2728
- with `86/86 across both test files` naming the suites that read this file, a
2729
- file set the tree does not bear out — `git log -1 --format=%b <sha> | grep -A2
2730
- Verified:` shows what each shipped. Inline is what makes the difference visible:
2731
- a claim carrying the command that produces it can be re-run instead of trusted.
2732
- A claim whose settling command cannot be written is still not one to assert
2733
- bare: settle it inline, mark it unsettleable from this repo per the citation
2734
- convention above, or drop it. The marker ending is not a loophole but the case
2735
- that convention already sanctions: it directs foreign evidence to be asserted as
2736
- prose saying it cannot be settled from this repo, and that marker is itself what
2737
- tells a later reader not to trust the claim instead of re-deriving it, which is
2738
- the property this rule protects.
2812
+ **Every implementer body carries the claim discipline, because tickets that
2813
+ restate facts ship new wrong claims** — inherited from the ticket, and minted
2814
+ in prose nobody asked for. It was measured on tickets that would have been
2815
+ judged routine too: an unasked-for comment asserting a silent-failure mode
2816
+ that does not exist, a false comparative plus positional references replacing
2817
+ a name-based one, and two present-tense counts already false when they were
2818
+ written.
2819
+ Nothing before dispatch can see the diff, so the discipline goes to every
2820
+ implementer. A pushed commit body cannot be edited, so its claims are settled
2821
+ at write time. See references/correction-tickets.md.
2739
2822
 
2740
2823
  **The settling command for "which files read X" must never be a literal-path
2741
2824
  grep.** The path is assembled in more than one spelling here, one of them behind
@@ -2770,7 +2853,10 @@ that name — never its implementer, recorded as
2770
2853
  like the review it replaces. Give it the PR number and tell it to read
2771
2854
  `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` — the resolved file
2772
2855
  path, not a slash invocation; command availability inside a member is not
2773
- guaranteed the way skill availability is. It then does the fix-applier's job too:
2856
+ guaranteed the way skill availability is. Tell it to check every added
2857
+ assertion against the tree, including comments in files the diff does not
2858
+ touch, and to read each corrected sentence literally, clause by clause. It then
2859
+ does the fix-applier's job too:
2774
2860
  apply, defer, file, push, report, exit. On its report, record
2775
2861
  `reviewed=<head>:0/<refuted>/<deferred>` against the head it pushed — it applied
2776
2862
  its own survivors, so the zero is what tells the tick no fix-applier is owed —
@@ -2838,10 +2924,10 @@ enough, and it never waits for the finisher's report. Tell it to read
2838
2924
  pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
2839
2925
  for late labels, then report once and exit — and say that you dispatched it,
2840
2926
  which is what makes it hold that grace instead of arming its own watcher. **Dispatch
2841
- it by its own definition and omit `model` on the call** — the tier (`haiku`)
2842
- lives in `agents/fleet-merge-bot.agent.md`:
2843
-
2844
- `fleet-merge-bot`.
2927
+ it with the `agent` that `ledger.mjs dispatch merge-bot` printed and omit
2928
+ `model` on the call** — the tier lives in that definition's frontmatter,
2929
+ `agents/fleet-merge-bot.agent.md`, as the `@smol:low` route, which resolves
2930
+ through the operator's `modelRoles`.
2845
2931
 
2846
2932
  Rebase, wait for green, check the
2847
2933
  label, merge is checklist work, and a bad merge still needs the label and the
@@ -2888,7 +2974,8 @@ ancestry proof, post-rebase red triage. Do not restate them here.
2888
2974
 
2889
2975
  ### Reap after each merge pass
2890
2976
 
2891
- A merge deletes the remote branch and leaves the local branch `[gone]` with its
2977
+ The merge bot deletes the remote branch after each merge (`delete-merged-branch.sh`,
2978
+ in `run-merge-bot.md` step 4), leaving the local branch `[gone]` with its
2892
2979
  worktree — and its `node_modules` — still on disk. Reap after **each** merge pass,
2893
2980
  not once at the end: a stale worktree still answers `git worktree list`, so the
2894
2981
  in-flight probe (`inflight.sh`, run by the Shortlist and by every Pull) reads an
@@ -3131,11 +3218,18 @@ never as a second, hand-run copy of it.
3131
3218
  Four holds outrank every row: `HOLD (draining)` once `ledger.mjs drain` has
3132
3219
  recorded the drain, `HOLD (tier mismatch impl-<N>)` until a replacement is
3133
3220
  dispatched at the right tier, `HOLD (tier unchecked impl-<N>)` until
3134
- `tier-check.mjs` has written its verdict on the newest implementer, and
3221
+ `tier-check.mjs` has written its verdict on the newest implementer —
3222
+ `tier-ok=`, `tier-mismatch=` or `tier-unverifiable=` — and
3135
3223
  `HOLD (review side saturated)` when a PR is still owed its review and no
3136
3224
  reviewer slot is left for it — refreshing to enable a Pull you are holding
3137
3225
  buys nothing.
3138
3226
 
3227
+ A main checkout that is not `clean` against its Phase 0 baseline outranks all
3228
+ of them, and every dispatching row besides: `HOLD (main checkout dirty)`,
3229
+ `HOLD (main checkout unknown)` or `HOLD (main checkout no baseline)` on the
3230
+ implementer, reviewer and merge-bot rows alike, beside the `MAIN-CHECKOUT-*`
3231
+ line that says why (#2210).
3232
+
3139
3233
  `/triage` is user-invoked only — suggest, never run. The suggestion is a report,
3140
3234
  not a blocking prompt. Counts come from cheap `gh issue list --search`, no bodies.
3141
3235
  A starved implementer queue never stalls the review or merge side.
@@ -3182,9 +3276,14 @@ as a stray commit — the flag and the maintainer's ruling above are what exit 1
3182
3276
  earns, and spending them on a probe that never answered costs a member its
3183
3277
  ticket over a failure a re-run would have cleared.
3184
3278
 
3185
- **Never `--delete-branch`.** It errors on a `main` held by another worktree, or
3186
- strands the feature worktree on `main`. `gh pr merge <n> --merge` alone; GitHub
3187
- deletes the remote branch anyway.
3279
+ **Never `--delete-branch` — the merge bot deletes the head branch itself.**
3280
+ `gh pr merge <n> --merge` alone: the flag's local cleanup errors on a `main`
3281
+ held by another worktree, or strands the feature worktree on `main`. After the
3282
+ merge, `delete-merged-branch.sh <pr>` deletes the branch from `origin` and reads
3283
+ the deletion back; `reap.sh` takes the `[gone]` local branch and its worktree.
3284
+ No repo setting is relied on to do it (#2196). A branch another open PR still
3285
+ uses as its head or base is kept instead — `branch-kept-#<that PR>` in the bot's
3286
+ report, a deliberate keep and not a failure (#2295).
3188
3287
 
3189
3288
  **Never force a rebase to start.** No `git clean`, `git checkout .`,
3190
3289
  `git reset --hard`, `git stash`. Uncommitted changes may exist nowhere else.
@@ -3289,11 +3388,13 @@ failures arrive as *wrong findings*, not errors:
3289
3388
  materialization failure. See references/isolation.md.
3290
3389
  - **Scratchpad paths need two levels — the member's own partition, then one
3291
3390
  directory per child it dispatches — and nothing outside them.** An
3292
- implementer partitions at `<scratch>/impl-<N>/`, the review side at
3293
- `<scratch>/pr<N>/…`; any member that dispatches a child writes an absolute
3294
- directory under its own partition into that child's prompt, one per child
3295
- and never shared, and a child never derives its own. Finding ids restart at 1
3296
- every review, so two fix-appliers on different PRs both reach for `unv1`; one
3391
+ implementer partitions at `<scratch>/impl-<N>/`; the review side's partition
3392
+ is `<scratch>/pr<N>/…`, which the review core creates itself, so a review
3393
+ runner is handed the scratch root, never that partition; any member that
3394
+ dispatches a child writes an absolute directory under its own partition into
3395
+ that child's prompt, one per child and never shared, and a child never
3396
+ derives its own. Finding ids restart at 1 every review, so two fix-appliers
3397
+ on different PRs both reach for `unv1`; one
3297
3398
  agent overwrote a sibling's `package.json`, and a probe built a git repo at
3298
3399
  the *checkout root*. Read from the object store at a pinned ref, write only
3299
3400
  under your own path. See references/isolation.md.
@@ -3330,8 +3431,13 @@ the step. Cut before you append.
3330
3431
  --pin`. You just changed the instrument set under your own check, and this is the
3331
3432
  only edit that legitimately does; skip it and the next gate refuses on your own
3332
3433
  fix, which teaches you to ignore the refusal. Then the ledger line, save the
3333
- rationale, one line to the maintainer. Live members hold the old text — re-brief
3334
- only if it changes what they do *now*.
3434
+ rationale, one line to the maintainer. **Then re-baseline the main checkout,
3435
+ if the fix was edited in it** — the next tick reads `MAIN-CHECKOUT-DIRTY`
3436
+ naming your own paths. Run `~/.fleet/bin/fleet-run main-checkout.mjs --check`
3437
+ first, and only when the paths it names are exactly the ones you just edited,
3438
+ run `--record`. Any other path on that line is a stray write — leave the hold for
3439
+ the maintainer, because `--record` would certify it with yours. Live members
3440
+ hold the old text — re-brief only if it changes what they do *now*.
3335
3441
 
3336
3442
  **Landing it.** The file being right is not the end of it. `main` carries a
3337
3443
  ruleset with no bypass actors, so a direct `git push origin main` is **refused** —
@@ -3410,19 +3516,23 @@ decides whether a replacement redoes or destroys work.
3410
3516
 
3411
3517
  ## Run ledger
3412
3518
 
3413
- One git-ignored `.fleet/ledger.md`, updated at **every** state change via
3519
+ One git-ignored `.fleet/ledger.md` per run, updated at **every** state change via
3414
3520
  `~/.fleet/bin/fleet-run ledger.mjs` subcommands (`row`, `filed`, `ruled`,
3415
- `check`, `read`, `dispatch`, `settle`, `drain`). Your context is the least
3521
+ `check`, `read`, `dispatch`, `settle`, `drain`, `rotate`). Your context is the least
3416
3522
  durable thing in the run: it compacts, and a controller that loses the dispatch
3417
3523
  map or the filed list redoes finished work. Two duplicate tickets shipped in one
3418
3524
  run from exactly that.
3419
3525
 
3526
+ **The file lives one run.** Phase 0 rotates it before anything reads it, so
3527
+ no row, exclusion, filing, ruling or drain marker outlives the run that
3528
+ wrote it. Never rotate mid-run: it is phase 0's step alone.
3529
+
3420
3530
  One line per ticket, rewritten in place (`ledger.mjs row <ticket> <text>`):
3421
3531
 
3422
3532
  ```
3423
3533
  #332 impl-332=PR#344 → PR#344 → MERGED 73b356de
3424
3534
  #324 impl-324=PR#346 → PR#346 · fix-pr-346 · ports=16324 · ruled:6-applies · held-behind:#313
3425
- #351 impl-351 · class=routine · tier=alt
3535
+ #351 impl-351 · tier=task-high
3426
3536
  #358 excluded · behind-pr:#346
3427
3537
  #360 excluded · behind-issue:#351
3428
3538
  ```
@@ -3433,9 +3543,17 @@ live count from it, so nobody states one. Write neither by hand:
3433
3543
 
3434
3544
  - **`ledger.mjs dispatch <ticket|pr> <member>`** — before the dispatch call,
3435
3545
  marks the member live on its row and appends it to `## Dispatched`. `dispatch
3436
- merge-bot` names the next bot itself. It refuses a name this run already
3437
- used (a replacement takes `-b`, `-c` …), a second live member on one ticket
3438
- or PR, and any implementer once the run is draining.
3546
+ merge-bot` names the next bot itself. It prints `{member, agent, ticket,
3547
+ line, created, total}`; `agent` is the definition the `task` call names — an
3548
+ implementer's comes off its row's `tier=` (phase 2's tier check states the
3549
+ mapping), a finisher's and a merge bot's are their own definitions, a
3550
+ review fix-applier's is `null`, and a conflict-hold fix-applier's is
3551
+ `fleet-implementer-slow-high`: its own section says how it is dispatched. It
3552
+ refuses a name this run already used (a replacement takes `-b`, `-c` …), a
3553
+ second live member on one ticket or PR, any implementer once the run is
3554
+ draining, an implementer whose row's `tier=` names no single definition
3555
+ or one with no file under `agents/`, and a fix-applier on a ledger the tick
3556
+ itself refuses.
3439
3557
  - **`ledger.mjs settle <member> <outcome>`** — rewrites the token to
3440
3558
  `<member>=<outcome>` in both places. Outcomes: `impl-N` = `PR#M | bailed |
3441
3559
  released | killed | tier-mismatch`; `fix-pr-M` = `applied:<head> | no-op |
@@ -3450,7 +3568,13 @@ live count from it, so nobody states one. Write neither by hand:
3450
3568
  `#M`'s row is genuinely the fallback (a live or settled PR-bound token on it,
3451
3569
  or nothing at all) rather than an unrelated row that merely shares the key.
3452
3570
  - **`ledger.mjs drain "<reason>"`** — the one drain marker per run; supply
3453
- stops, the review and merge sides keep going.
3571
+ stops, the review and merge sides keep going. It lives in this run's
3572
+ ledger, so the next run's rotation retires it with everything else.
3573
+ - **`ledger.mjs rotate`** — phase 0's first ledger write, every run: moves
3574
+ the file as-is to `ledger.<UTC YYYY-MM-DDTHHMMSSZ>.md` beside it under the
3575
+ same `<file>.lock`, and the next write starts the empty skeleton. Refused
3576
+ while the heartbeat mark is still beating or when the archive name already
3577
+ exists; no ledger is exit 0. Phase 0 states the guard's limit.
3454
3578
 
3455
3579
  `row` refuses a malformed member token anywhere in its text — one whose outcome
3456
3580
  is outside the vocabulary above, e.g. `merge-bot-1=dispatched` — at exit 2,
@@ -3458,7 +3582,7 @@ naming the token and writing nothing, because every reader would take it as a
3458
3582
  permanent settle.
3459
3583
 
3460
3584
  `→ PR#M` stays as the human-readable arrow; the tick reads only the `=`
3461
- tokens. `tier=alt` marks the every-5th-Pull member (phase 2), and `excluded ·
3585
+ tokens. `tier=<cell>` marks the every-5th-Pull member's cell (phase 2), and `excluded ·
3462
3586
  behind-pr:#M | behind-issue:#M` is an Exclusion (phase 1) — a ticket row like
3463
3587
  any other, never a section of its own.
3464
3588
 
@@ -3471,7 +3595,13 @@ flight, and the tick counts it against the reviewer cap. `ci=<run-id>:<attempt>:
3471
3595
  and `held-behind:#<lower>` are row tokens the same way (Phase 3), and so is
3472
3596
  `conflict-hold:#<pr>` — the one row token the merge bot writes itself, naming
3473
3597
  the row's own PR (`run-merge-bot.md` step 1). It is not an Exclusion: that
3474
- gates a ticket's claim, this a reviewed PR's merge.
3598
+ gates a ticket's claim, this a reviewed PR's merge. `label-off=<finisher-pr-M[-x]>`
3599
+ is yours, written before you take `ready-to-merge` off PR M on purpose (taking
3600
+ it off before you approve a push, or clearing one left on a moved head),
3601
+ naming that PR's latest finisher attempt: the tick reads a missing label as a
3602
+ finisher's miss only after the last attempt a `label-off=` names, so without
3603
+ it your own removal reads as one. `row` refuses a `label-off=` naming no
3604
+ `finisher-pr` member that `## Dispatched` or some row already carries.
3475
3605
 
3476
3606
  Plus two append-only lists:
3477
3607