@feigi/fleet-ctl 3.137.4 → 3.138.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +1 -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/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/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 +13 -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
|
@@ -38,7 +38,7 @@ job is red on its current head and you are here to fix it — do not review, do
|
|
|
38
38
|
not dispatch specialists.
|
|
39
39
|
|
|
40
40
|
## kind: review, dispositions-retry
|
|
41
|
-
Read
|
|
41
|
+
Read `~/.omp/plugins/node_modules/@feigi/fleet-ctl/commands/review-and-fix.md` and run **steps 2, 3
|
|
42
42
|
and 5 only**: split apply-now/defer, commit, push, file every deferral as its
|
|
43
43
|
own issue with the label the finding's state calls for. Skip step 1 — the
|
|
44
44
|
review already ran — and steps 4 and 6: the controller owns the CI wait and
|
|
@@ -48,8 +48,8 @@ Label names in this file are roles; the Label map gives the string to type; a me
|
|
|
48
48
|
|
|
49
49
|
**Before your first edit or refuter dispatch, read the Label map — the two
|
|
50
50
|
roles you type or compare, once — and use those strings for the rest of your
|
|
51
|
-
run.** `~/.fleet/
|
|
52
|
-
`~/.fleet/
|
|
51
|
+
run.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show needs-triage` and
|
|
52
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show wontfix` each print the string the
|
|
53
53
|
tracker uses; every `gh` command and label comparison those steps of
|
|
54
54
|
`review-and-fix.md` type for those two roles takes it. You never run `ensure`
|
|
55
55
|
and never ask anyone. **A non-zero exit from `show` ends you with no report** —
|
|
@@ -91,13 +91,13 @@ The ticket:
|
|
|
91
91
|
<ticket>
|
|
92
92
|
## kind: conflict
|
|
93
93
|
Bring `<branch>` current with `origin/main`, resolving every conflict by the
|
|
94
|
-
**No-undo audit** in
|
|
94
|
+
**No-undo audit** in `~/.omp/plugins/node_modules/@feigi/fleet-ctl/commands/run-merge-bot.md`.
|
|
95
95
|
Run `recipe-check.mjs` (below) from the worktree before you push, then push with
|
|
96
|
-
`~/.fleet/
|
|
96
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run push-sync.mjs --branch <branch>`. Report the new head, or that no conflict was
|
|
97
97
|
left.
|
|
98
98
|
## kind: red-check
|
|
99
99
|
Read the failing job's log and fix the cause. Run `recipe-check.mjs` (below)
|
|
100
|
-
from the worktree before you push, then push with `~/.fleet/
|
|
100
|
+
from the worktree before you push, then push with `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run push-sync.mjs --branch <branch>`.
|
|
101
101
|
Report the new head and **stop**: do not watch, poll or wait for CI — the
|
|
102
102
|
controller owns the next run on the pushed head. A red that is not yours to
|
|
103
103
|
fix — a flake that passes on rerun, or staleness — gets nothing pushed: report
|
|
@@ -121,7 +121,7 @@ re-run. That command never deletes an ignored file. A path the re-run still
|
|
|
121
121
|
refuses after that clean → push nothing and report that cause.
|
|
122
122
|
|
|
123
123
|
**`recipe-check.mjs` is how you run `<checkCmd>` and `<testCmd>`:**
|
|
124
|
-
`~/.fleet/
|
|
124
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run recipe-check.mjs --member <your name> --testCmd "<testCmd>" --reports <scratch>/reports`,
|
|
125
125
|
from the worktree, after `git add` and before the commit — `<testCmd>` copied
|
|
126
126
|
verbatim as the one quoted argument. It runs the Recipe's Check step,
|
|
127
127
|
`<checkCmd>`, then `<testCmd>`, against the staged tree and records both beside
|
|
@@ -166,13 +166,13 @@ nothing past, `applied` and `deferred` empty, `dispositionsRecord` and
|
|
|
166
166
|
|
|
167
167
|
Your report is a file, `<scratch>/reports/<your name>.json`, `<your name>` the
|
|
168
168
|
`fix-pr-` name you were dispatched as, in the shape
|
|
169
|
-
`~/.fleet/
|
|
169
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run report-schema.mjs print fix-pr` prints. A field with
|
|
170
170
|
nothing real to point at is `null`: `dispositionsRecord` for a conflict hold or
|
|
171
171
|
a red-check fix, which write no dispositions record, and `testRun` when no test
|
|
172
172
|
run exists — a `no-op`, or a `failed` that never ran tests. A non-null value
|
|
173
173
|
always reflects a real record or a real run. Write the report before your
|
|
174
174
|
final message, and send nothing until
|
|
175
|
-
`~/.fleet/
|
|
175
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run report-schema.mjs validate fix-pr <scratch>/reports/<your name>.json`
|
|
176
176
|
answers `valid`. Your final message is then one line,
|
|
177
177
|
`<your name>: <outcome> <scratch>/reports/<your name>.json`, `<outcome>` the
|
|
178
178
|
report's `outcome`.
|
|
@@ -27,7 +27,7 @@ The ticket, pasted verbatim from the controller's own read — its title, the
|
|
|
27
27
|
The controller's staleness probe: <staleness>
|
|
28
28
|
|
|
29
29
|
Before you commit and push, run
|
|
30
|
-
`~/.fleet/
|
|
30
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run recipe-check.mjs --member <your name> --testCmd ./agent-test --reports <scratch>/reports`
|
|
31
31
|
from the worktree, after `git add`: it runs the Recipe's Check step, then
|
|
32
32
|
`./agent-test`, against the staged tree and records both beside your report.
|
|
33
33
|
Run it again after any content change or rebase. After the commit, and before
|
|
@@ -69,9 +69,9 @@ maintainer.
|
|
|
69
69
|
|
|
70
70
|
Your report is a file, `<scratch>/reports/<your name>.json`, `<your name>` the
|
|
71
71
|
`impl-<N>[-x]` you were dispatched as, in the shape
|
|
72
|
-
`~/.fleet/
|
|
72
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run report-schema.mjs print impl` prints. Write it before
|
|
73
73
|
your final message, and send nothing until
|
|
74
|
-
`~/.fleet/
|
|
74
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run report-schema.mjs validate impl <scratch>/reports/<your name>.json`
|
|
75
75
|
answers `valid`. Your final message is then one line,
|
|
76
76
|
`<your name>: <outcome> <scratch>/reports/<your name>.json`, `<outcome>` the
|
|
77
77
|
report's `outcome`.
|
|
@@ -8,9 +8,9 @@ You are merge-bot-<n>.
|
|
|
8
8
|
scratch: <scratch>
|
|
9
9
|
|
|
10
10
|
Your report is a file, `<scratch>/reports/merge-bot-<n>.json`, in the shape
|
|
11
|
-
`~/.fleet/
|
|
11
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run report-schema.mjs print merge-bot` prints. Write it
|
|
12
12
|
before your final message, and send nothing until
|
|
13
|
-
`~/.fleet/
|
|
13
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run report-schema.mjs validate merge-bot <scratch>/reports/merge-bot-<n>.json`
|
|
14
14
|
answers `valid`. Your final message is then one line,
|
|
15
15
|
`merge-bot-<n>: done <scratch>/reports/merge-bot-<n>.json`. A Label map
|
|
16
16
|
refusal, which `run-merge-bot.md` describes, follows that line with what
|
|
@@ -137,7 +137,7 @@ detected by its mark going stale. A run that stops KNOWINGLY can do better
|
|
|
137
137
|
than being detected, and nothing else can write the reason afterwards:
|
|
138
138
|
|
|
139
139
|
```bash
|
|
140
|
-
~/.fleet/
|
|
140
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run fleet-heartbeat.mjs --stop "budget exhausted"
|
|
141
141
|
```
|
|
142
142
|
|
|
143
143
|
Skipping it is not fatal — the next reader still reports the stop, it just
|
|
@@ -78,7 +78,7 @@ while :; do # one tick
|
|
|
78
78
|
hidden_out=
|
|
79
79
|
fi
|
|
80
80
|
for pr in $(printf '%s\n' "$prs"); do # inline $(...): `for pr in $prs` is ONE iteration under zsh
|
|
81
|
-
st=$(~/.fleet/
|
|
81
|
+
st=$(~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ci-state.mjs --pr "$pr" 2>/dev/null) || : # not-green exits non-zero; the payload is the verdict
|
|
82
82
|
if ! printf '%s' "$st" | jq -e '.verdict and .verdict != "rate-limited"' >/dev/null 2>&1; then
|
|
83
83
|
case " $blind " in *" $pr "*) ;; *) # latch keyed BY PR: this cause is per-PR
|
|
84
84
|
echo "WATCHER DEGRADED: no usable ci-state reading for #$pr — silence is NOT green"
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
replacement controller too — and keeps the review, fix-applier and merge rows
|
|
9
9
|
firing until the open PRs merge. The drain starts the end of the run; it does
|
|
10
10
|
not end it. **End of run**, in this order:
|
|
11
|
-
1. `~/.fleet/
|
|
11
|
+
1. `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run fleet-event.mjs drain --reason "<reason>"` — runs
|
|
12
12
|
`closeout.mjs begin --reason "<reason>"` (references/reaping.md), then the tick. A claim it refuses prints `NEED hand-release #<N> <blocker>`: that
|
|
13
13
|
refusal is the finding, so run `worktree-audit.sh` and decide by hand.
|
|
14
14
|
`begin` selects a claim with no PR and a live or `bailed` implementer token
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
2. Act on the review, fix-applier and merge rows until the tick prints
|
|
18
18
|
`ACTION: run over → fleet-heartbeat.mjs --stop "<reason>"`, which it does
|
|
19
19
|
once the run is draining with no open PR and no live implementer.
|
|
20
|
-
3. `~/.fleet/
|
|
20
|
+
3. `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run closeout.mjs finish --reason "<reason>"` — scrapes
|
|
21
21
|
the run's member facts, checks the tier-outcomes rows, refreshes the
|
|
22
22
|
metrics, commits the three metrics files and opens their PR, sets the
|
|
23
23
|
phase-0 receipt aside as `.fleet/phase0.previous.json`, records
|
|
@@ -83,7 +83,7 @@ re-dispatched picks the new transcript up. **Never hand-edit
|
|
|
83
83
|
role classifier changes, and a hand-entered value would not survive that. The
|
|
84
84
|
verdict for a PR goes to `tier-outcomes.tsv` through `tier-outcomes.mjs
|
|
85
85
|
append`, as above. Once both files hold this run's rows, and before either is
|
|
86
|
-
committed, run `~/.fleet/
|
|
86
|
+
committed, run `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run tier-outcomes.mjs check --live`. Exit 1
|
|
87
87
|
names each row whose `tier` disagrees with the one implementer the member facts
|
|
88
88
|
say ran for its ticket: correct that row's `tier` to the short name it prints,
|
|
89
89
|
or blank it and say why in `note`. Exit 1 also names the PRs of the case where
|
|
@@ -103,7 +103,7 @@ issue number among the reasons — comes before that PR's WARNING and says why.
|
|
|
103
103
|
|
|
104
104
|
**Drain the pending ticket-features rows and refresh the cost guard, after
|
|
105
105
|
the member-outcomes scrape and every `tier-outcomes.mjs append`, before the
|
|
106
|
-
metrics files are committed.** `~/.fleet/
|
|
106
|
+
metrics files are committed.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run metrics-refresh.mjs`
|
|
107
107
|
moves `.fleet/ticket-features.pending.tsv` — the row the router script
|
|
108
108
|
appended for each Pull at dispatch — into `docs/metrics/ticket-features.tsv`,
|
|
109
109
|
deduped on `session`+`agent`, so this run's own rows are in the file that gets
|
|
@@ -153,4 +153,4 @@ The step can refuse in each of these ways:
|
|
|
153
153
|
|
|
154
154
|
## Undo a drain
|
|
155
155
|
|
|
156
|
-
**Undrain only when the maintainer asks, and never a drain that budget or context exhaustion caused.** `~/.fleet/
|
|
156
|
+
**Undrain only when the maintainer asks, and never a drain that budget or context exhaustion caused.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run fleet-event.mjs undrain --reason "<reason>"` runs `closeout.mjs reopen --reason "<reason>"`, then the tick, as `drain` does. `reopen` refuses (exit 2) once any `finish` step in `.fleet/closeout.json` is `ok`, because the tick and what follows it have already acted; a `finish` whose `tick` failed blocks nothing. Otherwise it puts `begin`'s `drain` and `release` steps back to pending and clears `begun`, then runs `ledger.mjs undrain "<reason>"`, which clears the marker, so the next `begin` drains and releases again. With no marker set it refuses (exit 2). A ledger drained by a bare `ledger.mjs drain`, with no receipt, is only undrained. A claim `begin` released stays released: its ticket goes back to the queue and is dispatched under the next free name (`impl-<N>-b`), because `ledger.mjs dispatch` refuses a name already dispatched this session.
|
|
@@ -37,7 +37,7 @@ reaches it anyway, and neither replaces the other.
|
|
|
37
37
|
## Audit every worktree before dispatching replacements
|
|
38
38
|
|
|
39
39
|
Audit every worktree before dispatching replacements with
|
|
40
|
-
`~/.fleet/
|
|
40
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run worktree-audit.sh` — it reports each worktree's
|
|
41
41
|
ahead-count and uncommitted files, the committed-vs-uncommitted distinction that
|
|
42
42
|
decides whether a replacement redoes or destroys work.
|
|
43
43
|
|
|
@@ -54,7 +54,7 @@ review-due. A
|
|
|
54
54
|
runner member that is killed rather than failed follows **Failure
|
|
55
55
|
handling** (fresh name, inherited state stated).
|
|
56
56
|
|
|
57
|
-
**Verify every reported SHA.** `~/.fleet/
|
|
57
|
+
**Verify every reported SHA.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run verify-sha.sh
|
|
58
58
|
<branch> <sha>` before enqueueing — a member can commit in a nested worktree,
|
|
59
59
|
leaving the SHA on a stray branch while its report reads normally. Exit codes as
|
|
60
60
|
`inflight.sh`: `# 0 reachable, 1 not reachable, 2 unanswerable`. Not reachable
|
|
@@ -240,7 +240,7 @@ head is not part of it, and duty 1 audits that head separately.
|
|
|
240
240
|
|
|
241
241
|
## A Ticketless PR has no mutation and no ruling
|
|
242
242
|
|
|
243
|
-
**A Ticketless PR skips the acceptance mutation on `ticketless.mjs`'s exit 0 alone.** Run `~/.fleet/
|
|
243
|
+
**A Ticketless PR skips the acceptance mutation on `ticketless.mjs`'s exit 0 alone.** Run `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ticketless.mjs --pr <M>`. It reads whether the PR closes an issue in its own repository and whether a settled `impl-<N>=PR#<M>` token names it; with neither, no ticket supplies a mutation to re-run, so exit 0 skips it whatever the diff, and the rest of duty 2 runs. Exit 1 and exit 2 (could not look) run duty 2 as for a ticket PR. Where a kill's evidence line would go, the report says that no mutation ran because the PR is ticketless.
|
|
244
244
|
|
|
245
245
|
**Duty 3 holds a Ticketless PR whose diff is not inert.** `finisher-label.mjs` adds `patch` to a Ticketless PR that carries no release label, then runs the Inert diff verdict in-process at your pin. A diff that is not inert, or a verdict that could not look, gets the `ready-to-merge-head:` record and no `ready-to-merge`, and the script exits 5: halt with cause `human`. No ticket gives that PR a ruling or a mutation, so the maintainer's `ready-to-merge` is the merge. The merge bot merges it off the record at the pinned head, and a head that moved after the record is merged by hand.
|
|
246
246
|
|
|
@@ -257,7 +257,7 @@ ordering is detectable afterwards from the diff — a restore lands on the
|
|
|
257
257
|
uncommitted clause and destroys it silently, or the mutant is still in the
|
|
258
258
|
tree when the fix-applier commits and a deliberately broken guard ships as
|
|
259
259
|
the fix, in a commit nothing re-reviews. So take your own:
|
|
260
|
-
`~/.fleet/
|
|
260
|
+
`~/.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>`
|
|
261
261
|
adds `git worktree add --detach <scratch>/pr<N>/finish-<your member name> <your dispatch pin>`
|
|
262
262
|
and runs the Install step in it, as a claim does: a detached worktree holds
|
|
263
263
|
tracked files only, so without that step a suite whose dependencies are
|
|
@@ -78,7 +78,7 @@ is the repository that `repository.url` in the Install root's `package.json`
|
|
|
78
78
|
names — the same host and `owner/repo` — file it the way `review-and-fix.md`
|
|
79
79
|
step 5 files a deferral: `ledger.mjs check "<subject>"`, then
|
|
80
80
|
`gh issue create --label "<needs-triage string>"`, `<needs-triage string>` being what
|
|
81
|
-
`~/.fleet/
|
|
81
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show needs-triage` prints, then `ledger.mjs filed <N> "<subject>"` with the same subject. A
|
|
82
82
|
tracker hit is handled the way step 5 handles one. The subject is `<path>: <the
|
|
83
83
|
defect in one line>`; the body carries the evidence — the members, the text
|
|
84
84
|
they followed, the transcript and ledger lines — the trigger it met, the
|
|
@@ -6,7 +6,7 @@ Why isolation envelope file not briefing, why private filesystem not private sta
|
|
|
6
6
|
|
|
7
7
|
Env vars in prompt missed five times in one run — including briefed member, and specialist whose parent briefed but did not pass down. So the runner is a file in the worktree. A claim writes `agent-test` into the fresh worktree it creates: an exec of the Recipe's Test entrypoint that exports one port triple derived from `<N>`, kept out of `git status` through the repository's exclude file. A repository that tracks its own `agent-test` keeps it byte-identical — the claim exports nothing into it, so its isolation is whatever that repository built, and any convenience beyond exec'ing the Test entrypoint is that runner's own to document. Brief members with `./agent-test` and nothing else: anyone who finds worktree finds runner — including grandchildren you never dispatched. Its arguments land after the Test entrypoint, so what one may name — a test file, a test name — is that entrypoint's to say, and nothing in the runner refuses one that selects no test: a run of zero tests is a failed run, not a pass. That triple makes collisions impossible, not discouraged — difference between safeguard and rule.
|
|
8
8
|
|
|
9
|
-
The runner a claim writes is written once and never rewritten — a claim refuses a worktree that already exists — so every copy under `.worktrees/` is frozen at whenever that worktree was claimed; reading or measuring one measures that build, not what the current emitter produces. Line 2 is what tells a reader which build they are holding: `# agent-test template: <cksum>`. Reproduce the number from the installed script (`cksum $(~/.fleet/
|
|
9
|
+
The runner a claim writes is written once and never rewritten — a claim refuses a worktree that already exists — so every copy under `.worktrees/` is frozen at whenever that worktree was claimed; reading or measuring one measures that build, not what the current emitter produces. Line 2 is what tells a reader which build they are holding: `# agent-test template: <cksum>`. Reproduce the number from the installed script (`cksum $(~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run --path claim-ticket.sh)`) or from any revision of it (`git show <rev>:plugin/scripts/claim-ticket.sh | cksum`) and compare the first field — `cksum` also prints a byte count, and the path when it is given a file. It checksums the whole emitting script, not the runner template inside it, so it over-reports: a mismatch means only that `claim-ticket.sh`'s bytes differ from the ones you checksummed — a reworded die message or an edited comment moves it while the runner it produces stays byte-identical — not "the template changed", and not "older" either, because `cksum` carries no order: over `claim-ticket.sh`'s own history both the checksum and the byte count fall as well as rise. It under-reports too, so a match is not the freshness proof it looks like. The stamp covers `claim-ticket.sh` and nothing else, while the command the runner `exec`s is the Recipe cache's Test entrypoint, which it does not cover: two claims under one stamp exec different commands once the Recipe is re-derived between them. So read a match as "this runner came from these bytes of `claim-ticket.sh`"; only a fresh claim writes the current runner. Nothing reads the stamp and nothing refuses on a mismatch; it makes staleness legible to a human, it gates nothing.
|
|
10
10
|
|
|
11
11
|
## A worktree no claim built: the runner, and the commit
|
|
12
12
|
|
|
@@ -18,7 +18,7 @@ unless the repository tracks its own, and a member told to run one
|
|
|
18
18
|
stalls on a missing script (observed with a rebase-resolver in a
|
|
19
19
|
prior-run worktree). There, tell the member the runner is absent and to
|
|
20
20
|
run the Recipe's Test entrypoint directly
|
|
21
|
-
(`~/.fleet/
|
|
21
|
+
(`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh <main checkout> test --at origin/main` prints
|
|
22
22
|
it).
|
|
23
23
|
|
|
24
24
|
**A reused worktree may also be on the wrong COMMIT.** `git worktree add <path>
|
|
@@ -115,7 +115,7 @@ tree with neither a HEAD move nor a restore in 7 days of every path git ignores
|
|
|
115
115
|
but its runner, and leaves the tree, its branch and its commits. The renderer
|
|
116
116
|
refuses to brief an implementer
|
|
117
117
|
or a fix-applier into one; before you run code in one by hand, restore it with
|
|
118
|
-
`~/.fleet/
|
|
118
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run evict.mjs --restore <tree> --apply`, which runs the
|
|
119
119
|
Install step there as a claim does.
|
|
120
120
|
|
|
121
121
|
## Filesystem isolation is not stack isolation
|
|
@@ -60,7 +60,7 @@ that was never read and from one whose rows you have to read yourself.
|
|
|
60
60
|
|
|
61
61
|
## Why the ledger outlives your context
|
|
62
62
|
|
|
63
|
-
One git-ignored `.fleet/ledger.md` per run is updated at every state change through the `~/.fleet/
|
|
63
|
+
One git-ignored `.fleet/ledger.md` per run is updated at every state change through the `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ledger.mjs` subcommands (`row`, `filed`, `ruled`, `check`, `read`, `dispatch`, `settle`, `review`, `drain`, `rotate`). Your context is the least durable thing in the run: it compacts, and a controller that loses the dispatch map or the filed list redoes finished work. Two duplicate tickets shipped in one run from exactly that.
|
|
64
64
|
|
|
65
65
|
## One line per ticket
|
|
66
66
|
|
|
@@ -187,7 +187,7 @@ A mismatch on a ticket whose issue is already CLOSED holds nothing: the tick pro
|
|
|
187
187
|
|
|
188
188
|
## The test command every gate runs
|
|
189
189
|
|
|
190
|
-
**The test command every gate runs.** Pass the same command to the review, to the fix-applier, and to the finisher — whose duty-2 mutation gate runs it too — so every gate runs one command. The fix-applier and the finisher run what you hand them, so hand them the wrapped string as `<testCmd>` — `~/.fleet/
|
|
190
|
+
**The test command every gate runs.** Pass the same command to the review, to the fix-applier, and to the finisher — whose duty-2 mutation gate runs it too — so every gate runs one command. The fix-applier and the finisher run what you hand them, so hand them the wrapped string as `<testCmd>` — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run suite-slot.mjs '<command>'`, each `'` inside the command written `'\''` — and it is still one command for every gate. The review wraps its own one run, so its args carry the bare command; a wrapped string handed to it anyway is harmless, the inner wrapper being the nested case. Omit it from the review args and the review (`review-core.mjs`, in a runner) reads the same cache itself, refusing outright when there is none; the fix-applier has no such fallback, so substituting `<testCmd>` with nothing leaves it no gate at all. See `references/isolation.md` (the stack-free test command).
|
|
191
191
|
|
|
192
192
|
## Dispatching the members a wake names, in full
|
|
193
193
|
|
|
@@ -65,7 +65,7 @@ metrics and docs THIS run builds on and nothing pulls them.
|
|
|
65
65
|
## Pin the instruments
|
|
66
66
|
|
|
67
67
|
**Pin the instruments, after that fast-forward and before anything reads
|
|
68
|
-
them, from this main checkout.** `~/.fleet/
|
|
68
|
+
them, from this main checkout.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run instruments.sh --pin`
|
|
69
69
|
records what the scripts and runbooks of the Install root — the tree the
|
|
70
70
|
fleet executes — say right now, which is what every later gate compares
|
|
71
71
|
against; SKILL.md's **Re-check before you act on any instrument reading** says
|
|
@@ -83,7 +83,7 @@ differ. Never dispatch a member into a run whose phase-0 pin refused.
|
|
|
83
83
|
## Record the main-checkout baseline
|
|
84
84
|
|
|
85
85
|
**Record the main-checkout baseline in the same step, right after the
|
|
86
|
-
pin.** `~/.fleet/
|
|
86
|
+
pin.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run main-checkout.mjs --record` writes
|
|
87
87
|
`.fleet/main-checkout.sha`: the main checkout's `git status --porcelain
|
|
88
88
|
-uall` entries plus a content hash of every path they name, and its HEAD —
|
|
89
89
|
symbolic ref and commit. Your own
|
|
@@ -117,7 +117,7 @@ and before the pre-flight.** The **Label map** (`.fleet/labels.json`) gives
|
|
|
117
117
|
the string this repository's tracker uses for each Label role:
|
|
118
118
|
`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`,
|
|
119
119
|
`wontfix`, `in-progress`, `onhold`, `ready-to-merge`. The `labels` step runs
|
|
120
|
-
`~/.fleet/
|
|
120
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs ensure` in this main checkout, which
|
|
121
121
|
reads the cached map, the repository's triage-label table and the tracker's
|
|
122
122
|
live label list, on every call, and never creates a label.
|
|
123
123
|
This step is yours, once per run start: a member never derives the map and
|
|
@@ -164,7 +164,7 @@ want otherwise — a role with no suggestion must be named; labels that do not
|
|
|
164
164
|
exist are created on your confirmation.
|
|
165
165
|
|
|
166
166
|
**Write the answer, say how to keep it, run phase 0 again.** Run
|
|
167
|
-
`~/.fleet/
|
|
167
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs set --create` with the reply:
|
|
168
168
|
`--accept-suggestions` for `defaults`, and each `<role>=<label>` the
|
|
169
169
|
maintainer named. Exit 0 prints the map it wrote; exit 1 is a refusal naming
|
|
170
170
|
the role and the rule, nothing written and nothing created — put it to the
|
|
@@ -181,10 +181,10 @@ the maintainer what it printed and stop, as for a failed `labels` step.
|
|
|
181
181
|
## Run the pre-flight
|
|
182
182
|
|
|
183
183
|
**Run the pre-flight, once the pin and the baseline are recorded.**
|
|
184
|
-
`~/.fleet/
|
|
184
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run preflight.mjs` checks what this machine and this
|
|
185
185
|
repository must give the fleet — the binaries, `gh` auth, `origin/main`,
|
|
186
186
|
`.worktrees/` and `.fleet/` ignored, merge commits on, a
|
|
187
|
-
ruleset
|
|
187
|
+
ruleset — and prints one `ok`, `WARN` or `FAIL` line per
|
|
188
188
|
check, each naming its check. **Exit 1 stops the run:** no shortlist, no
|
|
189
189
|
dispatch. Report every `FAIL` line to the maintainer by its check's name;
|
|
190
190
|
the run starts again once they are fixed. Exit 2 means it could not run at
|
|
@@ -227,7 +227,7 @@ person choosing to.
|
|
|
227
227
|
|
|
228
228
|
**Drain the pending ticket-features rows and refresh the cost guard, after
|
|
229
229
|
the fast-forward and before the first Pull is routed.**
|
|
230
|
-
`~/.fleet/
|
|
230
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run metrics-refresh.mjs` moves
|
|
231
231
|
`.fleet/ticket-features.pending.tsv` into `docs/metrics/ticket-features.tsv`,
|
|
232
232
|
deduped on `session`+`agent` — this recovers the rows of a run that crashed
|
|
233
233
|
before its close-out — and then runs `pr-cost.mjs --guard`, rewriting
|
|
@@ -253,7 +253,7 @@ line leaves the exit at 0, so it never stops the run.
|
|
|
253
253
|
## Launch the cockpit
|
|
254
254
|
|
|
255
255
|
**Launch the cockpit.** On every phase-0 pass, not just the first:
|
|
256
|
-
`node ~/.fleet/
|
|
256
|
+
`node ~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run board.mjs serve --open &` in the
|
|
257
257
|
background. It is a read-only mirror of `.fleet/ledger.md` + `gh` — you never
|
|
258
258
|
feed or update it, and it survives your own compaction. The launch is
|
|
259
259
|
idempotent per workspace when the running cockpit answers the identity
|
|
@@ -295,7 +295,7 @@ it and nothing signals its pid.
|
|
|
295
295
|
|
|
296
296
|
**Rotate the ledger before the fold-in below and before shortlisting —
|
|
297
297
|
every run, whatever way the previous one ended.** One ledger per run:
|
|
298
|
-
`~/.fleet/
|
|
298
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ledger.mjs rotate` moves the previous run's
|
|
299
299
|
`.fleet/ledger.md` byte-for-byte to `.fleet/ledger.<UTC
|
|
300
300
|
YYYY-MM-DDTHHMMSSZ>.md` and leaves none behind. What it carries forward
|
|
301
301
|
turns on the verdict it reaches below. After `dead` or `none` nothing is
|
|
@@ -391,7 +391,7 @@ Before the rotation, `phase0.mjs` puts the held-aside receipt (`phase0.previous.
|
|
|
391
391
|
## Reclaim scratch
|
|
392
392
|
|
|
393
393
|
**Reclaim scratch straight after the rotation — every run.**
|
|
394
|
-
`~/.fleet/
|
|
394
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --root <scratch>
|
|
395
395
|
--after-rotate --apply`, `<scratch>` the path `scratch-root.mjs` prints,
|
|
396
396
|
so a run that merges nothing still reclaims the previous run's leftovers
|
|
397
397
|
(`reclaim-scratch.mjs`'s header says what it removes).
|
|
@@ -410,7 +410,7 @@ its reason — and exits 0 even when a removal failed; record nothing on the
|
|
|
410
410
|
ledger.
|
|
411
411
|
|
|
412
412
|
Straight after that, the same step reclaims the other keys under the scratch parent:
|
|
413
|
-
`~/.fleet/
|
|
413
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --siblings --root <scratch> --apply`. A key
|
|
414
414
|
goes whole when nothing under it has changed in 7 days, and stays whole otherwise. The
|
|
415
415
|
call runs whatever the root sweep answered, and records nothing on the ledger. A non-zero
|
|
416
416
|
exit, and each path its receipt's `failed[]` names, is listed in the step's output; neither
|
|
@@ -419,7 +419,7 @@ stops the run.
|
|
|
419
419
|
## Evict idle claim trees
|
|
420
420
|
|
|
421
421
|
**Evict straight after the reclaim — every run.**
|
|
422
|
-
`~/.fleet/
|
|
422
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run evict.mjs --after-rotate --apply` is phase 0's own
|
|
423
423
|
`evict` step. A claim tree with neither a HEAD move nor a restore in 7 days loses
|
|
424
424
|
every path git ignores in it but its `agent-test` runner; the claim, its tree,
|
|
425
425
|
its branch and its commits stay (`evict.mjs`'s header says what keeps a tree).
|
|
@@ -434,7 +434,7 @@ straight after its reclaim, and reports it on an `APPLIED evict:` or
|
|
|
434
434
|
**An evicted tree is restored before a member runs code there.**
|
|
435
435
|
`dispatch-prompt.mjs render implementer` and `render fix-applier` refuse a
|
|
436
436
|
worktree evict.mjs marked, naming
|
|
437
|
-
`~/.fleet/
|
|
437
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run evict.mjs --restore <tree> --apply`: run it, then render
|
|
438
438
|
again. It runs the Install step in the tree as a claim does and refuses as a
|
|
439
439
|
claim does. A refused restore leaves the tree evicted: dispatch nothing into
|
|
440
440
|
it, report the restore's message, and the row comes up again on the next wake.
|
|
@@ -448,9 +448,9 @@ and before the first claim.** Every claim runs this repository's Install
|
|
|
448
448
|
step and bakes its Test entrypoint into the member's runner, and every
|
|
449
449
|
review reads the Test entrypoint, all out of the **Recipe cache**
|
|
450
450
|
(`.fleet/recipe.json` beside the common git dir); no script infers either
|
|
451
|
-
command. Check it first: `~/.fleet/
|
|
452
|
-
install --at origin/main`, `~/.fleet/
|
|
453
|
-
--at origin/main` and `~/.fleet/
|
|
451
|
+
command. Check it first: `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh .
|
|
452
|
+
install --at origin/main`, `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh . check
|
|
453
|
+
--at origin/main` and `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh . test --at
|
|
454
454
|
origin/main`. **All three exit
|
|
455
455
|
0 → the cache is present and valid: use it as it stands and derive
|
|
456
456
|
nothing.** Any exits 1 (a refusal about the cache) → derive it; a refusal
|
|
@@ -461,7 +461,7 @@ unknown: fix that environment fault and check again; deriving would not
|
|
|
461
461
|
help. This step is yours: one derivation
|
|
462
462
|
per run start at most, never one per member, and a member never derives.
|
|
463
463
|
Dispatch a `task` member named `derive-recipe`, agent
|
|
464
|
-
`fleet-recipe-deriver`, its prompt the brief `~/.fleet/
|
|
464
|
+
`fleet-recipe-deriver`, its prompt the brief `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run
|
|
465
465
|
dispatch-prompt.mjs render recipe-deriver --member derive-recipe --repo <repo>
|
|
466
466
|
--scratch <scratch>` prints, and wait for its report — nothing in this run can
|
|
467
467
|
claim before it lands. `<repo>` is this main checkout's absolute path and
|
|
@@ -481,7 +481,7 @@ PROVEN`** → re-run the three reads above (`derive-testcmd.sh . install --at or
|
|
|
481
481
|
their output is the Recipe this run uses. **`RECIPE NOT PROVEN`** →
|
|
482
482
|
stall, below.
|
|
483
483
|
|
|
484
|
-
**Where `checkCmd` comes from:** the repository's Check step, out of the same Recipe cache — `~/.fleet/
|
|
484
|
+
**Where `checkCmd` comes from:** the repository's Check step, out of the same Recipe cache — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh . check` prints it. Pass it to the fix-applier beside `testCmd`; the review does not run it. Neither member runs the two by hand: `recipe-check.mjs` runs the Check step it reads off that cache, then the `testCmd` it is handed, on the member's staged tree, and writes the record `ledger.mjs settle --from-report` requires of an implementer's and a fix-applier's report.
|
|
485
485
|
|
|
486
486
|
**Mid-run, a cache that stops running is re-derived once, then the run
|
|
487
487
|
stalls.** A claim or a review that refuses because the Recipe cache is
|
|
@@ -542,7 +542,7 @@ push, and rotation after a dead run carries no row forward, the candidate
|
|
|
542
542
|
scan excludes `in-progress`, and the in-flight check reads the worktree as
|
|
543
543
|
taken — so a
|
|
544
544
|
claim the previous run left without a PR is held by nobody until this step
|
|
545
|
-
names it. `~/.fleet/
|
|
545
|
+
names it. `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run stranded.mjs` lists and classifies; you
|
|
546
546
|
dispatch. It reads the `prior` rotate just recorded, never the record
|
|
547
547
|
itself, which names this run's own live controller, and prints
|
|
548
548
|
`{prior, claims: [{n, t, action, worktree, branch, why}], carried: [{name,
|
|
@@ -622,7 +622,7 @@ stranded.
|
|
|
622
622
|
|
|
623
623
|
## Build the Shortlist
|
|
624
624
|
|
|
625
|
-
1. **Build the Shortlist** — `~/.fleet/
|
|
625
|
+
1. **Build the Shortlist** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run shortlist.mjs`, then read
|
|
626
626
|
`.fleet/shortlist.json`. The script runs the cheap filters and nothing else
|
|
627
627
|
— no ticket body is read here, because a Pull reads one ticket in full at
|
|
628
628
|
the moment it admits it:
|
|
@@ -16,7 +16,7 @@ terminating in exactly one dispatch or an empty shortlist:
|
|
|
16
16
|
1. **Take the shortlist head** — the next `.fleet/shortlist.json` entry with no
|
|
17
17
|
`impl-` row and no `excluded` row whose premise still holds, which is the
|
|
18
18
|
ticket the tick's `PULL` row names.
|
|
19
|
-
2. **In-flight check, again** — `~/.fleet/
|
|
19
|
+
2. **In-flight check, again** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run inflight.sh <N>`; any
|
|
20
20
|
hit = taken, drop it and take the next entry. The shortlist is as old as its
|
|
21
21
|
last refresh. It runs all three probes (PRs, remote heads, local
|
|
22
22
|
worktrees + branches) so a partial one cannot read as free. The PR probe is
|
|
@@ -166,7 +166,7 @@ terminating in exactly one dispatch or an empty shortlist:
|
|
|
166
166
|
`origin/main`, the fatal-not-empty case above.
|
|
167
167
|
|
|
168
168
|
**`staleness.mjs` runs that check for you, and answers in THREE values.**
|
|
169
|
-
`~/.fleet/
|
|
169
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run staleness.mjs --path <path> --gone
|
|
170
170
|
'<string>'`, or `--present '<string>'`, once per claim the ticket makes.
|
|
171
171
|
It goes here and not in `shortlist.mjs` because choosing WHICH string
|
|
172
172
|
settles a ticket needs the ticket read, which the step above already did —
|
|
@@ -245,9 +245,9 @@ terminating in exactly one dispatch or an empty shortlist:
|
|
|
245
245
|
scope` `#N` refs as candidates: `clear`; `behind-pr:#M`, an open PR or a
|
|
246
246
|
branch with no PR yet by its name; `behind-issue:#M`, an open issue that
|
|
247
247
|
section sequences this one after; or `paths <p>…`, which scans again.
|
|
248
|
-
6. **Claim** — `~/.fleet/
|
|
248
|
+
6. **Claim** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run claim-ticket.sh <N> impl-<N> implementer
|
|
249
249
|
--apply` (below). Exit 2 → treat it as taken, next entry.
|
|
250
|
-
7. **Route, row, then dispatch** — `~/.fleet/
|
|
250
|
+
7. **Route, row, then dispatch** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ticket-router.mjs route
|
|
251
251
|
--session <session> --ticket <N> --arm <A|B> --impl-row <k>[ --chain-head] --issue
|
|
252
252
|
<scratch>/impl-<N>/issue.json --guard .fleet/cost-guard.json` prints the Pull's
|
|
253
253
|
Routing, `POLICY=… CELL=… DRAW=… BY=… STRATUM=… BRIEF=… CRITERIA=… PARENT=… SIZED=… OBJECTIVE=… TRIPPED=… REASON=…`
|
|
@@ -320,8 +320,8 @@ the stranded comment's heading line and URL, which is not one of the
|
|
|
320
320
|
`briefs/relabel.md` comments.
|
|
321
321
|
`gh issue edit <N> --remove-label "<ready-for-agent string>" --add-label "<label string>"` (no
|
|
322
322
|
`in-progress` to drop — it was never claimed), preceded by exactly one comment,
|
|
323
|
-
the one `~/.fleet/
|
|
324
|
-
prints. Each `<… string>` is what `~/.fleet/
|
|
323
|
+
the one `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run dispatch-prompt.mjs render relabel --kind <kind> …`
|
|
324
|
+
prints. Each `<… string>` is what `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show <role>` prints for that role — `<label string>` for the role the cause names — and you type that string, not the role name; where the rendered comment names `ready-for-agent`, file the string `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show ready-for-agent` prints in its place. `--kind needs-triage` takes `--line`, the one-line missing decision;
|
|
325
325
|
`--kind fork` takes `--options`, the options verbatim from the brief, and is
|
|
326
326
|
the `ready-for-human` comment for a fork; `--kind hands` takes `--hands`,
|
|
327
327
|
one of external access, manual testing or judgment during the work, and
|
|
@@ -356,7 +356,7 @@ read that way: `gh pr view` finds no PR for the branch, so it is exit 2, not a
|
|
|
356
356
|
|
|
357
357
|
## Claiming
|
|
358
358
|
|
|
359
|
-
**Claiming.** `~/.fleet/
|
|
359
|
+
**Claiming.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run claim-ticket.sh <N> impl-<N> implementer --apply` does
|
|
360
360
|
the label, worktree, branch, the Recipe's Install step, the clean-tree assertion, and the
|
|
361
361
|
isolation runner in one serial pass. The two arguments are always that literal
|
|
362
362
|
pair — `impl-<N>` as `<slug>`, `implementer` as `<type>` — so the claim is
|
|
@@ -396,9 +396,9 @@ a worktree, a branch and an `in-progress` label with no member behind them,
|
|
|
396
396
|
released by the end-of-run sweep rather than by a member that did the work.
|
|
397
397
|
|
|
398
398
|
**Record the dispatch before you make it.** `ledger.mjs row` wrote the row at
|
|
399
|
-
the Pull's step 7; `~/.fleet/
|
|
399
|
+
the Pull's step 7; `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run dispatch-prompt.mjs render
|
|
400
400
|
implementer --member impl-<N> …` then renders its brief, and
|
|
401
|
-
`~/.fleet/
|
|
401
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ledger.mjs dispatch <N> impl-<N>`
|
|
402
402
|
marks `impl-<N>` live on it and in `## Dispatched`, and the call follows.
|
|
403
403
|
Its JSON carries `agent`, the definition that call names, and `brief.path`,
|
|
404
404
|
the rendered brief whose content is that call's prompt — read both off that
|
|
@@ -660,7 +660,7 @@ floor to a count on stderr.
|
|
|
660
660
|
|
|
661
661
|
## A Pull's entry and exits, in full
|
|
662
662
|
|
|
663
|
-
A Pull's entry is `~/.fleet/
|
|
663
|
+
A Pull's entry is `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run pull.mjs next --head <N>`, run from the
|
|
664
664
|
main checkout (without `--head`, the next shortlist entry). It runs the
|
|
665
665
|
mechanical steps in order and stops at each judgement with a `QUESTION
|
|
666
666
|
<qid>:` block and exit 10; `pull.mjs answer <N> <qid> <token> [--path <p>] [--]
|
|
@@ -680,3 +680,11 @@ one scan, oldest first; admission never is. The invariant this replaces — one
|
|
|
680
680
|
human decision per batch of admissions, zero unilateral grabs — is retired
|
|
681
681
|
is retired: zero human decisions per admission, and every non-admission is a
|
|
682
682
|
label or a premise the maintainer can read.
|
|
683
|
+
|
|
684
|
+
## Red flags: is it decided
|
|
685
|
+
|
|
686
|
+
- "Touches eight files, too big for the fleet" → size is not the axis. Decided is.
|
|
687
|
+
- "Body is three lines, so it's simple" → short bodies hide open design choices.
|
|
688
|
+
- "The brief is thorough, so it's decided" → thorough ≠ decided. Read it for the
|
|
689
|
+
choice it leaves open.
|
|
690
|
+
- "I'd have to pick an approach myself" → that IS undecided.
|
|
@@ -89,4 +89,16 @@ fix-pr PR#<pr>` (**The fix-applier**).
|
|
|
89
89
|
|
|
90
90
|
## Never reap a branch a live member is on
|
|
91
91
|
|
|
92
|
-
Cross-check `.fleet/ledger.md` before running: row without terminal state means someone may still be in that worktree — merged PR can still have reviewer filing follow-ups. Dirty check does not see member that committed but not pushed. Update reaped tickets' ledger rows in same step, report reaped and kept counts. Kept-with-reason is half worth reading.
|
|
92
|
+
Cross-check `.fleet/ledger.md` before running: row without terminal state means someone may still be in that worktree — merged PR can still have reviewer filing follow-ups. Dirty check does not see member that committed but not pushed. Update reaped tickets' ledger rows in same step, report reaped and kept counts. Kept-with-reason is half worth reading.
|
|
93
|
+
|
|
94
|
+
## Red flags: reaping and removing a worktree
|
|
95
|
+
|
|
96
|
+
- "The reap at the end will pick up the claim I never dispatched" → it declines:
|
|
97
|
+
not `[gone]`, no unique commits. Release it, or it reads as taken next run.
|
|
98
|
+
- "`commit-commands:clean_gone` printed nothing, the tree is clean" → its
|
|
99
|
+
`[gone]` detection works fine; it just runs `-D`/`--force` with no merged
|
|
100
|
+
check, so "printed nothing" only means nothing was gone yet, not that it's safe.
|
|
101
|
+
- "`--force` the worktree removal, the PR merged anyway" → merged says nothing
|
|
102
|
+
about uncommitted files, and the reviewer may still be in there.
|
|
103
|
+
- "Reap once at the end of the run" → stale worktrees make phase 0 read merged
|
|
104
|
+
tickets as taken, so the starvation compounds with every Pull.
|
|
@@ -96,7 +96,7 @@ reads gates and never injects a fault.
|
|
|
96
96
|
the worktree from. Pass it as `--branch`, because
|
|
97
97
|
the member cannot read it off git: references/isolation.md creates an already-open PR's worktree
|
|
98
98
|
with `--detach`, and there `git branch --show-current` prints nothing and exits 0
|
|
99
|
-
(measured 2026-09-18, git 2.50.1), so `~/.fleet/
|
|
99
|
+
(measured 2026-09-18, git 2.50.1), so `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run push-sync.mjs
|
|
100
100
|
--branch "$(git branch --show-current)"` is handed an empty branch and exits 2
|
|
101
101
|
before pushing anything. A brief rendered without it would leave the push no
|
|
102
102
|
destination at all, which is why the renderer requires it.
|
|
@@ -229,3 +229,11 @@ retry letter's when there are several), so you pass no `--sizing`; the member
|
|
|
229
229
|
also puts it in the PR body's `Sizing:` line, with the signal it turned on;
|
|
230
230
|
`profile`, `loc` and `files` all come from `diff-stats.mjs` over the merged
|
|
231
231
|
diff.
|
|
232
|
+
|
|
233
|
+
## What a shared snapshot did to its readers
|
|
234
|
+
|
|
235
|
+
`review-and-fix.md`'s **Cut TWO trees, not one** rests on this. Observed with a single shared snapshot: three specialists read two *different* in-flight mutations, one reporting the PR's own bug as still present; elsewhere three watched their file go clean → `M` mid-analysis; twice a reviewer came one step from filing a false finding.
|
|
236
|
+
|
|
237
|
+
## What an unbounded read costs
|
|
238
|
+
|
|
239
|
+
`review-and-fix.md`'s **Then bound the read** rests on this. The cost of not bounding is never one-off: a specialist that dumps a 37 KB file carries it in its prefix for every remaining turn, re-billed as cache-read on each. Over one run's 92 subagents the 88 unpiped whole-file calls carried 434 KB (~110k tokens) — the single largest attributed line item in that run — against 319 piped ones. Agents already reach for the bounded form; nothing told them when it is required.
|
|
@@ -143,7 +143,7 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
|
|
|
143
143
|
when HEAD moved, and every live member; it
|
|
144
144
|
attributes nothing, because concurrent members make that a guess. Dispatch
|
|
145
145
|
nothing new and tell the maintainer: they resolve the stray paths FIRST,
|
|
146
|
-
then re-baseline with `~/.fleet/
|
|
146
|
+
then re-baseline with `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run main-checkout.mjs --record`.
|
|
147
147
|
A path entry holds until that re-baseline, tick after tick; a `HEAD …` entry
|
|
148
148
|
clears itself once HEAD reads clean again, and is never re-baselined while
|
|
149
149
|
HEAD is off the run's branch. Never revert the
|
|
@@ -164,7 +164,7 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
|
|
|
164
164
|
resolve any stray paths, which the line does not name; only then re-record.
|
|
165
165
|
- `MAIN-CHECKOUT-NO-BASELINE …` with `HOLD (main checkout no baseline)` — no
|
|
166
166
|
baseline was recorded. Yours to fix: run
|
|
167
|
-
`~/.fleet/
|
|
167
|
+
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run main-checkout.mjs --record`, which references/phase-0.md
|
|
168
168
|
describes under "Record the main-checkout baseline". A baseline
|
|
169
169
|
that vanished mid-run is not a fresh run — report it to the maintainer
|
|
170
170
|
before recording over whatever the tree now holds.
|
|
@@ -17,7 +17,7 @@ Read first: `gh issue view <N> --json title,body,comments --jq '.title, .body, (
|
|
|
17
17
|
| **light** | States exactly what to change, one-two files, no design choice open | Test first, make the one change, run it with the repo's test runner |
|
|
18
18
|
| **heavy** | Ambiguity in *what* to build, >~3 files, new API/schema/UX, or several viable approaches | Write a short plan, then carry it out inline, test first |
|
|
19
19
|
|
|
20
|
-
**Fleet member on heavy: write the plan under your own scratch path, `<scratch>/impl-<N>/` (`<scratch>` is the path your dispatch prompt names; with no dispatcher, the output of `~/.fleet/
|
|
20
|
+
**Fleet member on heavy: write the plan under your own scratch path, `<scratch>/impl-<N>/` (`<scratch>` is the path your dispatch prompt names; with no dispatcher, the output of `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run scratch-root.mjs`), then carry it out inline, test first.**
|
|
21
21
|
Heavy is never a reason to give up: a `ready-for-agent` ticket's `## Agent Brief`
|
|
22
22
|
already settles the open design choices, so plan from it. Solo session has a user:
|
|
23
23
|
settle the open design choices with them before planning.
|