@feigi/fleet-ctl 3.69.1 → 3.70.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/commands/review-and-fix.md +1 -1
- package/commands/run-merge-bot.md +1 -1
- package/package.json +1 -1
- package/scripts/fleet-event.mjs +10 -2
- package/scripts/fleet-tick.mjs +12 -4
- package/scripts/ledger-grammar.mjs +29 -2
- package/scripts/ledger.mjs +41 -14
- package/skills/run-team/SKILL.md +68 -625
- package/skills/run-team/references/ci-and-staleness.md +27 -1
- package/skills/run-team/references/ci-watcher.md +88 -0
- package/skills/run-team/references/correction-tickets.md +27 -1
- package/skills/run-team/references/failure-handling.md +35 -0
- package/skills/run-team/references/finisher.md +93 -0
- package/skills/run-team/references/instruments.md +19 -0
- package/skills/run-team/references/isolation.md +140 -1
- package/skills/run-team/references/ledger.md +57 -0
- package/skills/run-team/references/member-lifecycle.md +43 -1
- package/skills/run-team/references/merge-bot.md +14 -0
- package/skills/run-team/references/phase-0.md +5 -1
- package/skills/run-team/references/pull.md +60 -0
- package/skills/run-team/references/reviewers.md +98 -0
- package/skills/run-team/references/shell-traps.md +55 -0
|
@@ -14,7 +14,7 @@ argument-hint: [pr-number]
|
|
|
14
14
|
**Write every ruling to `<scratch>/dispositions-<your name>.json`, `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as (standalone, `fix-pr-<pr>`) — the disposition record `dispositions-check.mjs` judges against the review result file before any finisher is dispatched.** It is `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}` — `run` the `<run>` of the review path your prompt names, which the check holds against the one the PR's latest `reviewed=` names, so a record written against an earlier review of the same PR, a same-head one included, is a mismatch (standalone, with no ledger naming a run, leave it out): one entry per `survived` finding and per `unverified` finding, plus one per `refuted` finding you reverse. Each entry carries `bucket` (`survived|unverified|refuted`), `index` (its position in that bucket of the review file — stable, since a round's file never changes), `scope` (`in|out`), `claimKind` (`behavior|shape`) and `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the number you filed it to or commented on), `verdictPath` (a suggestion's refuter verdict file, in scope and, above the claim bar, out of scope) and `remedyFiles` (the files its remedy names). A `refuted` entry carries `scope`, `claimKind` and `disposition` like every other entry, and a non-empty `reason` holding the evidence that reverses it; a missing or blank `reason` is a mismatch. The check reads scope off the diff before it reads your entry: a finding with no `line`, or on a line `git diff` touches from the PR's merge-base with `origin/main` to the review's `head`, is in scope whatever `scope` says, and only otherwise does the declared one stand. An in-scope `survived` finding deferred passes only with `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or `remedy-outside-diff`. `remedy-outside-diff` — the remedy would edit a file the PR's diff does not touch — also needs `remedyFiles` to name at least one file absent from `git diff` from that merge-base to the review's `head`: none named, or every one in that diff, is a mismatch. A `critical` or `important` finding deferred for it goes to a human instead of passing: the script exits 1 with verdict `escalate`, `ledger.mjs dispatch` refuses the PR's finisher, and nothing retries it; a `suggestion` deferred for it passes. Any other reason, none, or a `survived` or `unverified` finding with no entry is a mismatch: the script exits 1 naming each violating entry's bucket, index and rule, and `ledger.mjs dispatch` refuses the PR's finisher. `disposition` has no `dismiss`: an in-scope `survived` finding verified correct, needing no change, is deferred with `reason` `false-rationale` and filed on the closed suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
|
|
15
15
|
3. **Run `testCmd` before you commit**, from the worktree, copied verbatim — not a runner you picked. `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you one, it is the repo's own test command**, the Test entrypoint in the repo's Recipe cache (`derive-testcmd.sh <repo> test` prints it). Read it off the repo, never invent one: "not a runner you picked" is what this step forbids, and on the standalone path nothing else defines the referent. With no usable Recipe cache (`derive-testcmd.sh` refuses), run the Recipe derivation step first — dispatch a `task` member, agent `fleet-recipe-deriver`, its prompt naming the main checkout's absolute path as `<repo>` and a scratch directory of its own; it proves both commands in a throwaway worktree and writes the cache only on proof, and its `RECIPE NOT PROVEN` is a stop, reported with its reason. Never fall back to a runner of your own choosing. `tests 0` is a FAILED run, not a pass: a glob matching nothing still exits 0. **Zero is not the only no-work count.** A run reporting **0 passes with no failures** skipped everything it collected, and a count **materially below the whole suite** means you ran a partial tree — this suite reported `tests 937` when this line was written, so compare what you get against a full run rather than against zero. The number drifts; that is the safe direction, because a stale one produces a loud false red while its absence produces a silent false green. Red, zero-test, or either no-work count → fix it or move the finding to defer; never commit over it. Then commit and push — `git push origin HEAD:<branch>`, the explicit refspec: this step also runs from a `--detach` worktree (`run-team/SKILL.md`'s worktree-recreation form), where a bare `git push` exits 128 (`fatal: You are not currently on a branch`) and any push whose destination is `HEAD` rather than a full or branch refname (`-u` or not, forced or not) exits 1 (`error: The destination you provided is not a full refname`) — and report the test result alongside the SHA. **Then reconcile the PR body with what you actually did.** It merges into the permanent record and nothing downstream re-derives it: your commit messages are yours to fix and usually get fixed, the body is neither. Removing a change, or reversing one, leaves the body asserting work the diff no longer contains. Measured twice in one run — one body kept asserting a calibration its own fix had just deleted as false, another kept claiming a hunk the fix had removed as "this diff owns it" — both caught by a finisher's reading rather than by any rule, and both would otherwise have merged intact. `gh pr edit <pr> --body-file <path>`, and re-read the body against the final diff rather than against your memory of it. **Never `--no-verify`.** The fleet runs in repos it knows nothing about: it must not assume a pre-commit hook exists, and must never bypass one that does — a hook that fails is a finding to report, not an obstacle. Nothing re-reviews what you commit here, so this run is the only gate between your edit and a merge.
|
|
16
16
|
4. **Under the fleet, do not hold this wait.** The controller owns a persistent CI Monitor and dispatches a finisher once your report has arrived and CI is green — so push, then report to the controller a **final verdict** (every specialist you dispatched + its outcome + your apply/defer adjudication + how many refuters you dispatched against out-of-scope suggestions + the pushed SHA) and stop. A specialist that has not reported to you is not a verdict line — `hub send` it by name for its report, then ask the controller, before ruling; see **Specialists**. The controller keys "review complete" on that verdict, **never on you merely going idle** — a slow specialist can still be running when your turn ends, and finishing off idle-alone ships a premature label (observed: a PR labelled while its contract-test specialist was still running and about to surface a vacuous pin). A turn-based reviewer re-reading `gh pr checks` each idle cycle rebuilds its whole context for nothing the Monitor lacks. **Standalone (no controller): watch** the run until the diff-validating jobs are green (bind via `ci-state.mjs` below); fix a **genuine** failure and repeat from 3. **Staleness is not a failure:** a `rebase-check` red or heavy jobs `skipped` **solely from a non-zero behind-count** never clears by waiting and must not be rebased away here — see **`skipped` is not `passed`** and **Do NOT rebase to label** below for what it looks like and why. Stop watching and go to 6. A turn-based reviewer that "waits for green" on a behind PR stalls forever and ends its turn without labelling. **`ci-state.mjs` returns `verdict: "no-ci"`** → there is no run to watch, so don't: go straight to 6 and let that step's `--declare-no-ci` branch decide.
|
|
17
|
-
5. File each deferred finding: `gh issue create --label needs-triage` with the finding, `file:line`, why deferred, `Deferred from PR #<pr> review`, and **the finding's `dimension` in the issue body** — the review returns it on every finding, and a backlog that does not carry it cannot be attributed to the specialist that generated it. **The body also carries the evidence triage needs: the refuter's verdict — the `verdictPath` reason, or the review's votes — and the candidate remedy.** **Every issue you create is labelled `needs-triage`; only triage sets `ready-for-agent`** — and the label is never omitted; an unlabelled issue is invisible to both `candidates.mjs --require-label` and the cockpit's pool query, reachable only by a human. **A confirmed defect does not settle its remedy**, so confirming one earns it no other label: a confirmed defect with the remedy still open files `needs-triage`, and so does a finding you are unsure is broken at all. **A finding a refuter CHECKED and did not survive is neither** — it is not a confirmed defect, and you are not unsure whether anything is broken: you measured that nothing is. Refutations go as **one issue per review, titled `PR #<pr> review: the suggestion band, checked`, labelled `wontfix`, and CLOSED** — a run that files them open instead has to be corrected afterwards, as one was on 2026-08-27. Left open they read as queued agent work and rot into filing artifacts; a measured triage pass found a quarter of its `needs-triage` backlog was refuted records, bulk-closable by title shape. Closed is still a durable home — `check` reads the tracker at `--state all`, so a future run re-deriving the finding lands on the evidence rather than re-litigating it. Split the band only where an entry is **not** a refutation: a residual the refuter surfaced, or an out-of-scope finding its refuter let survive or never decided, is real deferred work — and real deferred work earns its own open issue only past a second bar. **Worth a claim: a finding whose own claim is that correct code could be shaped better — style, naming, layout, redundancy, a micro-simplification — never gets its own open issue.** **Neither does a gap in a prose guard — a test holding prose to its wording — unless something acts on the guarded text: an agent follows it as an instruction (a skill, a command, an agent definition, a script's header or usage text, `AGENTS.md`), or a program other than its own guard reads it.** Whether anything does is your judgement, as `claimKind` is, and a gap below this bar is recorded `claimKind: shape`. A gap in a guard's own code — a slow pattern, a dead branch, an unchecked spawn result — takes the stakes of the prose it guards, and a helper several guards share takes the highest of theirs. A missed wording already in the tree is no guard gap — that prose is wrong — and neither is an input already in the tree that trips a guard's code; each files on its own merits. Once the prose is corrected, the observed wording may join the guard's literal ban, never a reader built to catch wordings nobody has written. A below-bar finding's only open question is "is this worth doing?", which answers itself under the repriced triage bar: measured 2026-08-15→31, 133 issues were triage-closed `wontfix` in sixteen days, 121 of them review deferrals, mostly this shape. Append it to the same closed record issue under a `Below the claim bar` heading — `file:line`, dimension, the claim, and a re-open trigger per entry. Closed is a durable home for these too: `check` reads `--state all`, so a run re-deriving the finding lands on the record instead of re-filing — and a later review returning the same finding as `survived`, or a maintainer hitting it, is the promotion signal: file it open then, citing the record. **An in-scope rediscovery step 2 applied is that same promotion signal, and it files nothing** — so the record carries no mark unless you write one: run `check` over each finding step 2 applied as well, and where its tracker rows put one on a `Below the claim bar` entry, comment on that record issue, opening `Promoted — applied, not filed`, and name the entry, that its refuter let it through, and the commit carrying the fix. That comment is the promotion mark this path leaves, and it is **not** a cross-reference — measured on this tracker, a comment mints `cross-referenced` on the issue its own text *names*, never on the issue it sits under (a comment citing a second issue landed on that issue's timeline and nowhere else), so the fixed opening is what carries the signal instead. **The bar reads the finding's claim, never its review band** — a finding that alleges wrong behavior, whatever band it sat in, `unverified`-with-crashed-refuters included, is above this bar and files open, `needs-triage`, which is why a band cannot carry this decision. Do **not** reach for phase 0's **decided?** test here. That is a *consumption* gate, and whether a filed issue is decided enough to reach it is triage's call, never the filer's. **The cost of this rule is watched:** open `needs-triage` issues citing `Deferred from PR` above 40 on 3 consecutive run dates send the filing rule back to the maintainer — batch triage, a fleet triage role, or a different bar. **Dedupe through `~/.fleet/bin/fleet-run ledger.mjs check "<subject>"`, never a bare `gh issue list --search`** — the duplicate class that guard exists to catch was filed from *here*: the ledger row for the finding rediscovered five times in one measured run carries a reviewer's own source tag, `(review-pr-108)`. `check` reads this run's filed list *and* the tracker at `--state all`, so a closed duplicate still counts. Exit **1** is already filed in this run; exit **3** is a clean ledger with matching tracker rows that score against the subject — read the ones it prints and comment on the existing follow-up rather than filing a second issue. **Exit 0 is not automatically "safe to file"**: it covers `clean`, `soft-hit` and `unverified` alike, and an unreachable `gh` degrades to a ledger-only answer that says `TRACKER NOT CHECKED`, so read the stdout `verdict` to tell a tracker that was searched and clean from one nobody read — under `unverified`, search it yourself before filing — or, for the applied-promotion comment above, before treating a tracker nobody could read as a reason to skip it. **`soft-hit` is the answer that costs most to misread**: it means related rows were found and none of them was established as a duplicate — a near-miss above the floor, or tracker rows the scorer rates 0.00 — so read the rows it printed and decide, and never treat that exit 0 as permission. Exit **2** is a usage error, meaning nothing was checked at all: fix the invocation and re-run, never read it as a duplicate. Full exit-code and `verdict` semantics live in `$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s **Run ledger** section — read them there rather than restating them here. **The guard dedupes, it never drops:** a duplicate becomes a comment on the issue that already covers it, never a dropped finding. **Record every issue you create, at once:** immediately after each `gh issue create`, run `~/.fleet/bin/fleet-run ledger.mjs filed <N> "<subject>"` — `<N>` the number `gh issue create` printed, and **the same subject string you passed to `check`**, so the next `check` for that finding meets it in the filed list instead of scoring a rewording. Without it the guard's ledger half never holds a row, and its exit **1** can never fire. If `filed` fails, retry it once; if it fails again, leave the issue alone — it exists and is correct — and report it as `unrecorded: #N <subject>`, so the controller runs `filed` for it. Report `filed: #N <subject>` for every issue you created — under the fleet, in your report to the controller. **The one window the guard cannot see:** `check` → `gh issue create` → `filed` is three commands, and the ledger's lock covers each alone, so two filers can both read `clean` in the seconds before either records. That gap is accepted, never a reason to skip `filed`. Post the numbers as one PR comment.
|
|
17
|
+
5. File each deferred finding: `gh issue create --label needs-triage` with the finding, `file:line`, why deferred, `Deferred from PR #<pr> review`, and **the finding's `dimension` in the issue body** — the review returns it on every finding, and a backlog that does not carry it cannot be attributed to the specialist that generated it. **The body also carries the evidence triage needs: the refuter's verdict — the `verdictPath` reason, or the review's votes — and the candidate remedy.** **Every issue you create is labelled `needs-triage`; only triage sets `ready-for-agent`** — and the label is never omitted; an unlabelled issue is invisible to both `candidates.mjs --require-label` and the cockpit's pool query, reachable only by a human. **A confirmed defect does not settle its remedy**, so confirming one earns it no other label: a confirmed defect with the remedy still open files `needs-triage`, and so does a finding you are unsure is broken at all. **A finding a refuter CHECKED and did not survive is neither** — it is not a confirmed defect, and you are not unsure whether anything is broken: you measured that nothing is. Refutations go as **one issue per review, titled `PR #<pr> review: the suggestion band, checked`, labelled `wontfix`, and CLOSED** — a run that files them open instead has to be corrected afterwards, as one was on 2026-08-27. Left open they read as queued agent work and rot into filing artifacts; a measured triage pass found a quarter of its `needs-triage` backlog was refuted records, bulk-closable by title shape. Closed is still a durable home — `check` reads the tracker at `--state all`, so a future run re-deriving the finding lands on the evidence rather than re-litigating it. Split the band only where an entry is **not** a refutation: a residual the refuter surfaced, or an out-of-scope finding its refuter let survive or never decided, is real deferred work — and real deferred work earns its own open issue only past a second bar. **Worth a claim: a finding whose own claim is that correct code could be shaped better — style, naming, layout, redundancy, a micro-simplification — never gets its own open issue.** **Neither does a gap in a prose guard — a test holding prose to its wording — unless something acts on the guarded text: an agent follows it as an instruction (a skill, a command, an agent definition, a script's header or usage text, `AGENTS.md`), or a program other than its own guard reads it.** Whether anything does is your judgement, as `claimKind` is, and a gap below this bar is recorded `claimKind: shape`. A gap in a guard's own code — a slow pattern, a dead branch, an unchecked spawn result — takes the stakes of the prose it guards, and a helper several guards share takes the highest of theirs. A missed wording already in the tree is no guard gap — that prose is wrong — and neither is an input already in the tree that trips a guard's code; each files on its own merits. Once the prose is corrected, the observed wording may join the guard's literal ban, never a reader built to catch wordings nobody has written. A below-bar finding's only open question is "is this worth doing?", which answers itself under the repriced triage bar: measured 2026-08-15→31, 133 issues were triage-closed `wontfix` in sixteen days, 121 of them review deferrals, mostly this shape. Append it to the same closed record issue under a `Below the claim bar` heading — `file:line`, dimension, the claim, and a re-open trigger per entry. Closed is a durable home for these too: `check` reads `--state all`, so a run re-deriving the finding lands on the record instead of re-filing — and a later review returning the same finding as `survived`, or a maintainer hitting it, is the promotion signal: file it open then, citing the record. **An in-scope rediscovery step 2 applied is that same promotion signal, and it files nothing** — so the record carries no mark unless you write one: run `check` over each finding step 2 applied as well, and where its tracker rows put one on a `Below the claim bar` entry, comment on that record issue, opening `Promoted — applied, not filed`, and name the entry, that its refuter let it through, and the commit carrying the fix. That comment is the promotion mark this path leaves, and it is **not** a cross-reference — measured on this tracker, a comment mints `cross-referenced` on the issue its own text *names*, never on the issue it sits under (a comment citing a second issue landed on that issue's timeline and nowhere else), so the fixed opening is what carries the signal instead. **The bar reads the finding's claim, never its review band** — a finding that alleges wrong behavior, whatever band it sat in, `unverified`-with-crashed-refuters included, is above this bar and files open, `needs-triage`, which is why a band cannot carry this decision. Do **not** reach for phase 0's **decided?** test here. That is a *consumption* gate, and whether a filed issue is decided enough to reach it is triage's call, never the filer's. **The cost of this rule is watched:** open `needs-triage` issues citing `Deferred from PR` above 40 on 3 consecutive run dates send the filing rule back to the maintainer — batch triage, a fleet triage role, or a different bar. **Dedupe through `~/.fleet/bin/fleet-run ledger.mjs check "<subject>"`, never a bare `gh issue list --search`** — the duplicate class that guard exists to catch was filed from *here*: the ledger row for the finding rediscovered five times in one measured run carries a reviewer's own source tag, `(review-pr-108)`. `check` reads this run's filed list *and* the tracker at `--state all`, so a closed duplicate still counts. Exit **1** is already filed in this run; exit **3** is a clean ledger with matching tracker rows that score against the subject — read the ones it prints and comment on the existing follow-up rather than filing a second issue. **Exit 0 is not automatically "safe to file"**: it covers `clean`, `soft-hit` and `unverified` alike, and an unreachable `gh` degrades to a ledger-only answer that says `TRACKER NOT CHECKED`, so read the stdout `verdict` to tell a tracker that was searched and clean from one nobody read — under `unverified`, search it yourself before filing — or, for the applied-promotion comment above, before treating a tracker nobody could read as a reason to skip it. **`soft-hit` is the answer that costs most to misread**: it means related rows were found and none of them was established as a duplicate — a near-miss above the floor, or tracker rows the scorer rates 0.00 — so read the rows it printed and decide, and never treat that exit 0 as permission. Exit **2** is a usage error, meaning nothing was checked at all: fix the invocation and re-run, never read it as a duplicate. Full exit-code and `verdict` semantics live in `$(~/.fleet/bin/fleet-run --root)/skills/run-team/references/ledger.md`, which `SKILL.md`'s **Run ledger** section points at — read them there rather than restating them here. **The guard dedupes, it never drops:** a duplicate becomes a comment on the issue that already covers it, never a dropped finding. **Record every issue you create, at once:** immediately after each `gh issue create`, run `~/.fleet/bin/fleet-run ledger.mjs filed <N> "<subject>"` — `<N>` the number `gh issue create` printed, and **the same subject string you passed to `check`**, so the next `check` for that finding meets it in the filed list instead of scoring a rewording. Without it the guard's ledger half never holds a row, and its exit **1** can never fire. If `filed` fails, retry it once; if it fails again, leave the issue alone — it exists and is correct — and report it as `unrecorded: #N <subject>`, so the controller runs `filed` for it. Report `filed: #N <subject>` for every issue you created — under the fleet, in your report to the controller. **The one window the guard cannot see:** `check` → `gh issue create` → `filed` is three commands, and the ledger's lock covers each alone, so two filers can both read `clean` in the seconds before either records. That gap is accepted, never a reason to skip `filed`. Post the numbers as one PR comment.
|
|
18
18
|
**A duplicate that should hold an open deferral is a comment, never a relabel.** Where the guard lands a finding whose home is an open issue on an existing one that is open, cite the refuters' verdict — or the review's votes — in the comment you leave there, and change no label. Never relabel `ready-for-agent` down to `needs-triage`: a `ready-for-agent` issue already holds a `needs-triage` finding, because triage already promoted it, and a later run's crashed refuters are no reason to send it back. A closed one cannot hold it: file a new open issue citing it, as the promotion rule above does for the closed record.
|
|
19
19
|
**Name where each deferral went, in the disposition record.** Every entry you defer carries `issue`: the number of the issue you filed it to, commented it onto, or appended it to — the closed `PR #<pr> review: the suggestion band, checked` record included. A `suggestion`'s entry — an `unverified` finding with `refutersDispatched` of zero — also carries `verdictPath`, applied or deferred, in scope and, above the claim bar, out of scope: the absolute path of a file holding its refuter's verdict as JSON, `{"refuted": <boolean>, "reason": "<string>"}`, under your own `<scratch>/pr<N>/fix-XXXXXXXX/<finding>/` run root. An out-of-scope one whose refuter crashed before any verdict reached you still names the path its verdict would have taken there; out of scope, that file missing or holding no decision files the finding open `needs-triage`, while in scope it is a mismatch. `dispositions-check.mjs` reads each named issue back through `gh issue view --json labels,state,title` and each verdict file off disk; a mismatch names the row of its filing table the entry broke, so move or relabel that filing to the home the row names and run the check again. With `gh` unreachable, or an issue it cannot read, that filing goes unchecked: with nothing else broken the verdict is `unchecked` — never `ok`, and it exits 1 — so run the check again once `gh` answers.
|
|
20
20
|
6. Diff-check green (run-bound per `ci-state.mjs`; under staleness see **`skipped` is not `passed`** for what the label then rests on) **and** deferrals filed **and** the PR carrying exactly one release label (`patch`/`minor`/`major`, counting only those three; **required on every PR** — `release-label.yml` auto-adds `patch` when none is present and hard-fails on more than one, so this never needs to check whether the repo defines the gate at all, and `gh label list` settles nothing here any more) **and** `dispositions-check.mjs --member fix-pr-<pr> --scratch <scratch>` run over your own record exiting 0 (standalone that is yours to run, from the worktree, after step 2 writes `<scratch>/dispositions-fix-pr-<pr>.json`; `--review <path>` names the review file, which you write yourself from the findings step 1 collected, in the shape **The review result file** describes — `pr`, `head`, `snapshot`, `counts` and the `survived`, `refuted` and `unverified` buckets; standalone you pass `--no-ledger` with it, so it writes no token and the exit status is the verdict — a `.fleet/ledger.md` the repository already holds is a previous run's, and without the flag it exits 2 for a ledger with no row for you; under the fleet `ledger.mjs dispatch` has already refused a finisher without it) → `gh pr comment <pr> --body "ready-to-merge-head: <prHead>"`, `prHead` being the full SHA your green `ci-state.mjs` reading reported, which the merge bot reads as the head the label was applied to, then `gh pr edit <pr> --add-label ready-to-merge`. Do not merge. A non-zero dispositions exit halts you before the label, and you report the violations it printed. Zero or more than one release label halts you before the label, naming which you found — a timed-out `gh pr create` opens the PR with its `--label` unapplied and no exit status to react to, and nothing after this step re-derives the release label. **Under the fleet a finisher does this** — a fresh small agent the controller dispatches (after your final verdict, never on your bare idle). Gate it on the diff-validating **`check`** job, **not** on `ci-state --quiet` exit 0, which a behind PR — the normal case once any sibling merges — never reaches: a `rebase-check` red or heavy jobs `skipped` off the behind-count hold it short of full green, so an exit-0 gate strands every behind PR unlabelled. Label when `check` is present and green **and no heavy job (the diff-validating suites — *not* the `rebase-check` currency gate) is in `failure`** — a `skipped` heavy job is behind-count staleness and fine — **solely** off that count, which is a condition to establish rather than infer, see the five-condition note in `$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s fix-applier prompt block. A `failure` is the diff's own fault and blocks the label, else a genuinely broken PR gets labelled off a green `check` and burns a merge-bot rebase+CI cycle before the failure resurfaces. Read per-job state for this: run `ci-state.mjs` **without** `--quiet`, or read its `jobs` — the `--quiet` payload drops the per-job `jobs`/`missing` and the `dropped` list, keeping `reasons` (which still distinguishes `is failure` from `is skipped`). You reach step 6 yourself only when green is already in hand at push time.
|
|
@@ -376,7 +376,7 @@ Arm with `persistent: true`, description `ready-to-merge label on this repo's PR
|
|
|
376
376
|
- Seed `seen` **before** the loop so PRs already handled — including ones skipped for `CHANGES_REQUESTED` or left on red CI — do not re-fire every minute. Only a label appearing after arming is an event. The seed poll is guarded the same way as every tick: a `gh` call failing on the very first poll must not arm on an empty `seen`, which would replay the whole labeled set as spurious events on tick one.
|
|
377
377
|
- The `if cur=$(poll)` guard — seed and every tick alike — keeps `seen` intact when a `gh` call fails transiently; without it a failed poll reads as an empty labeled set and either arms on nothing (the seed) or wipes `seen` (a tick), both replaying the full labeled set as events on the next successful poll. The guard depends on `poll` ending in the bare `gh` call, not in a pipe: `tr` sits at the call sites (not inside `poll`) precisely so a failing `gh` call's exit status reaches `cur=$(poll)` / `seed=$(poll)` instead of being swallowed by `tr`, which exits 0 regardless of what it reads.
|
|
378
378
|
- **A full page is not a whole reading either.** `gh pr list` stops at its `--limit` — 30 when the flag is absent — with exit 0 and no warning, so `poll` passes an explicit one (`cap`, one variable for the flag and the check), and `capcheck` says once when a poll fills it and once when one comes back under it: the DEGRADED/RECOVERED latch `run-team/SKILL.md`'s CI Monitor uses for the same cause, and never a line per tick. The numbers a capped poll did return are still real events; the line is for the labels past them, which fire nothing while it holds.
|
|
379
|
-
- **The per-PR loop is heredoc-fed on purpose — `for n in $cur` is the one form that cannot work here.** This runs under zsh, which word-splits an unquoted command substitution's result but *not* an unquoted parameter expansion, and `cur` is a parameter. Measured on zsh 5.9 with `seen` holding two PR numbers and `cur` those two plus a third: the bare form runs **one** iteration with the whole list glued into a single value and emits one `ready-to-merge label added:` event with all three numbers glued into it, one nonsense event naming no PR, while the real new PR is never reported; the heredoc form emits the third alone. `run-team/SKILL.md`'s **Shell traps** carries the mechanism
|
|
379
|
+
- **The per-PR loop is heredoc-fed on purpose — `for n in $cur` is the one form that cannot work here.** This runs under zsh, which word-splits an unquoted command substitution's result but *not* an unquoted parameter expansion, and `cur` is a parameter. Measured on zsh 5.9 with `seen` holding two PR numbers and `cur` those two plus a third: the bare form runs **one** iteration with the whole list glued into a single value and emits one `ready-to-merge label added:` event with all three numbers glued into it, one nonsense event naming no PR, while the real new PR is never reported; the heredoc form emits the third alone. `run-team/SKILL.md`'s **Shell traps** carries the mechanism and the `</dev/null` trap that bites the next command added inside this loop, and `run-team/references/shell-traps.md` carries the remedy table. Note the contrast with step 1's `for _ in $(seq 1 60)`: that is a command substitution, it splits, and it is correct as written.
|
|
380
380
|
- 60s poll — remote API, stay off rate limits.
|
|
381
381
|
- A held PR stays in `seen`, so its own label will not re-fire. Fine: what unblocks it is the **lower** PR getting labeled, which does fire, and step 4's re-evaluation picks up both in numeric order.
|
|
382
382
|
|
package/package.json
CHANGED
package/scripts/fleet-event.mjs
CHANGED
|
@@ -145,7 +145,7 @@ import { makeDie, defineFlags, isDigits, writeAll } from "./arg.mjs";
|
|
|
145
145
|
import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
|
|
146
146
|
import { gitEnv } from "./git-env.mjs";
|
|
147
147
|
import { isCLI } from "./is-cli.mjs";
|
|
148
|
-
import { BRIEFS, REVIEW, REVIEWED, memberTokens, nextReviewerName, parseDispatchedEntry, parseMember, parseToken, rowNums } from "./ledger-grammar.mjs";
|
|
148
|
+
import { BRIEFS, REVIEW, REVIEWED, memberTokens, nextReviewerName, parseDispatchedEntry, parseMember, parseToken, readRetired, rowNums } from "./ledger-grammar.mjs";
|
|
149
149
|
import { dispositionsToken, foldLedger } from "./fleet-tick.mjs";
|
|
150
150
|
import { readRunReceipt, tickCaps } from "./phase0-receipt.mjs";
|
|
151
151
|
import { defaultScratch, readReportIn, reportsDir } from "./report-files.mjs";
|
|
@@ -538,7 +538,15 @@ function reviewFailed(ev, pr, launch) {
|
|
|
538
538
|
let next;
|
|
539
539
|
if (prWords(ev.ledger, pr).includes(tok)) {
|
|
540
540
|
ev.note(`PR #${pr} already ${tok}`);
|
|
541
|
-
|
|
541
|
+
// `## Retired` read as `ledger.mjs review` reads it, refusing a line that
|
|
542
|
+
// names no member or reviewer as `review` does.
|
|
543
|
+
const { names, malformed } = readRetired(ev.ledger.retired);
|
|
544
|
+
if (malformed.length > 0) {
|
|
545
|
+
ev.refuse(`next free runner for PR #${pr}`, { status: 2, how: "exit 2",
|
|
546
|
+
stderr: `${NAME}: ## Retired has a line '${malformed[0]}' that names no member or reviewer — fix the ledger by hand before review can trust it\n` });
|
|
547
|
+
return;
|
|
548
|
+
}
|
|
549
|
+
next = nextReviewerName(ev.ledger.rows, pr, names);
|
|
542
550
|
} else {
|
|
543
551
|
const r = node("ledger.mjs", ["review", String(pr), tok]);
|
|
544
552
|
if (r.status !== 0) {
|
package/scripts/fleet-tick.mjs
CHANGED
|
@@ -132,7 +132,7 @@
|
|
|
132
132
|
// the ledger; main() does the I/O. Split so the guard table and the reading are
|
|
133
133
|
// both unit-testable without a network.
|
|
134
134
|
|
|
135
|
-
import { parseMember, parseToken, premisesOf, rowNums, nextRetry, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
|
|
135
|
+
import { parseMember, parseToken, premisesOf, rowNums, nextRetry, readRetired, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
|
|
136
136
|
|
|
137
137
|
// The implementer and reviewer rows' TARGET is the In-flight bound; the merge
|
|
138
138
|
// bot's is 1. Availability of work belongs in the ACTION, not the target: a
|
|
@@ -909,6 +909,14 @@ export const pastPinDue = (st, head) => st !== undefined && st.pastPinHalt && !s
|
|
|
909
909
|
export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, closed = new Set(), finished = new Set()) {
|
|
910
910
|
const open = new Set(prs.map((p) => p.number));
|
|
911
911
|
const { members, byPr, verdicts, claimed, excluded } = foldLedger({ rows, dispatched }, open);
|
|
912
|
+
// `## Retired` lines as every reader reads them: a line's name before its
|
|
913
|
+
// first `=`. One naming no member or reviewer would leave the name it was
|
|
914
|
+
// meant to hold unaccounted for, so it is refused, as a `## Dispatched`
|
|
915
|
+
// entry that is no member token is.
|
|
916
|
+
const { names: retiredNames, malformed: badRetired } = readRetired(retired);
|
|
917
|
+
if (badRetired.length > 0) {
|
|
918
|
+
throw new LedgerError(`## Retired line '${badRetired[0]}' names no member or reviewer — fix the ledger by hand before the tick can count from it`);
|
|
919
|
+
}
|
|
912
920
|
|
|
913
921
|
const all = [...members.values()];
|
|
914
922
|
const live = (family) => all.filter((m) => m.family === family && m.outcome === null).length;
|
|
@@ -1088,9 +1096,9 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, closed
|
|
|
1088
1096
|
// `review=wf:` run no member, so neither files one.
|
|
1089
1097
|
reporters: unsettled,
|
|
1090
1098
|
// Every member name the ledger records, settled or live: each row's
|
|
1091
|
-
// member tokens, each `## Dispatched` entry and each `## Retired` line
|
|
1092
|
-
// the names a transcript in the session directory is accounted for by.
|
|
1093
|
-
recorded: new Set([...members.keys(), ...
|
|
1099
|
+
// member tokens, each `## Dispatched` entry and each `## Retired` line's
|
|
1100
|
+
// name — the names a transcript in the session directory is accounted for by.
|
|
1101
|
+
recorded: new Set([...members.keys(), ...retiredNames]),
|
|
1094
1102
|
};
|
|
1095
1103
|
}
|
|
1096
1104
|
|
|
@@ -505,6 +505,33 @@ export const REVIEWER = /^review-pr-([1-9][0-9]*)(-[b-z])?$/;
|
|
|
505
505
|
* reviewer's, bare. */
|
|
506
506
|
export const isRetirable = (name) => parseMember(name) !== null || REVIEWER.test(name);
|
|
507
507
|
|
|
508
|
+
/** The name a `## Retired` line retires, read the one way every reader reads
|
|
509
|
+
* the section: the line's text before its first `=` — the whole line when it
|
|
510
|
+
* has none — whatever outcome follows it, so a name written with an outcome
|
|
511
|
+
* stays taken. Null when that name is not retirable: the line names no
|
|
512
|
+
* member or reviewer and is malformed, and read as no name it would release
|
|
513
|
+
* the name it was meant to hold, so `dispatch`, `review`, the tick and
|
|
514
|
+
* `review-failed` refuse it and `rotate` skips it aloud; `token` reads the
|
|
515
|
+
* names and leaves a malformed line to them. */
|
|
516
|
+
export function retiredName(line) {
|
|
517
|
+
const eq = line.indexOf("=");
|
|
518
|
+
const name = eq === -1 ? line : line.slice(0, eq);
|
|
519
|
+
return isRetirable(name) ? name : null;
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
/** `## Retired` lines read through retiredName(): `names`, the names they
|
|
523
|
+
* retire in line order, and `malformed`, the lines that name none. */
|
|
524
|
+
export function readRetired(lines) {
|
|
525
|
+
const names = [];
|
|
526
|
+
const malformed = [];
|
|
527
|
+
for (const line of lines) {
|
|
528
|
+
const name = retiredName(line);
|
|
529
|
+
if (name === null) malformed.push(line);
|
|
530
|
+
else names.push(name);
|
|
531
|
+
}
|
|
532
|
+
return { names, malformed };
|
|
533
|
+
}
|
|
534
|
+
|
|
508
535
|
// The reviewer runner names a row's `review=member:<name>` launches took,
|
|
509
536
|
// `=failed` or answered or open. A workflow launch is named by its runId,
|
|
510
537
|
// which no hub member holds.
|
|
@@ -522,8 +549,8 @@ function launchedRunners(text) {
|
|
|
522
549
|
* in `## Dispatched` or on any row, the same two places `ledger.mjs dispatch`
|
|
523
550
|
* refuses a repeat from within a run — and every reviewer runner a row
|
|
524
551
|
* launched, that `liveOnLedger` does not carry, plus every name the archive's
|
|
525
|
-
* own `## Retired` already held (`retired`,
|
|
526
|
-
*
|
|
552
|
+
* own `## Retired` already held (`retired`, the names the caller read off its
|
|
553
|
+
* lines with retiredName()), once each: the `## Retired` names first, then the
|
|
527
554
|
* `## Dispatched` entries' in order, then the rows' in the order given, a
|
|
528
555
|
* row's member tokens before the reviewer runners it launched. A retired
|
|
529
556
|
* name stays taken for the rest of the omp session: the process that ran
|
package/scripts/ledger.mjs
CHANGED
|
@@ -51,7 +51,7 @@ import { fileURLToPath } from "node:url";
|
|
|
51
51
|
import { spawnSync, execFileSync } from "node:child_process";
|
|
52
52
|
import { makeDie, isFlagLike, hasEqualsForm, isDigits, writeAll } from "./arg.mjs";
|
|
53
53
|
import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
|
|
54
|
-
import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger,
|
|
54
|
+
import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, retiredName, readRetired, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, headerRe, escapeText, unescapeText, nextReviewerName } from "./ledger-grammar.mjs";
|
|
55
55
|
import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD } from "./fleet-tick.mjs";
|
|
56
56
|
import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
|
|
57
57
|
import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
|
|
@@ -1673,9 +1673,8 @@ function runRotate() {
|
|
|
1673
1673
|
// or one whose outcome is outside its family's vocabulary, which skips the
|
|
1674
1674
|
// line but not the name — and every reviewer runner a row launched, read off
|
|
1675
1675
|
// the parsed rows, the skipped ones and every `## Dispatched` entry alike — a
|
|
1676
|
-
// line the tick refuses still names members this session ran — and the
|
|
1677
|
-
// archive's own `## Retired
|
|
1678
|
-
// reviewer name.
|
|
1676
|
+
// line the tick refuses still names members this session ran — and the names
|
|
1677
|
+
// the archive's own `## Retired` lines hold.
|
|
1679
1678
|
function carryOf(text) {
|
|
1680
1679
|
const skipped = [];
|
|
1681
1680
|
const skippedRows = [];
|
|
@@ -1700,11 +1699,19 @@ function carryOf(text) {
|
|
|
1700
1699
|
skipped.push({ line: e, why: t === null ? "not a member token" : `${t.name}: ${t.error}` });
|
|
1701
1700
|
return false;
|
|
1702
1701
|
});
|
|
1703
|
-
|
|
1704
|
-
|
|
1705
|
-
|
|
1706
|
-
|
|
1707
|
-
|
|
1702
|
+
// A `## Retired` line is read through retiredName(), as every reader reads
|
|
1703
|
+
// it: one that carries an outcome is skipped — the new ledger holds names
|
|
1704
|
+
// bare — but its name retires, and one naming no member or reviewer is
|
|
1705
|
+
// skipped and retires nothing.
|
|
1706
|
+
const archivedRetired = [];
|
|
1707
|
+
for (const line of sectionOf(text, RETIRED)) {
|
|
1708
|
+
const name = retiredName(line);
|
|
1709
|
+
if (name === null) skipped.push({ line, why: "names no member or reviewer" });
|
|
1710
|
+
else {
|
|
1711
|
+
if (name !== line) skipped.push({ line, why: `${name} is retired bare` });
|
|
1712
|
+
archivedRetired.push(name);
|
|
1713
|
+
}
|
|
1714
|
+
}
|
|
1708
1715
|
const live = liveOnLedger(rows, dispatched);
|
|
1709
1716
|
const carried = { rows: live.rows.map((i) => rows[i]), dispatched: live.dispatched };
|
|
1710
1717
|
const retired = retiredOnLedger([...rows, ...skippedRows], allDispatched, archivedRetired, carried);
|
|
@@ -1766,6 +1773,20 @@ function refuseMalformedDispatched() {
|
|
|
1766
1773
|
}
|
|
1767
1774
|
}
|
|
1768
1775
|
|
|
1776
|
+
// The names `## Retired` holds, for `cmd` (dispatch or review) to refuse a
|
|
1777
|
+
// repeat from: each line's name read through readRetired(), the grammar's
|
|
1778
|
+
// one reading of the section, so a line that carries an outcome still holds
|
|
1779
|
+
// its name. A line naming no member or reviewer would release the name it
|
|
1780
|
+
// was meant to hold; refuse it, naming it, as refuseMalformedDispatched()
|
|
1781
|
+
// refuses an entry.
|
|
1782
|
+
function retiredNames(cmd) {
|
|
1783
|
+
const { names, malformed } = readRetired(data.retired);
|
|
1784
|
+
if (malformed.length > 0) {
|
|
1785
|
+
die(`## Retired has a line '${malformed[0]}' that names no member or reviewer — fix the ledger by hand before ${cmd} can trust it`);
|
|
1786
|
+
}
|
|
1787
|
+
return names;
|
|
1788
|
+
}
|
|
1789
|
+
|
|
1769
1790
|
// Why a finisher on PR `pr` may not be recorded yet, or null when it may.
|
|
1770
1791
|
// `review` is the tick fold's `reviewed` entry for the PR, undefined when the
|
|
1771
1792
|
// PR has no returned review.
|
|
@@ -1810,13 +1831,14 @@ function runDispatch() {
|
|
|
1810
1831
|
// Read ahead of every lookup below that trusts `## Dispatched` by name,
|
|
1811
1832
|
// including `nextMergeBot()`'s own read of it.
|
|
1812
1833
|
refuseMalformedDispatched();
|
|
1834
|
+
const retired = retiredNames("dispatch");
|
|
1813
1835
|
|
|
1814
1836
|
// `merge-bot` bare is the merge-bot case of this command: the ledger names
|
|
1815
1837
|
// the bot, 1 + the highest merge-bot name this session holds — in
|
|
1816
1838
|
// `## Dispatched`, on a row or in `## Retired` — so the controller never
|
|
1817
1839
|
// counts. An explicit `merge-bot-<n>` is accepted only when it is that one.
|
|
1818
1840
|
// `sessionNames` is every name beyond `## Dispatched` the session has used.
|
|
1819
|
-
const sessionNames = [...data.rows.flatMap(memberTokens).map((t) => t.name), ...
|
|
1841
|
+
const sessionNames = [...data.rows.flatMap(memberTokens).map((t) => t.name), ...retired];
|
|
1820
1842
|
const member = parseMember(name === "merge-bot" ? nextMergeBot(data.dispatched, sessionNames) : name);
|
|
1821
1843
|
if (!member) die(unknownMember(name));
|
|
1822
1844
|
if (member.bound === null) {
|
|
@@ -1847,7 +1869,7 @@ function runDispatch() {
|
|
|
1847
1869
|
const prior =
|
|
1848
1870
|
data.dispatched.find((e) => parseToken(e).name === member.name) ??
|
|
1849
1871
|
(settledOnRow && `${settledOnRow.name}=${settledOnRow.outcome}`) ??
|
|
1850
|
-
(
|
|
1872
|
+
(retired.includes(member.name) ? "retired by rotate" : undefined);
|
|
1851
1873
|
if (prior !== undefined) {
|
|
1852
1874
|
// Never a merge bot: it is accepted only as the number past every name
|
|
1853
1875
|
// the session holds, so none of the three places above can name it.
|
|
@@ -2460,6 +2482,7 @@ function runReview() {
|
|
|
2460
2482
|
if (other !== undefined) {
|
|
2461
2483
|
die(`review #${prNum}: '${other}' is not a review token — review writes only review=… and reviewed=…; every other token goes through row, dispatch or settle`);
|
|
2462
2484
|
}
|
|
2485
|
+
const retired = retiredNames("review");
|
|
2463
2486
|
const i = prRowIndex(prNum);
|
|
2464
2487
|
const created = i === -1;
|
|
2465
2488
|
const oldLine = created ? null : data.rows[i];
|
|
@@ -2475,13 +2498,13 @@ function runReview() {
|
|
|
2475
2498
|
: created ? `${head} ${appended.join(" · ")}`
|
|
2476
2499
|
: `${head} · ${appended.join(" · ")}`;
|
|
2477
2500
|
const after = created ? [...data.rows, line] : data.rows.with(i, line);
|
|
2478
|
-
const refusal = rowWriteRefusal(data.rows, after, oldLine, line,
|
|
2501
|
+
const refusal = rowWriteRefusal(data.rows, after, oldLine, line, retired);
|
|
2479
2502
|
if (refusal !== null) die(`review #${prNum}: ${refusal}`);
|
|
2480
2503
|
data.rows = after;
|
|
2481
2504
|
save(data);
|
|
2482
2505
|
const key = rowKey(line);
|
|
2483
2506
|
console.error(` review on row ${key}`);
|
|
2484
|
-
console.log(JSON.stringify({ pr: prNum, row: key, line, created, next: nextReviewerName(data.rows, prNum,
|
|
2507
|
+
console.log(JSON.stringify({ pr: prNum, row: key, line, created, next: nextReviewerName(data.rows, prNum, retired) }));
|
|
2485
2508
|
}
|
|
2486
2509
|
|
|
2487
2510
|
// A row's tokens: its words after the key, bar the ` · ` separators between
|
|
@@ -2595,7 +2618,11 @@ function runToken() {
|
|
|
2595
2618
|
// on a row with no implementer), or split one PR across two rows.
|
|
2596
2619
|
const split = newSplitRow(data.rows, after);
|
|
2597
2620
|
if (split !== null) die(`token ${key}: ${splitRowClause(split)}`);
|
|
2598
|
-
|
|
2621
|
+
// The names only: `token` adds no launch of its own, but a `PR#<n>` mention
|
|
2622
|
+
// can move a row that already holds one onto another PR, and that launch is
|
|
2623
|
+
// then judged against the retired names. A malformed `## Retired` line is
|
|
2624
|
+
// left to the readers that refuse it.
|
|
2625
|
+
const refusal = rowWriteRefusal(data.rows, after, oldLine, line, readRetired(data.retired).names);
|
|
2599
2626
|
if (refusal !== null) die(`token ${key}: ${refusal}`);
|
|
2600
2627
|
data.rows = after;
|
|
2601
2628
|
save(data);
|