@mu-crew/mu 3.2.1 → 3.3.0

package/skills/mu/SKILL.md

@@ -55,9 +55,7 @@ auto-created), `send --fresh`, then `mu agent wait --json` (`lastText`).
 
 - `mu agent wait <names...> --first` waits for busy → idle instead of a
   `sleep` loop; exit 0 met, 5 timeout, 6 pane died.
-- For a watcher, persist last-seen state in a log ledger: write `mu log -w
-  scratch --kind pr-state 'pr=1234 sha=abc ci=red'`, then read `mu log -w
-  scratch --kind pr-state -n 1 --json`. Act only on change.
+- For a watcher (PR, CI, a log), follow [recipes/watcher.md](recipes/watcher.md).
 - One agent per independent unit; `--workspace` for any helper that may edit,
   build, or test the shared repo.
 
@@ -89,16 +87,10 @@ keeps LLM context. Claim and send warn at ≥10 commits behind
 
 ### Remote agents
 
-The PANE is local, the PROCESS is remote (`--command 'ssh <host> -t
-"..."'`); `mu agent remote-env` forwards a pi agent's control socket.
-**One orchestrator DB**: never run a second mu on the host. You create
-the remote workspace yourself (`--workspace` is local-only).
-
-**Read [REMOTE_WORKERS.md](REMOTE_WORKERS.md) before spawning your first
-remote agent, and again before waiting on one.** Poll once per turn with
-the claim's one-shot `Next:` command. On a session-capped host, route
-long commands and polls through [mule](https://github.com/mu-crew/mule):
-a refused bare ssh returns an empty sha that looks like progress.
+The PANE is local, the PROCESS is remote. **One orchestrator DB**: never
+run a second mu on the host. **Read
+[recipes/remote-workers.md](recipes/remote-workers.md) before spawning
+your first remote agent, and again before waiting on one.**
 **`mule` exit 3 is a HANDBACK** to the operator (hardware-key touch):
 never retry or open `ssh -MNf` yourself.
 
@@ -124,78 +116,37 @@ ODDITIES: weird things not acted on
 Then close with grounding:
 `mu task close <id> -w <ws> --evidence "tests pass: cargo test exit 0"`.
 
-## Orchestrator loop
-
-Every turn:
-
-1. `mu state -w <ws>` — read agents, IN_PROGRESS, ready tasks,
-   parallel tracks.
-2. Spawn at most one agent per independent ready track.
-3. **Claim before sending — even one-shot reviewers/scouts.**
-   `mu task claim <id> -w <ws> --for <agent> --evidence "..."`.
-   If no task exists, `mu task add` first (`--note 'REPRO: ...'` when
-   the title is not enough). Ownership is durable and waitable; agent
-   state is not.
-4. Send each new task with `mu agent send <w> --fresh '...'` (new
-   session + prompt in one step; refuses while busy): task id,
-   files/notes to read, workspace path, validation command, scope
-   guards, task note contract. Follow the `Next:` block; it picks
-   `--fresh` vs `--steer` for you.
-5. End with a loud final-action block:
-
-   ```text
-   ⚠️ FINAL ACTION
-   git commit -am '...' THEN
-   mu task close <id> -w <ws> --evidence '...'
-   ```
-
-6. `mu task wait ... --first --on-stall exit --json`.
-7. Cherry-pick the closed worker's **new** commit(s), verify the MERGE
-   (see below), return control. Do not barrier or loop in shell.
-   Only `CLOSED/done` ships; other closes: read the reason note.
-8. Repeat from `mu state`.
-
-## Dispatch rules that prevent real failures
-
-- **Pipeline; don't barrier.** Wait for one task, cherry-pick only its
-  new commits, verify, return control. 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; that found three breaks rerunning found none
-  of. Run a remote merge gate on the host (see REMOTE_WORKERS.md).
-- **Push only from a green gate.** Make `git push` the last line under
-  `set -e`. Check the gate runs what it claims: an env-gated randomized
-  test once passed with zero cases.
-- **Dispatch from current main.** Reset the worker's worktree to main
-  before each task.
-- **Accept evidence, not close notes.** Re-run the key measurement from
-  a clean checkout; close notes have claimed unpushed commits.
-- **Freeze only what conflicts.** Give idle workers tasks that avoid
-  shared files; a blanket freeze idled four of five workers for a day.
-- **Fix done before a long run.** Put the completion criterion (checks,
-  agreeing runs, allowed variance) in the task note first.
-- **Split long proofs into independent units**, sharded and parallel,
-  so one flake restarts only its unit.
-- Bucket waves by file cluster, not severity; two agents editing one file
-  conflict. Refresh workspaces between waves.
-- Cross-workstream wait and claim use qualified refs; only task
-  ownership crosses.
-- For an idle worker, read the pane, then answer, retry, or release its
-  task. `MU_IDLE_THRESHOLD_MS` defaults to 5m.
-- **Never chain `/new` and a prompt as two sends to a pi agent:** the prompt
-  can land mid-reset and vanish (it did, twice). `--fresh` does both inside pi.
-- **Stop a worker:** `mu agent abort <w>` first for pi (exact, local or
-  remote, keeps context, waits for idle; exit 5 = still busy; queued
-  follow-ups return to the editor unsent). Then `mu agent kick` (pi
-  unresponsive, or non-pi; local panes only), then `mu agent close`.
-- Use `mu agent send`, not raw mux input. Single-quote prompts containing shell
-  expansions, or use a quoted heredoc.
+## Orchestrator rules
+
+<!-- mu:keep-driving -->
+**While workers run, keep driving.** Your turn ends only when every
+task is closed, or when a decision only a human can make blocks all
+progress (scope, spend, irreversible or external actions, a hardware-key
+handback). A status summary is a log line, not a stopping point: write
+it with `mu log`, then go straight back to `mu task wait`. Ending a
+turn to report progress while workers are busy stalls the whole crew.
+<!-- /mu:keep-driving -->
+
+Before you dispatch, read [recipes/orchestrator-loop.md](recipes/orchestrator-loop.md):
+the every-turn loop, waiting, merging, and stopping workers. These
+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.
+- **Verify the merge, not the worker's rerun.** Only `CLOSED/done` ships.
+- **Push only from a green gate.**
+- **Fix done before a long run**: the completion criterion goes in the
+  task note first.
+- **New work to pi is `mu agent send --fresh`.** Never chain `/new` and
+  a prompt as two sends: the prompt can land mid-reset and vanish.
+- **`mu task wait --first --on-stall exit`**; exit 7 means read the
+  owner's pane and answer it.
+- **Stop a worker gently**: `mu agent abort`, then `kick`, then `close`.
 
 ## CLI gotchas
 
-- **`workstream teardown`** is dry-run without `--yes`. It writes
-  TOMBSTONE ops, so `mu undo <group> --yes` reverses it; the log is the
-  backup. `workstream list --torn-down` lists group ids to undo.
+- **`workstream teardown`** is dry-run without `--yes`.
 - **`task close --if-ready`** no-ops until every blocker is CLOSED; bare
   `task release` reopens IN_PROGRESS.
 - **`task close --as rejected|wontfix --why ...`** (declined | valid, not worth it) unblocks dependents (listed in
@@ -204,32 +155,12 @@ Every turn:
   IN_PROGRESS — `task release` first.
 - **For waits use `task wait`, not `log --tail`.** `--kind` is the operator's
   log-ledger channel; `--intent` is what mu recorded.
-- **`mu undo`** bare lists groups; `<group>` previews; `<group> --yes`
-  emits inverse ops for that group only (redo = undo the undo). Exit 4
-  if a later action changed the same fields (`--force` discards it).
-  Rows only: killed panes and freed workspace dirs do not come back.
-- **`mu rebuild <file>`** writes a new DB from the ops log, without
-  agents or workspaces; re-spawn after the swap. Recovery is
-  `mu rebuild`, not `mu db backup`.
 - **`mu sql`** skips ambient sync.
-- **Sync:** set `MU_SYNC_DIR` on each machine to a shared folder
-  (Syncthing). Every command flushes and ingests ops, merged per field.
-  mu never runs ssh or rsync; `mu sync` prints the line.
-  `--repair <peer>` is always safe. **Never put `MU_DB_PATH` inside
-  `MU_SYNC_DIR`**: it corrupts the DB. Agents, workspaces, and task
-  ownership never travel.
-- **`mu doctor --deep` DRIFT** (exit 5) is a capture bug: back up and
-  report it. Do not rebuild; the live rows may hold work the log missed.
-  The `disk` section is report-only: an orphan dir may hold the only copy
-  of uncommitted work, so mu prints cleanup commands and runs none.
-
-## `mu task wait`
-
-Use `--first --on-stall exit`: `--first` populates `.firing`, and
-`--on-stall exit` stops an unattended wait when a worker needs attention.
-Exit 6 is a dead pane; exit 7 is an owner in `needs_input`. Read that
-pane (`mu agent read <owner>`) and answer: the worker may be waiting on
-you. Questions are cheaper than rework.
+- **Never put `MU_DB_PATH` inside `MU_SYNC_DIR`**: it corrupts the DB.
+- **`mu doctor --deep` DRIFT** (exit 5): back up and report it; do not
+  rebuild.
+- Before undo, rebuild, teardown, sync setup, or acting on `doctor`
+  cleanup output, read [recipes/recovery.md](recipes/recovery.md).
 
 ## Models and thinking effort
 
@@ -258,31 +189,10 @@ says why. Before a high-stakes decision, read the pane
 (`mu agent read worker-1 -n 100`), `mu log -w <ws> --tail`, and
 `mu task notes <id>`.
 
-## In-pane worker loop
-
-`$MU_AGENT_NAME` (injected at spawn) resolves identity; adopted panes
-fall back to the pane title. In a worker pane, bare `mu task claim <id>`
-works. In the unregistered orchestrator pane it errors; use `--self`,
-`--for <worker>`, or `mu agent adopt <pane>`.
-
-```bash
-mu me
-mu me next
-mu task show <id>; mu task notes <id>
-mu task claim <id> --evidence "starting; read notes"
-mu task note <id> "FILES: ...\nDECISION: ...\nVERIFIED: ..."
-mu task close <id> --evidence "tests pass: ..."  # LAST action
-```
-
-Skipping close makes the orchestrator's wait hang. Won't do it:
-`close --as wontfix --why "..."`.
+## You are a worker
 
-## Follow-on prompts
-
-A plain `mu agent send` appends to prior context; use it to steer or
-answer. Unrelated work to pi: `mu agent send worker-1 --fresh 'Claim
-task_x...'`. claude-code/codex: send `/new` (codex: `/clear`), then the
-prompt; a send it cannot confirm prints a `warning:` on stderr.
+If a task was claimed for you, follow [recipes/worker.md](recipes/worker.md).
+Close the task as your last action, or the orchestrator's wait hangs.
 
 ## Guardrails
 
@@ -290,6 +200,36 @@ Task ownership outranks agent state. Coordinate through task notes and
 the activity log. Keep edges within one workstream and reserve the `mu_`
 task-id prefix. Give workers bounded paths and commands.
 
+## Recipes
+
+Read the recipe before starting the shape it names. For a large or
+risky job that needs several of them, start with
+[ultrathink](recipes/ultrathink.md).
+
+| Recipe | Read when |
+| --- | --- |
+| [ultrathink](recipes/ultrathink.md) | a job is too large or risky for one context; composes the rest |
+| [orchestrator-loop](recipes/orchestrator-loop.md) | you dispatch tasks and merge results |
+| [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 |
+| [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 |
+| [long-run](recipes/long-run.md) | a task or proof runs for hours, or must survive flakes |
+| [watcher](recipes/watcher.md) | a helper polls a PR, CI, or log for change |
+| [adversarial-review](recipes/adversarial-review.md) | work must be checked by someone other than its author before it counts |
+| [fan-out](recipes/fan-out.md) | the same change or check applies to many units |
+| [refute](recipes/refute.md) | an audit, sweep, or fact-check produces findings |
+| [hypothesis-panel](recipes/hypothesis-panel.md) | a root cause is unknown (flaky test, intermittent bug) |
+| [tournament](recipes/tournament.md) | several answers are possible and the best is a judgement call |
+| [loop-until-done](recipes/loop-until-done.md) | the amount of work is unknown until a check passes |
+| [triage](recipes/triage.md) | a backlog of external items needs classifying and acting on |
+| [deep-research](recipes/deep-research.md) | a question needs many sources read and cross-checked |
+| [review-panel](recipes/review-panel.md) | one diff or PR needs review from several angles |
+| [rules-audit](recipes/rules-audit.md) | a change must follow AGENTS.md rule by rule, or rules keep being restated |
+| [codemode-driver](recipes/codemode-driver.md) | a codemode script would dispatch a wave in parallel |
+
 ## See also
 
 - `mu --help`, `mu <verb> --help` — canonical CLI reference.

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

@@ -0,0 +1,83 @@
+# Adversarial review
+
+Use when a unit of work must be checked by someone other than its
+author before it counts: a fix, a finding, a claim, a plan. The author
+grades its own work generously; a fresh agent told to refute it does
+not. Every other review-shaped recipe builds on this one.
+
+The review is a task in the DAG, not a step inside the worker's
+session. Its verdict, its evidence, and every rejection stay in the DB.
+
+## 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.
+2. **Add the review task, blocked by the work:**
+
+   ```bash
+   mu task add review_x -w <ws> -t "Review x" -i 50 -e 0.5 --blocked-by x \
+     --note 'ACCEPTANCE: see x notes. Refute; report gaps, not style.'
+   ```
+
+3. **Dispatch the work** as usual. When `x` closes, `review_x` becomes
+   ready.
+4. **Spawn a fresh reviewer.** A new agent, or `--fresh` on an idle one,
+   so it has none of the author's reasoning. Use a different model from
+   the worker where you can (`--cli pi_big` reviewing `pi`): a second
+   model has different blind spots. Give it the worker's workspace path
+   and commits read-only by instruction; it edits nothing.
+5. **Send the reviewer brief** (below), claim `review_x` for it, wait.
+6. **Act on the verdict:**
+   - `ACCEPT`: cherry-pick `x`'s commits and verify the merge.
+   - `REJECT`: add `fix_x` (blocked by `review_x`, note = the gaps) and
+     `review_x_2` (blocked by `fix_x`). Dispatch `fix_x` to the original
+     worker, whose context still holds the work. Repeat from step 4.
+     The DAG grows; nothing is rewritten.
+   - The `fix_x` brief tells the author to check each gap before fixing
+     it: reproduce it, then fix it, or answer it with evidence in the
+     note (`GAP 2: not reproducible, <command + output>`). A gap the
+     author disputes goes to the next reviewer as a claim to check,
+     not as settled.
+7. **Cap the rounds.** After two rejections on the same unit, stop the
+   loop and decide yourself: split the unit, change the criteria, or
+   ask the human. A third round of the same argument rarely converges.
+
+Done when the latest review task closed with `VERDICT: ACCEPT`, and the
+accepted commits are merged and the merged tree passes the gate.
+
+## Reviewer brief
+
+Send this with the task id, the workspace path, and the commit range:
+
+```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 gaps 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.
+- Each gap cites a file:line or a command and its output.
+- If you could not check something (tool failed, no access), say
+  UNVERIFIED for it. Unverified is not a pass and not a fail.
+- Do not edit files.
+
+End with a note in the task note contract, plus one line:
+VERDICT: ACCEPT | REJECT
+Then close: mu task close review_<x> --evidence '<verdict + key check>'
+```
+
+## 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.
+- **"Looks good" is not a verdict.** Require the `VERDICT:` line and at
+  least one command the reviewer ran. A review with no evidence is a
+  rejected review: re-send it.
+- **Reviewers drift into fixing.** A reviewer that edits the code is now
+  an author nobody reviews. Keep the fix in `fix_x`.
+- **Review is not merge verification.** An accepted unit can still
+  break once merged with moved main. Verify the merge as in
+  [orchestrator-loop](orchestrator-loop.md#merging).

package/skills/mu/recipes/brief.md

@@ -0,0 +1,53 @@
+# Writing a brief
+
+Use when you write anything a worker reads: a task note, a `--fresh`
+prompt, a reviewer brief. The worker starts with no context. What is
+not in the brief, or one pointer away, does not exist for it.
+
+<!-- Ideas adapted from mattpocock/skills `writing-for-agents` (MIT). -->
+
+## Rules
+
+1. **End on a completion criterion.** The brief says how the worker
+   tells done from not done, and the criterion is both checkable and
+   exhaustive: "every file in the UNITS list compiles under
+   `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
+   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.
+3. **State the target, not the ban.** "Edit only files under
+   `src/auth/`" works; "don't touch other files" puts other files in
+   the worker's head. Keep a prohibition only for a hard guardrail
+   with no positive form, and pair it with the positive target.
+4. **Reuse the recipe words.** *Unit*, *stop rule*, *verdict*,
+   *finding*, *umbrella* mean the same thing in every recipe. Use them
+   as written; a worker that read one recipe brief reads the next
+   faster.
+5. **Cut the default.** A sentence the worker would obey anyway
+   ("be careful", "write clean code") costs attention and changes
+   nothing. Delete the whole sentence.
+6. **Ask for evidence, not reassurance.** The final note names the
+   commands run and their exit codes (the task note contract). "Done,
+   all good" is not a result.
+
+## Shape
+
+```text
+Task <id> in <ws>. Workspace: <path>.
+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>
+
+⚠️ FINAL ACTION
+git commit -am '<msg>' THEN
+mu task close <id> -w <ws> --evidence '<command + result>'
+```
+
+Done when a worker with no other context could finish the task from
+the brief and the notes it points at, and could tell when it is done.

package/skills/mu/recipes/codemode-driver.md

@@ -0,0 +1,54 @@
+# Codemode driver
+
+Use when a pi orchestrator with the `codemode` tool runs a recipe with
+many parallel units, and one tool call per spawn, send, and wait is
+slow. A script can issue those calls in parallel. It stays a driver:
+the plan, the state, and the results live in the DB.
+
+## The rule
+
+**Delete the script mid-run and nothing is lost.** That holds when:
+
+- The script calls only `mu` verbs, through `tools.bash`. It reads
+  state with `mu state --json` / `mu task notes`, never from its own
+  variables across calls.
+- Every task it dispatches exists in the DAG before the script starts.
+  The script adds no tasks the orchestrator has not planned, except the
+  ones a recipe step names (the next round, a `fix_` task).
+- `store()` / `load()` hold nothing a re-run needs. The DAG is the
+  cursor.
+- The script's source goes into the log before it runs:
+  `mu log -w <ws> --kind driver '<what it does, which tasks>'`.
+
+## Shape
+
+```js
+// @options: {"timeout_ms": 1800000}
+const ws = "audit";
+const sh = async (c) => {
+  const r = await tools.bash({ command: c });
+  if (r.exit_code !== 0) throw new Error(`${c}: ${r.output}`);
+  return r.output;
+};
+const ready = JSON.parse(await sh(`mu task next -w ${ws} -n 0 --json`)).items;
+await Promise.allSettled(ready.slice(0, 4).map(async (t, i) => {
+  const w = `worker-${i + 1}`;
+  await sh(`mu task claim ${t.name} -w ${ws} --for ${w} --evidence 'driver dispatch'`);
+  await sh(`mu agent send ${w} -w ${ws} --fresh 'Work on ${t.name}. Read: mu task notes ${t.name} -w ${ws}'`);
+}));
+const wait = await tools.bash({ command: `mu task wait -w ${ws} ${ready.slice(0, 4).map((t) => t.name).join(" ")} --first --on-stall exit --json` });
+return wait.output;
+```
+
+Check field names against `--json` output before relying on them; the
+script above is a shape, not an API.
+
+## Traps
+
+- **One wave per script.** A script that loops forever hides progress
+  from you and from the human. Dispatch, wait for the first close,
+  return; merge and verify outside the script, then run it again.
+- **A script timeout cancels the waits, not the workers.** Workers keep
+  running and their tasks stay claimed. Re-read `mu state` and carry on.
+- **Exit codes are data.** `mu task wait` exit 7 means a worker needs
+  you; return it to the model instead of retrying.

package/skills/mu/recipes/deep-research.md

@@ -0,0 +1,52 @@
+# Deep research
+
+Use when a question needs more sources than one context can read and
+checking them against each other: how a library or protocol behaves,
+what changed between versions, how competitors solve a problem, whether
+a claim in a draft holds. This is [refute](refute.md) applied to
+sources. Workers need a web search tool (pi's `brave_search`, or
+`curl` on docs) or the code they research.
+
+## Steps
+
+1. **Write the question and the bar** on an umbrella task: the exact
+   question, what a good answer contains (a recommendation, a
+   comparison table, a yes/no with conditions), and how fresh sources
+   must be.
+2. **Split by angle**, one search task per angle: official docs,
+   changelogs and release notes, issue trackers, independent write-ups,
+   the code itself. Each searcher reads, fetches, and writes claims to
+   its note, one per line:
+
+   ```text
+   CLAIM: c4 "Node 22 enables the permission model by default" SOURCE: <url> QUOTE: "<exact words>"
+   ```
+
+   A claim without a source and a quote is not a claim. Searchers can
+   run on a cheap model.
+3. **Dedupe claims** in one task: merge the same fact from several
+   sources (keep every source), and flag claims that contradict each
+   other.
+4. **One check task per claim** that the answer depends on. The checker
+   gets the claim and its sources, not the searcher's reasoning, fetches
+   the source itself, and tries to break the claim: is the quote there,
+   does it say that, is it current, does another source disagree? It
+   ends with `VERDICT: c4 CONFIRMED | REFUTED | UNVERIFIED <evidence>`.
+   For contradicted claims, one checker per side.
+5. **Synthesize** in a task blocked by every check: answer the question
+   from confirmed claims only, each with its source URL. List
+   unverified claims separately. Note what the sources disagree on and
+   which side the evidence favours.
+
+Done when every claim the answer uses has a `CONFIRMED` verdict line,
+every sentence of fact in the report cites a URL, and the report meets
+the bar from step 1.
+
+## Traps
+
+- **A fetch failure is UNVERIFIED, not REFUTED.** Rate limits and
+  paywalls block checkers; say so, do not drop the claim silently.
+- **Secondary sources copy each other.** Three blog posts repeating one
+  changelog are one source. Prefer the primary source in the dedupe.
+- **Version drift.** A claim true for v2 can be false for v3. Checkers
+  confirm the version the question asks about.

package/skills/mu/recipes/fan-out.md

@@ -0,0 +1,36 @@
+# Fan-out
+
+Use when the same treatment applies to many units: files, call sites,
+failing tests, findings, modules. One context holding 50 units drops
+some and calls the job done; one task per unit cannot.
+
+## Steps
+
+1. **Enumerate first, as its own task.** A scout lists the units and
+   writes them to the umbrella's note, one per line. The list is done
+   when it matches a command the scout ran (`rg -l`, a test listing),
+   not when it looks complete. Record the command and the count.
+2. **One task per unit**, blocked into an umbrella:
+
+   ```bash
+   mu task add sweep -w <ws> -t "Sweep: <goal>" -i 60 -e 1 --note 'UNITS: 37 (rg -l ... | wc -l)'
+   mu task add sweep_auth_ts -w <ws> -t "Sweep src/auth.ts" -i 50 -e 0.2
+   mu task block sweep -w <ws> --by sweep_auth_ts
+   ```
+
+   Put the shared brief and acceptance criteria on the umbrella; each
+   unit task's note holds only what differs.
+3. **Cap concurrency.** Spawn at most one agent per ready track, and no
+   more than the machine can build and test at once. Tell workers to
+   avoid repo-wide commands so more can run.
+4. **Pipeline.** Dispatch, wait `--first`, merge, dispatch the next unit
+   to the freed worker with `--fresh`. Units that touch the same files
+   go on one track (see [waves](waves.md)).
+5. **Review per unit** when a wrong unit is costly: add a review task
+   per unit ([adversarial-review](adversarial-review.md)).
+6. **Synthesize** when the output is a report, not commits: a final
+   task blocked by every unit reads their notes and writes one result.
+   It reads notes, not transcripts.
+
+Done when `mu task close sweep --if-ready` closes the umbrella: every
+unit is closed, and the closed count matches the step 1 count.

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

@@ -0,0 +1,40 @@
+# Hypothesis panel
+
+Use for root-cause work: a flaky test, an intermittent bug, a metric
+that moved. One agent that forms a theory then tests its own theory
+finds evidence for it. Separate agents, each given different evidence,
+form independent theories; separate agents then try to kill them.
+
+## Steps
+
+1. **Write the symptom** on the umbrella: what happens, how often, the
+   repro command, and what would count as fixed.
+2. **One hypothesis task per evidence source**: logs, the code path,
+   recent commits, data, environment. Each agent sees only its source,
+   so the theories do not anchor on each other. Each ends with:
+
+   ```text
+   HYPOTHESIS: h2 <cause>
+   PREDICTS: <an observation that is true if h2 is the cause, false otherwise>
+   ```
+
+3. **One test task per hypothesis**, in its own workspace. The tester
+   builds the experiment that would kill the hypothesis (force the race,
+   revert the commit, feed the data) and reports
+   `VERDICT: h2 SURVIVES | KILLED <evidence>`.
+4. **If one survives**, add a fix task for it, then a review task
+   ([adversarial-review](adversarial-review.md)). The fix is accepted
+   only if the step 1 repro stops reproducing.
+5. **If none survives**, start another round
+   ([loop-until-done](loop-until-done.md)): the new hypothesis tasks get
+   the killed hypotheses and their evidence as input.
+
+Done when a fix closed `ACCEPT` and the repro from step 1 no longer
+reproduces at the rate step 1 recorded.
+
+## Traps
+
+- **Two survivors** usually means the experiments were too weak. Design
+  one experiment that separates them before you fix either.
+- **Flaky repros need counts.** "Passed once" proves nothing for a 1 in
+  50 failure. Put the run count in step 1.

package/skills/mu/recipes/long-run.md

@@ -0,0 +1,20 @@
+# Long runs
+
+Use when a task or proof runs for hours, crosses context compaction,
+or may hit flakes.
+
+1. **Fix done first.** Before dispatch, write the completion criterion
+   into the task note: the checks, how many runs must agree, the
+   allowed variance. A worker that finds the bar in the note stops at
+   the bar, not at the first green.
+2. **Split into independent units.** Shard a long proof into tasks
+   that run in parallel, so one flake restarts only its unit. Each unit
+   carries its own criterion.
+3. **Keep state in the DB.** Progress lives in task notes, not in the
+   orchestrator's context. After a compaction, `mu state` and
+   `mu task notes <id>` are the whole picture.
+4. **Accept evidence, not close notes.** Re-run the key measurement
+   from a clean checkout before you count a unit as done.
+
+Done when every unit is `CLOSED/done` and the criterion from step 1
+holds on the merged tree.

package/skills/mu/recipes/loop-until-done.md

@@ -0,0 +1,38 @@
+# Loop until done
+
+Use when the amount of work is unknown: fix type errors until clean,
+find flaky tests until none are new, search until nothing new turns up.
+A fixed number of passes stops too early or runs too long; a stop rule
+written down first does neither.
+
+## Steps
+
+1. **Write the stop rule** on the umbrella before the first round. It
+   names a command and a condition, plus a no-progress rule:
+
+   ```text
+   STOP: `npx tsc --noEmit` exits 0
+   NO-PROGRESS: two rounds in a row reduce the error count by zero
+   ```
+
+2. **Each round is a task**, blocked by the previous one:
+   `round_1`, `round_2`, .... Add the next round only when the current
+   one closes; never pre-create rounds.
+3. **Each round ends with its measurement** in the note:
+   `MEASURE: 14 errors (was 31)`, or `NEW: 0 flaky tests`.
+4. **After each round, check the rule** yourself, from the measurement
+   command, not from the worker's note.
+   - Rule met: close the umbrella.
+   - No progress: stop the loop and decide. Change the approach, split
+     the work, or park the umbrella with
+     `mu task park <umbrella> --why '<what is stuck>'` and tell the human.
+   - Otherwise: add the next round and dispatch it.
+
+Done when the stop rule holds on the merged tree, run by you.
+
+## Traps
+
+- **A round that only reports is not progress.** Each round must change
+  something (fix, new search slice) or produce a new measurement.
+- **Moving goalposts.** Edit the stop rule only with a note saying why;
+  the old rule stays in the history.