@feigi/fleet-ctl 3.82.27 → 3.83.0

package/agents/fleet-recipe-deriver.agent.md

@@ -58,19 +58,27 @@ derive never changes the answer.
   the frozen or locked mode in the command; never rely on the environment to
   imply it.
 - **Test entrypoint** — every test step in the merge-gating CI jobs that can
-  run in a fresh worktree without a running service. Which steps qualify is yours to
-  decide, by reading CI and the repository. Members run it with their own
-  arguments appended (`sh -c '<test> "$@"'`), so it is one invocation: an
-  `&&` chain hands those arguments to its last command alone. Prefer a form
-  where an appended test file or test name lands as an argument to the test
-  runner. The cache reader refuses a command whose first word does not
-  resolve from the repository root (a builtin, a `PATH` entry, or an
-  executable path), one ending in `;`, `&` or a newline, one containing a
-  word that starts with `#`, and one with an unquoted pattern that matches no
-  file tracked from the repository root. Quote a pattern that a program
-  resolves under its own directory option, e.g.
-  `git -C web ls-files -- '*.test.ts'`: the reader accepts a quoted pattern
-  unchecked.
+  run in a fresh worktree without a running service. Which steps qualify is
+  yours to decide, by reading CI and the repository. It is ONE simple command:
+  the reader refuses an unquoted `&&`, `||`, `;`, `|`, a `&` that is not part
+  of a redirection, or a `(`…`)` group. Members run it with their own arguments
+  appended (`sh -c '<test> "$@"'`), and a join or group hands those arguments
+  to its last command alone or breaks the run. An unquoted newline ends a
+  command as `;` does, so it is refused too. `2>&1` and `>&2` stay accepted.
+  A chain is accepted only quoted as the script of `sh -c`, and that form
+  forwards the appended arguments only through `"$@"`:
+  `sh -c 'cd web && npm test -- "$@"' sh`. A suite in a subdirectory uses its
+  runner's directory option, not `cd`: `npm --prefix web test`,
+  `pnpm -C web test`, `make -C web test`, `go -C web test`,
+  `mvn -f web/pom.xml test`, `gradle -p web test`. Prefer a form where an
+  appended test file or test name lands as an argument to the test runner. The
+  cache reader refuses a command whose first word does not resolve from the
+  repository root (a builtin, a `PATH` entry, or an executable path), one
+  ending in `;`, `&` or a newline, one containing a word that starts with `#`,
+  and one with an unquoted pattern that matches no file tracked from the
+  repository root. Quote a pattern that a program resolves under its own
+  directory option, e.g. `git -C web ls-files -- '*.test.ts'`: the reader
+  accepts a quoted pattern unchecked.
 - **Check step** — every merge-gating CI step that is not a test step, that
   the Test entrypoint does not run, and that needs no running service: the format, lint and type checks the
   repository's CI gates on, whatever they are. One invocation, in the same form
@@ -92,6 +100,22 @@ derive never changes the answer.
   PROVEN` with the cause **needs a running service**, never an entrypoint
   that needs one. That is not the case above of no single invocation covering
   every qualifying step.
+- **Covered steps** — every merge-gating CI step the Test entrypoint or the
+  Check step runs, passed as `--covered`: one JSON array of
+  `{"step": "<the CI step>", "by": "test" | "check"}`, one entry per step,
+  `by` naming which of the two runs it. At least one entry is `by: "test"`,
+  and `by: "check"` is refused while the Check step is `true`. A step is in
+  `--covered` or in `--uncovered`, never both: the two lists are compared on
+  the step name exactly, after trimming and collapsing internal whitespace, so
+  write a step the same way in both.
+- **The ledger** — before you propose, classify every test step and every
+  non-test step of every merge-gating CI job: run by the Test entrypoint
+  (`by: "test"`), run by the Check step (`by: "check"`), or uncovered with a
+  reason. Leave none unclassified. A step the Test entrypoint or the Check step
+  runs never goes in `uncovered`; a merge-gating step that needs a running
+  service, or another OS, always does. Which steps qualify is your judgement:
+  no script checks it, so a step left out of both lists (a Docker-gated step
+  omitted from `uncovered`, for example) is the one error nothing here catches.
 
 ## 2. Prove it — this procedure exactly
 
@@ -100,7 +124,7 @@ script creates and removes; `<repo>`'s own tree is never touched.
 
 **First run, to see the output** — no proof flags:
 
-    ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --uncovered '<uncovered>'
+    ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>'
 
 It exits 1 with `NOT PROVEN — no proof given` once every command ran, and
 names the Test entrypoint's output file (`test output: <path>`). Any other
@@ -113,7 +137,7 @@ and revise.
   text off that summary line, as printed, into `--count-line`, and the number
   of tests that ran into `--test-count`:
 
-      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --uncovered '<uncovered>' \
+      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>' \
         --count-line '<literal text of the count line>' --test-count <n>
 
   The number is the tests that ran — never the skipped, the failed, or a
@@ -131,7 +155,7 @@ and revise.
   must change a tracked file; the script runs it in the throwaway worktree,
   requires the suite to go red, and discards the worktree after:
 
-      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --uncovered '<uncovered>' \
+      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>' \
         --mutate '<shell command that breaks one test>' --mutation '<one line: what it breaks>'
 
 **The Check step's own proof** — when `--check` is not `true`, the Check step
@@ -140,15 +164,17 @@ must run green on `origin/main`, and one mutation must turn it red. Give
 `--check true`. Both proofs ride in one run: the Test entrypoint's proof flags
 from above, and these:
 
-    ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --uncovered '<uncovered>' \
+    ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>' \
       --check-mutate '<shell command that breaks one file the Check step reads>' --check-mutation '<one line: what it breaks>' \
       <the Test entrypoint's proof flags>
 
 Exit 0 is the proof holding: the script wrote the Recipe cache and printed
 `PROVEN` and the cache's contents. Exit 1 is `NOT PROVEN`, with the reason;
-no cache was written. Exit 2 means no verdict on the proof: it could not be
-attempted (no `origin/main`, not a repository, a malformed `--uncovered`) or
-the cache could not be written — report it, do not work around it.
+no cache was written. A Test entrypoint, Install step or Check step whose shape
+the reader refuses is `NOT PROVEN` before any command runs. Exit 2 means no
+verdict on the proof: it could not be attempted (no `origin/main`, not a
+repository, a missing or malformed `--covered` or `--uncovered`) or the cache
+could not be written — report it, do not work around it.
 
 The script bounds each command it runs itself — the Install step, the Check
 step, both Test runs and the mutations — and refuses one still running at that

package/package.json

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

package/scripts/claim-ticket.sh

@@ -199,9 +199,11 @@ testcmd=$("$script_dir/derive-testcmd.sh" . test --at origin/main 2>&1) || die "
 echo "    test entrypoint → $testcmd" >&2
 
 # The Test entrypoint is a shell COMMAND, not an argv: the runner hands it to
-# the suite-slot wrapper, which hands it to `sh -c`, so a compound one
-# (`cd sub && make test`) keeps its meaning, with the
-# runner's own arguments appended as "$@". It reaches the runner's source
+# the suite-slot wrapper, which hands it to `sh -c`, so a compound one keeps
+# its meaning, with the runner's own arguments appended as "$@". A compound
+# one reaches here only quoted, as the script of an inner `sh -c`
+# (`sh -c 'cd sub && make test -- "$@"' sh`): derive-testcmd.sh refuses an
+# unquoted join. It reaches the runner's source
 # single-quoted — each embedded `'` closed, escaped and reopened — so nothing
 # in it expands at write time. `LC_ALL=C` so sed reads the command as bytes.
 # Derived here, ahead of every mutation, so a failure refuses before

package/scripts/derive-testcmd.sh

@@ -61,8 +61,20 @@
 # tree that probe reads instead of <repo>'s own index, for a caller that runs
 # the command in a worktree cut from a ref.
 #
+# A Test entrypoint is ONE simple command: a join or a group (an unquoted
+# newline, or an unquoted `;`, `&`, `|`, `(` or `)` outside a redirection) is
+# refused, because the runner appends a run's arguments to its last simple
+# command and a join hands them to the wrong one. A chain stays usable quoted
+# as the script of `sh -c`, for example `sh -c 'cd web && npm test -- "$@"' sh`.
+#
+# `--propose <repo> <install|check|test> <command> [--at <rev>]` runs the same
+# checks on a command that is in no cache: it reads no cache and runs nothing.
+# Its refusals are verdicts on the proposal. On success it prints the command
+# back and exits 0.
+#
 # Exit status: 0 the field is printed, `uncovered` as one line of compact
-# JSON; 1 a refusal about the cache, the repository or the arguments; 3 a
+# JSON, or a proposal that passes is printed back; 1 a refusal about the cache,
+# the repository, the arguments or a proposal; 3 a
 # tool this script needs to read the cache
 # (git, node, mktemp, cat) could not be started, mktemp could not create its
 # temp file, git did not run to an answer, node died mid-read, or node exited
@@ -134,17 +146,28 @@ derive="run the Recipe derivation step (run-team phase 0, before the first claim
 # the checkout still lists the old layout until someone updates it. Without
 # `--at` the probe reads <repo>'s own index, as for a caller that runs the
 # command in <repo> itself. Three arguments is neither shape: a refusal.
-usage="usage: derive-testcmd.sh <repo> <install|check|test|uncovered> [--at <rev>]"
+usage="usage: derive-testcmd.sh <repo> <install|check|test|uncovered> [--at <rev>]
+       derive-testcmd.sh --propose <repo> <install|check|test> <command> [--at <rev>]"
+propose=
+if [ "${1-}" = --propose ]; then
+  [ $# -ge 4 ] || die "$usage"
+  repo=$2
+  field=$3
+  propose=$4
+  [ -n "$propose" ] || die "--propose needs the command to check, got an empty one — $usage"
+  shift 4
+else
+  [ $# -ge 2 ] || die "$usage"
+  repo=$1
+  field=$2
+  shift 2
+fi
 rev=
-case $# in
-  2) ;;
-  4) [ "$3" = --at ] || die "$usage"
-     rev=$4
-     case $rev in ''|-*) die "--at needs a commit, got '$rev' — $usage" ;; esac ;;
-  *) die "$usage" ;;
-esac
-repo=$1
-field=$2
+if [ $# -gt 0 ]; then
+  [ $# -eq 2 ] && [ "$1" = --at ] || die "$usage"
+  rev=$2
+  case $rev in ''|-*) die "--at needs a commit, got '$rev' — $usage" ;; esac
+fi
 
 # git's own fatal — no repository there, or no such directory — exits 128, the
 # one status that is a verdict on the repository. Any other non-zero status is
@@ -157,7 +180,8 @@ gitout=$(git -C "$repo" rev-parse --git-dir 2>&1) || {
 }
 
 case $field in
-  install|check|test|uncovered) ;;
+  install|check|test) ;;
+  uncovered) [ -z "$propose" ] || die "--propose takes an install, check or test command, not '$field' — $usage" ;;
   *) die "unknown Recipe field '$field' — expected install, check, test or uncovered" ;;
 esac
 
@@ -169,6 +193,21 @@ if [ -n "$rev" ]; then
     || die "--at '$rev' does not resolve to a commit in $repo"
 fi
 
+# A proposed command is checked, never read: the checks below run on it as
+# they run on a cache's field, but nothing is read from the cache and nothing
+# is run. Its refusals are verdicts on the proposal, and say so.
+if [ -n "$propose" ]; then
+  subj="the proposed"
+  tail="no command was run — propose a command that passes these checks"
+  stale="a command that cannot run is refused before any command runs"
+  stale5="so it is refused before any command runs"
+  value=$propose
+  errf=$(mktemp) || unrunnable "cannot create a temporary file to check the proposed $field command"
+  trap 'rc=$?; rm -f "$errf" "$errf.idx" 2>/dev/null || :; exit $rc' EXIT
+else
+# The cache read, for the three fields a Recipe holds. The checks below the
+# `fi` that closes it run on the value it leaves in `value`.
+
 # `--path-format=absolute` so the common dir is a real path whatever the
 # caller's cwd. The workspace it names is git-env.mjs's resolveWorkspace() rule,
 # written out below in shell.
@@ -356,6 +395,10 @@ esac
 [ "${#framed}" -eq "$framedlen" ] || die "$carriedmsg"
 value=${framed#"$open"}
 value=${value%"$close"}
+subj="the Recipe cache at $cache is invalid: its"
+tail=$derive
+stale="a Recipe that cannot run is stale, not a finding"
+stale5="so the Recipe is stale, not a finding"
 
 # `uncovered` is data, not a command: nothing runs it and nothing appends to
 # it, so none of the command checks below apply. JSON.stringify above made it
@@ -364,6 +407,7 @@ if [ "$field" = uncovered ]; then
   printf '%s\n' "$value"
   exit 0
 fi
+fi
 
 # claim-ticket.sh appends the runner's own arguments after this string
 # textually (`exec sh -c '<cmd> "$@"' agent-test "$@"`), so a command ending in
@@ -383,7 +427,7 @@ fi
 # neither hazard is about whether the command resolves.
 case $value in
   *';'|*'&'|*'
-') die "the Recipe cache at $cache is invalid: its $field command '$value' ends in ';', '&', or a newline — a runner-appended argument after it would run as an unrelated command instead of reaching the Test entrypoint; $derive" ;;
+') die "$subj $field command '$value' ends in ';', '&', or a newline — a runner-appended argument after it would run as an unrelated command instead of reaching the Test entrypoint; $tail" ;;
 esac
 set -f
 IFS=' 	
@@ -391,7 +435,7 @@ IFS='
 # shellcheck disable=SC2086 # field splitting is the point: scanning every word
 for word in $value; do
   case $word in
-    '#'*) set +f; die "the Recipe cache at $cache is invalid: its $field command '$value' contains a '#' word — a runner-appended argument would be swallowed as a comment rather than reaching the Test entrypoint; $derive" ;;
+    '#'*) set +f; die "$subj $field command '$value' contains a '#' word — a runner-appended argument would be swallowed as a comment rather than reaching the Test entrypoint; $tail" ;;
   esac
 done
 set +f
@@ -418,7 +462,7 @@ while [ $# -gt 0 ]; do
     *) break ;;
   esac
 done
-[ $# -gt 0 ] || die "the Recipe cache at $cache is invalid: its $field command names no command, only assignments — $derive"
+[ $# -gt 0 ] || die "$subj $field command names no command, only assignments — $tail"
 case $1 in
   *[\'\"\\\$\`\(\)\{\}\<\>\|\&\;\*\?\[\~]*) ;;
   *)
@@ -431,7 +475,7 @@ case $1 in
     # or a PATH match) has no path to test and is left to `command -v`.
     (cd "$repo" && command -v -- "$1" || exit 1
       case $1 in */*) [ -x "$1" ] || exit 1 ;; esac) >/dev/null 2>&1 \
-      || die "the Recipe cache at $cache is invalid: its $field command '$1' is not found or not executable from $repo — a Recipe that cannot run is stale, not a finding; $derive"
+      || die "$subj $field command '$1' is not found or not executable from $repo — $stale; $tail"
     ;;
 esac
 
@@ -457,8 +501,8 @@ esac
 # that cannot run. An option, an `=`
 # assignment or value, a path outside <repo>, or the target of a `<` or `>`
 # redirection is the program's own to read, or selects no test, and is
-# accepted unprobed too. The scan stops judging at a `cd` or `pushd` piece,
-# past which a pattern no longer resolves from <repo>.
+# accepted unprobed too. A join or a group, an unquoted newline included, is
+# refused as soon as the scan reaches it, so no piece after one is judged.
 # A program's own directory option,
 # such as `git -C`, does not stop it: whether that option moves where the
 # program resolves a pattern is the program's to say, so a Recipe must quote a
@@ -482,7 +526,9 @@ esac
 # private index file, and the symlink and submodule test reads that tree
 # too; the ignore rules are still <repo>'s working copy's, the one place git
 # reads them from. The resolvability probe of the command's leading word
-# above stays <repo>'s own.
+# above stays <repo>'s own. A git call of the probe that fails is git not
+# running to an answer, exit 3: no verdict on the cache or on a proposal, so
+# recipe-prove.mjs never reads it as NOT PROVEN.
 if [ "$field" = test ]; then
   # An ambient index would answer `ls-files` for whatever repository or commit
   # the caller is in the middle of, not for <repo>'s tracked files.
@@ -493,7 +539,7 @@ if [ "$field" = test ]; then
     export GIT_INDEX_FILE="$errf.idx"
     git -C "$repo" read-tree "$revc" 2>"$errf" || {
       listed=$?
-      die "cannot read the tree of $rev in $repo (git read-tree exit $listed): $(cat "$errf" 2>/dev/null)"
+      unrunnable "cannot read the tree of $rev in $repo (git read-tree exit $listed): $(cat "$errf" 2>/dev/null)"
     }
   fi
   # Whether <path> is a directory git lists as ONE entry and never beneath: a
@@ -518,14 +564,12 @@ if [ "$field" = test ]; then
   # written) or `Q` (quoted or expansion-bearing: opaque), $2 the piece. Dies
   # on a stale pattern; otherwise returns 0 having accepted the piece.
   judge() {
-    [ -z "$stop" ] || return 0
     piece=$2
     was=$before
     before=$piece
     if [ -n "$redir" ]; then redir=; return 0; fi
     [ "$1" = P ] || return 0
     case $piece in
-      cd|pushd) stop=1; return 0 ;;
       -*|*=*|/*|*..*) return 0 ;;
       *'*'*|*'?'*|*'['*']'*) ;;
       *) return 0 ;;
@@ -539,7 +583,7 @@ if [ "$field" = test ]; then
     # the prefix of the files beneath it.
     tracked=$(git -C "$repo" ls-files -- ":(glob)$piece" ":(glob)${piece%/}/**" 2>"$errf") || {
       listed=$?
-      die "cannot list the files tracked in $where to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)"
+      unrunnable "cannot list the files tracked in $where to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)"
     }
     [ -z "$tracked" ] || return 0
     lead=${piece%%[*?[]*}
@@ -550,15 +594,15 @@ if [ "$field" = test ]; then
       case $opq in
         0) return 0 ;;
         1) ;;
-        *) die "cannot ask git whether '$lead' is a symlink or a submodule in $where, to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)" ;;
+        *) unrunnable "cannot ask git whether '$lead' is a symlink or a submodule in $where, to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)" ;;
       esac
     done
     ignored=0
     git -C "$repo" check-ignore -q --no-index -- "$piece" 2>"$errf" || ignored=$?
     case $ignored in
       0) ;;
-      1) die "the Recipe cache at $cache is invalid: its test command's pattern '$piece' matches no file tracked in $where — a Test entrypoint that selects no tests passes having run nothing, so the Recipe is stale, not a finding; a pattern that a program resolves under its own directory option, such as git -C, must be quoted; $derive" ;;
-      *) die "cannot ask git whether $repo ignores its test command's pattern '$piece' (git check-ignore exit $ignored): $(cat "$errf" 2>/dev/null)" ;;
+      1) die "$subj test command's pattern '$piece' matches no file tracked in $where — a Test entrypoint that selects no tests passes having run nothing, $stale5; a pattern that a program resolves under its own directory option, such as git -C, must be quoted; $tail" ;;
+      *) unrunnable "cannot ask git whether $repo ignores its test command's pattern '$piece' (git check-ignore exit $ignored): $(cat "$errf" 2>/dev/null)" ;;
     esac
   }
   # End the piece being read, if there is one, and judge it.
@@ -567,11 +611,14 @@ if [ "$field" = test ]; then
     scan_piece=
     scan_kind=P
   }
+  # Refuse the Test entrypoint for the unquoted join or group $1 names.
+  joined() {
+    die "$subj $field command '$value' has an unquoted $1, which joins or groups commands — a runner-appended argument would land after the last one, not reach the Test entrypoint; write one invocation with no unquoted operator or newline (a directory option such as npm --prefix web test, pnpm -C web, make -C web, go -C web, mvn -f web, gradle -p web, or a tracked script; or sh -c 'cd web && npm test -- \"\$@\"' sh so the appended arguments reach the inner command), and list any other step in uncovered; $tail"
+  }
   nl='
 '
   before=
   redir=
-  stop=
   scan_rest=$value
   scan_piece=
   scan_kind=P
@@ -650,9 +697,22 @@ if [ "$field" = test ]; then
         scan_piece=$scan_piece$scan_c
         scan_dollar ;;
       '{'|'}'|'~') scan_kind=Q; scan_piece=$scan_piece$scan_c ;;
-      ' '|'	'|"$nl") flush ;;
+      ' '|'	') flush ;;
+      # A join or a group is refused on the Test entrypoint: a runner appends
+      # its arguments after the whole string, so they reach only the last
+      # command. An unquoted newline ends a command as `;` does. A
+      # redirection's own `&`, and the `<` or `>` itself, are not.
+      "$nl")
+        flush
+        joined newline ;;
       ';'|'&'|'|'|'('|')'|'<'|'>')
         flush
+        if [ -z "$redir" ]; then
+          case $scan_c in
+            '<'|'>') ;;
+            *) joined "'$scan_c'" ;;
+          esac
+        fi
         before=
         case $scan_c in '<'|'>') redir=1 ;; esac ;;
       *) scan_piece=$scan_piece$scan_c ;;
@@ -660,7 +720,7 @@ if [ "$field" = test ]; then
   done
   flush
   if [ -n "$scan_sq" ] || [ -n "$scan_ctx" ]; then
-    die "the Recipe cache at $cache is invalid: its test command leaves a quote, a backtick, a \$( or a \${ open, so sh cannot run it — a Recipe that cannot run is stale, not a finding; $derive"
+    die "$subj test command leaves a quote, a backtick, a \$( or a \${ open, so sh cannot run it — $stale; $tail"
   fi
 fi
 

package/scripts/recipe-prove.mjs

@@ -5,7 +5,7 @@
 // reads: the deriving agent chooses all three commands by reading the repository,
 // and this script is what turns that choice into a cache, or refuses to.
 //
-//   recipe-prove.mjs <repo> --install <cmd> --check <cmd|true> --test <cmd> --uncovered <json>
+//   recipe-prove.mjs <repo> --install <cmd> --check <cmd|true> --test <cmd> --covered <json> --uncovered <json>
 //                    [--count-line <literal> --test-count <n>]
 //                    [--mutate <cmd> --mutation <description>]
 //                    [--check-mutate <cmd> --check-mutation <description>]
@@ -17,6 +17,14 @@
 // required, so a cache never stays silent about a CI step left unrun; it is
 // written as given, as the cache's `uncovered`.
 //
+// `--covered` is one JSON array of `{ "step": <string>, "by": "test" | "check" }`,
+// one per merge-gating CI step that the Test entrypoint or the Check step runs:
+// "test" for a step the Test entrypoint runs, "check" for one the Check step
+// runs. At least one entry is "test"; "check" is never used with `--check true`;
+// and no step is in both `--covered` and `--uncovered`. Its shape is checked
+// before any command runs, and it is never written to the cache: nothing here
+// can check which steps a command runs.
+//
 // Every check runs in a throwaway worktree of `origin/main`, detached and
 // removed afterwards, so neither the caller's checkout nor its uncommitted
 // state takes part — `derivedAt` is the commit the proof ran against:
@@ -102,7 +110,7 @@ import { isDigits } from "./arg.mjs";
 
 const NAME = "recipe-prove";
 const USAGE =
-  "usage: recipe-prove.mjs <repo> --install <cmd> --check <cmd|true> --test <cmd> --uncovered <json> [--count-line <literal> --test-count <n>] [--mutate <cmd> --mutation <description>] [--check-mutate <cmd> --check-mutation <description>]";
+  "usage: recipe-prove.mjs <repo> --install <cmd> --check <cmd|true> --test <cmd> --covered <json> --uncovered <json> [--count-line <literal> --test-count <n>] [--mutate <cmd> --mutation <description>] [--check-mutate <cmd> --check-mutation <description>]";
 const READER = join(dirname(fileURLToPath(import.meta.url)), "derive-testcmd.sh");
 
 // Scrubbed once, for every child: an ambient GIT_DIR or GIT_WORK_TREE — set
@@ -155,7 +163,7 @@ const READER_COULD_NOT_RUN = 3;
 function parseArgs(argv) {
   const [repo, ...rest] = argv;
   if (!repo || repo.startsWith("--")) throw cannot(USAGE);
-  const flags = new Set(["--install", "--check", "--test", "--uncovered", "--count-line", "--test-count", "--mutate", "--mutation", "--check-mutate", "--check-mutation"]);
+  const flags = new Set(["--install", "--check", "--test", "--covered", "--uncovered", "--count-line", "--test-count", "--mutate", "--mutation", "--check-mutate", "--check-mutation"]);
   const a = {};
   for (let i = 0; i < rest.length; i += 2) {
     const [flag, value] = [rest[i], rest[i + 1]];
@@ -169,6 +177,7 @@ function parseArgs(argv) {
     if (!a[f] || !a[f].trim()) throw cannot(`${f} needs a non-empty command — ${USAGE}`);
   }
   if (!("--uncovered" in a)) throw cannot(`--uncovered is required: the merge-gating CI steps neither the Test entrypoint nor the Check step runs, as one JSON array, \`[]\` for none — ${USAGE}`);
+  if (!("--covered" in a)) throw cannot(`--covered is required: the merge-gating CI steps the Test entrypoint or the Check step runs, one JSON array of { step, by } with by "test" or "check" — ${USAGE}`);
   const uncovered = parseUncovered(a["--uncovered"]);
   if (("--count-line" in a) !== ("--test-count" in a)) throw cannot("--count-line and --test-count go together");
   if ("--test-count" in a && !isDigits(a["--test-count"])) {
@@ -189,6 +198,7 @@ function parseArgs(argv) {
     if (!("--check-mutate" in a) || !a["--check-mutate"].trim()) throw cannot(`a Check step other than \`true\` needs --check-mutate, the command that turns it red — ${USAGE}`);
     if (!a["--check-mutation"].trim()) throw cannot("--check-mutation needs a non-empty description");
   }
+  checkCovered(a["--covered"], uncovered, a["--check"]);
   return {
     repo,
     install: a["--install"],
@@ -204,18 +214,20 @@ function parseArgs(argv) {
   };
 }
 
+function parseFlagJson(flag, json) {
+  try {
+    return JSON.parse(json);
+  } catch (e) {
+    throw cannot(`${flag} is not JSON: ${e.message}`);
+  }
+}
+
 // The same rule derive-testcmd.sh holds the cache to, applied before any
 // command runs, so a malformed list is a usage error rather than a proof that
 // held and a cache the reader then refuses.
 function parseUncovered(json) {
-  let list;
-  try {
-    list = JSON.parse(json);
-  } catch (e) {
-    throw cannot(`--uncovered is not JSON: ${e.message}`);
-  }
+  const list = parseFlagJson("--uncovered", json);
   if (!Array.isArray(list)) throw cannot("--uncovered is not a JSON array of { step, reason } entries, `[]` for none");
-  const filled = (s) => typeof s === "string" && s.trim() !== "";
   list.forEach((u, i) => {
     if (u === null || typeof u !== "object" || Array.isArray(u) || !filled(u.step) || !filled(u.reason)) {
       throw cannot(`--uncovered entry ${i + 1} is not an object with a non-empty \`step\` and \`reason\``);
@@ -224,6 +236,43 @@ function parseUncovered(json) {
   return list;
 }
 
+const filled = (s) => typeof s === "string" && s.trim() !== "";
+const normStep = (s) => s.trim().replace(/\s+/g, " ");
+
+// The ledger of CI steps the Test entrypoint or the Check step runs: a JSON
+// array of { step, by }, `by` exactly "test" or "check". Checked here, before
+// any command runs, and never written to the cache: nothing can check which
+// steps a command runs, only that the ledger is well-formed and agrees with
+// `uncovered` about what it leaves out.
+function checkCovered(json, uncovered, check) {
+  const list = parseFlagJson("--covered", json);
+  if (!Array.isArray(list)) throw cannot(`--covered is not a JSON array of { step, by } entries — ${USAGE}`);
+  list.forEach((c, i) => {
+    if (c === null || typeof c !== "object" || Array.isArray(c) || !filled(c.step) || (c.by !== "test" && c.by !== "check")) {
+      throw cannot(`--covered entry ${i + 1} is not an object with a non-empty \`step\` and a \`by\` of exactly "test" or "check"`);
+    }
+  });
+  if (!list.some((c) => c.by === "test")) throw cannot(`--covered names no step with by "test": the Test entrypoint runs at least one merge-gating CI step, or there is nothing to prove`);
+  if (check === "true" && list.some((c) => c.by === "check")) throw cannot(`--covered names a step with by "check", but --check is true, so no Check step runs`);
+  const listed = new Set(uncovered.map((u) => normStep(u.step)));
+  const both = list.find((c) => listed.has(normStep(c.step)));
+  if (both) throw cannot(`the step '${both.step}' is in both --covered and --uncovered: a step that runs is never listed as uncovered`);
+}
+
+// The reader's shape check, before any command runs: `--propose` holds a
+// proposed command to the rules the cache is held to, with no cache read and no
+// command run, so one the cache would refuse is refused before the proof.
+function preflight(field, command, repo, at) {
+  const args = [READER, "--propose", repo, field, command, ...(field === "test" ? ["--at", at] : [])];
+  const r = spawnSync("sh", args, { env: ENV, encoding: "utf8" });
+  if (r.error && !r.pid) throw cannot(`could not start sh to check the ${field} command: ${r.error.message}`);
+  if (r.signal) throw cannot(`the reader's sh was killed by ${r.signal}${errorCause(r.error)}, so the ${field} command was not checked`);
+  if (r.status === 0) return;
+  if (r.status === READER_COULD_NOT_RUN) throw cannot(`${r.stderr.trim()} — the reader could not run a tool it needs, so the ${field} command was not checked`);
+  if (r.status === 1) throw notProven(r.stderr.trim() || `the reader refused the ${field} command and said nothing`);
+  throw cannot(`the reader exited ${r.status} checking the ${field} command: ${r.stderr.trim()}`);
+}
+
 // A git that cannot be started is no verdict, as for `sh` below: read as a
 // failed git command, it would surface as whatever that command's failure
 // means to its caller — a missing repository, an unfetched origin/main, a
@@ -534,6 +583,9 @@ function main(argv) {
   if (!workspace) throw cannot(`cannot resolve the common git dir of ${o.repo}: ${common.err}`);
   const sha = git(["rev-parse", "--verify", "origin/main^{commit}"], o.repo);
   if (!sha.ok) throw cannot(`origin/main does not resolve to a commit (${sha.err}) — fetch it; the proof runs against it`);
+  // Each command's shape is checked before any command runs, and before the
+  // proof's worktree exists: a command the cache reader would refuse is refused here.
+  for (const field of ["install", "check", "test"]) preflight(field, o[field], o.repo, sha.out);
 
   const logs = mkdtempSync(join(tmpdir(), `${NAME}-`));
   const cache = join(workspace, ".fleet", "recipe.json");