@feigi/fleet-ctl 3.61.0 → 3.62.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agents/fleet-fix-applier.agent.md +4 -0
- package/package.json +1 -1
- package/scripts/dispatch-prompt.mjs +6 -4
- package/scripts/fleet-tick.mjs +119 -20
- package/skills/run-team/SKILL.md +112 -577
- package/skills/run-team/briefs/finisher.md +5 -0
- package/skills/run-team/briefs/fix-applier.md +7 -0
- package/skills/run-team/briefs/implementer.md +2 -0
- package/skills/run-team/briefs/merge-bot.md +1 -0
- package/skills/run-team/briefs/relabel.md +15 -0
- package/skills/run-team/briefs/review-runner.md +1 -0
- package/skills/run-team/references/phase-0.md +11 -13
package/skills/run-team/SKILL.md
CHANGED
|
@@ -27,15 +27,17 @@ correctly and ends its turn has reported nothing: the controller learns the
|
|
|
27
27
|
outcome only by re-reading artifacts and pinging, and a finding held only in
|
|
28
28
|
that member's context is lost. Members did exactly this in one run —
|
|
29
29
|
finishers, a reviewer and merge bots alike, the work done and only the
|
|
30
|
-
delivery missing.
|
|
30
|
+
delivery missing. Every brief's report paragraph says it. See
|
|
31
31
|
references/member-lifecycle.md.
|
|
32
32
|
|
|
33
|
-
**
|
|
34
|
-
member
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
33
|
+
**The implementer, fix-applier, finisher, merge-bot and review-runner briefs
|
|
34
|
+
each tell the member you do not acknowledge reports; you never write that line
|
|
35
|
+
yourself.** A member cannot see whether its report arrived, so silence
|
|
36
|
+
from you is indistinguishable from loss and it re-sends — three members did in
|
|
37
|
+
one run, each burning a turn, and in all three the original had in fact arrived.
|
|
38
|
+
Each of those templates under `briefs/` carries the line: *"The controller does
|
|
39
|
+
not acknowledge reports. Send once and exit; never re-send unless the controller
|
|
40
|
+
asks by name."*
|
|
39
41
|
|
|
40
42
|
**But a missing report is NOT evidence the member failed to send one — the
|
|
41
43
|
inbound direction drops AND delays messages.** Both were measured in one run,
|
|
@@ -114,9 +116,9 @@ changed.
|
|
|
114
116
|
**A label gate and a CI verdict are also taken by dispatched members, not
|
|
115
117
|
only by you** — the finisher labels, and the merge bot merges on its own
|
|
116
118
|
reading — and neither is dispatched to read this file, so neither can be
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
119
|
+
reached by stating the rule here. Each carries its own copy: the finisher's
|
|
120
|
+
in the instrument re-check block of `agents/fleet-finisher.agent.md`, the merge bot's inside
|
|
121
|
+
`merge-gate.mjs`, step 3 of `run-merge-bot.md`.
|
|
120
122
|
- **Re-pin only after a change you made deliberately.** The mid-run tooling fix
|
|
121
123
|
below is the one legitimate writer. Re-pinning to clear a refusal you cannot
|
|
122
124
|
explain discards the check.
|
|
@@ -141,9 +143,9 @@ was lost is that you pinged it by name with a concrete next action.
|
|
|
141
143
|
`finisher-pr-1184` reached for the same pattern minutes later — a proactive
|
|
142
144
|
warning is the only reason it did not repeat the stall. Its
|
|
143
145
|
`pgrep -f 'finish-finisher-pr-1184'` could never have matched any process, so
|
|
144
|
-
the poll it was waiting on was structurally incapable of firing.
|
|
145
|
-
|
|
146
|
-
|
|
146
|
+
the poll it was waiting on was structurally incapable of firing. This file is
|
|
147
|
+
yours, not theirs: the implementer, fix-applier and finisher briefs carry the
|
|
148
|
+
rule, as the line `A member runs its test suite in the foreground and blocks on it.`
|
|
147
149
|
|
|
148
150
|
**The scratch root is computed, never invented and never recorded.** No harness
|
|
149
151
|
supplies a scratch directory to a member, so a member left to name its own
|
|
@@ -156,7 +158,7 @@ re-invoked controller runs it, so nothing writes it down. It exits non-zero,
|
|
|
156
158
|
with its reason, when the root would sit inside a git work tree that does not
|
|
157
159
|
ignore it; that is an environment to fix, not a cue to pick another root.
|
|
158
160
|
`<scratch>` in this file is that path, resolved before you send anything: every
|
|
159
|
-
|
|
161
|
+
brief that carries one carries the absolute path you passed it — an
|
|
160
162
|
implementer's `<scratch>/impl-<N>/`, the recipe deriver's
|
|
161
163
|
`<scratch>/derive-recipe/`, a fix-applier's, a finisher's and a merge bot's
|
|
162
164
|
`<scratch>/pr<N>/…`, and a review runner's `scratch` argument, which is the
|
|
@@ -241,7 +243,7 @@ trap, opposite failure direction — so name the variable anything else
|
|
|
241
243
|
|
|
242
244
|
**The other deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
|
|
243
245
|
mechanism bites argv as well as loops, and that instance stays written out in the
|
|
244
|
-
fix-applier
|
|
246
|
+
fix-applier body and every refuter brief rather than here,
|
|
245
247
|
because the seats that inject faults are the ones that need it and a bot reads
|
|
246
248
|
gates without ever injecting one. Do not fold it into this block, and do not
|
|
247
249
|
restate this block there.
|
|
@@ -651,25 +653,15 @@ fleet has already judged unimplementable straight to the next member.
|
|
|
651
653
|
three causes, two labels: `ready-for-human` for hands or a fork;
|
|
652
654
|
`needs-triage` for a brief that names no *what*.
|
|
653
655
|
`gh issue edit <N> --remove-label ready-for-agent --add-label <label>` (no
|
|
654
|
-
`in-progress` to drop — it was never claimed), preceded by exactly one comment
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
> *Relabelled by the fleet controller.* Pulled for implementation and
|
|
665
|
-
> returned: the brief leaves a decision open. Open fork: <options, verbatim
|
|
666
|
-
> from the brief>.
|
|
667
|
-
|
|
668
|
-
- `ready-for-human` (hands):
|
|
669
|
-
|
|
670
|
-
> *Relabelled by the fleet controller.* Pulled for implementation and
|
|
671
|
-
> returned: needs human hands — <external access | manual testing |
|
|
672
|
-
> judgment during the work>: <one line>.
|
|
656
|
+
`in-progress` to drop — it was never claimed), preceded by exactly one comment,
|
|
657
|
+
the one `~/.fleet/bin/fleet-run dispatch-prompt.mjs render relabel --kind <kind> …`
|
|
658
|
+
prints. `--kind needs-triage` takes `--line`, the one-line missing decision;
|
|
659
|
+
`--kind fork` takes `--options`, the options verbatim from the brief, and is
|
|
660
|
+
the `ready-for-human` comment for a fork; `--kind hands` takes `--hands`,
|
|
661
|
+
one of external access, manual testing or judgment during the work, and
|
|
662
|
+
`--line`, and is the `ready-for-human` comment for hands. The three comments
|
|
663
|
+
live in `briefs/relabel.md`; `pull.mjs` posts its own one-line copy of the same
|
|
664
|
+
words when a Pull answer relabels, so a change to either is a change to both.
|
|
673
665
|
|
|
674
666
|
Neither label invokes anything: `/triage` is maintainer-run, and both labels
|
|
675
667
|
only stop the ticket costing a read per scan. These comments are the only
|
|
@@ -873,10 +865,10 @@ placeholders — the ticket number, the worktree abs path and branch
|
|
|
873
865
|
`<scratch>` as `scratch-root.mjs` printed it — and the
|
|
874
866
|
distilled brief (`<distilled brief>`): the title plus the `## Agent Brief`
|
|
875
867
|
comment or the issue body, whichever carries the brief, and its `Out of
|
|
876
|
-
scope`, pasted verbatim from the Pull's own read. Beyond those
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
868
|
+
scope`, pasted verbatim from the Pull's own read. Beyond those
|
|
869
|
+
`briefs/implementer.md` carries only its report paragraph, the
|
|
870
|
+
no-acknowledgement line, the foreground-suite line
|
|
871
|
+
— and a `staleness.mjs` **could not check** verdict with its
|
|
880
872
|
reason when the Pull got one, so the member's own re-derive step knows the
|
|
881
873
|
controller's probe could not look.
|
|
882
874
|
|
|
@@ -1660,6 +1652,22 @@ depth** guard table applied in code. Act on each line as it reads:
|
|
|
1660
1652
|
token. It repeats every tick while the token stays live past the threshold.
|
|
1661
1653
|
`--liveness-impl`, `--liveness-fix-pr`, `--liveness-finisher`,
|
|
1662
1654
|
`--liveness-merge-bot` and `--liveness-review` set the thresholds, in minutes.
|
|
1655
|
+
- `UNRECORDED <stem> (transcript exists, no ledger token)`, printed above the
|
|
1656
|
+
rows — the session directory holds a `<stem>.jsonl` whose stem is a member
|
|
1657
|
+
name no row token, `## Dispatched` entry or `## Retired` line names: a
|
|
1658
|
+
dispatch whose ledger write was forgotten. Record it with `ledger.mjs
|
|
1659
|
+
dispatch`, or confirm it is a stranger's member.
|
|
1660
|
+
Advice, like `CHECK-LIVENESS`: it resets no `quiet`, changes no row and
|
|
1661
|
+
frees no slot, it repeats every tick while it holds, and the folded line
|
|
1662
|
+
names it (`…; UNRECORDED <stem> persists — …`).
|
|
1663
|
+
- `NO-TRANSCRIPT <member> (live <age>m, no <session>/<member>.jsonl)`, printed
|
|
1664
|
+
above the rows — a live ledger token first seen more than
|
|
1665
|
+
`--no-transcript-after` minutes ago (default 5) has no transcript in the
|
|
1666
|
+
session directory: a dispatch whose `task` call was never made. Make the
|
|
1667
|
+
`task` call, or settle the token `killed`. Advice the same way, folded as
|
|
1668
|
+
`…; NO-TRANSCRIPT <member> persists — …`. Both lines read the session
|
|
1669
|
+
directory this run's phase-0 receipt names, else `--session <dir>`; with
|
|
1670
|
+
neither the tick skips them with one stderr line.
|
|
1663
1671
|
|
|
1664
1672
|
**Tier guards under Pull.** The per-dispatch `tier-check.mjs --batch` is
|
|
1665
1673
|
phase 2's own step, run by `tick --apply`: a mismatch it finds is the
|
|
@@ -2224,10 +2232,10 @@ named member per PR, `fix-pr-<pr#>` (the next suffix when that name is already
|
|
|
2224
2232
|
on record), never the PR's
|
|
2225
2233
|
implementer, its brief rendered with `dispatch-prompt.mjs render fix-applier
|
|
2226
2234
|
--kind review --member fix-pr-<pr#> …` and then recorded with `ledger.mjs
|
|
2227
|
-
dispatch <pr#> fix-pr-<pr#>` before the call. Its
|
|
2235
|
+
dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch,
|
|
2228
2236
|
the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`,
|
|
2229
2237
|
`<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>`
|
|
2230
|
-
in that
|
|
2238
|
+
in that brief is the absolute path `scratch-root.mjs` printed, the
|
|
2231
2239
|
`dispositions-<its name>.json` record's included. The fix-applier owns every per-PR ruling you once made
|
|
2232
2240
|
before dispatch: both mutual-exclusion scans, the suggested-fix re-derivation,
|
|
2233
2241
|
`refuted=false` ≠ apply, per-site measurement for a sibling-site extension, and
|
|
@@ -2246,8 +2254,8 @@ already on record — `dispatch` refuses a reused one — render its brief with
|
|
|
2246
2254
|
and dispatch it with the
|
|
2247
2255
|
`agent` that `ledger.mjs dispatch` printed, in the PR's existing worktree.
|
|
2248
2256
|
`dispatch` prints this member's definition, `fleet-fix-applier` whatever the
|
|
2249
|
-
row's `tier=` — read it off that output, never recall it. Its
|
|
2250
|
-
worktree
|
|
2257
|
+
row's `tier=` — read it off that output, never recall it. Its `conflict` brief carries the
|
|
2258
|
+
same worktree and branch identity paragraph, but in place of the review paragraphs:
|
|
2251
2259
|
bring `<branch>` current with `origin/main`, resolving every conflict by
|
|
2252
2260
|
`run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
|
|
2253
2261
|
head. Settle it `applied:<head>` — `no-op` if no conflict was left — which is
|
|
@@ -2264,7 +2272,7 @@ handling**.
|
|
|
2264
2272
|
**Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the
|
|
2265
2273
|
PR's current head that is not **solely** staleness: a `rebase-check` red, or
|
|
2266
2274
|
heavy jobs `skipped`, that comes only off the behind-count gets no fixer (the
|
|
2267
|
-
five-condition note in the fix-applier
|
|
2275
|
+
five-condition note in the fix-applier body states how to establish
|
|
2268
2276
|
that). The tick prints no `DISPATCH` for it, so you reconcile it yourself, and
|
|
2269
2277
|
it always goes after the review, never before. Take the common case, the
|
|
2270
2278
|
implementer's own first CI firing turning red before any review exists: the
|
|
@@ -2289,8 +2297,8 @@ refuses a reused name — render its brief with `dispatch-prompt.mjs render
|
|
|
2289
2297
|
fix-applier --kind red-check --member <name> …`, record it with `ledger.mjs dispatch <pr#> <name>`
|
|
2290
2298
|
before the call, and dispatch it with the `agent` that command printed
|
|
2291
2299
|
(`fleet-fix-applier`, as for a review fix-applier), in the PR's
|
|
2292
|
-
existing worktree. Its
|
|
2293
|
-
|
|
2300
|
+
existing worktree. Its `red-check` brief carries the same worktree and branch
|
|
2301
|
+
identity paragraph, but in place of the review paragraphs: read the failing job's
|
|
2294
2302
|
log, fix the cause, run `<testCmd>`, push, report the new head, and **stop**.
|
|
2295
2303
|
It is told outright not to watch, poll or wait for CI: your persistent Monitor
|
|
2296
2304
|
owns the next run on the pushed head, and the finisher gate — review returned
|
|
@@ -2306,9 +2314,9 @@ reach green" covers.
|
|
|
2306
2314
|
`dispositions-mismatch=<member>:<run>` for its latest review's run, and no later
|
|
2307
2315
|
fix-applier has landed — is one automatic retry, a review fix-applier named the
|
|
2308
2316
|
next suffix (`fix-pr-<M>-b`) and dispatched like the first, its brief rendered with `--kind dispositions-retry`. Its prompt is the
|
|
2309
|
-
first one's
|
|
2310
|
-
`<scratch>/
|
|
2311
|
-
|
|
2317
|
+
first one's with the retry paragraph added: `--mismatched-record`, the mismatched member's record
|
|
2318
|
+
`<scratch>/dispositions-<member>.json` it starts from, and `--violations`, the check's
|
|
2319
|
+
violation list as printed — the lines
|
|
2312
2320
|
`dispositions-check.mjs` printed, each naming a bucket, an index and a rule;
|
|
2313
2321
|
re-run the check for the mismatched member to reprint them. It writes its own
|
|
2314
2322
|
record, and when it reports you run the check for it exactly as for the first
|
|
@@ -2343,7 +2351,7 @@ arrives as ONE argument: a variable literally named `SETB` takes the value
|
|
|
2343
2351
|
while `fix-pr-1153` nearly retired a real review finding as non-reproducing after
|
|
2344
2352
|
the same shape handed both trees a single argv word and drew `exit 2` from each,
|
|
2345
2353
|
which is the signature of a correct refutation with nothing anomalous to notice.
|
|
2346
|
-
The fix-applier
|
|
2354
|
+
The fix-applier body and every refuter brief carry the rule and the safe
|
|
2347
2355
|
invocation form; the merge bot's brief is the wrong seat, because a bot
|
|
2348
2356
|
reads gates and never injects a fault.
|
|
2349
2357
|
|
|
@@ -2382,9 +2390,9 @@ review's test-run block captures into its log and the test-run agent reports as
|
|
|
2382
2390
|
dimension unrun, for the reason "no suite slot within <n> s — the host is at its
|
|
2383
2391
|
suite bound; not a test failure", with no retry inside the run: re-review it
|
|
2384
2392
|
under the next runner letter (`review-pr-<pr#>-b` after a first runner), as for
|
|
2385
|
-
a runner that reported `failed`.
|
|
2386
|
-
|
|
2387
|
-
command again
|
|
2393
|
+
a runner that reported `failed`. The implementer, fix-applier and finisher briefs
|
|
2394
|
+
carry the one-line rule: *Exit 75 from the suite is not a test result; run the
|
|
2395
|
+
command again.*
|
|
2388
2396
|
|
|
2389
2397
|
A slot holder killed without releasing is taken over by the next waiter under
|
|
2390
2398
|
the same `.reap` discipline as the ledger's lock; the wedges that discipline
|
|
@@ -2403,384 +2411,40 @@ substituting `<testCmd>` with nothing leaves it no gate at all.
|
|
|
2403
2411
|
|
|
2404
2412
|
**Where `<branch>` comes from:** the PR's head branch —
|
|
2405
2413
|
`gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut
|
|
2406
|
-
the worktree from.
|
|
2414
|
+
the worktree from. Pass it as `--branch`, because
|
|
2407
2415
|
the member cannot read it off git: phase 1 creates an already-open PR's worktree
|
|
2408
2416
|
with `--detach`, and there `git branch --show-current` prints nothing and exits 0
|
|
2409
2417
|
(measured 2026-09-18, git 2.50.1), so `git push origin
|
|
2410
2418
|
"HEAD:$(git branch --show-current)"` exits 128 on `fatal: invalid refspec
|
|
2411
|
-
'HEAD:'`.
|
|
2412
|
-
all.
|
|
2413
|
-
|
|
2414
|
-
|
|
2415
|
-
|
|
2416
|
-
|
|
2417
|
-
|
|
2418
|
-
|
|
2419
|
-
|
|
2420
|
-
|
|
2421
|
-
|
|
2422
|
-
|
|
2423
|
-
|
|
2424
|
-
> --
|
|
2425
|
-
|
|
2426
|
-
|
|
2427
|
-
|
|
2428
|
-
> Read `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` and run **steps 2, 3
|
|
2429
|
-
> and 5 only**: split apply-now/defer, commit, push, file every deferral as its
|
|
2430
|
-
> own issue with the label the finding's state calls for. Skip step 1 — the
|
|
2431
|
-
> review already ran — and steps 4 and 6: the controller owns the CI wait and
|
|
2432
|
-
> dispatches the finisher.
|
|
2433
|
-
>
|
|
2434
|
-
> **The review's result is `<scratch>/pr<pr>/<run>/review.json`** — the digest first
|
|
2435
|
-
> (`jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}'`),
|
|
2436
|
-
> then every finding (`jq '.survived'`, `jq '.unverified'`, `jq '.refuted'`).
|
|
2437
|
-
> Read it through `review-and-fix.md`'s **The review result file**, which holds
|
|
2438
|
-
> the rest of the recipes and every ruling on the findings: both
|
|
2439
|
-
> mutual-exclusion scans, the suggested-fix re-derivation, `refuted=false` ≠
|
|
2440
|
-
> apply, per-site measurement for a sibling-site extension, and `testEnvironment`
|
|
2441
|
-
> and `cwdAudit` before any result of the shared test run. Every one of those
|
|
2442
|
-
> rulings is yours — nobody upstream has made one, and the controller never
|
|
2443
|
-
> reads the findings.
|
|
2444
|
-
>
|
|
2445
|
-
> **Every factual claim your diff restates needs a settling command run
|
|
2446
|
-
> against the tree first** — the issue body is a lead, never a citation.
|
|
2447
|
-
> **No positional references** (`the closing/second/last X`); name the thing
|
|
2448
|
-
> semantically. **Never write a COUNT or a tally into prose; state the
|
|
2449
|
-
> property instead** — unless it is a past-tense record of a measurement you
|
|
2450
|
-
> performed, which stays as written; a present-tense claim about a live
|
|
2451
|
-
> property must be restated as a property (`every other test in the file`),
|
|
2452
|
-
> true at any count. **A settling grep over literal text takes `grep -F`, and
|
|
2453
|
-
> its zero counts only after the same command finds a line known to match.**
|
|
2454
|
-
>
|
|
2455
|
-
> **Apply `survived` findings. A finding in `unverified` whose refuters ran and
|
|
2456
|
-
> crashed or abstained always defers** — and which it is, you read off
|
|
2457
|
-
> `refutersDispatched` and `refutersInconclusive`, never off severity and never
|
|
2458
|
-
> off an empty vote list: `refutersDispatched` above zero with nothing decided
|
|
2459
|
-
> means every refuter dispatched against it died or abstained, and
|
|
2460
|
-
> `refutersInconclusive` counts the ones that abstained. Severity records how much a
|
|
2461
|
-
> finding would matter if true, never whether anything looked. Say *in the
|
|
2462
|
-
> deferral* which it was rather than that it went unchecked. Name a crash as
|
|
2463
|
-
> crashed refuters — the review re-dispatched each crash once already and
|
|
2464
|
-
> reports what died again, so a deferral that names the crash can still be
|
|
2465
|
-
> re-verified. An abstention is not a crash: cite the inconclusive runs each
|
|
2466
|
-
> abstaining refuter named in its `reason`, and never describe its refuters as
|
|
2467
|
-
> crashed. **A `suggestion` is also in `unverified`,
|
|
2468
|
-
> for a different reason — `refutersDispatched` of zero, the 0-refuter budget
|
|
2469
|
-
> the review gives that band by policy — and the rule below, not this one,
|
|
2470
|
-
> covers it.**
|
|
2471
|
-
>
|
|
2472
|
-
> **A `suggestion` is budgeted 0 refuters, so it is unchecked until you check
|
|
2473
|
-
> it.** For each one, first decide scope: is it inside the scope of the PR's own
|
|
2474
|
-
> ticket, or a different piece of work? **Out of scope → defer and file, never
|
|
2475
|
-
> apply** — but the claim bar runs first: an out-of-scope suggestion whose
|
|
2476
|
-
> claim is about shape (`claimKind: shape`) gets no refuter and goes to the
|
|
2477
|
-
> closed suggestion-band record, and every other one gets the same refuter an
|
|
2478
|
-
> in-scope one does, dispatched the same way, before it is filed.
|
|
2479
|
-
> **In scope → dispatch ONE refuter** against the finding before
|
|
2480
|
-
> touching the tree, biased to refuse, and hand it the prompt below with one
|
|
2481
|
-
> substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path
|
|
2482
|
-
> under your own run root — `mktemp -d` once per round for
|
|
2483
|
-
> `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids
|
|
2484
|
-
> restart at 1 each round too — and write that absolute path into the
|
|
2485
|
-
> refuter's prompt in its place; a refuter never derives its own path:
|
|
2486
|
-
>
|
|
2487
|
-
> > Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by
|
|
2488
|
-
> > RUNNING something — compile it, run the test, apply the mutation. Do not
|
|
2489
|
-
> > reason your way to agreement. Observe that run synchronously — run the
|
|
2490
|
-
> > command, wait for it, read its exit code. Never poll a log file for a
|
|
2491
|
-
> > completion marker: prefer ONE blocking run to a poll loop, and treat its
|
|
2492
|
-
> > return as permission to look, never as the answer. Reading a log the run has
|
|
2493
|
-
> > already finished writing is fine; waiting on one is not. If you match a test
|
|
2494
|
-
> > reporter's own output, accepting both `ℹ` and `#` is necessary but NOT
|
|
2495
|
-
> > sufficient — strip SGR escapes first as well. node's prefix moves with the
|
|
2496
|
-
> > node version and with whether stdout is a TTY, and color wraps the whole line
|
|
2497
|
-
> > so it begins with ESC and no prefix anchor matches at all, which returns
|
|
2498
|
-
> > empty at exit 0 — indistinguishable from a hung run and from a run of zero
|
|
2499
|
-
> > tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=`
|
|
2500
|
-
> > empty still enables color, so it is not a control. State your search scope
|
|
2501
|
-
> > AND what your pattern would have missed. A grep over one ref does not
|
|
2502
|
-
> > support a claim about history; a pattern built from the token a diff removed
|
|
2503
|
-
> > does not support a claim that the category is empty.
|
|
2504
|
-
> >
|
|
2505
|
-
> > When your check scores a mutant killed or a test red, run only in your own
|
|
2506
|
-
> > copy of the tree, and these rules decide it and nothing else:
|
|
2507
|
-
> >
|
|
2508
|
-
> > **Valid red:** a run that completed — the command returned on its own, with no
|
|
2509
|
-
> > signal and no timeout, deadline or kill having fired — in which the test the
|
|
2510
|
-
> > claim names is reported failing. An exit ≠ 0 with no failing test is not red,
|
|
2511
|
-
> > and a different test failing is not red for this claim. A red in the full
|
|
2512
|
-
> > suite only triggers a narrowed run; it is never evidence on its own.
|
|
2513
|
-
> >
|
|
2514
|
-
> > **Narrowed run:** the Test entrypoint with arguments appended, `<testCmd>
|
|
2515
|
-
> > <args>`. That appended arguments reach the Test entrypoint is all that is
|
|
2516
|
-
> > promised about them, so a narrowed run counts only if it reports `tests` > 0
|
|
2517
|
-
> > and its output names the claimed test. If no narrowing can be proven, run the
|
|
2518
|
-
> > full `<testCmd>` and read the named test's own result from its output.
|
|
2519
|
-
> >
|
|
2520
|
-
> > **Kill:** the mutant produced a valid red in a narrowed run, and the same
|
|
2521
|
-
> > narrowed command, in the same tree with the mutant reverted, ran a valid green
|
|
2522
|
-
> > with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
|
|
2523
|
-
> > completed exit ≠ 0 with the named test not failing is not a kill, and no kill
|
|
2524
|
-
> > stands without that green run on the unmutated tree. The result is
|
|
2525
|
-
> > inconclusive, never a kill, when the red does not reproduce in the narrowed
|
|
2526
|
-
> > run, when the unmutated tree is red too, or when no usable run exists.
|
|
2527
|
-
> >
|
|
2528
|
-
> > **Evidence line:** every kill and every valid red you claim carries one line
|
|
2529
|
-
> > in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>;
|
|
2530
|
-
> > baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the
|
|
2531
|
-
> > review's shared run carries the `red:` half alone.
|
|
2532
|
-
> >
|
|
2533
|
-
> > This refuter has no abstain: a run that could not decide — neither a valid red
|
|
2534
|
-
> > nor a valid green — is no kill and no refutation, so name the runs in
|
|
2535
|
-
> > `reason`, each with its evidence line, and leave `refuted` true, so the
|
|
2536
|
-
> > suggestion defers on the record instead of applying on a check that decided
|
|
2537
|
-
> > nothing.
|
|
2538
|
-
> >
|
|
2539
|
-
> > A failure injection with
|
|
2540
|
-
> > no positive control has produced NO result, never a negative one. Before you
|
|
2541
|
-
> > read an injected fault — an env var, an argv word, a mutant — as having had
|
|
2542
|
-
> > no effect, prove the injection reached the child: one run whose output
|
|
2543
|
-
> > differs with it present versus absent, or the child echoing the injected
|
|
2544
|
-
> > value back. Uncontrolled, the cell is unrun — say so in your verdict instead
|
|
2545
|
-
> > of reporting a no-effect result. Build such an invocation as an array
|
|
2546
|
-
> > expanded braced and quoted —
|
|
2547
|
-
> > `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
|
|
2548
|
-
> > assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
|
|
2549
|
-
> > unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
|
|
2550
|
-
> > zsh passes ONE argument, sets a variable literally named `SETB` to
|
|
2551
|
-
> > `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not
|
|
2552
|
-
> > the portable spelling either: measured, bash word-splits it into `SETB=1`
|
|
2553
|
-
> > and `BADJ=1[@]`, so the injection variable is set to a corrupted value,
|
|
2554
|
-
> > while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set,
|
|
2555
|
-
> > exit 0. Everything you
|
|
2556
|
-
> > write — mutants, fixtures,
|
|
2557
|
-
> > scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else;
|
|
2558
|
-
> > the checkout and any worktree are never write targets, though
|
|
2559
|
-
> > `git show`/`git archive` at a pinned ref read fine anywhere. Chain the
|
|
2560
|
-
> > directory change into the command, `cd "$D" && git …`, never
|
|
2561
|
-
> > `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in
|
|
2562
|
-
> > the checkout — and bracket a fixture's own git with
|
|
2563
|
-
> > `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to
|
|
2564
|
-
> > the host repository, and `fatal: not a git repository` (exit 128) is the
|
|
2565
|
-
> > usual pass, not a failure — an outer repository whose ignore rules cover
|
|
2566
|
-
> > your scratch dir is a pass too; before any `git commit` it must resolve to
|
|
2567
|
-
> > your scratch path, which catches a forgotten `git init` under any enclosing
|
|
2568
|
-
> > repository — compare resolved forms (`realpath`), since `--show-toplevel`
|
|
2569
|
-
> > can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under
|
|
2570
|
-
> > its resolved name.
|
|
2571
|
-
>
|
|
2572
|
-
> Survives → apply it, with one hold: if its refuter reports a blast radius
|
|
2573
|
-
> touching lines another finding also changes, that is the mutual-exclusion
|
|
2574
|
-
> scan's second input — rule the pair before either change reaches the tree;
|
|
2575
|
-
> you hold every finding, so only you can see that the two cannot both land. Refuted → defer and file it, and
|
|
2576
|
-
> say the refutation in the issue body. **Apply only what survives — no report is not a survival.** A
|
|
2577
|
-
> refuter you never hear from leaves the finding exactly as unchecked as it
|
|
2578
|
-
> arrived, so it defers like a refuted one.
|
|
2579
|
-
>
|
|
2580
|
-
> **Out of scope, the refuter decides only where the suggestion is filed — it
|
|
2581
|
-
> defers either way, never applied.** Refuted → the closed suggestion-band
|
|
2582
|
-
> record, never an open issue. Survived, or its refuter crashed or abstained →
|
|
2583
|
-
> its own open issue labelled `needs-triage`, citing the verdict, or the run
|
|
2584
|
-
> that crashed, in the body. There is no cap on these refuters: count the ones
|
|
2585
|
-
> you dispatch against out-of-scope suggestions, since your report names that
|
|
2586
|
-
> count.
|
|
2587
|
-
>
|
|
2588
|
-
> **A finding's `suggested_fix` is a hypothesis, not a patch — the review never
|
|
2589
|
-
> ran it.** Only the claim is verified adversarially; the remedy text is unchecked.
|
|
2590
|
-
> Three were wrong as written in one run: a stated end state that dropped a
|
|
2591
|
-
> load-bearing option and measured RED, an assertion against a property the test
|
|
2592
|
-
> helper does not expose (`TypeError`), and an enumeration that stopped short of
|
|
2593
|
-
> two further stale clauses — one of them false in the *dangerous* direction. Run
|
|
2594
|
-
> the remedy before you commit it, and re-derive an assertion from the post-fix
|
|
2595
|
-
> tree rather than from the finding, since a sibling finding may edit the very
|
|
2596
|
-
> text it asserts on.
|
|
2597
|
-
>
|
|
2598
|
-
> **Retrieve that report yourself; do not wait to be handed it — this covers the
|
|
2599
|
-
> refuters YOU dispatch, and only those.** The review's own specialists do leave
|
|
2600
|
-
> transcripts, but nothing gives you their address: the review had `agent()`
|
|
2601
|
-
> return their findings into the script, so the result file holds their findings
|
|
2602
|
-
> and names no transcript, and nothing on disk indexes a transcript by PR or
|
|
2603
|
-
> dimension. Hunting their paths gets you nothing; read the file. A report from a refuter you spawned is
|
|
2604
|
-
> different — it surfaces to the controller rather than to you, and waiting for a
|
|
2605
|
-
> relay that never comes strands the finding. Its transcript is at the output file
|
|
2606
|
-
> named in your spawn result, and its report is the last record:
|
|
2607
|
-
>
|
|
2608
|
-
> A depth-2 helper cannot dispatch further (`task.maxRecursionDepth: 2`); reach it directly instead, by its full dotted id (`<member>.<helper>`), via `hub send` — delivered, woken, no transcript workaround needed.
|
|
2609
|
-
>
|
|
2610
|
-
> If retrieval comes back empty, ask the controller by name. Only when neither
|
|
2611
|
-
> works is the finding **unchecked** — defer and file it, and say so in the body. This is
|
|
2612
|
-
> `review-and-fix.md`'s **Specialists** rule; it reaches you here because the
|
|
2613
|
-
> steps that point at it are the ones you skip.
|
|
2614
|
-
>
|
|
2615
|
-
> The CI facts in that file apply to you — a `rebase-check` red, or heavy jobs
|
|
2616
|
-
> `skipped`, **solely** off a non-zero behind-count, is staleness and not a
|
|
2617
|
-
> failure. Never rebase to clear it. **`solely` is the load-bearing word:**
|
|
2618
|
-
> `ci.yml`'s `rebase-check` exits 1 on five conditions and only one is
|
|
2619
|
-
> staleness, so a non-zero behind-count does not by itself settle which fired.
|
|
2620
|
-
> The job log names the condition — and because the staleness condition exits
|
|
2621
|
-
> before the merge-commit condition is evaluated, the log is silent on that one
|
|
2622
|
-
> by construction, so measure it separately with
|
|
2623
|
-
> `git fetch origin && git rev-list --merges --count "origin/<base>..HEAD"` —
|
|
2624
|
-
> keep the fetch, or a stale local `origin/<base>` widens the range over the
|
|
2625
|
-
> base's own merge commits and reports a merge commit this branch never added.
|
|
2626
|
-
> A non-zero count does not send you to a local rebase either: the merge bot's
|
|
2627
|
-
> step-1 `gh pr update-branch --rebase` drops merge commits too
|
|
2628
|
-
> (`run-merge-bot.md` step 1), so both conditions clear on that one server-side
|
|
2629
|
-
> rebase. What it buys you is knowing the red was never solely staleness.
|
|
2630
|
-
>
|
|
2631
|
-
> **Run `<testCmd>` from the worktree before committing**, copied verbatim.
|
|
2632
|
-
> `tests 0` is a FAILED run, not a pass. Red or zero-test → fix it, or move that
|
|
2633
|
-
> finding to defer; never commit over it. **Never `--no-verify`** — a failing
|
|
2634
|
-
> hook is a finding you report, not an obstacle you route around. Report the test
|
|
2635
|
-
> result with your SHA. Nothing re-reviews this commit: the review ran against a
|
|
2636
|
-
> snapshot cut before your edits existed, and a refuter checked the finding's
|
|
2637
|
-
> claim, never your patch.
|
|
2638
|
-
>
|
|
2639
|
-
> **A test you ADD must kill its own mutant** — break what it pins, confirm it and
|
|
2640
|
-
> only it goes red and that the red is a kill by the rules below, restore. **Then
|
|
2641
|
-
> a change it should *not* catch, staying green** — else you proved it fails, not
|
|
2642
|
-
> that it discriminates: a pin asserting whole-file text clears "it and only it
|
|
2643
|
-
> goes red" and still reddens on any edit (measured). A green suite says nothing
|
|
2644
|
-
> about a new test: one pin this run survived the exact mutation it was named for.
|
|
2645
|
-
>
|
|
2646
|
-
> **Valid red:** a run that completed — the command returned on its own, with
|
|
2647
|
-
> no signal and no timeout, deadline or kill having fired — in which the test
|
|
2648
|
-
> the claim names is reported failing. An exit ≠ 0 with no failing test is not
|
|
2649
|
-
> red, and a different test failing is not red for this claim. A red in the full
|
|
2650
|
-
> suite only triggers a narrowed run; it is never evidence on its own.
|
|
2651
|
-
>
|
|
2652
|
-
> **Narrowed run:** the Test entrypoint with arguments appended,
|
|
2653
|
-
> `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
|
|
2654
|
-
> that is promised about them, so a narrowed run counts only if it reports
|
|
2655
|
-
> `tests` > 0 and its output names the claimed test. If no narrowing can be
|
|
2656
|
-
> proven, run the full `<testCmd>` and read the named test's own result from its
|
|
2657
|
-
> output.
|
|
2658
|
-
>
|
|
2659
|
-
> **Kill:** the mutant produced a valid red in a narrowed run, and the same
|
|
2660
|
-
> narrowed command, in the same tree with the mutant reverted, ran a valid green
|
|
2661
|
-
> with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
|
|
2662
|
-
> completed exit ≠ 0 with the named test not failing is not a kill, and no kill
|
|
2663
|
-
> stands without that green run on the unmutated tree. The result is
|
|
2664
|
-
> inconclusive, never a kill, when the red does not reproduce in the narrowed
|
|
2665
|
-
> run, when the unmutated tree is red too, or when no usable run exists.
|
|
2666
|
-
>
|
|
2667
|
-
> **Evidence line:** every kill and every valid red you claim carries one line
|
|
2668
|
-
> in the claim's own free-text field:
|
|
2669
|
-
> `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
|
|
2670
|
-
> A failing-test finding filed off the review's shared run carries the `red:`
|
|
2671
|
-
> half alone.
|
|
2672
|
-
>
|
|
2673
|
-
> An inconclusive result proves nothing about the test: do not report the test
|
|
2674
|
-
> as proven, and measure again in a clean state. Put each kill's evidence line in
|
|
2675
|
-
> your report, beside the test result.
|
|
2676
|
-
>
|
|
2677
|
-
> **A mutation that never landed is not a green — it is a cell that did not
|
|
2678
|
-
> run.** Same rule for any fault you inject to see what breaks: prove the
|
|
2679
|
-
> injection reached the child before you read its result — one run whose output
|
|
2680
|
-
> differs with the injection present versus absent, or the child echoing the
|
|
2681
|
-
> injected value back. Without one, a probe that exits 0 reporting the mutant
|
|
2682
|
-
> behaving exactly like its baseline is indistinguishable from a real no-effect
|
|
2683
|
-
> result, and a reproduction that never happened reads as a refutation. Build
|
|
2684
|
-
> such an invocation as an array expanded braced and quoted —
|
|
2685
|
-
> `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
|
|
2686
|
-
> assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
|
|
2687
|
-
> unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
|
|
2688
|
-
> zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`,
|
|
2689
|
-
> never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable
|
|
2690
|
-
> spelling either: measured, bash word-splits it into `SETB=1` and
|
|
2691
|
-
> `BADJ=1[@]`, so the injection variable is set to a corrupted value, while
|
|
2692
|
-
> zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0.
|
|
2693
|
-
>
|
|
2694
|
-
> **Commit BEFORE you mutate, and restore with `cp`, never a git discard.**
|
|
2695
|
-
> `git checkout -- <file>` reverts the whole file, not your mutant — so it also
|
|
2696
|
-
> eats uncommitted edits you made earlier, and the "clean baseline" you measure
|
|
2697
|
-
> next is silently the reverted file. Two members hit this in one run; one lost
|
|
2698
|
-
> prose edits and caught it only because a non-catch control failed. Copy the
|
|
2699
|
-
> file aside and copy it back. Better still, mutate a copy under
|
|
2700
|
-
> `<scratch>/pr<N>/mutate/` and leave the worktree untouched — that is what
|
|
2701
|
-
> refuters are already required to do, and it has no blast radius at all.
|
|
2702
|
-
>
|
|
2703
|
-
> **Never `git stash` or `git stash pop` here either — a WIP commit is the
|
|
2704
|
-
> substitute, not a second scratch mechanism: `git commit -m wip`, then
|
|
2705
|
-
> restore or amend once you're back to real work.** The stash stack is
|
|
2706
|
-
> repo-global too, not per-worktree or per-session — the same `refs/stash`
|
|
2707
|
-
> every concurrent member and the main checkout share, not partitioned the
|
|
2708
|
-
> way `<scratch>/pr<N>/mutate/` above is. A bare pop takes whichever entry is
|
|
2709
|
-
> on top, from any worktree, silently — rc 0, no error — when the tree
|
|
2710
|
-
> receiving it is clean on the affected paths, and refuses only when that
|
|
2711
|
-
> tree is already dirty there. A bare `git stash` (push) does not reach into
|
|
2712
|
-
> a sibling's tree, so that half is not the risk — the pop is. Nothing
|
|
2713
|
-
> partitions the stack; this prohibition is the whole of the protection.
|
|
2714
|
-
>
|
|
2715
|
-
> **Report LAST, and only once nothing can still change.** A report you have
|
|
2716
|
-
> sent **pins that SHA** for the controller, which dispatches a finisher against
|
|
2717
|
-
> it. If a further instruction arrives after you have reported, reply saying the
|
|
2718
|
-
> SHA is moving *before* you touch the tree again — do not silently do the work
|
|
2719
|
-
> and re-report. Measured: three members in one run sent a final report and kept
|
|
2720
|
-
> working; one had its worktree audited mid-mutation, another handed over a SHA
|
|
2721
|
-
> that was two commits stale, and a finisher dispatched on either would have
|
|
2722
|
-
> halted on a diverged head.
|
|
2723
|
-
>
|
|
2724
|
-
> **Before you report, write every ruling to `<scratch>/dispositions-<your name>.json`**,
|
|
2725
|
-
> `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as — the record the controller checks with
|
|
2726
|
-
> `dispositions-check.mjs` before it dispatches any finisher. It is
|
|
2727
|
-
> `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}`
|
|
2728
|
-
> — `run` the `<run>` of the review path above, which the check holds against the
|
|
2729
|
-
> review the PR's latest `reviewed=` names: a record written against an earlier
|
|
2730
|
-
> review, a same-head one included, is a mismatch. One entry per
|
|
2731
|
-
> `survived` finding and per `unverified` finding, plus one per `refuted`
|
|
2732
|
-
> finding you reverse. Each entry carries `bucket`
|
|
2733
|
-
> (`survived|unverified|refuted`), `index` (its position in that bucket of the
|
|
2734
|
-
> review file), `scope` (`in|out`), `claimKind` (`behavior|shape`) and
|
|
2735
|
-
> `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the
|
|
2736
|
-
> number you filed it to or commented on), `verdictPath` (a suggestion's
|
|
2737
|
-
> refuter verdict file, in scope and, above the claim bar, out of scope) and
|
|
2738
|
-
> `remedyFiles` (the files its remedy names). An out-of-scope suggestion whose
|
|
2739
|
-
> refuter crashed before any verdict reached you still names the path its
|
|
2740
|
-
> verdict would have taken. A `refuted` entry carries `scope`, `claimKind` and `disposition`
|
|
2741
|
-
> like every other entry, and a non-empty `reason` holding the evidence that
|
|
2742
|
-
> reverses it; a missing or blank `reason` is a mismatch. A finding with no
|
|
2743
|
-
> `line`, or on a line the PR's diff touched —
|
|
2744
|
-
> `git diff` from its merge-base with `origin/main` to the review's head — is
|
|
2745
|
-
> in scope whatever its `scope` says. An in-scope `survived` finding you defer
|
|
2746
|
-
> carries `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or
|
|
2747
|
-
> `remedy-outside-diff`; the last needs `remedyFiles` to name a file the PR's
|
|
2748
|
-
> diff does not touch, and for a `critical` or `important` finding it sends the
|
|
2749
|
-
> PR to a human instead of passing. Any
|
|
2750
|
-
> other reason, none, or a `survived` or `unverified` finding with no entry is
|
|
2751
|
-
> a mismatch, and the PR gets no finisher. `disposition` has no `dismiss`: an
|
|
2752
|
-
> in-scope `survived` finding verified correct, needing no change, is deferred
|
|
2753
|
-
> with `reason` `false-rationale` and filed on the closed suggestion-band
|
|
2754
|
-
> record.
|
|
2755
|
-
>
|
|
2756
|
-
> Then write your report to the file your brief names,
|
|
2757
|
-
> `<scratch>/reports/<your name>.json`: `head` the pushed SHA, `applied` and
|
|
2758
|
-
> `deferred` your apply/defer split by bucket and index, each deferral's issue
|
|
2759
|
-
> number on its `deferred` entry, the deferral issues as `{issue, subject}`
|
|
2760
|
-
> entries — `filed` for every issue step 5 created, and `unrecorded` for one
|
|
2761
|
-
> whose `ledger.mjs filed` failed twice, which the controller's settle records —
|
|
2762
|
-
> `dispositionsRecord` your record's path and `testRun` your test result. Then
|
|
2763
|
-
> send the one line your brief gives, `<your name>: <outcome> <path>`, and exit.
|
|
2764
|
-
> **Deferring everything is a normal
|
|
2765
|
-
> outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
|
|
2766
|
-
> index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and your
|
|
2767
|
-
> report's `outcome` is `no-op`, its `head` the unchanged SHA. Say it
|
|
2768
|
-
> explicitly — silence there is indistinguishable from a member that died. Never
|
|
2769
|
-
> manufacture a commit to make CI fire.
|
|
2770
|
-
|
|
2771
|
-
**Put the standing CI facts in that prompt, not in per-event messages** —
|
|
2419
|
+
'HEAD:'`. A brief rendered without it would leave the push no destination at
|
|
2420
|
+
all, which is why the renderer requires it.
|
|
2421
|
+
|
|
2422
|
+
**What a fix-applier receives.** Its standing text — the worktree and
|
|
2423
|
+
session-root discipline, the review result file and every ruling on it, the
|
|
2424
|
+
claim discipline, the refuter prompt, the kill rule, the stash prohibition, the
|
|
2425
|
+
dispositions record and the report rules — is the body of
|
|
2426
|
+
`agents/fleet-fix-applier.agent.md`, which the harness injects as its system
|
|
2427
|
+
prompt, so none of it is pasted. The brief carries what varies, and the
|
|
2428
|
+
renderer prints it: `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
|
|
2429
|
+
fix-applier --kind <review|conflict|dispositions-retry|red-check> --member <name>
|
|
2430
|
+
--worktree <abs-path> --branch <branch> --testCmd <testCmd> --scratch <scratch>`,
|
|
2431
|
+
plus `--pr <pr#> --run <run>` for a review or a dispositions retry and
|
|
2432
|
+
`--mismatched-record <path> --violations <list>` for a retry. Then
|
|
2433
|
+
`ledger.mjs dispatch <pr#> <name>` records it before the call.
|
|
2434
|
+
|
|
2435
|
+
**The standing CI facts are in the fix-applier body, not in per-event messages** —
|
|
2772
2436
|
otherwise you send "your red is staleness, do not rebase" once per member per
|
|
2773
|
-
merge. `review-and-fix.md` states them; the
|
|
2437
|
+
merge. `review-and-fix.md` states them; the body says they apply.
|
|
2774
2438
|
|
|
2775
2439
|
**The fix-applier pushes and exits — it does not hold the CI wait.** You own the
|
|
2776
2440
|
persistent Monitor; a turn-based member re-reading `gh pr checks` each idle cycle
|
|
2777
|
-
rebuilds a 100k-token context for nothing the Monitor lacks. The
|
|
2778
|
-
|
|
2441
|
+
rebuilds a 100k-token context for nothing the Monitor lacks. The body
|
|
2442
|
+
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
|
|
2779
2443
|
diff-validating `check` job is green **and no
|
|
2780
2444
|
heavy job is in `failure`** (the heavy diff-validating suites — not the
|
|
2781
2445
|
`rebase-check` currency gate; a `skipped` heavy job is behind-count staleness and
|
|
2782
2446
|
fine — **solely** off that count, which is a condition to establish rather than
|
|
2783
|
-
infer, see the five-condition note in the fix-applier
|
|
2447
|
+
infer, see the five-condition note in the fix-applier body) — or
|
|
2784
2448
|
`ci-state.mjs` reads `verdict: "no-ci"`, see below — **and once the PR's review
|
|
2785
2449
|
has returned and its fix-applier, if one was dispatched, has sent its report,
|
|
2786
2450
|
which the CI-completes edge above states in full** — dispatch a
|
|
@@ -2889,12 +2553,12 @@ a minute apart showed *different* mutants, so a member's report and any single
|
|
|
2889
2553
|
finisher that cannot see the tree it labels cannot vouch for it, so none of
|
|
2890
2554
|
the script's steps is run by hand to get past a halt. A finisher that
|
|
2891
2555
|
verifies the dirt is harmless and labels anyway has substituted the rule's
|
|
2892
|
-
|
|
2893
|
-
|
|
2894
|
-
|
|
2895
|
-
|
|
2896
|
-
|
|
2897
|
-
|
|
2556
|
+
purpose for the rule, and you find out at merge time. The halt-cause block in
|
|
2557
|
+
`agents/fleet-finisher.agent.md` holds the script call and what each exit
|
|
2558
|
+
means, and a bare SHA mismatch names no cause. **Pass `--testCmd` too** —
|
|
2559
|
+
the same string you passed the workflow and the fix-applier — because duty
|
|
2560
|
+
2's mutation gate runs it and nothing else hands the finisher one; the renderer
|
|
2561
|
+
refuses a finisher brief rendered without it.
|
|
2898
2562
|
2. **Confirm every deferral — and every claimed APPLY — has a home that outlives
|
|
2899
2563
|
the merge.** The test is a durable home, not a tracker number: a tracker
|
|
2900
2564
|
issue and a committed in-tree comment both qualify, and for a finding whose
|
|
@@ -3012,122 +2676,17 @@ a minute apart showed *different* mutants, so a member's report and any single
|
|
|
3012
2676
|
printed, the JSON line, so a `rebase` halt's report carries the output of
|
|
3013
2677
|
`git cherry <pin> HEAD origin/main` that its `evidence` holds.
|
|
3014
2678
|
|
|
3015
|
-
**
|
|
3016
|
-
|
|
3017
|
-
|
|
3018
|
-
|
|
3019
|
-
top of this file, which no finisher
|
|
3020
|
-
|
|
3021
|
-
|
|
3022
|
-
|
|
3023
|
-
|
|
3024
|
-
>
|
|
3025
|
-
|
|
3026
|
-
> exit 2 (the check could not answer) both halt you: report what it printed,
|
|
3027
|
-
> add no label, and do NOT re-read the script that gave you the reading.
|
|
3028
|
-
> `--repo` is required and the spelling is the point — the run's baseline lives
|
|
3029
|
-
> in the audited checkout's gitignored `.fleet/`, which the scratch worktree
|
|
3030
|
-
> you take at duty 2 does not carry, so a bare invocation from there exits 2 on
|
|
3031
|
-
> a missing baseline instead of comparing anything. The `env -u GIT_DIR -u
|
|
3032
|
-
> GIT_WORK_TREE` wrapper guards against an ambient `GIT_DIR` in your own shell
|
|
3033
|
-
> pointing this check at the wrong tree — the script's own internal unset
|
|
3034
|
-
> cannot reach back and fix a path you already resolved wrong. The baseline
|
|
3035
|
-
> itself names the tree to audit: a cross-workspace run pinned it once at
|
|
3036
|
-
> phase 0, and your `--repo` only locates that baseline, never the audited
|
|
3037
|
-
> tree — so an exit 2 naming a moved or unreadable audited tree is a halt
|
|
3038
|
-
> like every other, not a spelling for you to correct.
|
|
3039
|
-
|
|
3040
|
-
**Give the finisher the test-run verdict rule verbatim too.** Duty 2 runs
|
|
3041
|
-
`<testCmd>` for the acceptance mutation, and the finisher's agent definition
|
|
3042
|
-
carries a copy of the rule below. A `node --test`
|
|
3043
|
-
stopped by an outside `timeout` still prints a summary, covering only the tests
|
|
3044
|
-
it reached, so reading that summary alone reads a partial suite as a whole one:
|
|
3045
|
-
|
|
3046
|
-
> **A test run is a verdict only if it ran to completion — and you read that
|
|
3047
|
-
> off the test command's own exit status.**
|
|
3048
|
-
> Redirect the run's output to a file in your scratch directory and read the
|
|
3049
|
-
> command's own `$?` straight after it, then read the file. In an `eval` cell
|
|
3050
|
-
> there is no `$?`: spawn `<testCmd>` with its output going to that file and
|
|
3051
|
-
> read the exit code and the signal off the spawn result — `exitCode` and
|
|
3052
|
-
> `signalCode` on Bun's `spawnSync`, `returncode` on Python's `subprocess.run`,
|
|
3053
|
-
> which is negative for a signal. Never read the status of
|
|
3054
|
-
> `<testCmd> | tail` or `<testCmd> | grep`: a pipeline's status is its
|
|
3055
|
-
> last stage's, so the filter's 0 hides the run's own exit, and the array that
|
|
3056
|
-
> holds the earlier stages' statuses is spelled differently per shell. A run is
|
|
3057
|
-
> a verdict only when that exit status is 0 **and** its summary shows `tests`
|
|
3058
|
-
> above 0 and `cancelled` 0. A summary line without that
|
|
3059
|
-
> is not a verdict, whatever pass count it prints.
|
|
3060
|
-
> **A run completed when the command itself returned on its own** — an exit
|
|
3061
|
-
> code, no signal, and no `timeout`, deadline or kill of yours having fired.
|
|
3062
|
-
> Judge that by how the run ended, never by its `cancelled` count: a failing
|
|
3063
|
-
> `before` hook or a per-test `timeout` cancels tests inside a run that
|
|
3064
|
-
> completed, and a SIGTERM'd `node --test` can exit 1 with `cancelled` above 0
|
|
3065
|
-
> in a run that did not.
|
|
3066
|
-
> **Any run that did not complete is a killed run** — 124 (`timeout`), 137
|
|
3067
|
-
> (SIGKILL), 143 (SIGTERM), a signal in the spawn result, an `eval` cell's
|
|
3068
|
-
> deadline — and read for green it is FAILED, the same bucket as
|
|
3069
|
-
> `tests 0`, however many tests had passed before the kill. Halt with cause
|
|
3070
|
-
> `other` and the exit code plus the summary line as evidence; label nothing.
|
|
3071
|
-
> The same holds for the mutation gate: a killed run is not a mutant that
|
|
3072
|
-
> reddened, and the files it cancelled are not failures — only a run that
|
|
3073
|
-
> completed can kill a mutant. A completed run that exits 1 is not a killed run
|
|
3074
|
-
> either, whatever its `cancelled` count, and not a killed mutant on its exit
|
|
3075
|
-
> status alone: the acceptance mutation scores a kill only by the rules below.
|
|
3076
|
-
> Exit 0 with `tests 0` stays FAILED.
|
|
3077
|
-
> Do not wrap `<testCmd>` in an external `timeout`. Run a long suite in one
|
|
3078
|
-
> `eval` cell with `timeout: 0`, as the review runner does, and wait for it.
|
|
3079
|
-
>
|
|
3080
|
-
> **Valid red:** a run that completed — the command returned on its own, with
|
|
3081
|
-
> no signal and no timeout, deadline or kill having fired — in which the test
|
|
3082
|
-
> the claim names is reported failing. An exit ≠ 0 with no failing test is not
|
|
3083
|
-
> red, and a different test failing is not red for this claim. A red in the full
|
|
3084
|
-
> suite only triggers a narrowed run; it is never evidence on its own.
|
|
3085
|
-
>
|
|
3086
|
-
> **Narrowed run:** the Test entrypoint with arguments appended,
|
|
3087
|
-
> `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
|
|
3088
|
-
> that is promised about them, so a narrowed run counts only if it reports
|
|
3089
|
-
> `tests` > 0 and its output names the claimed test. If no narrowing can be
|
|
3090
|
-
> proven, run the full `<testCmd>` and read the named test's own result from its
|
|
3091
|
-
> output.
|
|
3092
|
-
>
|
|
3093
|
-
> **Kill:** the mutant produced a valid red in a narrowed run, and the same
|
|
3094
|
-
> narrowed command, in the same tree with the mutant reverted, ran a valid green
|
|
3095
|
-
> with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
|
|
3096
|
-
> completed exit ≠ 0 with the named test not failing is not a kill, and no kill
|
|
3097
|
-
> stands without that green run on the unmutated tree. The result is
|
|
3098
|
-
> inconclusive, never a kill, when the red does not reproduce in the narrowed
|
|
3099
|
-
> run, when the unmutated tree is red too, or when no usable run exists.
|
|
3100
|
-
>
|
|
3101
|
-
> **Evidence line:** every kill and every valid red you claim carries one line
|
|
3102
|
-
> in the claim's own free-text field:
|
|
3103
|
-
> `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
|
|
3104
|
-
> A failing-test finding filed off the review's shared run carries the `red:`
|
|
3105
|
-
> half alone.
|
|
3106
|
-
>
|
|
3107
|
-
> An inconclusive acceptance mutation is neither a kill nor a pass: halt with
|
|
3108
|
-
> cause `other`, with both runs — the mutant's and the unmutated tree's — as
|
|
3109
|
-
> evidence; label nothing. A kill's evidence line goes in your report.
|
|
3110
|
-
|
|
3111
|
-
**Give the finisher duty 3 verbatim as well, as one script.** The finisher's
|
|
3112
|
-
agent definition carries this block in its body, so the brief does not repeat
|
|
3113
|
-
it. Two finishers in one run read the release-label check as the whole duty
|
|
3114
|
-
and reported `labelled` on a PR that never got the label, so the check and the
|
|
3115
|
-
label write are one command and the finisher never runs either alone:
|
|
3116
|
-
|
|
3117
|
-
> **Duty 3 is one script, and its exit code is your verdict.**
|
|
3118
|
-
> `~/.fleet/bin/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
|
|
3119
|
-
> (the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
|
|
3120
|
-
> PR, records the head you audited, adds `ready-to-merge`, and reads the labels
|
|
3121
|
-
> back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
|
|
3122
|
-
> carries zero or more than one release label: you are halted before the label,
|
|
3123
|
-
> and the receipt names which it found. Exit 4 means the read-back does not carry
|
|
3124
|
-
> the label, written or not. Exit 2 means a `gh` call or the invocation
|
|
3125
|
-
> itself failed: report the stderr it printed. Every non-zero exit halts you
|
|
3126
|
-
> with cause `other`, with the receipt as evidence, and you do not run any of
|
|
3127
|
-
> its steps by hand to get past it. A repo whose label list defines none of the
|
|
3128
|
-
> three does not gate on one, and the script says so in its receipt. Put the
|
|
3129
|
-
> receipt, the JSON line it printed, in your report as printed: it is what tells
|
|
3130
|
-
> the controller the label is on.
|
|
2679
|
+
**What a finisher receives.** The instrument re-check, the test-run verdict
|
|
2680
|
+
rule, duty 1's audit script and what each of its exits means, duty 3's script
|
|
2681
|
+
and the halt-cause rule are the body of `agents/fleet-finisher.agent.md`, which
|
|
2682
|
+
the harness injects as its system prompt; none of them is pasted. The
|
|
2683
|
+
instrument-set rule is stated once, at the top of this file, which no finisher
|
|
2684
|
+
is dispatched to read, so it reaches one through that body. The brief carries
|
|
2685
|
+
the PR, the worktree, the dispatch pin, `<testCmd>` and the scratch root:
|
|
2686
|
+
`~/.fleet/bin/fleet-run dispatch-prompt.mjs render finisher --kind <fresh|repair>
|
|
2687
|
+
--member finisher-pr-<pr#> --pr <pr#> --pin <sha> --worktree <abs-path>
|
|
2688
|
+
--testCmd <testCmd> --scratch <scratch>`, which `ledger.mjs dispatch <pr#>
|
|
2689
|
+
finisher-pr-<pr#>` records.
|
|
3131
2690
|
|
|
3132
2691
|
**Once the label is on, take it off before you approve any push.** The label is a
|
|
3133
2692
|
verdict on the tree the finisher read, and a GitHub label does not follow the
|
|
@@ -3147,36 +2706,10 @@ its own (`run-merge-bot.md`, **The labelled head**), so this is not the only
|
|
|
3147
2706
|
guard — but its refusal costs a pass and leaves the label lying, which is yours
|
|
3148
2707
|
to clear either way, the same way: `label-off=` first, then the removal.
|
|
3149
2708
|
|
|
3150
|
-
A halt at
|
|
2709
|
+
A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
|
|
3151
2710
|
and the causes `finisher-audit.mjs` names are the ones seen so far, not a
|
|
3152
|
-
closed list
|
|
3153
|
-
|
|
3154
|
-
|
|
3155
|
-
> **Duty 1 is one script, and its exit code is your verdict.**
|
|
3156
|
-
> `~/.fleet/bin/fleet-run finisher-audit.mjs --worktree <abs-path> --pin <your dispatch pin>`
|
|
3157
|
-
> (the path you were dispatched with, and the full SHA). It finds your
|
|
3158
|
-
> worktree's row, reads whether the tree is dirty, compares the worktree's
|
|
3159
|
-
> `HEAD` to your pin, and when the head differs derives the cause from the
|
|
3160
|
-
> reflog. Exit 0, with `cause` null, is the only code that means the worktree is
|
|
3161
|
-
> clean at your pin. Exit 1 means `cause` is non-null: you are halted, and
|
|
3162
|
-
> `cause` is the word you name — `live-editor`, `rebase`, `past-pin`,
|
|
3163
|
-
> `unreadable`, `missing`, `absent` or `other`, and `other` is a cause too, not
|
|
3164
|
-
> a gap. Exit 2 means the script could not look: you are halted with cause
|
|
3165
|
-
> `other`, with the line it printed on stderr as the evidence.
|
|
3166
|
-
>
|
|
3167
|
-
> The pin is the SHA you were dispatched against, never `PR headRefOid`: a
|
|
3168
|
-
> member that kept working and pushed after the pin matches the branch tip on a
|
|
3169
|
-
> clean tree, so a headRefOid comparison reports "settled" over commits no
|
|
3170
|
-
> reviewer read — the exact divergence this halt exists to catch. You do not
|
|
3171
|
-
> run any of the script's steps by hand to get past a halt or to second-guess
|
|
3172
|
-
> it. Put the verdict, the JSON line it printed, in your report as printed: its
|
|
3173
|
-
> `evidence` is what the controller resolves the halt from.
|
|
3174
|
-
>
|
|
3175
|
-
> Every cause halts, always — named or not, you never verify the dirt is
|
|
3176
|
-
> harmless and label over it, a rebase is not a fast-forward you get to accept,
|
|
3177
|
-
> a commit past the pin is not one either, and a cause you could not name is
|
|
3178
|
-
> the least settled of the lot. Naming the cause makes the halt cheap to
|
|
3179
|
-
> resolve, never a reason to skip it.
|
|
2711
|
+
closed list; the finisher's agent body gives it the cause from one script
|
|
2712
|
+
instead of asking anyone.
|
|
3180
2713
|
|
|
3181
2714
|
**Resolving a finisher halt.** A halt is the finisher working correctly — it
|
|
3182
2715
|
refused to label — so it is never `failed`, which stays for a finisher that
|
|
@@ -3289,13 +2822,15 @@ that name it refuses, naming the bot and the `dispatch-prompt.mjs render
|
|
|
3289
2822
|
merge-bot --member merge-bot-<n> …` to run — render it, then run `ledger.mjs
|
|
3290
2823
|
dispatch merge-bot` again. Dispatch
|
|
3291
2824
|
it on the tick's `DISPATCH merge-bot`: the first `ready-to-merge` label is
|
|
3292
|
-
enough, and it never waits for the finisher's report.
|
|
2825
|
+
enough, and it never waits for the finisher's report. Its body
|
|
2826
|
+
(`agents/fleet-merge-bot.agent.md`) tells it to read
|
|
3293
2827
|
`$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
|
|
3294
2828
|
pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
|
|
3295
|
-
for late labels, then report once and exit — and
|
|
2829
|
+
for late labels, then report once and exit — and that you dispatched it,
|
|
3296
2830
|
which is what makes it hold that grace instead of arming its own watcher. Its
|
|
3297
|
-
|
|
3298
|
-
|
|
2831
|
+
brief is `~/.fleet/bin/fleet-run dispatch-prompt.mjs render merge-bot --member
|
|
2832
|
+
merge-bot-<n> --n <n> --scratch <scratch>`, `<scratch>` the absolute
|
|
2833
|
+
`scratch-root.mjs` output: the bot writes only under `<scratch>/pr<N>/merge-bot-<n>/`. **Dispatch
|
|
3299
2834
|
it with the `agent` that `ledger.mjs dispatch merge-bot` printed and omit
|
|
3300
2835
|
`model` on the call** — the tier lives in that definition's frontmatter,
|
|
3301
2836
|
`agents/fleet-merge-bot.agent.md`, as the `@smol:low` route, which resolves
|
|
@@ -3717,7 +3252,7 @@ vs specific finding with paths → paths win.
|
|
|
3717
3252
|
**Members share one filesystem, one docker stack and one process table**, and the
|
|
3718
3253
|
failures arrive as *wrong findings*, not errors:
|
|
3719
3254
|
|
|
3720
|
-
- **A pattern kill reaches siblings —
|
|
3255
|
+
- **A pattern kill reaches siblings — the implementer, fix-applier and finisher briefs forbid it.** `pkill -f
|
|
3721
3256
|
<pattern>` matches on the whole command line, machine-wide. Members hold
|
|
3722
3257
|
separate worktrees, but the process table is not partitioned by them and a
|
|
3723
3258
|
test file's name is identical in every one, so a pattern naming a test file
|
|
@@ -3776,8 +3311,8 @@ failures arrive as *wrong findings*, not errors:
|
|
|
3776
3311
|
arrived.** The same incident: the controller's warning DID reach the member,
|
|
3777
3312
|
which re-ran, found nothing changed, and said nothing — correctly reading
|
|
3778
3313
|
"send once, never re-send" as covering it. The controller then had to spend a
|
|
3779
|
-
round trip asking whether its own outbox was lossy. So
|
|
3780
|
-
|
|
3314
|
+
round trip asking whether its own outbox was lossy. So the briefs say that
|
|
3315
|
+
**confirmation state includes warnings received and acted on, even
|
|
3781
3316
|
when the outcome is no change** — one line, in the report the member already
|
|
3782
3317
|
owes. That is the cheap half of the *never read silence as assent* rule, paid
|
|
3783
3318
|
by the member rather than by the controller's guesswork.
|
|
@@ -3920,7 +3455,7 @@ at the price, because the cost of the wrong call is asymmetric — a live member
|
|
|
3920
3455
|
written off gets killed and re-dispatched, which discards the work in flight
|
|
3921
3456
|
and, where it holds a claim or a worktree, collides the fleet with itself,
|
|
3922
3457
|
while one poll spent on a member that had in fact stopped costs only the poll.
|
|
3923
|
-
The refuter's own observation rule in the fix-applier
|
|
3458
|
+
The refuter's own observation rule in the fix-applier body stops a
|
|
3924
3459
|
member from creating that state; this one stops you from misreading whoever
|
|
3925
3460
|
reaches it anyway, and neither replaces the other.
|
|
3926
3461
|
|