@mu-crew/mu 3.13.2 → 4.0.0

package/skills/mu/SKILL.md

@@ -1,310 +1,79 @@
 ---
 name: mu
 description: >-
-  Fresh-context delegates (mu's counterpart to hidden subagents) and crews
-  in tmux/herdr panes. Check before you
-  commit: before acting on a claim, root cause, plan, fix or brief, have a
-  `mu_delegate` call refute it. Also for a fresh delegate's second look at
-  your own work or diff; parallel read-only research, investigation or fan-out
-  over files; background helpers (watchers, soak runs, agents you keep talking
-  to); persistent crews with a task graph, review gates and merges. Outside
-  pi, delegate through the reserved `scratch` workstream.
+  Fresh-context delegates and crews in tmux/herdr panes. Check before you
+  commit: have a `mu_delegate` call refute a claim, root cause, plan, fix or
+  brief before you act on it. Also parallel read-only research, fan-out,
+  background helpers, and persistent crews with a task DAG, review gates and
+  merges. Outside pi, delegate through the `scratch` workstream. Never write
+  mu's DB (no `sqlite3`, no raw SQL writes): read it with `mu sql "<SELECT>"`,
+  change it with a verb.
 ---
 
-# mu — Multi-agent orchestration
+# mu
 
-`mu` manages long-lived AI agents in multiplexer panes (tmux or
-herdr), coordinated by a SQLite task DAG at
-`<XDG_STATE_HOME or ~/.local/state>/mu/mu.db`.
+Agents in tmux/herdr panes, coordinated by a SQLite task DAG. **`mu --help` and
+`mu <verb> --help` outrank this skill**; a verb they omit does not exist. A verb takes
+`-w <workstream>` only if its `--help` lists it (`doctor`, `sync`, `delegates
+show` do not); workers get it.
 
-**Trust `mu --help` / `mu <verb> --help` over this skill.** Verbs
-not in `--help` do not exist.
-
-## Output + JSON shapes
-
-Default output is a card on stdout plus a `Next:` block. Read both.
-Every verb takes `--json`: one stdout object; collections are
-`{items, count}`, except `mu agent list` (`{agents, orphans}`); `mu sql --json` is bare rows; `mu log --tail` is
-NDJSON; `mu log` writes print text even with `--json`. Errors are `{error,message,nextSteps,exitCode}` on stderr
-(validation errors add `usage`). **`nextSteps` survives in JSON.**
-
-## Vocabulary
-
-- **workstream** — one **mux session** `mu-<name>` (tmux session or
-  herdr workspace) and one DB partition.
-- **agent** — named process in a pane (you may be one); a **worker** is an agent claiming tasks.
-- **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.
-- **task** — DAG node with mandatory `impact` (1–100) and
-  `effort_days`. Shown as status/substate: `OPEN/todo|parked|triage`,
-  `IN_PROGRESS/active`, `CLOSED/done|rejected|wontfix|duplicate|superseded`.
-  Any `CLOSED/*` satisfies `--blocked-by`.
-- **claim / release** — atomic take/clear of `tasks.owner`.
-- **note** — append-only task context; survives sessions.
-- **track** — tasks connected by `block` edges (`mu task block B --by A`
-  puts B on A's track). Spawn one agent per ready task, not per track:
-  an umbrella puts all its units on one track.
-- **workspace** — per-agent VCS copy under
-  `<state-dir>/workspaces/<workstream>/<agent>/`.
-
-Recipe words, the same in every recipe:
-
-- **umbrella** — the parent task of one job, blocked by every unit,
-  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).
-- **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.
-- **verdict** — a check's answer: `VERDICT: <id> CONFIRMED | REFUTED |
-  UNVERIFIED <one line>` plus `EVIDENCE:` lines (or ACCEPT | REJECT for
-  a review gate). REFUTED on a brief means it holds a false claim: rewrite it.
-- **stop rule** — the command and condition that end a loop, written on
-  the umbrella first ([loop-until-done](recipes/loop-until-done.md)).
-
-## When to use mu
-
-Use mu for persistent helpers, parallel work, dependencies, gated review, or
-work that must survive context compaction. Stay in one context for tiny edits
-or inspection.
-
-### Quick checks and off-the-cuff helpers (`scratch`)
-
-Before you act on a claim, root cause, plan, fix or brief, or to get a second
-look at your own work or diff, make a [delegate call](recipes/tasks-or-calls.md#delegate-call)
-that tries to refute it, on another model family ([models](recipes/models.md#checkers); briefs: see
-Orchestrator rules; many claims: [refute](recipes/refute.md)).
-
-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), as in
-[delegate call](recipes/tasks-or-calls.md#delegate-call). Recipes call either form a **delegate call**. A check judging a mu
-task lands its verdict there: `record: { task: "<ws>/<id>" }` on `mu_delegate`, a hand-written
-`REFUTER` note on the spawn path; with no task, skip both.
-
-- `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 pi helper showing `unknown (ctl missing)` right after spawn (spawn
-warns after 30 s) likely sits at pi's project trust prompt (through a
-wrapper whose argv0 is not `pi`/`pi-meta` it shows `needs_input`): add
-`--approve` to `MU_<CLI>_COMMAND`. Move off
-`scratch` when work gains dependencies or review gates.
-
-## Mental model
-
-### Workstreams, DAGs, tracks
-
-The DAG has one edge: `mu task block A --by B` means **B blocks A**.
-Tracks sharing a prerequisite collapse into one, so an umbrella every
-unit blocks makes the whole job one track. Parallelism is the ready
-set: tasks that edit the same files get a `block` edge between them,
-so only one is ready at a time.
-
-### Workspaces prevent trampling
-
-If an agent may edit, build, or test while another is active in the same
-repo, spawn with `--workspace` (`workspace: true` on `mu_delegate`).
-Two builds in one checkout corrupt each other; keep the main checkout
-for orchestration. Never make your own `git worktree`, `jj workspace`
-or copy for a local agent: mu cannot refresh, list, diff or free what
-it did not create, so it leaks. Remote agents are the exception
-([remote-workers](recipes/remote-workers.md)).
-
-Workspaces auto-detect jj, sl, or git (else `cp -a`). `mu agent close`
-frees one **only if clean**; otherwise it fails with
-`WorkspacePreservedError`. A `cp -a` copy is never clean. Cherry-pick what
-to keep, and pass `--discard-workspace` only to throw the rest away.
-Before each `--fresh` send, `mu workspace refresh <agent>` rebases onto
-main and keeps LLM context ([waves](recipes/waves.md) when workers share
-files). Claim and send warn at ≥10 commits behind
-(`--strict-staleness` refuses).
-
-### Remote agents
-
-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](https://github.com/mu-crew/mule) runs remote commands without
-holding an ssh channel; **`mule` exit 3 is a HANDBACK** to the operator
-(hardware-key touch): never retry or open `ssh -MNf` yourself.
-
-### Workstream names
-
-`<project>-<purpose>` (`hail-auth`), one per effort, torn down when it
-ships. Reviews nobody will track run as `scratch` delegates.
-
-### Agent 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 holding the applicable fields
-(write the brief that asks for it per [brief](recipes/brief.md)):
-
-```text
-FILES:    paths inspected/changed (line ranges if precise)
-COMMANDS: commands run + exit codes
-FINDINGS: what you observed
-DECISION: what you chose, and why
-NEXT:     follow-on tasks
-VERIFIED: tests/checks/output
-ODDITIES: weird things not acted on
-```
-
-Then close with grounding:
-`mu task close <id> -w <ws> --evidence "tests pass: cargo test exit 0"`.
+- **umbrella**: a job's parent task, blocked by every unit; holds brief, criteria, stop rule.
+- **finding**: an `OPEN/triage` task. **verdict**: `VERDICT: <id>
+  CONFIRMED|REFUTED|UNVERIFIED <line>` plus `EVIDENCE:`.
+- `mu task block A --by B`: B blocks A. Chain tasks sharing files.
 
 ## 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.
+**While workers run, keep driving.** Your turn ends only when everything you own
+is closed, or only a human can decide (scope, spend, irreversible or external
+action, hardware-key handback): record it with `mu human-needed -w <ws>
+"<reason>"`, then stop. A status summary is a `mu log` line, not a stopping
+point: one per wave, then back to waiting. An error never means a
+human is needed. Ending a turn mid-run stalls the 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 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 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
-  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`.
-  To redirect a busy pi now: `send --interrupt` (`--steer` waits for
-  the running tool).
-- **Send, don't note, a running worker**: it never sees new notes. The note is the durable copy
-  ([how to send](recipes/orchestrator-loop.md#sending)).
-- **Refute a brief claiming a cause, fix, threshold or code fact** before dispatch:
-  one `record`ed refuter call; rewrite on REFUTED. Others get a `REFUTE-EXEMPT: <why>` note.
-- **Checks are calls, not tasks.** Refuters, claim checkers, judges and
-  skeptics are [delegate calls](recipes/tasks-or-calls.md#delegate-call)
-  (`mu_delegate`, or a `scratch` spawn without it), all issued in one
-  turn. Refuters and claim checkers pass `record` (or hand-write the
-  `REFUTER` note) to land the verdict on the task; judges report
-  `WINNER:`. `MU_DELEGATE_MAX` (16) run at once; the rest queue.
-- **Leave no scratch files.** With tasks, briefs and answers live in
-  mu (task notes, `mu log`); for pure delegate calls, pass them through
-  stdin (`-` plus a quoted heredoc). A job that needs files
-  (diffs, a brief shared by a panel, reviewer outputs) keeps them in
-  one `mktemp -d` directory and `rm -rf`s it once the results are in
-  notes or your answer, before the turn ends.
-- **Findings are tasks.** A reviewer's or auditor's findings become
-  `mu task add --triage` tasks blocking the review, decided with
-  `mu task accept` or `close --as rejected|duplicate`. A review nobody
-  will track (someone's PR, a doc) runs as delegates instead. Rules:
-  [recipes/findings.md](recipes/findings.md).
-
-## CLI gotchas
-
-- **`task close --as rejected|wontfix --why ...`** unblocks dependents
-  (listed in the output). `rejected` = the claim is false; `wontfix` =
-  true, not worth doing. To keep dependents waiting, `task park --why` instead.
-- **For waits use `task wait`, not `log --tail`.** `mu log --kind <k>`
-  entries are your own durable state (a ledger); `--intent` filters what
-  mu recorded.
-- **Prose in notes, prompts, `--why` or `--evidence`**: an apostrophe
-  ends `'...'`; use a quoted heredoc ([brief](recipes/brief.md#quoting)).
-- **`mu sql`** does not pull synced ops; run any other mu command first.
-- **Never put `MU_DB_PATH` inside `MU_SYNC_DIR`**: it corrupts the DB.
-- Before undo, rebuild, teardown (dry-run without `--yes`), sync setup,
-  a `doctor --deep` DRIFT, or `doctor` cleanup output, read
-  [recipes/recovery.md](recipes/recovery.md).
-
-## Models and thinking effort
-
-mu passes the model through; you pick it. Before you choose one for a
-spawn or a delegate call, read [recipes/models.md](recipes/models.md):
-tiers, which roles need which, and local models as a last resort.
-
-- `mu_delegate` takes `model`; a spawn takes `--command "pi --model <id>"`.
-- A checker (reviewer, refuter, judge, auditor) runs at the author's tier
-  or higher, from another family when one exists. A delegate with no
-  `model` runs the cli's default model; pass `model` when it matters.
-
-## Reaper and agent state
-
-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.
-
-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 you merge, close `--as rejected`, abort, or tear down, read the pane
-(`mu agent read worker-1 -n 100`), `mu log -w <ws> --tail`, and
-`mu task notes <id>`.
-
-## You are a worker
-
-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 agent state. Coordinate through task notes and
-the ops log (`mu log`). Keep edges within one workstream. Give workers
-bounded paths and commands.
+Read [orchestrator-loop](recipes/orchestrator-loop.md) before you dispatch. Always:
+
+- **Claim before work is sent.** `agent spawn --task <id> --send ...` does both.
+- **Wait with `mu wait`, never `sleep` loops** (exits:
+  [orchestrator-loop](recipes/orchestrator-loop.md)).
+- **A send that timed out is unknown, never resent**: `mu agent check <a> <msgId>`.
+- **New work to pi: `send --fresh`.** A running worker never sees a note: send
+  ([modes](recipes/orchestrator-loop.md#sending)).
+- **`unknown` is not dead.** Read the pane and `mu doctor` first.
+- **Only `CLOSED/done` ships.** Verify the merge.
+- **Checks are calls, not tasks** ([tasks-or-calls](recipes/tasks-or-calls.md)).
+  Before you act on a claim, cause, plan, fix or brief, have a recorded call
+  refute it; rewrite on REFUTED.
+- **Findings are tasks** ([findings](recipes/findings.md)); each shipping unit gets a
+  [review gate](recipes/adversarial-review.md).
+- **Stop rule on the umbrella first.**
+- **`course check due` stops dispatch**: finish merging, then
+  [course-correct](recipes/course-correct.md) to its `mu human-needed`.
+- **Edit or build: `--worktree`.** Never make your own.
+
+## Gotchas
+
+- `close --as rejected|wontfix --why` unblocks dependents; `park --why` keeps them waiting.
+- Prose goes through `-` and a quoted heredoc ([brief](recipes/brief.md)).
+- Teardown, rebuild, sync, `doctor` DRIFT: [recovery](recipes/recovery.md) first.
+- Claimed for you: [worker](recipes/worker.md). Remote host:
+  [remote-workers](recipes/remote-workers.md).
 
 ## 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 |
+| [orchestrator-loop](recipes/orchestrator-loop.md) | you dispatch and merge |
+| [brief](recipes/brief.md) | you write what a worker reads |
+| [tasks-or-calls](recipes/tasks-or-calls.md) | a step spawns an agent |
+| [findings](recipes/findings.md) | a check reports problems |
+| [adversarial-review](recipes/adversarial-review.md) | a unit needs a gate |
+| [test-health](recipes/test-health.md) | you set gates or verify a merge |
+| [models](recipes/models.md) | you pick a model |
+| [remote-workers](recipes/remote-workers.md) | an agent runs on another host |
+| [recovery](recipes/recovery.md) | teardown, rebuild, sync |
 | [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 |
-| [long-run](recipes/long-run.md) | a task or proof runs for hours, or must survive flakes |
-| [drift-audit](recipes/drift-audit.md) | hours into a long run, after a batch, compaction or resume, before a stop rule |
-| [watcher](recipes/watcher.md) | a helper polls a PR, CI, or log for change |
-| [findings](recipes/findings.md) | any review, audit, or check reports problems: where they live, how they are triaged |
-| [models](recipes/models.md) | you pick a model for a spawn or delegate call |
-| [tasks-or-calls](recipes/tasks-or-calls.md) | a recipe step spawns an agent: DAG task or delegate call |
-| [adversarial-review](recipes/adversarial-review.md) | gate each unit you dispatch before it merges (a review task per unit) |
-| [fan-out](recipes/fan-out.md) | a sweep or migration: the same change over many files or call sites |
-| [refute](recipes/refute.md) | you start an audit, bug hunt, or fact-check |
-| [hypothesis-panel](recipes/hypothesis-panel.md) | debugging: "why does X", a regression, a flaky test, an 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) | fix until a check is clean (tsc, lint, tests), or search until nothing new |
-| [backlog-triage](recipes/backlog-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) | code review of a PR, branch, or diff |
-| [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) | you have the `codemode` tool and one step dispatches many workers or delegate calls |
-
-## See also
-
-- `mu --help`, `mu <verb> --help` — canonical CLI reference.
+| [course-correct](recipes/course-correct.md) | a `course check due` hint, or a human asks |
+| [move](recipes/move.md) | a human asks to move a 3.x workstream |

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

@@ -1,111 +1,20 @@
 # Adversarial review
 
-Use when a unit of work must be checked by someone other than its
-author before it counts: a unit that produces commits (a fix, a feature).
-Checking a finding or claim is a delegate call
-([findings § Triage](findings.md#triage), [refute](refute.md)). 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.
+Use when a unit that produces commits must be checked by someone other than its author before it counts. Checking a claim is a delegate call ([findings](findings.md)).
 
-The review is a task in the DAG, not a step inside the worker's
-session. Its verdict, its evidence, and every finding it makes stay in the
-DB: each is a finding task ([findings](findings.md)). For a one-off
-check outside any workstream, one
-[delegate call](tasks-or-calls.md#delegate-call) is enough; to review a
-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: 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:**
+1. **Criteria first**, on the work task: requirements, risky behaviour needing coverage, files that must not change.
+2. **Gate**, 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 findings, not style.'
+   mu task add review_x -w <ws> -t "Review x" --blocked-by x --note 'ACCEPTANCE: see x notes. Refute; findings, 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, at the worker's tier or
-   higher and from another family ([models](models.md#checkers)). Give it the worker's workspace path
-   and commits read-only by instruction; it edits nothing.
-5. **Claim `review_x` for the reviewer**, send the brief (below), wait.
-6. **Act on the verdict:**
-   The review's state is the verdict: `CLOSED/done` for ACCEPT,
-   `CLOSED/rejected` for REJECT.
-   - `ACCEPT`: cherry-pick `x`'s commits and verify the merge.
-   - `REJECT`: the reviewer recorded each finding as an `OPEN/triage` task.
-     Add `review_x_2` and block it on every finding
-     (`mu task block review_x_2 --by <finding>`). Closing `review_x`
-     `--as rejected` unblocked its dependents, so re-block each task
-     downstream of `x` on `review_x_2`
-     (`mu task block <downstream> --by review_x_2`). Decide each
-     finding ([findings § Triage](findings.md#triage)), then
-     dispatch the accepted ones to the original worker, whose context
-     still holds the work. Repeat from step 4 when the findings are closed.
-     The DAG grows; nothing is rewritten.
-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 is `CLOSED/done` (ACCEPT), and the
-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, 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>), 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>'
-- If you could not check something (tool failed, no access), say
-  UNVERIFIED for it. Unverified is not a pass and not a fail.
-- Your only writes are `mu task add` (findings), the verdict note, and
-  the close; leave the workspace as you found it.
-
-Write the verdict note (FILES/COMMANDS/FINDINGS/VERIFIED), then close
-(long reasons: a heredoc variable, brief.md § Quoting):
-  ACCEPT: mu task close review_<x> --evidence "<key command>: <result>"
-  REJECT: mu task close review_<x> --as rejected \
-            --why "<n> findings: <id> (<why it fails, one clause>), ..."
-```
-
-mu adds each named finding's title to the REJECTED note.
-
-**Closing a review yourself** (you fixed a finding, or accept without a
-fresh reviewer): write the reviewer's note plus `COMMIT: <sha> fixes
-<finding>`, and name the check in `--evidence`. Not `one finding fixed
-by orchestrator`.
-
-## Traps
+3. **Fresh reviewer**, a checker per [models](models.md). Send the diff range, criteria and gate records, not the worker's reasoning. Its only writes are findings, the verdict note and the close.
+4. **Reviewer brief:** reproduce claimed failures; report unmet requirements, untested or broken behaviour, scope creep, unsupported evidence, each as a [finding](findings.md); `UNVERIFIED` for what it could not check. Close:
+   - ACCEPT: `mu task close review_x --evidence "<command it ran>: <result>"`
+   - REJECT: `mu task close review_x --as rejected --why "<n> findings: <ids>"`
+5. **Act.** ACCEPT: cherry-pick `x`, verify the merge ([orchestrator-loop](orchestrator-loop.md)). REJECT: rejecting unblocked `x`'s dependents; add `review_x_2` blocked by every finding, re-block them on it, decide the findings, send accepted ones to the original worker, then a fresh reviewer.
+6. **Two rejections of one unit end the loop**: split it, change the criteria, or ask the human.
 
-- **A reviewer that sees the author's reasoning agrees with it.** Send
-  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
-  rejected review: re-send it.
-- **A review with only UNVERIFIED items is not a REJECT.** A broken
-  environment or unreachable resource starts no coder round: report it
-  to the human.
-- **Reviewers drift into fixing.** A reviewer that edits the code is now
-  an author nobody reviews. The fix belongs to the finding tasks.
-- **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).
+- A review that ran no command is no verdict: re-send it.
+- Only `UNVERIFIED` items is a report to the human, not a REJECT.

package/skills/mu/recipes/brief.md

@@ -1,75 +1,35 @@
 # 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
-   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.
-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.
-7. **A brief that makes claims is refuted before dispatch** ([SKILL.md](../SKILL.md#orchestrator-rules)).
-
-## Shape
+Use when you write anything a worker reads: a task note, a `--fresh` prompt, a reviewer brief. The worker starts with no context.
 
 ```text
-Task <id> in <ws>. Workspace: <path>.
-Read: mu task notes <id> -w <ws>   (and the umbrella's, if any)
-
+Task <id> in <ws>. Read: mu task notes <id> -w <ws>
 GOAL: <one sentence>
 FILES: <paths it may change>
 DONE WHEN: <checkable, exhaustive criterion>
-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
+VERIFY: <exact targeted command>
+FINAL ACTION: git commit, then
+mu task close <id> -w <ws> --evidence "$v"   # command + result
 ```
 
-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.
+- **End on a criterion** both checkable and exhaustive: "every file in UNITS compiles under `npm run typecheck`", not "update the call sites".
+- **Share once.** Common context goes on the umbrella; each brief says `Read:` and holds only what differs.
+- **State the target, not the ban**: "edit only `src/auth/`".
+- **Ask for evidence**: commands run and exit codes.
+- **Refutation.** A brief naming a cause, fix, threshold or code fact needs the recorded refutation ([SKILL](../SKILL.md)); any other carries `REFUTE-EXEMPT: <why>`.
+- Never tell a worker to `cd`: its cwd is its worktree.
 
 ## Quoting
 
-Single quotes suit short text with no `'`. Prose (an apostrophe ends
-`'...'`; `"..."` expands `$` and backticks) goes through stdin with a
-quoted heredoc, stored verbatim:
+An apostrophe ends `'...'`. Pass prose through `-` and a quoted heredoc, stored verbatim:
 
 ```bash
 mu task note <id> -w <ws> - <<'EOF'
-it's fine: $HOME and `pwd` stay literal
+it's fine: $HOME stays literal
 EOF
 ```
 
-`mu task add --note -`, `--text -` and `mu agent send <a> -` read stdin
-the same way. `--why` and `--evidence` have no `-` form: capture the
-heredoc in a variable and double-quote it:
+`task add --note -` and `agent send <a> -` read stdin too. `--why` and `--evidence` do not; capture the text first:
 
 ```bash
 v=$(cat <<'EOF'
@@ -78,10 +38,3 @@ EOF
 )
 mu task close <id> -w <ws> --evidence "$v"
 ```
-
-Chain batched adds with `&&`, then `mu task list`, so one
-quoting failure cannot half-apply the batch unseen.
-
-Done when the brief has GOAL, FILES, DONE WHEN, VERIFY and the
-final-action block, every shared fact is a `Read:` pointer, and the task
-holds a refuter verdict or a `REFUTE-EXEMPT:` note.

package/skills/mu/recipes/course-correct.md

@@ -0,0 +1,23 @@
+# Course-correct a long job
+
+Use when a hint says `course check due: <n> closed since <date>`, or a human asks.
+
+1. **A read-only `mu_delegate` measures**:
+
+   ```bash
+   git log --since=<date> --format=%s | cut -d: -f1 | sort | uniq -c
+   mu db query -w <ws> "SELECT CASE WHEN instr(local_id,'_')>0 THEN substr(local_id,1,instr(local_id,'_')-1) ELSE local_id END AS prefix, status, substate, count(*) AS n, sum(local_id GLOB '*_[2-9]') AS rounds FROM tasks t JOIN workstreams w ON w.id=t.workstream_id AND w.name='<ws>' WHERE t.created_at>'<date>' GROUP BY 1,2,3"
+   mu db query -w <ws> "SELECT lower(substr(title,1,instr(title,':')-1)) AS severity, status, count(*) AS n FROM tasks t JOIN workstreams w ON w.id=t.workstream_id AND w.name='<ws>' WHERE t.created_at>'<date>' AND severity IN ('critical','high','medium','low') GROUP BY 1,2"
+   tokei src
+   mu task tree <umbrella> -w <ws>
+   ```
+
+2. **Second delegate refutes the numbers** before any proposal.
+3. **Compare with the spec**: stale text, then:
+   - Switch line: which open critical-path units can move after the switch?
+   - Review cost: rounds per unit, findings by severity. Bar: high = fix + re-review; medium = fix, evidence in the close note; low = one batch.
+   - Code budget: `src/` vs baseline; units >30% over budget.
+   - Real use: last dogfood date; what it found that review missed.
+4. **Propose at most 7 changes**, each tied to a number.
+5. **Stop**: `mu human-needed -w <ws> "course check: <n> proposed changes, see note"`: settle ends a turn only there.
+6. **Approved**: one umbrella note starting `COURSE CHECK <date>` (the hint counts from it) and the DAG diff, then dispatch.