@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
|
@@ -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.
|
|
@@ -72,6 +72,8 @@ So nothing in the run cleans it up. Next run, the in-flight probe's local-worktr
|
|
|
72
72
|
|
|
73
73
|
**A checkout that lands between that fresh check and the delete halts the release after it.** `git worktree add` of an existing branch does not move the ref, so the compare-and-swap succeeds under it. The same `wt_recheck_delete` reap uses then finds the worktree, recreates the branch at the tip, and the release halts with exit 2, `released:false` and a blocker naming that worktree — the shape of a holder caught before the delete. A restore that fails halts the same way, with the tip and the repair command in the blocker.
|
|
74
74
|
|
|
75
|
+
**The branch's config section goes after the delete, as reap's does.** `git update-ref -d` removes the ref and not `[branch "<name>"]`; a later claim of the same name would inherit the dead upstream and read `[gone]` at once. worktree.sh's `wt_clear_branch_config` removes it; a claim that never pushed has none, which is not a fault, and a section that cannot be removed is a note on stderr, never a halt — the ref is already deleted. claim-ticket.sh `--apply` clears the same section before `git worktree add`, since whatever deleted the branch, config under a name no branch holds is leftover; there, a section that cannot be removed refuses the claim.
|
|
76
|
+
|
|
75
77
|
**`worktree remove` without `--force`** refuses on modified and untracked files and deletes ignored files silently (verified, git 2.50.1). Ignored-silently is what is wanted: `claim-ticket.sh` writes an `agent-test` into each fresh worktree it claims of a repository that tracks none, and ignores it through the repository's exclude file, so treating ignored files as dirt would strand every such release. The same asymmetry is why a claim never writes over a tracked `agent-test`: that write would leave a modified tracked path, which this refusal does not forgive. Its refusal is the dirty check recomputed by git at the moment of the delete — for the live-directory case ONLY. `worktree remove` gates that clean check on the same `stat` the guard does, so it is not an independent second opinion: where the path cannot be stat'ed git reaches the same "gone" by the same means, accepts the entry at rc 0 and deregisters a worktree whose files are still on disk (measured, git 2.50.1: an untracked file in a worktree under a `chmod 000` parent). There the `gone` guard is sole arbiter — which is why it establishes absence instead of inferring it from a failed `-e`, and why the fail-open fixed in `1e54bac` survived being reasoned about: guard and backstop fail on the same inputs.
|
|
76
78
|
|
|
77
79
|
**A worktree that wandered off the branch blocks too.** The worktree is located by the branch it has checked out, and it does not stay there — an interrupted rebase leaves it detached, a member can switch it. The lookup then finds nothing, which reads as "no worktree of ours": the dirty check is skipped entirely and the release reports success while the worktree stands with the member's work in it, so the next run's probe still reads the ticket as taken. So a linked worktree at `claim-ticket.sh`'s `.worktrees/<issue>-<slug>` that is *not* on the branch is its own blocker — which remedy it names is the next paragraph, and is not always a hand-release. The path is read as the whole rest of the `worktree list --porcelain` line, never the first whitespace field, or every checkout under a directory with a space in its name reads as a different path.
|
|
@@ -89,4 +91,16 @@ fix-pr PR#<pr>` (**The fix-applier**).
|
|
|
89
91
|
|
|
90
92
|
## Never reap a branch a live member is on
|
|
91
93
|
|
|
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.
|
|
94
|
+
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.
|
|
95
|
+
|
|
96
|
+
## Red flags: reaping and removing a worktree
|
|
97
|
+
|
|
98
|
+
- "The reap at the end will pick up the claim I never dispatched" → it declines:
|
|
99
|
+
not `[gone]`, no unique commits. Release it, or it reads as taken next run.
|
|
100
|
+
- "`commit-commands:clean_gone` printed nothing, the tree is clean" → its
|
|
101
|
+
`[gone]` detection works fine; it just runs `-D`/`--force` with no merged
|
|
102
|
+
check, so "printed nothing" only means nothing was gone yet, not that it's safe.
|
|
103
|
+
- "`--force` the worktree removal, the PR merged anyway" → merged says nothing
|
|
104
|
+
about uncommitted files, and the reviewer may still be in there.
|
|
105
|
+
- "Reap once at the end of the run" → stale worktrees make phase 0 read merged
|
|
106
|
+
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.
|
package/scripts/fleet-bootstrap
DELETED
|
@@ -1,140 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
// The Resolver's one-time bootstrap. Places a copy
|
|
3
|
-
// of `fleet-run` at `~/.fleet/bin/fleet-run` — the one artefact this repo
|
|
4
|
-
// owns OUTSIDE the plugin, because the Resolver cannot resolve itself and no
|
|
5
|
-
// per-session mechanism can carry it (nothing survives between harness
|
|
6
|
-
// Bash-tool calls). Idempotent: re-running reports "unchanged" once the
|
|
7
|
-
// placed copy already matches.
|
|
8
|
-
//
|
|
9
|
-
// SOURCE, and the one licensed exception. Every other script's rule is
|
|
10
|
-
// "only installed scripts run" — never a source checkout.
|
|
11
|
-
// This script's source is always ITS OWN sibling `fleet-run`, i.e. whatever
|
|
12
|
-
// directory this file itself is running from. Two shapes exist for that:
|
|
13
|
-
// - run as an INSTALLED script (this file's own directory IS a registry
|
|
14
|
-
// installPath's scripts/ — the steady state, e.g. invoked as
|
|
15
|
-
// `fleet-run fleet-bootstrap` once a Resolver already exists), or
|
|
16
|
-
// - run DIRECTLY FROM A CHECKOUT (this file's own directory is not any
|
|
17
|
-
// registered installPath) — the state the world is actually in the
|
|
18
|
-
// first time this ever runs, since no install anywhere yet carries
|
|
19
|
-
// `scripts/fleet-run`. This exception is licensed exactly once, loudly.
|
|
20
|
-
// This file cannot tell those apart by calling git (that would be exactly
|
|
21
|
-
// the self-location-derives-a-repo pattern every other script is barred from); it
|
|
22
|
-
// tells them apart by comparing its own directory's PARENT against the
|
|
23
|
-
// registries' recorded installPath strings — a plain string compare, no git
|
|
24
|
-
// involved, so it never anchors a git root to its own location.
|
|
25
|
-
"use strict";
|
|
26
|
-
|
|
27
|
-
const fs = require("node:fs");
|
|
28
|
-
const path = require("node:path");
|
|
29
|
-
const os = require("node:os");
|
|
30
|
-
const crypto = require("node:crypto");
|
|
31
|
-
|
|
32
|
-
const NAME = "fleet-bootstrap";
|
|
33
|
-
|
|
34
|
-
function die(message) {
|
|
35
|
-
process.stderr.write(`${NAME}: ${message}\n`);
|
|
36
|
-
process.exit(2);
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
// The Install root, same resolution point as scripts/fleet-run:
|
|
40
|
-
// the realpath of `~/.omp/plugins/node_modules/@feigi/fleet-ctl`. Absent or
|
|
41
|
-
// dangling answers null, which the caller reports as "omp: not installed".
|
|
42
|
-
function readInstallPath(packagePath) {
|
|
43
|
-
try {
|
|
44
|
-
return fs.realpathSync(packagePath);
|
|
45
|
-
} catch {
|
|
46
|
-
return null;
|
|
47
|
-
}
|
|
48
|
-
}
|
|
49
|
-
|
|
50
|
-
function sha256(buf) {
|
|
51
|
-
return crypto.createHash("sha256").update(buf).digest("hex");
|
|
52
|
-
}
|
|
53
|
-
|
|
54
|
-
function main() {
|
|
55
|
-
const argv = process.argv.slice(2);
|
|
56
|
-
const fromCheckoutFlag = argv.includes("--from-checkout");
|
|
57
|
-
|
|
58
|
-
const ownDir = __dirname;
|
|
59
|
-
const source = path.join(ownDir, "fleet-run");
|
|
60
|
-
|
|
61
|
-
let sourceBuf;
|
|
62
|
-
try {
|
|
63
|
-
sourceBuf = fs.readFileSync(source);
|
|
64
|
-
} catch (e) {
|
|
65
|
-
die(`cannot read ${source} — bootstrap copies fleet-run from its OWN directory and found nothing there (${e.code || e.message})`);
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
const home = os.homedir();
|
|
69
|
-
const PLUGIN_KEY = "@feigi/fleet-ctl"; // the plugin's package name, and its node_modules package dir.
|
|
70
|
-
const ompInstall = readInstallPath(path.join(home, ".omp", "plugins", "node_modules", PLUGIN_KEY));
|
|
71
|
-
// Both sides are realpaths — readInstallPath() already resolved the install,
|
|
72
|
-
// and this file's own directory exists, so its parent resolves too — so a
|
|
73
|
-
// path reached through a symlink (macOS /tmp → /private/tmp) compares equal.
|
|
74
|
-
const parent = fs.realpathSync(path.dirname(ownDir));
|
|
75
|
-
const runningFromInstall = parent === ompInstall;
|
|
76
|
-
|
|
77
|
-
const target = path.join(home, ".fleet", "bin", "fleet-run");
|
|
78
|
-
|
|
79
|
-
// The exception is opt-in, not merely announced: a stray checkout run
|
|
80
|
-
// (a wrong branch, a stale worktree) must not silently overwrite the one
|
|
81
|
-
// artefact outside the plugin. Every steady-state invocation — through
|
|
82
|
-
// the Resolver, once it exists — runs from an install and never needs
|
|
83
|
-
// this flag at all.
|
|
84
|
-
if (!runningFromInstall && !fromCheckoutFlag) {
|
|
85
|
-
die(
|
|
86
|
-
`refusing to place ${target} from ${ownDir}, which is not omp's resolved install root (looked at `
|
|
87
|
-
+ `${ompInstall ? `omp: ${ompInstall}` : "omp: not installed"}) — re-run with --from-checkout to take `
|
|
88
|
-
+ "the one-time bootstrap exception explicitly",
|
|
89
|
-
);
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
if (!runningFromInstall) {
|
|
93
|
-
process.stderr.write(
|
|
94
|
-
`${NAME}: BOOTSTRAP EXCEPTION — running from a source checkout (${ownDir}), not omp's resolved `
|
|
95
|
-
+ "install root (looked at "
|
|
96
|
-
+ `${ompInstall ? `omp: ${ompInstall}` : "omp: not installed"}). `
|
|
97
|
-
+ "This is licensed ONCE, as the Resolver's own bootstrap, because no install anywhere yet carries "
|
|
98
|
-
+ "scripts/fleet-run for an install-root-driven copy to come from. Every other fleet script must run through "
|
|
99
|
-
+ "the Resolver once it exists.\n",
|
|
100
|
-
);
|
|
101
|
-
}
|
|
102
|
-
|
|
103
|
-
fs.mkdirSync(path.dirname(target), { recursive: true });
|
|
104
|
-
|
|
105
|
-
let existingBuf = null;
|
|
106
|
-
try {
|
|
107
|
-
existingBuf = fs.readFileSync(target);
|
|
108
|
-
} catch {
|
|
109
|
-
existingBuf = null;
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
const changed = existingBuf === null || !existingBuf.equals(sourceBuf);
|
|
113
|
-
if (changed) {
|
|
114
|
-
fs.writeFileSync(target, sourceBuf);
|
|
115
|
-
}
|
|
116
|
-
fs.chmodSync(target, 0o755);
|
|
117
|
-
|
|
118
|
-
const sourceHash = sha256(sourceBuf);
|
|
119
|
-
if (existingBuf === null) {
|
|
120
|
-
process.stdout.write(`${NAME}: wrote ${target} (new, sha256 ${sourceHash})\n`);
|
|
121
|
-
} else if (changed) {
|
|
122
|
-
process.stdout.write(`${NAME}: wrote ${target} (changed: sha256 ${sha256(existingBuf)} -> ${sourceHash})\n`);
|
|
123
|
-
} else {
|
|
124
|
-
process.stdout.write(`${NAME}: unchanged — ${target} already matches ${source} (sha256 ${sourceHash})\n`);
|
|
125
|
-
}
|
|
126
|
-
process.stdout.write(`${NAME}: source ${source}\n`);
|
|
127
|
-
|
|
128
|
-
const pathDirs = (process.env.PATH || "").split(path.delimiter);
|
|
129
|
-
const binDir = path.dirname(target);
|
|
130
|
-
if (pathDirs.includes(binDir)) {
|
|
131
|
-
process.stdout.write(`${NAME}: PATH already includes ${binDir}\n`);
|
|
132
|
-
} else {
|
|
133
|
-
process.stdout.write(
|
|
134
|
-
`${NAME}: PATH does not include ${binDir} — add it yourself if you want to run "fleet-run" bare `
|
|
135
|
-
+ `(e.g. add \`export PATH="${binDir}:$PATH"\` to your shell rc); this script edits no rc file\n`,
|
|
136
|
-
);
|
|
137
|
-
}
|
|
138
|
-
}
|
|
139
|
-
|
|
140
|
-
main();
|