@feigi/fleet-ctl 3.77.0 → 3.78.0

package/agents/fleet-review-tests.agent.md

@@ -20,14 +20,25 @@ model: "@task:medium"
      permanently. -->
 
 You are a test-coverage analyst focused on whether tests actually
-DISCRIMINATE, not on line coverage percentages.
+DISCRIMINATE, not on line coverage percentages. The diff puts you in one of
+two modes.
 
-For each test the diff touches or adds, apply the mutation it is meant to
-catch and confirm a kill, revert, then apply a mutation it should NOT catch
-and confirm the named test stays green. Vary the syntactic form of the
-mutation — a guard written to catch `// whole-line` comments may let `code; //
-trailing` through, and a test that only exercises one form is not proven to
-discriminate the class. `<testCmd>` is the `command` your dispatch prompt's
+**The diff touches or adds a test file.** For each test the diff touches or
+adds, apply the mutation it is meant to catch and confirm a kill, revert, then
+apply a mutation it should NOT catch and confirm the named test stays green.
+Vary the syntactic form of the mutation — a guard written to catch `//
+whole-line` comments may let `code; // trailing` through, and a test that only
+exercises one form is not proven to discriminate the class.
+
+**The diff changes source and touches no test file.** There is nothing in the
+diff to discriminate, so hunt coverage gaps instead: for each piece of
+behaviour the diff adds or changes in source, apply a mutation to that
+changed source, run `<testCmd>`, and report changed behaviour that no
+existing test kills. A mutant that survives, with a valid green on the
+unmutated tree, is a finding; name the changed behaviour, the mutation and
+the run that shows it surviving.
+
+In both modes `<testCmd>` is the `command` your dispatch prompt's
 Tests paragraph names, run only in your own copy of the snapshot. Make that
 copy from the snapshot's tracked files only —
 `git -C <snapshot> archive HEAD | tar -x -C <copy>`, or a `git clone` of the

package/commands/review-and-fix.md

@@ -92,7 +92,7 @@ Tell readers **`git show <sha>:<path>` is the source of truth** — the object s
 
 **Brace a ref held in a variable — `git show "${SHA}:<path>"` — because quoting is not what fixes it.** zsh reads a `:x` suffix after an unbraced parameter as a history modifier, inside double quotes as well as outside, so git is handed a ref nobody typed; braces end the parameter name before the colon. Measured, fully quoted: the construct that fails loudly on one path exits 0 on another and prints the *commit* instead of the blob — and the silent shape is the hazard, because a survival `grep -c` scores it as a plausible hit and re-anchors a citation that was correct. A literal ref is unaffected either way; quote regardless — not for zsh's sake, which splits and globs an expansion's *result* only under `SH_WORD_SPLIT`/`GLOB_SUBST`, both off by default (measured: `V="a b"` unquoted still arrives as one argument), but so the same line survives a `bash` runner, where an unquoted path holding a space does split — measured, `fatal: path 'has' does not exist`.
 
-**The fan-out scales to the diff — the review computes it, you don't.** Its snapshot agent runs `diff-stats.mjs`, and `selectDimensions` keeps the applicable subset of the six-specialist catalog (fleet-review-correctness, fleet-review-silent-failure, fleet-review-tests, fleet-review-comments, fleet-review-types, fleet-review-simplify): fleet-review-correctness always; drop fleet-review-tests with no test changes, and fleet-review-types / fleet-review-silent-failure / fleet-review-simplify with no source; a docs-only PR keeps only fleet-review-correctness + fleet-review-comments. **Then the size tier applies a floor on top:** a `single-file` or `small` profile keeps fleet-review-correctness + fleet-review-silent-failure + fleet-review-comments, plus fleet-review-tests when the diff touches a test file — so a small source PR runs three, not five. **fleet-review-comments is unconditional on the floor**: it used to need a docs *file* in the diff, but `classify()` scores `.js`/`.mjs` `src` via the code-extension check and `.sh` `src` by falling through everything else, so a PR whose whole substance was prose in a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and lost the one specialist whose job it was — measured five times in production, all correction-class PRs, with `dimensionsUnrun` empty each time because the trim was by design. **The floor outranks the no-source drop for fleet-review-silent-failure**: a one-file `.yml` or `.github/` shell change runs fleet-review-correctness + fleet-review-silent-failure, which is the pair a swallowed error in CI needs. Above the size tier the no-source drop still stands, and `tests-only` outranks the size tier for a diff with no config file — a no-src, no-config diff that also touches a test file gets no fleet-review-silent-failure; a tests-only diff that also carries a config file keeps it. `single-file` is one file at *any* size. Profile unknown → the full six, the safe direction. Pin a subset explicitly with `args.dimensions` (keys or dimension objects). Dispatching by hand instead of automatically: apply the same heuristic yourself — two or three for annotation-only or single-file, the full six for production code.
+**The fan-out scales to the diff — the review computes it, you don't.** Its snapshot agent runs `diff-stats.mjs`, and `selectDimensions` keeps the applicable subset of the six-specialist catalog (fleet-review-correctness, fleet-review-silent-failure, fleet-review-tests, fleet-review-comments, fleet-review-types, fleet-review-simplify): fleet-review-correctness always; fleet-review-tests whenever the diff touches a test file, and also for a `production`-profile diff that changes source and touches no test file — there its job is the coverage gap, mutating the changed source and reporting behaviour no existing test kills, so untested source changes get asked that question during review — and dropped otherwise, so a diff with no source and no test file loses it; fleet-review-types / fleet-review-silent-failure / fleet-review-simplify with no source; a docs-only PR keeps only fleet-review-correctness + fleet-review-comments. **Then the size tier applies a floor on top:** a `single-file` or `small` profile keeps fleet-review-correctness + fleet-review-silent-failure + fleet-review-comments, plus fleet-review-tests when the diff touches a test file — so a small source PR runs three, not five, and the coverage-gap case above never reaches the size tier. **fleet-review-comments is unconditional on the floor**: it used to need a docs *file* in the diff, but `classify()` scores `.js`/`.mjs` `src` via the code-extension check and `.sh` `src` by falling through everything else, so a PR whose whole substance was prose in a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and lost the one specialist whose job it was — measured five times in production, all correction-class PRs, with `dimensionsUnrun` empty each time because the trim was by design. **The floor outranks the no-source drop for fleet-review-silent-failure**: a one-file `.yml` or `.github/` shell change runs fleet-review-correctness + fleet-review-silent-failure, which is the pair a swallowed error in CI needs. Above the size tier the no-source drop still stands, and `tests-only` outranks the size tier for a diff with no config file — a no-src, no-config diff that also touches a test file gets no fleet-review-silent-failure; a tests-only diff that also carries a config file keeps it. `single-file` is one file at *any* size. Profile unknown → the full six, the safe direction. Pin a subset explicitly with `args.dimensions` (keys or dimension objects). Dispatching by hand instead of automatically: apply the same heuristic yourself — two or three for annotation-only or single-file, the full six for production code.
 
 **If the ticket is a *correction* — stale docs, wrong comments, bad citations — hunt the defect inside the correction itself.** Four such tickets in one fleet run each shipped a new wrong claim in the fix: a misattributed package, a three-item list at inverted polarity (two items were the *negations* of the claims being marked stale, so the banner asserted currently-true facts were false), a commit body citing a line that held something else, and a banner whose own supporting sentence confirmed the bullet it marked as wrong. Nobody hunts this unprompted because the diff "obviously" improves accuracy. Read every corrected sentence literally and ask whether each clause is true under that reading.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.77.0",
+  "version": "3.78.0",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/metrics-refresh.mjs

@@ -16,6 +16,11 @@
 // rows the next drain finds already there, so a second run changes nothing.
 // A pending file that is empty, or blank lines only, is removed with its own
 // line: an append created it and never wrote.
+// The drain takes no lock by design: it assumes only the run's controller
+// appends to the pending file and drains it, serially, so nothing appends
+// between the read and either unlink. One controller per checkout is the
+// rule, but phase 0 refuses a second one at its ledger rotation, which runs
+// after its drain step, so a second controller's drain is not guarded.
 //
 // COST GUARD. `pr-cost.mjs --guard` rewrites `.fleet/cost-guard.json`, which
 // the router reads and fails closed without. It needs all three metrics TSVs;

package/scripts/review-core.mjs

@@ -209,7 +209,7 @@ export const DEFAULT_DIMENSIONS = [
   {
     key: "tests",
     agentType: "fleet-review-tests",
-    prompt: `whether each test DISCRIMINATES: apply the mutation it should catch and confirm a kill, revert, then apply one it should NOT catch and confirm the named test stays green. Vary the syntactic form — a guard catching \`// whole-line\` may let \`code; // trailing\` through. \`<testCmd>\` is the \`command\` your Tests paragraph names, run only in your own copy of the snapshot. A kill is scored by these rules and nothing else:
+    prompt: `whether tests DISCRIMINATE, in whichever of two modes the diff puts you in. **The diff touches or adds a test file:** for each such test, apply the mutation it should catch and confirm a kill, revert, then apply one it should NOT catch and confirm the named test stays green. Vary the syntactic form — a guard catching \`// whole-line\` may let \`code; // trailing\` through. **The diff changes source and touches no test file:** hunt coverage gaps instead. For each piece of behaviour the diff adds or changes in source, apply a mutation to that changed source, run \`<testCmd>\`, and report changed behaviour that no existing test kills: a mutant that survives, with a valid green on the unmutated tree, is a finding. \`<testCmd>\` is the \`command\` your Tests paragraph names, run only in your own copy of the snapshot. A kill is scored by these rules and nothing else:
 
 ${KILL_RULES}
 
@@ -376,7 +376,13 @@ export function selectDimensions(all, stats) {
     return docsOnlyDims;
   }
   let dims = all;
-  if (stats.hasTests === false) dims = dims.filter((d) => d.key !== "tests");
+  // `tests` has two jobs (see its prompt): discriminate the tests a diff touches,
+  // or — when the diff has source but no test — find changed behaviour no
+  // existing test kills. Only the second survives `hasTests === false`, and only
+  // above the size tier: a production-profile diff with source keeps it. The
+  // `!== false` on `hasSrc` keeps a blob that lost the field from narrowing.
+  const keepsCoverageGap = stats.profile === "production" && stats.hasSrc !== false;
+  if (stats.hasTests === false && !keepsCoverageGap) dims = dims.filter((d) => d.key !== "tests");
   if (stats.hasSrc === false) {
     const keepsSilentFailure =
       SIZE_TIER_PROFILES.has(stats.profile) ||

package/scripts/ticket-router.mjs

@@ -601,6 +601,10 @@ function main() {
       issue: readJson(issuePath), sizing: readJson(F.arg("sizing")), guard: readGuard(readJson(guardPath)), table,
     });
     const pending = F.arg("pending") ?? join(dirname(guardPath), "ticket-features.pending.tsv");
+    // The header decision and the append are not atomic and take no lock. That is
+    // safe only while the run's controller is the only process that routes or
+    // drains on a checkout, doing both serially: one controller per checkout is
+    // the rule, and neither this append nor the drain checks it.
     try {
       mkdirSync(dirname(pending), { recursive: true });
       const header = statSync(pending, { throwIfNoEntry: false })?.size > 0 ? "" : `${COLUMNS.join("\t")}\n`;