@feigi/fleet-ctl 3.69.1 → 3.70.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/commands/review-and-fix.md +1 -1
- package/commands/run-merge-bot.md +1 -1
- package/package.json +1 -1
- package/scripts/fleet-event.mjs +10 -2
- package/scripts/fleet-tick.mjs +12 -4
- package/scripts/ledger-grammar.mjs +29 -2
- package/scripts/ledger.mjs +41 -14
- package/skills/run-team/SKILL.md +68 -625
- package/skills/run-team/references/ci-and-staleness.md +27 -1
- package/skills/run-team/references/ci-watcher.md +88 -0
- package/skills/run-team/references/correction-tickets.md +27 -1
- package/skills/run-team/references/failure-handling.md +35 -0
- package/skills/run-team/references/finisher.md +93 -0
- package/skills/run-team/references/instruments.md +19 -0
- package/skills/run-team/references/isolation.md +140 -1
- package/skills/run-team/references/ledger.md +57 -0
- package/skills/run-team/references/member-lifecycle.md +43 -1
- package/skills/run-team/references/merge-bot.md +14 -0
- package/skills/run-team/references/phase-0.md +5 -1
- package/skills/run-team/references/pull.md +60 -0
- package/skills/run-team/references/reviewers.md +98 -0
- package/skills/run-team/references/shell-traps.md +55 -0
|
@@ -344,3 +344,63 @@ no-acknowledgement line, the foreground-suite line
|
|
|
344
344
|
— and a `staleness.mjs` **could not check** verdict with its
|
|
345
345
|
reason when the Pull got one, so the member's own re-derive step knows the
|
|
346
346
|
controller's probe could not look.
|
|
347
|
+
|
|
348
|
+
## Every 5th Pull goes at an exploration cell
|
|
349
|
+
|
|
350
|
+
**Every 5th Pull by ledger count goes at an exploration cell.** Count the `impl-`
|
|
351
|
+
rows in `.fleet/ledger.md` at Pull time; the Pull that creates row 5, 10, 15 …
|
|
352
|
+
is an Exploration Pull, and the router draws its cell: `k = 1 +
|
|
353
|
+
(sha256("<session>\t<ticket>")[0:8] mod K)` over `router-table.json`'s
|
|
354
|
+
`cells` minus the policy cell, in token order. While the table's `burn_in` is
|
|
355
|
+
true every Pull draws, over every cell, the policy cell included. An
|
|
356
|
+
Exploration Pull records `tier=<cell>` in the row, and a replacement inherits the row's tier —
|
|
357
|
+
written at the Pull's row step, ahead of `ledger.mjs dispatch`, which reads it
|
|
358
|
+
and prints `fleet-implementer-<cell>` as the `agent` to dispatch; a row with
|
|
359
|
+
no `tier=` runs the policy cell. The
|
|
360
|
+
assignment rolls to the next Pull when another open ticket sequences after
|
|
361
|
+
it — a ticket the rest of the run
|
|
362
|
+
depends on; `class` is not read. Do not tell the member it is a control: a member that
|
|
363
|
+
knows it is being measured is not measuring the same thing.
|
|
364
|
+
|
|
365
|
+
## The readout counts deliberate comparisons
|
|
366
|
+
|
|
367
|
+
**The readout counts DELIBERATE comparisons.** An earlier rule asked
|
|
368
|
+
only for a `session`+`role` carrying more than one distinct `model`, which any
|
|
369
|
+
session that happened to stage a routine ticket beside a correction one
|
|
370
|
+
satisfies. Measured 2026-09-12 on one corpus: 198 keys as that query was
|
|
371
|
+
literally written, 35 sessions across 21 `run_date`s once restricted to
|
|
372
|
+
implementers, against 17 real pairs across 8 — so the gate below read itself
|
|
373
|
+
past its floor on sessions where nothing had been controlled. Dispatch alone
|
|
374
|
+
is not enough either: the two rows must actually have RUN a different model or
|
|
375
|
+
effort, because a deliberate dispatch whose two sides resolve to the same model
|
|
376
|
+
(a `modelRoles` override, measured on omp 2026-09-12) controls nothing.
|
|
377
|
+
|
|
378
|
+
## Why the implementer body carries enumerate-and-declare
|
|
379
|
+
|
|
380
|
+
Why the agent body carries what it does — read this before editing any
|
|
381
|
+
`fleet-implementer-<cell>` file, and keep every cell's body byte-identical. Each rule in the body's
|
|
382
|
+
enumerate-and-declare block is load-bearing, for a different reason.
|
|
383
|
+
**Enumerate-and-declare** answers a signature measured four times in one run:
|
|
384
|
+
each implementer fixed exactly the cases its ticket named and left an adjacent
|
|
385
|
+
one of the same class broken — a CRLF body **broken by** the fix for depth and
|
|
386
|
+
split headings, a symlinked worktree after fixing locked and regular-file ones,
|
|
387
|
+
an unreadable `refs/heads/<type>/` after fixing `refs/heads` itself, a bracketed
|
|
388
|
+
file path after fixing typos and vendored ones. **All four failed to close their
|
|
389
|
+
own ticket** — one's acceptance criterion went unmet, and the other three left
|
|
390
|
+
the named defect reachable by a sibling spelling. Every one was caught by
|
|
391
|
+
review, at review cost, which runs 3-5x the implementation it checks.
|
|
392
|
+
|
|
393
|
+
## Default: In-flight bound 5
|
|
394
|
+
|
|
395
|
+
**Default: In-flight bound 5, fixed for the run.** The level is set by load, not
|
|
396
|
+
throughput: B caps live review units (≤ open PRs ≤ B), and the review side is
|
|
397
|
+
about 84 % of cache-write tokens, fanning out to 1 snapshot + up to 6
|
|
398
|
+
specialists + 2 refuters per finding. 5 keeps worst-case review concurrency
|
|
399
|
+
below the former reviewer count of 6 and sits near the measured mean In flight
|
|
400
|
+
of 5.6. On the means that allows ≈ 1.7 merges per open-time hour against 1.89
|
|
401
|
+
measured, so the default does not rest on throughput headroom and the guard's
|
|
402
|
+
throughput test may trip on it; the merge gate saturates near 10–11, so
|
|
403
|
+
raising B past that buys nothing. 8 was rejected: peak review concurrency above
|
|
404
|
+
the former reviewer count, for a throughput gain the backlog does not show it
|
|
405
|
+
needs. Re-derive it from the map's guard once 20 or more PRs have merged under
|
|
406
|
+
it, never from one run's rows.
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Reviewers: the evidence behind the review-side rules
|
|
2
|
+
|
|
3
|
+
Evidence for rules SKILL.md states in Phase 2 and **Reviewers**, keyed by the rule each justifies.
|
|
4
|
+
|
|
5
|
+
## A sizing verdict is a measurement only if it post-dates the run that produced it
|
|
6
|
+
|
|
7
|
+
**A verdict is a measurement only if it post-dates the run that produced it.** A
|
|
8
|
+
`Sizing:` line typed in before the skill ever ran is byte-identical to one the
|
|
9
|
+
skill produced, so the body cannot settle this alone, and neither can the
|
|
10
|
+
member's prose. The report file carries the second source: `sizing.ranBeforePr`,
|
|
11
|
+
whether `sizing-a-ticket` ran before the PR was opened (measured on a member
|
|
12
|
+
that wrote the line first, caught itself, and corrected it), and
|
|
13
|
+
`sizing.signal`, what the verdict turned on. `append` applies the rule itself:
|
|
14
|
+
it records `sizing` only when `ranBeforePr` is true AND `signal` is non-empty.
|
|
15
|
+
Any other state — no report file, one that fails its schema, `sizing` null,
|
|
16
|
+
`ranBeforePr` not true, an empty `signal` — leaves the field BLANK with a
|
|
17
|
+
WARNING naming which, and you say which in `note`. A `--sizing` you do pass
|
|
18
|
+
wins over the file, and stderr names the flag as the source: do not use it to
|
|
19
|
+
fill that gap, and do not re-derive the verdict from the diff to fill it
|
|
20
|
+
either — `sizing-a-ticket` weighs more than file count, and a substituted proxy
|
|
21
|
+
reads as measured too. **A value not in hand is left BLANK, never estimated** —
|
|
22
|
+
blank reads as unknown and drops the row from a stratified comparison, while a
|
|
23
|
+
guess reads as measured and poisons one. Blank still means the field is
|
|
24
|
+
WRITTEN and empty: omit the flag (`--sizing`, `--profile`, `--loc`, `--files`)
|
|
25
|
+
and the script writes that field empty at full width, because a row of some
|
|
26
|
+
in-between width cannot be told apart from a shifted one. The `note` field is
|
|
27
|
+
free text and sits before those four, so the script refuses a tab or newline in
|
|
28
|
+
it: one tab would shift all four for that row alone.
|
|
29
|
+
|
|
30
|
+
## Know the trim before you rely on it
|
|
31
|
+
|
|
32
|
+
**Know the trim before you rely on it — it is wider than `docsOnly` suggests.**
|
|
33
|
+
`diff-stats.mjs` calls a PR docs-only only when it touches **no** src, tests *or*
|
|
34
|
+
config, but that strictness cuts both ways and the size tier trims again on top.
|
|
35
|
+
Measured: a docs PR that also adds one test file is profile `tests-only` and runs
|
|
36
|
+
**three** (correctness+tests+comments), not six; a no-src, no-test diff that
|
|
37
|
+
carries a config file keeps silent-failure at **any** size, so a docs+config diff
|
|
38
|
+
too big for the size tier now runs correctness+silent-failure+comments, not
|
|
39
|
+
correctness+comments; and any `single-file` or `small` profile trims to
|
|
40
|
+
correctness+silent-failure+comments, keeping tests only when a test file is in
|
|
41
|
+
the diff. `comments` is on that floor
|
|
42
|
+
unconditionally — it used to need a docs FILE, and `classify()` scores
|
|
43
|
+
only a prose extension or a README/CHANGELOG-style name docs, so five production PRs whose whole
|
|
44
|
+
substance was prose inside a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and ran
|
|
45
|
+
without the one specialist that fit them, `dimensionsUnrun` empty every time.
|
|
46
|
+
That floor holds **regardless of `hasSrc`** — a one-file `.yml` or
|
|
47
|
+
`.github/` shell change gets silent-failure too, not correctness alone.
|
|
48
|
+
It is the size **tier's** floor,
|
|
49
|
+
so `tests-only` outranks it when the diff has no config file: that profile is
|
|
50
|
+
assigned ahead of `single-file`/`small`, so a no-src, no-config diff that also
|
|
51
|
+
touches a test file gets no silent-failure-hunter — a tests-only diff that also
|
|
52
|
+
carries a config file keeps it. `single-file` means one file at **any** size, so a
|
|
53
|
+
one-file rewrite trims too. An unknown profile widens to the full six, the safe
|
|
54
|
+
direction, so a trim is never something to count on in advance — and a full six
|
|
55
|
+
is never something to assume.
|
|
56
|
+
|
|
57
|
+
## A refutation needs its positive control
|
|
58
|
+
|
|
59
|
+
**A refutation resting on an injection nothing proved landed is not a refutation
|
|
60
|
+
— it is a cell that never ran.** A mutation test and a finding reproduction are
|
|
61
|
+
both failure injections: break something, read what the child does. When the
|
|
62
|
+
break never reaches the child, the child behaves exactly like its baseline, which
|
|
63
|
+
is what a genuine no-effect mutation looks like and what a correctly refuted
|
|
64
|
+
finding looks like. So a negative result is admitted only together with its
|
|
65
|
+
**positive control** — one run proving the injected difference is observable,
|
|
66
|
+
either the child's output differing with the injection present versus absent or
|
|
67
|
+
the child echoing the injected value back from inside. No control → the cell is
|
|
68
|
+
unrun: re-run it, and never record it as a negative. Measured 2026-08-28 and
|
|
69
|
+
re-measured on this tree, against a `probe.sh` that echoes both variables back:
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
zsh -c 'cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh' # BADJ=[unset] SETB=[1 BADJ=1]
|
|
73
|
+
bash -c 'cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh' # BADJ=[1] SETB=[1]
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
zsh does not word-split an unquoted parameter expansion, so the whole string
|
|
77
|
+
arrives as ONE argument: a variable literally named `SETB` takes the value
|
|
78
|
+
`1 BADJ=1`, the injection variable `BADJ` is never set, and the probe still exits
|
|
79
|
+
0. It bites in both directions, and the reproduction direction is the worse one —
|
|
80
|
+
one fix-applier nearly reported a mutant as behaving identically to its baseline,
|
|
81
|
+
while another nearly retired a real review finding as non-reproducing after
|
|
82
|
+
the same shape handed both trees a single argv word and drew `exit 2` from each,
|
|
83
|
+
which is the signature of a correct refutation with nothing anomalous to notice.
|
|
84
|
+
The fix-applier body and every refuter brief carry the rule and the safe
|
|
85
|
+
invocation form; the merge bot's brief is the wrong seat, because a bot
|
|
86
|
+
reads gates and never injects a fault.
|
|
87
|
+
|
|
88
|
+
## Where `<branch>` comes from
|
|
89
|
+
|
|
90
|
+
**Where `<branch>` comes from:** the PR's head branch —
|
|
91
|
+
`gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut
|
|
92
|
+
the worktree from. Pass it as `--branch`, because
|
|
93
|
+
the member cannot read it off git: references/isolation.md creates an already-open PR's worktree
|
|
94
|
+
with `--detach`, and there `git branch --show-current` prints nothing and exits 0
|
|
95
|
+
(measured 2026-09-18, git 2.50.1), so `git push origin
|
|
96
|
+
"HEAD:$(git branch --show-current)"` exits 128 on `fatal: invalid refspec
|
|
97
|
+
'HEAD:'`. A brief rendered without it would leave the push no destination at
|
|
98
|
+
all, which is why the renderer requires it.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Shell traps: the measurements behind them
|
|
2
|
+
|
|
3
|
+
Evidence for the rules SKILL.md states in **Shell traps**, keyed by the rule each justifies.
|
|
4
|
+
|
|
5
|
+
## zsh splits a command substitution, never an unquoted parameter expansion
|
|
6
|
+
|
|
7
|
+
**zsh word-splits an unquoted command substitution's result; it does NOT split
|
|
8
|
+
an unquoted parameter expansion.** That one difference is the whole rule, and the
|
|
9
|
+
hazard is the **assigned-variable** form, never `$(…)`. Measured on zsh 5.9
|
|
10
|
+
against `849`, `850`, `852` on three lines:
|
|
11
|
+
|
|
12
|
+
| Form | zsh | bash / sh |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| `prs=$(gh pr list …)` then `for pr in $prs` | **1 iteration**, all three glued into one value | 3 |
|
|
15
|
+
| `for pr in $(gh pr list …)` | 3 | 3 |
|
|
16
|
+
| `for _ in $(seq 1 60)` | 60 | 60 |
|
|
17
|
+
|
|
18
|
+
## Word the rule against the first row
|
|
19
|
+
|
|
20
|
+
**Word the rule against the first row.** A warning spelled *never `for x in
|
|
21
|
+
$(…)`* names the safe form as the hazard, so a reader avoids the form that works,
|
|
22
|
+
keeps the one that collapses, and rewrites correct bounded polls on the way.
|
|
23
|
+
A ticket was once filed carrying that inversion in its own remedy clause and in its title,
|
|
24
|
+
and its filer measured both forms and retracted it; the corrected rule is this
|
|
25
|
+
row. `$(…)` splits. Leave it alone.
|
|
26
|
+
|
|
27
|
+
## The inline `$(printf …)` form splits on every whitespace character
|
|
28
|
+
|
|
29
|
+
The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase
|
|
30
|
+
3's block uses, but it splits on *every* whitespace character, so it is safe only
|
|
31
|
+
for values that cannot contain one — PR numbers cannot, branch names and paths
|
|
32
|
+
can. Measured on a two-line list whose first value is `two words`: three
|
|
33
|
+
iterations through `$(printf …)`, two through `while IFS= read -r`. On an empty
|
|
34
|
+
`$prs` the counts diverge the other way: `for pr in $(printf '%s\n' "$prs")`
|
|
35
|
+
iterates **zero** times, but the heredoc form iterates **once** with `pr` empty —
|
|
36
|
+
the guard in SKILL.md's heredoc block is what stops that iteration from probing `--pr ""`.
|
|
37
|
+
|
|
38
|
+
## `</dev/null` every command inside a `while read` loop
|
|
39
|
+
|
|
40
|
+
**`</dev/null` every command inside a `while read` loop.** The loop's stdin *is*
|
|
41
|
+
the list, and any inner command that reads stdin eats the rest of it. Measured on
|
|
42
|
+
the three-line list above: one unredirected inner reader takes the loop to **1
|
|
43
|
+
iteration**, `</dev/null` on it restores 3 — the identical signature to the
|
|
44
|
+
word-split bug, so a correct heredoc fix missing this half looks exactly like no
|
|
45
|
+
fix at all, and reads as one.
|
|
46
|
+
|
|
47
|
+
## `status` is a read-only variable in zsh
|
|
48
|
+
|
|
49
|
+
**`status` is a READ-ONLY variable in zsh**, an alias for `$?`. So the obvious
|
|
50
|
+
bash idiom for reading the payload — `status=$(jq -r '.status' ci.json)` — aborts
|
|
51
|
+
with `read-only variable: status`. Measured this way it fails safe (a hard abort,
|
|
52
|
+
no merge), but the same assignment inside an `if`, or with stderr suppressed,
|
|
53
|
+
reads as a check that silently did not run. Same root cause as the `PIPESTATUS`
|
|
54
|
+
trap, opposite failure direction — so name the variable anything else
|
|
55
|
+
(`ci_status`).
|