@feigi/fleet-ctl 0.0.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/.claude-plugin/plugin.json +9 -0
- package/LICENSE +202 -0
- package/NOTICE +18 -0
- package/agents/fleet-finisher.agent.md +7 -0
- package/agents/fleet-implementer-alt.agent.md +210 -0
- package/agents/fleet-implementer.agent.md +210 -0
- package/agents/fleet-merge-bot.agent.md +7 -0
- package/agents/fleet-review-comments.agent.md +40 -0
- package/agents/fleet-review-correctness.agent.md +43 -0
- package/agents/fleet-review-runner.agent.md +73 -0
- package/agents/fleet-review-silent-failure.agent.md +49 -0
- package/agents/fleet-review-simplify.agent.md +46 -0
- package/agents/fleet-review-snapshot.agent.md +24 -0
- package/agents/fleet-review-tests.agent.md +46 -0
- package/agents/fleet-review-types.agent.md +41 -0
- package/agents/fleet-review-verifier.agent.md +29 -0
- package/commands/review-and-fix.md +98 -0
- package/commands/run-merge-bot.md +357 -0
- package/commands/run-team-help.md +17 -0
- package/package.json +23 -0
- package/scripts/agent-test-dir-prose.test.mjs +59 -0
- package/scripts/agent-test.test.mjs +1636 -0
- package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
- package/scripts/ambient-git-vars-prose.test.mjs +192 -0
- package/scripts/ancestry-check-position-prose.test.mjs +175 -0
- package/scripts/apply-ruleset.test.mjs +420 -0
- package/scripts/arg-header-probes-prose.test.mjs +393 -0
- package/scripts/arg.mjs +600 -0
- package/scripts/arg.test.mjs +1354 -0
- package/scripts/board-cli.test.mjs +694 -0
- package/scripts/board-identity.test.mjs +429 -0
- package/scripts/board-liveness-banner.test.mjs +119 -0
- package/scripts/board-prev-shape.test.mjs +229 -0
- package/scripts/board-tryparse-null.test.mjs +119 -0
- package/scripts/board.html +471 -0
- package/scripts/board.mjs +2037 -0
- package/scripts/board.test.mjs +3086 -0
- package/scripts/brief-after-cut-prose.test.mjs +53 -0
- package/scripts/candidates-exit3-prose.test.mjs +302 -0
- package/scripts/candidates.mjs +674 -0
- package/scripts/candidates.test.mjs +2101 -0
- package/scripts/caveat-unification-prose.test.mjs +98 -0
- package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
- package/scripts/ci-completes-premise-prose.test.mjs +257 -0
- package/scripts/ci-state-prose.test.mjs +113 -0
- package/scripts/ci-state.mjs +761 -0
- package/scripts/ci-state.test.mjs +1640 -0
- package/scripts/ci-vacuous-green.test.mjs +368 -0
- package/scripts/citation-sweep-prose.test.mjs +1572 -0
- package/scripts/claim-lifecycle.test.mjs +185 -0
- package/scripts/claim-ticket.sh +417 -0
- package/scripts/claim-ticket.test.mjs +1121 -0
- package/scripts/closing-keyword-prose.test.mjs +193 -0
- package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
- package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
- package/scripts/compute-board.mjs +579 -0
- package/scripts/compute-board.test.mjs +1060 -0
- package/scripts/compute-spend.mjs +329 -0
- package/scripts/compute-spend.test.mjs +451 -0
- package/scripts/cross-repo-citation-prose.test.mjs +156 -0
- package/scripts/cwd-isolation-pins.mjs +83 -0
- package/scripts/dedupe-guard-prose.test.mjs +243 -0
- package/scripts/derive-testcmd.sh +239 -0
- package/scripts/derive-testcmd.test.mjs +380 -0
- package/scripts/diff-stats.mjs +231 -0
- package/scripts/diff-stats.test.mjs +408 -0
- package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
- package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
- package/scripts/drop-merged-label.sh +173 -0
- package/scripts/drop-merged-label.test.mjs +480 -0
- package/scripts/expected-jobs-prose.test.mjs +80 -0
- package/scripts/filing-bar-seat-prose.test.mjs +242 -0
- package/scripts/filing-claim-bar-prose.test.mjs +166 -0
- package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
- package/scripts/finisher-halt-prose.test.mjs +106 -0
- package/scripts/finisher-name-prose.test.mjs +134 -0
- package/scripts/finisher-own-tree-prose.test.mjs +285 -0
- package/scripts/finisher-pin-race-prose.test.mjs +339 -0
- package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
- package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
- package/scripts/fleet-bootstrap +155 -0
- package/scripts/fleet-heartbeat.mjs +272 -0
- package/scripts/fleet-heartbeat.test.mjs +450 -0
- package/scripts/fleet-provenance +207 -0
- package/scripts/fleet-provenance.test.mjs +64 -0
- package/scripts/fleet-run +148 -0
- package/scripts/fleet-run.test.mjs +90 -0
- package/scripts/fleet-state.mjs +400 -0
- package/scripts/fleet-state.test.mjs +373 -0
- package/scripts/fleet-tick-prose.test.mjs +299 -0
- package/scripts/fleet-tick.mjs +832 -0
- package/scripts/fleet-tick.test.mjs +1332 -0
- package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
- package/scripts/frontmatter-allowlist.json +64 -0
- package/scripts/frontmatter-check.mjs +256 -0
- package/scripts/frontmatter-check.test.mjs +436 -0
- package/scripts/git-env.mjs +124 -0
- package/scripts/git-env.test.mjs +149 -0
- package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
- package/scripts/gone-walk.test.mjs +213 -0
- package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
- package/scripts/head-moved-after-label-prose.test.mjs +233 -0
- package/scripts/immutable-body-claim-prose.test.mjs +413 -0
- package/scripts/implementer-model-tier.test.mjs +643 -0
- package/scripts/inflight-citation-prose.test.mjs +144 -0
- package/scripts/inflight-exit2-prose.test.mjs +81 -0
- package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
- package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
- package/scripts/inflight.sh +1106 -0
- package/scripts/inflight.test.mjs +2984 -0
- package/scripts/injection-control-prose.test.mjs +404 -0
- package/scripts/install-root-audit.test.mjs +464 -0
- package/scripts/instrument-check-prose.test.mjs +235 -0
- package/scripts/instruments.sh +394 -0
- package/scripts/instruments.test.mjs +787 -0
- package/scripts/issue-tracker-prose.test.mjs +71 -0
- package/scripts/json.sh +248 -0
- package/scripts/json.test.mjs +364 -0
- package/scripts/ledger-dispatch.test.mjs +516 -0
- package/scripts/ledger-grammar.mjs +85 -0
- package/scripts/ledger-grammar.test.mjs +142 -0
- package/scripts/ledger-read-require-file.test.mjs +197 -0
- package/scripts/ledger.mjs +1753 -0
- package/scripts/ledger.test.mjs +3554 -0
- package/scripts/line-distance-prose.test.mjs +245 -0
- package/scripts/liveness-rationale-prose.test.mjs +83 -0
- package/scripts/locale-pin-prose.test.mjs +189 -0
- package/scripts/member-outcome-prose.test.mjs +167 -0
- package/scripts/member-outcomes-header.test.mjs +148 -0
- package/scripts/member-outcomes-prose.test.mjs +63 -0
- package/scripts/member-outcomes.mjs +231 -0
- package/scripts/member-outcomes.test.mjs +507 -0
- package/scripts/member-prompt-prose.test.mjs +161 -0
- package/scripts/member-record.mjs +605 -0
- package/scripts/member-record.test.mjs +516 -0
- package/scripts/member-write-guard.mjs +279 -0
- package/scripts/member-write-guard.test.mjs +211 -0
- package/scripts/merge-commit-probe-prose.test.mjs +122 -0
- package/scripts/merge-gate.mjs +262 -0
- package/scripts/merge-gate.test.mjs +613 -0
- package/scripts/muted-git-guard-sweep.test.mjs +493 -0
- package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
- package/scripts/net-watchdog-prose.test.mjs +79 -0
- package/scripts/net.sh +409 -0
- package/scripts/net.test.mjs +211 -0
- package/scripts/no-ci-gate-prose.test.mjs +108 -0
- package/scripts/no-undo-audit.sh +1134 -0
- package/scripts/no-undo-audit.test.mjs +3965 -0
- package/scripts/no-wave.test.mjs +138 -0
- package/scripts/node-floor-sweep.test.mjs +611 -0
- package/scripts/pointer-target-prose.test.mjs +186 -0
- package/scripts/pr-overlap.mjs +417 -0
- package/scripts/pr-overlap.test.mjs +695 -0
- package/scripts/printf-die-sweep.test.mjs +384 -0
- package/scripts/prompt-renderer.mjs +39 -0
- package/scripts/prompt-renderer.test.mjs +68 -0
- package/scripts/prose-pin.mjs +808 -0
- package/scripts/prose-pin.test.mjs +1034 -0
- package/scripts/prove-merge.sh +228 -0
- package/scripts/prove-merge.test.mjs +995 -0
- package/scripts/pull-table-relabel-prose.test.mjs +60 -0
- package/scripts/quiet-payload-prose.test.mjs +222 -0
- package/scripts/reap.sh +1768 -0
- package/scripts/reap.test.mjs +4395 -0
- package/scripts/reaping-prose.test.mjs +159 -0
- package/scripts/refuter-scratch-prose.test.mjs +135 -0
- package/scripts/release-label-required-prose.test.mjs +71 -0
- package/scripts/release-label-split-prose.test.mjs +169 -0
- package/scripts/release-ticket.sh +1716 -0
- package/scripts/release-ticket.test.mjs +5106 -0
- package/scripts/renovate-release-contract.test.mjs +379 -0
- package/scripts/repo-root.mjs +544 -0
- package/scripts/repo-root.test.mjs +873 -0
- package/scripts/reporter-output-rule-prose.test.mjs +208 -0
- package/scripts/review-agent-report-only.test.mjs +49 -0
- package/scripts/review-core-cwd-isolation.test.mjs +374 -0
- package/scripts/review-core-reads.test.mjs +478 -0
- package/scripts/review-core-refuter-scratch.test.mjs +148 -0
- package/scripts/review-core-snapshot-path.test.mjs +777 -0
- package/scripts/review-core-specialist-scratch.test.mjs +189 -0
- package/scripts/review-core-testcmd.test.mjs +288 -0
- package/scripts/review-core-unrun.test.mjs +530 -0
- package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
- package/scripts/review-core.mjs +1028 -0
- package/scripts/review-eval-resolver-path.test.mjs +55 -0
- package/scripts/review-eval.mjs +197 -0
- package/scripts/review-host-fixture.mjs +73 -0
- package/scripts/review-in-run-retry.test.mjs +187 -0
- package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
- package/scripts/review-path-default.test.mjs +796 -0
- package/scripts/review-runner-spawns.test.mjs +93 -0
- package/scripts/review-runner.test.mjs +155 -0
- package/scripts/review-tier-audit.test.mjs +140 -0
- package/scripts/run-artifact-pr-prose.test.mjs +341 -0
- package/scripts/run-merge-bot-prose.test.mjs +1391 -0
- package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
- package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
- package/scripts/section-between-guard-prose.test.mjs +378 -0
- package/scripts/select-dimensions.test.mjs +674 -0
- package/scripts/shared-refusal.test.mjs +388 -0
- package/scripts/shell-traps-prose.test.mjs +507 -0
- package/scripts/shortlist.mjs +355 -0
- package/scripts/shortlist.test.mjs +366 -0
- package/scripts/slow-transport.mjs +72 -0
- package/scripts/snapshot-repo.test.mjs +772 -0
- package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
- package/scripts/spend-view.test.mjs +312 -0
- package/scripts/staleness-qualifier-prose.test.mjs +251 -0
- package/scripts/staleness-verdict-prose.test.mjs +142 -0
- package/scripts/staleness.mjs +414 -0
- package/scripts/staleness.test.mjs +893 -0
- package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
- package/scripts/stash-prohibition-prose.test.mjs +313 -0
- package/scripts/strip-comments.mjs +44 -0
- package/scripts/tier-check.mjs +468 -0
- package/scripts/tier-check.test.mjs +726 -0
- package/scripts/tier-guard-gate-prose.test.mjs +216 -0
- package/scripts/tier-outcomes-header.test.mjs +586 -0
- package/scripts/tier-outcomes.mjs +441 -0
- package/scripts/tier-outcomes.test.mjs +342 -0
- package/scripts/tier-roles.mjs +250 -0
- package/scripts/tier-roles.test.mjs +316 -0
- package/scripts/tracker-block-copy-prose.test.mjs +288 -0
- package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
- package/scripts/unattended-git-sweep.test.mjs +142 -0
- package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
- package/scripts/verify-sha.sh +117 -0
- package/scripts/verify-sha.test.mjs +693 -0
- package/scripts/watcher-degraded-block.test.mjs +372 -0
- package/scripts/watcher-key-prose.test.mjs +106 -0
- package/scripts/within-run-pair-prose.test.mjs +208 -0
- package/scripts/worktree-audit.sh +482 -0
- package/scripts/worktree-audit.test.mjs +1407 -0
- package/scripts/worktree-head-prose.test.mjs +276 -0
- package/scripts/worktree-listing-sweep.test.mjs +217 -0
- package/scripts/worktree-model-prose.test.mjs +216 -0
- package/scripts/worktree.sh +470 -0
- package/skills/next-ticket/SKILL.md +138 -0
- package/skills/run-team/SKILL.md +3603 -0
- package/skills/run-team/references/ci-and-staleness.md +75 -0
- package/skills/run-team/references/correction-tickets.md +37 -0
- package/skills/run-team/references/isolation.md +23 -0
- package/skills/run-team/references/member-lifecycle.md +73 -0
- package/skills/run-team/references/reaping.md +73 -0
- package/skills/sizing-a-ticket/SKILL.md +39 -0
|
@@ -0,0 +1,3603 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: run-team
|
|
3
|
+
description: Run an agent fleet — implementers, reviewers (default 2 and 6), one merge bot — over the ready-for-agent queue. Invoke-only; the fleet writes to a live repo and must never start unasked.
|
|
4
|
+
argument-hint: "[implementers] [reviewers]"
|
|
5
|
+
disable-model-invocation: true
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
Run `next-ticket`, `review-and-fix`, `run-merge-bot` as one fleet. You are the
|
|
9
|
+
**controller**, in the main thread, never a member.
|
|
10
|
+
|
|
11
|
+
`$ARGUMENTS` = `[implementers] [reviewers]`, both optional, default 2 and 6, no
|
|
12
|
+
hard cap — they become the tick's `--implementer-cap` and `--reviewer-cap`.
|
|
13
|
+
Merge bot is at most one, not configurable.
|
|
14
|
+
|
|
15
|
+
Rationale: `docs/specs/2026-07-22-run-team-agent-fleet-design.md`. The
|
|
16
|
+
war story behind a rule ending `See references/<file>` lives in that file; load
|
|
17
|
+
it only when a member needs the *why*. A rule without that line carries its
|
|
18
|
+
reasoning inline — nothing is missing.
|
|
19
|
+
|
|
20
|
+
## Rules that fail silently
|
|
21
|
+
|
|
22
|
+
**A report is delivered, not implied by ending a turn.** Every member owes
|
|
23
|
+
the controller one report naming its outcome before it exits — including a
|
|
24
|
+
member whose prompt carries no explicit report line. The "report the SHA",
|
|
25
|
+
"report PR number" and "stop and report" instructions below *are* that
|
|
26
|
+
report, not a second obligation on top of it. A member that does the work
|
|
27
|
+
correctly and ends its turn has reported nothing: the controller learns the
|
|
28
|
+
outcome only by re-reading artifacts and pinging, and a finding held only in
|
|
29
|
+
that member's context is lost. Members did exactly this in one run —
|
|
30
|
+
finishers, a reviewer and merge bots alike, the work done and only the
|
|
31
|
+
delivery missing. Say it in every dispatch prompt. See
|
|
32
|
+
references/member-lifecycle.md.
|
|
33
|
+
|
|
34
|
+
**Say in every dispatch prompt that you do not acknowledge reports.** A
|
|
35
|
+
member cannot see whether its report arrived, so silence from you is
|
|
36
|
+
indistinguishable from loss and it re-sends — three members did in one run,
|
|
37
|
+
each burning a turn, and in all three the original had in fact arrived. Give
|
|
38
|
+
them the line verbatim: *"The controller does not acknowledge reports. Send
|
|
39
|
+
once and exit; never re-send unless the controller asks by name."*
|
|
40
|
+
|
|
41
|
+
**But a missing report is NOT evidence the member failed to send one — the
|
|
42
|
+
inbound direction drops AND delays messages.** Both were measured in one run,
|
|
43
|
+
and they are indistinguishable at the moment you look: one finisher's report was
|
|
44
|
+
accepted with a msg_id and never arrived at all, while another's arrived late —
|
|
45
|
+
its original and its re-send landing together, after the controller had already
|
|
46
|
+
concluded it was missing. Measured: a finisher completed every
|
|
47
|
+
duty, labelled the PR, and sent its report; the send was accepted with a msg_id
|
|
48
|
+
and never arrived. The controller read the silence as the member ending its turn
|
|
49
|
+
without reporting, said so, and was wrong. The re-send it asked for by name is
|
|
50
|
+
the only reason the report exists. So when a report is missing, **ask by name —
|
|
51
|
+
that is what the "unless the controller asks by name" clause is for — and do not
|
|
52
|
+
attribute the gap to the member until it answers.** A member re-sending on a
|
|
53
|
+
named request should state the original's msg_id and that it is a re-send, which
|
|
54
|
+
is what distinguishes a lost message from a member that never sent one; a
|
|
55
|
+
controller that skips the ask cannot tell those apart and will guess wrong in
|
|
56
|
+
whichever direction its expectations point.
|
|
57
|
+
|
|
58
|
+
Note this cuts against the paragraph above only in appearance: the default stays
|
|
59
|
+
*send once*, because unprompted re-sends were measured 2-to-1 false. The ask is
|
|
60
|
+
the controller's move, not the member's.
|
|
61
|
+
|
|
62
|
+
**Your OWN messages can vanish the same way, and that half is not recoverable by
|
|
63
|
+
a re-send.** Two controller rulings were lost in one run, both with a
|
|
64
|
+
`success: true` receipt: a member proceeded on its stated default and filed a
|
|
65
|
+
tracker issue the lost ruling had said not to file. So **never read a member's
|
|
66
|
+
silence as assent**, and require members to report their *confirmation state*
|
|
67
|
+
alongside results — "I escalated X, received no ruling, proceeded on default Y".
|
|
68
|
+
That sentence is the only thing that made either loss visible. After any ruling
|
|
69
|
+
you cannot confirm was received, re-check the artifacts it governed.
|
|
70
|
+
|
|
71
|
+
**Name every member.** The name is the ledger token and the hub address; omit
|
|
72
|
+
it and the ledger cannot match the member.
|
|
73
|
+
Names follow the unit of work: `impl-<issue#>`, `fix-pr-<pr#>`,
|
|
74
|
+
`review-pr-<pr#>`, `finisher-pr-<pr#>`, `merge-bot-<n>`. See
|
|
75
|
+
references/member-lifecycle.md.
|
|
76
|
+
|
|
77
|
+
**A depth-2 member cannot dispatch further** (`task.maxRecursionDepth: 2`):
|
|
78
|
+
if `task` is absent at your depth, ask the controller to dispatch the
|
|
79
|
+
specialists and relay their reports. Say so in a fallback reviewer's prompt,
|
|
80
|
+
or it silently downgrades to a solo review. See references/member-lifecycle.md.
|
|
81
|
+
|
|
82
|
+
**Fresh context per member.** One member, one unit of work, gone. Never
|
|
83
|
+
re-task a finished member — waking it drags the old ticket back in. Refill =
|
|
84
|
+
**new** member, **new** name. Sending is still right for pinging a live
|
|
85
|
+
member for a report it owes, or resuming a truncated reply — never for
|
|
86
|
+
handing a finished member the next ticket.
|
|
87
|
+
|
|
88
|
+
`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.
|
|
89
|
+
|
|
90
|
+
See references/member-lifecycle.md.
|
|
91
|
+
|
|
92
|
+
**You read your instruments out of a tree every member can write to — re-check
|
|
93
|
+
them before every gate decision.** Per-member worktrees and `./agent-test`'s port
|
|
94
|
+
derivation protect members from each other; neither protects the main checkout,
|
|
95
|
+
which you run every gate probe out of and which any member can edit — except
|
|
96
|
+
through a `write`/`edit`/`ast_edit` the `member-write-guard` extension refuses
|
|
97
|
+
(ADR 0020); a `bash` or `eval` write still lands (#2210). Measured: a
|
|
98
|
+
member edited two files there instead of in its worktree while the CI monitor was
|
|
99
|
+
polling one of them every 120s and a live finisher was using it to decide a
|
|
100
|
+
label. It caught itself; nothing in the fleet would have. That is the silent
|
|
101
|
+
direction — a modified instrument raises no error, shows in no PR and leaves
|
|
102
|
+
nothing in the ledger, and it still returns a verdict, just not necessarily the
|
|
103
|
+
right one, so you have no reason to re-check a script you did not know had
|
|
104
|
+
changed.
|
|
105
|
+
|
|
106
|
+
- **Pin once**, at phase 0 step 0 below, from the main checkout you are
|
|
107
|
+
running this from — never from a member's worktree, which is gitignored
|
|
108
|
+
and carries no baseline:
|
|
109
|
+
`~/.fleet/bin/fleet-run instruments.sh --pin`. On a workspace that does not
|
|
110
|
+
track `plugin/…`, the pin names the plugin checkout once — `--pin --audit
|
|
111
|
+
<plugin-checkout>` — and every check after it follows the recorded tree.
|
|
112
|
+
- **Re-check before you act on any instrument reading** — a SHA acceptance, a CI
|
|
113
|
+
verdict, the reconcile, a reap, a label gate — from that same main checkout:
|
|
114
|
+
`~/.fleet/bin/fleet-run instruments.sh`. **Exit 0 is the only code that
|
|
115
|
+
lets a gate proceed. Exit 1 (the set changed) and exit 2 (the check could not
|
|
116
|
+
answer) both refuse: report what it printed and do NOT re-read the
|
|
117
|
+
instrument** — a guard that fails open on "could not look" protects nothing.
|
|
118
|
+
**A label gate and a CI verdict are also taken by dispatched members, not
|
|
119
|
+
only by you** — the finisher labels, and the merge bot merges on its own
|
|
120
|
+
reading — and neither is dispatched to read this file, so neither can be
|
|
121
|
+
reached by stating the rule here. Each carries its own copy: the finisher's
|
|
122
|
+
in the verbatim block at its duties below, the merge bot's inside
|
|
123
|
+
`merge-gate.mjs`, step 3 of `run-merge-bot.md`.
|
|
124
|
+
- **Re-pin only after a change you made deliberately.** The mid-run tooling fix
|
|
125
|
+
below is the one legitimate writer. Re-pinning to clear a refusal you cannot
|
|
126
|
+
explain discards the check.
|
|
127
|
+
|
|
128
|
+
It covers every tracked file under this repo's own plugin component directories
|
|
129
|
+
— `plugin/commands/`, `plugin/scripts/`, `plugin/skills/`, `plugin/agents/`,
|
|
130
|
+
`plugin/workflows/` — the probes, the libraries they source, and these runbooks,
|
|
131
|
+
which you also read from that tree. Not the whole repo: `docs/metrics/` is
|
|
132
|
+
appended by THIS run, so covering it would refuse on the run's own bookkeeping
|
|
133
|
+
every time. It does not cover refs, deliberately: `claim-ticket.sh` creates a
|
|
134
|
+
branch per ticket and `reap.sh` deletes them in the ref store every worktree
|
|
135
|
+
shares, so ordinary work moves refs several times a run and a per-gate
|
|
136
|
+
refusal on that is noise.
|
|
137
|
+
|
|
138
|
+
**A member runs its test suite in the foreground and blocks on it.**
|
|
139
|
+
Backgrounding a suite and polling for it makes the member's own progress
|
|
140
|
+
depend on a wake-up nothing in the fleet guarantees, and an idle member is
|
|
141
|
+
indistinguishable from a working one — you learn only by pinging. Measured
|
|
142
|
+
twice in one run: `fix-pr-1184` backgrounded its suite plus a Monitor and sat
|
|
143
|
+
idle for roughly two hours; neither ever woke it, and the only reason no work
|
|
144
|
+
was lost is that you pinged it by name with a concrete next action.
|
|
145
|
+
`finisher-pr-1184` reached for the same pattern minutes later — a proactive
|
|
146
|
+
warning is the only reason it did not repeat the stall. Its
|
|
147
|
+
`pgrep -f 'finish-finisher-pr-1184'` could never have matched any process, so
|
|
148
|
+
the poll it was waiting on was structurally incapable of firing. Say it in
|
|
149
|
+
every dispatch prompt — this file is yours, not theirs, so a member learns
|
|
150
|
+
it only if you write it into the prompt.
|
|
151
|
+
|
|
152
|
+
## Shell traps
|
|
153
|
+
|
|
154
|
+
Monitor and Bash commands run under **zsh**, and the shell in this file is
|
|
155
|
+
prescriptive — copied verbatim into a watcher or pasted into a bot's brief. So
|
|
156
|
+
every trap here is a zsh-vs-bash difference that ships as a green-looking gate:
|
|
157
|
+
correct in the shell you tested in, silently wrong in the one it runs in. Phase
|
|
158
|
+
3's monitor paragraph and the **Merge bot**'s brief both point here
|
|
159
|
+
instead of restating any of it; the one deliberate copy is named at the end.
|
|
160
|
+
|
|
161
|
+
**zsh word-splits an unquoted command substitution's result; it does NOT split
|
|
162
|
+
an unquoted parameter expansion.** That one difference is the whole rule, and the
|
|
163
|
+
hazard is the **assigned-variable** form, never `$(…)`. Measured on zsh 5.9
|
|
164
|
+
against `849`, `850`, `852` on three lines:
|
|
165
|
+
|
|
166
|
+
| Form | zsh | bash / sh |
|
|
167
|
+
|---|---|---|
|
|
168
|
+
| `prs=$(gh pr list …)` then `for pr in $prs` | **1 iteration**, all three glued into one value | 3 |
|
|
169
|
+
| `for pr in $(gh pr list …)` | 3 | 3 |
|
|
170
|
+
| `for _ in $(seq 1 60)` | 60 | 60 |
|
|
171
|
+
|
|
172
|
+
**Word the rule against the first row.** A warning spelled *never `for x in
|
|
173
|
+
$(…)`* names the safe form as the hazard, so a reader avoids the form that works,
|
|
174
|
+
keeps the one that collapses, and rewrites correct bounded polls on the way.
|
|
175
|
+
#854 was filed carrying that inversion in its own remedy clause and in its title,
|
|
176
|
+
and its filer measured both forms and retracted it; the corrected rule is this
|
|
177
|
+
row. `$(…)` splits. Leave it alone.
|
|
178
|
+
|
|
179
|
+
**Capture-then-loop needs `while IFS= read -r` fed by a heredoc**, which is
|
|
180
|
+
line-exact under every shell:
|
|
181
|
+
|
|
182
|
+
```sh
|
|
183
|
+
while IFS= read -r pr; do
|
|
184
|
+
[ -n "$pr" ] || continue # a blank line from an empty capture, not a probe that could not look
|
|
185
|
+
node …/ci-state.mjs --pr "$pr" </dev/null # every inner call, per the trap below
|
|
186
|
+
done <<EOF
|
|
187
|
+
$prs
|
|
188
|
+
EOF
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase
|
|
192
|
+
3's block uses, but it splits on *every* whitespace character, so it is safe only
|
|
193
|
+
for values that cannot contain one — PR numbers cannot, branch names and paths
|
|
194
|
+
can. Measured on a two-line list whose first value is `two words`: three
|
|
195
|
+
iterations through `$(printf …)`, two through `while IFS= read -r`. On an empty
|
|
196
|
+
`$prs` the counts diverge the other way: `for pr in $(printf '%s\n' "$prs")`
|
|
197
|
+
iterates **zero** times, but the heredoc form iterates **once** with `pr` empty —
|
|
198
|
+
the guard above is what stops that iteration from probing `--pr ""`.
|
|
199
|
+
|
|
200
|
+
**`</dev/null` every command inside a `while read` loop.** The loop's stdin *is*
|
|
201
|
+
the list, and any inner command that reads stdin eats the rest of it. Measured on
|
|
202
|
+
the three-line list above: one unredirected inner reader takes the loop to **1
|
|
203
|
+
iteration**, `</dev/null` on it restores 3 — the identical signature to the
|
|
204
|
+
word-split bug, so a correct heredoc fix missing this half looks exactly like no
|
|
205
|
+
fix at all, and reads as one.
|
|
206
|
+
|
|
207
|
+
**A probe that could not look emits an event; it never `continue`s.** Stated in
|
|
208
|
+
full at *A probe that cannot read is a transition event, not silence* in Phase 3,
|
|
209
|
+
and it binds every watcher in this file rather than that one block: the third
|
|
210
|
+
value beside pass and fail is what turns a broken loop into a loud failure
|
|
211
|
+
instead of a quiet one. A guard that drops an unreadable probe — `[ -n "$json" ]
|
|
212
|
+
|| continue` — makes *could not look* indistinguishable from *nothing to report*.
|
|
213
|
+
|
|
214
|
+
**`$?`/`PIPESTATUS` is unconditionally-TRUE in zsh.** zsh has no `PIPESTATUS`
|
|
215
|
+
(its array is lowercase `pipestatus`, 1-indexed), so `${PIPESTATUS[0]}` is always
|
|
216
|
+
empty and `[ "" -eq 0 ]` passes. A bot's merge gate opened without ever reading
|
|
217
|
+
an exit code.
|
|
218
|
+
|
|
219
|
+
**`status` is a READ-ONLY variable in zsh**, an alias for `$?`. So the obvious
|
|
220
|
+
bash idiom for reading the payload — `status=$(jq -r '.status' ci.json)` — aborts
|
|
221
|
+
with `read-only variable: status`. Measured this way it fails safe (a hard abort,
|
|
222
|
+
no merge), but the same assignment inside an `if`, or with stderr suppressed,
|
|
223
|
+
reads as a check that silently did not run. Same root cause as the `PIPESTATUS`
|
|
224
|
+
trap, opposite failure direction — so name the variable anything else
|
|
225
|
+
(`ci_status`).
|
|
226
|
+
|
|
227
|
+
**The one deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
|
|
228
|
+
mechanism bites argv as well as loops, and that instance stays written out in the
|
|
229
|
+
fix-applier prompt and every refuter brief under **Reviewers** rather than here,
|
|
230
|
+
because the seats that inject faults are the ones that need it and a bot reads
|
|
231
|
+
gates without ever injecting one. Do not fold it into this block, and do not
|
|
232
|
+
restate this block there.
|
|
233
|
+
|
|
234
|
+
## Phase 0 — shortlist
|
|
235
|
+
|
|
236
|
+
Once per run, at start. Supply is automatic after that (ADR 0013): the tick
|
|
237
|
+
refreshes the Shortlist itself, and every admission is a **Pull** — one ticket
|
|
238
|
+
into one free implementer slot, the moment it frees (phase 1). Nothing in this
|
|
239
|
+
phase, or in any later one, asks the maintainer which tickets to take.
|
|
240
|
+
|
|
241
|
+
0. **Once per run, before anything else.**
|
|
242
|
+
|
|
243
|
+
**Fast-forward the checkout before you trust these rules — you are reading
|
|
244
|
+
them from it.** `git fetch origin && git rev-list --count main..origin/main`;
|
|
245
|
+
non-zero means the SKILL.md you are executing is superseded, so
|
|
246
|
+
`git merge --ff-only origin/main` and re-read what changed under
|
|
247
|
+
`commands/`, `scripts/` and `skills/`. The usual cause is the PREVIOUS run's own close-out PR: it
|
|
248
|
+
lands the rules THIS run needs and nothing pulls them. Measured twice — 57
|
|
249
|
+
commits stale in one run, 20 in another, the second shipping every dispatch
|
|
250
|
+
prompt without two rules that had merged the day before. Silent by
|
|
251
|
+
construction: stale text reads as authoritative, and the tier guard's own
|
|
252
|
+
floor is re-derived from a stale `tier-outcomes.tsv` at the same time.
|
|
253
|
+
|
|
254
|
+
**Pin the instruments, after that fast-forward and before anything reads
|
|
255
|
+
them, from this main checkout.** `~/.fleet/bin/fleet-run instruments.sh --pin`
|
|
256
|
+
records what the scripts and runbooks in this repo say right now, which is
|
|
257
|
+
what every later gate compares against; the rule above says what its exit
|
|
258
|
+
codes mean. Pinning before that fast-forward would instead pin the
|
|
259
|
+
superseded text and certify it for the rest of the run.
|
|
260
|
+
**When this workspace does not track `plugin/…`** — fleets run here on an
|
|
261
|
+
installed plugin rather than a vendored tree — the bare pin refuses on an
|
|
262
|
+
empty instrument set, because this checkout holds no instruments to certify.
|
|
263
|
+
Name the plugin checkout to the pin instead:
|
|
264
|
+
`~/.fleet/bin/fleet-run instruments.sh --pin --audit <plugin-checkout>`.
|
|
265
|
+
The baseline records the audited tree beside the digest, and every later
|
|
266
|
+
check — yours, a finisher's, the merge gate's own leg — follows that
|
|
267
|
+
recorded root without being told twice. Refusing the bare pin and naming
|
|
268
|
+
the tree once is the whole cross-workspace contract; never dispatch a
|
|
269
|
+
member into a run whose phase-0 pin refused.
|
|
270
|
+
|
|
271
|
+
**Check the merge gate against its spec, once the fast-forward has put the
|
|
272
|
+
ratified spec in front of you.** Where the workspace checks a ruleset spec
|
|
273
|
+
in, `.github/scripts/apply-ruleset.sh --check` compares it to the live gate
|
|
274
|
+
without writing anything (no spec checked in → nothing to run, skip it).
|
|
275
|
+
Three statuses and they are not interchangeable: **0** the gate is what the
|
|
276
|
+
tree says it is; **3** it is not — including the gate having been deleted
|
|
277
|
+
or renamed — and the diff it prints says how; **2** the question could not
|
|
278
|
+
be answered at all: no spec, no `gh`, a listing or read that failed
|
|
279
|
+
outright, or a read that succeeded but withheld `bypass_actors` because
|
|
280
|
+
the session lacks repository admin.
|
|
281
|
+
|
|
282
|
+
**3 does not stop the run and is not yours to fix** — reconciling is a
|
|
283
|
+
write to the gate protecting this repo, so it needs the maintainer.
|
|
284
|
+
Surface the diff and carry on. What it changes is what you may then claim:
|
|
285
|
+
every statement this run makes about which checks must pass before a merge
|
|
286
|
+
is sourced from the spec plus ADR 0007 and is true of the live gate only
|
|
287
|
+
while this check is green, so a 3 means saying "the gate requires X"
|
|
288
|
+
without naming the drift is a false claim, and a 2 means you never learned
|
|
289
|
+
either way. Measured 2026-09-23 (#1710): four contexts ADR 0007 had
|
|
290
|
+
selected were required by the spec and by nothing live, and the gap sat
|
|
291
|
+
there unnoticed because the only thing that ever read the live gate was a
|
|
292
|
+
person choosing to.
|
|
293
|
+
|
|
294
|
+
**Launch the cockpit.** On every phase-0 pass, not just the first:
|
|
295
|
+
`node ~/.fleet/bin/fleet-run board.mjs serve --open &` in the
|
|
296
|
+
background. It is a read-only mirror of `.fleet/ledger.md` + `gh` — you never
|
|
297
|
+
feed or update it, and it survives your own compaction. The launch is
|
|
298
|
+
idempotent per workspace when the running cockpit answers the identity
|
|
299
|
+
handshake: an already-served workspace's launch finds the running server
|
|
300
|
+
over HTTP, prints its URL, and exits 0 without starting a second one
|
|
301
|
+
(#1585) — nothing to skip. It opens nothing either: `--open` opens a tab
|
|
302
|
+
only from the launch that binds a port and starts the server (#1714), so a
|
|
303
|
+
re-shortlist leaves the board tab you already have alone. A second fleet
|
|
304
|
+
on another workspace collides with none of that: its own launch derives
|
|
305
|
+
that workspace's own port and binds it when free, or scans to the next
|
|
306
|
+
free port in its range when the derived one is already held by something
|
|
307
|
+
else — either way it gets its own board, just not always on the port its
|
|
308
|
+
hash predicts.
|
|
309
|
+
|
|
310
|
+
The spend panel reads this workspace's own `~/.omp/agent/sessions` tree
|
|
311
|
+
(#1716), and is pinned to whichever session first writes a transcript on this
|
|
312
|
+
cockpit's own watch (#1583/#1679): it will not follow a workspace that
|
|
313
|
+
already had another session's transcripts sitting there at launch. If the
|
|
314
|
+
panel is reading someone else's numbers, relaunch with `--spend-dir <path>`
|
|
315
|
+
naming this run's own session directory to override the heuristic outright —
|
|
316
|
+
`~/.omp/agent/sessions/<encoded-cwd>/<ISO>_<uuid>` (the directory, never
|
|
317
|
+
the `.jsonl` file of the same name beside it).
|
|
318
|
+
|
|
319
|
+
**Fold in every PR a prior run left open, before shortlisting.** A chore PR
|
|
320
|
+
carrying that run's own metrics, or ticket work whose review was deferred —
|
|
321
|
+
both are reviewable work no member otherwise picks up, because the Shortlist
|
|
322
|
+
holds ISSUES and nothing looks at inherited PRs. Queue each for review exactly as
|
|
323
|
+
ticket work: same review workflow, same fix-applier, same finisher. Measured
|
|
324
|
+
2026-09-03 — #1222 arrived this way and its review found a defect its own PR
|
|
325
|
+
body called unreviewed, and #1237's review then caught two metrics rows the
|
|
326
|
+
controller had missed in its own close-out, so a chore PR is not exempt from
|
|
327
|
+
being wrong. Reviewing them next run is also what stops one pinning
|
|
328
|
+
`fleet-tick`'s backlog forever (#590): unreviewable AND uncounted is the state
|
|
329
|
+
that strands it.
|
|
330
|
+
|
|
331
|
+
1. **Build the Shortlist** — `~/.fleet/bin/fleet-run shortlist.mjs`, then read
|
|
332
|
+
`.fleet/shortlist.json`. The script runs the cheap filters and nothing else
|
|
333
|
+
— no ticket body is read here, because a Pull reads one ticket in full at
|
|
334
|
+
the moment it admits it (ADR 0013 §1):
|
|
335
|
+
|
|
336
|
+
- **Candidate scan** — `candidates.mjs --require-label ready-for-agent`,
|
|
337
|
+
oldest-first, never re-ranked. Its row count is `scanned`, the supply.
|
|
338
|
+
- **Dependency scan**, `next-ticket` step 2, on each row's `d` array. Open
|
|
339
|
+
blocker → drop.
|
|
340
|
+
- **Live Exclusions** — a ticket whose ledger row reads `excluded ·
|
|
341
|
+
behind-pr:#M` or `excluded · behind-issue:#M` stays out while its premise
|
|
342
|
+
holds (phase 1, **Exclusion**).
|
|
343
|
+
- **In-flight check** — `inflight.sh <N>` per survivor. Exit 1 is taken, and
|
|
344
|
+
any other non-zero exit is a check that could not answer, which is never
|
|
345
|
+
free. Both drop the ticket, logged by number.
|
|
346
|
+
|
|
347
|
+
It writes the survivors, in order, to `.fleet/shortlist.json` —
|
|
348
|
+
`{scanned, shortlist: [{n, t}]}` — resolved against the git common dir
|
|
349
|
+
exactly as `ledger.mjs` resolves `.fleet/ledger.md`, so you, the tick and a
|
|
350
|
+
member in its own worktree all name one file. **Exit 0 is the file written,
|
|
351
|
+
an empty shortlist included** — the empty queue is an answer. **Exit 2 is a
|
|
352
|
+
refusal**: the scan, the ledger read or the write did not answer, and the
|
|
353
|
+
previous file stands untouched, because an empty file written then would
|
|
354
|
+
read as "no work". Never read 2 as empty.
|
|
355
|
+
|
|
356
|
+
Every probe fails CLOSED: an unreadable blocker counts as open, an
|
|
357
|
+
unreadable premise leaves its exclusion standing, an unanswered in-flight
|
|
358
|
+
check counts as taken. A ticket dropped wrongly waits one refresh; a ticket
|
|
359
|
+
admitted wrongly costs a Pull's full read at best and two members on one
|
|
360
|
+
ticket at worst.
|
|
361
|
+
|
|
362
|
+
**`--require-label ready-for-agent` mandatory, no fallback** — the script
|
|
363
|
+
fixes it, and you never run `candidates.mjs --allow-fallback` by hand to
|
|
364
|
+
widen the list: `ready-for-human` needs a human to brainstorm first and you
|
|
365
|
+
have no channel to one mid-flight.
|
|
366
|
+
|
|
367
|
+
`candidates.mjs`'s exit 3 reaches you as an empty shortlist with its to-spec
|
|
368
|
+
notice on stderr. **Exit 3 is not that empty queue, and never a reason to
|
|
369
|
+
widen the net.** It says the labeled query returned rows and the to-spec
|
|
370
|
+
filter took every one: what is queued is to-tickets' input rather than
|
|
371
|
+
claimable tickets, and a member handed one implements an entire spec as a
|
|
372
|
+
single ticket. Log it as
|
|
373
|
+
specs awaiting to-tickets, not as no work — and still do not pass
|
|
374
|
+
`--allow-fallback`, whose second pass is unfiltered and so reaches the
|
|
375
|
+
`ready-for-human` and untriaged work you have no channel for.
|
|
376
|
+
2. **Refresh is the tick's from here on.** `fleet-tick.mjs` runs
|
|
377
|
+
`shortlist.mjs` itself when unclaimed entries fall below the implementer
|
|
378
|
+
cap, when the file is missing or empty, and when an `excluded` premise has
|
|
379
|
+
lifted, and prints `REFRESHED shortlist: <n> entries; <k> lifted`. Phase 0
|
|
380
|
+
runs it by hand once because a dead run's shortlist is stale by definition.
|
|
381
|
+
|
|
382
|
+
**No multi-select, no maintainer tick.** Selection and ordering are batched —
|
|
383
|
+
one scan, oldest first; admission never is. The invariant this replaces — one
|
|
384
|
+
human decision per batch of admissions, zero unilateral grabs — is retired
|
|
385
|
+
(ADR 0013): zero human decisions per admission, and every non-admission is a
|
|
386
|
+
label or a premise the maintainer can read.
|
|
387
|
+
|
|
388
|
+
## Phase 1 — Pull: judge, then claim or relabel
|
|
389
|
+
|
|
390
|
+
Serial, main checkout, one Pull at a time. Never parallel, never inside a member —
|
|
391
|
+
concurrent `worktree add` and label writes race.
|
|
392
|
+
|
|
393
|
+
One free implementer slot is one Pull. The tick names the heads — `PULL #412
|
|
394
|
+
#415`, one per free slot — and each Pull runs this sequence on its head,
|
|
395
|
+
terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
|
|
396
|
+
|
|
397
|
+
1. **Take the shortlist head** — the next `.fleet/shortlist.json` entry with no
|
|
398
|
+
`impl-` row and no `excluded` row whose premise still holds, which is the
|
|
399
|
+
ticket the tick's `PULL` row names.
|
|
400
|
+
2. **In-flight check, again** — `~/.fleet/bin/fleet-run inflight.sh <N>`; any
|
|
401
|
+
hit = taken, drop it and take the next entry. The shortlist is as old as its
|
|
402
|
+
last refresh. It runs all three probes (PRs, remote heads, local
|
|
403
|
+
worktrees + branches) so a partial one cannot read as free. The PR probe is
|
|
404
|
+
two signals rather than a bare full-text match — GitHub's own closing-PR links
|
|
405
|
+
plus branch-segment matching — and both drop `MERGED` and `CLOSED`, so a
|
|
406
|
+
merged or abandoned PR the `gh pr list` window covers cannot hold a ticket
|
|
407
|
+
forever. A linked PR that window does *not* cover has no state to read: it
|
|
408
|
+
prints `?` and still counts as taken, merged or not.
|
|
409
|
+
|
|
410
|
+
**Exit 2 is not free** — the question went unanswered, so treat it as taken
|
|
411
|
+
and say which ticket it was in the log. A probe that could not look is
|
|
412
|
+
recorded rather than aborting the run, so exit 2 from one prints the same
|
|
413
|
+
JSON as 0 and 1 plus an `unknown[]` naming the probes that could not look:
|
|
414
|
+
read `unknown`, never `taken` alone, because exit 2 says `"taken": false`,
|
|
415
|
+
which summarizes `hits` and is not a claim the ticket is free. A hit outranks
|
|
416
|
+
an unknown — a payload can carry a non-empty `hits[]` and a non-empty
|
|
417
|
+
`unknown[]` at exit 1, which is taken. Four causes print nothing at all — a
|
|
418
|
+
bad argument, not inside a git repository, no such issue, a verdict that could
|
|
419
|
+
not be written — so never assume exit 2 parses.
|
|
420
|
+
|
|
421
|
+
**A free verdict is not evidence that nobody is editing the ticket's
|
|
422
|
+
target files.** All three probes ask whether a branch-shaped claim
|
|
423
|
+
exists — a PR, a remote head, a local branch, or a worktree — and
|
|
424
|
+
nothing else; work done directly against the shared checkout, by a
|
|
425
|
+
human or another agent session, stakes no branch-shaped claim and trips
|
|
426
|
+
none of them.
|
|
427
|
+
3. **Read the ticket in full, once** — `gh issue view <N> --json title,body,comments,labels
|
|
428
|
+
--jq '.title, .body, ([.labels[].name]|join(",")), (.comments[]|.author.login + ": " + .body)'`.
|
|
429
|
+
One read answers every question the Pull asks. Record the ticket's real
|
|
430
|
+
brief — the `## Agent Brief` comment where one exists, otherwise the issue
|
|
431
|
+
body, which is where most tickets actually carry it (a controller probe found only 43/100 open
|
|
432
|
+
`ready-for-agent` issues have a separate Agent Brief comment; the rest,
|
|
433
|
+
this ticket included, carry the brief in the body) — plus its `Out of
|
|
434
|
+
scope` sequencing wherever that section is found. Then judge **decided?**
|
|
435
|
+
— never size.
|
|
436
|
+
|
|
437
|
+
**Still live?** A backlog ticket's claims rot. Before `decided?`, settle the
|
|
438
|
+
ticket's central claim against `origin/main` — never the working tree, never
|
|
439
|
+
the ticket's own line numbers, which drift. One `git show origin/main:<file>`
|
|
440
|
+
piped to `grep` does it for any ticket citing a construct, which is most of
|
|
441
|
+
them. **That read is fatal, not empty, when the path is untracked in
|
|
442
|
+
`origin/main`** — `git show origin/main:<path>` exits 128 saying the path
|
|
443
|
+
does not exist, and the file may still sit right there on disk, so it is a
|
|
444
|
+
probe that could not look rather than a clean tree. Fall back to
|
|
445
|
+
`git ls-tree origin/main -- <path>` (empty output at exit 0 = untracked)
|
|
446
|
+
before reading the failure as "unfixed". Already fixed → close it citing the
|
|
447
|
+
commit, do not claim it. Partly fixed → say which acceptance criteria the
|
|
448
|
+
tree already meets, and which the tree now **contradicts**.
|
|
449
|
+
|
|
450
|
+
**Grep for the ticket's ASKED-FOR CHANGE, not only its subject construct** —
|
|
451
|
+
the construct check passes on every stale pin ticket, because the construct
|
|
452
|
+
is what the pin is *about* and never went anywhere. So for a ticket asking
|
|
453
|
+
for a pin, test or assertion, grep the **test file** for the assertion it
|
|
454
|
+
wants; for one asking for exact wording, grep the **old** wording the ticket
|
|
455
|
+
quotes as wrong, never the new wording it proposes. A proposed replacement is
|
|
456
|
+
a suggestion the implementer is free to reword — an equivalent rewording
|
|
457
|
+
satisfies the ticket while failing a grep for its literal text — and the
|
|
458
|
+
quoted defect is the fact. Old string gone from `git show origin/main:<file>`
|
|
459
|
+
⇒ the fix landed, and
|
|
460
|
+
`git log -S '<old string>' --oneline origin/main -- <file> | head -1` names
|
|
461
|
+
the commit that removed it; close citing that commit. Seconds either way,
|
|
462
|
+
and the construct half alone is the probe that could not look.
|
|
463
|
+
**No ancestry check on what that walk printed.** `origin/main` is where the
|
|
464
|
+
walk starts, so every commit it can print is reachable from `origin/main` by
|
|
465
|
+
construction, and `git merge-base --is-ancestor <sha> origin/main` is true
|
|
466
|
+
for all of them — true again when the sha *is* `origin/main`. A step that
|
|
467
|
+
cannot answer no is not evidence, and reads as evidence anyway.
|
|
468
|
+
**That check belongs one input over — a sha the TICKET quotes**, where it
|
|
469
|
+
can answer no: a rebase leaves the commit it orphaned a whole object, so
|
|
470
|
+
`git show` resolves it happily while nothing in `origin/main`'s history
|
|
471
|
+
reaches it, and a "fixed in `<sha>`" premise built on one describes a tree
|
|
472
|
+
that no longer exists. Separate its two non-zero answers before citing
|
|
473
|
+
either — exit 1 is the answer *not reachable*, while exit 128 with `Not a
|
|
474
|
+
valid object name` is a sha this clone does not have at all, a probe that
|
|
475
|
+
could not look rather than an orphan (measured: #640's comment cites
|
|
476
|
+
`35c0845` on a since-deleted branch, and 128 is what it exits here).
|
|
477
|
+
|
|
478
|
+
**Both halves of that command are load-bearing.** Drop the `origin/main`
|
|
479
|
+
argument and `git log -S` searches `HEAD`, contradicting the rule a paragraph
|
|
480
|
+
up — and the two searches fail differently there. On a checkout behind the
|
|
481
|
+
fix the prescribed **old**-string search names a *wrong* commit at exit 0,
|
|
482
|
+
the old string still being present in that tree: measured at #206's
|
|
483
|
+
`0dc39ef^`, `| head -1` names the rename `4fd2f73`, not the fix. It is the
|
|
484
|
+
**new**-string search the paragraph above forbids that prints nothing at exit
|
|
485
|
+
0 there, indistinguishable from "the change never landed"; the old-string
|
|
486
|
+
search goes empty on a checkout that predates the old string's own arrival
|
|
487
|
+
at that path — behind that rename in #206's case, and with no rename in play
|
|
488
|
+
at all in this file's: measured at `647ae44^`, which already tracks this
|
|
489
|
+
path under this name, `git log -S 'ls-tree origin/main'` prints nothing at
|
|
490
|
+
exit 0.
|
|
491
|
+
Add `--reverse` and you get the *oldest* count-changing commit, which is the
|
|
492
|
+
file's last rename whenever the string predates one — measured on #206's old
|
|
493
|
+
wording, `--reverse` names `4fd2f73` ("move next-ticket and sizing-a-ticket
|
|
494
|
+
into the plugin"), a refactor that clears an ancestry gate exactly as
|
|
495
|
+
well as the real fix, while newest-first `| head -1` names `0dc39ef`, the
|
|
496
|
+
commit that actually did it.
|
|
497
|
+
(`--follow` fixes the rename half but is mutually destructive with
|
|
498
|
+
`--reverse`: the two together return empty at exit 0, and `--follow` takes
|
|
499
|
+
exactly one pathspec or exits 128.) So read the subject of whatever it names
|
|
500
|
+
before citing it in the close, and treat empty output as an answer you did
|
|
501
|
+
not get rather than a commit.
|
|
502
|
+
|
|
503
|
+
Measured, one run: #132's one-line remedy had shipped in `e7b11e6` ten days
|
|
504
|
+
earlier and #134's AC-2 asked for an exit code a later design (#64)
|
|
505
|
+
deliberately changed — neither commit carried a trailer back, so the tracker
|
|
506
|
+
showed both as open work. #132 cost a full claim, worktree and implementer
|
|
507
|
+
dispatch to learn this; #134 would have shipped a test asserting the opposite
|
|
508
|
+
of the shipped behaviour. The two probes that settled both took seconds.
|
|
509
|
+
**A ticket deferred from a review is a claim about a tree that has since
|
|
510
|
+
moved** — and the older the ticket, the more it has moved, so this bites
|
|
511
|
+
hardest at exactly the head of an oldest-first queue.
|
|
512
|
+
|
|
513
|
+
Measured again 2026-08-19: four stale in the 20 oldest, and the construct
|
|
514
|
+
probe caught **none** of the four. It **missed** #156 — the two pins and the
|
|
515
|
+
`contentWords()` extraction it asks for had all landed (`d016414`, `1abd6c8`)
|
|
516
|
+
while `overlap()`, the construct, sat right where the ticket said, so the
|
|
517
|
+
probe passed the ticket through as live work and it cost a claim, a worktree
|
|
518
|
+
and a dispatch. It **missed** #205, whose `d:` scan `candidates.test.mjs`
|
|
519
|
+
already pinned — `6d94451` and `43d6ac5` both added `.d` assertions, and the
|
|
520
|
+
ticket's own closing comment cites both. It **missed** #206, whose wording
|
|
521
|
+
defect `0dc39ef` had already fixed — by an **equivalent rewording**, not by
|
|
522
|
+
the literal string the ticket proposed, which appears nowhere in
|
|
523
|
+
`origin/main`; the ticket's **line number** had drifted too, `:95` → `:98`.
|
|
524
|
+
And #187 it could not read at all: that ticket's file is untracked in
|
|
525
|
+
`origin/main`, the fatal-not-empty case above.
|
|
526
|
+
|
|
527
|
+
**`staleness.mjs` runs that check for you, and answers in THREE values.**
|
|
528
|
+
`~/.fleet/bin/fleet-run staleness.mjs --path <path> --gone
|
|
529
|
+
'<string>'`, or `--present '<string>'`, once per claim the ticket makes.
|
|
530
|
+
It goes here and not in `shortlist.mjs` because choosing WHICH string
|
|
531
|
+
settles a ticket needs the ticket read, which the step above already did —
|
|
532
|
+
so the cost lands on the pulled ticket and never on the backlog.
|
|
533
|
+
`--gone` is a defect the fix must remove, the wording the ticket quotes as
|
|
534
|
+
wrong; `--present` is what the fix must add, the assertion a pin ticket asks
|
|
535
|
+
for. Give exactly one — the direction is not inferable from the string, and
|
|
536
|
+
the wrong one answers the opposite verdict with full confidence.
|
|
537
|
+
|
|
538
|
+
A needle that itself starts with `--` — #240's `--label ready-for-agent`
|
|
539
|
+
is one this backlog carries — needs the end-of-options separator: `--gone
|
|
540
|
+
-- '<string>'`/`--present -- '<string>'`. Given bare, with no `--`
|
|
541
|
+
immediately before it, the value guard still refuses it — `staleness:
|
|
542
|
+
--gone needs a value` — at exit 2, a could-not-check to admit and annotate,
|
|
543
|
+
not an invocation to retry.
|
|
544
|
+
|
|
545
|
+
| Exit | Verdict | What it does at the Pull |
|
|
546
|
+
|---|---|---|
|
|
547
|
+
| 0 | still reproduces | admit it |
|
|
548
|
+
| 1 | provably fixed | do not admit; close citing the payload's `commit` and `subject` |
|
|
549
|
+
| 2 | could not check | admit it, **and say the probe could not check** |
|
|
550
|
+
|
|
551
|
+
The third value is the one that has to survive. A probe that could not look
|
|
552
|
+
answers exactly like a probe that looked and found nothing, so folding it
|
|
553
|
+
into either neighbour retires live supply on a guess in one direction and
|
|
554
|
+
reports a defect as live on a spelling the tree stopped using in the other.
|
|
555
|
+
Exit 2 is also where every guard and every failed git call in that script
|
|
556
|
+
lands, so a probe that breaks keeps the ticket in the queue.
|
|
557
|
+
|
|
558
|
+
What it refuses to answer is the point of it. It reads `origin/main` and
|
|
559
|
+
nothing else — never the working tree, never anything on disk — so a path
|
|
560
|
+
this repo does not track is exit 2 rather than a clean read: that is #187's
|
|
561
|
+
case and the generated-artifact case together, `agent-test` being written
|
|
562
|
+
into a claimed worktree by `claim-ticket.sh`'s heredoc, which makes every
|
|
563
|
+
copy under `.worktrees/` a snapshot of whenever that worktree was claimed.
|
|
564
|
+
`fixed` is never read off the string's presence alone either: it carries the
|
|
565
|
+
commit `git log -S` names for that string at that path, reachable from
|
|
566
|
+
`origin/main` by construction since that is where the walk starts. A
|
|
567
|
+
`--gone` string absent from the file that ALSO never changed count there is
|
|
568
|
+
exit 2, not a fix — that is the positive control, and without it a typo in
|
|
569
|
+
the string closes a live ticket.
|
|
570
|
+
|
|
571
|
+
It does not run a reproduction. The general "is this still reproducible?"
|
|
572
|
+
oracle over the whole backlog is what #238 ruled out, and a reproduction run
|
|
573
|
+
without a positive and a negative control misattributes causes rather than
|
|
574
|
+
merely missing defects — the #230 check needed a purpose-built fixture plus
|
|
575
|
+
both. A ticket no single string settles is a `could not check`: admitted,
|
|
576
|
+
annotated in the dispatch prompt (phase 2), never quietly dropped.
|
|
577
|
+
|
|
578
|
+
**Decided?** Would two competent implementers, reading only this ticket, build
|
|
579
|
+
materially different things? "Material" by inventory, not feel:
|
|
580
|
+
|
|
581
|
+
| Left open | Verdict |
|
|
582
|
+
|---|---|
|
|
583
|
+
| architecture, API shape, schema, UX | **undecided** |
|
|
584
|
+
| new dependency, new seam | **undecided** |
|
|
585
|
+
| naming, file layout, ordering, test arrangement | decided — ignore |
|
|
586
|
+
|
|
587
|
+
Any undecided item → not decided. Name it; that name is the relabel comment's
|
|
588
|
+
missing decision or open fork. **Torn → surface, never guess**: relabel it
|
|
589
|
+
`ready-for-human` as a fork naming the open decision — the label is how a
|
|
590
|
+
Pull surfaces it to the maintainer. Opposite of
|
|
591
|
+
`sizing-a-ticket`'s *torn → take the heavier row*, deliberately — see that skill.
|
|
592
|
+
|
|
593
|
+
**This is a consumption gate**, priced for the seat where implementer
|
|
594
|
+
divergence costs a claim, a worktree and a dispatch; the filing-time
|
|
595
|
+
counterpart was repriced to *is the defect confirmed* and states its own bar
|
|
596
|
+
inline — see `docs/adr/0001-filing-label-bar-is-defect-confirmed.md`.
|
|
597
|
+
|
|
598
|
+
No sizing agent here. `sizing-a-ticket` picks the *process path*, and that is
|
|
599
|
+
phase 2's call, after the ticket is claimed.
|
|
600
|
+
|
|
601
|
+
**Class?** Second judgement off the same read, so it costs no extra tokens.
|
|
602
|
+
Stale docs, wrong comments, bad citations → `class=correction`; everything
|
|
603
|
+
else → `class=routine`. **Torn → correction**: a misjudged routine is a
|
|
604
|
+
missed saving, a misjudged correction runs the one class that demonstrably
|
|
605
|
+
ships new wrong claims.
|
|
606
|
+
|
|
607
|
+
**The class no longer selects a model tier** — the phase-2 guard fired on
|
|
608
|
+
2026-08-16 and every class now dispatches at the session's tier. It still
|
|
609
|
+
earns its read: it selects the **correction-ticket discipline** phase 2
|
|
610
|
+
hands the implementer (settle every restated claim against the tree, keep
|
|
611
|
+
the diff to the ticket's stated size, no positional references, never a
|
|
612
|
+
count in prose, a settling command re-run and written inline for every
|
|
613
|
+
claim that goes into the commit or PR body, and literal text grepped with
|
|
614
|
+
`-F`, its zero trusted only after the same command, with the same flags,
|
|
615
|
+
finds a known match), it partitions
|
|
616
|
+
`docs/metrics/tier-outcomes.tsv`, and it is what any future tier
|
|
617
|
+
control would be drawn from. A row with no class is still `class=unknown`,
|
|
618
|
+
never a guess.
|
|
619
|
+
|
|
620
|
+
The correction exception was always a **precaution, not a measurement.**
|
|
621
|
+
references/correction-tickets.md records four tickets in one run each
|
|
622
|
+
shipping a *new* wrong claim, and blames the ticket's framing and
|
|
623
|
+
unasked-for prose — **not** implementer capability; it measures no tier at
|
|
624
|
+
all. That reasoning is why the discipline survives the tiering that used to
|
|
625
|
+
accompany it.
|
|
626
|
+
|
|
627
|
+
Record the class in the Pull's ledger row (step 7); phase 2 reads it for
|
|
628
|
+
the discipline, no longer for the tier.
|
|
629
|
+
4. **Collision scan against open PRs and live branches** — the ticket is an
|
|
630
|
+
*un-implemented issue* with no diff, so infer its target files from the brief
|
|
631
|
+
(the paths it names) and compare them against each open PR's `gh pr diff <PR>
|
|
632
|
+
--name-only` **and** each live worktree's `git diff --name-only
|
|
633
|
+
origin/main...<branch>` (the branches `git worktree list` names) — a member
|
|
634
|
+
mid-work has a branch before it has a PR. `pr-overlap.mjs` is **PR-vs-PR
|
|
635
|
+
only** — it runs `gh pr diff` on *both* args and errors on an issue number,
|
|
636
|
+
so use it the way the merge bot does (PR vs PR), never on a ticket here.
|
|
637
|
+
Step 2 catches a ticket already taken, not one that *edits a file an open PR
|
|
638
|
+
edits*. Overlap → exclude it `behind-pr:#M`, next entry. The tracker cannot
|
|
639
|
+
express this, and it is what actually stalls a Pull's PR at merge.
|
|
640
|
+
5. **Sequence check** — the brief's `Out of scope` names an open ticket this one
|
|
641
|
+
sequences after → exclude it `behind-issue:#M`, next entry. That lives in the
|
|
642
|
+
brief, is invisible to the dependency scan, and oldest-first order puts a
|
|
643
|
+
chain's members next to each other, where two consecutive numbers read as
|
|
644
|
+
two independent tickets.
|
|
645
|
+
6. **Claim** — `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer
|
|
646
|
+
--apply` (below). Exit 2 → treat it as taken, next entry.
|
|
647
|
+
7. **Row, then dispatch** — `ledger.mjs row <N> "impl-<N> · class=… [· tier=alt]"`,
|
|
648
|
+
then phase 2 at once: claim what you are about to dispatch;
|
|
649
|
+
dispatch what you have just claimed.
|
|
650
|
+
|
|
651
|
+
**The Pull table** — every verdict a Pull can reach, and the one thing each
|
|
652
|
+
does (ADR 0013 Decision 2 and 4):
|
|
653
|
+
|
|
654
|
+
| At the Pull | Action |
|
|
655
|
+
|---|---|
|
|
656
|
+
| in-flight hit, or an in-flight check that could not answer | drop, next entry |
|
|
657
|
+
| no longer labelled `ready-for-agent` | drop, next entry |
|
|
658
|
+
| `staleness.mjs` exit 1 — provably fixed | close citing the commit, next entry |
|
|
659
|
+
| brief names no *what* | relabel `needs-triage`, next entry |
|
|
660
|
+
| genuine fork — options named, none ruled | relabel `ready-for-human`, next entry |
|
|
661
|
+
| needs human hands — external access, manual testing, judgment during the work | relabel `ready-for-human`, next entry |
|
|
662
|
+
| target files collide with an open PR or a live branch | exclude `behind-pr:#M`, next entry |
|
|
663
|
+
| `Out of scope` sequences it after an open ticket | exclude `behind-issue:#M`, next entry |
|
|
664
|
+
| `claim-ticket.sh` exit 2 | taken, next entry |
|
|
665
|
+
| decided, live, free, claimed | row, then dispatch (phase 2) |
|
|
666
|
+
|
|
667
|
+
**The shortlist runs out → run `shortlist.mjs` once and Pull again; still
|
|
668
|
+
empty → hold the slot idle until the next refresh trigger.** Within a turn,
|
|
669
|
+
Pull from the current list first and refresh second — a refresh never delays a
|
|
670
|
+
dispatch.
|
|
671
|
+
|
|
672
|
+
**A Pull never re-admits a ticket already relabelled.** The shortlist file can
|
|
673
|
+
be older than a relabel — this run's own Pulls, or a demotion in phase 3 — so
|
|
674
|
+
read the ticket's labels in step 3's full read (`--json
|
|
675
|
+
title,body,comments,labels`) and drop it when `ready-for-agent` is gone. A Pull
|
|
676
|
+
that trusted a list built before the relabel landed would hand a ticket the
|
|
677
|
+
fleet has already judged unimplementable straight to the next member.
|
|
678
|
+
|
|
679
|
+
**Relabel by cause.** An unclaimed ticket is yours to reclassify at the Pull —
|
|
680
|
+
three causes, two labels: `ready-for-human` for hands or a fork;
|
|
681
|
+
`needs-triage` for a brief that names no *what*.
|
|
682
|
+
`gh issue edit <N> --remove-label ready-for-agent --add-label <label>` (no
|
|
683
|
+
`in-progress` to drop — it was never claimed), preceded by exactly one comment:
|
|
684
|
+
|
|
685
|
+
- `needs-triage`:
|
|
686
|
+
|
|
687
|
+
> *Relabelled by the fleet controller.* Pulled for implementation and
|
|
688
|
+
> returned: the brief does not decide what to build. Missing decision: <one
|
|
689
|
+
> line>. Returning to /triage; `ready-for-agent` restored once decided.
|
|
690
|
+
|
|
691
|
+
- `ready-for-human` (fork):
|
|
692
|
+
|
|
693
|
+
> *Relabelled by the fleet controller.* Pulled for implementation and
|
|
694
|
+
> returned: the brief leaves a decision open. Open fork: <options, verbatim
|
|
695
|
+
> from the brief>.
|
|
696
|
+
|
|
697
|
+
- `ready-for-human` (hands):
|
|
698
|
+
|
|
699
|
+
> *Relabelled by the fleet controller.* Pulled for implementation and
|
|
700
|
+
> returned: needs human hands — <external access | manual testing |
|
|
701
|
+
> judgment during the work>: <one line>.
|
|
702
|
+
|
|
703
|
+
Neither label invokes anything: `/triage` is maintainer-run, and both labels
|
|
704
|
+
only stop the ticket costing a read per scan. These comments are the only
|
|
705
|
+
writes the fleet makes to a ticket it did not claim.
|
|
706
|
+
|
|
707
|
+
**Exclusion is a ticket row with a premise.** `ledger.mjs row <N> "excluded ·
|
|
708
|
+
behind-pr:#M"` or `ledger.mjs row <N> "excluded · behind-issue:#M"` — `#M` is
|
|
709
|
+
the open PR, or the branch name until its PR exists, or the issue this ticket
|
|
710
|
+
sequences after. No new ledger section. `shortlist.mjs` probes every premise at
|
|
711
|
+
each refresh — MERGED or CLOSED lifts a `behind-pr`, CLOSED lifts a
|
|
712
|
+
`behind-issue` — and a lifted ticket re-enters the shortlist in its own
|
|
713
|
+
oldest-first slot; its row is rewritten to `impl-<N> …` when it is pulled,
|
|
714
|
+
because `row` replaces the whole line.
|
|
715
|
+
|
|
716
|
+
**Claiming.** `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer --apply` does
|
|
717
|
+
the label, worktree, branch, frozen install, lockfile-clean assertion, and the
|
|
718
|
+
isolation runner in one serial pass. The two arguments are always that literal
|
|
719
|
+
pair — `impl-<N>` as `<slug>`, `implementer` as `<type>` — so the claim is
|
|
720
|
+
branch `implementer/<N>-impl-<N>`, worktree `.worktrees/<N>-impl-<N>`. Never
|
|
721
|
+
read them off `git branch -r` or `git worktree list`: human branches on origin
|
|
722
|
+
(`fix/…`, `docs/…`) have another shape, and the script takes both arguments as
|
|
723
|
+
free text, so a pair copied from one claims under that shape at exit 0.
|
|
724
|
+
|
|
725
|
+
**Infer `<install>` — never default to `npm install`.** A lockfile-mutating
|
|
726
|
+
install in a throwaway worktree corrupts it for everyone; the script derives the
|
|
727
|
+
frozen form from the lockfile and refuses to guess.
|
|
728
|
+
|
|
729
|
+
**Materialize the isolation envelope as a file, not a briefing.** The runner is
|
|
730
|
+
tracked at the repo root since #55, so every checkout has one; it derives its
|
|
731
|
+
ports from the worktree's own `<N>-slug` directory name (so collisions stay
|
|
732
|
+
impossible) and materializes the current runner from the one emitter rather than
|
|
733
|
+
carrying a copy of it. Brief members with `./agent-test
|
|
734
|
+
<file-or-dir>` and nothing else — anyone who finds the worktree finds the
|
|
735
|
+
runner, including grandchildren you never dispatched. A directory works too and
|
|
736
|
+
expands to the test files under it; one holding none refuses rather than passing
|
|
737
|
+
vacuously, so a mistyped file or directory path cannot come back green. See
|
|
738
|
+
references/isolation.md.
|
|
739
|
+
|
|
740
|
+
**A reused worktree may lack the runner** — no longer here, and still can
|
|
741
|
+
elsewhere. `claim-ticket.sh` used to write `agent-test` only when it claimed a
|
|
742
|
+
*fresh* worktree, so a worktree carried over from a prior run, or an already-open
|
|
743
|
+
PR's worktree you sent a rebaser/resolver into, had no `./agent-test` and the
|
|
744
|
+
member stalled on a missing script (observed with a rebase-resolver in a
|
|
745
|
+
prior-run worktree). #55 tracked the runner, so any worktree checked out from
|
|
746
|
+
`origin/main` now carries it. A tree that is NOT a checkout — a `git archive`
|
|
747
|
+
snapshot, a `cp -R` subset — still has whatever was copied into it, and a repo
|
|
748
|
+
that tracks no runner never had one: there, tell the member the runner is absent
|
|
749
|
+
and to run docker-free suites directly (`npx vitest run --config
|
|
750
|
+
vitest.ci.config.ts <file>` — the CI unit config has no `globalSetup`, so there
|
|
751
|
+
is no stack to collide on).
|
|
752
|
+
|
|
753
|
+
**A reused worktree may also be on the wrong COMMIT.** `git worktree add <path>
|
|
754
|
+
<branch>` checks out the existing LOCAL branch and never consults the remote, so
|
|
755
|
+
a branch a previous run left behind wins over the rebased `origin/` ref that is
|
|
756
|
+
actually the PR. Measured in a scratch repo (git 2.50.1): with the branch rebased
|
|
757
|
+
on the remote and a stale local ref standing, `git worktree add <path> <branch>`
|
|
758
|
+
checked out the stale commit and printed `HEAD is now at <stale-sha> <subject>` —
|
|
759
|
+
the same subject the PR head carries, because a rebase preserves it. Neither
|
|
760
|
+
commit was an ancestor of the other, so *behind* is the wrong model; it is a
|
|
761
|
+
fork. Every other signal reads normal too: `git worktree list` shows the worktree
|
|
762
|
+
present on the expected branch, and the tree is clean. `claim-ticket.sh` never
|
|
763
|
+
touches this path — it claims only fresh tickets, and builds those from
|
|
764
|
+
`origin/main`.
|
|
765
|
+
|
|
766
|
+
**The two reuse failures are not symmetric.** A missing runner fails LOUDLY: the
|
|
767
|
+
member stalls on a script that is not there. A stale base fails SILENTLY and
|
|
768
|
+
produces confident wrong output — a review cut its immutable snapshot at the
|
|
769
|
+
stale commit and a fix-applier was dispatched into it, halted only before a push
|
|
770
|
+
that would have been a non-fast-forward.
|
|
771
|
+
|
|
772
|
+
So, when you re-create a worktree for an already-open PR:
|
|
773
|
+
|
|
774
|
+
- **Create it detached from the remote ref**, never from the bare branch name:
|
|
775
|
+
`git worktree add --detach <path> origin/<branch>`. Same scratch repo, same
|
|
776
|
+
moment: this landed on the remote's commit. It removes the mechanism rather
|
|
777
|
+
than catching it, and leaves no local ref for the next run to inherit.
|
|
778
|
+
- **Then verify against the branch REF, and refuse on mismatch.** Compare
|
|
779
|
+
`git -C <path> rev-parse HEAD` against
|
|
780
|
+
`git ls-remote origin refs/heads/<branch> | cut -f1` — the ref itself, which
|
|
781
|
+
is what the PR's head actually is, and **never `git rev-parse
|
|
782
|
+
origin/<branch>`**, which is the ref the worktree was just cut from and so
|
|
783
|
+
agrees with it by construction. Unequal → dispatch nothing into that
|
|
784
|
+
worktree, and report it naming BOTH commits, since their subjects will not
|
|
785
|
+
tell them apart. **An empty read is neither equal nor a mismatch**: the read
|
|
786
|
+
failed, or that head branch is not on `origin` at all (a fork PR, where the
|
|
787
|
+
creation form above cannot work either), so report the ref as unreadable
|
|
788
|
+
rather than the worktree as wrong — the same hole `[ -n "$pre" ]` closes on
|
|
789
|
+
the way into `run-merge-bot.md`'s step-1 poll.
|
|
790
|
+
- **Read `gh pr view <N> --json headRefOid -q .headRefOid` here too, and
|
|
791
|
+
record it — it is NOT the gate.** A `headRefOid` that disagrees with the ref
|
|
792
|
+
is the PR-object desync `run-merge-bot.md`'s step 1 says needs a controller,
|
|
793
|
+
so it is a fact to carry into that decision, never the operand this refusal
|
|
794
|
+
turns on.
|
|
795
|
+
|
|
796
|
+
**Why the ref and not `headRefOid`: during the PR object's lag both operands go
|
|
797
|
+
stale in the SAME direction, so that compare fails OPEN as readily as it fails
|
|
798
|
+
closed.** The PR object spends the lag sitting on the PRE-rebase sha — cleared
|
|
799
|
+
on re-poll attempt 24 (~2 min) in one merge pass and attempt 14 (~84s) in the next,
|
|
800
|
+
both after `gh pr update-branch --rebase` returned `rc=0`, measured in
|
|
801
|
+
`run-merge-bot.md`'s step 1 — and that is the very commit a clone which has not
|
|
802
|
+
fetched since the rebase still has `origin/<branch>` pointing at. So the false
|
|
803
|
+
REFUSAL (worktree current, PR object behind) is only half of it: cut the
|
|
804
|
+
worktree from the stale remote-tracking ref and both sides read the superseded
|
|
805
|
+
sha, the check reads EQUAL, and the dispatch lands on exactly the commit this
|
|
806
|
+
paragraph exists to catch. Measured in a scratch repo (git 2.50.1): with the
|
|
807
|
+
branch rebased onto an advanced `main`, force-pushed, and the clone not fetched
|
|
808
|
+
since, `git worktree add --detach <path> origin/<branch>` landed on the
|
|
809
|
+
pre-rebase `c774756` and printed its subject unchanged by the rebase, while
|
|
810
|
+
`git ls-remote origin refs/heads/<branch>` read the true tip `62ba798` from
|
|
811
|
+
that same unfetched clone. **Re-reading `headRefOid` on a settle window does
|
|
812
|
+
not reach that half at all** — it fires only where the two disagree — which is
|
|
813
|
+
why the operand changes here rather than the verdict gaining a window.
|
|
814
|
+
|
|
815
|
+
**A mismatch is usually one `git fetch origin` old, so `git worktree remove
|
|
816
|
+
--force <path>` first, then fetch and re-create once before reporting it.**
|
|
817
|
+
`git worktree add --detach <path> origin/<branch>` resolves the LOCAL
|
|
818
|
+
remote-tracking ref (measured above), so the ordinary cause is this clone's
|
|
819
|
+
own staleness, and re-creating after a fetch costs seconds where the refusal
|
|
820
|
+
costs a dispatch. **Bounded at one retry**: still unequal after the fetch →
|
|
821
|
+
refuse and report, because the second reading is a push that landed while
|
|
822
|
+
you worked, or a ref this clone cannot resolve, and neither gets better with
|
|
823
|
+
more waiting.
|
|
824
|
+
|
|
825
|
+
`review-core.mjs` refuses a snapshot whose head is not the branch ref's, so the
|
|
826
|
+
review path is backstopped — except when the operand comes back
|
|
827
|
+
empty, which skips the compare rather than refusing on it. A same-repo PR
|
|
828
|
+
still reads `refs/heads/<branch>` first and falls back to
|
|
829
|
+
`refs/pull/<number>/head` only when that comes back empty; a cross-repo PR (a
|
|
830
|
+
fork) skips the branch-ref read entirely and goes straight to the pull ref,
|
|
831
|
+
because a fork's branch NAME can collide with an unrelated branch the base
|
|
832
|
+
repo already carries under that name (#1616) — so a fork PR now gets this
|
|
833
|
+
operand populated in the ordinary case, and the skip is rare rather than the
|
|
834
|
+
norm for forks. Its run log names the skip: `head ref (absent): head check
|
|
835
|
+
SKIPPED`. A worktree you hand to an agent directly is not backstopped at all.
|
|
836
|
+
Verify here anyway. **That backstop now compares against the same ref this
|
|
837
|
+
bullet does** — #1513 moved its operand off `headRefOid` for the reason
|
|
838
|
+
above — so it is a second
|
|
839
|
+
chance to notice a stale snapshot on the one path it covers, never a reason
|
|
840
|
+
to skip the ref compare here.
|
|
841
|
+
|
|
842
|
+
## Phase 2 — dispatch the Pull's implementer
|
|
843
|
+
|
|
844
|
+
**A Pull is one claim followed by one dispatch of a new member under a name no
|
|
845
|
+
member has held; nothing holds a queue.** The implementer cap is the fleet's
|
|
846
|
+
own accounting rather than anything the runtime enforces, and the member is
|
|
847
|
+
fresh and never a wake of one that already ran. Admission is per slot and
|
|
848
|
+
never batched, so there is nothing to hand a freed slot its next ticket but
|
|
849
|
+
the next Pull.
|
|
850
|
+
|
|
851
|
+
a Pull dispatches its member with one more `task` call — definition `fleet-implementer`, or `fleet-implementer-alt` on every 5th Pull; name `impl-<N>`; in the background, so its report arrives on its own.
|
|
852
|
+
|
|
853
|
+
**No workpool, and no kernel-resident handle.** A pool's only refill virtue —
|
|
854
|
+
handing a queued item to a freed worker without a controller turn — is exactly
|
|
855
|
+
what a Pull forbids, and its completions never arrive per member. `eval`'s
|
|
856
|
+
`agent()` is not the omp call either: a kernel-resident handle dies with the
|
|
857
|
+
kernel and needs a `wait`, while a `task` job is process-level and its report
|
|
858
|
+
auto-delivers on its own, like every other member's.
|
|
859
|
+
|
|
860
|
+
**No per-call tier or effort anywhere on this path**: tier stays the agent
|
|
861
|
+
definition's own frontmatter (ADR 0005), whichever of the two definitions the
|
|
862
|
+
Pull names, and a member's Resolved tier stays readable from its transcript.
|
|
863
|
+
|
|
864
|
+
**Claim what you are about to dispatch; dispatch what you have just claimed.**
|
|
865
|
+
Phase 1 makes the claim, serially in the main checkout — its rule is measured —
|
|
866
|
+
and the dispatch follows it at once. A claim that runs ahead of its dispatch is
|
|
867
|
+
a worktree, a branch and an `in-progress` label with no member behind them,
|
|
868
|
+
released by the end-of-run sweep rather than by a member that did the work.
|
|
869
|
+
|
|
870
|
+
**Record the dispatch before you make it.** `ledger.mjs row` wrote the row at
|
|
871
|
+
the Pull's step 7; `~/.fleet/bin/fleet-run ledger.mjs dispatch <N> impl-<N>`
|
|
872
|
+
then marks `impl-<N>` live on it and in `## Dispatched`, and the call follows.
|
|
873
|
+
Live implementers are the `impl-` tokens with no `=<outcome>` — the tick reads
|
|
874
|
+
that count off the ledger, and nobody states it. `dispatch` refuses once the
|
|
875
|
+
run is draining: drain stops supply.
|
|
876
|
+
|
|
877
|
+
**The prompt carries only what varies.** Everything shared — the
|
|
878
|
+
unattended-member block, the `edit`/`read` absolute-path rule (#1727), the
|
|
879
|
+
issue re-read and re-derive backstop, commit incrementally, no `git stash`, the
|
|
880
|
+
shared `eval` kernel (#1447), enumerate-and-declare, sizing and the PR steps —
|
|
881
|
+
is the body of `agents/fleet-implementer.agent.md`, byte-identical in
|
|
882
|
+
`agents/fleet-implementer-alt.agent.md`, and each harness injects it as the
|
|
883
|
+
member's system prompt. Never re-paste it. The prompt fills that body's
|
|
884
|
+
placeholders — the ticket number, the worktree abs path and branch
|
|
885
|
+
(`<abs-path>`, `<branch>`), the scratch path `<scratch>/impl-<N>/`, and the
|
|
886
|
+
distilled brief (`<distilled brief>`): the title plus the `## Agent Brief`
|
|
887
|
+
comment or the issue body, whichever carries the brief, and its `Out of
|
|
888
|
+
scope`, pasted verbatim from the Pull's own read. Beyond those it carries only
|
|
889
|
+
the lines **Rules that fail silently** above say every dispatch prompt
|
|
890
|
+
carries — the report is a message, reports are not acknowledged, the suite
|
|
891
|
+
runs in the foreground — the class's correction-ticket discipline when
|
|
892
|
+
`class=correction`, and a `staleness.mjs` **could not check** verdict with its
|
|
893
|
+
reason when the Pull got one, so the member's own re-derive step knows the
|
|
894
|
+
controller's probe could not look.
|
|
895
|
+
|
|
896
|
+
**The prompt pastes the Pull's own read of the ticket rather than telling the
|
|
897
|
+
member to re-fetch it, and this still costs one `gh issue view` per ticket,
|
|
898
|
+
never one per member.** The fresh-context design's isolation rationale — "every
|
|
899
|
+
implementer re-reads its Agent Brief... from scratch"
|
|
900
|
+
(`docs/specs/2026-07-22-run-team-agent-fleet-design.md:178-179`) — is about a member
|
|
901
|
+
never inheriting another ticket's context, not about where the bytes come from.
|
|
902
|
+
Pasting the Pull's own read into the prompt keeps that: the member still gets the
|
|
903
|
+
brief verbatim and re-derives nothing from a sibling. What it drops is the
|
|
904
|
+
unconditional re-fetch of an issue the controller already has open, on every
|
|
905
|
+
dispatch — the fetch the agent body still carries is the backstop for a brief
|
|
906
|
+
that turns out to be insufficient, not the default path.
|
|
907
|
+
|
|
908
|
+
**A member settling with nothing is not, by itself, a bail.** Each member's
|
|
909
|
+
outcome arrives as its own job status. Settle (CONTEXT.md § Coordination) is
|
|
910
|
+
three states on omp — `completed`, `failed`, `cancelled` — and reading
|
|
911
|
+
`failed`/`cancelled` the same as a `completed` turn that had nothing to report
|
|
912
|
+
is the exact collapse this line blocks: a member that died never chose to bail,
|
|
913
|
+
so demoting its ticket on its silence demotes a ticket its member never got the
|
|
914
|
+
chance to judge. Confirm death first, exactly as the Member-killed row does
|
|
915
|
+
(Failure handling, below) — its mtime discriminator, never silence alone.
|
|
916
|
+
**Only an explicit bail report — the member itself naming the cause — reaches
|
|
917
|
+
Implementer bails before implementing** (phase 3, below); a died or
|
|
918
|
+
merely-quiet member's silence never does. A confirmed-dead member recovers
|
|
919
|
+
exactly as the Member-killed row says — new member, new name, the SAME ticket —
|
|
920
|
+
never a demotion.
|
|
921
|
+
|
|
922
|
+
**Dispatch every implementer as `agent: "fleet-implementer"`, and still
|
|
923
|
+
omit `model` on the `task` call, whatever the class.** The tier now lives in that
|
|
924
|
+
definition's frontmatter (`agents/fleet-implementer.agent.md`), which is what an
|
|
925
|
+
omitted `model` takes first — the session's tier applies only when the definition
|
|
926
|
+
names none, and a member dispatched with `model` set does not get the declared
|
|
927
|
+
tier back. Omitting `model` is therefore still the mechanism; what changed is
|
|
928
|
+
that the tier it resolves to is now declared and pinned rather than inherited by
|
|
929
|
+
accident. Keep `name: impl-<N>`: the name is what makes a member, and both the
|
|
930
|
+
spend classifier and `member-outcomes.mjs` read it.
|
|
931
|
+
|
|
932
|
+
**After every Pull's dispatch, run the tier check — a scripted step, never a
|
|
933
|
+
prose reminder.** `~/.fleet/bin/fleet-run tier-check.mjs --batch <path-to-batch.json>`
|
|
934
|
+
judges the implementer just dispatched on the ledger's terms. The definition it
|
|
935
|
+
should have run under comes off its ticket row's `tier=` token: none means
|
|
936
|
+
`fleet-implementer`, `tier=<x>` means `fleet-implementer-<x>` (`tier=alt` →
|
|
937
|
+
`fleet-implementer-alt`). It fails the member two ways, one line each —
|
|
938
|
+
`member: dispatched <agent>, expected <definition>` when its transcript says
|
|
939
|
+
it was dispatched as anything else (a generic `task` dispatch fails even when
|
|
940
|
+
its model happens to match), and `member: declared <m>/<l> resolved <m>/<l>`
|
|
941
|
+
when the harness resolved a different model or level than that definition
|
|
942
|
+
declares. The verdict lands on the ledger either way, written by the check
|
|
943
|
+
itself: exit 0 appends `tier-ok=impl-<N>:<definition>` to the row, once
|
|
944
|
+
however often it runs; exit 1 runs `ledger.mjs settle impl-<N> tier-mismatch`
|
|
945
|
+
— or, for a member already settled another way, which `settle` will not
|
|
946
|
+
re-settle, appends `tier-mismatch=impl-<N>:<definition>` instead.
|
|
947
|
+
|
|
948
|
+
**The tick holds the next Pull until that verdict exists.** Dispatching the
|
|
949
|
+
next member on top of an unchecked or mismatched dispatch multiplies whatever
|
|
950
|
+
silently degraded. The tick prints `HOLD (tier unchecked impl-<N>)` for the
|
|
951
|
+
newest `impl-` member of a ticket whose row carries neither verdict, whether
|
|
952
|
+
that member is still running or already settled `bailed`, `killed` or
|
|
953
|
+
`released`, and `HOLD (tier mismatch impl-<N>)` for a mismatched one. Only the
|
|
954
|
+
newest member counts, so a replacement (`impl-<N>-b`) is what clears a
|
|
955
|
+
mismatch — and is then owed its own check. The tick never reads a
|
|
956
|
+
transcript: clear an unchecked hold by running the check on that member with
|
|
957
|
+
`session`, which works after it has settled too, because its
|
|
958
|
+
`<session>/<member>.jsonl` is written at dispatch. Clear a mismatch by fixing
|
|
959
|
+
the definition or the dispatch and dispatching the replacement at the right
|
|
960
|
+
tier.
|
|
961
|
+
|
|
962
|
+
**The batch file is a JSON array, one entry per dispatched member** — under
|
|
963
|
+
Pull, a batch of one, the member just dispatched: `{member, session}`.
|
|
964
|
+
`member` is the AgentId the dispatch returns (`impl-<N>`). `session` is the
|
|
965
|
+
SAME session directory `member-outcomes.mjs`/`board.mjs` are already handed
|
|
966
|
+
for this run; the check reads the member's own `<session>/<member>.jsonl`
|
|
967
|
+
directly, so a member with no assistant turn yet still resolves off its
|
|
968
|
+
dispatch-time record. A caller already holding the exact transcript path may
|
|
969
|
+
give `transcript` instead. Either one is required: the agent type an
|
|
970
|
+
implementer was dispatched as lives only in its transcript. `resolvedModel`
|
|
971
|
+
**and** `resolvedThinkingLevel` together — the dispatch's own job record —
|
|
972
|
+
may ride beside it and are preferred for the model and level. An `impl-`
|
|
973
|
+
entry carries no `agentFile`: its definition is the row's, never the
|
|
974
|
+
caller's. `transcript`/`session` resolve relative to `--repo` (defaults to
|
|
975
|
+
the plugin's own root), and the check reads and writes the run's own ledger
|
|
976
|
+
unless `--ledger` names another.
|
|
977
|
+
|
|
978
|
+
**The declaration is `model: "@<role>:<level>"` — a fleet tier route, never
|
|
979
|
+
a vendor id.** `@slow`, `@task`, `@smol` resolve through the operator's
|
|
980
|
+
`modelRoles`, so an install with no Anthropic model still runs the fleet
|
|
981
|
+
at whatever each role points at; the explicit `:<level>` suffix wins over
|
|
982
|
+
the role's baked one, and the tier check judges a member against the
|
|
983
|
+
role's own target (`modelRoles.<role>`), never a model family (ADR 0011,
|
|
984
|
+
ADR 0014).
|
|
985
|
+
|
|
986
|
+
Before the run's first dispatch run `~/.fleet/bin/fleet-run tier-roles.mjs
|
|
987
|
+
--check`; exit 1 names every definition whose `model:` is not a route,
|
|
988
|
+
every unset `modelRoles.<role>` a definition needs, and every
|
|
989
|
+
`task.agentModelOverrides` entry that would shadow a fleet definition,
|
|
990
|
+
prints the exact remedy, and **stops the run** before any member is
|
|
991
|
+
dispatched — the fleet reads that config and never writes it (ADR 0003).
|
|
992
|
+
|
|
993
|
+
**Every 5th Pull by ledger count goes at the alternate tier.** Count the `impl-`
|
|
994
|
+
rows in `.fleet/ledger.md` at Pull time; the Pull that creates row 5, 10, 15 …
|
|
995
|
+
dispatches `agent: "fleet-implementer-alt"` and records
|
|
996
|
+
`tier=alt` in the row, and a replacement inherits the row's tier. The
|
|
997
|
+
assignment rolls to the next Pull when the pulled ticket is `class=correction`
|
|
998
|
+
or another open ticket sequences after it — a ticket the rest of the run
|
|
999
|
+
depends on. Do not tell the member it is a control: a member that
|
|
1000
|
+
knows it is being measured is not measuring the same thing.
|
|
1001
|
+
|
|
1002
|
+
**Count the rate against the ledger, because a Pull is the dispatch unit.** One
|
|
1003
|
+
Pull is one member, so a rate counted per Pull is a rate counted per member —
|
|
1004
|
+
one implementer in five, however the Pulls fall across the run — and the
|
|
1005
|
+
ledger, not your memory, is what still holds the count after a compaction.
|
|
1006
|
+
|
|
1007
|
+
**Do not label it anywhere — the dispatch record already carries it.** The
|
|
1008
|
+
pairing is a query over `docs/metrics/member-outcomes.tsv` (the exact awk sits
|
|
1009
|
+
in that file's header): a `session` that ran BOTH implementer definitions at
|
|
1010
|
+
DIFFERENT `model`s — one member whose `subagent_type` is
|
|
1011
|
+
`fleet-implementer-alt`, another whose is `fleet-implementer`. That column is
|
|
1012
|
+
the record of what each member was dispatched AS, scraped like every other
|
|
1013
|
+
column, so it survives the file's regeneration and mislabels no historical row
|
|
1014
|
+
— a pre-rule session carries no such dispatch to find. A hand-set column would
|
|
1015
|
+
fail both of those tests, and one derived against today's declared tiers would
|
|
1016
|
+
mislabel every historical row.
|
|
1017
|
+
|
|
1018
|
+
**The query counts DELIBERATE pairs, and that is the whole of #1066.** The
|
|
1019
|
+
rule this replaces asked only for a `session`+`role` carrying more than one
|
|
1020
|
+
distinct `model`, which any session that happened to stage a routine ticket
|
|
1021
|
+
beside a correction one satisfies. Measured 2026-09-12 on one corpus: 198
|
|
1022
|
+
keys as that query is literally written, 35 sessions across 21 `run_date`s
|
|
1023
|
+
once restricted to implementers, against 17 real pairs across 8 — so the gate
|
|
1024
|
+
below read itself past its floor on sessions where nothing had been
|
|
1025
|
+
controlled. Dispatch alone is not enough either: both arms must actually have
|
|
1026
|
+
RUN different models, because a deliberate alt dispatch whose two arms resolve
|
|
1027
|
+
to the same model (a `modelRoles` override, measured on omp 2026-09-12)
|
|
1028
|
+
controls nothing.
|
|
1029
|
+
|
|
1030
|
+
**Why one in five within the run, not a week of one tier then a week of the other:**
|
|
1031
|
+
tier would then be confounded with calendar date and therefore with prompt
|
|
1032
|
+
evolution, which is exactly the state #864 documents and the reason the rows
|
|
1033
|
+
already on disk cannot answer the question they were collected for.
|
|
1034
|
+
|
|
1035
|
+
**`class=routine` → `sonnet` was REVERTED on 2026-08-16, by the guard below
|
|
1036
|
+
firing.** Both halves were met on the accumulated `docs/metrics/tier-outcomes.tsv`:
|
|
1037
|
+
the floor (8 `class=routine` PRs spanning 3 distinct `run_date`s) and the trigger
|
|
1038
|
+
(2 rows carrying `closed_own_ticket` `no` — PR #452, which regressed the exact
|
|
1039
|
+
defect its ticket existed to remove, and PR #466, which emitted invalid JSON in
|
|
1040
|
+
the very payload its three tickets existed to make truthful). Per the guard's own
|
|
1041
|
+
wording this reverts **`class=routine`**, never the rule wholesale: the Pull still
|
|
1042
|
+
records the class, it still governs the correction-ticket discipline, and it is
|
|
1043
|
+
still what a future control would be drawn from.
|
|
1044
|
+
|
|
1045
|
+
**Read the counter-evidence before restoring it.** Recount from the file before
|
|
1046
|
+
citing it — these figures are a snapshot, not a live count, and a doc-only
|
|
1047
|
+
append lands a row without touching this paragraph. **As of 2026-08-28, 103
|
|
1048
|
+
rows:** the file holds 66 `class=routine` PRs across 14 distinct `run_date`s,
|
|
1049
|
+
so the floor is long since met, and 6 of them carry `closed_own_ticket` `no`,
|
|
1050
|
+
so the trigger is met too. **Firing changes nothing: the action is "revert
|
|
1051
|
+
`class=routine` to top tier" and that revert already happened on 2026-08-16.**
|
|
1052
|
+
The guard is in its fired state and has no further move; the live question is
|
|
1053
|
+
the opposite one, restoring a cheaper tier, which this guard does not decide
|
|
1054
|
+
and which no row on file settles.
|
|
1055
|
+
|
|
1056
|
+
The raw split still favours the top tier — 3 failures in 11 `routine`/`sonnet`
|
|
1057
|
+
rows against 3 in 55 `routine`/`opus`. **Do not read that as a tier result.**
|
|
1058
|
+
Tier remains largely confounded with calendar date and therefore with prompt
|
|
1059
|
+
evolution: 8 of the 11 `sonnet` rows fall on 2026-08-13 to 08-17, before the
|
|
1060
|
+
window in which 54 of the 55 `opus` rows were run, and the dispatch prompts
|
|
1061
|
+
gained rules throughout. The confound is **weakened, not resolved.** Three
|
|
1062
|
+
`sonnet` rows now break it rather than one — **#714** (2026-08-20, a
|
|
1063
|
+
maintainer-authorized deliberate control) and **#750** and **#751**
|
|
1064
|
+
(2026-08-21) — all three run against prompts of the same vintage as the `opus`
|
|
1065
|
+
rows, and **all three passed**, which is the direction opposite the raw split.
|
|
1066
|
+
Three is still not a result. **What replaces this argument going forward is the
|
|
1067
|
+
within-run pairing above**: one implementer in five at the alternate tier makes
|
|
1068
|
+
tier orthogonal to date by construction, so the question stops depending on
|
|
1069
|
+
whichever rows history happened to leave. **Orthogonal to date, and to nothing
|
|
1070
|
+
else** — the alternate member is whichever ticket the 5th Pull draws, rolling
|
|
1071
|
+
past every correction and every ticket another open one sequences after, while
|
|
1072
|
+
the top tier absorbs all of those, so the pairing trades the calendar confound
|
|
1073
|
+
for a difficulty one that runs in a known direction. That is why the four covariates
|
|
1074
|
+
exist: condition a pair comparison on `sizing`/`profile`/`loc`/`files` before
|
|
1075
|
+
reading it as a tier result, never on the raw split.
|
|
1076
|
+
|
|
1077
|
+
`minted_false_claim` **discriminates and no longer reads "always yes"** — 20 of
|
|
1078
|
+
the 66 `routine` rows carry `no`, 18 at `opus` and 2 at `sonnet` (#714, #750).
|
|
1079
|
+
Read it as a property of the TICKET before the tier: a pure code simplification
|
|
1080
|
+
need not add prose, while a correction ticket adds prose by construction. The
|
|
1081
|
+
honest summary is unchanged and is the reason this paragraph exists: the guard
|
|
1082
|
+
fired on the criterion the maintainer chose in advance, not on a demonstration
|
|
1083
|
+
that the cheaper tier is worse.
|
|
1084
|
+
|
|
1085
|
+
**No class recorded → record `class=unknown`, never a guess.** Since the revert
|
|
1086
|
+
every class dispatches the same way, so a lost class no longer misprices a
|
|
1087
|
+
member — but it still costs the **correction-ticket discipline**, which phase 2
|
|
1088
|
+
selects on the class and which is the half that caught real defects. Every path
|
|
1089
|
+
that loses it lands here — a compaction, a Pull whose read did not survive
|
|
1090
|
+
one, a killed member replaced from inherited state. Writing the gap down is what makes it visible; re-read the issue to
|
|
1091
|
+
recover the class when a correction's discipline is worth one `gh issue view`.
|
|
1092
|
+
**Never infer the class from the tier** — that inference is what the revert
|
|
1093
|
+
removed, and a future control would break it again.
|
|
1094
|
+
|
|
1095
|
+
Carry the class in the ticket's ledger row, written before dispatch like every
|
|
1096
|
+
other field:
|
|
1097
|
+
|
|
1098
|
+
```
|
|
1099
|
+
ledger.mjs row <N> "impl-<N> · class=routine"
|
|
1100
|
+
ledger.mjs row <N> "impl-<N> · class=correction"
|
|
1101
|
+
ledger.mjs row <N> "impl-<N> · class=unknown"
|
|
1102
|
+
```
|
|
1103
|
+
|
|
1104
|
+
`row` **replaces the whole line**, it does not append. Re-dispatching over a row
|
|
1105
|
+
that already carries `KILLED`, `ports=` or `→ PR#` must repeat those tokens or
|
|
1106
|
+
they are gone, with only `rewrote row #N` on stderr to say so. Recover a class
|
|
1107
|
+
after a compaction with `ledger.mjs read` — `class=` is a raw-row field, and the
|
|
1108
|
+
cockpit does not parse or surface it.
|
|
1109
|
+
|
|
1110
|
+
`ledger.mjs read` is safe on a pipe as well as a redirect: its payload used to
|
|
1111
|
+
be abandoned at the pipe buffer and still exit 0, which is what left `board.mjs`
|
|
1112
|
+
reporting `ledger read parse failed` and serving a blind cockpit for a whole run
|
|
1113
|
+
(#246). Every use above is a recovery path, so a payload that arrives short
|
|
1114
|
+
lands exactly where a lost class or a settled `ruled:` is unrecoverable — which
|
|
1115
|
+
is why the script's own suite pins that `read`, `row`, `filed` and `ruled` each
|
|
1116
|
+
reach a pipe whole.
|
|
1117
|
+
|
|
1118
|
+
`check` reaches a pipe whole at both of its exits too. Its ALREADY FILED exit
|
|
1119
|
+
sits mid-branch, where falling through would run the near-miss ranking and the
|
|
1120
|
+
tracker search that exit exists to skip — so `check`'s branch is a function now,
|
|
1121
|
+
where `process.exitCode` carries the code and a `return` is what skips them
|
|
1122
|
+
(#808). No payload this script prints is abandoned to `process.exit()` any more,
|
|
1123
|
+
and the suite drives both of `check`'s arms through a pipe on a payload the
|
|
1124
|
+
ledger sizes rather than argv. So trust that payload — and read `verdict`,
|
|
1125
|
+
because a searched-and-clean tracker and one that was never read share exit 0.
|
|
1126
|
+
|
|
1127
|
+
The consumer side raised its cliff rather than removing it. `board.mjs` reads
|
|
1128
|
+
`ledger.mjs read` with an explicit `maxBuffer`, so a payload past node's
|
|
1129
|
+
default is carried rather than killed mid-flight and reported as an
|
|
1130
|
+
unreachable tool — which is how the blind cockpit came back at HTTP 200 even
|
|
1131
|
+
after the pipe cut was gone (#807). That cap is deliberately bounded, so a
|
|
1132
|
+
payload past it lands in the same blind cockpit — and so does a ledger that
|
|
1133
|
+
cannot be read at all, at any size. The read fails open to an empty ledger, and
|
|
1134
|
+
`board.json`'s `ledgerState` field now distinguishes a read that failed or
|
|
1135
|
+
didn't parse from one that succeeded (`unread`/`unparsed`/`read`, #816) —
|
|
1136
|
+
`spend` in the same payload carries its own error the same way (#874). Zeroes
|
|
1137
|
+
on the cockpit are not yet proof the pipeline is idle.
|
|
1138
|
+
|
|
1139
|
+
**Guard: accumulate per PR, never conclude inside one run.** The unit is the PR —
|
|
1140
|
+
supply is one Pull per free slot, so there are no implementer batches. **Append one row to
|
|
1141
|
+
`docs/metrics/tier-outcomes.tsv` when you rule each PR's review, with
|
|
1142
|
+
`~/.fleet/bin/fleet-run tier-outcomes.mjs append <pr> --class <class> --closed-own-ticket yes|no --minted-false-claim yes|no --note "<text>"`,
|
|
1143
|
+
never by hand** (that file's header carries the column meanings). The script
|
|
1144
|
+
fills `run_date`, `pr`, `ticket` and `tier` itself — `tier` from what actually
|
|
1145
|
+
ran, off the implementer's `tier-ok=` ledger verdict or else its one
|
|
1146
|
+
member-outcomes row, and BLANK with a WARNING naming why when neither settles
|
|
1147
|
+
it; never type a tier in over that. A PR that already has a row is left
|
|
1148
|
+
untouched, so re-running it is safe. That append is the whole duty; the guard
|
|
1149
|
+
fires on the accumulated file, across runs, not on the run in front of you.
|
|
1150
|
+
|
|
1151
|
+
The row's last four fields are the ticket's difficulty, and they are what lets a
|
|
1152
|
+
tier comparison condition on the thing that swamps it. `sizing` is the
|
|
1153
|
+
**member's** own `light`/`heavy` verdict from its phase-2 `sizing-a-ticket`
|
|
1154
|
+
run, read back off the PR body's `Sizing:` line (`gh pr view <pr> --json body`),
|
|
1155
|
+
which names the signal the verdict turned on beside the verdict itself;
|
|
1156
|
+
`profile`, `loc` and `files` all come from `diff-stats.mjs` over the merged
|
|
1157
|
+
diff. **Phase 0 does not size anything** — it shortlists, a Pull claims, and
|
|
1158
|
+
the sizing run happens inside the member after both, which is why the verdict
|
|
1159
|
+
has to travel in the PR body rather than being something you already hold.
|
|
1160
|
+
|
|
1161
|
+
**A verdict is a measurement only if it post-dates the run that produced it.** A
|
|
1162
|
+
`Sizing:` line typed in before the skill ever ran is byte-identical to one the
|
|
1163
|
+
skill produced, so the body cannot settle this alone and the member's report
|
|
1164
|
+
carries the second source: when it ran `sizing-a-ticket` relative to opening the
|
|
1165
|
+
PR (#1070, measured on a member that wrote the line first, caught itself, and
|
|
1166
|
+
corrected it). **Record `sizing` only when the report places that run before the
|
|
1167
|
+
PR AND the line carries its signal.** Ordering clause missing, verdict authored
|
|
1168
|
+
before the run with no corrected value reported, or body and report naming
|
|
1169
|
+
different verdicts — leave the field BLANK and say which in `note`. Do not
|
|
1170
|
+
re-derive the verdict from the diff to fill the gap: `sizing-a-ticket` weighs
|
|
1171
|
+
more than file count, and a substituted proxy reads as measured too. **A value
|
|
1172
|
+
not in hand is left BLANK, never estimated** — blank reads as unknown and drops
|
|
1173
|
+
the row from a stratified comparison, while a guess reads as measured and
|
|
1174
|
+
poisons one. Blank still means the field is WRITTEN and empty: omit the flag
|
|
1175
|
+
(`--sizing`, `--profile`, `--loc`, `--files`) and the script writes that field
|
|
1176
|
+
empty at full width, because a row of some in-between width cannot be told
|
|
1177
|
+
apart from a shifted one. The `note` field is free text and sits before those
|
|
1178
|
+
four, so the script refuses a tab or newline in it: one tab would shift all
|
|
1179
|
+
four for that row alone.
|
|
1180
|
+
|
|
1181
|
+
**Then record the run's member facts — do not author them.** Scrape EVERY session
|
|
1182
|
+
directory for this cwd, not one:
|
|
1183
|
+
|
|
1184
|
+
```bash
|
|
1185
|
+
PROJECT_DIR="$(node -e 'import("./scripts/board.mjs").then(m => console.log(m.encodeProjectDir(process.cwd())))')"
|
|
1186
|
+
for d in "$HOME/.omp/agent/sessions/$PROJECT_DIR"/*/; do
|
|
1187
|
+
node scripts/member-outcomes.mjs "$d"
|
|
1188
|
+
done
|
|
1189
|
+
```
|
|
1190
|
+
|
|
1191
|
+
`encodeProjectDir` (`scripts/board.mjs`) encodes the cwd the way omp's own
|
|
1192
|
+
session directory naming does — every non-alphanumeric character becomes
|
|
1193
|
+
`-`, with a leading dot segment's dot PRESERVED rather than folded into the
|
|
1194
|
+
dash run (`member-record.test.mjs`'s regression case: `.claude` becomes
|
|
1195
|
+
`-.claude`, not `--claude`) — and hand-guessing that path is why the fleet's
|
|
1196
|
+
own panel once rendered nothing here. The trailing `/` on the glob matters:
|
|
1197
|
+
the same encoded-cwd directory also holds this cwd's own top-level session
|
|
1198
|
+
transcripts as loose FILES sibling to the per-session directories, and a
|
|
1199
|
+
glob without it would try to scrape one of those as if it were a session.
|
|
1200
|
+
|
|
1201
|
+
**Do not narrow this to "this run's session" with `findSubagentsDir`.** That helper
|
|
1202
|
+
answers a different question — the session with the NEWEST transcript for this cwd,
|
|
1203
|
+
which is not the same as the one you are in. Any other session sharing this cwd —
|
|
1204
|
+
a second terminal, a second controller run — can hold a newer transcript than
|
|
1205
|
+
yours at the moment you reach this step, and a second session dispatching
|
|
1206
|
+
anything while you reach it wins the tie: the run then re-scrapes a stranger's
|
|
1207
|
+
members, prints a plausible row count and exits 0 while its own facts are
|
|
1208
|
+
never recorded. Looping every session dir costs a few seconds, cannot pick
|
|
1209
|
+
wrong, and is idempotent by construction.
|
|
1210
|
+
|
|
1211
|
+
The scraper takes the session directory itself and refuses a path it cannot
|
|
1212
|
+
read — a missing, unreadable or non-directory path all exit 2 — so a wrong
|
|
1213
|
+
path fails loudly instead of writing nothing and exiting 0. It reports the
|
|
1214
|
+
run's own YIELD, `scraped N of M members (D dropped)`, alongside the file's
|
|
1215
|
+
total: read the yield, because the total is the whole corpus and looks
|
|
1216
|
+
healthy even when every member of this session dropped.
|
|
1217
|
+
|
|
1218
|
+
It derives every row from the member transcripts omp already wrote — both the
|
|
1219
|
+
flat ones and a member's own nested fan-out one level down — so a
|
|
1220
|
+
second run over the same session changes nothing and a re-run after a member is
|
|
1221
|
+
re-dispatched picks the new transcript up. **Never hand-edit
|
|
1222
|
+
`docs/metrics/member-outcomes.tsv`** — it is regenerated wholesale whenever the
|
|
1223
|
+
role classifier changes, and a hand-entered value would not survive that. The
|
|
1224
|
+
verdict for a PR goes to `tier-outcomes.tsv` through `tier-outcomes.mjs
|
|
1225
|
+
append`, as above. Once both files hold this run's rows, and before either is
|
|
1226
|
+
committed, run `~/.fleet/bin/fleet-run tier-outcomes.mjs check --live`. Exit 1
|
|
1227
|
+
names each row whose `tier` disagrees with the one implementer the member facts
|
|
1228
|
+
say ran for its ticket: correct that row's `tier` to the short name it prints,
|
|
1229
|
+
or blank it and say why in `note`. Each WARNING names a PR this run's ledger
|
|
1230
|
+
marks `reviewed=` that has no row yet — append it before committing if it is
|
|
1231
|
+
an implementer PR.
|
|
1232
|
+
|
|
1233
|
+
Both files are the run's own artifacts and neither commits itself. Carry them to
|
|
1234
|
+
main the same way the run carries any other controller-authored change; leaving a
|
|
1235
|
+
regenerated 5,000-row corpus uncommitted in the checkout is how it gets discarded by
|
|
1236
|
+
the next `git checkout` with nothing to show it ever ran.
|
|
1237
|
+
|
|
1238
|
+
**Commit both to `chore/run-artifacts-<date>` and open a PR — at end of run, and
|
|
1239
|
+
that branch name is the convention rather than a suggestion.** Phase 0's
|
|
1240
|
+
fast-forward step calls this the previous run's close-out PR and says the rules
|
|
1241
|
+
THIS run needs arrive in it, so the next controller goes looking for it by shape;
|
|
1242
|
+
a name of your own invention still merges and still cannot be found. Suffix a
|
|
1243
|
+
letter when the date already has one (`chore/run-artifacts-2026-08-23b`).
|
|
1244
|
+
|
|
1245
|
+
**Data rows and rule-doc prose never share a PR — one branch each, and when the
|
|
1246
|
+
rules here compete this is the one to keep.** The two halves have opposite cost
|
|
1247
|
+
profiles, and bundling makes the cheap-to-strand half gate the expensive one.
|
|
1248
|
+
Stranding a data row loses it: the tier guard re-derives its floor from the
|
|
1249
|
+
undercount and re-fires, the same stale-file failure Phase 0's fast-forward step
|
|
1250
|
+
exists to catch, and `member-outcomes.tsv` is regenerated from harness
|
|
1251
|
+
transcripts this repo does not own, so re-running the scrape later is worth only
|
|
1252
|
+
what the harness still holds. Stranding a rule change costs the status quo, which
|
|
1253
|
+
is where it already was. So `chore/run-artifacts-<date>` carries the two
|
|
1254
|
+
`docs/metrics/` files and nothing else, and prose that wants review goes on its
|
|
1255
|
+
own branch with its own PR.
|
|
1256
|
+
|
|
1257
|
+
**Why not decide inside one run.** A run holds 2-3 implementer PRs, and ticket
|
|
1258
|
+
difficulty swamps the tier effect — a gojq parity harness and a two-statement
|
|
1259
|
+
shell reorder are not comparable units. Finding-counts are not comparable either:
|
|
1260
|
+
`selectDimensions` trims the fan-out by diff profile, so one PR fields 29 agents
|
|
1261
|
+
over six dimensions and its sibling fields 8 over three. And the fleet is not
|
|
1262
|
+
stationary — this prompt gets edited mid-run when a defect earns it. Hence a
|
|
1263
|
+
binary outcome per PR, accumulating, rather than a per-run verdict.
|
|
1264
|
+
|
|
1265
|
+
**Why the rows this guard fired on could not answer the tier question, and this
|
|
1266
|
+
is the load-bearing part.** Until the 2026-08-16 revert, `class` and `tier` were
|
|
1267
|
+
perfectly confounded: routine always ran `sonnet`, correction always ran top
|
|
1268
|
+
tier. So the comparison the file invites — routine-at-sonnet against
|
|
1269
|
+
correction-at-top-tier — measures **class, not tier**, because those classes fail
|
|
1270
|
+
in different ways by construction: corrections ship false claims in prose,
|
|
1271
|
+
routines ship incomplete or regressing code. A run that "mixes both" does not fix
|
|
1272
|
+
it. **Only a same-class comparison across tiers is informative**, and the old
|
|
1273
|
+
rule could not produce one, since no routine ticket ever ran at top tier.
|
|
1274
|
+
|
|
1275
|
+
**That last sentence is no longer true, and this is the part to re-read.** Since
|
|
1276
|
+
the revert every routine ticket runs at top tier, so the file now holds 55
|
|
1277
|
+
`routine`/`opus` rows against 11 `routine`/`sonnet` (as of 2026-08-28, 103 rows
|
|
1278
|
+
— recount before citing). The same-class comparison the paragraph above calls
|
|
1279
|
+
the only informative one therefore EXISTS now. It is still not clean: the two
|
|
1280
|
+
groups are split almost entirely by calendar date, so it measures prompt
|
|
1281
|
+
evolution at least as much as tier. The counter-evidence paragraph earlier in
|
|
1282
|
+
this section carries the split and the three rows that cut against it. Recount
|
|
1283
|
+
both, and every other figure in this section, with:
|
|
1284
|
+
|
|
1285
|
+
```bash
|
|
1286
|
+
grep -vc '^#' docs/metrics/tier-outcomes.tsv
|
|
1287
|
+
awk -F'\t' '!/^#/ && $4=="routine" {n++; d[$1]=1; if($6=="no") no++} \
|
|
1288
|
+
END{print n, length(d), no+0}' docs/metrics/tier-outcomes.tsv
|
|
1289
|
+
awk -F'\t' '!/^#/ && $4=="routine" {t[$5]++; if($6=="no") f[$5]++} \
|
|
1290
|
+
END{for(k in t) print k, t[k], f[k]+0}' docs/metrics/tier-outcomes.tsv
|
|
1291
|
+
```
|
|
1292
|
+
|
|
1293
|
+
**These rows are the historical corpus, and nothing appended to them fixes the
|
|
1294
|
+
confound.** What fixes it is the within-run pairing in the dispatch rule above:
|
|
1295
|
+
from now on one implementer in every five runs at `sonnet` beside the `opus`
|
|
1296
|
+
ones, against the same prompts on the same day, so the comparison stops depending on
|
|
1297
|
+
which tier history happened to leave in which week. Read the pairs, not the
|
|
1298
|
+
whole-file split, once there are enough of them.
|
|
1299
|
+
|
|
1300
|
+
**So read what the guard actually established: routine tickets sometimes fail to
|
|
1301
|
+
close their own ticket. Not that `sonnet` caused it.** The revert is the
|
|
1302
|
+
pre-committed rule being honoured, not a measurement. Restoring a cheap tier is
|
|
1303
|
+
still the maintainer's call and still a change to the dispatch rule — but the
|
|
1304
|
+
deliberate control it used to require is no longer something anyone has to
|
|
1305
|
+
authorize one ticket at a time: the alternate-tier dispatch above produces one
|
|
1306
|
+
in every five Pulls by construction. **Do not read the pairs early.** Report the count —
|
|
1307
|
+
the DELIBERATE count, from the query in `member-outcomes.tsv`'s header, which
|
|
1308
|
+
prints the pair count and its distinct `run_date`s and counts only sessions
|
|
1309
|
+
that ran both implementer definitions at different models — and stop until
|
|
1310
|
+
there are at least ten of them across five or more distinct `run_date`s; below
|
|
1311
|
+
that, a pair count is a number, not evidence, and the last guard fired with
|
|
1312
|
+
n=1 on the control side. **Report whichever number that query prints, never a
|
|
1313
|
+
number from any other one:** the query it replaces (#1066) counted every
|
|
1314
|
+
session whose implementers merely differed, so it cleared this floor by an
|
|
1315
|
+
order of magnitude while the controlled comparison did not exist yet.
|
|
1316
|
+
|
|
1317
|
+
The risk being priced is economic, not shipped bugs. Reviews run 3-5x *longer*
|
|
1318
|
+
than implementation (Red flags, below), so one extra fix-round costs an implementer slot
|
|
1319
|
+
and eats the saving the cheaper implementer made. The revert needs a floor AND a
|
|
1320
|
+
trigger, and neither alone. **Floor:** the file holds at least
|
|
1321
|
+
three `class=routine` PRs spanning **two or more distinct `run_date`s**.
|
|
1322
|
+
**Trigger, read only once the floor is met:** **two or more** of those rows carry
|
|
1323
|
+
`closed_own_ticket` `no`, or the implementer
|
|
1324
|
+
share in `board.mjs build`'s `.spend.roles` is climbing →
|
|
1325
|
+
revert **`class=routine`** to top tier, never the rule wholesale. That floor is
|
|
1326
|
+
over the accumulated file, never one run — and the `run_date` half is what makes
|
|
1327
|
+
that literal instead of merely asserted: a PR count alone is satisfied by a
|
|
1328
|
+
single run's rows, which is the state this file ships in. Without the floor a
|
|
1329
|
+
single noisy PR reverts a class; without a `no` count, "trending" names no
|
|
1330
|
+
threshold and whether the guard fires is undefined. Per-`impl-<N>`
|
|
1331
|
+
spend is not available from `.spend.top`: it labels agents by the member
|
|
1332
|
+
name, but holds only the eight largest spenders.
|
|
1333
|
+
|
|
1334
|
+
**Never read the guard's silence as a pass** — and never read a single run's rows
|
|
1335
|
+
as its verdict.
|
|
1336
|
+
Why the agent body carries what it does — read this before editing either agent
|
|
1337
|
+
file, and keep the two bodies byte-identical. Each rule in the body's
|
|
1338
|
+
enumerate-and-declare block is load-bearing, for a different reason.
|
|
1339
|
+
**Enumerate-and-declare** answers a signature measured four times in one run:
|
|
1340
|
+
each implementer fixed exactly the cases its ticket named and left an adjacent
|
|
1341
|
+
one of the same class broken — a CRLF body **broken by** the fix for depth and
|
|
1342
|
+
split headings, a symlinked worktree after fixing locked and regular-file ones,
|
|
1343
|
+
an unreadable `refs/heads/<type>/` after fixing `refs/heads` itself, a bracketed
|
|
1344
|
+
file path after fixing typos and vendored ones. **All four failed to close their
|
|
1345
|
+
own ticket** — #65's acceptance criterion went unmet, and the other three left
|
|
1346
|
+
the named defect reachable by a sibling spelling. Every one was caught by
|
|
1347
|
+
review, at review cost, which runs 3-5x the implementation it checks.
|
|
1348
|
+
|
|
1349
|
+
**Prose-first** and **wrongly-REFUSE** are not padding — they are the #394 case,
|
|
1350
|
+
which shipped with **enumerate-and-declare** already in its prompt. It missed a
|
|
1351
|
+
shape its own ticket named in passing, because it enumerated from the mechanism
|
|
1352
|
+
instead of the text; and it introduced a regression refusing every `node --test`
|
|
1353
|
+
flag, because it enumerated what the guard should catch and never what it could
|
|
1354
|
+
wrongly refuse.
|
|
1355
|
+
|
|
1356
|
+
The commit-incrementally block is not optional. A member that goes idle mid-task
|
|
1357
|
+
leaves its diff only in the worktree, and the controller cannot reap, replace,
|
|
1358
|
+
or even see it — `worktree-audit.sh`'s committed-vs-uncommitted split is exactly
|
|
1359
|
+
what decides whether a replacement redoes or destroys work. Observed twice in
|
|
1360
|
+
one run.
|
|
1361
|
+
|
|
1362
|
+
**The identity block is what makes `sizing-a-ticket`'s fleet entry reachable.**
|
|
1363
|
+
That skill conditions its heavy-row entry on the reader being a fleet member; a
|
|
1364
|
+
reader that takes itself for a solo session gets `superpowers:brainstorming`
|
|
1365
|
+
instead, whose `<HARD-GATE>` withholds every implementation action until a human
|
|
1366
|
+
partner approves — approval no unattended member can obtain, so it parks rather
|
|
1367
|
+
than fails. Nothing else you carry says what the member is — an incidental
|
|
1368
|
+
mention of the controller is not a statement that the reader is one of its
|
|
1369
|
+
members. That skill keeps its condition, so a solo session still runs the
|
|
1370
|
+
interactive path; this block is what puts a member on the fleet side of it.
|
|
1371
|
+
|
|
1372
|
+
A member that bails demotes nothing itself; demotion by cause is yours
|
|
1373
|
+
(**Implementer bails before implementing**).
|
|
1374
|
+
|
|
1375
|
+
## Phase 3 — event loop
|
|
1376
|
+
|
|
1377
|
+
React to events; never block on one.
|
|
1378
|
+
|
|
1379
|
+
**React to artifacts, not agents.** `idle` means "not currently executing", not
|
|
1380
|
+
"done", and a finished member's finding may never arrive. Read `gh pr view`,
|
|
1381
|
+
`gh run view`, `git -C <worktree> status` **before** messaging; when you message,
|
|
1382
|
+
send the specific next action, never "what is your status".
|
|
1383
|
+
See references/member-lifecycle.md.
|
|
1384
|
+
|
|
1385
|
+
**Do not ask permission to run the loop.** Dispatching a reviewer, spawning a
|
|
1386
|
+
merge bot, Pulling a ticket, re-verifying a SHA, filing a follow-up — all proceed
|
|
1387
|
+
unconfirmed. Invoking the command was the opt-in. One exception: **a judgement the
|
|
1388
|
+
evidence cannot settle**.
|
|
1389
|
+
|
|
1390
|
+
**Rule: record, tick, act, beat.** Every wake — a member report, a review
|
|
1391
|
+
notification, a label, a CI run reaching a terminal state, a heartbeat — ends in
|
|
1392
|
+
one `fleet-tick.mjs` invocation, and you do what it prints. There are no hand-run
|
|
1393
|
+
refill or dispatch edges left. Record first, because the tick reads the run off
|
|
1394
|
+
`.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
|
|
1395
|
+
one it cannot see, and it names the same dispatch again. Every record goes
|
|
1396
|
+
through `ledger.mjs` (**Run ledger**) — `settle` for a member's outcome, `row`
|
|
1397
|
+
for a token on a ticket's line — never a hand edit.
|
|
1398
|
+
|
|
1399
|
+
| Wake | Record, then tick |
|
|
1400
|
+
|---|---|
|
|
1401
|
+
| Implementer report | `verify-sha.sh`; `ledger.mjs settle impl-<N>=PR#<M>`, or `=bailed` and relabel by cause (**Implementer bails before implementing**, below) |
|
|
1402
|
+
| Review workflow notification / `review-pr-<n>` report | write `<scratch>/review-<pr>.json`; `reviewed=<head>:<survived>/<refuted>/<unverified>` on the PR's row (**Reviewers**) |
|
|
1403
|
+
| Fix-applier report | `ledger.mjs settle fix-pr-<M>=…`; copy the refutations it reversed to `ruled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
|
|
1404
|
+
| Finisher report | `ledger.mjs settle finisher-pr-<M>=labelled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
|
|
1405
|
+
| Finisher report (halted) | `ledger.mjs settle finisher-pr-<M>=halted:<cause>`; `gh pr comment <M>` with the finisher's halt report, cause and evidence; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line; then the per-cause rule (**Resolving a finisher halt**, below) |
|
|
1406
|
+
| Label seen (persistent Monitor) | nothing to record |
|
|
1407
|
+
| CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
|
|
1408
|
+
| Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `reap.sh --apply`. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — that token is the bot's, never `reap.sh`'s.) |
|
|
1409
|
+
| Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released` |
|
|
1410
|
+
| Heartbeat | nothing to record |
|
|
1411
|
+
|
|
1412
|
+
Then run the tick, act on every line it prints, and arm the beat. What a wake
|
|
1413
|
+
owes beyond its row:
|
|
1414
|
+
|
|
1415
|
+
- **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
|
|
1416
|
+
below. A turn that ends on a drained queue is #3's stall itself: nothing
|
|
1417
|
+
external will wake you, and the level-check you are one command away from
|
|
1418
|
+
never runs. Listed first because it is the only wake with no trigger —
|
|
1419
|
+
every other row above arrives; this one is the absence of one.
|
|
1420
|
+
- **Implementer report** → verify the SHA is reachable on the expected branch,
|
|
1421
|
+
settle the member, then run the tick. The PR is owed a review from here on:
|
|
1422
|
+
the tick names it as `DISPATCH review PR#<M>` once a reviewer slot is free,
|
|
1423
|
+
and it names the next shortlist head for the slot the implementer left. Pull
|
|
1424
|
+
nothing the tick did not name.
|
|
1425
|
+
- **Implementer bails before implementing** → settle `impl-<N>=bailed`, then
|
|
1426
|
+
demote by cause:
|
|
1427
|
+
|
|
1428
|
+
| Cause | Label |
|
|
1429
|
+
|---|---|
|
|
1430
|
+
| brief does not decide *what* to build | `needs-triage` |
|
|
1431
|
+
| genuine fork — options named, none ruled | `ready-for-human` |
|
|
1432
|
+
| needs human hands — external access, manual testing, judgment during the work | `ready-for-human` |
|
|
1433
|
+
|
|
1434
|
+
`gh issue edit <N> --remove-label ready-for-agent --remove-label in-progress
|
|
1435
|
+
--add-label <label>`, comment the cause, release the worktree and branch with
|
|
1436
|
+
`release-ticket.sh` (below — `reap.sh` declines a claim that never became a
|
|
1437
|
+
PR), then run the tick: the head it names next is a *different* ticket.
|
|
1438
|
+
`needs-triage` routes back to `/triage`, which can return it as
|
|
1439
|
+
`ready-for-agent`; `ready-for-human` for hands or a fork; `needs-triage` for a
|
|
1440
|
+
brief that names no *what*.
|
|
1441
|
+
|
|
1442
|
+
**Dropping `in-progress` is the load-bearing half** — phase 1 applied it and
|
|
1443
|
+
`candidates.mjs` excludes it, so leaving it makes the ticket invisible to your
|
|
1444
|
+
scans *and* the maintainer's. It does not loop; it disappears. The same causes
|
|
1445
|
+
relabel an unclaimed ticket at the Pull (phase 1), where there is no
|
|
1446
|
+
`in-progress` to drop — the causes and labels are one table, applied at
|
|
1447
|
+
whichever point the ticket fails them.
|
|
1448
|
+
- **A review result lands** → see the result file written (by you or by the
|
|
1449
|
+
runner — **Reviewers** says which, per harness) and record `reviewed=` off its
|
|
1450
|
+
digest, then run the tick: a PR with survivors prints as
|
|
1451
|
+
`DISPATCH fix-pr PR#<M>`. Nothing survived and nothing to file → skip the
|
|
1452
|
+
fix-applier and dispatch the **finisher** directly: no member will touch that
|
|
1453
|
+
PR, so no push is coming and nothing will wake you. A review that failed is
|
|
1454
|
+
not a result — **Reviewers** says who retries it and what takes over.
|
|
1455
|
+
- **Monitor: `ready-to-merge` appears** → nothing to record; run the tick, and
|
|
1456
|
+
on `DISPATCH merge-bot` dispatch the next `merge-bot-<n>` (**Merge bot**).
|
|
1457
|
+
Catches hand-added labels as well as a finisher's own. The bot does not wait
|
|
1458
|
+
for that finisher's report (ADR 0012 Decision 2): its rebase is server-side,
|
|
1459
|
+
`gh pr update-branch --rebase`, so nothing on the finisher's worktree has to
|
|
1460
|
+
happen first.
|
|
1461
|
+
- **Merge-bot pass reports done** → write each `held-behind-#<lower>` it reports
|
|
1462
|
+
into that ticket's row as `held-behind:#<lower>` — the verdict moves no label
|
|
1463
|
+
and leaves nothing in the repo, so the row is the only place the tick can read
|
|
1464
|
+
it from — settle `merge-bot-<n>=done`, reap merged branches and worktrees with
|
|
1465
|
+
`reap.sh --apply` (below) — always, even when the pass merged nothing — and
|
|
1466
|
+
then run the tick. A label that landed at the last moment reads `DISPATCH
|
|
1467
|
+
merge-bot` again: dispatch the next bot straight away. A `rebase-fallback-#<pr>`
|
|
1468
|
+
on a conflict needs no record from you — the bot already appended
|
|
1469
|
+
`conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
|
|
1470
|
+
fix-pr PR#<pr>` (**Reviewers**).
|
|
1471
|
+
- **The run ends, or the maintainer says drain** → `ledger.mjs drain
|
|
1472
|
+
"<reason>"` first, then release every claim that never became a PR (below)
|
|
1473
|
+
and settle each `impl-<N>=released`. Nothing else in the loop fires for those
|
|
1474
|
+
claims. The marker is on disk, so the tick holds the implementer row at
|
|
1475
|
+
`HOLD (draining)` from then on — for a replacement controller too — and keeps
|
|
1476
|
+
the review, fix-applier and merge rows firing until the open PRs merge.
|
|
1477
|
+
- **Monitor: CI run completes** → bind it (`ci-state.mjs --pr <N>`) and **record
|
|
1478
|
+
it as `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
|
|
1479
|
+
ticket's ledger row, which outlives your context. `row` **replaces the whole
|
|
1480
|
+
line** (above), so repeat `class=`, `ports=` and `→ PR#` or they are gone.
|
|
1481
|
+
That key cannot be reconstructed once the head is superseded, so a
|
|
1482
|
+
controller holding only the colour cannot later tell an edge it has already
|
|
1483
|
+
spent from one that never fired, and that is the distinction the sibling
|
|
1484
|
+
bullet below turns on. The whole key, never the conclusion alone: **a
|
|
1485
|
+
conclusion is not stable** (below), because a rerun rewrites the run in
|
|
1486
|
+
place. The diff-validating `check` job green with no heavy job (the
|
|
1487
|
+
diff-validating suites, not the `rebase-check` currency gate) in `failure`
|
|
1488
|
+
→ a finisher CANDIDATE (gated below), a `check`
|
|
1489
|
+
**failure** → a fixer. A `check`-green board whose heavy jobs are merely
|
|
1490
|
+
`skipped` (behind-count staleness, the normal case after a merge) still labels — do NOT
|
|
1491
|
+
gate on `ci-state --quiet` exit 0, which a behind PR never reaches. **This
|
|
1492
|
+
edge fires for every CI run the PR produces, and the implementer's own
|
|
1493
|
+
firing comes first for every PR** — `ci.yml` triggers on `pull_request`, so
|
|
1494
|
+
opening the PR at the end of `next-ticket` step 7 starts a run within seconds,
|
|
1495
|
+
while the review returns 20-40 minutes later. That first firing is
|
|
1496
|
+
the ordinary case for every PR, not a rarity, and no review has run at all
|
|
1497
|
+
when it arrives. **Green is therefore not the gate: dispatch a finisher only
|
|
1498
|
+
once the PR's review has returned AND its fix-applier, if one was dispatched,
|
|
1499
|
+
has sent its report — pushed is not reported**, and a push before that report
|
|
1500
|
+
is mid-work on a SHA the member may still move, which its own prompt tells it
|
|
1501
|
+
not to hand over. A push is therefore not an exit, and a report that has not
|
|
1502
|
+
arrived is asked for by name rather than read as one. Neither shape is caught
|
|
1503
|
+
by an empty outbox: on the implementer's firing there is no fix-applier to owe
|
|
1504
|
+
anything to, so the outbox is *vacuously* empty, and on a fix-applier's
|
|
1505
|
+
mid-work push nothing has been sent since the dispatch, so it is *genuinely*
|
|
1506
|
+
empty. **The outbox is the last test, not the only one, and it stands wherever
|
|
1507
|
+
a fix-applier exists** — that is exactly where a ruling you still owe it is
|
|
1508
|
+
outstanding, so never dispatch off it while you do. Empty your outbox to it
|
|
1509
|
+
first — including any ruling you have withdrawn or reversed — then dispatch
|
|
1510
|
+
(below); a final report is not proof it stopped. A PR that needs nothing fixed
|
|
1511
|
+
reaches a finisher through the **fix-applier reports `no-op`** bullet below,
|
|
1512
|
+
never by waiting for a second CI event this head will never produce.
|
|
1513
|
+
Then run the tick.
|
|
1514
|
+
- **A fix-applier reports `no-op`, or a SHA you have already bound** → dispatch
|
|
1515
|
+
the finisher **now**, against the existing head. No push means no new run, and
|
|
1516
|
+
the Monitor above is edge-keyed on `<run-id>:<attempt>:<conclusion>` — that
|
|
1517
|
+
head's terminal state already fired once and will never fire again, so waiting
|
|
1518
|
+
for the CI event waits forever. This stays a common outcome on a clean PR:
|
|
1519
|
+
`suggestion` is the band a clean diff produces, and every out-of-scope or
|
|
1520
|
+
refuted one is filed as an issue rather than committed. An edge-only label path
|
|
1521
|
+
therefore strands exactly the PRs with nothing wrong with them. **Reconcile, do
|
|
1522
|
+
not wait for an event** governs here too, not only the implementer row. **This
|
|
1523
|
+
bullet and the one above are a pair, and on a clean PR this one carries the
|
|
1524
|
+
whole route to a finisher**: a `no-op` report satisfies the gate above by
|
|
1525
|
+
itself — the review has returned, because a fix-applier exists only after it
|
|
1526
|
+
did, and the member has reported — so nothing further is owed and no further
|
|
1527
|
+
event is coming. Edit either bullet without the other and what strands is
|
|
1528
|
+
exactly the PR that needed no fixes.
|
|
1529
|
+
- **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → no workflow run will ever
|
|
1530
|
+
complete for this repo, so the CI-run-completion edge above never fires and
|
|
1531
|
+
waiting for it stalls the whole PR — the same silent-stall shape #111 reported
|
|
1532
|
+
before this verdict existed. Dispatch the finisher off the reviewer's final
|
|
1533
|
+
verdict instead, the moment it lands — and, same as above, never while you still
|
|
1534
|
+
owe it a ruling — or hold anything else it has not received, a ruling you have
|
|
1535
|
+
withdrawn or reversed included. The finisher's gate is then the
|
|
1536
|
+
`--declare-no-ci` declaration, not a `check` job: with it, label off the
|
|
1537
|
+
reviewer's verified suite run; **without it, do not label** — report that this
|
|
1538
|
+
repo has no CI configured and no declaration, and stop. Absence never reads as
|
|
1539
|
+
pass. See `review-and-fix.md` step 6.
|
|
1540
|
+
|
|
1541
|
+
**Every wake ends in the tick.** One invocation, and you act on what it prints:
|
|
1542
|
+
|
|
1543
|
+
```
|
|
1544
|
+
~/.fleet/bin/fleet-run fleet-tick.mjs [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
|
|
1545
|
+
```
|
|
1546
|
+
|
|
1547
|
+
It reads the run itself, and nobody states a count. Live implementers, live
|
|
1548
|
+
review units (in-flight `review=` tokens plus unsettled `fix-pr-` ones), the
|
|
1549
|
+
merge bot, merge holds, tier mismatches and the drain marker come off
|
|
1550
|
+
`.fleet/ledger.md`; the unclaimed heads and the supply come off
|
|
1551
|
+
`.fleet/shortlist.json`, which it refreshes itself when the unclaimed count is
|
|
1552
|
+
below the implementer cap, when the file is missing or empty, or when an
|
|
1553
|
+
Exclusion's premise has lifted; the open PRs come off `gh`. A ledger token it
|
|
1554
|
+
cannot read, it refuses rather than guessing — a member counted live or gone on
|
|
1555
|
+
a guess is the over- or under-dispatch it exists to prevent — so correct that
|
|
1556
|
+
row with `ledger.mjs row` and tick again. The caps default to 2 implementers
|
|
1557
|
+
and 6 reviewers, and neither is a hard bound: pass `--implementer-cap` and
|
|
1558
|
+
`--reviewer-cap` on every tick when `$ARGUMENTS` set them, and never otherwise.
|
|
1559
|
+
|
|
1560
|
+
It prints `actual/target` and a named ACTION per role, with the whole **Queue
|
|
1561
|
+
depth** guard table applied in code. Act on each line as it reads:
|
|
1562
|
+
|
|
1563
|
+
- `PULL #<N> …` — one Pull per named ticket, in the order printed: phase 1's
|
|
1564
|
+
read, then phase 2's dispatch. A ticket that fails the read is relabelled or
|
|
1565
|
+
excluded (phase 1), and the next tick names the next head.
|
|
1566
|
+
- `REFRESHED shortlist: <n> entries; <k> lifted` — the tick refreshed the
|
|
1567
|
+
shortlist itself, and its `PULL` row already reads the result. `REFRESH
|
|
1568
|
+
FAILED` is yours: `shortlist.mjs` could not run, and the implementer row is
|
|
1569
|
+
blind until it can.
|
|
1570
|
+
- `SUGGEST /triage, hold idle` — nothing is admissible after the refresh.
|
|
1571
|
+
Suggest, never run (**Queue depth**).
|
|
1572
|
+
- `DISPATCH fix-pr PR#<M> …` — a fix-applier per PR, for a review's survivors
|
|
1573
|
+
or a merge bot's `conflict-hold:#<M>` (**Reviewers**). Printed
|
|
1574
|
+
ahead of reviews on purpose: finishing what is started beats starting more.
|
|
1575
|
+
- `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn
|
|
1576
|
+
(**Reviewers**).
|
|
1577
|
+
- `DISPATCH merge-bot` — the next `merge-bot-<n>` (**Merge bot**).
|
|
1578
|
+
- `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
|
|
1579
|
+
unchecked tier, a saturated review side, `--max-reviews` in flight, or every
|
|
1580
|
+
queued merge candidate held behind a lower PR or on a conflict hold no
|
|
1581
|
+
fix-applier has cleared. The two tier holds are yours to clear — an
|
|
1582
|
+
unchecked tier by running `tier-check.mjs --batch` on the member it names,
|
|
1583
|
+
a mismatch by dispatching the replacement at the right tier (phase 2). Each
|
|
1584
|
+
prints its clearing step in the row's detail: the `tier-check.mjs` command
|
|
1585
|
+
with a batch entry per member it names (fill in `<file>` and `<session>`),
|
|
1586
|
+
or the replacement's name — `impl-<N>-b` on a first retry, else one letter
|
|
1587
|
+
past the highest the ticket has used, or that no retry letter is left.
|
|
1588
|
+
- `AT CAP`, `IDLE OK` — nothing to do on that row.
|
|
1589
|
+
|
|
1590
|
+
**Tier guards under Pull.** An alt Pull — the Pull phase 2 routes to the
|
|
1591
|
+
alternate tier — is where the tier floor is read. Run phase 2's tier guard
|
|
1592
|
+
before choosing the alternate tier, on the floor phase 2 defines over the
|
|
1593
|
+
accumulated `docs/metrics/tier-outcomes.tsv` and on no gate of this Pull's own:
|
|
1594
|
+
a second threshold stated here is a second definition, free to drift from
|
|
1595
|
+
the one that governs, and a throttle would need state nothing on disk records
|
|
1596
|
+
— a schema change with its own ticket. A floor breach — the guard firing —
|
|
1597
|
+
dispatches that Pull at the default tier instead, with no `tier=alt` in its
|
|
1598
|
+
row; say why in your report. The per-dispatch `tier-check.mjs --batch` stays
|
|
1599
|
+
phase 2's own step: a mismatch it finds is the
|
|
1600
|
+
`HOLD (tier mismatch impl-<N>)` above, and a member it has no verdict on is
|
|
1601
|
+
the `HOLD (tier unchecked impl-<N>)`. Nothing else in the loop owns it.
|
|
1602
|
+
|
|
1603
|
+
**`--max-reviews <n>`** bounds how many reviews are in flight at once, inside
|
|
1604
|
+
the reviewer cap. It defaults to the reviewer cap, and the reviewer slots it
|
|
1605
|
+
leaves still serve fix-appliers. Leave it at its default: every review unit
|
|
1606
|
+
already counts against the session's single `task.maxConcurrency` semaphore,
|
|
1607
|
+
which queues at its ceiling rather than refusing (#1771), so reviews run up
|
|
1608
|
+
to the reviewer cap without a tighter explicit bound.
|
|
1609
|
+
|
|
1610
|
+
**Why every wake.** A merge cascade is a firehose of merges, CI greens and
|
|
1611
|
+
rebases that holds your attention on the merge side while the implementer side
|
|
1612
|
+
drains to 0 and stays there — 0 implementers emit no completion event, so a
|
|
1613
|
+
refill that waited for one would never fire. A tick on every wake you are
|
|
1614
|
+
already handling is what makes that drain visible. **Every wake is still an
|
|
1615
|
+
edge, so none covers a fully drained queue**: no members and no open PRs is no
|
|
1616
|
+
event at all, and the tick goes unrun. That state is the heartbeat's (#357).
|
|
1617
|
+
|
|
1618
|
+
**Beat when there is nothing to do, and never end your turn on a drained
|
|
1619
|
+
queue.** You cannot be woken. A backgrounded Monitor does not wake an idle
|
|
1620
|
+
agent — measured twice, see **A member runs its test suite in the foreground**
|
|
1621
|
+
above, where `fix-pr-1184` backgrounded a suite plus a Monitor and sat idle for
|
|
1622
|
+
roughly two hours — and `run-merge-bot.md`'s CI gate states the general rule:
|
|
1623
|
+
"whatever wakes you is external and may never come". So hold the wait yourself,
|
|
1624
|
+
exactly the way that gate does:
|
|
1625
|
+
|
|
1626
|
+
```bash
|
|
1627
|
+
~/.fleet/bin/fleet-run fleet-heartbeat.mjs \
|
|
1628
|
+
[--base 300] [--ceiling 1200] [--multiplier 2] [--hold 240]
|
|
1629
|
+
```
|
|
1630
|
+
|
|
1631
|
+
It blocks, then prints one line. Which line it is, is the whole protocol:
|
|
1632
|
+
|
|
1633
|
+
- `… interval elapsed (quiet=<n>) → run fleet-tick` — the level-check is due.
|
|
1634
|
+
Run the tick above **with `--fold-unchanged`** and act on what it prints.
|
|
1635
|
+
Then arm the beat again.
|
|
1636
|
+
- `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
|
|
1637
|
+
command blocks for a whole interval (omp backgrounds one at
|
|
1638
|
+
60s, which is why the
|
|
1639
|
+
CI gate tells you to re-issue `gh run watch`). Issue it again. That is still
|
|
1640
|
+
one blocking call per turn, never an idle turn.
|
|
1641
|
+
|
|
1642
|
+
The interval doubles while the fleet asks for nothing and stops at `--ceiling`,
|
|
1643
|
+
so a quiet night costs ~26 wakes instead of ~96. **The ceiling is a real bound,
|
|
1644
|
+
not a formality**: supply grows from OUTSIDE the fleet — a ticket you triage, a
|
|
1645
|
+
correction ticket a reviewer files — and that arrival emits no event either, so
|
|
1646
|
+
the ceiling is your worst-case latency for noticing it. Do not raise it past 30
|
|
1647
|
+
minutes.
|
|
1648
|
+
|
|
1649
|
+
**The beat does not stop on idleness.** An empty shortlist and an empty supply are
|
|
1650
|
+
not a reason to end the run; they are the state a newly triaged ticket arrives
|
|
1651
|
+
into. The run ends when you drain it, when the budget goes, or when this
|
|
1652
|
+
context does — not because there was briefly nothing to do.
|
|
1653
|
+
|
|
1654
|
+
**`--fold-unchanged` belongs to the heartbeat alone**, never to any other wake.
|
|
1655
|
+
It prints one line instead of the rows when a tick asks for nothing AND says
|
|
1656
|
+
exactly what the last one said, which is what makes an unattended night
|
|
1657
|
+
affordable; a tick on any other wake is read by a controller that just acted and
|
|
1658
|
+
needs the rows. An unchanged `PULL` or `DISPATCH` is never folded — unclaimed work
|
|
1659
|
+
always prints in full, because folding it would hide the stall behind this
|
|
1660
|
+
ticket's own remedy.
|
|
1661
|
+
|
|
1662
|
+
**When you stop on purpose, say why — one command, and it is the last thing
|
|
1663
|
+
you owe the next run.** The beat leaves a dated mark on every hold, so a run
|
|
1664
|
+
that dies abruptly (a crashed harness, a closed terminal, an OOM kill) is
|
|
1665
|
+
detected by its mark going stale. A run that stops KNOWINGLY can do better
|
|
1666
|
+
than being detected, and nothing else can write the reason afterwards:
|
|
1667
|
+
|
|
1668
|
+
```bash
|
|
1669
|
+
~/.fleet/bin/fleet-run fleet-heartbeat.mjs --stop "budget exhausted"
|
|
1670
|
+
```
|
|
1671
|
+
|
|
1672
|
+
It holds nothing and returns at once. Use it when the budget goes, when you
|
|
1673
|
+
can see the context ceiling coming, or when you drain the run deliberately.
|
|
1674
|
+
Skipping it is not fatal — the next reader still reports the stop, it just
|
|
1675
|
+
reports that the beat stopped *without a recorded reason*, which is all it can
|
|
1676
|
+
honestly say about a death that named nothing.
|
|
1677
|
+
|
|
1678
|
+
**A `heartbeat STALLED` line is the PREVIOUS run, never this one.** `fleet-tick`
|
|
1679
|
+
prints it before its own rows when the mark it finds is overdue against the
|
|
1680
|
+
interval that mark recorded, and the cockpit shows the same line while it is
|
|
1681
|
+
up. It names when the beat was last seen, how overdue that is, how many
|
|
1682
|
+
tickets are still claimed and in flight, and how much supply the last read found
|
|
1683
|
+
— because the claimed ones keep the `in-progress` label, the candidate scan
|
|
1684
|
+
EXCLUDES that label, and those tickets are therefore invisible to your own
|
|
1685
|
+
shortlist and to the maintainer's. Read the line, decide what to do about the
|
|
1686
|
+
stranded tickets, and carry on; nothing in the fleet releases, relabels or
|
|
1687
|
+
reaps them for you, and nothing restarts the run that stranded them.
|
|
1688
|
+
|
|
1689
|
+
**Own the CI waits.** Members are turn-based and cannot hold across a ten-minute
|
|
1690
|
+
run — they rebase, push, stop. Arm a second persistent Monitor over open PRs'
|
|
1691
|
+
latest runs, keyed `<run-id>:<attempt>:<conclusion>` so each terminal state fires once, and
|
|
1692
|
+
emit the behind-count and the per-job conclusions with it: a `success` on a branch
|
|
1693
|
+
8 behind is not actionable, and `check`-green-with-heavy-skipped is the staleness
|
|
1694
|
+
board you must not confuse with a red. Do not reinvent that read: one
|
|
1695
|
+
`~/.fleet/bin/fleet-run ci-state.mjs --pr <N>` per open PR already emits
|
|
1696
|
+
run id, attempt, conclusion, behind-count and per-job conclusions, branch derived
|
|
1697
|
+
from the PR — including the `gh api --hostname <host>` a GHE compare call needs,
|
|
1698
|
+
without which the probe 404s and `behind` comes back `null`, never 0, so every
|
|
1699
|
+
event reads as unknown-behind. Call it **without `--quiet`** — that flag drops
|
|
1700
|
+
`jobs` and `missing`.
|
|
1701
|
+
|
|
1702
|
+
A monitor event is a wake-up, never a verdict; members re-query at labelling
|
|
1703
|
+
time. See references/ci-and-staleness.md.
|
|
1704
|
+
|
|
1705
|
+
**A conclusion is not stable, even for a fixed run id on an unchanged head.** A
|
|
1706
|
+
rerun rewrites the run in place, so never cache a conclusion; key watchers on
|
|
1707
|
+
`<run-id>:<attempt>:<conclusion>`. Leaving `attempt` out of the key is the bug
|
|
1708
|
+
that looks like it works: a rerun that lands on the *same* conclusion regenerates
|
|
1709
|
+
an already-seen key and fires nothing, so the second failure is silent and reads
|
|
1710
|
+
exactly like a run still in progress. **Building that key with jq's `//` is the
|
|
1711
|
+
same bug in the opposite direction**: `ci-state` reports an in-progress run as
|
|
1712
|
+
`conclusion: ""`, and `//` catches `null` and `false` but never the empty
|
|
1713
|
+
string, so `.conclusion // "-"` passes `""` straight through, keys a RUNNING job
|
|
1714
|
+
as terminal and fires a spurious not-green — measured in four separate runs,
|
|
1715
|
+
including one where the controller then had to re-arm blind. Test any fallback
|
|
1716
|
+
you write against `""`, `null` AND a real conclusion, and check it still lets
|
|
1717
|
+
the real one through: `map(if . == null or . == "" then "-" else tostring end)`.
|
|
1718
|
+
Also: the newest
|
|
1719
|
+
run on a branch is frequently *not* CI, so `--limit 1` can hide the CI result
|
|
1720
|
+
entirely. See references/ci-and-staleness.md.
|
|
1721
|
+
|
|
1722
|
+
**A probe that cannot read is a transition event, not silence.** The natural
|
|
1723
|
+
watcher shape — `st=$(ci-state.mjs --pr "$pr" 2>/dev/null) || continue` — fails
|
|
1724
|
+
closed correctly and then throws the failure away, so a rate-limited probe emits
|
|
1725
|
+
NOTHING and "no event" becomes indistinguishable from "not green yet". Every
|
|
1726
|
+
open PR stalls unlabelled while the run reads as merely quiet; observed live
|
|
1727
|
+
twice. So check the REST budget *before* polling — `gh api rate_limit` is itself
|
|
1728
|
+
unmetered (`gh api rate_limit --jq '.resources.core.remaining'`, re-confirmed
|
|
1729
|
+
2026-09-08) — and give an unreadable `ci-state` payload the same treatment one
|
|
1730
|
+
level down. The shape is **one outer tick loop with an inner pass over the open
|
|
1731
|
+
PRs**, because the two causes live at different levels — the budget is one
|
|
1732
|
+
account, the payload is one PR:
|
|
1733
|
+
|
|
1734
|
+
```sh
|
|
1735
|
+
budget_out= list_out= cap_out= blind= # seed the latches: set -u reads each below before tick 1 ever assigns one
|
|
1736
|
+
pr_cap=200 # the open-PR read's --limit; gh stops there with exit 0 and no warning
|
|
1737
|
+
while :; do # one tick
|
|
1738
|
+
rl=$(gh api rate_limit --jq '.resources.core.remaining' 2>/dev/null || echo ERR)
|
|
1739
|
+
case "$rl" in ''|*[!0-9]*) rl=ERR;; esac # a non-numeric read is an outage, not a budget
|
|
1740
|
+
if [ "$rl" = ERR ] || [ "$rl" -lt 200 ]; then
|
|
1741
|
+
if [ -z "$budget_out" ]; then # ONE global latch: a quota outage hits every PR
|
|
1742
|
+
echo "WATCHER DEGRADED: core REST budget=$rl — CI polling paused, silence is NOT green"
|
|
1743
|
+
budget_out=1
|
|
1744
|
+
fi
|
|
1745
|
+
else
|
|
1746
|
+
if [ -n "$budget_out" ]; then
|
|
1747
|
+
echo "WATCHER RECOVERED: core budget=$rl — CI polling resumed"
|
|
1748
|
+
budget_out=
|
|
1749
|
+
fi
|
|
1750
|
+
prs=$(gh pr list --state open --limit "$pr_cap" --json number --jq '.[].number' 2>/dev/null) || prs=ERR
|
|
1751
|
+
if [ "$prs" = ERR ]; then
|
|
1752
|
+
if [ -z "$list_out" ]; then # global latch: this cause is account-level too
|
|
1753
|
+
echo "WATCHER DEGRADED: cannot list open PRs — CI polling paused, silence is NOT green"
|
|
1754
|
+
list_out=1
|
|
1755
|
+
fi
|
|
1756
|
+
else
|
|
1757
|
+
if [ -n "$list_out" ]; then
|
|
1758
|
+
echo "WATCHER RECOVERED: open-PR list readable again — CI polling resumed"
|
|
1759
|
+
list_out=
|
|
1760
|
+
fi
|
|
1761
|
+
if [ "$(printf '%s\n' "$prs" | grep -c .)" -ge "$pr_cap" ]; then
|
|
1762
|
+
if [ -z "$cap_out" ]; then # global latch: a full page may have been cut there
|
|
1763
|
+
echo "WATCHER DEGRADED: open-PR list hit its --limit $pr_cap — PRs past it are NOT watched, silence on them is NOT green"
|
|
1764
|
+
cap_out=1
|
|
1765
|
+
fi
|
|
1766
|
+
elif [ -n "$cap_out" ]; then
|
|
1767
|
+
echo "WATCHER RECOVERED: open-PR list under its --limit $pr_cap — every open PR watched again"
|
|
1768
|
+
cap_out=
|
|
1769
|
+
fi
|
|
1770
|
+
for pr in $(printf '%s\n' "$prs"); do # inline $(...): `for pr in $prs` is ONE iteration under zsh
|
|
1771
|
+
st=$(~/.fleet/bin/fleet-run ci-state.mjs --pr "$pr" 2>/dev/null) || : # not-green exits non-zero; the payload is the verdict
|
|
1772
|
+
if ! printf '%s' "$st" | jq -e '.verdict and .verdict != "rate-limited"' >/dev/null 2>&1; then
|
|
1773
|
+
case " $blind " in *" $pr "*) ;; *) # latch keyed BY PR: this cause is per-PR
|
|
1774
|
+
echo "WATCHER DEGRADED: no usable ci-state reading for #$pr — silence is NOT green"
|
|
1775
|
+
blind="$blind $pr" ;;
|
|
1776
|
+
esac
|
|
1777
|
+
continue # inner continue — still reaches the tick sleep
|
|
1778
|
+
fi
|
|
1779
|
+
case " $blind " in *" $pr "*)
|
|
1780
|
+
echo "WATCHER RECOVERED: ci-state reading #$pr again — CI polling resumed"
|
|
1781
|
+
keep=; for b in $(printf '%s\n' "$blind"); do [ "$b" = "$pr" ] || keep="$keep $b"; done; blind=$keep ;;
|
|
1782
|
+
esac
|
|
1783
|
+
: # your normal handling of $st for this PR
|
|
1784
|
+
done
|
|
1785
|
+
fi
|
|
1786
|
+
fi
|
|
1787
|
+
sleep 120 # the block's only pacing, once per tick
|
|
1788
|
+
done
|
|
1789
|
+
```
|
|
1790
|
+
|
|
1791
|
+
**One gate, not a gate plus a caveat.** `jq -e '.verdict and .verdict !=
|
|
1792
|
+
"rate-limited"'` exits non-zero on unparseable input *and* on a false result, so
|
|
1793
|
+
that single test covers empty, garbage AND a self-named quota refusal. Empty
|
|
1794
|
+
stdin produces no result at all, which `-e` reports as exit 4 (measured), so a
|
|
1795
|
+
`[ -z "$st" ] ||` pre-check in front of it is a *second* gate testing what this
|
|
1796
|
+
one already tests — the caveat this heading is about. Leaving
|
|
1797
|
+
the named verdict to prose instead is how a watcher clears its latch on an
|
|
1798
|
+
outage payload and hands it downstream as CI state — the very blindness this
|
|
1799
|
+
section exists to remove, one level in. **The `.verdict and` half is load-bearing
|
|
1800
|
+
and not belt-and-braces**: inequality alone never tests that a verdict *exists*,
|
|
1801
|
+
so `{}`, `null` and `{"verdict":null}` all evaluate `null != "rate-limited"` →
|
|
1802
|
+
true and clear the gate (measured), handing an empty or error object downstream
|
|
1803
|
+
as a CI reading. Require the field, then compare it.
|
|
1804
|
+
|
|
1805
|
+
**It has to latch** — one line entering the degraded state, one leaving it,
|
|
1806
|
+
never one per tick. An unlatched line at a 120s poll gets the Monitor
|
|
1807
|
+
auto-stopped for volume during even a two-minute outage, reintroducing the same
|
|
1808
|
+
blindness by another route. **Latch each cause at the level its cause lives
|
|
1809
|
+
at**: the budget, the open-PR list and that list's cap are one global flag
|
|
1810
|
+
each — all three are account-level — but the payload latch is keyed by PR, and a
|
|
1811
|
+
shared scalar for those is an unlatched line wearing a latch's clothes — one
|
|
1812
|
+
persistently blind PR alongside one healthy PR re-clears the flag on every tick,
|
|
1813
|
+
emitting a DEGRADED and a false RECOVERED pair forever. The recovery line is
|
|
1814
|
+
what says the watch is alive again, so emit it on the first good pass even when
|
|
1815
|
+
nothing about the CI state changed; without it a reader cannot tell a recovered
|
|
1816
|
+
watcher from a dead one.
|
|
1817
|
+
|
|
1818
|
+
**All pacing in exactly one place — the tick loop's own tail `sleep`.** A sleep
|
|
1819
|
+
inside the per-PR pass multiplies by the number of open PRs (8 open PRs → 960s
|
|
1820
|
+
of pause per tick, against the 24s outage reset measured below), and a degraded
|
|
1821
|
+
branch that `continue`s the *outer* loop skips the tail sleep and busy-spins
|
|
1822
|
+
probe pairs during exactly the outage it is reporting. Every degraded
|
|
1823
|
+
branch above falls through to the same single sleep instead.
|
|
1824
|
+
|
|
1825
|
+
**Guard every probe, not just the ones with a verdict field.** The block makes
|
|
1826
|
+
*three* API calls, and the third — `gh pr list` — is the one that looks like
|
|
1827
|
+
plumbing rather than a probe. A non-quota failure there (secondary/abuse limit,
|
|
1828
|
+
5xx, network blip, expired token) does not lower `.resources.core.remaining`, so
|
|
1829
|
+
the budget gate clears, and an unguarded `for pr in $(gh pr list …)` then
|
|
1830
|
+
iterates zero times over the empty substitution: no error, no latch, no DEGRADED
|
|
1831
|
+
line — total silence per tick, which is exactly what this section exists to
|
|
1832
|
+
remove. Capture its status (`prs=$(…) || prs=ERR`), latch it globally, and fall
|
|
1833
|
+
through to the same tail sleep. **Then iterate with the inline `$(printf '%s\n'
|
|
1834
|
+
"$prs")` form, never a bare `for pr in $prs`** — the assigned-variable trap in
|
|
1835
|
+
**Shell traps** above, which carries the mechanism and the measurements. It
|
|
1836
|
+
applies to **every** loop in this block, the `blind`-latch removal included:
|
|
1837
|
+
under a bare `for b in $blind` a recovered PR never leaves the list and the block
|
|
1838
|
+
emits a fresh RECOVERED every tick thereafter — the per-tick volume the latch
|
|
1839
|
+
exists to prevent, wearing a latch's clothes again.
|
|
1840
|
+
|
|
1841
|
+
**A readable list can still be a short one.** `gh pr list` stops at its
|
|
1842
|
+
`--limit` — 30 when the flag is absent — with exit 0 and no warning, so a list
|
|
1843
|
+
that fills its limit reads exactly like one that happens to be that long, and
|
|
1844
|
+
every open PR past it goes unwatched without a line. Pass an explicit `--limit`
|
|
1845
|
+
(`pr_cap`: one variable for the flag and the check, so the two cannot drift)
|
|
1846
|
+
and treat a full page as its own degraded cause — the "no silent caps" rule
|
|
1847
|
+
`candidates.mjs`'s `refuseIfCapped()` and `fleet-tick.mjs`'s `PR_LIMIT` already
|
|
1848
|
+
enforce. It latches globally like the list failure but does not pause polling:
|
|
1849
|
+
the PRs it did return are real, so the pass still watches them, and the
|
|
1850
|
+
DEGRADED line names the rest as unwatched until a pass comes back under the cap.
|
|
1851
|
+
|
|
1852
|
+
**Judge `ci-state` on its payload, never its exit code** — the same rule as
|
|
1853
|
+
`merge-gate.mjs` applies on the merge path, applied to the watcher. `not-green` is an
|
|
1854
|
+
ordinary, frequent state that exits non-zero, so a watcher treating any non-zero
|
|
1855
|
+
exit as an outage misfires constantly on PRs that are merely in progress. Empty
|
|
1856
|
+
or unparseable output is the degraded case; parseable JSON reading
|
|
1857
|
+
`verdict: "not-green"` is normal. An exhausted quota may also name itself,
|
|
1858
|
+
`verdict: "rate-limited"` on stdout — likewise degraded, and likewise not a
|
|
1859
|
+
reading, which is why the gate above tests the verdict rather than mere
|
|
1860
|
+
parseability: that payload is perfectly good JSON.
|
|
1861
|
+
|
|
1862
|
+
**Do not back off and wait.** These outages are short — a rolling window; one
|
|
1863
|
+
measured reset came 24 seconds after `remaining: 0` — and pausing members for a
|
|
1864
|
+
fixed interval stalls the fleet longer than the outage itself would have. A
|
|
1865
|
+
retry-and-wait loop is what turns a 60s outage into a stalled member. Report it,
|
|
1866
|
+
keep the local work moving (git, tests and mutation runs are all unaffected),
|
|
1867
|
+
re-probe.
|
|
1868
|
+
|
|
1869
|
+
**While the budget is exhausted, `ledger.mjs check` reads
|
|
1870
|
+
`verdict: "unverified"`** — the ledger was read and the tracker was not. That is
|
|
1871
|
+
correct behaviour, but `unverified` exits **0**, the same as `clean`, so a
|
|
1872
|
+
member treating exit 0 as "safe to file" files blind during exactly this window.
|
|
1873
|
+
Say so when you flag the outage: members read `verdict` explicitly until you
|
|
1874
|
+
report recovery, never the exit code alone.
|
|
1875
|
+
|
|
1876
|
+
### Reviewers
|
|
1877
|
+
|
|
1878
|
+
**Dispatch the review, never wait on it, and act when its result lands. That is the default path.**
|
|
1879
|
+
The tick names every PR owed one — `DISPATCH review PR#<M>`, oldest first —
|
|
1880
|
+
and each gets one review, once per PR:
|
|
1881
|
+
|
|
1882
|
+
a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the same five args — it loads `review-eval.mjs` through the Resolver (`~/.fleet/bin/fleet-run --path review-eval.mjs`), awaits `runReviewOnOmp` in its own kernel, writes the result file and reports; record `review=member:review-pr-<pr#>` on the PR's row before the dispatch call.
|
|
1883
|
+
|
|
1884
|
+
Write the `review=` token with `ledger.mjs row`, which **replaces the whole
|
|
1885
|
+
line**, so carry every other field. The tick counts in-flight reviews off the
|
|
1886
|
+
ledger and nowhere else, so a review you launched and never recorded is one it
|
|
1887
|
+
names again.
|
|
1888
|
+
|
|
1889
|
+
**It is the only path on which `selectDimensions` sizes the fan-out to the
|
|
1890
|
+
diff and the verify budget follows severity.** Hand-dispatched (the fallback
|
|
1891
|
+
below), neither executes at all: sizing falls back to a reviewer's own
|
|
1892
|
+
judgement and nothing budgets the adversarial pass. It cuts one immutable
|
|
1893
|
+
snapshot, verifies every critical/important finding adversarially,
|
|
1894
|
+
re-dispatches each crashed specialist and each crashed refuter pair once before
|
|
1895
|
+
it assembles the result, and has `agent()` return **into the script**, so no
|
|
1896
|
+
report can go undelivered and you relay nothing — the delivery failure that
|
|
1897
|
+
cost one fleet five reports on one PR and four on another. None of it runs on
|
|
1898
|
+
your turn: a review takes 20-40 minutes, and a controller that held its turn
|
|
1899
|
+
for each one, one at a time, was what left implementer slots empty (map #1768).
|
|
1900
|
+
|
|
1901
|
+
**Know the trim before you rely on it — it is wider than `docsOnly` suggests.**
|
|
1902
|
+
`diff-stats.mjs` calls a PR docs-only only when it touches **no** src, tests *or*
|
|
1903
|
+
config, but that strictness cuts both ways and the size tier trims again on top.
|
|
1904
|
+
Measured: a docs PR that also adds one test file is profile `tests-only` and runs
|
|
1905
|
+
**three** (correctness+tests+comments), not six; a no-src, no-test diff that
|
|
1906
|
+
carries a config file keeps silent-failure at **any** size, so a docs+config diff
|
|
1907
|
+
too big for the size tier now runs correctness+silent-failure+comments, not
|
|
1908
|
+
correctness+comments; and any `single-file` or `small` profile trims to
|
|
1909
|
+
correctness+silent-failure+comments, keeping tests only when a test file is in
|
|
1910
|
+
the diff. `comments` is on that floor
|
|
1911
|
+
unconditionally since #218 — it used to need a docs FILE, and `classify()` scores
|
|
1912
|
+
any code extension `src` before it checks docs, so five production PRs whose whole
|
|
1913
|
+
substance was prose inside a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and ran
|
|
1914
|
+
without the one specialist that fit them, `dimensionsUnrun` empty every time.
|
|
1915
|
+
That floor holds **regardless of `hasSrc`** (#236) — a one-file `.yml` or
|
|
1916
|
+
`.github/` shell change gets silent-failure too, not correctness alone.
|
|
1917
|
+
It is the size **tier's** floor,
|
|
1918
|
+
so `tests-only` outranks it when the diff has no config file: that profile is
|
|
1919
|
+
assigned ahead of `single-file`/`small`, so a no-src, no-config diff that also
|
|
1920
|
+
touches a test file gets no silent-failure-hunter — a tests-only diff that also
|
|
1921
|
+
carries a config file keeps it (#739). `single-file` means one file at **any** size, so a
|
|
1922
|
+
one-file rewrite trims too. An unknown profile widens to the full six, the safe
|
|
1923
|
+
direction, so a trim is never something to count on in advance — and a full six
|
|
1924
|
+
is never something to assume.
|
|
1925
|
+
|
|
1926
|
+
**The reviewer cap counts live review units.** A review in flight — a
|
|
1927
|
+
`review-pr-<pr#>` member still running — is one; each
|
|
1928
|
+
`fix-pr-<pr#>` is one; a finisher and a CI wait are zero; and a PR holds at most
|
|
1929
|
+
one slot at a time. In-flight reviews are derived, never remembered: a row with
|
|
1930
|
+
`review=` and no `reviewed=` is one, which is why the token goes on before
|
|
1931
|
+
anything else. The defaults are 2 implementers and 6 reviewers, and neither is
|
|
1932
|
+
a hard cap. The cap bounds units, not the agents a review fans out to — 1
|
|
1933
|
+
snapshot + up to 6 specialists + 2 refuters per critical/important finding — and
|
|
1934
|
+
how many reviews may be in flight at once, inside it, is `--max-reviews`. The
|
|
1935
|
+
slots a review does not hold still serve fix-appliers.
|
|
1936
|
+
|
|
1937
|
+
It returns `{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts, snapshot, survived, refuted, unverified}` —
|
|
1938
|
+
the **digest** first, then the snapshot and the findings — and it lands as
|
|
1939
|
+
one artefact, `<scratch>/review-<pr>.json`, holding that bare object: the
|
|
1940
|
+
`review-pr-<pr#>` runner writes it and reports the digest and the path.
|
|
1941
|
+
|
|
1942
|
+
**You read the digest; the findings are the fix-applier's.**
|
|
1943
|
+
`jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}' <scratch>/review-<pr>.json`
|
|
1944
|
+
is the whole of your read, and it is what you record: `reviewed=<head>:<survived>/<refuted>/<unverified>`,
|
|
1945
|
+
off `head` and `counts`, on the PR's row. Findings never enter your context —
|
|
1946
|
+
a result runs 26-61 KB, 7-15k tokens that used to land in yours and then again,
|
|
1947
|
+
up to ~10k characters, in every fix-applier prompt you wrote. The fix-applier
|
|
1948
|
+
reads every one off the file and makes every ruling on them
|
|
1949
|
+
(`review-and-fix.md`'s **The review result file**). What the digest tells you:
|
|
1950
|
+
|
|
1951
|
+
**`testEnvironment` says what every dimension's `test_run` is evidence about**,
|
|
1952
|
+
and it is present on a healthy run as well as a degraded one, so there is
|
|
1953
|
+
nothing to notice by its absence. The snapshot is `git archive`d and then
|
|
1954
|
+
`git init`ed with one commit, and the block that cuts it compares that commit's
|
|
1955
|
+
tree hash against the reviewed commit's (#1056): verified, a suite run in the
|
|
1956
|
+
snapshot collects and runs what a checkout does, and a red is a fact about the
|
|
1957
|
+
tree. UNVERIFIED, it is not — tests that ask git what ships decline or fail for
|
|
1958
|
+
the environment, and this field carries which line of the cut failed. The
|
|
1959
|
+
fix-applier reads it before acting on any `test_run` count; you read it so a
|
|
1960
|
+
degraded review never passes for a clean one.
|
|
1961
|
+
`unverified` is *not* "checked and cleared" — a `suggestion` skips the pass by
|
|
1962
|
+
policy, and a finding whose refuters all crashed lands there too. Both go to the
|
|
1963
|
+
fix-applier with the rest, in the file; never rule on them yourself.
|
|
1964
|
+
**`refutersDispatched`, carried on every finding, is what tells those two
|
|
1965
|
+
apart** — zero is the policy skip, above zero with no surviving vote is the
|
|
1966
|
+
crash — so the population is read off that field rather than off severity,
|
|
1967
|
+
which records only how much a finding would matter if true. `resume` is
|
|
1968
|
+
non-null exactly when a specialist or a refuter pair crashed again after the
|
|
1969
|
+
review's own in-run retry, and **resume beats handing a crash-heavy review
|
|
1970
|
+
on**: a deferred crash is a finding nobody ever looked at.
|
|
1971
|
+
No replay exists for a review that ran in a runner's own kernel — `resume` is reported, not acted on, and the fix-applier defers what it names.
|
|
1972
|
+
`refuted` comes back deliberately as well — a refutation is itself a claim, and
|
|
1973
|
+
one has been reversed on new evidence. The fix-applier may reverse one; its
|
|
1974
|
+
report lists every refutation it reversed, and you copy those to the ledger's
|
|
1975
|
+
`ruled` line.
|
|
1976
|
+
|
|
1977
|
+
**`dimensionsRun` is the dispatch; `dimensionsUnrun` is what names a gap.** A
|
|
1978
|
+
specialist that dies, and one that never executed the suite, both contribute zero
|
|
1979
|
+
findings while the key stays in `dimensionsRun` — so read the two together. A key
|
|
1980
|
+
in `dimensionsRun` and NOT in `dimensionsUnrun` ran a suite; every
|
|
1981
|
+
`dimensionsUnrun` entry is `{dimension, reason}` naming which failure it was.
|
|
1982
|
+
The review already re-dispatched each crashed specialist once, so what
|
|
1983
|
+
`dimensionsUnrun` still names is residue: the fix-applier names it unrun in its
|
|
1984
|
+
report and re-runs nothing — an absence of findings is not coverage. Same rule
|
|
1985
|
+
the fallback below states for a killed specialist, for the same reason.
|
|
1986
|
+
|
|
1987
|
+
The rule this replaces — treat any dimension with nothing in
|
|
1988
|
+
`survived`/`refuted`/`unverified` as unrun — was the workaround for having no
|
|
1989
|
+
such field, and it over-refuses in the direction that costs work: a dimension
|
|
1990
|
+
that ran clean has nothing in those three either (#137, #138).
|
|
1991
|
+
|
|
1992
|
+
**`cwdAudit` is the specialist's own inherited-checkout audit, one entry per
|
|
1993
|
+
dispatched dimension: `{dimension, state, line}`, `state` one of**
|
|
1994
|
+
`clean`/`dirty`/`unrepo`/`missing`. The prompt asks every specialist to run
|
|
1995
|
+
`git status --porcelain -uall` against the directory it inherited before
|
|
1996
|
+
returning and fold the result into a `CWD-AUDIT:` line — a convention, not
|
|
1997
|
+
schema, so a specialist that never emits it or misspells it still validates
|
|
1998
|
+
clean. This field is the runtime backstop that reads for the line regardless:
|
|
1999
|
+
`missing` is exactly as loud as `dirty`, and both name a checkout you should
|
|
2000
|
+
treat as a live scratch write until you have checked it (#1433/#1673).
|
|
2001
|
+
|
|
2002
|
+
**A throw, an empty return, or a notification whose status is not `completed`
|
|
2003
|
+
is a failure event, not a clean review.** The review throws on missing
|
|
2004
|
+
`args.pr`/`args.worktree` and on a snapshot agent that returned no tree, and a
|
|
2005
|
+
failure surfaces mid-loop, where "react, never block" makes it easy to log and
|
|
2006
|
+
carry on — leaving a PR that *reads* as reviewed and is not. **Retry once, then
|
|
2007
|
+
fall back — and whoever holds the review call is who retries:**
|
|
2008
|
+
The `review-pr-<pr#>` runner already retried once inside its cell and reports `failed` with both errors; hand-dispatch the fallback reviewer below as `review-pr-<pr#>-b`, the name that report gives.
|
|
2009
|
+
Either way, settle the dead review by appending `=failed` to its `review=`
|
|
2010
|
+
token, then append `review=fallback:review-pr-<pr#>[-b]` after it, both in one
|
|
2011
|
+
`ledger.mjs row` rewrite — the tick takes the last `review=` token on a row as
|
|
2012
|
+
the one in flight, so that order is what keeps the fallback counted against the
|
|
2013
|
+
cap. A runner member that is killed rather than failed follows **Failure
|
|
2014
|
+
handling** (fresh name, inherited state stated).
|
|
2015
|
+
|
|
2016
|
+
**Then dispatch a fix-applier** — on `DISPATCH fix-pr PR#<M>`, which the tick
|
|
2017
|
+
prints for a PR whose `reviewed=` counts survivors and that has had no
|
|
2018
|
+
fix-applier since — one named member per PR, `fix-pr-<pr#>`, never the PR's
|
|
2019
|
+
implementer, recorded with `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the
|
|
2020
|
+
call. Its prompt carries the PR number, the worktree abs path, the PR's branch,
|
|
2021
|
+
the same `testCmd` you passed the review, and the **path** `<scratch>/review-<pr>.json`
|
|
2022
|
+
— never the findings. The fix-applier owns every per-PR ruling you once made
|
|
2023
|
+
before dispatch: both mutual-exclusion scans, the suggested-fix re-derivation,
|
|
2024
|
+
`refuted=false` ≠ apply, per-site measurement for a sibling-site extension, and
|
|
2025
|
+
`testEnvironment`/`cwdAudit` before any `test_run`. It holds every finding and
|
|
2026
|
+
you hold none, so there is nothing for you to rank, relay or pre-rule — and a
|
|
2027
|
+
report from a refuter it spawns that surfaces to you is its to retrieve, never
|
|
2028
|
+
yours to scan or pass on.
|
|
2029
|
+
|
|
2030
|
+
**A `DISPATCH fix-pr PR#<M>` on a conflict hold** — the row carries the merge
|
|
2031
|
+
bot's `conflict-hold:#<M>` (`run-merge-bot.md` step 1's fallback), not
|
|
2032
|
+
survivors — is the same slot with a different job, and no review file to hand
|
|
2033
|
+
over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
|
|
2034
|
+
already on record — `dispatch` refuses a reused one — and dispatch a
|
|
2035
|
+
`fleet-implementer` in the PR's existing worktree with the prompt below's
|
|
2036
|
+
worktree, branch and path discipline, but in place of its review paragraphs:
|
|
2037
|
+
bring `<branch>` current with `origin/main`, resolving every conflict by
|
|
2038
|
+
`run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
|
|
2039
|
+
head. Settle it `applied:<head>` — `no-op` if no conflict was left — which is
|
|
2040
|
+
what lifts the tick's merge hold; a dispatched-but-live one does not, and
|
|
2041
|
+
`failed`/`killed` leave the PR fix-due for a replacement. The push moves the
|
|
2042
|
+
head after `ready-to-merge`, so the next merge bot refuses it
|
|
2043
|
+
`head-moved-after-label-#<M>`: a fresh finisher, per **Failure handling**.
|
|
2044
|
+
|
|
2045
|
+
**A refutation resting on an injection nothing proved landed is not a refutation
|
|
2046
|
+
— it is a cell that never ran.** A mutation test and a finding reproduction are
|
|
2047
|
+
both failure injections: break something, read what the child does. When the
|
|
2048
|
+
break never reaches the child, the child behaves exactly like its baseline, which
|
|
2049
|
+
is what a genuine no-effect mutation looks like and what a correctly refuted
|
|
2050
|
+
finding looks like. So a negative result is admitted only together with its
|
|
2051
|
+
**positive control** — one run proving the injected difference is observable,
|
|
2052
|
+
either the child's output differing with the injection present versus absent or
|
|
2053
|
+
the child echoing the injected value back from inside. No control → the cell is
|
|
2054
|
+
unrun: re-run it, and never record it as a negative. Measured 2026-08-28 and
|
|
2055
|
+
re-measured on this tree, against a `probe.sh` that echoes both variables back:
|
|
2056
|
+
|
|
2057
|
+
```sh
|
|
2058
|
+
zsh -c 'cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh' # BADJ=[unset] SETB=[1 BADJ=1]
|
|
2059
|
+
bash -c 'cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh' # BADJ=[1] SETB=[1]
|
|
2060
|
+
```
|
|
2061
|
+
|
|
2062
|
+
zsh does not word-split an unquoted parameter expansion, so the whole string
|
|
2063
|
+
arrives as ONE argument: a variable literally named `SETB` takes the value
|
|
2064
|
+
`1 BADJ=1`, the injection variable `BADJ` is never set, and the probe still exits
|
|
2065
|
+
0. It bites in both directions, and the reproduction direction is the worse one —
|
|
2066
|
+
`fix-pr-983` nearly reported a mutant as behaving identically to its baseline,
|
|
2067
|
+
while `fix-pr-1153` nearly retired a real review finding as non-reproducing after
|
|
2068
|
+
the same shape handed both trees a single argv word and drew `exit 2` from each,
|
|
2069
|
+
which is the signature of a correct refutation with nothing anomalous to notice.
|
|
2070
|
+
The fix-applier prompt and every refuter brief carry the rule and the safe
|
|
2071
|
+
invocation form; the merge bot's brief is the wrong seat, because a bot
|
|
2072
|
+
reads gates and never injects a fault.
|
|
2073
|
+
|
|
2074
|
+
**Where `testCmd` comes from:** the repo's own test command, the one you hand
|
|
2075
|
+
specialists per **Give specialists a stack-free test command** above — in this
|
|
2076
|
+
repo `node --test plugin/scripts/*.test.mjs`. Pass the same string to the
|
|
2077
|
+
review, to the fix-applier, and to the finisher — whose duty-2 mutation gate
|
|
2078
|
+
runs it too — so every gate runs one command. Omit it from the review args and
|
|
2079
|
+
the review (`review-core.mjs`, in a runner) now DERIVES it
|
|
2080
|
+
from the repo under review (#142) instead of defaulting to a fixed string —
|
|
2081
|
+
refusing outright if it can't; the fix-applier has no such fallback, so
|
|
2082
|
+
substituting `<testCmd>` with nothing leaves it no gate at all.
|
|
2083
|
+
|
|
2084
|
+
**Where `<branch>` comes from:** the PR's head branch —
|
|
2085
|
+
`gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut
|
|
2086
|
+
the worktree from. Substitute it exactly as you substitute `<testCmd>`, because
|
|
2087
|
+
the member cannot read it off git: phase 1 creates an already-open PR's worktree
|
|
2088
|
+
with `--detach`, and there `git branch --show-current` prints nothing and exits 0
|
|
2089
|
+
(measured 2026-09-18, git 2.50.1), so `git push origin
|
|
2090
|
+
"HEAD:$(git branch --show-current)"` exits 128 on `fatal: invalid refspec
|
|
2091
|
+
'HEAD:'`. Left unsubstituted, the push that prompt ends on has no destination at
|
|
2092
|
+
all.
|
|
2093
|
+
|
|
2094
|
+
> You are ALREADY in worktree `<abs-path>`, whose PR branch is `<branch>` — the
|
|
2095
|
+
> push destination below, given to you because a detached worktree cannot supply
|
|
2096
|
+
> it. Do NOT create another worktree. The review is done and its result is the
|
|
2097
|
+
> file below — do not re-review, do not dispatch specialists.
|
|
2098
|
+
>
|
|
2099
|
+
> **`edit` and `read` resolve a bare relative path against the SESSION ROOT —
|
|
2100
|
+
> the controller's own main checkout — not against that worktree and not
|
|
2101
|
+
> against your `bash` cwd, which they share no `cwd` parameter with. Give them
|
|
2102
|
+
> the absolute worktree path on every call, mutation-probe copies included.**
|
|
2103
|
+
> The main checkout is the parent of `git rev-parse --path-format=absolute
|
|
2104
|
+
> --git-common-dir`. A `member-write-guard` refusal means the path hit the
|
|
2105
|
+
> main checkout — for `bash`, a missing or main-checkout `cwd` — so re-issue
|
|
2106
|
+
> it absolute, under your worktree.
|
|
2107
|
+
>
|
|
2108
|
+
> Read `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` and run **steps 2, 3
|
|
2109
|
+
> and 5 only**: split apply-now/defer, commit, push, file every deferral as its
|
|
2110
|
+
> own issue with the label the finding's state calls for. Skip step 1 — the
|
|
2111
|
+
> review already ran — and steps 4 and 6: the controller owns the CI wait and
|
|
2112
|
+
> dispatches the finisher.
|
|
2113
|
+
>
|
|
2114
|
+
> **The review's result is `<scratch>/review-<pr>.json`** — the digest first
|
|
2115
|
+
> (`jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}'`),
|
|
2116
|
+
> then every finding (`jq '.survived'`, `jq '.unverified'`, `jq '.refuted'`).
|
|
2117
|
+
> Read it through `review-and-fix.md`'s **The review result file**, which holds
|
|
2118
|
+
> the rest of the recipes and every ruling on the findings: both
|
|
2119
|
+
> mutual-exclusion scans, the suggested-fix re-derivation, `refuted=false` ≠
|
|
2120
|
+
> apply, per-site measurement for a sibling-site extension, and `testEnvironment`
|
|
2121
|
+
> and `cwdAudit` before any `test_run`. Every one of those rulings is yours —
|
|
2122
|
+
> nobody upstream has made one, and the controller never reads the findings.
|
|
2123
|
+
>
|
|
2124
|
+
> **Every factual claim your diff restates needs a settling command run
|
|
2125
|
+
> against the tree first** — the issue body is a lead, never a citation.
|
|
2126
|
+
> **No positional references** (`the closing/second/last X`); name the thing
|
|
2127
|
+
> semantically. **Never write a COUNT or a tally into prose; state the
|
|
2128
|
+
> property instead** — unless it is a past-tense record of a measurement you
|
|
2129
|
+
> performed, which stays as written; a present-tense claim about a live
|
|
2130
|
+
> property must be restated as a property (`every other test in the file`),
|
|
2131
|
+
> true at any count. **A settling grep over literal text takes `grep -F`, and
|
|
2132
|
+
> its zero counts only after the same command finds a line known to match.**
|
|
2133
|
+
>
|
|
2134
|
+
> **Apply `survived` findings. A finding in `unverified` whose refuters ran and
|
|
2135
|
+
> crashed always defers** — and which of the two it is, you read off
|
|
2136
|
+
> `refutersDispatched`, never off severity and never off an empty vote list:
|
|
2137
|
+
> above zero with nothing surviving means every refuter dispatched against it
|
|
2138
|
+
> died, and at `critical` that is every one of them. Severity records how much a
|
|
2139
|
+
> finding would matter if true, never whether anything looked. Say *in the
|
|
2140
|
+
> deferral* that its refuters crashed rather than that it went unchecked — the
|
|
2141
|
+
> review re-dispatched each crash once already and reports what died again, so
|
|
2142
|
+
> a deferral that names the crash can still be re-verified. **A `suggestion` is also in `unverified`,
|
|
2143
|
+
> for a different reason — `refutersDispatched` of zero, the 0-refuter budget
|
|
2144
|
+
> the review gives that band by policy — and the rule below, not this one,
|
|
2145
|
+
> covers it.**
|
|
2146
|
+
>
|
|
2147
|
+
> **A `suggestion` is budgeted 0 refuters, so it is unchecked until you check
|
|
2148
|
+
> it.** For each one, first decide scope: is it inside the scope of the PR's own
|
|
2149
|
+
> ticket, or a different piece of work? **Out of scope → defer and file, never
|
|
2150
|
+
> apply.** **In scope → dispatch ONE refuter** against the finding before
|
|
2151
|
+
> touching the tree, biased to refuse, and hand it the prompt below with one
|
|
2152
|
+
> substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path
|
|
2153
|
+
> under your own run root — `mktemp -d` once per round for
|
|
2154
|
+
> `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids
|
|
2155
|
+
> restart at 1 each round too — and write that absolute path into the
|
|
2156
|
+
> refuter's prompt in its place; a refuter never derives its own path:
|
|
2157
|
+
>
|
|
2158
|
+
> > Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by
|
|
2159
|
+
> > RUNNING something — compile it, run the test, apply the mutation. Do not
|
|
2160
|
+
> > reason your way to agreement. Observe that run synchronously — run the
|
|
2161
|
+
> > command, wait for it, read its exit code. Never poll a log file for a
|
|
2162
|
+
> > completion marker: prefer ONE blocking run to a poll loop, and treat its
|
|
2163
|
+
> > return as permission to look, never as the answer. Reading a log the run has
|
|
2164
|
+
> > already finished writing is fine; waiting on one is not. If you match a test
|
|
2165
|
+
> > reporter's own output, accepting both `ℹ` and `#` is necessary but NOT
|
|
2166
|
+
> > sufficient — strip SGR escapes first as well. node's prefix moves with the
|
|
2167
|
+
> > node version and with whether stdout is a TTY, and color wraps the whole line
|
|
2168
|
+
> > so it begins with ESC and no prefix anchor matches at all, which returns
|
|
2169
|
+
> > empty at exit 0 — indistinguishable from a hung run and from a run of zero
|
|
2170
|
+
> > tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=`
|
|
2171
|
+
> > empty still enables color, so it is not a control. State your search scope
|
|
2172
|
+
> > AND what your pattern would have missed. A grep over one ref does not
|
|
2173
|
+
> > support a claim about history; a pattern built from the token a diff removed
|
|
2174
|
+
> > does not support a claim that the category is empty. A failure injection with
|
|
2175
|
+
> > no positive control has produced NO result, never a negative one. Before you
|
|
2176
|
+
> > read an injected fault — an env var, an argv word, a mutant — as having had
|
|
2177
|
+
> > no effect, prove the injection reached the child: one run whose output
|
|
2178
|
+
> > differs with it present versus absent, or the child echoing the injected
|
|
2179
|
+
> > value back. Uncontrolled, the cell is unrun — say so in your verdict instead
|
|
2180
|
+
> > of reporting a no-effect result. Build such an invocation as an array
|
|
2181
|
+
> > expanded braced and quoted —
|
|
2182
|
+
> > `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
|
|
2183
|
+
> > assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
|
|
2184
|
+
> > unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
|
|
2185
|
+
> > zsh passes ONE argument, sets a variable literally named `SETB` to
|
|
2186
|
+
> > `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not
|
|
2187
|
+
> > the portable spelling either: measured, bash word-splits it into `SETB=1`
|
|
2188
|
+
> > and `BADJ=1[@]`, so the injection variable is set to a corrupted value,
|
|
2189
|
+
> > while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set,
|
|
2190
|
+
> > exit 0. Everything you
|
|
2191
|
+
> > write — mutants, fixtures,
|
|
2192
|
+
> > scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else;
|
|
2193
|
+
> > the checkout and any worktree are never write targets, though
|
|
2194
|
+
> > `git show`/`git archive` at a pinned ref read fine anywhere. Chain the
|
|
2195
|
+
> > directory change into the command, `cd "$D" && git …`, never
|
|
2196
|
+
> > `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in
|
|
2197
|
+
> > the checkout — and bracket a fixture's own git with
|
|
2198
|
+
> > `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to
|
|
2199
|
+
> > the repository, and a fresh scratch dir's `fatal: not a git repository`
|
|
2200
|
+
> > (exit 128) is the pass, not a failure; before any `git commit` it must
|
|
2201
|
+
> > resolve to your scratch path — compare resolved forms (`realpath`), since
|
|
2202
|
+
> > `--show-toplevel` can report `/private/tmp/…` for a `/tmp` scratch dir on
|
|
2203
|
+
> > macOS.
|
|
2204
|
+
>
|
|
2205
|
+
> Survives → apply it, with one hold: if its refuter reports a blast radius
|
|
2206
|
+
> touching lines another finding also changes, that is the mutual-exclusion
|
|
2207
|
+
> scan's second input — rule the pair before either change reaches the tree;
|
|
2208
|
+
> you hold every finding, so only you can see that the two cannot both land. Refuted → defer and file it, and
|
|
2209
|
+
> say the refutation in the issue body. **Apply only what survives — no report is not a survival.** A
|
|
2210
|
+
> refuter you never hear from leaves the finding exactly as unchecked as it
|
|
2211
|
+
> arrived, so it defers like a refuted one.
|
|
2212
|
+
>
|
|
2213
|
+
> **A finding's `suggested_fix` is a hypothesis, not a patch — the review never
|
|
2214
|
+
> ran it.** Only the claim is verified adversarially; the remedy text is unchecked.
|
|
2215
|
+
> Three were wrong as written in one run: a stated end state that dropped a
|
|
2216
|
+
> load-bearing option and measured RED, an assertion against a property the test
|
|
2217
|
+
> helper does not expose (`TypeError`), and an enumeration that stopped short of
|
|
2218
|
+
> two further stale clauses — one of them false in the *dangerous* direction. Run
|
|
2219
|
+
> the remedy before you commit it, and re-derive an assertion from the post-fix
|
|
2220
|
+
> tree rather than from the finding, since a sibling finding may edit the very
|
|
2221
|
+
> text it asserts on.
|
|
2222
|
+
>
|
|
2223
|
+
> **Retrieve that report yourself; do not wait to be handed it — this covers the
|
|
2224
|
+
> refuters YOU dispatch, and only those.** The review's own specialists do leave
|
|
2225
|
+
> transcripts, but nothing gives you their address: the review had `agent()`
|
|
2226
|
+
> return their findings into the script, so the result file holds their findings
|
|
2227
|
+
> and names no transcript, and nothing on disk indexes a transcript by PR or
|
|
2228
|
+
> dimension. Hunting their paths gets you nothing; read the file. A report from a refuter you spawned is
|
|
2229
|
+
> different — it surfaces to the controller rather than to you, and waiting for a
|
|
2230
|
+
> relay that never comes strands the finding. Its transcript is at the output file
|
|
2231
|
+
> named in your spawn result, and its report is the last record:
|
|
2232
|
+
>
|
|
2233
|
+
> 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.
|
|
2234
|
+
>
|
|
2235
|
+
> If retrieval comes back empty, ask the controller by name. Only when neither
|
|
2236
|
+
> works is the finding **unchecked** — defer and file it, and say so in the body. This is
|
|
2237
|
+
> `review-and-fix.md`'s **Specialists** rule; it reaches you here because the
|
|
2238
|
+
> steps that point at it are the ones you skip.
|
|
2239
|
+
>
|
|
2240
|
+
> The CI facts in that file apply to you — a `rebase-check` red, or heavy jobs
|
|
2241
|
+
> `skipped`, **solely** off a non-zero behind-count, is staleness and not a
|
|
2242
|
+
> failure. Never rebase to clear it. **`solely` is the load-bearing word:**
|
|
2243
|
+
> `ci.yml`'s `rebase-check` exits 1 on five conditions and only one is
|
|
2244
|
+
> staleness, so a non-zero behind-count does not by itself settle which fired.
|
|
2245
|
+
> The job log names the condition — and because the staleness condition exits
|
|
2246
|
+
> before the merge-commit condition is evaluated, the log is silent on that one
|
|
2247
|
+
> by construction, so measure it separately with
|
|
2248
|
+
> `git fetch origin && git rev-list --merges --count "origin/<base>..HEAD"` —
|
|
2249
|
+
> keep the fetch, or a stale local `origin/<base>` widens the range over the
|
|
2250
|
+
> base's own merge commits and reports a merge commit this branch never added.
|
|
2251
|
+
> A non-zero count does not send you to a local rebase either: the merge bot's
|
|
2252
|
+
> step-1 `gh pr update-branch --rebase` drops merge commits too
|
|
2253
|
+
> (`run-merge-bot.md` step 1), so both conditions clear on that one server-side
|
|
2254
|
+
> rebase. What it buys you is knowing the red was never solely staleness.
|
|
2255
|
+
>
|
|
2256
|
+
> **Run `<testCmd>` from the worktree before committing**, copied verbatim.
|
|
2257
|
+
> `tests 0` is a FAILED run, not a pass. Red or zero-test → fix it, or move that
|
|
2258
|
+
> finding to defer; never commit over it. **Never `--no-verify`** — a failing
|
|
2259
|
+
> hook is a finding you report, not an obstacle you route around. Report the test
|
|
2260
|
+
> result with your SHA. Nothing re-reviews this commit: the review ran against a
|
|
2261
|
+
> snapshot cut before your edits existed, and a refuter checked the finding's
|
|
2262
|
+
> claim, never your patch.
|
|
2263
|
+
>
|
|
2264
|
+
> **A test you ADD must kill its own mutant** — break what it pins, confirm it and
|
|
2265
|
+
> only it goes red, restore. **Then a change it should *not* catch, staying
|
|
2266
|
+
> green** — else you proved it fails, not that it discriminates: a pin asserting
|
|
2267
|
+
> whole-file text clears "it and only it goes red" and still reddens on any edit
|
|
2268
|
+
> (measured). A green suite says nothing about a new test: one pin this run
|
|
2269
|
+
> survived the exact mutation it was named for.
|
|
2270
|
+
>
|
|
2271
|
+
> **A mutation that never landed is not a green — it is a cell that did not
|
|
2272
|
+
> run.** Same rule for any fault you inject to see what breaks: prove the
|
|
2273
|
+
> injection reached the child before you read its result — one run whose output
|
|
2274
|
+
> differs with the injection present versus absent, or the child echoing the
|
|
2275
|
+
> injected value back. Without one, a probe that exits 0 reporting the mutant
|
|
2276
|
+
> behaving exactly like its baseline is indistinguishable from a real no-effect
|
|
2277
|
+
> result, and a reproduction that never happened reads as a refutation. Build
|
|
2278
|
+
> such an invocation as an array expanded braced and quoted —
|
|
2279
|
+
> `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
|
|
2280
|
+
> assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
|
|
2281
|
+
> unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
|
|
2282
|
+
> zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`,
|
|
2283
|
+
> never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable
|
|
2284
|
+
> spelling either: measured, bash word-splits it into `SETB=1` and
|
|
2285
|
+
> `BADJ=1[@]`, so the injection variable is set to a corrupted value, while
|
|
2286
|
+
> zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0.
|
|
2287
|
+
>
|
|
2288
|
+
> **Commit BEFORE you mutate, and restore with `cp`, never a git discard.**
|
|
2289
|
+
> `git checkout -- <file>` reverts the whole file, not your mutant — so it also
|
|
2290
|
+
> eats uncommitted edits you made earlier, and the "clean baseline" you measure
|
|
2291
|
+
> next is silently the reverted file. Two members hit this in one run; one lost
|
|
2292
|
+
> prose edits and caught it only because a non-catch control failed. Copy the
|
|
2293
|
+
> file aside and copy it back. Better still, mutate a copy under
|
|
2294
|
+
> `<scratch>/pr<N>/mutate/` and leave the worktree untouched — that is what
|
|
2295
|
+
> refuters are already required to do, and it has no blast radius at all.
|
|
2296
|
+
>
|
|
2297
|
+
> **Never `git stash` or `git stash pop` here either — a WIP commit is the
|
|
2298
|
+
> substitute, not a second scratch mechanism: `git commit -m wip`, then
|
|
2299
|
+
> restore or amend once you're back to real work.** The stash stack is
|
|
2300
|
+
> repo-global too, not per-worktree or per-session — the same `refs/stash`
|
|
2301
|
+
> every concurrent member and the main checkout share, not partitioned the
|
|
2302
|
+
> way `<scratch>/pr<N>/mutate/` above is. A bare pop takes whichever entry is
|
|
2303
|
+
> on top, from any worktree, silently — rc 0, no error — when the tree
|
|
2304
|
+
> receiving it is clean on the affected paths, and refuses only when that
|
|
2305
|
+
> tree is already dirty there. A bare `git stash` (push) does not reach into
|
|
2306
|
+
> a sibling's tree, so that half is not the risk — the pop is. Nothing
|
|
2307
|
+
> partitions the stack; this prohibition is the whole of the protection.
|
|
2308
|
+
>
|
|
2309
|
+
> **Report LAST, and only once nothing can still change.** A report you have
|
|
2310
|
+
> sent **pins that SHA** for the controller, which dispatches a finisher against
|
|
2311
|
+
> it. If a further instruction arrives after you have reported, reply saying the
|
|
2312
|
+
> SHA is moving *before* you touch the tree again — do not silently do the work
|
|
2313
|
+
> and re-report. Measured: three members in one run sent a final report and kept
|
|
2314
|
+
> working; one had its worktree audited mid-mutation, another handed over a SHA
|
|
2315
|
+
> that was two commits stale, and a finisher dispatched on either would have
|
|
2316
|
+
> halted on a diverged head.
|
|
2317
|
+
>
|
|
2318
|
+
> Then report to the controller the pushed SHA, your apply/defer split, and
|
|
2319
|
+
> the deferral issue numbers — a `filed: #N <subject>` line for every issue
|
|
2320
|
+
> step 5 created, and `unrecorded: #N <subject>` for one whose `ledger.mjs filed`
|
|
2321
|
+
> failed twice — and exit. **Deferring everything is a normal
|
|
2322
|
+
> outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
|
|
2323
|
+
> index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and you
|
|
2324
|
+
> report `no-op, HEAD unchanged at <sha>` in place of a new SHA. Say it
|
|
2325
|
+
> explicitly — silence there is indistinguishable from a member that died. Never
|
|
2326
|
+
> manufacture a commit to make CI fire.
|
|
2327
|
+
|
|
2328
|
+
**Put the standing CI facts in that prompt, not in per-event messages** —
|
|
2329
|
+
otherwise you send "your red is staleness, do not rebase" once per member per
|
|
2330
|
+
merge. `review-and-fix.md` states them; the prompt only has to say they apply.
|
|
2331
|
+
|
|
2332
|
+
**The fix-applier pushes and exits — it does not hold the CI wait.** You own the
|
|
2333
|
+
persistent Monitor; a turn-based member re-reading `gh pr checks` each idle cycle
|
|
2334
|
+
rebuilds a 100k-token context for nothing the Monitor lacks. The prompt block
|
|
2335
|
+
above carries the report-last rule; you do not have to restate it. When the
|
|
2336
|
+
diff-validating `check` job is green **and no
|
|
2337
|
+
heavy job is in `failure`** (the heavy diff-validating suites — not the
|
|
2338
|
+
`rebase-check` currency gate; a `skipped` heavy job is behind-count staleness and
|
|
2339
|
+
fine — **solely** off that count, which is a condition to establish rather than
|
|
2340
|
+
infer, see the five-condition note in the fix-applier block above) — or
|
|
2341
|
+
`ci-state.mjs` reads `verdict: "no-ci"`, see below — **and once the PR's review
|
|
2342
|
+
has returned and its fix-applier, if one was dispatched, has sent its report,
|
|
2343
|
+
which the CI-completes edge above states in full** — dispatch a
|
|
2344
|
+
**finisher** — a fresh small agent, not the fix-applier resumed. **Dispatch it
|
|
2345
|
+
by its own definition and omit `model` on the call** — the tier (`haiku`)
|
|
2346
|
+
lives in `agents/fleet-finisher.agent.md`:
|
|
2347
|
+
|
|
2348
|
+
`fleet-finisher`.
|
|
2349
|
+
|
|
2350
|
+
Record it with `ledger.mjs dispatch <pr#> finisher-pr-<pr#>` before the call.
|
|
2351
|
+
Its four duties are a checklist — audit the
|
|
2352
|
+
worktree, confirm every deferral has a tracker home and re-run the acceptance
|
|
2353
|
+
mutation, apply one release label, report — and the
|
|
2354
|
+
merge gate downstream still catches whatever it gets wrong, the same argument
|
|
2355
|
+
that puts the merge bot on the same tier below. **Never dispatch
|
|
2356
|
+
one while you still owe the fix-applier a ruling**: the pinned SHA is only as good
|
|
2357
|
+
as the guarantee nothing else is inbound. **The test is your OUTBOX, not the
|
|
2358
|
+
member's last message** — anything you have decided that it has not received,
|
|
2359
|
+
including a ruling you have since **withdrawn or reversed**. **That is the test
|
|
2360
|
+
of THIS condition only**: an empty outbox says nothing is inbound from you, and
|
|
2361
|
+
nothing about whether the member considers itself finished, which is what the
|
|
2362
|
+
report condition above is for. A withdrawal you
|
|
2363
|
+
recorded only in the ledger is undelivered: the member still holds the original
|
|
2364
|
+
and will act on it. Relay everything — reversals too — then dispatch.
|
|
2365
|
+
|
|
2366
|
+
**An unanswered question from the member is an outbox item, and it blocks
|
|
2367
|
+
dispatch with the same weight as a ruling you have already made.** It does not
|
|
2368
|
+
feel like one — you have decided nothing yet, so the outbox reads empty — but a
|
|
2369
|
+
member waiting on you is a member that will push once you answer, and the SHA
|
|
2370
|
+
you are about to pin is exactly what that push moves. Measured on #488's run:
|
|
2371
|
+
`fix-pr-488` asked whether to add two pins, and the finisher was held until the
|
|
2372
|
+
member acknowledged the answer. That worked because the controller chose to
|
|
2373
|
+
hold, not because a rule required it. Answer it, or tell the member you are not
|
|
2374
|
+
ruling and it should proceed on its own default — either empties the outbox.
|
|
2375
|
+
What does not empty it is noticing the question and dispatching anyway.
|
|
2376
|
+
|
|
2377
|
+
**A final report is not proof the member stopped.** Observed twice: a ruling
|
|
2378
|
+
relayed after dispatch produced a new commit mid-audit, and a fix-applier that
|
|
2379
|
+
reported "nothing outstanding" resumed on a ledger-only withdrawal and was
|
|
2380
|
+
cycling mutants through the worktree when the finisher audited it. Both finishers
|
|
2381
|
+
correctly halted. Note what that costs to detect: two reads of the same worktree
|
|
2382
|
+
a minute apart showed *different* mutants, so a member's report and any single
|
|
2383
|
+
`git status` are each valid only at their instant. Its duties, in this order:
|
|
2384
|
+
|
|
2385
|
+
1. **Audit the worktree** — run `worktree-audit.sh` (it takes no argument; it
|
|
2386
|
+
audits every worktree in one pass, so find this worktree's row in its
|
|
2387
|
+
output). Match the row by the resolved form of the worktree path you were
|
|
2388
|
+
dispatched with — `realpath <abs-path>`, or `cd <abs-path> && pwd -P` —
|
|
2389
|
+
never by that path as written: the row's `worktree` field is the physical
|
|
2390
|
+
path `git worktree list` reports, so a spelling reached through a symlink
|
|
2391
|
+
(macOS's `/tmp` and `/var/folders` are symlinks too) matches no row on a
|
|
2392
|
+
healthy worktree. Two checks, each with the instrument that can answer it.
|
|
2393
|
+
**Dirty:** the row's `dirty` field, or `git status --porcelain -unormal`
|
|
2394
|
+
inside the worktree itself — the explicit mode, never bare `--porcelain`, or
|
|
2395
|
+
`status.showUntrackedFiles = no` reads a dirty worktree as clean (#730). The
|
|
2396
|
+
row is the better read: in a worktree whose `.git` linkage is missing,
|
|
2397
|
+
`git status` answers for the enclosing repo at rc 0, where the audit reports
|
|
2398
|
+
the worktree unreadable. **Diverged:** the worktree's `HEAD` against your
|
|
2399
|
+
dispatch pin — the cause block's head-equality check below. Neither
|
|
2400
|
+
instrument above answers it: `git status --porcelain` reports no commits,
|
|
2401
|
+
and the row's `ahead` is counted against `origin/main`, which a PR worktree
|
|
2402
|
+
is always ahead of, so it cannot answer this. Three row shapes halt too,
|
|
2403
|
+
each named in the report with the script's stderr line quoted where it
|
|
2404
|
+
prints one: `readable:false` with `null` counts
|
|
2405
|
+
(`UNREADABLE: <wt> (<cause>)`) is *worktree unreadable*, `readable:false`
|
|
2406
|
+
with zero counts (`MISSING on disk: <wt>`) is *worktree missing*, and no
|
|
2407
|
+
row for this worktree at all is *worktree absent*. `git status` is no
|
|
2408
|
+
substitute for the audit here — it answers the dirty check only, and a
|
|
2409
|
+
finisher that cannot see the tree it labels cannot vouch for it. Dirty,
|
|
2410
|
+
diverged, unreadable, missing or absent halts the finisher *here*, before
|
|
2411
|
+
the label: it reports what it found and labels nothing. A finisher that
|
|
2412
|
+
verifies the dirt is harmless and labels anyway has substituted the rule's
|
|
2413
|
+
purpose for the rule, and you find out at merge time. **Give it the cause block below,
|
|
2414
|
+
verbatim** — a bare SHA mismatch names no cause, and the halt report needs
|
|
2415
|
+
one. **Give it `<testCmd>` too** — the same string you passed the workflow
|
|
2416
|
+
and the fix-applier — because duty 2's mutation gate runs it and nothing
|
|
2417
|
+
else hands the finisher one; substituted with nothing it leaves that gate
|
|
2418
|
+
no command at all.
|
|
2419
|
+
2. **Confirm every deferral — and every claimed APPLY — has a home that outlives
|
|
2420
|
+
the merge.** The test is a durable home, not a tracker number: a tracker
|
|
2421
|
+
issue and a committed in-tree comment both qualify, and for a finding whose
|
|
2422
|
+
remedy was measured worse than the defect the in-tree note is the better one.
|
|
2423
|
+
What fails is a promise living only in a PR body, or on the PR's *own* source
|
|
2424
|
+
issue, which `Closes #N` buries on merge. Caught once at seven findings. A
|
|
2425
|
+
comment on an existing *follow-up* issue is filed: that is
|
|
2426
|
+
`review-and-fix.md` step 5, not a violation. Not filed → file it or halt,
|
|
2427
|
+
never label over it — and file it the way step 5 does, through
|
|
2428
|
+
`ledger.mjs check "<subject>"`, never a bare search. The finisher files last,
|
|
2429
|
+
off its own read of what the reviewer left behind, so a deferral it reads as
|
|
2430
|
+
unfiled may already be on the tracker under someone else's wording. Then
|
|
2431
|
+
record it the way step 5 does: `ledger.mjs filed <N> "<subject>"`
|
|
2432
|
+
immediately after `gh issue create`, with the same subject string you passed
|
|
2433
|
+
to `check`. If `filed` fails, retry once; if it fails again, leave the issue
|
|
2434
|
+
alone — it exists and is correct — and report it `unrecorded: #N <subject>`.
|
|
2435
|
+
|
|
2436
|
+
**A fix-applier's "applied" is a claim like any other**, and nothing else
|
|
2437
|
+
checks it — the review ran against a snapshot cut before those edits existed.
|
|
2438
|
+
Confirm `git diff origin/main...HEAD` actually contains what it reported
|
|
2439
|
+
applying. Two finishers in one run extended duty 2 this way unprompted, and
|
|
2440
|
+
one found five applies where the controller's hand-written list named three:
|
|
2441
|
+
a controller's list of what to verify is itself a claim.
|
|
2442
|
+
|
|
2443
|
+
**That range is right for the positive check and wrong for a negative one.**
|
|
2444
|
+
It spans the implementer's commits too, so a constraint of the form *file X
|
|
2445
|
+
was not touched* has to be scoped to the apply commit. Measured on PR #776:
|
|
2446
|
+
a controller wrote "neither document was touched" against
|
|
2447
|
+
`origin/main...HEAD` on a two-commit branch whose documents the IMPLEMENTER
|
|
2448
|
+
had correctly edited — the PR's whole point — and a finisher reading that
|
|
2449
|
+
literally halts a correct PR. It caught the error instead, and said so; do
|
|
2450
|
+
not rely on that.
|
|
2451
|
+
|
|
2452
|
+
**Whatever you verify by RUNNING, run in a tree nobody else owns.**
|
|
2453
|
+
Independently re-running the ticket's acceptance mutation — loosen the
|
|
2454
|
+
regex, delete the guard clause, flip the per-entry reset, run `<testCmd>`,
|
|
2455
|
+
watch it redden, discard — is the half of this duty reading a diff cannot
|
|
2456
|
+
do, and it stays. But it **writes**, and the PR's worktree belongs to
|
|
2457
|
+
another member. Measured on #380: a finisher was inside that worktree at the
|
|
2458
|
+
instant the fix-applier announced one more clause to land, and neither
|
|
2459
|
+
ordering is detectable afterwards from the diff — a restore lands on the
|
|
2460
|
+
uncommitted clause and destroys it silently, or the mutant is still in the
|
|
2461
|
+
tree when the fix-applier commits and a deliberately broken guard ships as
|
|
2462
|
+
the fix, in a commit nothing re-reviews. So take your own:
|
|
2463
|
+
`git worktree add --detach <scratch>/pr<N>/finish-<your member name> <your dispatch pin>`,
|
|
2464
|
+
mutate and run `<testCmd>` in there, then
|
|
2465
|
+
`git worktree remove --force <scratch>/pr<N>/finish-<your member name>`.
|
|
2466
|
+
**At your dispatch pin, never at the fetched branch tip** — duty 1 just
|
|
2467
|
+
proved the owned worktree sits at that pin, and `PR headRefOid` may carry
|
|
2468
|
+
commits no reviewer read, the substitution the halt block's head-equality
|
|
2469
|
+
check rejects for the same reason. The member name is in the path because
|
|
2470
|
+
the scratch root is shared with every sibling, so `<scratch>/pr<N>` alone
|
|
2471
|
+
collides whenever a PR gets a second finisher, and `worktree add` on an
|
|
2472
|
+
occupied path fails closed into a halt with a purely mechanical cause.
|
|
2473
|
+
|
|
2474
|
+
**Remove it on every path, the failing ones included** — a mutant that comes
|
|
2475
|
+
back green, a suite that will not start, your own halt at any duty. `--force`
|
|
2476
|
+
is required and is right only here: the tree is deliberately dirty when you
|
|
2477
|
+
are done, so a plain `git worktree remove` refuses it (`contains modified or
|
|
2478
|
+
untracked files`, rc 128, directory left on disk — measured, git 2.50.1),
|
|
2479
|
+
while everywhere else in this runbook that refusal is a finding precisely
|
|
2480
|
+
because the dirt may be someone's only copy. Here nothing in it is anyone's.
|
|
2481
|
+
Nothing sweeps a leak for you either: `reap.sh`'s branchless sweep is bounded
|
|
2482
|
+
to the fleet's worktree home, so a tree under `<scratch>` is a `kept` entry
|
|
2483
|
+
it reports and never collects. The tree you added is a checkout, so since #55
|
|
2484
|
+
it carries the tracked `./agent-test` like any other — run either that or
|
|
2485
|
+
`<testCmd>` in it, per **A reused worktree may lack the runner** above.
|
|
2486
|
+
|
|
2487
|
+
**None of this licenses a write to the owned worktree.** Duty 1 is a read;
|
|
2488
|
+
you never restore that tree, because you never wrote to it. A controller
|
|
2489
|
+
instruction to restore mutated paths there is an instruction to perform the
|
|
2490
|
+
silent-destruction ordering above — report it back, do not run it. One
|
|
2491
|
+
finisher refused exactly that instruction live, on the grounds it could not
|
|
2492
|
+
prove the diff was its own; that was judgement, and this is the rule.
|
|
2493
|
+
3. Add `ready-to-merge` — after reading the PR's labels back
|
|
2494
|
+
(`gh pr view <pr> --json labels`) and finding **exactly one** release label,
|
|
2495
|
+
`patch`/`minor`/`major`. Zero or more than one halts the finisher before the
|
|
2496
|
+
label, naming which it found. This is the backstop for a label lost wherever
|
|
2497
|
+
it was lost, a hand-created PR included: a `gh pr create` that outran its
|
|
2498
|
+
caller's tool timeout leaves the PR open with the flag unapplied and no exit
|
|
2499
|
+
status anywhere to notice, and nothing downstream re-derives the release
|
|
2500
|
+
label. Count only those three — the PR carries other labels, `ready-to-merge`
|
|
2501
|
+
itself among them once you add it, so a PR wearing one release label beside
|
|
2502
|
+
them passes unchanged. A repo that defines none of the three does not gate on
|
|
2503
|
+
one — `gh label list` settles that, and it is no licence to skip the read
|
|
2504
|
+
where they exist.
|
|
2505
|
+
4. Report you the label, the deferral issue numbers — a
|
|
2506
|
+
`filed: #N <subject>` line for every issue duty 2 created, and
|
|
2507
|
+
`unrecorded: #N <subject>` for one whose `filed` failed twice — and anything
|
|
2508
|
+
it halted on — cause and evidence, below, never a bare "head moved". The
|
|
2509
|
+
cause is one word of the ledger's `halted:<cause>` vocabulary:
|
|
2510
|
+
`live-editor`, `rebase` or `past-pin` from the cause block below,
|
|
2511
|
+
`unreadable`, `missing` or `absent` from duty 1's row shapes, and `other`
|
|
2512
|
+
for every other halt — the block's *anything else*, and a halt at duty 2,
|
|
2513
|
+
duty 3, the instrument re-check or the CI gate. A `rebase` halt's report
|
|
2514
|
+
carries the output of `git cherry <pin> HEAD origin/main`, run in the
|
|
2515
|
+
worktree.
|
|
2516
|
+
|
|
2517
|
+
**Give the finisher the instrument re-check verbatim too.** Duty 1 and duty 2
|
|
2518
|
+
each run a script the digest covers — `worktree-audit.sh` and `ledger.mjs`,
|
|
2519
|
+
both under `plugin/scripts/` — and the label at duty 3 rests on what they
|
|
2520
|
+
returned. The rule is stated once, at the top of this file, which no finisher
|
|
2521
|
+
is dispatched to read, so it reaches one through this block or not at all:
|
|
2522
|
+
|
|
2523
|
+
> **Re-check the instrument set before you act on what duty 1 or duty 2 read,
|
|
2524
|
+
> and again before you add the label.**
|
|
2525
|
+
> `~/.fleet/bin/fleet-run instruments.sh --repo "$(dirname "$(env -u GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir)")"`.
|
|
2526
|
+
> Exit 0 is the only code that lets you go on. Exit 1 (the set changed) and
|
|
2527
|
+
> exit 2 (the check could not answer) both halt you: report what it printed,
|
|
2528
|
+
> add no label, and do NOT re-read the script that gave you the reading.
|
|
2529
|
+
> `--repo` is required and the spelling is the point — the run's baseline lives
|
|
2530
|
+
> in the audited checkout's gitignored `.fleet/`, which the scratch worktree
|
|
2531
|
+
> you take at duty 2 does not carry, so a bare invocation from there exits 2 on
|
|
2532
|
+
> a missing baseline instead of comparing anything. The `env -u GIT_DIR -u
|
|
2533
|
+
> GIT_WORK_TREE` wrapper guards against an ambient `GIT_DIR` in your own shell
|
|
2534
|
+
> pointing this check at the wrong tree — the script's own internal unset
|
|
2535
|
+
> cannot reach back and fix a path you already resolved wrong. The baseline
|
|
2536
|
+
> itself names the tree to audit: a cross-workspace run pinned it once at
|
|
2537
|
+
> phase 0, and your `--repo` only locates that baseline, never the audited
|
|
2538
|
+
> tree — so an exit 2 naming a moved or unreadable audited tree is a halt
|
|
2539
|
+
> like every other, not a spelling for you to correct.
|
|
2540
|
+
|
|
2541
|
+
**Once the label is on, take it off before you approve any push.** The label is a
|
|
2542
|
+
verdict on the tree the finisher read, and a GitHub label does not follow the
|
|
2543
|
+
branch — on #180 it survived a push and came to sit on a commit nobody had
|
|
2544
|
+
audited. Remove `ready-to-merge` *first*, then approve: removing the artifact the
|
|
2545
|
+
merge bot gates on is the reliable stop, where messaging the bot races it, and a
|
|
2546
|
+
label has been observed holding until after an abort message arrived. Then
|
|
2547
|
+
dispatch a **fresh** finisher against the new head; the first audit does not
|
|
2548
|
+
transfer, since it verified a different tree. The merge bot refuses that head on
|
|
2549
|
+
its own (`run-merge-bot.md`, **The labelled head**), so this is not the only
|
|
2550
|
+
guard — but its refusal costs a pass and leaves the label lying, which is yours
|
|
2551
|
+
to clear either way.
|
|
2552
|
+
|
|
2553
|
+
A halt at step 1 reads identical from a bare SHA mismatch whatever caused it,
|
|
2554
|
+
and the causes below are the ones seen so far, not a closed list. Give the
|
|
2555
|
+
finisher this verbatim, so it derives the cause itself instead of asking anyone:
|
|
2556
|
+
|
|
2557
|
+
> Worktree differs from your pin, or from what you last read. **Check
|
|
2558
|
+
> head-equality first: `worktree HEAD == the SHA you were dispatched against` on
|
|
2559
|
+
> a clean tree settles it.** Against your dispatch pin, never against
|
|
2560
|
+
> `PR headRefOid`: a member that kept working and pushed after the pin matches
|
|
2561
|
+
> the branch tip on a clean tree, so a headRefOid comparison reports "settled"
|
|
2562
|
+
> over commits no reviewer read — the exact divergence this halt exists to
|
|
2563
|
+
> catch. `headRefOid` is a second, separate read (pushed vs unpushed), never the
|
|
2564
|
+
> equality the halt turns on. A rebase entry sitting at or behind the pin is
|
|
2565
|
+
> that head's provenance — the implementer's own pre-push replay — not
|
|
2566
|
+
> divergence from it, and needs no adjudication at all. Three finishers in one
|
|
2567
|
+
> run adjudicated a reflog this one check had already answered. Only when the
|
|
2568
|
+
> head differs from your pin, work out what happened. Each cause below is cheap
|
|
2569
|
+
> and self-checkable, and `anything else` is a cause too, not a gap:
|
|
2570
|
+
>
|
|
2571
|
+
> - **Live editor.** `git status --porcelain -unormal` is dirty. Sample
|
|
2572
|
+
> `git diff --stat` twice, a minute apart — diffstat growing means someone
|
|
2573
|
+
> is still writing. Halt, name `live-editor`, report both samples.
|
|
2574
|
+
> - **Rebase.** `git status --porcelain -unormal` is clean, head still differs
|
|
2575
|
+
> from your pin. `git reflog` in the worktree: a `reset`/rebase entry near
|
|
2576
|
+
> the move, not a plain `commit`, means the branch replayed onto a new
|
|
2577
|
+
> base — its own commits on a new parent, content-identical only on a
|
|
2578
|
+
> conflict-free replay.
|
|
2579
|
+
> Halt, name `rebase`, report the reflog line and the output of
|
|
2580
|
+
> `git cherry <pin> HEAD origin/main`, run in the worktree.
|
|
2581
|
+
> - **Work past the pin.** `git status --porcelain -unormal` is clean, head
|
|
2582
|
+
> still differs from your pin, and `git reflog` in the worktree reads a plain
|
|
2583
|
+
> `commit` at the move — no `reset`/rebase entry there, any of those sitting
|
|
2584
|
+
> at or behind the pin as provenance. A member kept working and committed
|
|
2585
|
+
> after you were dispatched. Measured 2026-08-28 on #983, where the finisher
|
|
2586
|
+
> matched neither cause above and halted on its own judgement (#997).
|
|
2587
|
+
> Halt, name `past-pin`, and report **the commit, and whether it
|
|
2588
|
+
> is pushed, unpushed, or unknown**: `git log -1 --format='%h %s'` names it,
|
|
2589
|
+
> and `git ls-remote origin <branch>` answers the rest — a non-zero exit or
|
|
2590
|
+
> any other failed read is **unknown**, never folded into "unpushed": the
|
|
2591
|
+
> same rule `release-ticket.sh`'s own `ls-remote` names ("a failure here is
|
|
2592
|
+
> an unknown answer, never a 'no'") and `reaping.md`'s remote check shares
|
|
2593
|
+
> ("its failure is an unknown answer, never a 'not pushed'"). Only a
|
|
2594
|
+
> successful read settles pushed vs not: equal to that commit means pushed,
|
|
2595
|
+
> and a fresh finisher can audit it; a successful read that comes back
|
|
2596
|
+
> without it means the commit exists only in that worktree, where no
|
|
2597
|
+
> reviewer can reach it. Ask the remote, not the PR object, whose head lags
|
|
2598
|
+
> a ref move — the same field `run-merge-bot.md` refuses to poll, for that
|
|
2599
|
+
> reason. The controller's next move differs between pushed, unpushed, and
|
|
2600
|
+
> unknown, so a report naming only two of the three is not a report of this
|
|
2601
|
+
> cause.
|
|
2602
|
+
> - **Anything else.** Matching none of the above is not a licence to report
|
|
2603
|
+
> the mismatch as unexplained — that report is the one this block exists to
|
|
2604
|
+
> make unnecessary, and it is where labelling over a moved head starts
|
|
2605
|
+
> looking reasonable. Halt, name `other`, and name what you did find: both
|
|
2606
|
+
> `git status --porcelain -unormal` samples, the `git reflog` line at the
|
|
2607
|
+
> move, and both SHAs. A cause nobody has named yet is still a cause you
|
|
2608
|
+
> observed, and your report is what gets it named.
|
|
2609
|
+
>
|
|
2610
|
+
> Every cause halts, always — named or not, you never verify the dirt is
|
|
2611
|
+
> harmless and label over it, a rebase is not a fast-forward you get to accept,
|
|
2612
|
+
> a commit past the pin is not one either, and a cause you could not name is
|
|
2613
|
+
> the least settled of the lot. Naming the cause makes the halt cheap to
|
|
2614
|
+
> resolve, never a reason to skip it.
|
|
2615
|
+
|
|
2616
|
+
**Resolving a finisher halt.** A halt is the finisher working correctly — it
|
|
2617
|
+
refused to label — so it is never `failed`, which stays for a finisher that
|
|
2618
|
+
crashed or gave up. Record it `ledger.mjs settle finisher-pr-<M>=halted:<cause>`,
|
|
2619
|
+
`<cause>` the word the report names; the ledger refuses any other. Every halt
|
|
2620
|
+
escalates two ways: the cockpit flags the PR `halted:<cause>` at severity 4 off
|
|
2621
|
+
that token, and you post the finisher's halt report — cause and evidence — with
|
|
2622
|
+
`gh pr comment <M>`, so it outlives the run. **No label**: the missing
|
|
2623
|
+
`ready-to-merge` already keeps the PR out of the merge queue. Then the cause
|
|
2624
|
+
decides the rest — two resolve automatically, every other one escalates:
|
|
2625
|
+
|
|
2626
|
+
| Cause | Resolution |
|
|
2627
|
+
|---|---|
|
|
2628
|
+
| `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. |
|
|
2629
|
+
| `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, and its result reaches a fresh finisher through the same gate. |
|
|
2630
|
+
| `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. |
|
|
2631
|
+
| `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
|
|
2632
|
+
|
|
2633
|
+
`past-pin` needs the tick because the dead-review path cannot reach it: once a
|
|
2634
|
+
review has **returned**, its `reviewed=` token holds the PR out of `review-due=`,
|
|
2635
|
+
and settling that review `=failed` re-queues nothing — that path covers only a
|
|
2636
|
+
review that died before returning. A head that moved past `reviewed=` with no
|
|
2637
|
+
such halt — a fix-applier's push — stays not due: duty 2 verifies what it
|
|
2638
|
+
applied.
|
|
2639
|
+
|
|
2640
|
+
Gate on the `check` job, **not** on `ci-state --quiet` exit 0: a behind PR never
|
|
2641
|
+
reaches full green, so an exit-0 gate strands it unlabelled. The finisher reads
|
|
2642
|
+
per-job state (`ci-state.mjs` without `--quiet`, or its `jobs`), since `--quiet`
|
|
2643
|
+
drops `jobs` and `missing`. Normal path, not only kill-recovery.
|
|
2644
|
+
|
|
2645
|
+
**`ci-state.mjs` reads `verdict: "no-ci"`** — no `check` job exists in this repo
|
|
2646
|
+
to gate on, and that is not a third way to skip the wait. **The
|
|
2647
|
+
`--declare-no-ci` declaration is caller-side, and reading it back out of the
|
|
2648
|
+
payload verifies nothing**: the flag is echoed into `reasons` and flips the exit
|
|
2649
|
+
code, so re-running with it and finding it there confirms only that you passed
|
|
2650
|
+
it. Passing it yourself is not a second opinion. Check the two facts it stands
|
|
2651
|
+
for instead:
|
|
2652
|
+
|
|
2653
|
+
1. `ci-state.mjs` **without** the flag still reads `verdict: "no-ci"`. A repo
|
|
2654
|
+
whose CI is merely misconfigured — workflow files present under other names,
|
|
2655
|
+
or `.github/workflows/` unreadable — exits 2 there rather than reading no-ci,
|
|
2656
|
+
so this is the check that separates real absence from misconfiguration, the
|
|
2657
|
+
case that must never ship silently.
|
|
2658
|
+
2. The reviewer's own final verdict reports a green `testCmd` run on the SHA it
|
|
2659
|
+
pushed. `review-and-fix.md` step 3 requires it to, and that run is the only
|
|
2660
|
+
gate this repo actually has.
|
|
2661
|
+
|
|
2662
|
+
Both → add the label, and say it rests on the reviewer's suite run, not on CI.
|
|
2663
|
+
Either missing → halt here, same as a dirty worktree: report `no CI configured,
|
|
2664
|
+
no verified suite run on record` and add no label.
|
|
2665
|
+
|
|
2666
|
+
**Correction tickets ship new wrong claims — inherited from the ticket, and
|
|
2667
|
+
minted in prose the ticket never asked for.** Put the check on the
|
|
2668
|
+
**implementer**, not only the reviewer: every factual claim the diff restates
|
|
2669
|
+
must have a settling command run against the tree first — the issue body is a
|
|
2670
|
+
lead, never a citation — and the diff must **match the ticket's stated size**,
|
|
2671
|
+
since added prose is where minted claims enter. No positional references (`the
|
|
2672
|
+
closing/second/last X`); name the thing semantically. Evidence from a run on
|
|
2673
|
+
**another repo** is cited by host: a github.com source as `owner/repo#N`;
|
|
2674
|
+
anything else (GHE, GitLab, internal) as prose naming host and repo and saying
|
|
2675
|
+
it cannot be settled from this repo — a bare `#N` stays bare only for this
|
|
2676
|
+
repo's own issues and PRs. The workflow's `comments`
|
|
2677
|
+
dimension checks every added assertion against the tree, including comments in
|
|
2678
|
+
files the diff does not touch; a fallback reviewer has to be told that *and* told
|
|
2679
|
+
to read each corrected sentence literally, clause by clause.
|
|
2680
|
+
See references/correction-tickets.md.
|
|
2681
|
+
|
|
2682
|
+
**But the discipline follows the DIFF, not the class — hand it to any
|
|
2683
|
+
implementer whose diff writes prose.** Phase 2 selects it on `class=correction`,
|
|
2684
|
+
and that selection is too narrow: a `routine` ticket that adds a test fixture, a
|
|
2685
|
+
helper, or a coverage case writes comment prose too, and prose is where minted
|
|
2686
|
+
claims live. Measured twice in one run, both `class=routine`, both therefore
|
|
2687
|
+
dispatched WITHOUT this block: PR #756 added an unasked-for comment asserting a
|
|
2688
|
+
silent-failure mode that does not exist (gross PATH damage is loud — 10 of 39
|
|
2689
|
+
tests red), and PR #768 minted a false comparative ("the cheapest of the four to
|
|
2690
|
+
tear down, not the dearest", when its route is the only one of four needing any
|
|
2691
|
+
in-body teardown) **and** introduced two positional references replacing a
|
|
2692
|
+
name-based one. Neither ticket asked for either sentence.
|
|
2693
|
+
|
|
2694
|
+
Two of the rules above are what caught both, so give them to every implementer
|
|
2695
|
+
regardless of class: **every factual claim the diff restates needs a settling
|
|
2696
|
+
command first**, and **no positional references**. A third earns its place here
|
|
2697
|
+
— **never write a COUNT or a tally into prose; state the property instead** —
|
|
2698
|
+
unless it is a past-tense record of a measurement you performed, which stays
|
|
2699
|
+
as written; a present-tense claim about a live property must be restated as a
|
|
2700
|
+
property (`every other test in the file`), true at any count. A
|
|
2701
|
+
count is false the moment the next commit lands, and #768 falsified two of them
|
|
2702
|
+
(`the only other chmodSync(..., 0o644)`, already off by one before it; `fails 75
|
|
2703
|
+
of the 85 cases`, measured 81 of 91) in a file whose own header records having
|
|
2704
|
+
shipped a stale count once already. The immutable-body rule earns the same
|
|
2705
|
+
place: **every claim a commit body or a PR body asserts needs its settling
|
|
2706
|
+
command re-run at the commit that ships it, and written inline beside it.**
|
|
2707
|
+
The literal-text `-F` rule earns the same place: **a settling command over
|
|
2708
|
+
literal text uses `grep -F`, and its zero counts only after the same
|
|
2709
|
+
command, with the same flags, finds a line known to match.** Measured on
|
|
2710
|
+
#1087, the same false zero fired twice in one run. A relayed enumeration
|
|
2711
|
+
delivers only what it names, so this list is the whole of what a controller
|
|
2712
|
+
hands over, never a preface to it.
|
|
2713
|
+
|
|
2714
|
+
**One more rule, and the one the diff cannot carry: a claim written into a
|
|
2715
|
+
commit body or a PR body needs its settling command re-run at the commit that
|
|
2716
|
+
ships it, not at the commit that motivated it — and the command goes inline,
|
|
2717
|
+
beside the claim.** The rules above scope to prose the diff restates, and a
|
|
2718
|
+
pushed commit body is not in the diff: it cannot be edited, only retracted by a
|
|
2719
|
+
later commit, which is itself a fresh unverified historical claim. So the check
|
|
2720
|
+
has to sit at write time, and review-time is already too late. The claim types
|
|
2721
|
+
are wider than measurement — a line number, a SHA, an **attribution** of who
|
|
2722
|
+
said what, a positional reference and a count all rot the same way, and an
|
|
2723
|
+
attribution is the worst of them, because the argument it carries collapses
|
|
2724
|
+
when it turns out false, while a wrong line number leaves the surrounding
|
|
2725
|
+
reasoning standing. `Verified:` is the construct a later reader trusts
|
|
2726
|
+
*instead of* re-deriving, so a wrong figure under that header is worse than no
|
|
2727
|
+
figure at all. Measured on #399: `f961cf2` and `acce6ee` both close `Verified:`
|
|
2728
|
+
with `86/86 across both test files` naming the suites that read this file, a
|
|
2729
|
+
file set the tree does not bear out — `git log -1 --format=%b <sha> | grep -A2
|
|
2730
|
+
Verified:` shows what each shipped. Inline is what makes the difference visible:
|
|
2731
|
+
a claim carrying the command that produces it can be re-run instead of trusted.
|
|
2732
|
+
A claim whose settling command cannot be written is still not one to assert
|
|
2733
|
+
bare: settle it inline, mark it unsettleable from this repo per the citation
|
|
2734
|
+
convention above, or drop it. The marker ending is not a loophole but the case
|
|
2735
|
+
that convention already sanctions: it directs foreign evidence to be asserted as
|
|
2736
|
+
prose saying it cannot be settled from this repo, and that marker is itself what
|
|
2737
|
+
tells a later reader not to trust the claim instead of re-deriving it, which is
|
|
2738
|
+
the property this rule protects.
|
|
2739
|
+
|
|
2740
|
+
**The settling command for "which files read X" must never be a literal-path
|
|
2741
|
+
grep.** The path is assembled in more than one spelling here, one of them behind
|
|
2742
|
+
a local `read` helper, so a grep for the path string answers with the files that
|
|
2743
|
+
merely *name* it — comments included — and misses the files that build it.
|
|
2744
|
+
Replace the file with `MUTATED` in a throwaway copy, run the suite, and read off
|
|
2745
|
+
which suites red: that answers which ones **depend on its contents**, which is
|
|
2746
|
+
the question a coverage claim actually needs, and it returns a different set
|
|
2747
|
+
from any spelling of the grep.
|
|
2748
|
+
|
|
2749
|
+
**A settling command over literal text uses `grep -F`, and its zero counts only
|
|
2750
|
+
after the same command finds a line known to match.** Prose fragments and
|
|
2751
|
+
code snippets routinely carry `\`, `.`, `*`, `[` or `$`, and without `-F` those
|
|
2752
|
+
are read as a pattern rather than as the text itself, so the command answers
|
|
2753
|
+
for a different string from the one the claim names — and a wrong zero is the
|
|
2754
|
+
benign-looking answer. Measured on #1087: `grep -c 'settled by:\s+x'` answers
|
|
2755
|
+
0 against a file holding that exact line, and `grep -cF` answers 1. A zero or
|
|
2756
|
+
an absence counts only after the same command, with the same flags, finds a
|
|
2757
|
+
line known to match: a command that cannot find a match settles nothing, and
|
|
2758
|
+
under `Verified:` its zero reads as a checked absence.
|
|
2759
|
+
|
|
2760
|
+
#### Fallback: hand-dispatched reviewer member
|
|
2761
|
+
|
|
2762
|
+
Only where the review unit is unavailable **or has failed** — never a
|
|
2763
|
+
preference. "Unavailable" is the review unit not being there to dispatch at
|
|
2764
|
+
all; "failed" is the failure event above, surviving its one retry. A review that
|
|
2765
|
+
is present and failing is not absent, and reading this line as absence-only
|
|
2766
|
+
leaves the likeliest failure with no sanctioned path at all. One named member
|
|
2767
|
+
per PR — `review-pr-<pr#>`, or `review-pr-<pr#>-b` where a runner already held
|
|
2768
|
+
that name — never its implementer, recorded as
|
|
2769
|
+
`review=fallback:review-pr-<pr#>[-b]` on the PR's row. It runs off your turn
|
|
2770
|
+
like the review it replaces. Give it the PR number and tell it to read
|
|
2771
|
+
`$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` — the resolved file
|
|
2772
|
+
path, not a slash invocation; command availability inside a member is not
|
|
2773
|
+
guaranteed the way skill availability is. It then does the fix-applier's job too:
|
|
2774
|
+
apply, defer, file, push, report, exit. On its report, record
|
|
2775
|
+
`reviewed=<head>:0/<refuted>/<deferred>` against the head it pushed — it applied
|
|
2776
|
+
its own survivors, so the zero is what tells the tick no fix-applier is owed —
|
|
2777
|
+
and it reaches a finisher through the same gate as any other PR.
|
|
2778
|
+
|
|
2779
|
+
**Authorize the fan-out explicitly.** State that the full specialist set IS the
|
|
2780
|
+
requested work — otherwise the reviewer inherits the standing "do not call the
|
|
2781
|
+
AgentTool unless requested" and silently downgrades to a thinner solo review.
|
|
2782
|
+
Nothing computes the count here, so apply the heuristic yourself: two or three
|
|
2783
|
+
specialists for annotation-only or single-file, the full set for production code.
|
|
2784
|
+
See references/member-lifecycle.md.
|
|
2785
|
+
|
|
2786
|
+
**Delivering specialist reports is your duty on this path, not the reviewer's.**
|
|
2787
|
+
Reports surface to *you* and grandchildren are unaddressable, so a reviewer must
|
|
2788
|
+
never be told to ping for one. But it **can** read the report itself: a specialist
|
|
2789
|
+
it spawned writes its transcript to the output file named in its spawn result, and
|
|
2790
|
+
`tail -1 <file> | jq -r '.message.content[]?|select(.type=="text").text'`
|
|
2791
|
+
extracts the final report — bounded, unlike reading the whole file. State that in
|
|
2792
|
+
the prompt: retrieve first, ask you by name only if the file yields nothing, and
|
|
2793
|
+
rule a dimension **unrun** only when neither works — not silently, and not after
|
|
2794
|
+
waiting forever, since a killed specialist never reports and never gets relayed.
|
|
2795
|
+
See references/member-lifecycle.md.
|
|
2796
|
+
|
|
2797
|
+
So two obligations enter the event loop for as long as a hand-dispatched reviewer
|
|
2798
|
+
is live:
|
|
2799
|
+
|
|
2800
|
+
- **A specialist report lands** (a task-notification from a grandchild you never
|
|
2801
|
+
dispatched) → **relay it to the reviewer that owns the PR — source named, text
|
|
2802
|
+
included.** Relay anyway even though the reviewer can retrieve it itself — a
|
|
2803
|
+
duplicate costs nothing, a missed report costs a verdict. Telling it to ping the
|
|
2804
|
+
specialist does not work either — a depth-2 member cannot dispatch
|
|
2805
|
+
further, so the reviewer has no path to its own un-nameable children
|
|
2806
|
+
beyond reading their output file.
|
|
2807
|
+
- **A reviewer's verdict claims a dimension went undelivered** → reconcile it
|
|
2808
|
+
against your relay receipts before accepting it. Receipts say relayed → re-send
|
|
2809
|
+
naming the specialist and hold that verdict until it lands; a relay can arrive
|
|
2810
|
+
after a verdict is already composed. Only you hold the msg id, so only you can
|
|
2811
|
+
catch this — the reviewer cannot tell "no report exists" from "one was sent that
|
|
2812
|
+
I have not received". One reviewer ruled a relayed dimension "not covered by a
|
|
2813
|
+
specialist" and shipped a headline claim that report refuted.
|
|
2814
|
+
|
|
2815
|
+
Neither belongs in a workflow-path prompt: there `agent()` returns into the
|
|
2816
|
+
script, no relay ever occurs, and a rule to wait for one strands every finding.
|
|
2817
|
+
|
|
2818
|
+
**Same receipts gate the finisher dispatch** — dispatch only once every
|
|
2819
|
+
specialist report you know landed for this PR is relayed, none unrelayed. The
|
|
2820
|
+
reviewer applies findings and pushes as each relay lands, so an
|
|
2821
|
+
unrelayed report is exactly as inbound as a fix-applier ruling you haven't sent
|
|
2822
|
+
(above) — dispatch past it and you pin a SHA the reviewer is about to move past.
|
|
2823
|
+
Necessary, not sufficient — a reviewer re-reading its own inbox late still moves
|
|
2824
|
+
the head, which is what the halt block's cause list above is for.
|
|
2825
|
+
Vacuous on the workflow path: `agent()` already returned every report before
|
|
2826
|
+
you had a tree to dispatch a finisher against, so nothing is ever outstanding
|
|
2827
|
+
there.
|
|
2828
|
+
|
|
2829
|
+
### Merge bot
|
|
2830
|
+
|
|
2831
|
+
Per pass, named `merge-bot-<n>`, never two at once. `ledger.mjs dispatch
|
|
2832
|
+
merge-bot` names it before the dispatch call — `n` is 1 + the `merge-bot-`
|
|
2833
|
+
entries already in the ledger's `## Dispatched` list, so it restarts at 1 every
|
|
2834
|
+
run, a replacement for a dead bot takes the next `n`, and nobody counts. Dispatch
|
|
2835
|
+
it on the tick's `DISPATCH merge-bot`: the first `ready-to-merge` label is
|
|
2836
|
+
enough, and it never waits for the finisher's report. Tell it to read
|
|
2837
|
+
`$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
|
|
2838
|
+
pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
|
|
2839
|
+
for late labels, then report once and exit — and say that you dispatched it,
|
|
2840
|
+
which is what makes it hold that grace instead of arming its own watcher. **Dispatch
|
|
2841
|
+
it by its own definition and omit `model` on the call** — the tier (`haiku`)
|
|
2842
|
+
lives in `agents/fleet-merge-bot.agent.md`:
|
|
2843
|
+
|
|
2844
|
+
`fleet-merge-bot`.
|
|
2845
|
+
|
|
2846
|
+
Rebase, wait for green, check the
|
|
2847
|
+
label, merge is checklist work, and a bad merge still needs the label and the
|
|
2848
|
+
per-job CI state to have been read correctly, which is exactly what a wrong
|
|
2849
|
+
merge later surfaces and a human resolves; `no-undo-audit.sh` is the
|
|
2850
|
+
deterministic, script-driven backstop run before every push specifically to
|
|
2851
|
+
catch a wrongly-resolved conflict, so the tier buys nothing that backstop
|
|
2852
|
+
doesn't already cover.
|
|
2853
|
+
|
|
2854
|
+
**Put the shell traps in the bot's brief, not in a follow-up message.** A bot
|
|
2855
|
+
already looping cannot be corrected — the loop consumes the turns a correction
|
|
2856
|
+
would land in. **Every entry in Shell traps, verbatim** — that section is where
|
|
2857
|
+
they are stated once, and this is the seat that has to paste them: the bot
|
|
2858
|
+
reads an exit code off `gh pr update-branch`, `merge-gate.mjs` and
|
|
2859
|
+
`prove-merge.sh`, which is the `PIPESTATUS` and read-only-`status` pair, and its
|
|
2860
|
+
grace poll captures `gh pr list` output and loops over it, which is the
|
|
2861
|
+
assigned-variable trap. The brief always travels with the dispatch.
|
|
2862
|
+
|
|
2863
|
+
**Its merge gate is one script, run twice.** Step 3 of `run-merge-bot.md` is
|
|
2864
|
+
`merge-gate.mjs --pr <n> --pre <sha> [--post <sha>]`: read-only, it runs the
|
|
2865
|
+
instrument re-check, the label and review-decision read and a run-bound
|
|
2866
|
+
`ci-state`, and answers their conjunction — exit 0 mergeable, 1 blocked (the
|
|
2867
|
+
bot reports `<reason>-#<pr>`), 2 could not evaluate. The bot runs it once
|
|
2868
|
+
before any CI wait and again immediately before `gh pr merge`, and merges only
|
|
2869
|
+
on that second exit 0. Nothing but the gate reads `ci-state` on the merge path,
|
|
2870
|
+
so a bot's report names the gate's `reason`, never a field it read by hand.
|
|
2871
|
+
|
|
2872
|
+
**You own the watcher, not the bot.** A dying member takes a watcher down with it
|
|
2873
|
+
and the queue stops silently. Arm one yourself, `persistent: true`, seeded before
|
|
2874
|
+
the loop so handled PRs do not re-fire.
|
|
2875
|
+
|
|
2876
|
+
**Every merge invalidates every other open PR, silently.** The rest show *stale
|
|
2877
|
+
green* until something re-triggers, then flip to `rebase-check: FAILURE` with the
|
|
2878
|
+
slow jobs skipped. Behind-count is the only honest signal.
|
|
2879
|
+
See references/ci-and-staleness.md.
|
|
2880
|
+
|
|
2881
|
+
**One rebase per PR, at merge time.** The bot establishes currency once, when the
|
|
2882
|
+
PR is the merge candidate; requiring it earlier costs a full CI cycle per sibling
|
|
2883
|
+
merge. Any behind-count you hand a bot is expired on arrival; say so. See
|
|
2884
|
+
references/ci-and-staleness.md.
|
|
2885
|
+
|
|
2886
|
+
`run-merge-bot.md` carries the mechanics — intra-pass re-checks, run-binding, the
|
|
2887
|
+
ancestry proof, post-rebase red triage. Do not restate them here.
|
|
2888
|
+
|
|
2889
|
+
### Reap after each merge pass
|
|
2890
|
+
|
|
2891
|
+
A merge deletes the remote branch and leaves the local branch `[gone]` with its
|
|
2892
|
+
worktree — and its `node_modules` — still on disk. Reap after **each** merge pass,
|
|
2893
|
+
not once at the end: a stale worktree still answers `git worktree list`, so the
|
|
2894
|
+
in-flight probe (`inflight.sh`, run by the Shortlist and by every Pull) reads an
|
|
2895
|
+
already-merged ticket as taken and the queue quietly shrinks. The trigger is the
|
|
2896
|
+
bot's one exit report, and it reaps every time — a pass that merged nothing
|
|
2897
|
+
included (phase 3, **Merge-bot pass reports done**). See references/reaping.md.
|
|
2898
|
+
|
|
2899
|
+
`~/.fleet/bin/fleet-run reap.sh --apply` recomputes every precondition
|
|
2900
|
+
inside the same invocation as the delete — `for-each-ref` for `[gone]`, `git
|
|
2901
|
+
cherry origin/main` to authorize `-D`, worktree removal without `--force` — and
|
|
2902
|
+
reports reaped and kept-with-reason counts. Update the reaped tickets' ledger rows
|
|
2903
|
+
in the same step. See references/reaping.md.
|
|
2904
|
+
|
|
2905
|
+
**It sweeps detached worktrees too — the shape a `[gone]` walk structurally
|
|
2906
|
+
cannot see.** Bounded to `.worktrees/`, so a checkout of yours outside it is
|
|
2907
|
+
reported, never removed. Read `worktreesRemoved` alongside `reaped`: a pass that
|
|
2908
|
+
reaps branches and removes no worktrees is a finding, not a quiet success.
|
|
2909
|
+
See references/reaping.md.
|
|
2910
|
+
|
|
2911
|
+
**Do not invoke `commit-commands:clean_gone`.** It runs `git branch -D` and
|
|
2912
|
+
`git worktree remove --force` with no merged check at all — nothing there stops it
|
|
2913
|
+
deleting a branch, or discarding a member's uncommitted work, that exists nowhere
|
|
2914
|
+
else. The skill is the maintainer's to fix; do the reap yourself.
|
|
2915
|
+
See references/reaping.md.
|
|
2916
|
+
|
|
2917
|
+
**Never reap a branch a live member is on.** Cross-check `.fleet/ledger.md` first:
|
|
2918
|
+
a row without a terminal state means someone may still be in that worktree, and
|
|
2919
|
+
the dirty check does not see a member that committed but has not pushed.
|
|
2920
|
+
See references/reaping.md.
|
|
2921
|
+
|
|
2922
|
+
### Release the claims that never became PRs — at end of run, and on drain
|
|
2923
|
+
|
|
2924
|
+
Phase 1 is serial and claims ahead of dispatch, so a ticket can be legitimately
|
|
2925
|
+
claimed and then never sent: a collision surfaces after the claim, or the
|
|
2926
|
+
maintainer says drain. The claim still holds the `in-progress`
|
|
2927
|
+
label, a worktree and a branch, and **`reap.sh` will not take them** — the branch
|
|
2928
|
+
is not `[gone]` and has no unique commits, so it is correctly not reapable. Reaping
|
|
2929
|
+
fires after each merge pass and nothing fires at end of run, so the claim survives
|
|
2930
|
+
it and the in-flight probe reads a free ticket as taken next run. Same silent queue
|
|
2931
|
+
shrink as a stale merged worktree, from the opposite end.
|
|
2932
|
+
|
|
2933
|
+
`~/.fleet/bin/fleet-run release-ticket.sh <N> impl-<N> implementer --apply` —
|
|
2934
|
+
the pair the claim took, so the two name the same branch and worktree — is the
|
|
2935
|
+
inverse of the claim, and recomputes its preconditions inside the same
|
|
2936
|
+
invocation as the delete: 0 commits ahead of `origin/main`, no unique commits
|
|
2937
|
+
(`git cherry`), no branch on `origin`, and — whenever the worktree directory is
|
|
2938
|
+
there to read — a clean worktree. Where that directory is established absent the
|
|
2939
|
+
dirty check does not run at all, and `git worktree remove` is no backstop for it:
|
|
2940
|
+
it gates its own clean check on the same `stat`, so the script's absence
|
|
2941
|
+
measurement is sole arbiter there. Two of the four are recomputed a second time
|
|
2942
|
+
at the delete itself: the dirty check by git, which is what `worktree remove`
|
|
2943
|
+
without `--force` is; and the ahead count, re-run against `origin/main`
|
|
2944
|
+
immediately before the branch delete, because a commit can land across the
|
|
2945
|
+
`gh issue view` between the checks and the delete. The `git cherry` and
|
|
2946
|
+
pushed-branch checks are **not** re-run there — a commit landing in that window
|
|
2947
|
+
is ahead of `origin/main` by construction, so the recount covers it. All clear →
|
|
2948
|
+
drops the label, removes the worktree without `--force`, deletes the branch with
|
|
2949
|
+
`-D`, authorized by those two commit checks plus the recount and by nothing else
|
|
2950
|
+
(`-d` measures against local HEAD, and a claim has no upstream, so it refuses a
|
|
2951
|
+
pristine claim whenever local `main` is behind `origin/main` — #760). Any one of
|
|
2952
|
+
them failing → it touches nothing and names the blocker. **That refusal is the
|
|
2953
|
+
finding, never an obstacle**: a claim carrying commits or a pushed branch is not
|
|
2954
|
+
auto-released, ever — run `worktree-audit.sh` (it audits every worktree; find
|
|
2955
|
+
this claim's row in the output) and decide by hand.
|
|
2956
|
+
|
|
2957
|
+
Run it over every claimed ticket with no PR when the run ends or the maintainer
|
|
2958
|
+
drains, and on the spot for a claim abandoned mid-run (a bail before
|
|
2959
|
+
implementing, a collision found after the claim). Update the released tickets'
|
|
2960
|
+
ledger rows in the same step. See references/reaping.md.
|
|
2961
|
+
|
|
2962
|
+
## Worktree and claim model
|
|
2963
|
+
|
|
2964
|
+
Ruled on #1315, measured 2026-09-09 in a throwaway clone (`/tmp/fleet-probe`)
|
|
2965
|
+
that never touched the real checkout.
|
|
2966
|
+
|
|
2967
|
+
**Claim, release and reap are unchanged on omp.** `claim-ticket.sh`,
|
|
2968
|
+
`release-ticket.sh`, `reap.sh` and `inflight.sh` are git-native and operate on
|
|
2969
|
+
the single shared ref store every worktree and the main checkout read and
|
|
2970
|
+
write directly (**Phase 1**, **Reap after each merge pass**, **Release the claims
|
|
2971
|
+
that never became PRs** above); nothing in omp's `task` model touches that
|
|
2972
|
+
store, so none of the four scripts carries a dialect branch.
|
|
2973
|
+
|
|
2974
|
+
**A fleet member is never dispatched with omp's `isolated: true`.** Measured:
|
|
2975
|
+
an isolated spawn builds its workspace under `~/.omp/wt/<hash>/m` — an APFS
|
|
2976
|
+
clone (on this box), never a registered `git worktree` of the repo — and,
|
|
2977
|
+
because `apply` defaults to `true`, its changes are patch-applied into the
|
|
2978
|
+
**calling session's own cwd** the instant the spawn completes: a file an
|
|
2979
|
+
isolated probe created there appeared as `?? probe-isolated.txt` in the probe
|
|
2980
|
+
session's own cwd — which for an actual fleet run is the controller's main
|
|
2981
|
+
checkout — not in the worktree the prompt named. That is the exact
|
|
2982
|
+
silent-spill hazard this section exists to guard against, on by default, so
|
|
2983
|
+
`isolated` stays unused for every member and `task.isolation.enabled` stays
|
|
2984
|
+
off.
|
|
2985
|
+
|
|
2986
|
+
**A member's tree is the claimed worktree, addressed by absolute path.** An
|
|
2987
|
+
`edit` header without the worktree prefix resolves into the main checkout,
|
|
2988
|
+
where `member-write-guard` refuses it (**You read your instruments out of a
|
|
2989
|
+
tree every member can write to** above). How a
|
|
2990
|
+
member gets its cwd: the `task` tool's item schema — `name`/`agent`/`task`/
|
|
2991
|
+
`outputSchema`/`schemaMode` always, `effort`/`isolated` only when their own
|
|
2992
|
+
settings enable them — carries no working-directory field; measured
|
|
2993
|
+
directly: a member dispatched through it with none of those fields, told
|
|
2994
|
+
only to report `pwd`, returned the calling session's own cwd, not the
|
|
2995
|
+
claimed worktree, the same output an un-`cwd`-set `bash` call gives from
|
|
2996
|
+
that session, so the recipe is the dispatch-prompt absolute path, plus
|
|
2997
|
+
`bash`'s own `cwd` parameter set to it on every call and absolute paths for
|
|
2998
|
+
`write`/`edit`.
|
|
2999
|
+
|
|
3000
|
+
**The one open gap this ticket measured: `task` does not accept a per-dispatch
|
|
3001
|
+
working directory.** `omp://tools/task.md` documents non-isolated spawns as
|
|
3002
|
+
running `runSubprocess(...)` "directly with parent cwd" — no `cwd` field
|
|
3003
|
+
appears anywhere in the item schema — and the probe above confirms it in
|
|
3004
|
+
practice: the recipe is the absolute-path discipline above, not a placeholder
|
|
3005
|
+
for a `cwd` field that does not exist. The gap is now enforced rather than only
|
|
3006
|
+
written down: the plugin's `member-write-guard` omp extension (ADR 0020)
|
|
3007
|
+
refuses a fleet member's `write`/`edit`/`ast_edit` into the main checkout's
|
|
3008
|
+
non-ignored tree and an implementer's `bash` from a main-checkout cwd, and the
|
|
3009
|
+
missing field itself is requested upstream as can1357/oh-my-pi#13754.
|
|
3010
|
+
|
|
3011
|
+
**The same gap reaches past the filesystem: `task`-dispatched members share one
|
|
3012
|
+
`eval` kernel.** Measured 2026-09-21 on #1447, in a live run rather than a
|
|
3013
|
+
probe clone: two sibling implementers dispatched in the same batch, and the
|
|
3014
|
+
controller that dispatched both, reported the same Python kernel pid and the
|
|
3015
|
+
same runner file under `$TMPDIR/omp-python-runner/`, and each read the others'
|
|
3016
|
+
top-level bindings out of its own `eval` cell — a bare `WT` bound by one member
|
|
3017
|
+
was read back by a sibling and by the controller, the collision #1447 was filed
|
|
3018
|
+
on as an unproven self-report. `omp://tools/eval.md` states the mechanism:
|
|
3019
|
+
retained kernels are keyed by `python:${sessionId}`, normalized cwd and
|
|
3020
|
+
interpreter — `js:${sessionId}` for the JS VM — and "Parent and ordinary task
|
|
3021
|
+
subagents may share an inherited eval executor id; children created by eval's
|
|
3022
|
+
own `agent()` explicitly do not." Neither key component separates two members
|
|
3023
|
+
of one run: the session id is inherited from the controller, and the cwd is the
|
|
3024
|
+
main checkout for all of them, because `eval`, unlike `bash`, takes no `cwd`
|
|
3025
|
+
parameter to set. So the absolute-path discipline above is load-bearing inside
|
|
3026
|
+
`eval` too, and it needs one rule `write`/`edit` do not — member-prefixed
|
|
3027
|
+
binding names, since a shared global has no path to be absolute about. The
|
|
3028
|
+
corollary is `reset`: it "is likewise destructive to concurrent work sharing
|
|
3029
|
+
that backend session", so a member resetting its own kernel resets every
|
|
3030
|
+
concurrent sibling's. No per-dispatch knob turns any of this off: `task`'s item
|
|
3031
|
+
shape carries no kernel, executor or cwd field, and `python.kernelMode` set to
|
|
3032
|
+
`"per-call"` — the one documented lever that would hand every call a fresh
|
|
3033
|
+
kernel — is a session setting a child inherits, not something one dispatch can
|
|
3034
|
+
set for one member. Isolating a member's kernel is an omp-side change, so
|
|
3035
|
+
discipline is the whole of the remedy here — unlike the missing `cwd` field
|
|
3036
|
+
above, which `member-write-guard` enforces for `write`/`edit`/`ast_edit` and
|
|
3037
|
+
`eval` bypasses. **Phase 2** carries all three rules to every member.
|
|
3038
|
+
|
|
3039
|
+
**`release-ticket.sh` is not a no-op on omp, and `inflight.sh`'s probes are
|
|
3040
|
+
unaffected by a running member.** Measured against a hand-built claim (a
|
|
3041
|
+
branch plus a `git worktree add`) with a member sleeping inside it: a `bash`
|
|
3042
|
+
call with `cwd` set to the worktree, and a non-isolated `task` spawn told to
|
|
3043
|
+
work there, both operate inside the existing worktree and leave `git worktree
|
|
3044
|
+
list` unchanged — they coexist with the claim rather than duplicating it. An
|
|
3045
|
+
isolated spawn is architecturally blind to the worktree — its relative writes
|
|
3046
|
+
land in its own `~/.omp/wt/…` workspace regardless of the prompt — but it
|
|
3047
|
+
neither removes nor hides the claim, and `~/.omp/wt/` was empty after every
|
|
3048
|
+
isolated run: omp's own teardown touches only omp's own workspace, never the
|
|
3049
|
+
claim. `release-ticket.sh`'s three-artifact teardown (label, worktree, branch)
|
|
3050
|
+
is therefore still necessary. With the member live inside
|
|
3051
|
+
the worktree, `git worktree list` and `git branch --list` from the main
|
|
3052
|
+
checkout reported the claim unchanged before, during and after — `inflight.sh`
|
|
3053
|
+
hides nothing from omp.
|
|
3054
|
+
|
|
3055
|
+
**The controller's own cwd stays the main checkout, unchanged.** Nothing in
|
|
3056
|
+
this section's dispatch recipe — the cwd recipe above, the isolated-workspace
|
|
3057
|
+
measurement, or the teardown scoping — moves
|
|
3058
|
+
where the controller itself runs from.
|
|
3059
|
+
|
|
3060
|
+
## Queue depth
|
|
3061
|
+
|
|
3062
|
+
- **shortlist** — `.fleet/shortlist.json`'s entries with no `impl-` row and no
|
|
3063
|
+
live `excluded` row: admissible, not yet pulled. The tick's `unclaimed=`.
|
|
3064
|
+
- **supply** — `scanned`, the open `ready-for-agent` tickets `shortlist.mjs`'s
|
|
3065
|
+
candidate scan returned, before any filter. Only a Pull's full read judges
|
|
3066
|
+
decided?, so a shortlist of undecided tickets is supply that every Pull
|
|
3067
|
+
relabels away — and relabelling is what stops it being counted next scan.
|
|
3068
|
+
- **review backlog** — PRs owed a review. `fleet-tick.mjs` counts every
|
|
3069
|
+
open PR without `ready-to-merge` **that closes an issue** and carries no `review=`
|
|
3070
|
+
token on the ledger — one settled `=failed` is owed a review again, and so is
|
|
3071
|
+
one whose latest finisher halted `past-pin` past its latest `reviewed=` head
|
|
3072
|
+
(**Resolving a finisher halt**) — and it
|
|
3073
|
+
prints them as `review-due=`. Exact, not a wider read: the ledger records
|
|
3074
|
+
which PRs are under review or reviewed, so nothing about it is guesswork. The
|
|
3075
|
+
closing-issue test is what keeps it from widening: a chore PR you author
|
|
3076
|
+
yourself closes nothing and is left unlabelled for the maintainer, so no
|
|
3077
|
+
member of the fleet will ever review it, and counting it floors the backlog at
|
|
3078
|
+
a depth nothing in the run can drain — the implementer gate then holds for the
|
|
3079
|
+
rest of the run against a queue of nothing (#590). GitHub's own linked-issue
|
|
3080
|
+
set decides that, not a keyword regex over the body; see
|
|
3081
|
+
`docs/agents/issue-tracker.md`. **That exemption is for the chore PR THIS run
|
|
3082
|
+
authors, never one a PRIOR run left open** — step 0 folds those into this
|
|
3083
|
+
run's review queue, so count one when you reason about backlog BY HAND. **The
|
|
3084
|
+
`fleet-tick.mjs` number still excludes it**: nothing in its filter
|
|
3085
|
+
distinguishes an inherited chore PR from this run's own, since a PR closing no
|
|
3086
|
+
issue fails the closing-issue test either way — folding one in cannot reach
|
|
3087
|
+
the count. So the by-hand judgement and the script's output differ here, and
|
|
3088
|
+
such a PR's review is dispatched by hand.
|
|
3089
|
+
|
|
3090
|
+
**Defaults: 2 implementers, 6 reviewers — no hard cap on either.** Reviewer
|
|
3091
|
+
slots in use ≈ I·(T_review + 0.94·T_fix)/T_impl ≈ 1.95·I (spec 2026-09-24 § 3
|
|
3092
|
+
§3, medians since 2026-08-07: T_impl 19.3 min, T_fix 21.0 min, T_review ~18
|
|
3093
|
+
min, 0.94 fix-appliers per review), so at the default about four of the six
|
|
3094
|
+
are busy, and an idle slot costs nothing. Re-derive it from the map's guard
|
|
3095
|
+
once 20 or more PRs have merged under it, never from one run's rows.
|
|
3096
|
+
|
|
3097
|
+
**The review-backlog gate is narrowed, and the merge-queue depth never gates.**
|
|
3098
|
+
More PRs into a review-bound pipeline buy nothing, but the pipeline is
|
|
3099
|
+
review-bound only when a PR is still owed its review after the tick's own
|
|
3100
|
+
dispatches AND no reviewer slot is left for it — `HOLD (review side
|
|
3101
|
+
saturated)`. A deep backlog with free slots is a `DISPATCH review` on the same
|
|
3102
|
+
tick, never a reason to idle an implementer. A deep `ready-to-merge` queue is
|
|
3103
|
+
*not* that signal at all: each PR rebases exactly once, when it becomes the
|
|
3104
|
+
candidate, so producing more PRs adds no rebases-per-PR — it changes only
|
|
3105
|
+
*when* a given PR is ready.
|
|
3106
|
+
|
|
3107
|
+
**Reconcile, do not wait for an event.** "A slot is free and the shortlist is
|
|
3108
|
+
non-empty" is a *level* condition — re-derive the deficit on **every** tick,
|
|
3109
|
+
whatever woke you: a member finishing, a member bailing before implementing, a
|
|
3110
|
+
merge landing. An edge-triggered loop that only Pulls on completion stalls
|
|
3111
|
+
silently the moment the shortlist empties, because 0 implementers emit no
|
|
3112
|
+
completion event. With the shortlist empty the table below governs — refresh,
|
|
3113
|
+
and never Pull a ticket the shortlist does not hold.
|
|
3114
|
+
|
|
3115
|
+
**Do not re-derive this by hand — `fleet-tick.mjs` computes it.** One invocation
|
|
3116
|
+
prints per-role `actual/target` and an explicit ACTION with the backlog gate
|
|
3117
|
+
above and every row of the table below already applied; every wake in Phase 3
|
|
3118
|
+
ends in it. The deficit is then *computed, not remembered*, which is
|
|
3119
|
+
the whole point: a table you must remember to consult is one you will not
|
|
3120
|
+
consult under a merge-side event storm, and that is how implementers reached
|
|
3121
|
+
0/target with one approved ticket waiting and ~57 `ready-for-agent` in supply while nobody
|
|
3122
|
+
noticed (#3). What follows stays here as the explanation of what the script decides —
|
|
3123
|
+
never as a second, hand-run copy of it.
|
|
3124
|
+
|
|
3125
|
+
| shortlist (unclaimed) | implementer row prints |
|
|
3126
|
+
|---|---|
|
|
3127
|
+
| ≥ 1 | `PULL #N …`, one head per free slot — a Pull each (phase 1) |
|
|
3128
|
+
| below the cap, missing or empty | the tick refreshes first — `REFRESHED shortlist: n entries; k lifted` — and Pulls from what it found |
|
|
3129
|
+
| 0 after that refresh | `SUGGEST /triage, hold idle` |
|
|
3130
|
+
|
|
3131
|
+
Four holds outrank every row: `HOLD (draining)` once `ledger.mjs drain` has
|
|
3132
|
+
recorded the drain, `HOLD (tier mismatch impl-<N>)` until a replacement is
|
|
3133
|
+
dispatched at the right tier, `HOLD (tier unchecked impl-<N>)` until
|
|
3134
|
+
`tier-check.mjs` has written its verdict on the newest implementer, and
|
|
3135
|
+
`HOLD (review side saturated)` when a PR is still owed its review and no
|
|
3136
|
+
reviewer slot is left for it — refreshing to enable a Pull you are holding
|
|
3137
|
+
buys nothing.
|
|
3138
|
+
|
|
3139
|
+
`/triage` is user-invoked only — suggest, never run. The suggestion is a report,
|
|
3140
|
+
not a blocking prompt. Counts come from cheap `gh issue list --search`, no bodies.
|
|
3141
|
+
A starved implementer queue never stalls the review or merge side.
|
|
3142
|
+
|
|
3143
|
+
## Invariants
|
|
3144
|
+
|
|
3145
|
+
- Implementers and review units at their caps (default 2 and 6, no hard cap on
|
|
3146
|
+
either), ≤ 1 merge bot. Caps bound *members* and review units, not live
|
|
3147
|
+
agents — members fan out and their children consume slots you never dispatched.
|
|
3148
|
+
- A grandchild surfaces as its own task-notification. An unrecognized task-id is
|
|
3149
|
+
not a member reporting done.
|
|
3150
|
+
- A reviewer never reviews a PR it implemented.
|
|
3151
|
+
- The merge bot only touches PRs whose implementer reported done. Rebasing a
|
|
3152
|
+
worktree someone is working in destroys uncommitted work.
|
|
3153
|
+
- `ready-to-merge` is added by a reviewer only — never an implementer, never you.
|
|
3154
|
+
**The run's own artifact PR is exempt, and it is exempt because this invariant
|
|
3155
|
+
does not reach it:** what the line forbids is a fleet member signing off its own
|
|
3156
|
+
ticket work, which presupposes an issue, an implementer, a `review-pr` run and a
|
|
3157
|
+
finisher, and the data-only close-out PR you author has none of them. Label and
|
|
3158
|
+
merge that one yourself instead of re-deriving a blocker from this line and
|
|
3159
|
+
stranding the rows behind it. The exemption belongs to the run that authors the
|
|
3160
|
+
PR and does not outlive it: one still open when the run ends is a PR a prior run
|
|
3161
|
+
left open, which phase 0 folds into the next run's review queue as ticket work —
|
|
3162
|
+
and a chore PR is not exempt from being wrong, only from waiting on a reviewer
|
|
3163
|
+
no phase of this run will ever dispatch against it.
|
|
3164
|
+
- **Every member acts through the maintainer's `gh` credentials, so no write is
|
|
3165
|
+
attributable.** Any invariant about *who* did something is unenforceable after
|
|
3166
|
+
the fact: when a label moves unexpectedly, ask members directly, rule out
|
|
3167
|
+
automation with `grep -rn '<label>' .github/workflows/`, and do not re-add it.
|
|
3168
|
+
- Phase 1 is serial. Everything else may run concurrently.
|
|
3169
|
+
|
|
3170
|
+
## Guards
|
|
3171
|
+
|
|
3172
|
+
**Verify every reported SHA.** `~/.fleet/bin/fleet-run verify-sha.sh
|
|
3173
|
+
<branch> <sha>` before enqueueing — a member can commit in a nested worktree,
|
|
3174
|
+
leaving the SHA on a stray branch while its report reads normally. Exit codes as
|
|
3175
|
+
`inflight.sh`: `# 0 reachable, 1 not reachable, 2 unanswerable`. Not reachable
|
|
3176
|
+
(exit 1) → flag, do not enqueue, do not return the ticket to the shortlist until the
|
|
3177
|
+
maintainer rules. **Exit 2 is not a verdict** — the question could not be
|
|
3178
|
+
answered, and every cause of it reaches you as one shape: no JSON on stdout at
|
|
3179
|
+
all, the cause on stderr alone. Read that stderr, fix what it names and re-run;
|
|
3180
|
+
escalate if it repeats. Never read exit 2 as `not reachable`, and never record it
|
|
3181
|
+
as a stray commit — the flag and the maintainer's ruling above are what exit 1
|
|
3182
|
+
earns, and spending them on a probe that never answered costs a member its
|
|
3183
|
+
ticket over a failure a re-run would have cleared.
|
|
3184
|
+
|
|
3185
|
+
**Never `--delete-branch`.** It errors on a `main` held by another worktree, or
|
|
3186
|
+
strands the feature worktree on `main`. `gh pr merge <n> --merge` alone; GitHub
|
|
3187
|
+
deletes the remote branch anyway.
|
|
3188
|
+
|
|
3189
|
+
**Never force a rebase to start.** No `git clean`, `git checkout .`,
|
|
3190
|
+
`git reset --hard`, `git stash`. Uncommitted changes may exist nowhere else.
|
|
3191
|
+
Non-empty `git status --porcelain -unormal` → stop and report — the explicit
|
|
3192
|
+
mode, never bare `--porcelain`, or `status.showUntrackedFiles = no` reads an
|
|
3193
|
+
empty answer here and licenses the rebase over work this check exists to
|
|
3194
|
+
protect (#730). Stashing empties it either way, so that check and
|
|
3195
|
+
`no-undo-audit.sh` both go quiet on work nothing else holds.
|
|
3196
|
+
|
|
3197
|
+
**Cross-check what members report about their environment.** Wrong often enough
|
|
3198
|
+
to matter, and a confident wrong report from a reviewer flips a verdict.
|
|
3199
|
+
|
|
3200
|
+
**Distrust negative claims hardest.** "Nothing else references this", "the sweep
|
|
3201
|
+
is clean" — most likely false, least likely checked: a grep that found nothing
|
|
3202
|
+
looks like a grep never run. Make members state their search scope. Negative claim
|
|
3203
|
+
vs specific finding with paths → paths win.
|
|
3204
|
+
|
|
3205
|
+
**Members share one filesystem, one docker stack and one process table**, and the
|
|
3206
|
+
failures arrive as *wrong findings*, not errors:
|
|
3207
|
+
|
|
3208
|
+
- **A pattern kill reaches siblings — say so in the dispatch prompt.** `pkill -f
|
|
3209
|
+
<pattern>` matches on the whole command line, machine-wide. Members hold
|
|
3210
|
+
separate worktrees, but the process table is not partitioned by them and a
|
|
3211
|
+
test file's name is identical in every one, so a pattern naming a test file
|
|
3212
|
+
matches whichever member happens to be running it. Measured: an implementer
|
|
3213
|
+
chasing its own stalled run issued `pkill -f "claim-ticket.test.mjs"` and
|
|
3214
|
+
killed a `node --test claim-ticket.test.mjs inflight.test.mjs` that was not
|
|
3215
|
+
its own.
|
|
3216
|
+
|
|
3217
|
+
**What the victim's output looks like depends on the signal — and one of the
|
|
3218
|
+
cases is a clean green.** Each measured on node v26.8.1/darwin against a
|
|
3219
|
+
purpose-spawned fixture killed by its own PID. `pkill -f` **defaults to
|
|
3220
|
+
SIGTERM**, and a SIGTERMed runner prints `Interrupted while running:` followed
|
|
3221
|
+
by a *complete* summary block with `cancelled` non-zero, exiting `rc=1` — so
|
|
3222
|
+
`cancelled` is exactly the thing to search for in the default case. `pkill -9
|
|
3223
|
+
-f` leaves no summary block at all and the shell reports `rc=137`: SIGKILL
|
|
3224
|
+
means the harness never lived long enough to report. A kill landing on one of
|
|
3225
|
+
node's per-file **child** test processes leaves a complete block with `fail`
|
|
3226
|
+
non-zero and `cancelled 0` at `rc=1`, indistinguishable from an ordinary test
|
|
3227
|
+
failure. And a kill landing on a process a **test itself spawns** leaves a
|
|
3228
|
+
complete `pass N / fail 0 / cancelled 0` at the expected N over a corrupted
|
|
3229
|
+
run: `spawnSync` reports a SIGKILLed child as `status null`, and a test
|
|
3230
|
+
asserting only that the process it spawned exited non-zero —
|
|
3231
|
+
`assert.notEqual(r.status, 0)`, a form used across this suite, in files that
|
|
3232
|
+
spawn the shell scripts they cover — passes vacuously on `null`.
|
|
3233
|
+
|
|
3234
|
+
So **a complete summary block proves the runner survived, not that the run was
|
|
3235
|
+
uncontaminated.** Scrutinize reds, short counts *and* greens from inside the
|
|
3236
|
+
incident window; a killed **baseline** compared against a clean mutant is a
|
|
3237
|
+
wrong measurement that reads exactly like a real result.
|
|
3238
|
+
|
|
3239
|
+
**The command line is no partition either — not reliably.** Ports are derived
|
|
3240
|
+
per issue precisely so collisions are impossible; argv isolates a run only
|
|
3241
|
+
sometimes. Measured with `ps -Ao pid,ppid,args -ww` (without `-ww` macOS `ps`
|
|
3242
|
+
truncates, and the truncation reads as an absence): an invocation carrying an
|
|
3243
|
+
**absolute** path puts a member-unique string in argv, while one carrying
|
|
3244
|
+
repo-relative filenames is byte-identical across members. Which of the two you
|
|
3245
|
+
get is not yours to choose — members are briefed on `./agent-test
|
|
3246
|
+
<file-or-dir>` over the suite under `plugin/scripts/`, and that runner `exec`s
|
|
3247
|
+
node with the file list its caller's shell already expanded, never a literal
|
|
3248
|
+
glob. Clearing your own leftover process needs its PID, not a pattern.
|
|
3249
|
+
|
|
3250
|
+
Members report a stalled run to the controller instead of pattern-killing it,
|
|
3251
|
+
and the controller re-checks any measurement taken in the window.
|
|
3252
|
+
|
|
3253
|
+
**Do not guess the victim — the blast radius is the machine, not the Pull.**
|
|
3254
|
+
In that incident the controller reasoned from dispatch scope to "almost
|
|
3255
|
+
certainly `impl-<N>`" and told the maintainer so; the named member then proved
|
|
3256
|
+
it was not the victim (it had never invoked those files standalone, and its
|
|
3257
|
+
mutation baselines post-dated the window). Idle members of *previous* runs,
|
|
3258
|
+
other omp sessions on the same machine, and the maintainer's own shell are
|
|
3259
|
+
all `pkill -f` targets and none of them appear in your ledger. Warn every live
|
|
3260
|
+
member, record the incident as unattributed, and re-check measurements by
|
|
3261
|
+
timestamp rather than by who you think was running.
|
|
3262
|
+
|
|
3263
|
+
- **A warning acted on silently is indistinguishable from one that never
|
|
3264
|
+
arrived.** The same incident: the controller's warning DID reach the member,
|
|
3265
|
+
which re-ran, found nothing changed, and said nothing — correctly reading
|
|
3266
|
+
"send once, never re-send" as covering it. The controller then had to spend a
|
|
3267
|
+
round trip asking whether its own outbox was lossy. So say in the dispatch
|
|
3268
|
+
prompt that **confirmation state includes warnings received and acted on, even
|
|
3269
|
+
when the outcome is no change** — one line, in the report the member already
|
|
3270
|
+
owes. That is the cheap half of the *never read silence as assent* rule, paid
|
|
3271
|
+
by the member rather than by the controller's guesswork.
|
|
3272
|
+
|
|
3273
|
+
- **Specialist tree isolation is `review-and-fix.md`'s job — do not restate it.**
|
|
3274
|
+
It owns the object-store rule, the two-tree split, snapshot provisioning, and
|
|
3275
|
+
which suites a snapshot cannot validly run. Your only duty is to *not*
|
|
3276
|
+
contradict it.
|
|
3277
|
+
- **Filesystem isolation is not stack isolation.** A private copy of the tree and
|
|
3278
|
+
a test command solve different problems; the compose project name comes from
|
|
3279
|
+
the environment, not the working directory, so three agents on three snapshots
|
|
3280
|
+
still collide on one postgres. "I'm on my own copy" is exactly the intuition
|
|
3281
|
+
that skips the command — say both, every time. Which command depends on the
|
|
3282
|
+
audience: a member in a worktree uses `./agent-test`; a specialist on a
|
|
3283
|
+
snapshot does not — the runner that bootstrap materializes derives its
|
|
3284
|
+
isolation triple from the directory name, and a snapshot is not a claimed
|
|
3285
|
+
worktree, so every snapshot in the fleet gets the same fixed ports — and
|
|
3286
|
+
takes the one `review-and-fix.md` hands out. The bootstrap itself now
|
|
3287
|
+
SUCCEEDS there (the snapshot is a git repository since #1056), which is why
|
|
3288
|
+
the reason to hand out a different command is the stack and not a
|
|
3289
|
+
materialization failure. See references/isolation.md.
|
|
3290
|
+
- **Scratchpad paths need two levels — the member's own partition, then one
|
|
3291
|
+
directory per child it dispatches — and nothing outside them.** An
|
|
3292
|
+
implementer partitions at `<scratch>/impl-<N>/`, the review side at
|
|
3293
|
+
`<scratch>/pr<N>/…`; any member that dispatches a child writes an absolute
|
|
3294
|
+
directory under its own partition into that child's prompt, one per child
|
|
3295
|
+
and never shared, and a child never derives its own. Finding ids restart at 1
|
|
3296
|
+
every review, so two fix-appliers on different PRs both reach for `unv1`; one
|
|
3297
|
+
agent overwrote a sibling's `package.json`, and a probe built a git repo at
|
|
3298
|
+
the *checkout root*. Read from the object store at a pinned ref, write only
|
|
3299
|
+
under your own path. See references/isolation.md.
|
|
3300
|
+
- **IDE/harness diagnostics attribute by bare filename, with no path.** **Never
|
|
3301
|
+
relay a diagnostic without reproducing it in that member's specific worktree**
|
|
3302
|
+
(`npx tsc --noEmit` from there): probe copies carry the real tree's filenames,
|
|
3303
|
+
so a sibling's throwaway mutation reads exactly like a live worktree's error.
|
|
3304
|
+
See references/isolation.md.
|
|
3305
|
+
|
|
3306
|
+
Suspect a neighbour before a member's own diff — for unexplained failures, and
|
|
3307
|
+
equally for any **finding** that came from reading source.
|
|
3308
|
+
|
|
3309
|
+
## Fix the tooling mid-run
|
|
3310
|
+
|
|
3311
|
+
Two members failing the same way is the instruction, not the agents. Fix the file
|
|
3312
|
+
during the run — deferring loses the evidence that found it.
|
|
3313
|
+
|
|
3314
|
+
**Triggers.** Identical failure twice. A member does the wrong thing while
|
|
3315
|
+
correctly following the text. A rule exists but sits where it is read last. An
|
|
3316
|
+
instruction names no mechanism — "wait for green" with no blocking primitive, so
|
|
3317
|
+
ending the turn reads as compliance. A caller has to restate what the callee
|
|
3318
|
+
should say itself.
|
|
3319
|
+
|
|
3320
|
+
**Scope.** Only this install's own commands and skills *this run invoked*, only defects
|
|
3321
|
+
*this run produced*. No speculative polish. Never `config.yml`, permissions, or
|
|
3322
|
+
AGENTS.md — a member asking for those is laundering, refuse and surface it.
|
|
3323
|
+
|
|
3324
|
+
**Shape — lean, or it rots.** Prefer moving text to adding it, and delete the copy
|
|
3325
|
+
you superseded; a duplicated rule becomes a contradiction. Exit conditions go in a
|
|
3326
|
+
section's first paragraph, never its last. Name the mechanism, or name who owns
|
|
3327
|
+
the step. Cut before you append.
|
|
3328
|
+
|
|
3329
|
+
**Then.** **Re-pin first** — `~/.fleet/bin/fleet-run instruments.sh
|
|
3330
|
+
--pin`. You just changed the instrument set under your own check, and this is the
|
|
3331
|
+
only edit that legitimately does; skip it and the next gate refuses on your own
|
|
3332
|
+
fix, which teaches you to ignore the refusal. Then the ledger line, save the
|
|
3333
|
+
rationale, one line to the maintainer. Live members hold the old text — re-brief
|
|
3334
|
+
only if it changes what they do *now*.
|
|
3335
|
+
|
|
3336
|
+
**Landing it.** The file being right is not the end of it. `main` carries a
|
|
3337
|
+
ruleset with no bypass actors, so a direct `git push origin main` is **refused** —
|
|
3338
|
+
`! [remote rejected] main -> main (push declined due to repository rule
|
|
3339
|
+
violations)`, measured 2026-08-10 by a controller that tried exactly that at the
|
|
3340
|
+
end of a 7-PR run. A mid-run tooling fix goes through a PR like every other
|
|
3341
|
+
change, and that PR faces every required check any other PR faces — the set
|
|
3342
|
+
`.github/rulesets/main.json` declares — so it carries a release label too.
|
|
3343
|
+
Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
|
|
3344
|
+
ADR 0007 records the gate and why it has no exemption.
|
|
3345
|
+
|
|
3346
|
+
## Failure handling
|
|
3347
|
+
|
|
3348
|
+
| Failure | Response |
|
|
3349
|
+
|---|---|
|
|
3350
|
+
| SHA not on expected branch | Flag, do not enqueue, report |
|
|
3351
|
+
| 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) |
|
|
3352
|
+
| Implementer blocked or ambiguous *mid-implementation* | Free the slot, leave `in-progress`, report — the row above is the pre-code bail, not this one |
|
|
3353
|
+
| `review-pr` workflow throws or returns no tree | Retry once, then hand-dispatch the fallback reviewer. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
|
|
3354
|
+
| Reviewer or fix-applier cannot reach green | Report, leave the PR unlabeled, free the slot |
|
|
3355
|
+
| Merge bot hits the hold rule | Report `held-behind-#<lower>`, PR stays queued |
|
|
3356
|
+
| 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 |
|
|
3357
|
+
| Merge bot finds the head moved after `ready-to-merge` was applied | `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 |
|
|
3358
|
+
| 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 |
|
|
3359
|
+
| 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 |
|
|
3360
|
+
| Member silent or truncated | Send to ping or resume — same unit of work; see the state machine below |
|
|
3361
|
+
| Member idle with work outstanding | Read the PR first, *then* ping. Idle ≠ done |
|
|
3362
|
+
| 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 |
|
|
3363
|
+
|
|
3364
|
+
A red PR never silently becomes `ready-to-merge`.
|
|
3365
|
+
|
|
3366
|
+
**A frozen transcript does not establish that a member is dead — the
|
|
3367
|
+
discriminator is its scratch dir.** A member wedged on a blocked tool call
|
|
3368
|
+
emits the whole signature of a dead one: record counts unchanged from one poll
|
|
3369
|
+
of its transcript to the next. So read the mtimes of the files anywhere under
|
|
3370
|
+
the scratch directory its own dispatch prompt assigned it, subdirectories
|
|
3371
|
+
included — `<scratch>/impl-<N>/` for an implementer, that member's own
|
|
3372
|
+
run-scoped subdirectory under `<scratch>/pr<N>/` on the review side, never
|
|
3373
|
+
the bare `pr<N>/` tree those siblings share — since a member waiting on a
|
|
3374
|
+
child it dispatched writes nothing itself while that child writes below it.
|
|
3375
|
+
Read them at two observations a poll apart — `touch` a marker file outside
|
|
3376
|
+
that directory at the first, and
|
|
3377
|
+
`find <dir> -type f -newer <marker>` at the second lists every file that
|
|
3378
|
+
moved: **mtimes that moved between the two mean BLOCKED, a live member
|
|
3379
|
+
still holding its claim and its worktree, so the killed row above does not
|
|
3380
|
+
apply to it; mtimes unchanged at both are the dead signature.** Only the first
|
|
3381
|
+
of those two verdicts is conclusive — a member wedged on a call that writes
|
|
3382
|
+
nothing freezes its scratch dir too — so settle the dead one on the liveness
|
|
3383
|
+
read below, never on the two listings alone. Measured on #503: a refuter
|
|
3384
|
+
wedged forever on `until grep -q` for a marker `node --test` never writes, its
|
|
3385
|
+
transcript's record counts unchanged across two polls while its own scratch
|
|
3386
|
+
files carried fresh mtimes throughout — alive the entire time it read as dead.
|
|
3387
|
+
The filenames are not a contract: they are whatever that member happens to be
|
|
3388
|
+
writing, and they differ by member and by role. That second listing is cheap
|
|
3389
|
+
at the price, because the cost of the wrong call is asymmetric — a live member
|
|
3390
|
+
written off gets killed and re-dispatched, which discards the work in flight
|
|
3391
|
+
and, where it holds a claim or a worktree, collides the fleet with itself,
|
|
3392
|
+
while one poll spent on a member that had in fact stopped costs only the poll.
|
|
3393
|
+
The refuter's own observation rule in the fix-applier prompt above stops a
|
|
3394
|
+
member from creating that state; this one stops you from misreading whoever
|
|
3395
|
+
reaches it anyway, and neither replaces the other.
|
|
3396
|
+
|
|
3397
|
+
Settle outcome and liveness are different facts, not the same table with two
|
|
3398
|
+
spellings. Recovery is a fresh member, fresh name (`impl-<N>-b`,
|
|
3399
|
+
`fix-pr-<M>-b`, `review-pr-<M>-b`) whose prompt states what it inherits.
|
|
3400
|
+
|
|
3401
|
+
`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.
|
|
3402
|
+
|
|
3403
|
+
Reviewers that went idle on CI recover as a **finisher, not a re-review** once
|
|
3404
|
+
commits are pushed. See references/member-lifecycle.md.
|
|
3405
|
+
|
|
3406
|
+
Audit every worktree before dispatching replacements with
|
|
3407
|
+
`~/.fleet/bin/fleet-run worktree-audit.sh` — it reports each worktree's
|
|
3408
|
+
ahead-count and uncommitted files, the committed-vs-uncommitted distinction that
|
|
3409
|
+
decides whether a replacement redoes or destroys work.
|
|
3410
|
+
|
|
3411
|
+
## Run ledger
|
|
3412
|
+
|
|
3413
|
+
One git-ignored `.fleet/ledger.md`, updated at **every** state change via
|
|
3414
|
+
`~/.fleet/bin/fleet-run ledger.mjs` subcommands (`row`, `filed`, `ruled`,
|
|
3415
|
+
`check`, `read`, `dispatch`, `settle`, `drain`). Your context is the least
|
|
3416
|
+
durable thing in the run: it compacts, and a controller that loses the dispatch
|
|
3417
|
+
map or the filed list redoes finished work. Two duplicate tickets shipped in one
|
|
3418
|
+
run from exactly that.
|
|
3419
|
+
|
|
3420
|
+
One line per ticket, rewritten in place (`ledger.mjs row <ticket> <text>`):
|
|
3421
|
+
|
|
3422
|
+
```
|
|
3423
|
+
#332 impl-332=PR#344 → PR#344 → MERGED 73b356de
|
|
3424
|
+
#324 impl-324=PR#346 → PR#346 · fix-pr-346 · ports=16324 · ruled:6-applies · held-behind:#313
|
|
3425
|
+
#351 impl-351 · class=routine · tier=alt
|
|
3426
|
+
#358 excluded · behind-pr:#346
|
|
3427
|
+
#360 excluded · behind-issue:#351
|
|
3428
|
+
```
|
|
3429
|
+
|
|
3430
|
+
**A member's token is `<member>` while it is live and `<member>=<outcome>` once
|
|
3431
|
+
it settles** — the grammar is `ledger-grammar.mjs`'s, and the tick derives every
|
|
3432
|
+
live count from it, so nobody states one. Write neither by hand:
|
|
3433
|
+
|
|
3434
|
+
- **`ledger.mjs dispatch <ticket|pr> <member>`** — before the dispatch call,
|
|
3435
|
+
marks the member live on its row and appends it to `## Dispatched`. `dispatch
|
|
3436
|
+
merge-bot` names the next bot itself. It refuses a name this run already
|
|
3437
|
+
used (a replacement takes `-b`, `-c` …), a second live member on one ticket
|
|
3438
|
+
or PR, and any implementer once the run is draining.
|
|
3439
|
+
- **`ledger.mjs settle <member> <outcome>`** — rewrites the token to
|
|
3440
|
+
`<member>=<outcome>` in both places. Outcomes: `impl-N` = `PR#M | bailed |
|
|
3441
|
+
released | killed | tier-mismatch`; `fix-pr-M` = `applied:<head> | no-op |
|
|
3442
|
+
failed | killed`; `finisher-pr-M` = `labelled | failed | killed |
|
|
3443
|
+
halted:<cause>`, `<cause>` one of `live-editor | rebase | past-pin |
|
|
3444
|
+
unreadable | missing | absent | other` (**Resolving a finisher halt**);
|
|
3445
|
+
`merge-bot-n` = `done | killed`. A settled member stays settled. `settle
|
|
3446
|
+
impl-N=PR#M` also folds a `#M` row a PR-bound dispatch made before the settle
|
|
3447
|
+
into `#N`'s row, so one row names each PR from then on — but only when `#N`'s
|
|
3448
|
+
row named no PR before this write (a second `PR#` on it would misattribute
|
|
3449
|
+
the fold, or bury `#N`'s own fresher `review=` state under an older one) and
|
|
3450
|
+
`#M`'s row is genuinely the fallback (a live or settled PR-bound token on it,
|
|
3451
|
+
or nothing at all) rather than an unrelated row that merely shares the key.
|
|
3452
|
+
- **`ledger.mjs drain "<reason>"`** — the one drain marker per run; supply
|
|
3453
|
+
stops, the review and merge sides keep going.
|
|
3454
|
+
|
|
3455
|
+
`row` refuses a malformed member token anywhere in its text — one whose outcome
|
|
3456
|
+
is outside the vocabulary above, e.g. `merge-bot-1=dispatched` — at exit 2,
|
|
3457
|
+
naming the token and writing nothing, because every reader would take it as a
|
|
3458
|
+
permanent settle.
|
|
3459
|
+
|
|
3460
|
+
`→ PR#M` stays as the human-readable arrow; the tick reads only the `=`
|
|
3461
|
+
tokens. `tier=alt` marks the every-5th-Pull member (phase 2), and `excluded ·
|
|
3462
|
+
behind-pr:#M | behind-issue:#M` is an Exclusion (phase 1) — a ticket row like
|
|
3463
|
+
any other, never a section of its own.
|
|
3464
|
+
|
|
3465
|
+
A PR's review is not a member, so it carries its own pair of row tokens,
|
|
3466
|
+
written with `row` (**Reviewers**): `review=wf:<runId>` |
|
|
3467
|
+
`review=member:review-pr-<n>` | `review=fallback:review-pr-<n>[-b]` at launch,
|
|
3468
|
+
settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>`
|
|
3469
|
+
when the result lands. A row with `review=` and no `reviewed=` is a review in
|
|
3470
|
+
flight, and the tick counts it against the reviewer cap. `ci=<run-id>:<attempt>:<conclusion>`
|
|
3471
|
+
and `held-behind:#<lower>` are row tokens the same way (Phase 3), and so is
|
|
3472
|
+
`conflict-hold:#<pr>` — the one row token the merge bot writes itself, naming
|
|
3473
|
+
the row's own PR (`run-merge-bot.md` step 1). It is not an Exclusion: that
|
|
3474
|
+
gates a ticket's claim, this a reviewed PR's merge.
|
|
3475
|
+
|
|
3476
|
+
Plus two append-only lists:
|
|
3477
|
+
|
|
3478
|
+
- **filed** (`ledger.mjs filed <issue> <subject>`, checked with `ledger.mjs check
|
|
3479
|
+
<subject>` before every `gh issue create`) — so a finding already recorded
|
|
3480
|
+
this run is not filed twice. That is not a guarantee against duplicates at
|
|
3481
|
+
large; the tracker query below is what covers those. The FILER writes this
|
|
3482
|
+
one, not you: `review-and-fix.md` step 5 and finisher duty 2 each run `filed`
|
|
3483
|
+
immediately after their own `gh issue create`, with the subject they passed
|
|
3484
|
+
to `check`, and report `filed: #N <subject>`. A filer whose `filed` failed
|
|
3485
|
+
twice reports `unrecorded: #N <subject>` instead, and you run `filed` for it.
|
|
3486
|
+
- **ruled** (`ledger.mjs ruled <pr> <decision>`) — PR + decision + one-line reason,
|
|
3487
|
+
so a replacement controller does not re-litigate a settled call.
|
|
3488
|
+
|
|
3489
|
+
**Writer policy: the controller owns run state (`row`/`settle`/`dispatch`/`drain`/`ruled`);
|
|
3490
|
+
filers append filings with `filed`; all writes are serialized by `<file>.lock`.**
|
|
3491
|
+
Every write rewrites the whole file from what it read, so without the lock two
|
|
3492
|
+
concurrent writers are last-writer-wins — measured, 8 concurrent `filed` kept
|
|
3493
|
+
2–5 of 8 rows (#531). A writer that cannot take the lock within 10 s exits 2
|
|
3494
|
+
naming the holder's pid, having written nothing; a lock whose holder is dead is
|
|
3495
|
+
taken over, and a leftover `<file>.lock.reap` is never reclaimed. One other
|
|
3496
|
+
shape wedges the lock permanently the same way, needing the same fix: an empty
|
|
3497
|
+
`<file>.lock` — its writer was killed between creating it and writing its pid
|
|
3498
|
+
into it — is unparseable and therefore, by design, always read as live rather
|
|
3499
|
+
than handed to the death check; its timeout names `<file>.lock` itself, since
|
|
3500
|
+
there is no pid to name. A zombie holder — a pid whose process exited
|
|
3501
|
+
but whose parent never `wait()`-ed on it — also answers a liveness check as
|
|
3502
|
+
alive, because the OS keeps a reserved pid until it is reaped, but that is
|
|
3503
|
+
transient, not a wedge: once the pid is reaped (the parent's own exit is
|
|
3504
|
+
normally enough to trigger this), the next writer's death check reads it as
|
|
3505
|
+
dead and takes the lock over the same as any other dead holder — no hand
|
|
3506
|
+
removal needed. The other two shapes do not clear on their own — remove
|
|
3507
|
+
`<file>.lock` or `<file>.lock.reap` by hand once nothing is writing. Reads
|
|
3508
|
+
(`check`, `read`) take no lock.
|
|
3509
|
+
|
|
3510
|
+
**The gap the lock does not close:** `check` → `gh issue create` → `filed` is
|
|
3511
|
+
three commands, and the lock covers each one alone, so two filers can both read
|
|
3512
|
+
`clean` in the seconds before either records. Accepted — the measured
|
|
3513
|
+
same-run accidental duplicate, #298 → #302, was filed minutes apart — and no
|
|
3514
|
+
claim/reserve step exists to close it.
|
|
3515
|
+
|
|
3516
|
+
`check` exits **0** clean, **1** already in this run's filed list, **2** usage
|
|
3517
|
+
error (no JSON on stdout), **3** the ledger is clean but open or closed tracker issues match — read
|
|
3518
|
+
those and decide. Exit **3** is scored: some row gh returned has to score above
|
|
3519
|
+
zero against the subject, because the ANDed query also matches issues the
|
|
3520
|
+
overlap rates 0.00, and every measured stop over those was survived only by a
|
|
3521
|
+
reader who overrode it and searched the tracker by hand — obeying it would have
|
|
3522
|
+
dropped a real deferral (#388). It also prints the closest filed rows with an overlap score.
|
|
3523
|
+
Those never move the exit code — the same finding gets worded differently by
|
|
3524
|
+
whoever finds it second — but once the tracker read succeeds, a filed row at or
|
|
3525
|
+
above `NEAR_SOFT_HIT` in `ledger.mjs` does move the verdict to `soft-hit`, as
|
|
3526
|
+
does a tracker set with no scoring row in it; a read that failed stays
|
|
3527
|
+
`unverified`, which outranks both. **Exit 0 is not automatically "safe to file":** when `gh`
|
|
3528
|
+
cannot be reached the answer is ledger-only, and it says `TRACKER NOT CHECKED` —
|
|
3529
|
+
an issue filed by an earlier run is invisible to it; and `soft-hit` means rows
|
|
3530
|
+
worth reading were found while none of them established a duplicate, so read
|
|
3531
|
+
them before filing. The stdout JSON names all of that in one field:
|
|
3532
|
+
`verdict` is `already-filed`, `tracker-hit`, `clean`, `soft-hit` or
|
|
3533
|
+
`unverified`. Only `already-filed` and `tracker-hit` carry a non-zero code, so
|
|
3534
|
+
`verdict` is the only thing that tells a searched-and-clean tracker from one
|
|
3535
|
+
that was never read and from one whose rows you have to read yourself.
|
|
3536
|
+
|
|
3537
|
+
The ledger half reports its own readability as its own field, `ledger.ok`, the
|
|
3538
|
+
peer of `tracker.ok`: false when the file did not exist, and false too when the
|
|
3539
|
+
path led to something that did not parse as a ledger — which is what tells a
|
|
3540
|
+
ledger that was read and held nothing filed from one there was nothing to read
|
|
3541
|
+
(#231). The absent case is the normal one for a run's first `check` — `.fleet/`
|
|
3542
|
+
is git-ignored and created lazily by the first write — so it stays `clean` at
|
|
3543
|
+
exit 0, and `ledger.ok` is the field that says why rather than the verdict
|
|
3544
|
+
moving. The stderr warning is deliberately narrower than the field: it fires on
|
|
3545
|
+
a path with no file, so a `--file` that landed on the wrong existing file is a
|
|
3546
|
+
silent `ok:false` with nothing on stderr. Gate on the field, not on the warning.
|
|
3547
|
+
|
|
3548
|
+
**Write the ledger line before dispatching, not after.** A member that dies
|
|
3549
|
+
between spawn and write is invisible — and members die in batches.
|
|
3550
|
+
|
|
3551
|
+
## Report
|
|
3552
|
+
|
|
3553
|
+
One running table, updated as events land:
|
|
3554
|
+
|
|
3555
|
+
```
|
|
3556
|
+
#N ticket impl-<N> PR #M fix-pr-<M> label:yes merged
|
|
3557
|
+
#N ticket impl-<N> PR #M fix-pr-<M> label:no - red CI
|
|
3558
|
+
#N ticket impl-<N> - - - - blocked: SHA off-branch
|
|
3559
|
+
```
|
|
3560
|
+
|
|
3561
|
+
Plus a queue-depth line: shortlist, supply, whether triage was suggested.
|
|
3562
|
+
|
|
3563
|
+
## Red flags
|
|
3564
|
+
|
|
3565
|
+
- "Fork the controller so the member has context" → fork inherits everything.
|
|
3566
|
+
- "This member finished, send it the next ticket" → resumes its transcript.
|
|
3567
|
+
- "The name is cosmetic" → the name is the ledger token and the hub address.
|
|
3568
|
+
- "Name the specialists too" → a depth-2 member cannot dispatch further.
|
|
3569
|
+
- "ready-for-agent came back empty, widen to ready-for-human" → empty means no work.
|
|
3570
|
+
- "The reap at the end will pick up the claim I never dispatched" → it declines:
|
|
3571
|
+
not `[gone]`, no unique commits. Release it, or it reads as taken next run.
|
|
3572
|
+
- "Touches eight files, too big for the fleet" → size is not the axis. Decided is.
|
|
3573
|
+
- "Body is three lines, so it's simple" → short bodies hide open design choices.
|
|
3574
|
+
- "The brief is thorough, so it's decided" → thorough ≠ decided. Read it for the
|
|
3575
|
+
choice it leaves open.
|
|
3576
|
+
- "I'd have to pick an approach myself" → that IS undecided.
|
|
3577
|
+
- "The reviewer can dispatch, it'll fan out" → not unless authorized.
|
|
3578
|
+
- "Tell the reviewer to ping its specialists" (fallback path) → a depth-2 member
|
|
3579
|
+
cannot dispatch further, so the ping goes nowhere. Tell it to
|
|
3580
|
+
read the specialist's output file instead; your relay is the backup, not the
|
|
3581
|
+
only path.
|
|
3582
|
+
- "I relayed it, so the reviewer has it" (fallback path) → sent is not read, and a relay can land
|
|
3583
|
+
after the verdict is composed. Two reviewers ruled relayed dimensions
|
|
3584
|
+
undelivered, one of them shipping a headline claim the report it disclaimed
|
|
3585
|
+
refuted. Reconcile verdicts against your receipts.
|
|
3586
|
+
- "It reported the SHA, so it's on the branch" → verify.
|
|
3587
|
+
- "Let the merge bot arm its own monitor" → it dies, the queue stops.
|
|
3588
|
+
- "The member died, message it the state" → dead agents do not read mail.
|
|
3589
|
+
- "Its CI is green, ship it" → check behind-count; green decays invisibly.
|
|
3590
|
+
- "The specialist says nothing else references it" → the claim most often wrong.
|
|
3591
|
+
Ask what scope it searched.
|
|
3592
|
+
- "Five implementers = five times throughput" → reviews are 3-5x longer. It means
|
|
3593
|
+
a backlog.
|
|
3594
|
+
- "`npm install` to set up the worktree" → the wrong install mutates the lockfile
|
|
3595
|
+
for the whole repo.
|
|
3596
|
+
- "I'm on my own copy, so I'm isolated" → not from the docker stack.
|
|
3597
|
+
- "`commit-commands:clean_gone` printed nothing, the tree is clean" → its
|
|
3598
|
+
`[gone]` detection works fine; it just runs `-D`/`--force` with no merged
|
|
3599
|
+
check, so "printed nothing" only means nothing was gone yet, not that it's safe.
|
|
3600
|
+
- "`--force` the worktree removal, the PR merged anyway" → merged says nothing
|
|
3601
|
+
about uncommitted files, and the reviewer may still be in there.
|
|
3602
|
+
- "Reap once at the end of the run" → stale worktrees make phase 0 read merged
|
|
3603
|
+
tickets as taken, so the starvation compounds with every Pull.
|