@feigi/fleet-ctl 3.141.5 → 3.143.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.
@@ -194,5 +194,5 @@ A mismatch on a ticket whose issue is already CLOSED holds nothing: the tick pro
194
194
  - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). Write the `review=` token with `ledger.mjs review <pr> <token>`; `ledger.mjs` refuses a bad grammar. The tick names every PR owed one, oldest first, and each gets one review, once per PR. The tick counts in-flight reviews off the ledger and nowhere else, so a review you launched and never recorded is one it names again. The runner writes the result file and reports its path and `reviewed=` token.
195
195
  A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
196
196
  - **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none. It holds every finding and you hold none, so there is nothing for you to rank, relay or pre-rule — and a report from a refuter it spawns that surfaces to you is its to retrieve, never yours to scan or pass on. It answers the hold and nothing else: survived or unverified findings of a returned review the row also carries stay unanswered through its settle, so the tick prints `DISPATCH fix-pr PR#<M>` again once it lands, and that one is a review fix-applier, dispatched as above. On a PR carrying `ready-to-merge`, the push moves the head after the label, so the next merge bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure handling**.
197
- - **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Read the definition off that output (`fleet-fix-applier` whatever the row's `tier=`), never recall it. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement.
198
- - **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the PR's current head that is not **solely** staleness: a `rebase-check` red, or heavy jobs `skipped`, that comes only off the behind-count gets no fixer (the five-condition note in `agents/fleet-fix-applier.agent.md` establishes that). Name `fix-pr-<M>`, or the next free suffix; render with `dispatch-prompt.mjs render fix-applier --kind red-check --member <name> …`, record with `ledger.mjs dispatch <pr#> <name>` before the call, and dispatch with the printed `agent` in the PR's existing worktree. While a review or a review fix-applier on the PR is live or still owes its report — a dispositions mismatch awaiting its retry and a conflict hold awaiting its fix-applier included — the red-check fixer does not fire: their push starts a new run, and a fixer racing them would work on a SHA that is still moving. The common case, the implementer's own first CI firing turning red before any review exists, still dispatches the review against that head as normal. The tick prints no `DISPATCH` for it, so you reconcile it yourself, and it always goes after the review, never before. It is told outright not to watch, poll or wait for CI: your persistent Monitor owns the next run on the pushed head, and the finisher gate — review returned AND fix-applier report sent — applies to this member the same way. Settle it `applied:<head>` once a fix is pushed. Settle it `no-op` only when the red turns out not to be this member's to fix — a flake that passes on rerun, or staleness — with nothing pushed; `no-op` counts as landed, so it never stands for "could not fix". Settle it `failed` when it cannot reach green, which the **Failure handling** row "Reviewer, fix-applier or red-check fixer cannot reach green" covers. Its three dispatch edges are under **The finisher gate**; their rationale is in `references/member-lifecycle.md` (The red-check fixer's three edges).
197
+ - **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Read the definition off that output (`fleet-fix-applier` whatever the row's `tier=`), never recall it. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement, but a second `failed` since the PR's latest review escalates (`ESCALATE fix-failed`).
198
+ - **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the PR's current head that is not **solely** staleness: a `rebase-check` red, or heavy jobs `skipped`, that comes only off the behind-count gets no fixer (the five-condition note in `agents/fleet-fix-applier.agent.md` establishes that). Name `fix-pr-<M>`, or the next free suffix; render with `dispatch-prompt.mjs render fix-applier --kind red-check --member <name> …`, record with `ledger.mjs dispatch <pr#> <name>` before the call, and dispatch with the printed `agent` in the PR's existing worktree. `dispatch` refuses one on a PR where two fix-appliers have settled `failed` since its latest review with none landed after them, whether or not the tick prints `ESCALATE fix-failed` for it — it prints that row only while the PR is owed a fix-applier: handle that refusal as the row. While a review or a review fix-applier on the PR is live or still owes its report — a dispositions mismatch awaiting its retry and a conflict hold awaiting its fix-applier included — the red-check fixer does not fire: their push starts a new run, and a fixer racing them would work on a SHA that is still moving. The common case, the implementer's own first CI firing turning red before any review exists, still dispatches the review against that head as normal. The tick prints no `DISPATCH` for it, so you reconcile it yourself, and it always goes after the review, never before. It is told outright not to watch, poll or wait for CI: your persistent Monitor owns the next run on the pushed head, and the finisher gate — review returned AND fix-applier report sent — applies to this member the same way. Settle it `applied:<head>` once a fix is pushed. Settle it `no-op` only when the red turns out not to be this member's to fix — a flake that passes on rerun, or staleness — with nothing pushed; `no-op` counts as landed, so it never stands for "could not fix". Settle it `failed` when it cannot reach green, which the **Failure handling** row "Reviewer, fix-applier or red-check fixer cannot reach green" covers. Its three dispatch edges are under **The finisher gate**; their rationale is in `references/member-lifecycle.md` (The red-check fixer's three edges).
@@ -32,7 +32,7 @@ into one free implementer slot, the moment it frees (phase 1).
32
32
 
33
33
  `phase0.mjs` runs the start sequence in
34
34
  its fixed order — alarm, branch, fast-forward, pin, baseline, labels, preflight, ruleset,
35
- tier-roles, metrics, cockpit, rotate, reclaim, evict, recipe, fold-in, stranded,
35
+ tier-roles, metrics, cockpit, rotate, catch-up, reclaim, evict, recipe, fold-in, stranded,
36
36
  shortlist — prints one `phase0: <step>: <status>` line per step with the
37
37
  `NEED` lines last, and records each step in `.fleet/phase0.json`, which the
38
38
  tick reads: it prints `PHASE0-INCOMPLETE` and holds every dispatching row
@@ -79,6 +79,8 @@ yourself. The baseline records the root it
79
79
  certified beside the digest, and every later check — yours, a finisher's, the
80
80
  merge gate's own leg — compares it with the live root and refuses when they
81
81
  differ. Never dispatch a member into a run whose phase-0 pin refused.
82
+ `phase0.mjs` records the version the pin wrote into the receipt as
83
+ `pluginVersion`, so the run's archived receipt says which plugin it ran.
82
84
 
83
85
  ## Record the main-checkout baseline
84
86
 
@@ -388,13 +390,39 @@ archives, hand-named ones included, are left alone.
388
390
  Before the rotation, `phase0.mjs` puts the held-aside receipt (`phase0.previous.json`) back at `phase0.json`, which `ledger.mjs rotate` then files as `phase0.<UTC stamp>.json`.
389
391
  `ledger.mjs rotate` archives the run's two receipts with the ledger, under the ledger archive's own stamp: `.fleet/phase0.<UTC stamp>.json` and `.fleet/closeout.<UTC stamp>.json` beside `.fleet/ledger.<UTC stamp>.md`.
390
392
 
393
+ ## Catch up the run records
394
+
395
+ **Catch up the run records straight after the rotation, before the reclaim —
396
+ every run.** The `catch-up` step copies every run archive in `.fleet/` — the
397
+ previous run's, which the rotation has just filed, and any earlier one — into
398
+ `docs/metrics/runs/<UTC stamp>/`, and every review's evidence under the
399
+ scratch root into `docs/metrics/reviews/<pr>/<run>/`, the same gather the
400
+ close-out runs (references/close-out.md). When main lacks a record of a run
401
+ that never closed out — no `.fleet/closeout.<UTC stamp>.json` beside its
402
+ ledger archive — it commits every file main lacks alone on a branch of its own
403
+ in this checkout, pushes it, opens a PR and switches back to `main`; the
404
+ metrics files' changes stay in the work tree, out of that commit. The PR is an
405
+ Owned PR, so the fold-in below queues it. A run that closed out leaves its
406
+ records to this run's close-out, which gathers them again, so the step opens
407
+ no second PR carrying the same files and its output says so. A run whose
408
+ close-out never ran therefore loses nothing: its ledger, receipts and version
409
+ reach main here, and its review evidence is still in scratch when the reclaim
410
+ runs, which keeps a merged PR's evidence until main holds it. The step never
411
+ stops the run but for a checkout it could not switch back to `main`; a commit
412
+ it could not make is named in its output, with how far it got — a branch
413
+ pushed with no PR open for it is named so — and the close-out gathers those
414
+ files again.
415
+
391
416
  ## Reclaim scratch
392
417
 
393
- **Reclaim scratch straight after the rotation — every run.**
418
+ **Reclaim scratch straight after the catch-up — every run.**
394
419
  `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --root <scratch>
395
420
  --after-rotate --apply`, `<scratch>` the path `scratch-root.mjs` prints,
396
421
  so a run that merges nothing still reclaims the previous run's leftovers
397
422
  (`reclaim-scratch.mjs`'s header says what it removes).
423
+ A merged PR's `pr<pr>/` and Charges files that hold review evidence stay
424
+ until `origin/main` holds that evidence under `docs/metrics/reviews/<pr>/`,
425
+ and a lookup that cannot answer keeps them.
398
426
  `--after-rotate` goes on this call always and on no other: rotate leaves
399
427
  no ledger behind when it carried nothing, and the flag reads that absence
400
428
  as "no live token" — rotate's own verdict — where without it the script
@@ -493,8 +521,10 @@ settled `blocked` and `fix-report` for a fix-applier settled `failed`: it is
493
521
  counted in the same once per run, a line printed while that derivation runs
494
522
  is covered by it, and one printed after its `RECIPE PROVEN` is the second
495
523
  refusal that stalls the run. What to retry for a wake's line: a fix-applier's
496
- PR is fix-due again and the tick re-dispatches it; a blocked implementer's
497
- ticket is reported to the maintainer and waits for their `replace #<N>`.
524
+ PR is fix-due again and the tick re-dispatches it, unless that `failed` was its
525
+ second since the PR's latest review, which escalates (`ESCALATE fix-failed`);
526
+ a blocked implementer's ticket is reported to the maintainer and waits for
527
+ their `replace #<N>`.
498
528
  The count is yours to keep; the ledger holds no record of it. The Install step's refusals
499
529
  fire after the claim has labelled the ticket and created its worktree, so
500
530
  release that claim with `release-ticket.sh` first (SKILL.md's Failure handling
@@ -65,6 +65,31 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
65
65
  and flag it for a human; write no hold and dispatch no fix-applier. Not
66
66
  actionable; it repeats while the PR reads CONFLICTING and clears once it
67
67
  stops, closes or merges.
68
+ - `ESCALATE fix-failed PR#<M> …` — PR M is owed a fix-applier, but two
69
+ fix-appliers on it have settled `failed` since its latest `reviewed=` (from
70
+ its first token, with none), each with a retry suffix after that of every
71
+ fix-applier on the PR that landed `applied:`/`no-op`. Every kind counts —
72
+ review, conflict, dispositions retry, red-check; `killed` and live ones
73
+ neither count nor restart the count, and a landed one restarts it. The row
74
+ prints in place of `DISPATCH fix-pr PR#<M>`, its detail naming the counted
75
+ members, and `ledger.mjs dispatch` refuses a third fix-applier of any kind
76
+ on M, a hand-dispatched red-check fixer included. It refuses one on any PR
77
+ whose count reaches two, even one owed no fix-applier, for which no row
78
+ prints — two failed red-check fixers after a review with nothing to fix.
79
+ Handle that refusal as the row. Dispatch no fix-applier for M. Comment on
80
+ the PR once — read its comments for the first line before posting, since
81
+ the row repeats and the comment does not. Its first line is `**Two
82
+ fix-appliers failed on this PR since its latest review; the fleet
83
+ dispatches no third.**`; then each
84
+ counted member with what its report says (`confirmation`, and `testRun`
85
+ when not null), or `no report`; then: a new review hands the PR back, and a
86
+ draft PR is skipped by the next run. Tell the maintainer. On their word,
87
+ launch a new review with `ledger.mjs review <M> review=member:<next
88
+ reviewer name>` and dispatch it as any review: its `reviewed=` restarts the
89
+ count. Not actionable; it repeats every tick while it holds and clears once
90
+ a new `reviewed=` lands or the PR closes or merges. Nothing carries it
91
+ across runs: the next run's fold-in queues the PR for review like any Owned
92
+ PR, and a draft is not one.
68
93
  - `ESCALATE pr-closed #<N> PR#<M>` — PR M, ticket N's latest PR (the latest
69
94
  `impl-<N>…=PR#<M>` on the row), is CLOSED unmerged while issue #N is not
70
95
  read CLOSED (an issue gh cannot read counts as open), and no