@feigi/fleet-ctl 3.82.19 → 3.82.21

package/skills/run-team/references/pull.md

@@ -492,7 +492,7 @@ every five Pulls by construction.
 The last guard fired with n=1 on the control side. The pre-cell pair query
 counted pairs that are no cell's comparisons, and the query before that one
 counted every session whose implementers merely differed, so it cleared the
-cell floor SKILL.md's **Report** states — at least ten comparisons across five
+cell floor **Do not read a cell early** states — at least ten comparisons across five
 or more distinct `run_date`s — by an order of magnitude while the controlled
 comparison did not exist yet.
 
@@ -576,3 +576,38 @@ The raw split still favours the top tier — 3 failures in 11 `routine`/`sonnet`
 ## What minted_false_claim reads
 
 `minted_false_claim` **discriminates and no longer reads "always yes"** — 20 of the 66 `routine` rows carry `no`, 18 at `opus` and 2 at `sonnet`. Read it as a property of the TICKET before the tier: a pure code simplification need not add prose, while a correction ticket adds prose by construction. The honest summary is unchanged and is the reason this paragraph exists: the guard fired on the criterion the maintainer chose in advance, not on a demonstration that the cheaper tier is worse.
+
+## Do not read a cell early
+
+**Do not read a cell early.** A cell's
+comparison is one session holding an admissible row at that cell — its tier
+check passed and its resolved effort is the cell's level — and one at
+`slow-high` whose resolved model and effort differ. Count them per cell, never
+pooled across cells, and stop until
+there are at least ten of them across five or more distinct `run_date`s; below
+that, a comparison count is a number, not evidence. SKILL.md's **Report**
+reports the count `cell-readout.mjs` prints, which holds a cell below that
+floor to a count on stderr.
+
+## A Pull's entry and exits, in full
+
+A Pull's entry is `~/.fleet/bin/fleet-run pull.mjs next --head <N>`, run from the
+main checkout (without `--head`, the next shortlist entry). It runs the
+mechanical steps in order and stops at each judgement with a `QUESTION
+<qid>:` block and exit 10; `pull.mjs answer <N> <qid> <token> [--path <p>] [--]
+[<text>…]` records the answer and resumes it. Exit 0 prints `DISPATCH {name,
+agent, brief}`, the `task` call that the dispatch makes; exit 1 means the ticket left the
+Pull, so take the next entry; exit 2 names what could not be looked at —
+`next --head <N>` again retries a step that failed, the same `answer` again
+retries one that failed while applying an answer (the question stands), and
+after a router refusal `next --head <N>` starts the ticket over; exit 3 is a
+usage mistake, or an answer the question does not take, and records nothing.
+The record is `<scratch>/impl-<N>/pull.json`.
+
+## No multi-select, no maintainer tick
+
+**No multi-select, no maintainer tick.** Selection and ordering are batched —
+one scan, oldest first; admission never is. The invariant this replaces — one
+human decision per batch of admissions, zero unilateral grabs — is retired
+is retired: zero human decisions per admission, and every non-admission is a
+label or a premise the maintainer can read.

package/skills/run-team/references/reviewers.md

@@ -148,3 +148,84 @@ to matter, and a confident wrong report from a reviewer flips a verdict.
 "Nothing else references this", "the sweep
 is clean" — most likely false, least likely checked: a grep that found nothing
 looks like a grep never run.
+
+## Reading a review result's digest, field by field
+
+Findings never enter your context —
+a result runs 26-61 KB, 7-15k tokens that used to land in yours and then again,
+up to ~10k characters, in every fix-applier prompt you wrote. What the digest tells you:
+
+**`testEnvironment` says what the review's shared test run is evidence about**,
+and it is present on a healthy run as well as a degraded one, so there is
+nothing to notice by its absence. The
+fix-applier reads it before acting on any count from the shared test run; you
+read it so a degraded review never passes for a clean one.
+`unverified` is *not* "checked and cleared" — a `suggestion` skips the pass by
+policy, and a finding whose refuters all crashed or abstained lands there too.
+All go to the fix-applier with the rest, in the file; never rule on them yourself.
+**`refutersDispatched`, carried on every finding, is what tells the skip
+apart** — zero is the policy skip, above zero with no deciding vote is a
+refuter pass that decided nothing — and `refutersInconclusive` splits that
+one: the refuters it counts abstained, every other one dispatched crashed. So
+the population is read off those fields rather than off severity,
+which records only how much a finding would matter if true. `resume` is
+non-null exactly when a specialist or a refuter pair crashed again after the
+review's own in-run retry, and **resume beats handing a crash-heavy review
+on**: a deferred crash is a finding nobody ever looked at.
+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.
+`refuted` comes back deliberately as well — a refutation is itself a claim, and
+one has been reversed on new evidence. The fix-applier may reverse one; it
+records each reversal as a `refuted` entry in its disposition record, the
+evidence in `reason`, and you copy those entries to the ledger's `ruled` line by
+running `fleet-event.mjs fix-report`, whose `settle --from-report` records each
+refutation the report defers.
+
+**`dimensionsRun` is the dispatch; `dimensionsUnrun` is what names a gap.** A
+specialist that dies contributes zero findings while its key stays in
+`dimensionsRun`. So read the two together. A key
+in `dimensionsRun` and NOT in `dimensionsUnrun` returned a review; every
+`dimensionsUnrun` entry is `{dimension, reason}` naming a specialist that
+returned nothing, its `reason` the crash.
+The review already re-dispatched each crashed specialist once, so what
+`dimensionsUnrun` still names is residue: the fix-applier names it unrun in its
+report and re-runs nothing — an absence of findings is not coverage.
+
+**`suiteVerdict` is the review's one judgement on its shared test run:
+`{usable, reason}`, always present.** The review runs the test command once,
+and every specialist reads that run instead of running its own. `{usable: true,
+reason: null}` says the run executed real tests and its exit status is
+explained by its counts; usable is not green, so a usable run can have failing
+tests. `usable: false` carries `reason`, including a run that never started
+(install skipped, no suite slot). The verdict says nothing about whether a
+dimension reviewed: a specialist that returned reviewed, its findings verified
+as usual, whatever the suite verdict. With `usable: false` the
+fix-applier names `shared test run not usable: <reason>` in its final verdict
+and does nothing more — its own `<testCmd>` run and CI cover the suite.
+**Exit 75 is not a test result.** In a review it makes
+`suiteVerdict` not usable, `suiteVerdict.reason` beginning "no suite slot within
+<n> s — the host is at its suite bound; not a test failure", with no retry
+inside the run: read that `reason` off the digest and re-review it
+under the next runner letter (`review-pr-<pr#>-b` after a first runner), as for
+a runner that reported `failed`.
+
+**`cwdAudit` is the specialist's own inherited-checkout audit, one entry per
+dispatched dimension: `{dimension, state, line}`, `state` one of**
+`clean`/`dirty`/`unrepo`/`missing`. The prompt asks every specialist to run
+`git status --porcelain -uall` against the directory it inherited before
+returning and fold the result into a `CWD-AUDIT:` line — a convention, not
+schema, so a specialist that never emits it or misspells it still validates
+clean. This field is the runtime backstop that reads for the line regardless:
+`missing` is exactly as loud as `dirty`, and both name a checkout you should
+treat as a live scratch write until you have checked it.
+
+## The tier-outcomes row's difficulty fields
+
+The row's last four fields are the ticket's difficulty, and they are what lets a
+tier comparison condition on the thing that swamps it. `sizing` is the
+**member's** own `light`/`heavy` verdict from its dispatched `sizing-a-ticket`
+run, which `append` reads itself off the member's report file
+(`<scratch>/reports/impl-<ticket>[-x].json`, its `sizing.verdict`, the highest
+retry letter's when there are several), so you pass no `--sizing`; the member
+also puts it in the PR body's `Sizing:` line, with the signal it turned on;
+`profile`, `loc` and `files` all come from `diff-stats.mjs` over the merged
+diff.

package/skills/run-team/references/shell-traps.md

@@ -2,12 +2,13 @@
 
 ## Shell traps
 
-Monitor and Bash commands run under **zsh**, and the shell in SKILL.md is
-prescriptive — copied verbatim into a watcher or into the merge bot's agent
-body. So every trap here is a zsh-vs-bash difference that ships as a
-green-looking gate: correct in the shell you tested in, silently wrong in the
-one it runs in. **Own the CI waits**'s monitor paragraph points here instead of
-restating any of it. The merge bot's agent body is the one place this block is
+Monitor and Bash commands run under **zsh**, and the shell in
+references/ci-watcher.md is prescriptive — copied verbatim into a watcher or
+into the merge bot's agent body. So every trap here is a zsh-vs-bash difference
+that ships as a green-looking gate: correct in the shell you tested in,
+silently wrong in the one it runs in. references/ci-watcher.md's monitor
+paragraph points here instead of restating any of it. The merge bot's agent
+body is the one place this block is
 copied whole (see **The merge bot**); the other deliberate copy is named at the end.
 
 A bot already looping cannot be corrected — the loop consumes the turns a correction would land in — so `agents/fleet-merge-bot.agent.md` carries **every entry in `references/shell-traps.md`'s Shell traps**, each written out in full: the rules with the measurements from that file beside them, and the bot has them before its first turn. An edit to `references/shell-traps.md` lands in that body in the same change.
@@ -28,13 +29,13 @@ $prs
 EOF
 ```
 
-The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what the watcher block under **Own the CI waits** uses, but it splits on *every* whitespace character, so it is safe only for values that cannot contain one — PR numbers cannot, branch names and paths can.
+The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what the watcher block in references/ci-watcher.md uses, but it splits on *every* whitespace character, so it is safe only for values that cannot contain one — PR numbers cannot, branch names and paths can.
 
 **`</dev/null` every command inside a `while read` loop.**
 
 **A probe that could not look emits an event; it never `continue`s.** Stated in
-full at *A probe that cannot read is a transition event, not silence* under **Own the CI waits**,
-and it binds every watcher in SKILL.md rather than that one block: the third
+full at *A probe that cannot read is a transition event, not silence* in references/ci-watcher.md,
+and it binds every watcher rather than that one block: the third
 value beside pass and fail is what turns a broken loop into a loud failure
 instead of a quiet one. A guard that drops an unreadable probe — `[ -n "$json" ]
 || continue` — makes *could not look* indistinguishable from *nothing to report*.

package/skills/run-team/references/tick-rows.md

@@ -253,3 +253,38 @@ the whole point: a table you must remember to consult is one you will not
 consult under a merge-side event storm, and that is how implementers reached
 0/target with ~57 `ready-for-agent` in supply while nobody
 noticed.
+
+## What the tick reads
+
+It reads the run itself, and nobody states a count. The In-flight count —
+every open PR that closes an issue off `gh`, plus every claimed ticket whose
+newest implementer is live or owed a replacement and has no such PR yet, off
+the ledger — sits beside the live review units (in-flight `review=` tokens
+plus unsettled `fix-pr-` ones), the merge bot, merge holds, tier mismatches
+and the drain marker, all off `.fleet/ledger.md`; the unclaimed heads and the
+supply come off `.fleet/shortlist.json`, which it refreshes itself when the
+unclaimed count is below the In-flight bound, when the file is missing or
+empty, when an Exclusion's premise has lifted, or when a branch-named
+`behind-pr` or a `behind-issue` Exclusion still not lifted names a ticket the
+file carries — never while the bound holds; the open PRs come off `gh`. A
+head whose Pull ended this run is not counted, unless on a lifted exclusion. A
+ledger token it
+cannot read, it refuses rather than guessing — a member counted live or gone on
+a guess is the over- or under-dispatch it exists to prevent — so correct that
+row with `ledger.mjs row` and tick again. The In-flight bound defaults to 5
+and is fixed for the run: pass `--in-flight` on every tick when `$ARGUMENTS`
+set it, and never otherwise.
+
+## Refresh is the tick's
+
+2. **Refresh is the tick's from here on.** `fleet-tick.mjs` runs
+   `shortlist.mjs` itself when unclaimed entries fall below the In-flight
+   bound, when the file is missing or empty, when an `excluded` premise has
+   lifted, and when a branch-named `behind-pr` exclusion whose PR is not yet
+   MERGED or CLOSED, or a `behind-issue` exclusion whose issue is not yet
+   closed, names a ticket the file still carries, and prints
+   `REFRESHED shortlist: <n> entries; <k> lifted`. A head whose Pull ended
+   this run is not counted, unless on a lifted exclusion. Phase 0 runs it by hand
+   once because a dead run's shortlist is stale by definition.
+   None of those triggers runs while `HOLD (in-flight <n>/<B>)` stands.
+