@mu-crew/mu 3.13.1 → 3.13.3

package/dist/extension/mu-pi.js

@@ -1362,7 +1362,7 @@ function registerRefuteNudge(pi, run = defaultRunner(), nested = notNested, hold
 }
 
 // extension/mu-pi.ts
-var EXT_VERSION = true ? "3.13.1" : void 0;
+var EXT_VERSION = true ? "3.13.3" : void 0;
 var FRESH_COMMAND = "mu-fresh";
 var FRESH_TIMEOUT_MS = 3e4;
 function commandName(name) {

package/docs/VOCABULARY.md

@@ -83,6 +83,19 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | **anonymous claim** | A `--self` claim by an actor that is not a worker. `owner` stays NULL; `ops.actor` records who. | "unowned claim" |
 | **release** | Clear `tasks.owner`. | "unclaim", "unassign" |
 
+### Recipe gates
+
+| Term | Meaning | Don't use |
+| --- | --- | --- |
+| **fast gate** | Repo-defined iteration checks: format, lint, unit tests and cheap integration tests. Cost is measured, not guaranteed seconds. | "gate command" (alone) |
+| **slow gate** | The remaining merge checks: real-environment e2e, release and packaging checks. | "gate command" (alone) |
+| **gate budget** | The slow gate's target wall time; crossing it prioritises test upkeep. | "timeout" |
+| **gate record** | A note identifying commit/tree, exact command/scope, result, duration, environment/toolchain and skips; reuse needs equivalent conditions. | "tests pass" (alone) |
+| **test upkeep** | Ordinary DAG work to profile, speed up, move down, merge or remove tests while preserving coverage; see [test-health](../skills/mu/recipes/test-health.md). | "coverage reduction" |
+| **test level** | Unit < integration < e2e; use the lowest level that catches the guarded failure. | |
+| **review gate** | A review task blocked by a work task, deciding whether its commits count. | "gate command" |
+| **merge batch** | Accepted commits combined into one pinned tree for full merge verification, without a crew-wide barrier. | "wave" (when only verification is batched) |
+
 ### Workspaces and housekeeping
 
 | Term | Meaning | Don't use |

package/docs/specs/2026-10-21-fast-and-slow-gates.md

@@ -0,0 +1,229 @@
+# Fast and slow gates, and test upkeep as routine work
+
+Status: implemented in mu `10d758c`. Swaywardlock pilot commits `90c3f1c`
+and `36273ff` are merged locally: gate instrumentation and one targeted wait
+improvement. Full-suite upkeep and the slow-gate budget remain open.
+
+**Measurement correction (implementation check):** the initial figures below
+came from exploratory regex scripts, not an execution classifier. The
+museum tool's drill-down showed that many counted "full gate runs" were
+commands writing commit messages or task notes that merely mentioned the
+gate. The claimed six full runs per task and daily run totals are not
+verified and must not be used as a baseline. Command duration also includes
+other work in a compound command, and background work appears in later
+polls. Preserve the initial investigation below for provenance, but establish
+a fresh, inspected baseline with `museum-search calls --tool bash` and step
+timing before judging the pilot. Unit-test runtime and source-size figures
+were read directly from logs and git history.
+Date: 2026-10-21
+
+## Problem
+
+Crews slow down as a project grows, and the gate is where the time goes.
+swaywardlock (repo `swayward-wm/swaywardlock`, started 2026-10-19) is the
+clearest case. From 225 museum sessions over its first three days:
+
+| | Oct 19 | Oct 20 | Oct 21 |
+|---|---|---|---|
+| `contrib/e2e-sway` lines | 273 → 980 | → 2,437 | → 3,587 |
+| unit tests (`#[test]`) | 0 → 69 | → 165 | → 224 |
+| test + harness share of the day's diff | 12% | 43% | 36% |
+| median full `contrib/gate` run | 1–3 min | 2.3 → 5.9 min | 5.5 → 7.9 min |
+| full gate runs | 88 | 152 | 92 (by 15:00) |
+| hours spent in gate commands | 3.3 | 8.4 | 7.0 |
+
+- A task got about 6 full gate runs (13 at most): about 4–5 by the
+  worker and 2–3 by its reviewer, then a merge-time run by the
+  orchestrator.
+- A worker's median tool calls per session went from 45 to 95, and the
+  gate's share of its wall time from 10–20% to 22–49%.
+- Up to 4 gates ran at once on the same machine, which slows each one
+  down.
+
+**Tests are not the cost.** A representative gate log
+(`scratch/review-e2e_scaffold_2/gate.log`) shows:
+- the 214 unit tests take **0.96 s**
+- a cold compile of 583 crates for dev, test and release takes about
+  3 min, because every review worktree starts with an empty `target/`
+- the rest is `contrib/e2e-sway`: 64 cases, 406 checks, and 178 fixed
+  `sleep`s in the script
+
+What kills progress is the slow, unprofiled part of the gate, run
+redundantly and with nobody whose job is to look at it.
+
+Our own rules caused part of this:
+- `recipes/adversarial-review.md` lists "an edge case without a test" as
+  a finding.
+- The swaywardlock briefs told each worker to "re-run the gate" after
+  every rebase, and each reviewer to re-run the full `contrib/gate`,
+  then build the parent in a second worktree to prove every new test
+  fails there.
+- Nothing in any recipe ever removes, merges, moves or speeds up a test.
+
+## Goal
+
+Testing stays encouraged. What changes is where tests live, how often
+the expensive ones run, and that looking after the test suite becomes
+normal project work instead of something that never happens.
+
+## Concepts
+
+- **Fast gate.** The checks anyone runs at any time, in seconds: format,
+  lint, unit tests, and cheap integration tests. A worker runs it every
+  time it iterates.
+- **Slow gate.** Everything else the merge needs: e2e against a real
+  environment (headless compositor, real PAM), release builds, packaging
+  checks. Run once per tree, by whoever has to.
+- **Gate budget.** The slow gate's target wall time, written next to the
+  gate commands. The default is 5 min, and the project can change it.
+- **Gate record.** A task note names commit/tree, exact command and scope,
+  duration, toolchain/environment and skips. Reuse requires matching tree,
+  scope and equivalent execution conditions. A targeted run or privileged
+  check that skipped is not a full slow-gate pass.
+- **Test upkeep.** Profile the gate, then speed up, move down a level,
+  merge or delete tests, so the gate stays inside its budget. It is
+  ordinary work in the DAG, not a cleanup that happens when someone
+  remembers.
+- **Test level.** Unit < integration < e2e. A test belongs at the lowest
+  level that can catch the failure it guards against.
+
+## Decisions
+
+1. **The gates are defined in the repo.** The project defines its gates
+   in AGENTS.md (or the README), in a `## Gates` section: the fast
+   command, the slow command, the budget, and how to run one slow test,
+   e.g. `TESTS=preview contrib/e2e-sway`. Workstream plan notes point to
+   it. Recipes say "the fast gate" and "the slow gate" instead of "the
+   gate command".
+   *Why:* gates outlive workstreams. A plan note copy goes out of date.
+2. **Who runs which gate:**
+   - **Worker:** the fast gate while iterating. Before closing, the
+     slow tests for its own area once, then the fast gate on the final
+     commit, and records both.
+   - **Reviewer:** reuses the worker's gate record when tree, scope and
+     execution conditions match. It runs only the tests that cover the diff, and reproduces
+     a finding when one is claimed. It no longer runs the full gate or
+     builds the parent to show a test fails there.
+   - **Orchestrator:** the full slow gate once per merge batch, on the
+     merged tree. When it fails, it bisects the batch.
+
+   *Why:* avoid repeating equivalent full runs across roles. The merged-tree
+   run checks interactions not covered by individual worker runs. Measure
+   batch failure rate during the pilot; the exploratory counts do not
+   establish how often bisecting will be necessary.
+3. **Red-green only for bug fixes.** A fix shows the test failing on the
+   base and passing on the fix, and the worker shows it, not the
+   reviewer. Feature work does not have to show a test failing first.
+4. **Rules for adding a test:**
+   - it goes at the lowest level that can catch the failure
+   - it covers behaviour no existing test covers
+   - a new slow-gate case states what only it can see, in a comment or
+     the commit message
+   - poll readiness/completion; retain documented temporal sampling,
+     negative-observation windows and deliberately sleeping process fixtures
+5. **Reviewer findings about tests** change from "an edge case without a
+   test" to:
+   - a risky behaviour that is untested, or broken
+   - a test at the wrong level
+   - a test that duplicates test X
+   - an unnecessary readiness sleep, not a documented temporal assertion
+   - a gate that got noticeably slower in this diff
+6. **Build cache across workspaces.** Prefer private targets with shared
+   dependency downloads and, when available, a compiler cache such as
+   sccache. Keep normal-auth, test-auth and release artifacts distinct and
+   pass explicit paths to consumers. Cargo's lock does not protect a binary
+   after a build exits: a shared writable target may replace it under tests.
+   Optional warm-up uses a quiescent snapshot into private storage, never
+   hardlinks or a live copy. This is recipe guidance, not a mu feature.
+   *Why:* inspected logs show substantial build time, but reuse and
+   contention must be measured rather than assuming a cache removes it.
+7. **When test upkeep happens.** A test upkeep task is queued:
+   - when a merged slow gate goes over its budget (it comes before any
+     new feature work)
+   - at the end of every phase or milestone
+8. **Gate timing is visible.** The gate prints how long each step takes
+   and names its slowest tests. The orchestrator adds the slow gate's
+   duration to its merge note, so the trend is visible in `mu log`
+   without any new tooling.
+9. **No `mu gate` command yet.** Gate records are note text. Add a
+   command only if agents keep re-running gates despite the records.
+
+## The `test-health` recipe (new)
+
+`skills/mu/recipes/test-health.md`. It runs when a decision 7 trigger
+fires, or when the user asks.
+
+1. **Profile.**
+   - Time every gate step.
+   - List the 20 slowest tests at each level.
+   - Inspect waits: distinguish avoidable readiness padding from temporal
+     assertions, negative observations and sleeping fixtures.
+   - Find build work that runs more than once: cold caches, duplicate
+     profiles, the same build in dev and release.
+   - Record the gate's wall time and test counts as a BEFORE note.
+2. **Classify.** One finder per area (parallel delegate calls). Each
+   slow or overlapping test gets one verdict:
+   - KEEP
+   - SPEED-UP: poll readiness instead of padding; share setup only if test
+     isolation is preserved
+   - MOVE-DOWN: rewrite at a lower level
+   - MERGE: fold into another test, which it names
+   - DELETE: covered by the test it names
+   Every verdict comes with its evidence.
+3. **Refute.** Every MERGE and DELETE goes to a refuter: "which failure
+   would no longer be caught?" A refuted verdict becomes KEEP.
+4. **Do.** The surviving verdicts run as normal tasks. They are
+   test-only diffs, and their review checks only that the coverage the
+   refuter accepted is still there.
+5. **Measure.** Run the slow gate again and record an AFTER note. A pass
+   that leaves the gate neither faster nor smaller did not do its job:
+   say so, and say why.
+
+Done when the AFTER note is recorded, and the slow gate is within its
+budget or the note says what still keeps it over.
+
+## Changes
+
+| File | Change |
+|---|---|
+| `skills/mu/SKILL.md` | Vocabulary: replace the single gate command with fast gate / slow gate / gate budget / gate record / test upkeep. Orchestrator rules: one slow gate per merge batch; queue test-health when a trigger fires. |
+| `skills/mu/recipes/test-health.md` | New, as above. |
+| `skills/mu/recipes/adversarial-review.md` | Reviewer brief: reuse gate records; run only the tests for the diff; the new test findings (decision 5). |
+| `skills/mu/recipes/worker.md`, `recipes/brief.md` | Who runs which gate (decision 2); the gate record line in the DONE note; red-green only for fixes; rules for adding a test. |
+| `skills/mu/recipes/orchestrator-loop.md` § Merging | Batch merge, then one slow gate, then bisect when it fails. Add the slow gate's duration to the merge note. Section on sharing the build cache. |
+| `skills/mu/recipes/waves.md`, `review-panel.md`, `remote-workers.md` | "Gate command" → "slow gate" where they mean the merge gate. |
+| `skills/mu/recipes/plan.md` | A new project's plan defines `## Gates` in the repo first. Every phase ends with a test-health task. |
+
+Out of scope: a `mu gate` command, caching gate results in the mu DB,
+and test-coverage tooling.
+
+## Rollout
+
+1. **Battle-test on swaywardlock** before editing any recipe:
+   - after Phase 3 owners release the repo, add `## Gates` to its README
+   - split and instrument `contrib/gate`, preserving default full execution
+     and all checks; route CI through the canonical inventory
+   - full slow mode clears/rejects inherited `TESTS`; targeted runs remain
+     explicit, and standalone slow mode builds its own test-auth executable
+   - preserve default-feature auth tests and all three release hook scans;
+     report privilege/scdoc skips explicitly
+   - time every gate step and e2e case including setup/teardown; establish
+     an inspected baseline before moving or removing coverage
+   - retain private build artifacts; investigate safe cache reuse separately
+   - make one low-risk readiness-wait change, then measure before/after
+   - run `test-health` by hand, from this spec
+   - write down where the spec was wrong
+2. Write the recipe changes from what we learned.
+3. **Measure** with `museum-search stats` (museum spec
+   `2026-10-21-session-stats.md`): full gate runs per task, gate share
+   of worker time, slow gate duration. Compare swaywardlock Phase 3 with
+   the next phase.
+
+## Open questions
+
+- Where the line between the fast and slow gate falls when a project has
+  a cheap integration test that needs a daemon. Settle it on
+  swaywardlock, where `contrib/test-real-pam` and the converter tests
+  are candidates for either side.
+- Whether the gate record should carry the commit sha as well as the
+  tree hash, for readability. It costs nothing, so probably yes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.13.1",
+  "version": "3.13.3",
   "description": "A persistent, observable crew of pi agents running in one tmux or herdr session per workstream, coordinated through a built-in task DAG.",
   "publishConfig": {
     "access": "public"

package/skills/mu/SKILL.md

@@ -56,9 +56,9 @@ Recipe words, the same in every recipe:
   finding and round; holds the brief, criteria and stop rule; closes
   with `mu task close <umbrella> --if-ready`.
 - **unit** — one piece of the job, one task (a file, a call site, a fix).
-- **gate** — two kinds: a **gate command** (tests, build) that must
-  pass on the merged tree, and a **review gate** (a `review_x` task
-  blocked by `x`) that decides whether `x` counts.
+- **fast gate / slow gate / gate budget / gate record / test upkeep** —
+  repo-defined verification and its upkeep ([test-health](recipes/test-health.md#gate-contract));
+  a **review gate** (`review_x` blocked by `x`) decides whether `x` counts.
 - **wave** — the units dispatched from one main revision; refresh
   workspaces before the next.
 - **finding** — one reported problem, recorded as an `OPEN/triage` task.
@@ -183,9 +183,11 @@ rules hold even when you skip it:
 
 - **Claim before sending**, even one-shot reviewers. Ownership is
   durable and waitable; agent state is not.
-- **Pipeline; don't barrier.** Merge each task as it closes.
+- **Pipeline; don't barrier.** Merge accepted tasks as they close; verify
+  one pinned merge batch without pausing independent workers.
 - **Verify the merge, not the worker's rerun.** Only `CLOSED/done` ships.
-- **Push only when the gate command passes** on the merged tree.
+- **Push after merged-tree gates pass.** Run full slow once per batch, plus
+  fast if needed; queue [test upkeep](recipes/test-health.md#upkeep-loop) at milestones or budget crossings.
 - **Define done before a long run**: the completion criterion goes in
   the task note first ([long-run](recipes/long-run.md)).
 - **New work to pi is `mu agent send --fresh`.** Never chain `/new` and
@@ -281,6 +283,7 @@ risky job that needs several of them, start with
 | [brief](recipes/brief.md) | you write a task note or prompt a worker will read |
 | [plan](recipes/plan.md) | you turn a spec or requirements into a task DAG |
 | [worker](recipes/worker.md) | a task was claimed for you |
+| [test-health](recipes/test-health.md) | define gates, choose verification, add tests, or upkeep at milestones/budget crossings |
 | [recovery](recipes/recovery.md) | undo, rebuild, teardown, sync setup, `doctor` cleanup |
 | [remote-workers](recipes/remote-workers.md) | an agent runs on another machine |
 | [waves](recipes/waves.md) | more than one worker edits the same repo at once |

package/skills/mu/recipes/adversarial-review.md

@@ -17,9 +17,9 @@ PR or diff from several angles, use [review-panel](review-panel.md).
 ## Steps
 
 1. **Write the criteria first.** Before dispatching the work, note on
-   the work task what "accepted" means: the requirements, the edge
-   cases that need tests, the files that must not change. The reviewer
-   judges against this note, not against its own taste.
+   the work task what "accepted" means: requirements, risky behaviours
+   needing coverage, and files that must not change. The reviewer judges
+   against this note, not against its own taste.
 2. **Add the review task, blocked by the work:**
 
    ```bash
@@ -53,20 +53,24 @@ PR or diff from several angles, use [review-panel](review-panel.md).
    ask the human. A third round of the same argument rarely converges.
 
 Done when the latest review task is `CLOSED/done` (ACCEPT), and the
-accepted commits are merged and the merged tree passes the gate command.
+accepted commits are merged and the batch passes the merged-tree gates
+([orchestrator-loop § Merging](orchestrator-loop.md#merging)).
 
 ## Reviewer brief
 
-Send this with the task id, the workspace path, and the commit range:
+Send this with the task id, workspace path, commit range, gate records and
+[test-health](test-health.md) pointer:
 
 ```text
 You are reviewing task <x>. You did not write it. Your job is to find
 where it fails the acceptance criteria in `mu task notes <x>`.
 
-- Read the diff (<range>) and the criteria. Run the tests that cover it.
-- Report findings against the criteria: a requirement not met, an edge case
-  without a test, a change outside scope, a claim the evidence does not
-  support. Not style, not preferences.
+- Read the diff (<range>), criteria and worker gate records. Follow
+  test-health.md for record equivalence, targeted runs and test findings.
+  Reproduce claimed failures; a full rerun or parent build is not routine.
+- Report findings against the criteria: a requirement not met, risky
+  untested/broken behaviour, a change outside scope, unsupported evidence.
+  Not style, not preferences.
 - Record each as a finding, per findings.md § Record:
   mu task add -w <ws> --triage -t "<severity>: <title>" -i <n> -e <days> \
     --note 'FINDING: <severity> <file:line> <what fails> EVIDENCE: <command + output>'
@@ -92,7 +96,7 @@ by orchestrator`.
 ## Traps
 
 - **A reviewer that sees the author's reasoning agrees with it.** Send
-  the diff and the criteria, not the worker's transcript or close note.
+  the diff, criteria and gate records, not the worker's reasoning transcript.
 - **"Looks good" is not a verdict.** Require a close that matches the
   verdict (`done` or `--as rejected`) and at least one command the
   reviewer ran. A review with no evidence is a

package/skills/mu/recipes/brief.md

@@ -14,7 +14,7 @@ not in the brief, or one pointer away, does not exist for it.
    `npm run typecheck`", not "update the call sites". A vague bound
    invites the worker to stop at the first plausible point.
 2. **Inline what every path needs; point to the rest.** Files, the
-   verify command, scope, and the final action go in the brief. Shared
+   targeted verify command, scope, and the final action go in the brief. Shared
    context goes in one place (an umbrella's note) and the brief points
    at it: `Read: mu task notes sweep -w audit`. Repeating it per task
    copies it into every worker's context and lets the copies drift.
@@ -43,13 +43,18 @@ Read: mu task notes <id> -w <ws>   (and the umbrella's, if any)
 GOAL: <one sentence>
 FILES: <paths it may change>
 DONE WHEN: <checkable, exhaustive criterion>
-VERIFY: <exact command>
+VERIFY: <repo Gates pointer + exact targeted command/scope; test-health.md by role>
+NOTE: <applicable gate records before close; test-health.md § Gate contract>
 
 ⚠️ FINAL ACTION
 git commit -am '<msg>' THEN
 mu task close <id> -w <ws> --evidence "$v"   # command + result; see Quoting
 ```
 
+Use [test-health](test-health.md) for worker/reviewer gate allocation, gate
+records, test levels and cheap bug red-green. Point to it rather than asking
+each role for a full gate or parent build.
+
 ## Quoting
 
 Single quotes suit short text with no `'`. Prose (an apostrophe ends

package/skills/mu/recipes/orchestrator-loop.md

@@ -19,9 +19,9 @@ the loop and the reasons behind them.
    `mu agent send <w> --fresh '...'` (new session + prompt in one step;
    refuses while busy). The brief ends with its final-action block.
 5. `mu task wait ... --first --on-stall exit --json`.
-6. Cherry-pick the closed worker's **new** commit(s), verify the MERGE,
-   then continue the loop in the same turn. Do not barrier or loop in
-   shell.
+6. Cherry-pick the accepted worker's **new** commit(s) into a merge batch
+   (below), then continue the loop in the same turn. Do not barrier or
+   loop in shell.
    Only `CLOSED/done` ships; other closes: read the reason note.
 7. Repeat from `mu state`.
 
@@ -42,9 +42,9 @@ keeps it.
   ends with its `VERDICT: <id>` block, so a batch still maps back. Read
   every verdict in the batch before deciding any.
 - **Workers with workspaces** build and test: about one per CPU core,
-  fewer when each runs the full suite. A remote host has its own
-  session cap ([remote-workers](remote-workers.md)).
-- **Stream, do not batch.** Keep the pool full: dispatch the next unit
+  fewer when targeted slow checks contend for resources. A remote host has
+  its own session cap ([remote-workers](remote-workers.md)).
+- **Stream dispatch.** Keep the pool full: dispatch the next unit
   when one closes, rather than waiting for a whole wave. With the
   `codemode` tool, a [driver](codemode-driver.md) can dispatch a batch
   of workers in one script.
@@ -72,15 +72,21 @@ per turn ([remote-workers](remote-workers.md#step-5-poll-once-per-turn)).
 
 ## Merging
 
-- **Pipeline; don't barrier.** Wait for one task, cherry-pick only its
-  new commits, verify, dispatch the next. An umbrella wait hides progress;
-  merging stale branches can restore reverted code.
-- **Verify the merge, not the worker's rerun.** Only the combination
-  with moved main is new, and it breaks in ways the worker's own run
-  cannot show. Remote hosts: [run the merged gate there](remote-workers.md#run-the-merged-gate-on-the-host).
-- **Push only when the gate command passes.** Make `git push` the last
-  line under `set -e`. Check the gate command runs what it claims: an env-gated randomized
-  test once passed with zero cases.
+- **Pipeline; don't barrier.** Cherry-pick accepted new commits as tasks
+  close and dispatch the next unit. Choose a bounded merge batch; an umbrella
+  wait hides progress and stale branches can restore reverted code.
+- **Pin the batch tree.** Run full slow once, plus fast if slow excludes it,
+  under [the gate contract](test-health.md#gate-contract). Keep the tested
+  checkout unchanged during the run; independent workers continue in their
+  workspaces. Later merges form the next batch, not an extension of this pass.
+  Remote hosts: [run the merged gate there](remote-workers.md#run-the-merged-gate-on-the-host).
+- **Bisect a failed batch.** Isolate the offending commit/interaction, fix it,
+  and gate the corrected merged tree before shipping.
+- **Push only the verified tree.** Make `git push` the last line under
+  `set -e`; required integration and safety checks must actually run.
+  Record the gate result and slow duration with the merged tree in the merge
+  note/`mu log`. Queue [upkeep](test-health.md#upkeep-loop) on a budget crossing
+  or milestone, rather than stopping all independent work.
 - **Accept evidence, not close notes.** Re-run the key measurement from
   a clean checkout; close notes have claimed unpushed commits. A
   worker's "done" counts only once the diff shows the change. Your own
@@ -90,6 +96,16 @@ per turn ([remote-workers](remote-workers.md#step-5-poll-once-per-turn)).
   agreeing with itself, a fixture you tuned on. A nonzero diff is a
   failure even when the command exited 0.
 
+## Build cache
+
+Keep build targets private per workspace and auth/profile lane. Share dependency
+downloads and use an existing compiler cache when available; measure cold/warm
+cost and contention. Keep normal-auth, test-auth and release artifacts distinct,
+with explicit executable paths for consumers. A shared writable Cargo target
+can replace a binary after its build lock is released, while tests still use it.
+Warm-up may copy a quiescent snapshot into private storage, never hardlinks or
+a live target. This is build guidance, not a new mu cache or dependency.
+
 ## Sending
 
 A running worker sees what you send, never a new task note: deliver

package/skills/mu/recipes/plan.md

@@ -7,8 +7,10 @@ human asks for a file.
 
 ## Steps
 
-1. **Map the files first.** List what gets created or changed and what
-   each file is responsible for. Task boundaries fall out of this map.
+1. **Map files and gates.** List what gets created or changed and each
+   file's responsibility. For a new project, define repo `## Gates` first
+   ([test-health](test-health.md#gate-contract)); point plan notes there.
+   Existing gates remain until their replacement is approved.
 2. **Size the tasks.** A task is the smallest unit that carries its own
    verification and is worth a review. Split only where a reviewer
    could reject one task and accept its neighbour. Fold setup, config,
@@ -59,5 +61,7 @@ lists the tasks you meant to run in parallel as Ready together. Then dispatch pe
   its step count. Guess honestly rather than defaulting to 50 and 1.
 - Review gates follow [adversarial-review](adversarial-review.md): a
   review task blocked by the work.
+- End each phase/milestone with a [test-health task](test-health.md#upkeep-loop);
+  connect real dependencies, not a barrier across independent workers.
 - When reality disagrees with the plan, append a note saying so. Do not
   rewrite earlier notes.

package/skills/mu/recipes/remote-workers.md

@@ -53,7 +53,7 @@ git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
 ```
 
 Done when the worker's commits are cherry-picked locally, the merged
-tree passes the gate command (on the host, below), and the pane is
+tree passes the merged-tree gates (host and local checks below), and the pane is
 closed.
 
 ### Step 2: the note is load-bearing
@@ -117,9 +117,9 @@ while the worker asks a question, do not poll: read the pane
 
 ### Run the merged gate on the host
 
-Do not re-run what the worker ran. Only the merge is unverified.
-Cherry-pick locally, push the merged head to the host, and run the gate
-there with its warm dependencies:
+Reuse only equivalent [gate records](test-health.md#gate-contract).
+Cherry-pick a merge batch locally, push its pinned head to the host, and run
+full slow there with warm dependencies, plus fast if slow excludes it:
 
 ```bash
 git cherry-pick <sha>
@@ -131,12 +131,16 @@ mule run --cwd ~/hacking/<gate-checkout> --wait \
 `<gate-checkout>` is a scratch checkout or worktree used only for
 gates, never one holding work. Push to a temporary ref, never `main`;
 delete it afterwards (`git push origin :gate-tmp`). Push to `main` only
-after the gate passes.
+after required gates pass. Replace `npm run check` with the repo's canonical
+merged-tree command(s), preserving full scope and recording host conditions.
+Keep the gate checkout pinned while other remote workers continue in theirs;
+use private artifacts ([build cache](orchestrator-loop.md#build-cache)).
 
 `--wait` exits with the suite's code. A bare ssh would hold the capped
-channel for minutes. Keep two gates local: platform-sensitive tests (macOS `ps` returns argv,
-Linux `ps -e` appends the environment, and a real bug lived there), and
-the final gate before the push that matters.
+channel for minutes. Retain local platform-sensitive checks (macOS `ps`
+returns argv, Linux `ps -e` appends the environment, and a real bug lived
+there), and the repo-required final local gate before the push that matters.
+A remote pass does not substitute for non-equivalent local conditions.
 
 ## Traps
 

package/skills/mu/recipes/review-panel.md

@@ -28,11 +28,12 @@ panel's findings will be fixed by agents. Both modes are in
    | correctness | logic errors, edge cases, error paths, races |
    | security | injection, auth and permission checks, secrets, unsafe input |
    | simplicity | duplication, dead code, needless abstraction, an existing helper not reused |
-   | tests | changed behaviour without a test, tests that cannot fail |
+   | tests | risky coverage gaps, ineffective tests, level/duplication/wait/cost findings ([test-health](test-health.md#adding-or-changing-tests)) |
    | rules | the repo's written rules (see [rules-audit](rules-audit.md)) |
 
    Each reviewer gets the range, its angle, and the [brief](brief.md)
-   rules; it edits nothing. A clean result (`FINDINGS: none` plus the
+   rules and available gate records ([test-health](test-health.md#gate-contract));
+   coordinate targeted checks across angles. It edits nothing. A clean result (`FINDINGS: none` plus the
    commands it ran) is a valid result.
 3. **Record findings** by mode:
    - delegate: each reviewer ends its answer with `FINDING:` lines;
@@ -60,5 +61,5 @@ triage and the umbrella closes with `--if-ready` (workstream mode).
   author's tier or higher ([models](models.md#checkers)); one model's
   blind spot repeated five times is still one blind spot. Pass `model`
   to `mu_delegate`.
-- **The panel is not the gate command.** Merge verification still runs on the
+- **The panel is not the slow gate.** Merge verification still runs on the
   merged tree ([orchestrator-loop](orchestrator-loop.md#merging)).

package/skills/mu/recipes/test-health.md

@@ -0,0 +1,92 @@
+# Test health
+
+Read when defining gates, choosing worker/reviewer verification, adding tests,
+or doing upkeep at a milestone, a budget crossing, or the user's request.
+Testing stays encouraged; upkeep protects coverage and the iteration loop.
+
+## Gate contract
+
+Use the repo's `## Gates` in AGENTS.md or README: fast and slow commands,
+slow-gate budget (default 5 min), and a targeted slow-test command. Plan notes
+point there. Until a split is approved, keep the existing repo gate intact;
+recipe guidance does not waive project checks. Fast means iteration checks,
+not a universal seconds promise: measure cold and warm costs.
+
+- **Worker:** run the fast gate while iterating; before closing, run slow
+  tests for the changed area once, then fast on the final commit. Record
+  both, or why a scope is inapplicable/unavailable. Changes invalidate records.
+- **Reviewer:** inspect the diff and reuse equivalent worker records. Run
+  uncovered tests for the diff and reproduce claimed failures, rather than
+  repeating the full suite or building the parent for every new test.
+- **Orchestrator:** verify one pinned merged tree per batch with the full
+  slow gate, plus fast if slow does not include it. All required integration,
+  auth, release and packaging checks still pass before push. Bisect a failed
+  batch; record the corrected tree's pass. See [merging](orchestrator-loop.md#merging).
+
+Gate records are task-note text, not a mu command or stored result cache:
+
+```text
+GATE: commit=<sha> tree=<hash>; command=<exact command + filters>; scope=<full/area>
+RESULT: exit=<code>; duration=<wall time>; counts=<tests/assertions>; skips=<none or reasons>
+CONDITIONS: <toolchain, host/platform, privileges, relevant env/features, cache state>
+```
+
+Reuse requires the same tree, command/scope and equivalent execution
+conditions. Record uncommitted inputs too; a dirty tree hash alone is not
+an identity. A targeted pass, zero selected cases, or a skipped privileged
+check is not a full pass. Clear/reject inherited selectors for full runs;
+report skips explicitly and resolve required missing checks before push.
+
+## Adding or changing tests
+
+Use the lowest level that catches the failure, covering behaviour not
+already guarded. A new slow case states what only it can see in a comment
+or commit message. For a bug with a cheap, obvious local target, the worker
+shows red on the base and green on the fix; feature work and integration-heavy
+paths need no mandatory red-green ceremony. Use direct executable evidence
+when stronger, recording the reason.
+
+Poll readiness/completion with a bound and useful failure output. Retain
+necessary temporal sampling, negative-observation windows and deliberately
+sleeping process fixtures; explain their timing contract.
+
+Reviewer findings identify risky untested/broken behaviour, a wrong test
+level, duplication of a named test, avoidable readiness padding, or measured
+gate slowdown—not every conceivable edge case without a test.
+
+## Upkeep loop
+
+Queue ordinary upkeep work at each phase/milestone end or when a merged slow
+gate exceeds budget. Prioritise it before new features; continue independent
+work. A budget is a scheduling trigger, not an indefinite crew-wide stop.
+
+1. **Profile.** Time each gate step and test, including setup/teardown.
+   List up to 20 slowest tests per level; inspect waits and repeated builds,
+   cold caches and profiles. BEFORE records wall time, counts, skips and
+   conditions. Use inspected execution logs, not commands merely mentioning
+   a gate or compound-command durations attributed entirely to tests.
+2. **Classify.** Parallel [delegate calls](tasks-or-calls.md#delegate-call),
+   one per area, give slow/overlapping tests an evidenced verdict:
+   KEEP; SPEED-UP (poll or share setup with isolation); MOVE-DOWN;
+   MERGE into a named test; DELETE as covered by a named test.
+3. **Refute.** Send every MERGE/DELETE verdict to a refuter: which failure
+   would no longer be caught? A refuted or unresolved verdict becomes KEEP.
+4. **Do.** Dispatch surviving changes as normal test-only tasks. Review
+   coverage preservation, isolation and correctness of the harness changes.
+   Preserve auth lanes, privilege checks and release scans; measure safe
+   [build reuse](orchestrator-loop.md#build-cache) separately.
+5. **Measure.** Run the merged gates and record AFTER under comparable
+   conditions, including coverage/count changes. If neither faster nor
+   smaller, say so and why; smaller alone does not prove preserved coverage.
+
+6. **Report.** Before teardown, commit a dated report to the repo
+   (`docs/test-health/<YYYY-MM-DD>.md`): conditions, BEFORE/AFTER, each
+   finding with its evidence, every refuted or rejected verdict with the
+   reason, and the remaining bottleneck. Task notes die with the
+   workstream; the next pass reads the latest report first and still
+   re-measures. Add a file per pass; never edit an old one.
+
+Done when AFTER records the outcome, the report is committed, and the slow
+gate is within budget or the report names the remaining bottleneck and
+prioritised follow-up. Keep unmet required checks distinct from a
+time-budget overrun.

package/skills/mu/recipes/waves.md

@@ -10,12 +10,12 @@ runs in its own `--workspace`; this recipe decides what each one gets.
    the shared files. A blanket freeze idled four of five workers for a
    day.
 3. **Pipeline the merge.** Cherry-pick each task as it closes and
-   verify the merged tree ([orchestrator-loop § Merging](orchestrator-loop.md#merging));
-   never wait for the whole wave.
+   verify pinned merge batches ([orchestrator-loop § Merging](orchestrator-loop.md#merging));
+   batching gates does not mean waiting for the whole wave.
 4. **Refresh before each dispatch.** `mu workspace refresh <agent>`
    rebases onto the tracked main (git: `origin/HEAD`, so unpushed local
    merges are missed; pass `--from <local-branch>` to include them) and
    keeps the agent's context; run it before every `--fresh` send.
 
 Done when every task in the wave is `CLOSED/done`, merged, and the
-merged tree passes the gate command.
+merged tree passes the slow gate and fast if needed, per the repo contract.

package/skills/mu/recipes/worker.md

@@ -17,11 +17,15 @@ mu task note <id> "FILES: ...\nCOMMANDS: ... (exit codes)\nDECISION: ...\nVERIFI
 mu task close <id> --evidence "tests pass: ..."  # LAST action
 ```
 
+Follow [test-health](test-health.md) for fast iteration checks, targeted slow
+checks before close, gate records, and cheap bug red-green. Include the gate
+records in your final note; adding tests uses its test-level and timing rules.
+
 The note follows the task note contract in SKILL.md. Keep each tool
 call to minutes (short batches, waits with a timeout): steering reaches
 you only between tool calls. Commit before you close: the orchestrator cherry-picks your commits, not your tree. A
 review or audit task records each problem per
 [findings § Record](findings.md#record).
 
-Done when your changes are committed in the workspace, the task note holds FILES, COMMANDS (with exit codes) and VERIFIED, and `mu task close` succeeded as your last action. Skipping close makes the orchestrator's
+Done when your changes are committed in the workspace, the task note holds FILES, COMMANDS (with exit codes), VERIFIED and applicable gate records, and `mu task close` succeeded as your last action. Skipping close makes the orchestrator's
 wait hang. Won't do it: `close --as wontfix --why "..."`.