@feigi/fleet-ctl 3.48.1 → 3.49.1
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.
|
@@ -13,7 +13,7 @@ argument-hint: [pr-number]
|
|
|
13
13
|
2. Plan the actions. Split explicitly into **apply now** / **defer**. A finding is deferred, never dropped. **Every `suggestion` — the review's `severity`, the plugin's *Suggestions* bucket — arrives unchecked: the review budgets that band 0 refuters, so nothing has looked at it yet.** Checking it is now your job, not nobody's. So split it by SCOPE first, and check it in either scope. Out of the PR's ticket scope → defer and file, but **the claim bar runs first:** a suggestion whose claim is about shape — step 5's worth-a-claim bar, recorded `claimKind: shape` — gets no refuter and goes to the closed `PR #<pr> review: the suggestion band, checked` record, and every other out-of-scope suggestion gets the same refuter an in-scope one does, dispatched the same way, before it is filed. In scope → dispatch one refuter against it, biased to refuse, and hand it this instruction verbatim with one substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path under your own run root — `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids restart at 1 each round too — and write that absolute path into the refuter's prompt in its place; a refuter never derives its own path, and tell it your step-3 `testCmd`, which its rules call `<testCmd>`: *Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by RUNNING something — compile it, run the test, apply the mutation. Do not reason your way to agreement. Observe that run synchronously — run the command, wait for it, read its exit code. Never poll a log file for a completion marker: prefer ONE blocking run to a poll loop, and treat its return as permission to look, never as the answer. Reading a log the run has already finished writing is fine; waiting on one is not. If you match a test reporter's own output, accepting both `ℹ` and `#` is necessary but NOT sufficient — strip SGR escapes first as well. node's prefix moves with the node version and with whether stdout is a TTY, and color wraps the whole line so it begins with ESC and no prefix anchor matches at all, which returns empty at exit 0 — indistinguishable from a hung run and from a run of zero tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=` empty still enables color, so it is not a control. State your search scope AND what your pattern would have missed. A grep over one ref does not support a claim about history; a pattern built from the token a diff removed does not support a claim that the category is empty. When your check scores a mutant killed or a test red, run only in your own copy of the tree, and these rules decide it and nothing else: Valid red: a run that completed — the command returned on its own, with no signal and no timeout, deadline or kill having fired — in which the test the claim names is reported failing. An exit ≠ 0 with no failing test is not red, and a different test failing is not red for this claim. A red in the full suite only triggers a narrowed run; it is never evidence on its own. Narrowed run: the Test entrypoint with arguments appended, `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all that is promised about them, so a narrowed run counts only if it reports `tests` > 0 and its output names the claimed test. If no narrowing can be proven, run the full `<testCmd>` and read the named test's own result from its output. Kill: the mutant produced a valid red in a narrowed run, and the same narrowed command, in the same tree with the mutant reverted, ran a valid green with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A completed exit ≠ 0 with the named test not failing is not a kill, and no kill stands without that green run on the unmutated tree. The result is inconclusive, never a kill, when the red does not reproduce in the narrowed run, when the unmutated tree is red too, or when no usable run exists. Evidence line: every kill and every valid red you claim carries one line in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the review's shared run carries the `red:` half alone. This refuter has no abstain: a run that could not decide — neither a valid red nor a valid green — is no kill and no refutation, so name the runs in `reason`, each with its evidence line, and leave `refuted` true, so the suggestion defers on the record instead of applying on a check that decided nothing. A failure injection with no positive control has produced NO result, never a negative one. Before you read an injected fault — an env var, an argv word, a mutant — as having had no effect, prove the injection reached the child: one run whose output differs with it present versus absent, or the child echoing the injected value back. Uncontrolled, the cell is unrun — say so in your verdict instead of reporting a no-effect result. Build such an invocation as an array expanded braced and quoted — `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable spelling either: measured, bash word-splits it into `SETB=1` and `BADJ=1[@]`, so the injection variable is set to a corrupted value, while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0. Everything you write — mutants, fixtures, scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else; the checkout and any worktree are never write targets, though `git show`/`git archive` at a pinned ref read fine anywhere. Chain the directory change into the command, `cd "$D" && git …`, never `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in the checkout — and bracket a fixture's own git with `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to the host repository, and `fatal: not a git repository` (exit 128) is the usual pass, not a failure — an outer repository whose ignore rules cover your scratch dir is a pass too; before any `git commit` it must resolve to your scratch path, which catches a forgotten `git init` under any enclosing repository — compare resolved forms (`realpath`), since `--show-toplevel` can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under its resolved name.* That last clause is the whole mechanism — a refuter left to reason its way to agreement rubber-stamps, and "apply only what survives" silently degrades into "apply everything in scope". Apply only what survives; a refuted one defers with the refutation in its body. **Out of scope the refuter decides only where the suggestion is filed — it defers either way, never applied.** Refuted → the closed `PR #<pr> review: the suggestion band, checked` record, never an open issue. Survived, or its refuter crashed or abstained → its own open issue labelled `needs-triage`, citing the verdict, or the run that crashed, in the body. There is no cap on these refuters; your final verdict (step 4) says how many you dispatched against out-of-scope suggestions. "In scope" means the ticket's scope, not merely the same files — and applying one still never licenses editing a file the ticket has no business in. **A finding in `unverified` whose refuters ran and crashed or abstained always defers, whatever its severity** — and which it is, you read off the finding's **`refutersDispatched`** and **`refutersInconclusive`**, never off severity and never off an empty vote list: `refutersDispatched` above zero with nothing decided means every refuter dispatched against it died or abstained, and `refutersInconclusive` counts the ones that abstained. Only a `survived` finding has been checked; severity says how much a finding would matter if true, never whether anything looked. **Deferring a crash is your move, and re-running it is not** — the review already re-dispatched every crashed refuter pair once, in-run, so a crash that reaches you crashed twice, and the result's `resume` field names the one move left, which is not yours: nothing replays a review that ran in a runner's kernel — it is reported, not acted on. So say *in the deferral* that its refuters crashed rather than that it went unchecked, and re-run nothing for it. **An abstention is not a crash** — a refuter that abstained ran and could not decide: defer and file the finding, citing the inconclusive runs each abstaining refuter named in its `reason`, and never describe its refuters as crashed. **A `suggestion` is also in `unverified`, for a different reason — `refutersDispatched` of zero, the 0-refuter budget the workflow gives that band by policy, so nothing looked *there* — and the scope split above, not this rule, covers it.**
|
|
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
|
-
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
|
|
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
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.
|
|
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.
|
|
@@ -70,15 +70,14 @@ jq '.refuted' "$R" # refuted: your
|
|
|
70
70
|
|
|
71
71
|
## Specialists
|
|
72
72
|
|
|
73
|
-
**The controller runs the review; everything below is the fallback for
|
|
73
|
+
**The controller runs the review; everything below is the hand-dispatch fallback for a standalone session with no `eval` access.**
|
|
74
74
|
|
|
75
75
|
`eval` loading `scripts/review-eval.mjs` through the Resolver (`fleet-run --path review-eval.mjs`) and calling `runReviewOnOmp({pr, branch, worktree, testCmd, scratch})` is the fleet's **default** review path. Its `scratch` is the scratch root, never `<scratch>/pr<N>`: the review creates that partition itself and refuses a `scratch` already ending in one, or one that is not an absolute path.
|
|
76
76
|
|
|
77
|
-
`$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s Reviewers section owns its dispatch. It cuts the snapshot, sizes the fan-out, adversarially verifies every **critical/important** finding, and has `agent()` return **into the script**, so no report can go undelivered, the failure that cost one fleet five reports on one PR and four on another. It does **not** verify the `suggestion` band — that gets 0 refuters by policy, which is why step 2 checks each one itself — an in-scope one before applying it, an out-of-scope one above the claim bar before filing it. **You cannot run it** — the one member that runs it is the `review-pr-<pr#>` runner (`agents/fleet-review-runner.agent.md`), never a reader of this file
|
|
77
|
+
`$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s Reviewers section owns its dispatch. It cuts the snapshot, sizes the fan-out, adversarially verifies every **critical/important** finding, and has `agent()` return **into the script**, so no report can go undelivered, the failure that cost one fleet five reports on one PR and four on another. It does **not** verify the `suggestion` band — that gets 0 refuters by policy, which is why step 2 checks each one itself — an in-scope one before applying it, an out-of-scope one above the claim bar before filing it. **You cannot run it** — the one member that runs it is the `review-pr-<pr#>` runner (`agents/fleet-review-runner.agent.md`), never a reader of this file.
|
|
78
78
|
|
|
79
79
|
It cannot ask the user anything and cannot wait on CI — rebasing, watching checks, binding and labelling stay here.
|
|
80
80
|
|
|
81
|
-
- **A depth-2 member cannot dispatch** (`task.maxRecursionDepth: 2`): if `task` is absent at your depth, ask the controller to dispatch the specialists and relay their reports; never downgrade to a solo review.
|
|
82
81
|
- **Say read-only.** No `fleet-review-*` definition's frontmatter restricts tool access — a `.agent.md` prompt saying "report only" is instruction, not enforcement — so an agent hand-dispatched here, named or general-purpose, has write tools it must not use: one committed and pushed during a report-only dispatch. No commits, no pushes, no worktree edits.
|
|
83
82
|
- **Cut TWO trees, not one — a shared snapshot is not enough.** Mutation probing is a *write*, so a mutating specialist and read-only specialists cannot share a copy: the readers then observe the mutant exactly as if it were real code. Give them `snap-ro`, pristine and **never written**, and one private copy **per mutating specialist**. Keep every one out of the worktree. Observed with a single shared snapshot: three specialists read two *different* in-flight mutations, one reporting the PR's own bug as still present; elsewhere three watched their file go clean → `M` mid-analysis; twice a reviewer came one step from filing a false finding. Reverting a probe does not help — it leaves a window where every concurrent reader sees a lie, and serializing does not close it because readers are concurrent with the *mutator*.
|
|
84
83
|
- **Do not trust the obvious contamination check.** `diff -rq` and `md5` against the mutating tree both returned *clean* — because the probe had been reverted between the two reads. A clean diff against a live tree is not evidence in either direction; only `snap-ro` and the object store settle it.
|
package/package.json
CHANGED
package/scripts/fleet-tick.mjs
CHANGED
|
@@ -392,13 +392,13 @@ export class LedgerError extends Error {}
|
|
|
392
392
|
// nothing can tell which review a dispositions verdict answered. Only a ledger
|
|
393
393
|
// written before the plugin update and read after it can hold one.
|
|
394
394
|
const REVIEWED_RUNLESS = /^reviewed=[0-9a-fA-F]{7,40}:\d+\/\d+\/\d+$/;
|
|
395
|
-
const HELD = /^held-behind[:-]#?(\d+)$/;
|
|
395
|
+
export const HELD = /^held-behind[:-]#?(\d+)$/;
|
|
396
396
|
// The durable record that a PR conflicts — written onto the held PR's own
|
|
397
397
|
// row by the merge bot, when its local-rebase fallback hits a conflict it would
|
|
398
398
|
// not force, or by the controller off this tick's `CONFLICT` line — and
|
|
399
399
|
// spelled like `held-behind` so the two read alike. Distinct from an
|
|
400
400
|
// Exclusion, which gates a ticket's claim; this gates a PR's merge.
|
|
401
|
-
const CONFLICT_HOLD = /^conflict-hold[:-]#?(\d+)$/;
|
|
401
|
+
export const CONFLICT_HOLD = /^conflict-hold[:-]#?(\d+)$/;
|
|
402
402
|
// tier-check.mjs's verdict on an implementer, `tier-ok=<member>:<def>`
|
|
403
403
|
// or `tier-mismatch=<member>:<def>` — or `tier-unverifiable=<member>:no-transcript`
|
|
404
404
|
// for a settled member whose transcript was never written.
|
|
@@ -198,7 +198,7 @@ function readReviews(tokens) {
|
|
|
198
198
|
|
|
199
199
|
// The entries of `after` that `before` does not account for, counting
|
|
200
200
|
// duplicates: what a write added.
|
|
201
|
-
function added(before, after) {
|
|
201
|
+
export function added(before, after) {
|
|
202
202
|
const left = new Map();
|
|
203
203
|
for (const x of before) left.set(x, (left.get(x) ?? 0) + 1);
|
|
204
204
|
return after.filter((x) => {
|
package/scripts/ledger.mjs
CHANGED
|
@@ -4,7 +4,8 @@
|
|
|
4
4
|
// redoes finished work. Two duplicate tickets shipped in one run from exactly
|
|
5
5
|
// that.
|
|
6
6
|
//
|
|
7
|
-
// Rows are rewritten in place, one per ticket
|
|
7
|
+
// Rows are rewritten in place, one per ticket: `row` replaces a whole line
|
|
8
|
+
// and `token` appends tokens to one. `filed` and `ruled` are
|
|
8
9
|
// append-only, because their whole purpose is to outlive the reasoning that
|
|
9
10
|
// produced them; `filed` appends at most one row per issue.
|
|
10
11
|
//
|
|
@@ -25,7 +26,7 @@
|
|
|
25
26
|
// `## Retired`, where `dispatch` and that numbering still read it.
|
|
26
27
|
//
|
|
27
28
|
// Writer policy: the controller owns run state
|
|
28
|
-
// (`row`/`settle`/`dispatch`/`review`/`drain`/`ruled`/`rotate`); filers append
|
|
29
|
+
// (`row`/`token`/`settle`/`dispatch`/`review`/`drain`/`ruled`/`rotate`); filers append
|
|
29
30
|
// filings with `filed`; all writes are serialized by `<file>.lock`. Every
|
|
30
31
|
// write subcommand except `rotate` — which moves the file whole and never
|
|
31
32
|
// loads it, see runRotate() — rewrites the WHOLE file from what it loaded,
|
|
@@ -46,8 +47,8 @@ import { fileURLToPath } from "node:url";
|
|
|
46
47
|
import { spawnSync, execFileSync } from "node:child_process";
|
|
47
48
|
import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
|
|
48
49
|
import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
|
|
49
|
-
import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, premisesOf, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
|
|
50
|
-
import { deriveRun, LedgerError, labelOffMember } from "./fleet-tick.mjs";
|
|
50
|
+
import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
|
|
51
|
+
import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD } from "./fleet-tick.mjs";
|
|
51
52
|
import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
|
|
52
53
|
import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
|
|
53
54
|
import { attemptLock, releaseLockFile, reapPathOf } from "./pid-lock.mjs";
|
|
@@ -168,6 +169,9 @@ function defaultLedgerPath() {
|
|
|
168
169
|
}
|
|
169
170
|
}
|
|
170
171
|
|
|
172
|
+
// What `row` and `token` say of a `label-off=` naming no finisher this run has.
|
|
173
|
+
const LABEL_OFF_UNKNOWN = "names no finisher-pr member this run has dispatched or recorded — label-off=<finisher-pr-M[-x]>, the latest finisher attempt, before taking ready-to-merge off PR M";
|
|
174
|
+
|
|
171
175
|
const argv = process.argv.slice(2);
|
|
172
176
|
// Both flags are read by EXACT token below (`indexOf`), so the `--flag=value`
|
|
173
177
|
// spelling matches neither — and an unmatched token is not refused, it lands
|
|
@@ -236,7 +240,7 @@ const requireFile = requireFileIdx !== -1;
|
|
|
236
240
|
if (requireFileIdx !== -1) argv.splice(requireFileIdx, 1);
|
|
237
241
|
|
|
238
242
|
const [cmd, ...rest] = argv;
|
|
239
|
-
if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|filed|ruled|check|read|dispatch|settle|review|drain|rotate [args]");
|
|
243
|
+
if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|token|filed|ruled|check|read|dispatch|settle|review|drain|rotate [args]");
|
|
240
244
|
|
|
241
245
|
// A `--`-prefixed token in `check`'s free-text tail used to fold
|
|
242
246
|
// straight into the duplicate-filing subject, so a misspelled flag searched
|
|
@@ -645,7 +649,7 @@ async function acquireLock() {
|
|
|
645
649
|
// so a caller gating on the exit code reads the same failure either way.
|
|
646
650
|
if (requireFile && !existsSync(file)) die(`--require-file given but ledger file does not exist: ${file}`);
|
|
647
651
|
|
|
648
|
-
const WRITE_COMMANDS = new Set(["row", "filed", "ruled", "dispatch", "settle", "review", "drain", "rotate"]);
|
|
652
|
+
const WRITE_COMMANDS = new Set(["row", "token", "filed", "ruled", "dispatch", "settle", "review", "drain", "rotate"]);
|
|
649
653
|
if (WRITE_COMMANDS.has(cmd)) await acquireLock();
|
|
650
654
|
// `rotate` never load()s: a ledger load() would refuse is still the previous
|
|
651
655
|
// run's record, and it is archived as-is — and read line by line when it
|
|
@@ -706,18 +710,10 @@ if (cmd === "read") {
|
|
|
706
710
|
// `label-off=<attempt>` tells the tick a missing `ready-to-merge` is
|
|
707
711
|
// the controller's own removal, not a finisher's miss — so one naming no
|
|
708
712
|
// finisher-pr member this run has would mask a real miss behind a record of
|
|
709
|
-
// nothing
|
|
710
|
-
|
|
711
|
-
// reads: a token `row` wrote never enters `## Dispatched`, and this line's
|
|
712
|
-
// own copy of a name vouches for nothing. Local only — never `gh`.
|
|
713
|
-
const known = new Set([...data.dispatched.map(parseToken), ...data.rows.flatMap(memberTokens)]
|
|
714
|
-
.filter((t) => t && t.family === "finisher-pr").map((t) => t.name));
|
|
715
|
-
const badOff = line.split(/\s+/).find((tok) => {
|
|
716
|
-
const m = labelOffMember(tok);
|
|
717
|
-
return m === null || (m !== undefined && !known.has(m.name));
|
|
718
|
-
});
|
|
713
|
+
// nothing; see badLabelOff().
|
|
714
|
+
const badOff = badLabelOff(line.split(/\s+/));
|
|
719
715
|
if (badOff !== undefined) {
|
|
720
|
-
die(`row ${key}: '${badOff}'
|
|
716
|
+
die(`row ${key}: '${badOff}' ${LABEL_OFF_UNKNOWN}`);
|
|
721
717
|
}
|
|
722
718
|
const i = data.rows.findIndex((r) => r.split(/\s/)[0] === key);
|
|
723
719
|
const created = i === -1;
|
|
@@ -748,7 +744,15 @@ if (cmd === "read") {
|
|
|
748
744
|
// Logged only after save() returns — a failed write must not claim a row
|
|
749
745
|
// was recorded when it never made it to disk.
|
|
750
746
|
save(data);
|
|
751
|
-
|
|
747
|
+
// A rewrite loses every token the new text does not repeat, so the ones it
|
|
748
|
+
// lost are named: the controller learns of a dropped `ports=` or `→ PR#`
|
|
749
|
+
// here and not from a later reader that finds it missing.
|
|
750
|
+
if (created) {
|
|
751
|
+
console.error(` new row ${key}`);
|
|
752
|
+
} else {
|
|
753
|
+
const dropped = droppedTokens(oldRow, line);
|
|
754
|
+
console.error(` rewrote row ${key}${dropped.length === 0 ? "" : `; dropped: ${dropped.join(" ")}`}`);
|
|
755
|
+
}
|
|
752
756
|
console.log(JSON.stringify({ ticket: key, line, created }));
|
|
753
757
|
} else if (cmd === "filed") {
|
|
754
758
|
const [issue, ...subjectParts] = rest;
|
|
@@ -802,6 +806,8 @@ if (cmd === "read") {
|
|
|
802
806
|
runDispatch();
|
|
803
807
|
} else if (cmd === "settle") {
|
|
804
808
|
runSettle();
|
|
809
|
+
} else if (cmd === "token") {
|
|
810
|
+
runToken();
|
|
805
811
|
} else if (cmd === "review") {
|
|
806
812
|
runReview();
|
|
807
813
|
} else if (cmd === "drain") {
|
|
@@ -825,7 +831,7 @@ if (cmd === "read") {
|
|
|
825
831
|
if (rest.length) die("usage: ledger.mjs rotate");
|
|
826
832
|
runRotate();
|
|
827
833
|
} else {
|
|
828
|
-
die(`unknown subcommand '${cmd}' — expected row, filed, ruled, check, read, dispatch, settle, review, drain or rotate`);
|
|
834
|
+
die(`unknown subcommand '${cmd}' — expected row, token, filed, ruled, check, read, dispatch, settle, review, drain or rotate`);
|
|
829
835
|
}
|
|
830
836
|
|
|
831
837
|
// Reached only by an arm that did not die, so every write subcommand that did
|
|
@@ -2015,6 +2021,15 @@ function runSettle() {
|
|
|
2015
2021
|
console.log(JSON.stringify(payload(i, true)));
|
|
2016
2022
|
}
|
|
2017
2023
|
|
|
2024
|
+
// A ticket or PR number argument as a number: a leading `#` is allowed, a
|
|
2025
|
+
// stray flag or anything but digits refused, saying `what` was expected.
|
|
2026
|
+
function numberArg(arg, what, usage) {
|
|
2027
|
+
refuseStrayInId(arg, what);
|
|
2028
|
+
const digits = arg.replace(/^#/, "");
|
|
2029
|
+
if (!isDigits(digits)) die(`'${arg}' is not ${what} — ${usage}`);
|
|
2030
|
+
return Number(digits);
|
|
2031
|
+
}
|
|
2032
|
+
|
|
2018
2033
|
// `review <pr> <token>…`: the only writer of a PR's `review=`/`reviewed=`
|
|
2019
2034
|
// tokens. Each lands on the PR's row — the ticket row once `settle
|
|
2020
2035
|
// impl-<N>=PR#M` has run, else `#M`, created when neither exists — so the
|
|
@@ -2027,10 +2042,7 @@ function runReview() {
|
|
|
2027
2042
|
const usage = "usage: ledger.mjs review <pr> <review=…|reviewed=…>…";
|
|
2028
2043
|
const [pr, ...parts] = rest;
|
|
2029
2044
|
if (!pr || parts.length === 0) die(usage);
|
|
2030
|
-
|
|
2031
|
-
const digits = pr.replace(/^#/, "");
|
|
2032
|
-
if (!isDigits(digits)) die(`'${pr}' is not a PR number — ${usage}`);
|
|
2033
|
-
const prNum = Number(digits);
|
|
2045
|
+
const prNum = numberArg(pr, "a PR number", usage);
|
|
2034
2046
|
const tokens = parts.join(" ").split(/\s+/).filter(Boolean);
|
|
2035
2047
|
const other = tokens.find((tok) => !isReviewToken(tok));
|
|
2036
2048
|
if (other !== undefined) {
|
|
@@ -2059,3 +2071,122 @@ function runReview() {
|
|
|
2059
2071
|
console.error(` review on row ${key}`);
|
|
2060
2072
|
console.log(JSON.stringify({ pr: prNum, row: key, line, created }));
|
|
2061
2073
|
}
|
|
2074
|
+
|
|
2075
|
+
// A row's tokens: its words after the key, bar the ` · ` separators between
|
|
2076
|
+
// them.
|
|
2077
|
+
function rowTokens(text) {
|
|
2078
|
+
return text.split(/\s+/).filter((w) => w !== "" && w !== "·").slice(1);
|
|
2079
|
+
}
|
|
2080
|
+
|
|
2081
|
+
// Every token `oldRow` had that `line` lacks, duplicates counted, in the old
|
|
2082
|
+
// row's order: what a `row` rewrite lost.
|
|
2083
|
+
function droppedTokens(oldRow, line) {
|
|
2084
|
+
return added(rowTokens(line), rowTokens(oldRow));
|
|
2085
|
+
}
|
|
2086
|
+
|
|
2087
|
+
// The first of `words` that is a `label-off=` naming no finisher-pr member
|
|
2088
|
+
// this run has, else undefined. Known means in `## Dispatched` or among a
|
|
2089
|
+
// row's member tokens as they stand before this write, the two places
|
|
2090
|
+
// dispatch's live-sibling check reads: a token `row` or `token` wrote never
|
|
2091
|
+
// enters `## Dispatched`, and the line being written vouches for nothing.
|
|
2092
|
+
// Local only — never `gh`.
|
|
2093
|
+
function badLabelOff(words) {
|
|
2094
|
+
const known = new Set([...data.dispatched.map(parseToken), ...data.rows.flatMap(memberTokens)]
|
|
2095
|
+
.filter((t) => t && t.family === "finisher-pr").map((t) => t.name));
|
|
2096
|
+
return words.find((tok) => {
|
|
2097
|
+
const m = labelOffMember(tok);
|
|
2098
|
+
return m === null || (m !== undefined && !known.has(m.name));
|
|
2099
|
+
});
|
|
2100
|
+
}
|
|
2101
|
+
|
|
2102
|
+
// Why `token` may not write `tok` onto a row whose text is `rowText` (the row
|
|
2103
|
+
// as it stands plus the call's earlier tokens), or null when it may. A token
|
|
2104
|
+
// is one word: an empty argument, one with a space in it (prose, which would
|
|
2105
|
+
// split into words the row's own words then dedupe against), and the row's
|
|
2106
|
+
// ` · ` separator are no token. A member token is `dispatch`'s or `settle`'s,
|
|
2107
|
+
// a review token `review`'s. A word shaped like a member that the grammar
|
|
2108
|
+
// cannot parse, a `tier=` that is not a cell, a `tier=` naming a second tier
|
|
2109
|
+
// on a row that already has one, a `held-behind` or `conflict-hold` token the
|
|
2110
|
+
// tick cannot read, and a lone `→` — an arrow with no PR beside it points at
|
|
2111
|
+
// nothing — are refused. Every other word is a freeform token.
|
|
2112
|
+
function tokenRefusal(tok, rowText) {
|
|
2113
|
+
if (tok === "" || /\s/.test(tok)) {
|
|
2114
|
+
return "is not one token — pass each token as its own argument, with no space in it";
|
|
2115
|
+
}
|
|
2116
|
+
if (tok === "·") return "is the row's ` · ` separator, which `token` writes between tokens itself";
|
|
2117
|
+
if (parseToken(tok) !== null) {
|
|
2118
|
+
return "is a member token — members are written only with `ledger.mjs dispatch` and `ledger.mjs settle`";
|
|
2119
|
+
}
|
|
2120
|
+
if (isReviewToken(tok)) {
|
|
2121
|
+
return "is a review token — review tokens are written only with `ledger.mjs review <pr> <token>…`, which puts them on the PR's row";
|
|
2122
|
+
}
|
|
2123
|
+
const name = tok.split("=")[0];
|
|
2124
|
+
if (MEMBER_FAMILIES.some((family) => name.startsWith(`${family}-`))) {
|
|
2125
|
+
return "is shaped like a member token this grammar cannot parse — a member is impl-<N>, fix-pr-<M>, finisher-pr-<M> or merge-bot-<n>, a retry suffix allowed";
|
|
2126
|
+
}
|
|
2127
|
+
for (const [prefix, shape] of [["held-behind", HELD], ["conflict-hold", CONFLICT_HOLD]]) {
|
|
2128
|
+
if (tok.startsWith(prefix) && !shape.test(tok)) {
|
|
2129
|
+
return `is not ${prefix}:#<M> — the tick reads only ${prefix}:#<number> and would ignore this one`;
|
|
2130
|
+
}
|
|
2131
|
+
}
|
|
2132
|
+
const [tier] = tierValues(tok);
|
|
2133
|
+
if (tier !== undefined) {
|
|
2134
|
+
if (!CELL.test(tier)) return "is not tier=<cell> — a cell is <slow|task|smol>-<level>";
|
|
2135
|
+
const other = tierValues(rowText).find((v) => v !== tier);
|
|
2136
|
+
if (other !== undefined) {
|
|
2137
|
+
return `names a second tier — the row already carries tier=${other}, and a row names one; replacing it takes ledger.mjs row, which rewrites the whole line`;
|
|
2138
|
+
}
|
|
2139
|
+
}
|
|
2140
|
+
if (tok === "→") return "is the row's arrow, which is written with the PR it points at — ledger.mjs row writes the whole line";
|
|
2141
|
+
if (badLabelOff([tok]) !== undefined) return LABEL_OFF_UNKNOWN;
|
|
2142
|
+
return null;
|
|
2143
|
+
}
|
|
2144
|
+
|
|
2145
|
+
// `token <ticket|pr> <token>…`: appends each token to the row the key maps to
|
|
2146
|
+
// — the PR's row for a PR key, the ticket row once `settle impl-<N>=PR#M` has
|
|
2147
|
+
// run, else `#M`, created when neither exists: `review`'s lookup — keeping
|
|
2148
|
+
// every token already there, in order, as ` · <token>`. A token the row
|
|
2149
|
+
// already carries is a no-op. Every refusal is judged before anything is
|
|
2150
|
+
// written, whole call alike, under the lock.
|
|
2151
|
+
function runToken() {
|
|
2152
|
+
const usage = "usage: ledger.mjs token <ticket|pr> <token>…";
|
|
2153
|
+
const [keyArg, ...tokens] = rest;
|
|
2154
|
+
if (!keyArg || tokens.length === 0) die(usage);
|
|
2155
|
+
const num = numberArg(keyArg, "a ticket or PR number", usage);
|
|
2156
|
+
const i = prRowIndex(num);
|
|
2157
|
+
const created = i === -1;
|
|
2158
|
+
const oldLine = created ? null : data.rows[i];
|
|
2159
|
+
let carried = oldLine ?? "";
|
|
2160
|
+
for (const tok of tokens) {
|
|
2161
|
+
const why = tokenRefusal(tok, carried);
|
|
2162
|
+
if (why !== null) die(`token #${num}: '${tok}' ${why}`);
|
|
2163
|
+
carried += ` ${tok}`;
|
|
2164
|
+
}
|
|
2165
|
+
const key = created ? `#${num}` : rowKey(oldLine);
|
|
2166
|
+
const have = new Set(created ? [] : rowTokens(oldLine));
|
|
2167
|
+
const appended = [];
|
|
2168
|
+
for (const tok of tokens) {
|
|
2169
|
+
if (have.has(tok)) {
|
|
2170
|
+
console.error(` already present on row ${key}: ${tok}`);
|
|
2171
|
+
} else {
|
|
2172
|
+
have.add(tok);
|
|
2173
|
+
appended.push(tok);
|
|
2174
|
+
}
|
|
2175
|
+
}
|
|
2176
|
+
if (appended.length === 0) {
|
|
2177
|
+
console.log(JSON.stringify({ key, line: oldLine, added: appended }));
|
|
2178
|
+
return;
|
|
2179
|
+
}
|
|
2180
|
+
const line = created ? `${key} ${appended.join(" · ")}` : `${oldLine} · ${appended.join(" · ")}`;
|
|
2181
|
+
const after = created ? [...data.rows, line] : data.rows.with(i, line);
|
|
2182
|
+
// A freeform token can still move the PR a row maps to (a `PR#<n>` mention
|
|
2183
|
+
// on a row with no implementer), or split one PR across two rows.
|
|
2184
|
+
const split = newSplitRow(data.rows, after);
|
|
2185
|
+
if (split !== null) die(`token ${key}: ${splitRowClause(split)}`);
|
|
2186
|
+
const refusal = rowWriteRefusal(data.rows, after, oldLine, line, data.retired);
|
|
2187
|
+
if (refusal !== null) die(`token ${key}: ${refusal}`);
|
|
2188
|
+
data.rows = after;
|
|
2189
|
+
save(data);
|
|
2190
|
+
console.error(` appended ${appended.join(" ")} to row ${key}`);
|
|
2191
|
+
console.log(JSON.stringify({ key, line, added: appended }));
|
|
2192
|
+
}
|
package/skills/run-team/SKILL.md
CHANGED
|
@@ -73,10 +73,6 @@ Names follow the unit of work: `impl-<issue#>`, `fix-pr-<pr#>`,
|
|
|
73
73
|
`review-pr-<pr#>`, `finisher-pr-<pr#>`, `merge-bot-<n>`. See
|
|
74
74
|
references/member-lifecycle.md.
|
|
75
75
|
|
|
76
|
-
**A depth-2 member cannot dispatch further** (`task.maxRecursionDepth: 2`):
|
|
77
|
-
if `task` is absent at your depth, ask the controller to dispatch the
|
|
78
|
-
specialists and relay their reports. See references/member-lifecycle.md.
|
|
79
|
-
|
|
80
76
|
**Fresh context per member.** One member, one unit of work, gone. Never
|
|
81
77
|
re-task a finished member — waking it drags the old ticket back in. Refill =
|
|
82
78
|
**new** member, **new** name. Sending is still right for pinging a live
|
|
@@ -1414,9 +1410,12 @@ honest summary is unchanged and is the reason this paragraph exists: the guard
|
|
|
1414
1410
|
fired on the criterion the maintainer chose in advance, not on a demonstration
|
|
1415
1411
|
that the cheaper tier is worse.
|
|
1416
1412
|
|
|
1417
|
-
`row` **replaces the whole line**, it does not append.
|
|
1418
|
-
that
|
|
1419
|
-
|
|
1413
|
+
`row` **replaces the whole line**, it does not append. To add a token to a row
|
|
1414
|
+
that exists — `ci=`, `held-behind:#M`, `conflict-hold:#M`, `label-off=`, `ports=`
|
|
1415
|
+
— run `ledger.mjs token <key> <token>…`, which keeps every token already on the
|
|
1416
|
+
row and takes a PR's number as the key. A `row` over a row that already carries
|
|
1417
|
+
`KILLED`, `ports=` or `→ PR#` must repeat those tokens or they are gone, and its
|
|
1418
|
+
stderr, `rewrote row #N; dropped: <token>…`, names each token it lost.
|
|
1420
1419
|
|
|
1421
1420
|
`ledger.mjs read` is safe on a pipe as well as a redirect: its payload used to
|
|
1422
1421
|
be abandoned at the pipe buffer and still exit 0, which is what left `board.mjs`
|
|
@@ -1804,8 +1803,9 @@ owes beyond its row:
|
|
|
1804
1803
|
because every reader takes a recorded stop as the end of the run.
|
|
1805
1804
|
- **Monitor: CI run completes** → bind it (`ci-state.mjs --pr <N>`) and **record
|
|
1806
1805
|
it as `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
|
|
1807
|
-
ticket's ledger row, which outlives your context
|
|
1808
|
-
|
|
1806
|
+
ticket's ledger row, which outlives your context: `ledger.mjs token <key>
|
|
1807
|
+
ci=<run-id>:<attempt>:<conclusion>` appends it and keeps every token already on
|
|
1808
|
+
the row, where `row` would replace the whole line (above).
|
|
1809
1809
|
That key cannot be reconstructed once the head is superseded, so a
|
|
1810
1810
|
controller holding only the colour cannot later tell an edge it has already
|
|
1811
1811
|
spent from one that never fired, and that is the distinction the sibling
|
|
@@ -1934,11 +1934,11 @@ depth** guard table applied in code. Act on each line as it reads:
|
|
|
1934
1934
|
tracks it, no conflict hold stands on it, no fix-applier, finisher or
|
|
1935
1935
|
implementer on it is live, and, if it carries `ready-to-merge`, no merge bot
|
|
1936
1936
|
is live: a queued PR is the bot's while one runs, and its own fallback records
|
|
1937
|
-
the hold. Record
|
|
1938
|
-
|
|
1939
|
-
|
|
1940
|
-
|
|
1941
|
-
|
|
1937
|
+
the hold. Record it with `ledger.mjs token <key> conflict-hold:#<M>`, `<key>`
|
|
1938
|
+
the row naming PR M, or M itself: it appends the token and keeps every token
|
|
1939
|
+
the row already carries. The row's detail prints the `row` form of that
|
|
1940
|
+
write for each PR it names; the `token` form is the one that keeps the row's
|
|
1941
|
+
tokens. Then run the tick: the hold reads as `DISPATCH fix-pr
|
|
1942
1942
|
PR#<M>`, a conflict fix-applier (**A `DISPATCH fix-pr PR#<M>` on a conflict
|
|
1943
1943
|
hold**), and that row obeys every hold. A review in flight does not stop the
|
|
1944
1944
|
line: `fix-due` waits for the review to return. It prints under a
|
|
@@ -3472,7 +3472,8 @@ label write are one command and the finisher never runs either alone:
|
|
|
3472
3472
|
verdict on the tree the finisher read, and a GitHub label does not follow the
|
|
3473
3473
|
branch — on one PR it survived a push and came to sit on a commit nobody had
|
|
3474
3474
|
audited. Write `label-off=<latest finisher attempt>` onto the PR's row first
|
|
3475
|
-
(`ledger.mjs
|
|
3475
|
+
(`ledger.mjs token <PR number> label-off=<latest finisher attempt>`, which keeps
|
|
3476
|
+
every token the row already has — **Run ledger**), then
|
|
3476
3477
|
remove `ready-to-merge`, then approve. The token is how the tick tells your
|
|
3477
3478
|
removal from a finisher that never labelled — a tick run between a removal and
|
|
3478
3479
|
its token re-dispatches a finisher into your take-off window. The label goes
|
|
@@ -4420,7 +4421,7 @@ is yours, written before you take `ready-to-merge` off PR M on purpose (taking
|
|
|
4420
4421
|
it off before you approve a push, or clearing one left on a moved head),
|
|
4421
4422
|
naming that PR's latest finisher attempt: the tick reads a missing label as a
|
|
4422
4423
|
finisher's miss only after the last attempt a `label-off=` names, so without
|
|
4423
|
-
it your own removal reads as one. `row`
|
|
4424
|
+
it your own removal reads as one. `row` and `token` refuse a `label-off=` naming no
|
|
4424
4425
|
`finisher-pr` member that `## Dispatched` or some row already carries.
|
|
4425
4426
|
|
|
4426
4427
|
`review` holds a PR's review record to these rules, read across every row that
|
|
@@ -4452,7 +4453,7 @@ Plus two append-only lists:
|
|
|
4452
4453
|
- **ruled** (`ledger.mjs ruled <pr> <decision>`) — PR + decision + one-line reason,
|
|
4453
4454
|
so a replacement controller does not re-litigate a settled call.
|
|
4454
4455
|
|
|
4455
|
-
**Writer policy: the controller owns run state (`row`/`settle`/`dispatch`/`review`/`drain`/`ruled`);
|
|
4456
|
+
**Writer policy: the controller owns run state (`row`/`token`/`settle`/`dispatch`/`review`/`drain`/`ruled`);
|
|
4456
4457
|
filers append filings with `filed`; all writes are serialized by `<file>.lock`.**
|
|
4457
4458
|
Every write rewrites the whole file from what it read, so without the lock two
|
|
4458
4459
|
concurrent writers are last-writer-wins — measured, 8 concurrent `filed` kept
|
|
@@ -4537,7 +4538,6 @@ Plus a queue-depth line: shortlist, supply, whether triage was suggested.
|
|
|
4537
4538
|
- "Fork the controller so the member has context" → fork inherits everything.
|
|
4538
4539
|
- "This member finished, send it the next ticket" → resumes its transcript.
|
|
4539
4540
|
- "The name is cosmetic" → the name is the ledger token and the hub address.
|
|
4540
|
-
- "Name the specialists too" → a depth-2 member cannot dispatch further.
|
|
4541
4541
|
- "ready-for-agent came back empty, widen to ready-for-human" → empty with no `specs-dropped=` means no work; empty with drops means specs awaiting to-tickets, and is still never a reason to widen.
|
|
4542
4542
|
- "The reap at the end will pick up the claim I never dispatched" → it declines:
|
|
4543
4543
|
not `[gone]`, no unique commits. Release it, or it reads as taken next run.
|
|
@@ -6,14 +6,6 @@ Why member name load-bearing, why every member single-use, how a member's job ou
|
|
|
6
6
|
|
|
7
7
|
The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (the PR's first reviewer; every later one on the PR — failed-runner retry, past-pin re-review — takes the next letter the PR's row does not carry yet, `review-pr-<pr#>-b`, `-c`, …; a reviewer's launch and result are recorded on the PR's row with `ledger.mjs review <pr#>`), `finisher-pr-<pr#>` (Phase 3's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
|
|
8
8
|
|
|
9
|
-
## A depth-2 member cannot dispatch further
|
|
10
|
-
|
|
11
|
-
`task` is absent at a depth-2 member's depth (`task.maxRecursionDepth: 2`). Must state in reviewer prompt — else reviewer concludes fan-out unavailable, silently downgrades to solo review, no error, no signal; ask the controller to dispatch the specialists and relay their reports instead.
|
|
12
|
-
|
|
13
|
-
## Capability is not permission
|
|
14
|
-
|
|
15
|
-
Holding the dispatch tool does not authorize using it: a reviewer not told the fan-out is requested work declines to dispatch specialists, and you get thinner solo review, no error, no signal. Having tool (capability) not authorization to use it (permission); reviewer prompt must state full specialist set IS requested work.
|
|
16
|
-
|
|
17
9
|
## The coordination contract
|
|
18
10
|
|
|
19
11
|
Stated once, in this fixed vocabulary — *dispatch* (start a member),
|
|
@@ -24,7 +16,7 @@ outcome), *consume* (the controller deliberately taking a settled result):
|
|
|
24
16
|
- A refill is a **new** member under a **new** name, never a wake back into the old one — waking a finished member drags its old ticket in.
|
|
25
17
|
- Liveness is not settlement. A member that is not currently executing is not thereby done (Settle and liveness, below).
|
|
26
18
|
- A settled result is consumed deliberately, never assumed — the discipline holds even where the *hazard* it guards against does not (Grandchildren, below).
|
|
27
|
-
- Every send is reconciled against its receipt
|
|
19
|
+
- Every send is reconciled against its receipt, the `delivered`/`failed` result `hub send` returns inline (Grandchildren, below).
|
|
28
20
|
|
|
29
21
|
`hub send` is the omp messaging mechanism. It appears in the recipes below, never in this contract's own vocabulary.
|
|
30
22
|
|
|
@@ -36,20 +28,14 @@ One member, one unit of work, gone. Never re-task a finished member — waking i
|
|
|
36
28
|
|
|
37
29
|
## Grandchildren surface to you, not to the member that spawned them
|
|
38
30
|
|
|
39
|
-
A specialist's report routes to *you*, the controller.
|
|
31
|
+
A specialist's or refuter's report routes to *you*, the controller, not to the member that spawned it.
|
|
40
32
|
|
|
41
33
|
A depth-2 helper cannot dispatch further (`task.maxRecursionDepth: 2`); measured 2026-09-09 from an actual controller session: a `hub send` to a depth-2 helper's full dotted id (`<member>.<helper>`) delivered, woke it, and got a reply — the controller reaches a member's helper directly, no transcript workaround needed.
|
|
42
34
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
Results auto-deliver, and a settled `hub jobs`/`wait` snapshot **is** the delivery itself.
|
|
46
|
-
|
|
47
|
-
So relay each: name source, send its *text* (ruling on it as "your finding" makes reviewer verify a report it never sent, or act on one it cannot check). Then **reconcile every verdict against your relay receipts** — verdict claims a dimension undelivered, receipts say relayed → re-send naming the specialist, hold the verdict until it lands. Do not require reviewer-side acknowledgement: compliance depends on the same failure it catches, and the receipt check needs nothing from the reviewer.
|
|
35
|
+
A completed member's result is consumed deliberately, never assumed silent. Results auto-deliver, and a settled `hub jobs`/`wait` snapshot **is** the delivery itself.
|
|
48
36
|
|
|
49
37
|
`hub send` returns a structured `delivered`/`failed` receipt inline, replies thread by a 16-hex message id, and `await: true` returns the reply in the same call — the bookkeeping is native.
|
|
50
38
|
|
|
51
|
-
Measured 2026-09 (pre-cutover), both halves, with quotes. `review-pr-11` was sent `code-reviewer`'s report, msg `58c6bef2`, before its verdict; verdict read *"`code-reviewer` — dispatched, never delivered. No report reached me and none was relayed. Dimension not covered by a specialist."* — then ruled that dimension solo, headline claim refuted by report already sent to it. `review-pr-12` composed its first verdict *before* relays landed and reported all four as delivering nothing, found same defects in own mutation pass, credited all four by name in second verdict — convergent discovery, not silent application. Naming gap honestly is necessary, not sufficient: relay sent ≠ relay read, and relay can land after verdict composed. Neither reviewer could tell "no report" from "not yet relayed" without the receipt check; the second's independent re-derivation is what makes the correction trustworthy, not the naming alone.
|
|
52
|
-
|
|
53
39
|
Grandchild surfaces as own task-notification; unrecognized task-id not a member reporting done.
|
|
54
40
|
|
|
55
41
|
## Settle and liveness are different facts
|