@feigi/fleet-ctl 3.127.1 → 3.127.3

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.
@@ -7,7 +7,7 @@ argument-hint: [pr-number]
7
7
 
8
8
  Label names in this file are roles; the Label map gives the string to type; a member never derives the map.
9
9
 
10
- **Standalone, before step 1, run the Label map derivation step:** `~/.fleet/bin/fleet-run label-map.mjs ensure`. Exit 0 → go on. Exit 3 → it printed the question payload: render it to the maintainer as one question — each uncertain role, its suggestion, why, the alternatives, ending "reply `defaults` to accept every suggestion, or name `<role>=<label>` for any you want otherwise" — wait for the answer, run `~/.fleet/bin/fleet-run label-map.mjs set --create` with it (`--accept-suggestions` for `defaults`), then `ensure` again, which now exits 0. Exit 1 or 2 → show what it printed and stop. **Dispatched as a fix-applier, you never run `ensure` and never ask:** your brief has you read the map instead, once, before your first edit or refuter dispatch, and a refusal there ends you with no report.
10
+ **Standalone, before step 1, run the Label map derivation step:** `~/.fleet/bin/fleet-run label-map.mjs ensure`. Exit 0 → go on. Exit 3 → it printed the question payload, whose `tableFile` is the path of the repository's triage-label table: render it to the maintainer as one question — each uncertain role, its suggestion, why (a role declared in the table but not in the tracker names `tableFile`), the alternatives, ending "reply `defaults` to accept every suggestion, or name `<role>=<label>` for any you want otherwise" — wait for the answer, run `~/.fleet/bin/fleet-run label-map.mjs set --create` with it (`--accept-suggestions` for `defaults`), then `ensure` again, which now exits 0. Exit 1 or 2 → show what it printed and stop. After that second `ensure`, tell the maintainer to add or edit the role's row in the file `tableFile` names; never write that table yourself. **Dispatched as a fix-applier, you never run `ensure` and never ask:** your brief has you read the map instead, once, before your first edit or refuter dispatch, and a refusal there ends you with no report.
11
11
 
12
12
  `<needs-triage string>`, `<wontfix string>` and `<ready-to-merge string>` below are what `~/.fleet/bin/fleet-run label-map.mjs show <role>` prints for that role.
13
13
 
@@ -27,7 +27,7 @@ Label names in this file are roles; the Label map gives the string to type; a me
27
27
  **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 `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.
28
28
  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` only to a dependabot or renovate PR that has none, and hard-fails any PR with none or 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. The prefix `ready-to-merge-head:` is not a label: type it as written, whatever string the Label map gives `ready-to-merge`. Then `gh pr edit <pr> --add-label "<ready-to-merge string>"`. 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.
29
29
 
30
- **`verdict: "no-ci"` — this repo has no `check` job to gate on at all**, and that is a different state from red or unknown, not a third way to skip the wait. Label off step 3's own green `testCmd` run instead of a `check` job that will never exist — and only once `ci-state.mjs` reads `no-ci` **without** the flag, since a repo whose CI is merely misconfigured exits 2 there rather than reading no-ci. `--declare-no-ci` is your caller-side declaration that step 3's run **is** this repo's gate: it flips the exit code and echoes itself into `reasons`, so finding it in the payload confirms only that you passed it, never that anyone verified anything. **No green `testCmd` run on record → do not label.** Say in your verdict that the repo has no CI configured and no declaration, and stop — inferring a pass from silence here is exactly the misconfigured-CI case the declaration exists to rule out. See `ci-state.mjs --pr <n> --declare-no-ci` below.
30
+ **`verdict: "no-ci"` — this repo has no `check` job to gate on at all**, and that is a different state from red or unknown, not a third way to skip the wait. Label off step 3's own green `testCmd` run instead of a `check` job that will never exist — and only once `ci-state.mjs` reads `no-ci` **without** the flag, since a repo whose CI is merely misconfigured exits 2 there rather than reading no-ci. `--declare-no-ci` is your caller-side declaration that step 3's run **is** this repo's gate: it flips the exit code and echoes itself into `reasons`, so finding it in the payload confirms only that you passed it, never that anyone verified anything. **No green `testCmd` run on record → do not label.** Say in your verdict that the repo has no CI configured and no declaration, and stop — inferring a pass from silence here is exactly the misconfigured-CI case the declaration exists to rule out.
31
31
 
32
32
  **Bind green to the *run*, not to check conclusions.** `gh pr checks` aggregates across runs and reports a `pass` inherited from a **cancelled** run on a superseded SHA. Head-SHA binding misses it — the head is genuinely right; only the conclusions belong to another commit.
33
33
 
@@ -41,11 +41,11 @@ Label names in this file are roles; the Label map gives the string to type; a me
41
41
 
42
42
  **Query at labelling time; never label off a watcher's summary.** A monitor stitches its event from reads taken at different moments, so it can stream `RUN COMPLETE: success` under a run id whose authoritative job list is a failure — observed: streamed all-five-green for run `165158547`, while `gh run view 165158547 --json jobs` reported `rebase-check failure` with three jobs **skipped**; the green belonged to the previous run on an earlier head. Head-SHA binding does not catch this, because the *run id* is wrong rather than the head. Watchers are for waking you up, never for deciding.
43
43
 
44
- **A conclusion is not stable even for a fixed run id on an unchanged head.** A rerun rewrites the existing run in place instead of creating a new one, so a run you read as `success` can later read `failure` with nothing pushed. Observed twice in one run, on two PRs: a refresh workflow re-ran the currency check after `main` advanced and flipped the same id on the same SHA. So a cached conclusion is not merely stale, it can be *inverted* — re-query at the moment you decide. Also note the newest run on a branch is often a label or policy workflow rather than CI, so `--limit 1` can hide the CI result entirely.
44
+ **A conclusion is not stable even for a fixed run id on an unchanged head.** A rerun rewrites the existing run in place instead of creating a new one, so a run you read as `success` can later read `failure` with nothing pushed. Observed: a refresh workflow re-ran the currency check after `main` advanced and flipped the same id on the same SHA. So a cached conclusion is not merely stale, it can be *inverted* — re-query at the moment you decide. The newest run on a branch is often a label or policy workflow rather than CI, so `--limit 1` can hide the CI result entirely.
45
45
 
46
46
  **`skipped` is not `passed`**. When the currency check fails, the heavy jobs report `skipped` — they did **not** execute. A board of `check: success` / currency `failure` / three `skipped` reads as "nearly green" and is in fact *three required suites unverified*. That is not grounds to withhold the label (see below), but if you label under it, say the label rests on the checks that actually ran plus your own verification — never call it "CI green".
47
47
 
48
- **Do NOT rebase to label**, and do not require a zero behind-count. Your green proves the diff is sound *against the base it was tested on* — that is what the label attests, and it does not expire. Requiring currency forces a full CI cycle every time any sibling lands (six wasted cycles in one run) and re-establishes nothing the merge bot will not. Rebase only when pushing a change, or when the PR is put on a conflict hold — the bot bouncing it back, or the controller recording one off the tick's `CONFLICT` line once GitHub reads the PR CONFLICTING.
48
+ **Do NOT rebase to label**, and do not require a zero behind-count. Your green proves the diff is sound *against the base it was tested on* — that is what the label attests, and it does not expire. Requiring currency forces a full CI cycle every time any sibling lands and re-establishes nothing the merge bot will not. Rebase only when pushing a change, or when the PR is put on a conflict hold — the bot bouncing it back, or the controller recording one off the tick's `CONFLICT` line once GitHub reads the PR CONFLICTING.
49
49
 
50
50
  Three claims, none substituting for another: **run-binding** (this green belongs to this SHA) · **your green** (correct against its base) · **the bot's post-rebase green** (still correct against current `main`). Only the third catches a sibling renaming a symbol you use — a rebase can apply cleanly and still break the build, which is why it is the bot's job and not yours.
51
51
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.127.1",
3
+ "version": "3.127.3",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {