@mu-crew/mu 3.2.0 → 3.3.0

package/skills/mu/SKILL.md

@@ -14,25 +14,19 @@ not in `--help` do not exist.
 
 ## Output + JSON shapes
 
-Default output: textual card on stdout plus a `Next:` block. Read
-both. `--json` exists on every verb:
-- Success: one stdout object.
-- Collection reads (`task list`, `workspace commits`, ...): `{items: T[], count: number}`.
-- Singletons keep named fields.
-- `mu sql --json`: bare array rows.
-- `mu log --tail`: NDJSON (one object per line).
-- Errors: `{error,message,nextSteps,exitCode}` on stderr.
-- Validation errors also include structured `usage`.
-- **`nextSteps` survives in JSON.**
+Default output is a card on stdout plus a `Next:` block. Read both.
+Every verb takes `--json`: one stdout object; collections are
+`{items, count}`; `mu sql --json` is bare rows; `mu log --tail` is
+NDJSON. Errors are `{error,message,nextSteps,exitCode}` on stderr
+(validation errors add `usage`). **`nextSteps` survives in JSON.**
 
 ## Vocabulary
 
-- **workstream** — unit of organization; one **mux session** named
-  `mu-<name>` (a tmux session, or a herdr workspace).
+- **workstream** — one **mux session** `mu-<name>` (tmux session or
+  herdr workspace) and one DB partition.
 - **agent** — named worker in a pane (you may be one).
-- **mux** — the multiplexer mu drives: tmux, or herdr. One per
-  invocation. `mu doctor` names the active one; `MU_MUX` forces it.
-  Spawn, send, and read work on both. `mu agent kick` is Linux-only on herdr.
+- **mux** — tmux or herdr, one per invocation. `mu doctor` names it;
+  `MU_MUX` forces it. `mu agent kick` is Linux-only on herdr.
 - **control socket (ctl)** — how mu drives a pi agent: the mu pi
   extension (`mu link pi`) serves exact send, state, wait and abort
   inside pi's own TUI. `ctl missing|refused` means it does not answer.
@@ -42,8 +36,8 @@ both. `--json` exists on every verb:
   Any `CLOSED/*` satisfies `--blocked-by`.
 - **claim / release** — atomic take/clear of `tasks.owner`.
 - **note** — append-only task context; survives sessions.
-- **track** — independent DAG subtree; don't spawn more agents than
-  ready tracks.
+- **track** — independent DAG subtree; spawn at most one agent per
+  ready track.
 - **workspace** — per-agent VCS copy under
   `<state-dir>/workspaces/<workstream>/<agent>/`.
 
@@ -55,82 +49,59 @@ or inspection.
 
 ### Off-the-cuff helpers (`scratch`)
 
-The reserved `scratch` workstream holds helpers that need no task DAG; it
-auto-creates on spawn. `mu_delegate` (installed by `mu link pi`) is its tool
-form for one answer back; the CLI form is spawn + send + `mu agent wait --json`
-(`lastText`).
+For one-shot work inside pi, call `mu_delegate` (installed by `mu link pi`).
+Outside pi: spawn into the reserved `scratch` workstream (no task DAG,
+auto-created), `send --fresh`, then `mu agent wait --json` (`lastText`).
 
-- `mu agent wait <name> --first` waits for busy → idle; 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.
+- `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 (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.
 
-A helper stuck at `needs_input` right after spawn likely hit pi's project trust
-prompt: add `--approve` to `MU_<CLI>_COMMAND` rather than overriding it with
-`--command`.
-
-Move off `scratch` when work gains dependencies or review gates.
+A helper stuck at `needs_input` right after spawn likely hit pi's
+project trust prompt: add `--approve` to `MU_<CLI>_COMMAND`. Move off
+`scratch` when work gains dependencies or review gates.
 
 ## Mental model
 
 ### Workstreams, DAGs, tracks
 
-One workstream is one mux session and DB partition. Its task DAG has one edge:
-`mu task block A --by B` means **B blocks A**. Parallel tracks sharing a
-prerequisite collapse, preventing two agents from taking the same dependency.
+The DAG has one edge: `mu task block A --by B` means **B blocks A**.
+Tracks sharing a prerequisite collapse into one, so two agents never
+take the same dependency.
 
 ### Workspaces prevent trampling
 
-If an agent may edit/build/test while another agent is active in the
-same repo, spawn with `--workspace`. Keep the main checkout for
-orchestration: two builds in one checkout corrupt each other.
-
-Workspaces auto-detect jj/sl/git; non-VCS uses `cp -a`. They are
-auto-freed on `mu agent close` **iff clean**: no uncommitted changes
-and no commits since fork. Non-clean close fails with
-`WorkspacePreservedError`; then use `mu workspace free <agent>` or
-`mu agent close <agent> --discard-workspace` (lossy).
+If an agent may edit, build, or test while another is active in the same
+repo, spawn with `--workspace`. Two builds in one checkout corrupt each
+other; keep the main checkout for orchestration.
 
-Between waves, `mu workspace refresh <agent>` rebases onto fresh main without
-killing LLM context. Claim/send warn at ≥10 commits behind; scripts can make
-that a refusal with `--strict-staleness`.
+Workspaces auto-detect jj, sl, or git (else `cp -a`). `mu agent close`
+frees one **only if clean** (no uncommitted changes, no commits since
+fork); otherwise it fails with `WorkspacePreservedError`. Then use
+`mu workspace free <agent>` or `--discard-workspace` (lossy).
+Between waves, `mu workspace refresh <agent>` rebases onto main and
+keeps LLM context. Claim and send warn at ≥10 commits behind
+(`--strict-staleness` refuses).
 
 ### Remote agents
 
-Agents can run on another machine: the PANE is local, the PROCESS is
-remote (`--command 'ssh <host> -t "..."'`), so `send`, `read`, and the
-reaper keep working unchanged. A pi agent's control socket is forwarded
-over that ssh (`mu agent remote-env`). **One orchestrator
-DB; panes may be remote** — never run a second mu on the host, since
-`tasks.owner_id` is an FK into the machine-local `agents` table and a
-remote mu could not claim your tasks anyway. 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 and run
-the claim's one-shot `Next:` command.** Three more costly traps:
-- **On a session-capped host, route long commands and silent-failure
-  polls through [mule](https://github.com/mu-crew/mule).** A refused
-  bare `rev-parse` can return an empty sha that looks like progress;
-  batch all workers in one `--max-secs`-bounded mule job.
-- **`mule` exit 3 is a HANDBACK** — no ssh master, and opening one can
-  need a human to touch a hardware key. Ask the operator; never retry,
-  never run `ssh -MNf` yourself, never fall back to `ssh <host> <cmd>`.
-- **Exit 4 and 6 mean wait again; 5 means never.** Neither says the work
-  failed.
+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.
 
 ### Agent names
 
-Use roles: `worker-1`, `worker-2`, `reviewer-1`, `scout-1`,
-`auditor-1`, `planner-1`. Smallest unused suffix. Avoid human names.
+Use roles with the smallest unused suffix: `worker-1`, `reviewer-1`,
+`scout-1`, `auditor-1`, `planner-1`. No human names.
 
 ### Task note contract
 
-End every delegated task with a note containing the applicable
-fields:
+End every delegated task with a note holding the applicable fields:
 
 ```text
 FILES:    paths inspected/changed (line ranges if precise)
@@ -143,102 +114,39 @@ ODDITIES: weird things not acted on
 ```
 
 Then close with grounding:
-
-```bash
-mu task close <id> -w <ws> --evidence "tests pass: cargo test exit 0"
-```
-
-Future agents can reconstruct context via `mu task notes <id>`.
-
-## 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; include initial context with
-   `--note 'REPRO: ...\nSCOPE: ...'` when the title alone is not
-   enough. Agent state is runtime observation; task ownership is durable and
-   waitable.
-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 onto main, verify the combined tree, then return control. Waiting on an
-  umbrella task hides partial progress; merging stale branches can restore
-  reverted code.
-- **Verify the merge, not the worker's rerun.** The worker tested against its
-  fork point; only the combination with moved main is new. This found three
-  integration breaks where rerunning worker suites found none. For remote work,
-  run the merged gate on the host with warm dependencies: 500s × 30 integrations
-  is four laptop-hours. Keep platform-sensitive checks and the final release gate
-  local; macOS `ps` once exposed a bug Linux could not.
-- **Push only from a green gate.** Script the gate so `git push` is its last
-  line under `set -e`; a chain that printed a failure and pushed anyway put a red
-  commit on main. Check the gate runs what it claims: a randomized test gated on
-  an env var passed with zero cases.
-- **Dispatch from current main.** Reset the worker's worktree to main before each
-  task. Stale bases caused four merges that conflicted or broke tests after
-  passing in the worker.
-- **Accept evidence, not close notes.** Re-run the key measurement from a clean
-  checkout. Close notes have claimed unpushed commits and reported numbers from
-  a half-edited clone.
-- **Freeze only what conflicts.** While one task owns shared files, give idle
-  workers tasks that avoid them; a blanket freeze idled four of five workers for
-  a day.
-- **Fix done before a long run.** Put the completion criterion in the task note
-  first: which checks, how many agreeing runs, what may differ. Without it the
-  target moves with every run.
-- **Split long proofs into independent units**, sharded and in parallel, so a
-  unit that passes stays passed and one flake restarts only its own unit.
-  Workers poll background jobs every few minutes, not hourly.
-- Bucket waves by file cluster, not severity; two agents editing one file
-  conflict. Refresh workspaces between waves.
-- Cross-workstream wait/claim uses qualified refs. The owner stays in its own
-  workstream; only task ownership crosses.
-- For an idle worker, read the pane to learn why it stopped, 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.
+`mu task close <id> -w <ws> --evidence "tests pass: cargo test exit 0"`.
+
+## 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 by default; `--yes` commits. It writes
-  TOMBSTONE ops, so history survives and `mu undo <group> --yes` reverses the
-  deletions — do NOT `mu db backup` first, the log IS the backup.
-  `workstream list --torn-down` replays past teardowns with the group id to
-  undo, newest first, marking ones already recreated.
-- **`agent wait <names...> --first`** blocks until an agent stops working
-  (busy → anything else) — the task-less counterpart to `mu task wait`, for
-  helpers that own no task. Use it instead of a `sleep` loop. Exit 0 met,
-  5 timeout, 6 pane died.
+- **`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
@@ -247,49 +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 undoable actions with group ids; `<group>` previews;
-  `<group> --yes` applies. It emits INVERSE ops for that one group, so it
-  touches nothing else, and the undo is itself an op — REDO is
-  `mu undo <that group> --yes`. Refuses with exit 4 if a later action changed
-  the same fields (`--force` discards that newer work). Rows only: killed panes
-  and freed workspace dirs do not come back. No snapshots, no `--to`.
-- **`mu rebuild <file>`** writes a NEW DB from the ops log. Agents and
-  workspaces are absent because they have no captured ops; re-spawn after swap.
-- **`mu sql`** alone skips ambient sync, preserving no-surprise mutations.
-- **`mu db backup`** is a convenient copy; real recovery is `mu rebuild`.
-- **Sync (laptop ↔ devserver):** `export MU_SYNC_DIR=$HOME/Sync/mu` on each
-  machine pointing at a shared folder (Syncthing recommended). Every command
-  then flushes your ops and ingests peers' — ambient, no daemon — so a bare
-  `mu task list` on the other box already shows what you added here. Merge is
-  per-FIELD, so two machines editing different fields of one task both keep
-  their edit. `mu sync` bare reports peer status plus a copy-pasteable rsync
-  line; mu never runs ssh/scp/rsync itself. `--from <peer-mu.db>` reads a
-  peer's ops directly; `--repair <peer>` re-reads from zero and is always safe
-  (ingest is idempotent).
-  **NEVER put `MU_DB_PATH` inside `MU_SYNC_DIR`** — it corrupts the DB and
-  `mu doctor` hard-fails. Agent/workspace state and task OWNERSHIP are
-  machine-local and never travel.
-- **`mu doctor`** runs fast checks; `--deep` rebuilds the log into a temp DB and
-  diffs it field-by-field. DRIFT means the log and the tables disagree, which
-  breaks undo and sync at once (exit 5, naming table, key and field). It is a
-  capture bug, not operator error: back up and report it, do NOT reflexively
-  rebuild — if capture missed a mutation, the live rows hold the real work.
-  The `disk` section reconciles state-dir against DB both ways and is
-  **report-only**: `ws-rows` is a row whose directory is gone (nothing else
-  reports it), `ws-dirs` blocks the next `--workspace` spawn, and an orphan dir
-  may hold the only copy of uncommitted work — which is why mu prints the
-  cleanup command and runs none of them. `--disk` adds per-checkout byte usage.
-
-## `mu task wait`
-
-Use `--first --on-stall exit`: `--first` populates `.firing`, and
-`--on-stall exit` prevents unattended waits from polling forever when a worker
-needs attention. Exit 6 means a dead pane; exit 7 means the owner sat in
-`needs_input`. Read that pane (`mu agent read <owner>`) before acting: the
-worker may be waiting on an answer from you, not merely forgetting to close.
-Answer it — questions are cheaper than rework. For remote workers, see
-[REMOTE_WORKERS.md](REMOTE_WORKERS.md) before choosing timeout or stall
-handling.
+- **`mu sql`** skips ambient sync.
+- **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
 
@@ -301,63 +172,63 @@ export MU_PI_COMMAND="pi --model sonnet:medium"
 mu agent spawn a --cli pi_big   # uses $MU_PI_BIG_COMMAND
 ```
 
-Convention: `pi_mini` / `pi` / `pi_big`. Use mini for probing,
-modest for build/edit/refactor, big for design/review/incidents.
-Discover model strings with `pi --list-models [fuzzy-search]`.
+Convention: `pi_mini` for probing, `pi` for build and refactor,
+`pi_big` for design, review, and incidents. List models with
+`pi --list-models [search]`.
 
 ## Reaper and agent state
 
-If an agent pane dies, or `mu agent close` kills it mid-task, owned
-IN_PROGRESS tasks revert to OPEN with a `[reaper]` note and `task
-reap` op. No manual release after crashes.
-
-pi agents report state through the control socket; other CLIs through
-[murmur](https://github.com/mu-crew/murmur) on tmux or herdr on herdr.
-`unknown` means no state source; `mu doctor` says why. pi agents need
-no murmur. See [REMOTE_WORKERS.md](REMOTE_WORKERS.md) § mu and murmur.
-
-For high-stakes decisions:
-
-```bash
-mu agent read worker-1 -n 100
-mu log -w <ws> --tail
-mu task notes <id>
-```
-
-## In-pane worker loop
-
-`$MU_AGENT_NAME`, injected at spawn, resolves identity; the pane title
-is the fallback that adopted panes need. Env-first means this loop is
-identical whichever multiplexer you are in — you never need to know.
-
-- Worker pane: spawned/adopted by mu; bare `mu task claim <id>` works.
-- Orchestrator pane: not registered; bare `claim` errors with next
-  steps: `--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
-```
+If an agent pane dies, or `mu agent close` kills it mid-task, its
+IN_PROGRESS tasks revert to OPEN with a `[reaper]` note. No manual
+release after crashes.
 
-Skipping close makes the orchestrator's wait hang. Won't do it:
-`close --as wontfix --why "..."`.
+pi agents report state through the control socket and need no murmur.
+Other CLIs report through [murmur](https://github.com/mu-crew/murmur) on
+tmux, or herdr on herdr. `unknown` means no state source; `mu doctor`
+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>`.
 
-## Follow-on prompts
+## You are a worker
 
-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
 
-Task ownership outranks runtime agent state. Coordinate through task notes and the
-activity log. Keep edges within one workstream, role-name agents, and reserve
-the `mu_` task-id prefix. Give workers bounded paths and commands.
+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
 

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.