@feigi/fleet-ctl 3.69.2 → 3.71.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.
@@ -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`).