@feigi/fleet-ctl 3.137.5 → 3.138.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.
- package/agents/fleet-finisher.agent.md +8 -8
- package/agents/fleet-fix-applier.agent.md +1 -1
- package/agents/fleet-merge-bot.agent.md +1 -1
- package/agents/fleet-recipe-deriver.agent.md +5 -5
- package/agents/fleet-review-runner.agent.md +1 -1
- package/commands/review-and-fix.md +11 -11
- package/commands/run-merge-bot.md +9 -9
- package/package.json +1 -1
- package/scripts/claim-ticket.sh +15 -1
- package/scripts/controller-alarm.mjs +1 -1
- package/scripts/evict-mark.mjs +1 -1
- package/scripts/finisher-audit.mjs +1 -1
- package/scripts/finisher-label.mjs +1 -1
- package/scripts/finisher-tree.mjs +1 -1
- package/scripts/fleet-provenance +9 -52
- package/scripts/fleet-run +5 -10
- package/scripts/fleet-tick.mjs +3 -3
- package/scripts/instruments.sh +3 -4
- package/scripts/ledger.mjs +1 -1
- package/scripts/main-checkout.mjs +1 -1
- package/scripts/phase0-receipt.mjs +1 -1
- package/scripts/preflight.mjs +0 -1
- package/scripts/recipe-check.mjs +1 -1
- package/scripts/release-ticket.sh +16 -0
- package/scripts/repo-root.mjs +1 -1
- package/scripts/report-schema.mjs +1 -1
- package/scripts/review-core.mjs +6 -6
- package/scripts/review-eval.mjs +1 -1
- package/scripts/ticketless.mjs +1 -1
- package/scripts/worktree.sh +46 -0
- package/skills/next-ticket/SKILL.md +8 -8
- package/skills/run-team/SKILL.md +22 -34
- package/skills/run-team/briefs/finisher.md +2 -2
- package/skills/run-team/briefs/fix-applier.md +9 -9
- package/skills/run-team/briefs/implementer.md +3 -3
- package/skills/run-team/briefs/merge-bot.md +2 -2
- package/skills/run-team/references/ci-and-staleness.md +1 -1
- package/skills/run-team/references/ci-watcher.md +1 -1
- package/skills/run-team/references/close-out.md +5 -5
- package/skills/run-team/references/failure-handling.md +2 -2
- package/skills/run-team/references/finisher.md +2 -2
- package/skills/run-team/references/instruments.md +1 -1
- package/skills/run-team/references/isolation.md +3 -3
- package/skills/run-team/references/ledger.md +1 -1
- package/skills/run-team/references/member-lifecycle.md +1 -1
- package/skills/run-team/references/phase-0.md +20 -20
- package/skills/run-team/references/pull.md +18 -10
- package/skills/run-team/references/reaping.md +15 -1
- package/skills/run-team/references/reviewers.md +9 -1
- package/skills/run-team/references/tick-rows.md +2 -2
- package/skills/sizing-a-ticket/SKILL.md +1 -1
- package/scripts/fleet-bootstrap +0 -140
|
@@ -12,8 +12,8 @@ Your four duties are a checklist — audit the worktree, confirm every deferral
|
|
|
12
12
|
|
|
13
13
|
**Before duty 1, read the Label map — the two roles you type or compare, once —
|
|
14
14
|
and use those strings for the rest of your run.**
|
|
15
|
-
`~/.fleet/
|
|
16
|
-
`~/.fleet/
|
|
15
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show needs-triage` and
|
|
16
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show wontfix` each print the string the
|
|
17
17
|
tracker uses. Wherever the duties below name `needs-triage` or `wontfix` in a
|
|
18
18
|
`gh` command, a label comparison or text you write to the tracker, they mean
|
|
19
19
|
those strings. You never run `ensure` and you never ask anyone. Any non-zero
|
|
@@ -23,7 +23,7 @@ that could not look — `outcome` `halted`, `cause` `other`, `evidence` what
|
|
|
23
23
|
`show` printed, `kill` null, and every list empty.
|
|
24
24
|
|
|
25
25
|
**Duty 1 is one script, and its exit code is your verdict.**
|
|
26
|
-
`~/.fleet/
|
|
26
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run finisher-audit.mjs --worktree <abs-path> --pin <your dispatch pin>`
|
|
27
27
|
(the path you were dispatched with, and the full SHA). It finds your
|
|
28
28
|
worktree's row, reads whether the tree is dirty, compares the worktree's
|
|
29
29
|
`HEAD` to your pin, and when the head differs derives the cause from the
|
|
@@ -52,7 +52,7 @@ resolve, never a reason to skip it.
|
|
|
52
52
|
|
|
53
53
|
**Re-check the instrument set before you act on what duty 1 or duty 2 read,
|
|
54
54
|
and again before you add the label.**
|
|
55
|
-
`~/.fleet/
|
|
55
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run instruments.sh --repo "$(dirname "$(env -u GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir)")"`.
|
|
56
56
|
Exit 0 is the only code that lets you go on. Exit 1 (the set changed) and
|
|
57
57
|
exit 2 (the check could not answer) both halt you: report what it printed,
|
|
58
58
|
add no label, and do NOT re-read the script that gave you the reading.
|
|
@@ -126,7 +126,7 @@ literally halts a correct PR. It caught the error instead, and said so; do
|
|
|
126
126
|
not rely on that.
|
|
127
127
|
|
|
128
128
|
**Run the Inert diff verdict before the acceptance mutation.** Run
|
|
129
|
-
`~/.fleet/
|
|
129
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run finisher-scope.mjs --worktree <abs-path> --pin <your dispatch pin>`
|
|
130
130
|
(the path you were dispatched with, and the full SHA). It reads the PR's diff
|
|
131
131
|
from the merge base with `origin/main` to your pin and classifies every path.
|
|
132
132
|
Exit 0 means every path is prose (plain `.md` or `.markdown` outside the
|
|
@@ -136,7 +136,7 @@ look) both run the mutation exactly as it is described below. When you skip,
|
|
|
136
136
|
the verdict's one JSON line goes in your report in place of the `red:` line.
|
|
137
137
|
|
|
138
138
|
**A Ticketless PR has no acceptance mutation to re-run.** Run
|
|
139
|
-
`~/.fleet/
|
|
139
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ticketless.mjs --pr <M>`. It reads whether the PR
|
|
140
140
|
closes an issue in its own repository and whether a settled
|
|
141
141
|
`impl-<N>=PR#<M>` token names it. Only its exit 0 skips the acceptance
|
|
142
142
|
mutation below, whatever the diff, and the rest of duty 2 runs. Where a kill's
|
|
@@ -155,7 +155,7 @@ ordering is detectable afterwards from the diff — a restore lands on the
|
|
|
155
155
|
uncommitted clause and destroys it silently, or the mutant is still in the
|
|
156
156
|
tree when the fix-applier commits and a deliberately broken guard ships as
|
|
157
157
|
the fix, in a commit nothing re-reviews. So take your own:
|
|
158
|
-
`~/.fleet/
|
|
158
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run finisher-tree.mjs --worktree <abs-path> --pin <your dispatch pin> --pr <N> --member <your member name> --scratch <scratch>`
|
|
159
159
|
adds `git worktree add --detach <scratch>/pr<N>/finish-<your member name> <your dispatch pin>`
|
|
160
160
|
and runs the Install step in it, as a claim does: a detached worktree holds
|
|
161
161
|
tracked files only, so without that step a suite whose dependencies are
|
|
@@ -269,7 +269,7 @@ cause `other`, with both runs — the mutant's and the unmutated tree's — as
|
|
|
269
269
|
evidence; label nothing. A kill's evidence line goes in your report.
|
|
270
270
|
|
|
271
271
|
**Duty 3 is one script, and its exit code is your verdict.**
|
|
272
|
-
`~/.fleet/
|
|
272
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
|
|
273
273
|
(the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
|
|
274
274
|
PR — a Ticketless PR with none gets `patch` added first — records the head you
|
|
275
275
|
audited, adds `ready-to-merge`, and reads the labels
|
|
@@ -345,7 +345,7 @@ exits; no outcome is reported, and the controller settles the missing report as
|
|
|
345
345
|
`failed`.
|
|
346
346
|
**Deferring everything is a normal
|
|
347
347
|
outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
|
|
348
|
-
index, `~/.fleet/
|
|
348
|
+
index, `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run push-sync.mjs --branch <branch>` prints git's
|
|
349
349
|
`Everything up-to-date`, and your
|
|
350
350
|
report's `outcome` is `no-op`, its `head` the unchanged SHA. Say it
|
|
351
351
|
explicitly — silence there is indistinguishable from a member that died. Never
|
|
@@ -8,7 +8,7 @@ Your brief names you, `merge-bot-<n>`, and your scratch directory. Where the tex
|
|
|
8
8
|
|
|
9
9
|
Label names in this file are roles; the Label map gives the string to type; a member never derives the map.
|
|
10
10
|
|
|
11
|
-
Read
|
|
11
|
+
Read `~/.omp/plugins/node_modules/@feigi/fleet-ctl/commands/run-merge-bot.md` and run **one**
|
|
12
12
|
pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
|
|
13
13
|
for late labels, then report once and exit. The controller dispatched you, which
|
|
14
14
|
is what makes you hold that grace instead of arming your own watcher.
|
|
@@ -17,7 +17,7 @@ decided; nothing is cached on a guess.
|
|
|
17
17
|
Your dispatch prompt gives you `<repo>` (the repository's main checkout, an
|
|
18
18
|
absolute path) and `<scratch>` (a directory that is yours alone, an absolute
|
|
19
19
|
path; standalone, with no dispatcher, it is `<root>/derive-recipe/` with
|
|
20
|
-
`<root>` what `~/.fleet/
|
|
20
|
+
`<root>` what `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run scratch-root.mjs` prints). Read files
|
|
21
21
|
under `<repo>`; write only under `<scratch>`. **Never edit, create or delete a
|
|
22
22
|
file under `<repo>`, and never write `.fleet/recipe.json` yourself** — the
|
|
23
23
|
proof below is the cache's only writer, and it writes only on proof.
|
|
@@ -124,7 +124,7 @@ script creates and removes; `<repo>`'s own tree is never touched.
|
|
|
124
124
|
|
|
125
125
|
**First run, to see the output** — no proof flags:
|
|
126
126
|
|
|
127
|
-
~/.fleet/
|
|
127
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>'
|
|
128
128
|
|
|
129
129
|
It exits 1 with `NOT PROVEN — no proof given` once every command ran, and
|
|
130
130
|
names the Test entrypoint's output file (`test output: <path>`). Any other
|
|
@@ -137,7 +137,7 @@ and revise.
|
|
|
137
137
|
text off that summary line, as printed, into `--count-line`, and the number
|
|
138
138
|
of tests that ran into `--test-count`:
|
|
139
139
|
|
|
140
|
-
~/.fleet/
|
|
140
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>' \
|
|
141
141
|
--count-line '<literal text of the count line>' --test-count <n>
|
|
142
142
|
|
|
143
143
|
The number is the tests that ran — never the skipped, the failed, or a
|
|
@@ -155,7 +155,7 @@ and revise.
|
|
|
155
155
|
must change a tracked file; the script runs it in the throwaway worktree,
|
|
156
156
|
requires the suite to go red, and discards the worktree after:
|
|
157
157
|
|
|
158
|
-
~/.fleet/
|
|
158
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>' \
|
|
159
159
|
--mutate '<shell command that breaks one test>' --mutation '<one line: what it breaks>'
|
|
160
160
|
|
|
161
161
|
**The Check step's own proof** — when `--check` is not `true`, the Check step
|
|
@@ -164,7 +164,7 @@ must run green on `origin/main`, and one mutation must turn it red. Give
|
|
|
164
164
|
`--check true`. Both proofs ride in one run: the Test entrypoint's proof flags
|
|
165
165
|
from above, and these:
|
|
166
166
|
|
|
167
|
-
~/.fleet/
|
|
167
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>' \
|
|
168
168
|
--check-mutate '<shell command that breaks one file the Check step reads>' --check-mutation '<one line: what it breaks>' \
|
|
169
169
|
<the Test entrypoint's proof flags>
|
|
170
170
|
|
|
@@ -42,7 +42,7 @@ retries it under the next letter.
|
|
|
42
42
|
|
|
43
43
|
```js
|
|
44
44
|
return await (async () => {
|
|
45
|
-
const path = (await Bun.$`~/.fleet/
|
|
45
|
+
const path = (await Bun.$`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run --path review-eval.mjs`.text()).trim();
|
|
46
46
|
const { runReviewToFile } = await import(path);
|
|
47
47
|
return runReviewToFile({ pr: 1234, branch: "the-branch", worktree: "/abs/worktree", testCmd: "the test command", scratch: "/abs/scratch-root" });
|
|
48
48
|
})();
|
|
@@ -3,13 +3,13 @@ description: review a PR, apply recommended actions, push — standalone, then w
|
|
|
3
3
|
argument-hint: [pr-number]
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
`<scratch>` below is the absolute path your dispatch prompt names. Run standalone, with no dispatcher, it is what `~/.fleet/
|
|
6
|
+
`<scratch>` below is the absolute path your dispatch prompt names. Run standalone, with no dispatcher, it is what `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run scratch-root.mjs` prints — never a directory you pick.
|
|
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/
|
|
10
|
+
**Standalone, before step 1, run the Label map derivation step:** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/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 `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/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
|
-
`<needs-triage string>`, `<wontfix string>` and `<ready-to-merge string>` below are what `~/.fleet/
|
|
12
|
+
`<needs-triage string>`, `<wontfix string>` and `<ready-to-merge string>` below are what `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show <role>` prints for that role.
|
|
13
13
|
|
|
14
14
|
1. Run the review yourself. **Dispatched as a fix-applier, skip this step**: the review already ran, and its result came with your prompt — see **The review result file**, which also holds the rulings on it that are yours to make. Re-running it re-reviews a PR nobody asked you to review. Otherwise — no `eval` access at your level — hand-dispatch the six `fleet-review-*` specialists yourself, by name:
|
|
15
15
|
|
|
@@ -19,20 +19,20 @@ Label names in this file are roles; the Label map gives the string to type; a me
|
|
|
19
19
|
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 `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 `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.**
|
|
20
20
|
**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 suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
|
|
21
21
|
**Give every entry whose finding stands a Charge:** `charge` — `false-claim`, `unmet`, `both` or `none` — and, with `none` only, a `chargeReason`: `defect-outside-acceptance` (a defect outside the ticket's acceptance criteria, which no text the implementer wrote claims is otherwise), `not-the-implementers-text` (the false text predates the PR, or comes from the ticket) or `claim-about-untouched-code` (a claim about code the change does not touch). A `survived` finding not deferred `false-rationale` stands, and so does every `refuted` one you reverse; an `unverified` one never does. Charge the work as submitted — a finding you apply is charged as if it were still there — by the definitions of `closed_own_ticket` and `minted_false_claim` in the header of `docs/metrics/tier-outcomes.tsv`, against the ticket as its implementer was dispatched with it; an entry scoped `out` is charged `none`. The check requires a Charge on every standing entry of the record answering the PR's first review — the first that counted no survived and no unverified finding, or else the first a fix-applier answered — and a record answering a later review, or one checked with no ledger, needs none. Wherever a `charge` or `chargeReason` appears it is judged: an unknown value, `none` with no `chargeReason`, a `chargeReason` with any other `charge` or with none, and an out-of-scope entry charged anything but `none` are each a mismatch.
|
|
22
|
-
3. **Run `checkCmd` and `testCmd` before you commit**, from the worktree, each copied verbatim — not a runner you picked. `checkCmd` is the Recipe's Check step and `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you them, they are the repo's own Check step and Test entrypoint**, read off the repo's Recipe cache (`derive-testcmd.sh <repo> check` prints the first, `derive-testcmd.sh <repo> test` the second). Read them 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 all three 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 — `~/.fleet/
|
|
23
|
-
**Under the fleet, run the two through `recipe-check.mjs`, not one by one:** from the worktree, after `git add` and before the commit, `~/.fleet/
|
|
22
|
+
3. **Run `checkCmd` and `testCmd` before you commit**, from the worktree, each copied verbatim — not a runner you picked. `checkCmd` is the Recipe's Check step and `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you them, they are the repo's own Check step and Test entrypoint**, read off the repo's Recipe cache (`derive-testcmd.sh <repo> check` prints the first, `derive-testcmd.sh <repo> test` the second). Read them 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 all three 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 — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run push-sync.mjs --branch <branch>`, which pushes the explicit refspec `HEAD:refs/heads/<branch>` and then moves the worktree holding `<branch>` to the pushed SHA, or names why it did not and exits 3 with the push landed: 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`), 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 a refspec push alone leaves the claim worktree's `refs/heads/<branch>` at its old tip — 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. Seen twice in one run, and caught only by a finisher's reading. `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` on a commit you push, or on the push itself.** 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 on what reaches the branch — 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.
|
|
23
|
+
**Under the fleet, run the two through `recipe-check.mjs`, not one by one:** from the worktree, after `git add` and before the commit, `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run recipe-check.mjs --member <your name> --testCmd "<testCmd>" --reports <scratch>/reports` — `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as, and `<testCmd>` the whole command you were handed, one quoted argument. It runs the Recipe's Check step, which is `checkCmd`, then `<testCmd>` exactly as handed, against the staged tree, and records both results beside your report. The record is keyed to the tree, so run it again after any content change or rebase — a message-only amend keeps it valid — and the controller refuses an `applied` report whose head's tree has no green record. After the commit, and before you push or report, compare `git rev-parse 'HEAD^{tree}'` with the `tree` field of your record, `<scratch>/reports/<your name>.check.json`. A commit hook that rewrote and re-staged files after the record was written makes the two differ. When they do, list the paths it changed, `git diff --name-only "$(jq -r .tree <scratch>/reports/<your name>.check.json)" HEAD`. If the PR changes every listed path anyway, run `recipe-check.mjs` again with the same arguments: right after the commit the index holds the committed tree, so the re-run runs both commands on that tree and records it, leaving the head's sha as it is. A listed path the PR does not otherwise change is a stale base the hook staged rather than left unstaged, and a re-run would record it green: `git fetch origin && git rebase origin/main`, take the commit back with `git reset --soft HEAD^`, put each such path alone back with `git restore --source=HEAD --staged --worktree -- <that path>`, run `recipe-check.mjs`, then `git commit -C ORIG_HEAD` and compare again. A hook that stages such a path again on the rebased base → push nothing and report that cause. Equal trees need no re-run. Exit 1 is red; exit 2 and 4 are refusals that record nothing: your brief says how each ends; exit 75 (no slot free) and exit 143, 130 or 129 (a SIGTERM, SIGINT or SIGHUP, nothing recorded) are no test result: run it again, with `timeout: 0` on the call for a signal. **Standalone, with no report to settle against,** run `checkCmd` and `testCmd` yourself, each copied verbatim.
|
|
24
24
|
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. 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.
|
|
25
|
-
5. File each deferred finding: `gh issue create --label "<needs-triage string>"` 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`, filed with `gh issue create --label "<wontfix string>"` and then CLOSED** — left open they read as queued agent work. Closed is still a durable home — `check` reads the tracker at `--state all`, so a later run re-deriving the finding lands on the evidence. 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. 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, 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/
|
|
25
|
+
5. File each deferred finding: `gh issue create --label "<needs-triage string>"` 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`, filed with `gh issue create --label "<wontfix string>"` and then CLOSED** — left open they read as queued agent work. Closed is still a durable home — `check` reads the tracker at `--state all`, so a later run re-deriving the finding lands on the evidence. 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. 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, 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 `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/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*. `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 `~/.omp/plugins/node_modules/@feigi/fleet-ctl/skills/run-team/references/ledger.md`, which `SKILL.md`'s wake section points at — read them there rather than restating them here. **The guard dedupes, it never drops:** a duplicate becomes a comment on the issue that already covers it, never a dropped finding. **Record every issue you create, at once:** immediately after each `gh issue create`, run `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/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.
|
|
26
26
|
**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.
|
|
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
|
-
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
|
|
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 `~/.omp/plugins/node_modules/@feigi/fleet-ctl/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
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
|
|
|
34
34
|
```bash
|
|
35
|
-
~/.fleet/
|
|
35
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ci-state.mjs --pr <n>
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
`ci-state.mjs` does the whole run-binding check and prints a `verdict` with reasons: it binds the run to the PR head, requires run `status` **completed** and **every expected job present**, and treats `skipped` as not-green. The expected list is derived, never hardcoded, from the CI workflow (discovered by its `name:` under `.github/workflows/`) as it stands at the PR's own head and base commits — never from your working tree, so the answer is the same wherever you run it: every job the head's workflow declares, plus each job the head dropped from the base's workflow that the base branch's rules (rulesets or classic branch protection) still require as a status check. A dropped job no rule requires is not expected, and the payload lists it in `dropped`; one a rule still requires stays in `missing`. No `--workflow-file` needed unless two files share that name, or none carries it, both of which exit 2 saying so. Exit 0 only when genuinely green. Its job-presence check is what catches the case above: a force-push cancels the run under you, its finished jobs keep the conclusions they already reached, while the jobs that never ran are absent rather than red — and an absent job reads as `pending` in an aggregating checks summary, never here: `ci-state.mjs` names it in the reason `expected jobs absent from the run: …` and refuses green.
|
|
@@ -83,12 +83,12 @@ jq '.refuted' "$R" # refuted: your
|
|
|
83
83
|
|
|
84
84
|
`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.
|
|
85
85
|
|
|
86
|
-
|
|
86
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/skills/run-team/SKILL.md`'s **The reviewer** bullet owns its dispatch, and `references/reviewers.md` (**A review runs off your turn and relays nothing**) says what it does. 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.
|
|
87
87
|
|
|
88
88
|
It cannot ask the user anything and cannot wait on CI — rebasing, watching checks, binding and labelling stay here.
|
|
89
89
|
|
|
90
90
|
- **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.
|
|
91
|
-
- **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.
|
|
91
|
+
- **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. What one shared snapshot did is in run-team's `references/reviewers.md` (**What a shared snapshot did to its readers**). 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*.
|
|
92
92
|
- **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.
|
|
93
93
|
- **`git archive` carries tracked files only.** No installed dependencies, no gitignored runner or config. Provision in the same step — run the Install step in the copy (read it off the worktree or main checkout, `derive-testcmd.sh <worktree or main checkout> install`; pointed at the copy it refuses, since a copy holds no Recipe cache), from the copy's root, before anyone measures in it — or specialists silently have no runnable suite and reason from source instead of measuring. That failure is invisible: you get confident prose where you asked for a measurement. Never `cp -R` an installed tree, and never symlink or clone its ignored paths into a copy: an install can record absolute paths back into the tree it ran in, so the copy runs that tree's source and a mutation made in the copy never runs.
|
|
94
94
|
- **Initialize the copy before anyone measures in it — a bare `git archive` tree cannot validly run every suite.** It is not a git repository, so anything that asks git about the checkout breaks: `derive_workspace_id` shells out to `git rev-parse`, falls back to the directory basename and the hook tests fail on the *name* — naming the dir after the repo makes those pass **by coincidence, not correctness** — while every sweep that asks git what ships declines instead of running, which is the silent half (measured on this repo at `ffa9026`: 2401 tests, 2382 pass, 19 skipped in an extraction against 2401/2401/0 in a worktree, the totals identical). `git init && git add -A -f && git commit` in the extracted copy is what makes a count mean what it looks like; the review's snapshot agent does exactly that, verifies it by comparing the new commit's tree hash against the reviewed commit's, and then runs the Install step in it, and a hand-cut tree needs the same before you read a count off it. **Every agent you send to work in its own copy of the snapshot makes that copy the same way:** copy the tracked files only (`git -C <snapshot> archive HEAD | tar -x -C <copy>`, or a `git clone` of the snapshot repository), `git init`, `git add -A -f` and commit, then run the Install step in the copy before measuring anything in it — never `cp -R` the snapshot. Suites that need the real worktree for some *other* reason — the stack below — still do.
|
|
@@ -96,7 +96,7 @@ It cannot ask the user anything and cannot wait on CI — rebasing, watching che
|
|
|
96
96
|
- **Completion is not delivery — but you can reach a specialist, so never wait idle.** A specialist you dispatched reports when it settles; if a report is missing, `hub send` it by name and ask for the report. Judge delivery by whether a report came out. **Do not settle a dimension you hold no report for**: ask the specialist, then the controller by name; only when neither answers, rule and name that dimension **unrun** — a killed specialist never reports, so waiting on one is unbounded. Never ship "dispatched, never delivered" as settled; a ruling citing a report you do not hold gets verified from source, never applied on trust.
|
|
97
97
|
- **Apply only once the fan-out is settled — every report either in hand or accounted for.** Collection is not guaranteed; a report that never arrived is an open dimension, not a smaller set. And editing while they read is the same defect as probing — one specialist reviewed uncommitted code that was never in the PR diff.
|
|
98
98
|
|
|
99
|
-
Tell readers **`git show <sha>:<path>` is the source of truth** — the object store cannot be contaminated by any agent, needs no copy, and touches nothing. Make it the default for settling *what the PR contains*, not a fallback. A finding that disagrees with it is a probe artifact. **Then bound the read — the guarantee is the blob, not the byte count.** `git show <sha>:<path> | sed -n 'A,Bp'` reads the same uncontaminatable object; take the file whole only once `| wc -l` says it is small — a count, not a feeling. Where the *change* is what you are settling, diff instead of reading: `git diff <base>...<head> -- <path>` for the PR's whole change, `git show <sha> -- <path>` only for one named commit's. That second form is scoped to that single commit and prints **nothing, at exit 0**, when the commit did not touch the path (measured) — the same silent green as `tests 0`, and it reads as "the PR changed nothing here".
|
|
99
|
+
Tell readers **`git show <sha>:<path>` is the source of truth** — the object store cannot be contaminated by any agent, needs no copy, and touches nothing. Make it the default for settling *what the PR contains*, not a fallback. A finding that disagrees with it is a probe artifact. **Then bound the read — the guarantee is the blob, not the byte count.** `git show <sha>:<path> | sed -n 'A,Bp'` reads the same uncontaminatable object; take the file whole only once `| wc -l` says it is small — a count, not a feeling. Where the *change* is what you are settling, diff instead of reading: `git diff <base>...<head> -- <path>` for the PR's whole change, `git show <sha> -- <path>` only for one named commit's. That second form is scoped to that single commit and prints **nothing, at exit 0**, when the commit did not touch the path (measured) — the same silent green as `tests 0`, and it reads as "the PR changed nothing here". What an unbounded read costs is in run-team's `references/reviewers.md` (**What an unbounded read costs**).
|
|
100
100
|
|
|
101
101
|
**Brace a ref held in a variable — `git show "${SHA}:<path>"` — because quoting is not what fixes it.** zsh reads a `:x` suffix after an unbraced parameter as a history modifier, inside double quotes as well as outside, so git is handed a ref nobody typed; braces end the parameter name before the colon. Measured, fully quoted: the construct that fails loudly on one path exits 0 on another and prints the *commit* instead of the blob — and the silent shape is the hazard, because a survival `grep -c` scores it as a plausible hit and re-anchors a citation that was correct. A literal ref is unaffected either way; quote regardless — not for zsh's sake, which splits and globs an expansion's *result* only under `SH_WORD_SPLIT`/`GLOB_SUBST`, both off by default (measured: `V="a b"` unquoted still arrives as one argument), but so the same line survives a `bash` runner, where an unquoted path holding a space does split — measured, `fatal: path 'has' does not exist`.
|
|
102
102
|
|
|
@@ -12,11 +12,11 @@ Only `ready-to-merge` PRs are in scope — it is the author's sign-off. Never ad
|
|
|
12
12
|
|
|
13
13
|
## The Label map
|
|
14
14
|
|
|
15
|
-
**At the start of your pass, before selection, read the Label map — once.** `~/.fleet/
|
|
15
|
+
**At the start of your pass, before selection, read the Label map — once.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show ready-to-merge` prints the string the tracker uses for `ready-to-merge`. Type that one string for the rest of your pass wherever this file polls or compares by label: `<ready-to-merge string>` below is what it printed, in both polls (the grace's and the Monitor's) and in the timeline comparison. You run no `ensure` and ask no one.
|
|
16
16
|
|
|
17
17
|
**A non-zero exit from `show` ends your pass before selection**, with nothing else done first and `ready-to-merge` never typed in place of the string:
|
|
18
18
|
|
|
19
|
-
- **A bot a controller dispatched** holds no grace. Read the queue your dispatch recorded, which needs no map — `~/.fleet/
|
|
19
|
+
- **A bot a controller dispatched** holds no grace. Read the queue your dispatch recorded, which needs no map — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ledger.mjs read | jq -c '.queued["merge-bot-<n>"]'` — and write your one report giving every PR there `refused` with `reason` `label-map-refused`; an empty or absent queue gives every list empty. Validate it as **One verdict per queued PR** says, then send your final line followed by what `show` printed.
|
|
20
20
|
- **The top-level invocation** prints what `show` printed and stops. It writes no report.
|
|
21
21
|
|
|
22
22
|
## Order
|
|
@@ -178,13 +178,13 @@ For each labeled PR, lowest first:
|
|
|
178
178
|
**When that hand-back is a conflict, record it on the ledger before you report — your report is gone when you exit, and nothing else durable says the PR is stuck: the controller records a hold off the tick's `CONFLICT` line only for a PR no live merge bot owns.** It is a conflict when the fallback's local rebase stopped on conflicting paths, whether you then resolved them for verification or aborted: nothing on this path pushes, so the remote head still carries the conflict either way. Not when the server-side rebase failed only because `allow_update_branch` is off and the local rebase applied clean — there is nothing for a fix-applier to resolve. The stopped rebase already named the conflicting paths — read them before you resolve or abort (`git -C <worktree> diff --name-only --diff-filter=U`) — so a later auditor can tell what collided from the row text alone, without re-reading this report. Append the hold to the ticket row that names the PR — the row whose first `PR#` mention is `PR#<pr>`, or the row keyed `#<pr>` when none does — as one rewrite of that row's own text, never a bare line — **unless it already carries one unresolved.** Read the row fresh (below) before writing: if its last `conflict-hold:#<pr>` has no `fix-pr-<n>` settled after it, the row already says what you are about to say — a duplicate write teaches the tick nothing new, and once a fix-applier already working the first hold settles in place before your copy, the tick reads your copy as a fresh hold that settle never cleared. Report `rebase-fallback-#<pr>` and stop there; only write when the row's last hold (if any) has a settled fix-pr after it, or carries no hold at all.
|
|
179
179
|
|
|
180
180
|
```bash
|
|
181
|
-
~/.fleet/
|
|
182
|
-
~/.fleet/
|
|
181
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ledger.mjs read # the row: `#<key> <text>`
|
|
182
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ledger.mjs row <key> "<text> · conflict-hold:#<pr> (conflict: <path1>, <path2>)"
|
|
183
183
|
```
|
|
184
184
|
|
|
185
185
|
`<text>` is everything after the key, verbatim — `row` rewrites the whole line, so a token you drop is gone. `#<pr>` is this PR, never the one it conflicts with; the tick refuses a hold naming another PR. The `(conflict: …)` note is free text, comma-joined paths from the `diff --name-only` read above — placed *after* the token, never before, so it cannot become the first `PR#` mention a row with no `impl-` token is read by (`ledger-grammar.mjs`'s `rowPr`) or fall inside `CONFLICT_HOLD`'s own pattern. From then on the tick prints `DISPATCH fix-pr PR#<pr>` for it and counts it in `held=` until a fix-applier dispatched after the hold settles `applied:`/`no-op`. Skip the `row` write on an already-unresolved hold, per the paragraph above — nothing else about this path changes: still report `rebase-fallback-#<pr>`, still hand it back.
|
|
186
186
|
|
|
187
|
-
**The fallback's "verified" needs a clean main-gain check on the local rebased head.** Save the PR body to `<scratch>/pr<N>/merge-bot-<n>/body.md` (`gh pr view <pr> --json body -q .body`) and, beside it, what `gh pr view <pr> --json number,url,closingIssuesReferences` prints to `<scratch>/pr<N>/merge-bot-<n>/closing-refs.json`, then from the main checkout run `~/.fleet/
|
|
187
|
+
**The fallback's "verified" needs a clean main-gain check on the local rebased head.** Save the PR body to `<scratch>/pr<N>/merge-bot-<n>/body.md` (`gh pr view <pr> --json body -q .body`) and, beside it, what `gh pr view <pr> --json number,url,closingIssuesReferences` prints to `<scratch>/pr<N>/merge-bot-<n>/closing-refs.json`, then from the main checkout run `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run main-gain.mjs --head "$(git -C <worktree> rev-parse HEAD)" --body-file <scratch>/pr<N>/merge-bot-<n>/body.md --closing-refs <scratch>/pr<N>/merge-bot-<n>/closing-refs.json`, so both paths reach one verdict. Exit 0 is the only clean result; name every `acknowledged[]` entry, with its reason, in the hand-back. Exit 1 (a line `main` gained after the PR began would be removed) or exit 2 (it could not answer) is reported inside `rebase-fallback-#<pr>` — the hits and each one's `ack` line to copy, or the `reason` it could not answer — and the fallback is never reported verified.
|
|
188
188
|
|
|
189
189
|
2. Watch checks settle **on the rebased head**. A missing release label (`patch`/`minor`/`major`) fails `validate-release-label` — add the one matching; `release-label.yml` defines that job and exits 1 when the count of those three is zero. A stale `rebase-check` failure usually means step 1 has not landed. Where a repo chains jobs behind that check with `needs:`, they come back `skipped` rather than red and the currency check is the only thing to fix — check `ci.yml` for a `needs:` chain before assuming that: it declares none as of this reading, so no job is currently skipped behind `rebase-check`. **The wait is bounded: 20 minutes of wall-clock per PR, measured from your first poll for it across every poll cell you issue for it.** The bound belongs to one selection of the PR: a PR re-selected fresh from step 1 after a `behind:<n>` skip is rebased again, runs a new CI run, and gets a fresh bound, whatever the earlier wait spent. A run whose `status` is still not `completed` at that bound is an outcome, not a reason to poll on — skip the PR and report `ci-wait-timeout-#<pr>` with the run id and its `status`, leave the label alone, and move to the next candidate; handled the same way as step 3.1's null-runId cap.
|
|
190
190
|
|
|
@@ -203,7 +203,7 @@ For each labeled PR, lowest first:
|
|
|
203
203
|
3. **Gate the merge with `merge-gate.mjs`, run twice, and merge only on the second run's exit 0.**
|
|
204
204
|
|
|
205
205
|
```bash
|
|
206
|
-
~/.fleet/
|
|
206
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run merge-gate.mjs --pr <pr> --pre <pre> --post <post> \
|
|
207
207
|
--out <scratch>/pr<N>/merge-bot-<n>/ci.json; rc=$?
|
|
208
208
|
```
|
|
209
209
|
|
|
@@ -234,7 +234,7 @@ For each labeled PR, lowest first:
|
|
|
234
234
|
**Prove which head landed.** A rebase-then-merge leaves no trace of *which* version went in, and "I rebased" is exactly the claim asserted without doing it:
|
|
235
235
|
|
|
236
236
|
```bash
|
|
237
|
-
~/.fleet/
|
|
237
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run prove-merge.sh <pre-rebase-head> <rebased-head> <merge-commit>
|
|
238
238
|
```
|
|
239
239
|
|
|
240
240
|
**No rebase happened because the PR was already current? Pass the head twice.** That is the normal case in a pass, not an edge case, and `pre == post` selects a proof path built for it. Never invent a plausible-looking `pre` to make the arguments differ — a `pre` that never landed satisfies the pre-rebase leg by construction, and passing one is the single easiest way to turn a stale merge into `proved=true`.
|
|
@@ -248,7 +248,7 @@ For each labeled PR, lowest first:
|
|
|
248
248
|
**Delete the head branch from `origin`** — this bot owns that step, and no repo setting does it for you. Without it a merged branch is never `[gone]`, so `reap.sh` never reaps it or its worktree. The same step also drops `in-progress` from every issue this PR closes: the merge is the only point where the ticket number and the fact of completion are known together, and nothing else clears it.
|
|
249
249
|
|
|
250
250
|
```bash
|
|
251
|
-
~/.fleet/
|
|
251
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run delete-merged-branch.sh <pr>
|
|
252
252
|
```
|
|
253
253
|
|
|
254
254
|
Exit 0 the branch is gone from `origin` — `deleted`, `alreadyGone` (a repo that still auto-deletes), or `skipped` for a fork PR, whose branch is not ours. **1 the branch is still on `origin` — report it as `branch-delete-failed-#<pr>`, never swallow it**: either a push landed on it after the merge (the delete is leased to the merged head, so it refuses rather than destroy commits `main` never received) or the push failed. The script reads the deletion back from `origin` rather than trusting the push's exit status. Exit 2 could not tell what to delete — the PR is not MERGED, a `gh` or `ls-remote` read failed, or the lookup for other open PRs on the branch failed (nothing is deleted then); call this only after the merge is confirmed at the top of this step. **Exit 3 the branch is kept on purpose — another open PR uses it as its head or its base**: deleting it would close the PRs headed by it, and may close rather than retarget the PRs based on it. Nothing was pushed. Its stdout is one `branch-kept-#<pr>` line per such PR, naming that open PR, not the merged one — report each line as printed. A deliberate keep, not a failure: never retry it, and never report it as `branch-delete-failed`. The branch stays on `origin`, so it is not `[gone]` and `reap.sh` leaves it and its worktree in place.
|
|
@@ -277,7 +277,7 @@ This audit is the pre-rebase half and sees only what conflicts. A deletion of li
|
|
|
277
277
|
**1-3. Do not destroy unpushed work, preview conflicts, and name the work at risk** — what `main` gained in the conflicting files since the branch forked:
|
|
278
278
|
|
|
279
279
|
```bash
|
|
280
|
-
~/.fleet/
|
|
280
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run no-undo-audit.sh <worktree> <branch>
|
|
281
281
|
```
|
|
282
282
|
|
|
283
283
|
It refuses (exit 1) on a dirty worktree. Exit **2** is not that refusal: it means the audit could not answer at all — a bad argument, no such worktree, a worktree git does not answer for (its linkage is broken, and git still answers at rc 0 — for the enclosing repo when the `.git` is gone, from another worktree's HEAD and index when it names that worktree's admin dir, against another directory's files when `core.worktree` moves the working tree there), `BASE_REF` is not spelled `origin/<branch>` or `refs/remotes/<path>`, `BASE_REF` names the audited branch, a ref that does not resolve, a probe that could not run, or a conflicting path no pathspec can name — and it emits no payload. What it will **not** do is spend a 2 on the formatting of `worktree` or `branch`: those two echo the arguments you handed it rather than reporting a finding, so an escaper that cannot render one leaves that field and its `*Rewritten` flag as JSON `null` and the run still delivers `clean`, `stash`, `conflicts[]` and `atRisk[]` at its own exit code, naming the field and the escaper on stderr. Read a `null` there as "this run could not render the path or branch you passed in" — it is **never** "there is no worktree", and never a path: pasting it into a command builds a pathspec matching nothing, the same empty-reads-as-proven trap the `conflictsRewritten[]` note below describes. Treat 2 as "ask a human", never as "the worktree is dirty"; there is nothing to commit and hunting for it wastes the pass. **Never** `git clean`, `git checkout .`, `git reset --hard`, or `git stash` to make it pass — that work is unrecoverable and is not on the remote, and stashing it clears `porcelain` so the audit passes on the next run without the work ever shipping. The stash count it prints is reported, not gated: the stack is repo-global across worktrees, so a nonzero count is usually the maintainer's. It can also come back `unknown` rather than a number. Usually the list came back empty and the audit cannot call that an empty stash: `refs/stash` is not absent, which an unreadable ref, an unreadable reflog, or a ref pointing at a missing object each produce just as a genuinely empty stash would. The fourth cause is the opposite shape: `refs/stash` **is** absent while its reflog is not, so the entries it names are unreachable rather than gone. One cause is neither shape: `git stash list` printed entries and then exited nonzero, so what it printed is short — a corrupt loose object behind an entry that is not the tip does this, and the audit reports `unknown` there rather than the number it could have counted. The audit's line says which of them you have. None is the same thing as an empty stash and the audit no longer conflates them. The number it prints is a floor, not a proof: a reflog that is merely truncated — some entries lost, the rest still parsing — drops the missing entries from `git stash list` itself, so the audit and your own read of the list come up short by the same ones and neither reports it. Read `git stash list` yourself when the count is nonzero **or `unknown`** — an entry naming this branch may be a dead member's only copy — and never pop, drop or apply an entry you did not create. On `unknown` do not stop at that list: the causes git stays silent about leave it empty at rc 0, so the list alone shows you nothing. The missing-object cause is the one git is not silent about: `git stash list`'s own stderr there already ends `fatal: bad object refs/stash`, naming that cause outright, so read that line first. The corrupt loose object is named outright too — `fatal: loose object … is corrupt`, printed after the entries git could read — and the audit's own line carries that text for you either way. For the causes it stays silent on, read the files behind it. Set `c=$(git rev-parse --git-common-dir)` — the stack is repo-global, and a linked worktree's `.git` is a file, so `.git/refs/stash` reaches nothing — then `ls -l "$c"/refs/stash "$c"/logs/refs/stash`, where a mode of `----------` on either, or a `Permission denied` from `ls` itself, is the fault, and `cat "$c"/logs/refs/stash`, which still names the branch when `refs/stash` is the unreadable one. `No such file or directory` for `refs/stash` alone, with the reflog listing beside it, is the fourth cause: recover from the SHAs `cat` prints, do not rebase over it. A missing `refs/stash` file is not an empty stash: `git gc` packs it into `packed-refs`. When both reads instead come back with nothing to recover from — `cat` denied, or a reflog that is present but blank — `git show refs/stash` still resolves the ref whether loose or packed, printing the `WIP on <branch>` label; it prints no diff beside that label when the stashed change was staged before `git stash`, so read the content with `git stash show -p refs/stash`, which prints the hunk either way. Both fail only where the ref FILE is itself the broken one — unreadable, holding text that is not a SHA, or gone with nothing in `packed-refs` — and there the SHA `cat` already printed, in the reflog's second field, is what `git stash show -p <that sha>` recovers instead. That fallback is a SHA `cat` printed, so it is gone where the reflog is the denied read too — both files unreadable, `refs/stash` holding text that is not a SHA while the reflog cannot be read, or `refs/stash` gone with nothing in `packed-refs` while the reflog cannot be read — and nothing ref-based recovers there: `git stash list` is still empty at rc 0, `git show refs/stash` answers `ambiguous argument` and `git stash show -p refs/stash` answers `not a valid reference`, and no SHA was printed to hand them instead. Restore read permission where the mode is yours to fix — on whichever of the two files `ls` gave a `----------`, or on the `logs/refs` directory when `ls` failed before printing a mode at all. Only the both-files-unreadable shape then has `git stash list` name the entry again on its own, measured, because the ref file's own content was never touched, only its permission. The other two shapes leave `refs/stash` itself broken — deleted, or holding garbage text — so restoring the reflog's mode only unlocks the SHA `cat` now prints; `git stash list` stays empty at rc 0 until you clear the broken ref and re-point it yourself. `git update-ref refs/stash <that sha>` works directly once `refs/stash` is already gone; where it instead holds garbage text, `git update-ref` refuses that too (`reference broken`, even with `-d`) until you `rm` the file first. Either path is measured to list the entry again as a new `stash@{0}` (an empty-subject entry the update itself adds), pushing the recovered one down to `stash@{1}` rather than restoring it to its original slot. Where there is no mode left to fix — both files are simply gone, with nothing in `packed-refs` and no reflog to read either — `git fsck` still prints a `dangling commit <sha>` line per stash entry, objects loose or packed — at a nonzero exit in the unreadable-ref shape, so read its lines and not its status — and `git stash show -p <that sha>` prints the hunk there, refusing anything that is not a stash (`is not a stash-like commit`). Treat it as a lead, not a listing: no `stash@{N}` comes back with it, and an entry someone dropped on purpose is indistinguishable from a live one. Read the at-risk commits the audit lists first; those are what a careless resolution deletes.
|
package/package.json
CHANGED
package/scripts/claim-ticket.sh
CHANGED
|
@@ -276,12 +276,26 @@ in_progress=$(node "$script_dir/label-map.mjs" show in-progress) \
|
|
|
276
276
|
|
|
277
277
|
if [ "$apply" = false ]; then
|
|
278
278
|
echo "$NAME: DRY RUN — nothing created. Pass --apply to act." >&2
|
|
279
|
+
printf ' would: git config --remove-section branch.%s — if one is left under that name\n' "$branch" >&2
|
|
279
280
|
echo " would: gh issue edit $issue --add-label $in_progress" >&2
|
|
280
281
|
printf ' would: git worktree add --no-track %s -b %s origin/main\n' "$wt" "$branch" >&2
|
|
281
282
|
printf ' would: (cd %s && %s)\n' "$wt" "$install" >&2
|
|
282
283
|
printf ' would: write %s and add it to .git/info/exclude — skipped if %s is\n' "$runner" "$runner" >&2
|
|
283
284
|
printf ' already present, a repo-local runner checked out with the worktree\n' >&2
|
|
284
285
|
else
|
|
286
|
+
# The branch does not exist yet (refused above), so any `[branch "$branch"]`
|
|
287
|
+
# config under its name is a leftover from an earlier branch of that name:
|
|
288
|
+
# `git update-ref -d` removes a ref and nothing else, and `git worktree add
|
|
289
|
+
# --no-track -b` does not clear what is there. Left in place, the new branch
|
|
290
|
+
# inherits the old upstream — a remote ref that no longer exists — and reads
|
|
291
|
+
# `[gone]` from its first moment, which is what reap.sh selects on. Before
|
|
292
|
+
# the label, for the reason the stamp is derived before it: a refusal here
|
|
293
|
+
# has nothing to clean up. A section that cannot be removed is a refusal,
|
|
294
|
+
# since claiming past it is the defect.
|
|
295
|
+
printf '$ git config --remove-section branch.%s\n' "$branch" >&2
|
|
296
|
+
wt_clear_branch_config "$branch" ||
|
|
297
|
+
die "could not remove the leftover config of branch.$branch — $wt_err"
|
|
298
|
+
|
|
285
299
|
echo "\$ gh issue edit $issue --add-label $in_progress" >&2
|
|
286
300
|
gh issue edit "$issue" --add-label "$in_progress" >/dev/null || die "could not label issue $issue"
|
|
287
301
|
|
|
@@ -417,7 +431,7 @@ else
|
|
|
417
431
|
#!/bin/sh
|
|
418
432
|
# agent-test template: $tmpl_stamp
|
|
419
433
|
export TEST_COMPOSE_PROJECT=ab-$issue TEST_POSTGRES_PORT=$pg TEST_OLLAMA_PORT=$ollama
|
|
420
|
-
exec "\$HOME/.fleet/
|
|
434
|
+
exec "\$HOME/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run" suite-slot.mjs '$quoted' "\$@"
|
|
421
435
|
SH
|
|
422
436
|
chmod +x "$runner"
|
|
423
437
|
excl="$(git rev-parse --git-common-dir)/info/exclude"
|
|
@@ -65,7 +65,7 @@ import { readState, stateFileIn } from "./fleet-state.mjs";
|
|
|
65
65
|
import { processSource } from "./proc.mjs";
|
|
66
66
|
|
|
67
67
|
export const POLL_MS = 30_000;
|
|
68
|
-
export const ALARM_LINE = "[fleet-alarm] run ~/.fleet/
|
|
68
|
+
export const ALARM_LINE = "[fleet-alarm] run ~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run fleet-event.mjs heartbeat";
|
|
69
69
|
// Where the extension running as `pid` records that its timer is armed; phase 0 reads it there.
|
|
70
70
|
export const alarmFile = (pid) => join(homedir(), ".fleet", "alarm", `${pid}.json`);
|
|
71
71
|
|
package/scripts/evict-mark.mjs
CHANGED
|
@@ -22,7 +22,7 @@ const GIT_TIMEOUT_MS = 30_000;
|
|
|
22
22
|
const shellWord = (s) => (/^[\w/.@%+=:,-]+$/.test(s) ? s : `'${s.replaceAll("'", "'\\''")}'`);
|
|
23
23
|
|
|
24
24
|
/** The command that restores an evicted tree, as the controller runs it. */
|
|
25
|
-
export const restoreCommand = (tree) => `~/.fleet/
|
|
25
|
+
export const restoreCommand = (tree) => `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run evict.mjs --restore ${shellWord(tree)} --apply`;
|
|
26
26
|
|
|
27
27
|
/** Why a spawnSync result failed, in one phrase: its error, its signal, or its exit and last stderr line. */
|
|
28
28
|
export const how = (r) => {
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
// `worktree-audit.sh` runs in (it audits the worktrees of whichever repository
|
|
12
12
|
// it stands in); the cwd when omitted. `--sample-seconds` is the gap between the
|
|
13
13
|
// two `git diff --stat` samples of a dirty tree, 60 when omitted. Reached
|
|
14
|
-
// through the Resolver: `~/.fleet/
|
|
14
|
+
// through the Resolver: `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run finisher-audit.mjs ...`.
|
|
15
15
|
//
|
|
16
16
|
// Stdout is always one JSON line, the verdict:
|
|
17
17
|
//
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
//
|
|
8
8
|
// `--pin` is the full 40-hex head the finisher audited; `--repo` is the
|
|
9
9
|
// directory `gh` runs in (it resolves the repository from there), the cwd when
|
|
10
|
-
// omitted. Reached through the Resolver: `~/.fleet/
|
|
10
|
+
// omitted. Reached through the Resolver: `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run
|
|
11
11
|
// finisher-label.mjs ...`.
|
|
12
12
|
//
|
|
13
13
|
// Steps, in this order, each one only if every earlier one held:
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
// `<scratch>/pr<N>/finish-<member>`: the member name is in the path because the
|
|
13
13
|
// scratch root is shared with every sibling, so `pr<N>` alone collides whenever
|
|
14
14
|
// a PR gets a second finisher. Reached through the Resolver:
|
|
15
|
-
// `~/.fleet/
|
|
15
|
+
// `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run finisher-tree.mjs ...`.
|
|
16
16
|
//
|
|
17
17
|
// In order, each step only once every earlier one held:
|
|
18
18
|
//
|