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