@mu-crew/mu 3.2.1 → 3.4.0

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

@@ -0,0 +1,67 @@
+# 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.
+
+**Mode:** delegates by default: the report is the result, and claims
+need no permanent record. Use a workstream for a long run that must
+survive compaction or feeds a tracked decision; then each claim the
+answer rests on is an `OPEN/triage` task, decided like a finding
+([findings](findings.md)).
+
+## Steps
+
+1. **Write the question and the bar**, into every searcher's brief
+   (delegate mode) or on an umbrella task (workstream mode): 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 searcher per angle (delegates; tasks only in
+   workstream mode): 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**: merge the same fact from several sources (keep
+   every source), and flag claims that contradict each other. In
+   workstream mode, each surviving claim becomes an `OPEN/triage` task
+   titled with the claim, its sources and quotes in the note.
+4. **One checker per claim** that the answer depends on, as a
+   [delegate call](tasks-or-calls.md#delegate-call) in both modes. 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. Batch under the cap
+   ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)). In workstream mode the
+   verdict is the claim task's state: `accept` for confirmed,
+   `close --as rejected` for refuted, an `UNVERIFIED:` note in triage
+   otherwise.
+5. **Synthesize** once every checker has answered (in workstream mode,
+   when no claim task is left undecided): 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,40 @@
+# 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.** A scout (a [delegate call](tasks-or-calls.md#delegate-call)) 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](brief.md) and acceptance criteria on the
+   umbrella; each unit task's note holds only what differs. A sweep that
+   only checks (no commits) makes each unit a delegate call instead
+   ([tasks-or-calls](tasks-or-calls.md)).
+3. **Cap concurrency** ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
+   Spawn at most one agent per ready track. Tell workers to avoid
+   repo-wide commands so more can run.
+4. **Pipeline.** Dispatch, wait `--first`, merge
+   ([orchestrator-loop § Merging](orchestrator-loop.md#merging)), dispatch
+   the next unit to the freed worker with `--fresh`. With `codemode`, a
+   [driver](codemode-driver.md) can dispatch each batch. 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: one
+   delegate call reads the unit notes (not transcripts) and writes one
+   result into the umbrella's note.
+
+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/findings.md

@@ -0,0 +1,103 @@
+# Findings
+
+Use whenever an agent reviews, audits, checks, or researches something
+and reports problems: every recipe that produces findings follows this
+one. It decides where findings live, and how they become work.
+
+## Pick the mode first
+
+Ask: **will anyone act on these findings through the DAG?**
+
+| Situation | Mode | Findings live in |
+| --- | --- | --- |
+| The result is read once and acted on directly: PR comments, doc edits, a go/no-go, a draft fact-check | **Delegate** | the delegate's answer |
+| Findings become work agents fix, or must be tracked to closure | **Workstream** | one `OPEN/triage` task per finding |
+
+Delegate mode keeps reviews of other people's PRs and docs out of the
+ops log, which is permanent and syncs to every machine. Workstream mode
+is the mu way for your own work: the graph shows every finding, who
+decided it, and the fix.
+
+## Delegate mode
+
+1. Run reviewers as [delegate calls](tasks-or-calls.md#delegate-call):
+   one per angle or slice, all in one turn so they run in parallel,
+   under the cap ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
+2. Each delegate ends its answer with one line per finding:
+
+   ```text
+   FINDING: high src/api/user.ts:88 PUT handler skips the auth check EVIDENCE: curl -X PUT ... returned 200
+   ```
+
+3. You read the answers, merge duplicates, and act: post the comments,
+   edit the doc, give the verdict.
+4. **Promote** when the findings turn out to be work: create one
+   `OPEN/triage` task per line (below) and continue in workstream mode.
+
+Done when every delegate answered and every finding line was acted on
+or dropped with a reason.
+
+## Workstream mode
+
+### Record
+
+The reviewer records each finding as a task in triage, blocking the
+review's umbrella so the umbrella cannot close while findings are
+undecided:
+
+```bash
+mu task add -w <ws> --triage \
+  -t "high: PUT /user skips the auth check" -i 70 -e 0.5 \
+  --note 'FINDING: high src/api/user.ts:88 PUT skips the auth check EVIDENCE: curl -X PUT ... returned 200 without a token'
+mu task block <umbrella> -w <ws> --by <finding-id>
+```
+
+The title starts with the severity. The note is one `FINDING:` line,
+the same shape everywhere: `FINDING: <severity> <file:line> <what>
+EVIDENCE: <command + output>`. `OPEN/triage` keeps the finding out of `mu task next`, and
+`claim` refuses it, so no worker starts on an undecided finding.
+
+**More than 5 findings from one reviewer:** the reviewer writes them as
+`FINDING:` lines in its own task note instead. Before that reviewer
+task closes, the orchestrator adds `triage_<umbrella>` blocking the
+umbrella; the triage agent ([Triage](#triage) step 1) merges duplicates
+across reviewers and creates one task per real problem.
+
+### Triage
+
+1. **Who:** a handful of findings, the orchestrator triages itself. Many,
+   or several reviewers on one change: a `triage_<umbrella>` task, run
+   by a fresh agent, so the orchestrator reads only its result.
+2. **Refute** each finding before accepting it with a
+   [delegate call](tasks-or-calls.md#delegate-call): a fresh agent tries
+   to prove it false and ends with
+   `VERDICT: <id> CONFIRMED | REFUTED | UNVERIFIED <evidence>`. Skip this
+   for low-severity style findings. High severity: three refuters,
+   accept only if at least two say CONFIRMED.
+3. **Decide** each one; the decision is the task's state:
+
+   | Decision | Command |
+   | --- | --- |
+   | real work | `mu task accept <id> --evidence '<what confirmed it>'` |
+   | false | `mu task close <id> --as rejected --why '<evidence>'` |
+   | same as another | `mu task close <id> --as duplicate --why 'same as <id>'` |
+   | valid, not worth it | `mu task close <id> --as wontfix --why '<reason>'` |
+   | could not check | stays in triage, with an `UNVERIFIED: <why>` note |
+
+4. **Group** accepted findings that touch the same files into one fix
+   task when separate workers would collide; close the grouped findings
+   `--as superseded --why 'fixed in <fix-task>'`.
+
+Done when `mu task list --substate triage -w <ws>` lists only findings
+with an `UNVERIFIED` note, and each of those is reported to the human.
+
+### Fix and close
+
+Accepted findings are ordinary tasks: dispatch them, review the fix
+([adversarial-review](adversarial-review.md)), merge. The umbrella
+closes with `mu task close <umbrella> --if-ready` once every finding is
+`CLOSED/*`. A plain `close` would succeed with findings still open.
+
+The report is a query, not a document: `mu task list -w <ws>
+--substate rejected`, `--substate duplicate`, `--status OPEN`, and the
+notes on each task.

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

@@ -0,0 +1,45 @@
+# 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 reader per evidence source** (a [delegate call](tasks-or-calls.md#delegate-call)): logs, the
+   code path, recent commits, data, environment. Each sees only its
+   source, so the theories do not anchor on each other. Record each
+   theory as an `OPEN/triage` task blocking the umbrella, decided like
+   a finding ([findings § Triage](findings.md#triage)):
+
+   ```bash
+   mu task add -w <ws> --triage -t "h: <cause>" -i 60 -e 0.5 \
+     --note 'PREDICTS: <an observation true if this is the cause, false otherwise>'
+   ```
+
+3. **Test each hypothesis.** An experiment that changes code (force the
+   race, revert the commit) needs a workspace: `mu task accept` the
+   hypothesis and dispatch it as a task. One that only reads (feed the
+   data, grep the logs) is a delegate call. A killed hypothesis closes
+   `--as rejected --why '<evidence>'`; a survivor gets a
+   `SURVIVED: <evidence>` note.
+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 the fix's review task is `CLOSED/done` (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** ([long-run](long-run.md) step 1). "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. **Define 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** ([fan-out](fan-out.md)). 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**
+   ([orchestrator-loop § Merging](orchestrator-loop.md#merging)).
+
+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,42 @@
+# 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** that blocks the umbrella and is blocked by
+   the previous round:
+   `round_1`, `round_2`, .... Add the next round only when the current
+   one closes; never pre-create rounds. Dispatch each per
+   [orchestrator-loop](orchestrator-loop.md); multi-hour loops follow
+   [long-run](long-run.md).
+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: `mu task close <umbrella> --if-ready --evidence '<stop
+     command + result>'` (each round blocks 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.

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

@@ -0,0 +1,98 @@
+# Orchestrator loop
+
+Use when you run a workstream: you dispatch DAG tasks to workers and
+merge their commits. The hard rules in SKILL.md still apply; this is
+the loop and the reasons behind them.
+
+## 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 ([waves](waves.md)
+   when workers share files).
+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. Review tasks: [adversarial-review](adversarial-review.md).
+4. Run `mu workspace refresh <w>`, then send a [brief](brief.md) with
+   `mu agent send <w> --fresh '...'` (new session + prompt in one step;
+   refuses while busy). The brief ends with its final-action block.
+5. `mu task wait ... --first --on-stall exit --json`.
+6. Cherry-pick the closed worker's **new** commit(s), verify the MERGE,
+   then continue the loop in the same turn. Do not barrier or loop in
+   shell.
+   Only `CLOSED/done` ships; other closes: read the reason note.
+7. Repeat from `mu state`.
+
+## Concurrency
+
+Write the ceiling on the umbrella before the first wave
+(`CONCURRENCY: delegates 12, workers 4`) so a resumed orchestrator
+keeps it.
+
+- **[Delegate calls](tasks-or-calls.md#delegate-call)** (read-only): 10 to 20 at once is reasonable.
+  Token spend and provider rate limits bind first; start near 8 and
+  raise after a clean wave. `mu_delegate` refuses past
+  `MU_DELEGATE_MAX` (default 16).
+- **Workers with workspaces** build and test: about one per CPU core,
+  fewer when each runs the full suite. A remote host has its own
+  session cap ([remote-workers](remote-workers.md)).
+- **Stream, do not batch.** Keep the pool full: dispatch the next unit
+  when one closes, rather than waiting for a whole wave. With the
+  `codemode` tool, a [driver](codemode-driver.md) can dispatch a batch
+  of workers in one script.
+
+## Waiting
+
+Use `--first --on-stall exit`: `--first` populates `.firing`, and
+`--on-stall exit` stops an unattended wait when a worker needs attention.
+Exit 6: the owner's pane died and the reaper reopened the task; exit 7:
+the owner sat in `needs_input`. Read that
+pane (`mu agent read <owner>`) and answer: the worker may be waiting on
+you.
+
+For an idle worker, read the pane, then answer, retry, or release its
+task. `MU_IDLE_THRESHOLD_MS` defaults to 5m. A remote owner: poll once
+per turn ([remote-workers](remote-workers.md#step-5-poll-once-per-turn)).
+
+## Merging
+
+- **Pipeline; don't barrier.** Wait for one task, cherry-pick only its
+  new commits, verify, dispatch the next. An umbrella wait hides progress;
+  merging stale branches can restore reverted code.
+- **Verify the merge, not the worker's rerun.** Only the combination
+  with moved main is new, and it breaks in ways the worker's own run
+  cannot show. Remote hosts: [run the merged gate there](remote-workers.md#run-the-merged-gate-on-the-host).
+- **Push only when the gate command passes.** Make `git push` the last
+  line under `set -e`. Check the gate command runs what it claims: an env-gated randomized
+  test once passed with zero cases.
+- **Accept evidence, not close notes.** Re-run the key measurement from
+  a clean checkout; close notes have claimed unpushed commits. A
+  worker's "done" counts only once the diff shows the change.
+- **Ask whether the check could have failed.** A gate that cannot say
+  no is not evidence: a test filtered to zero cases, a script you wrote
+  agreeing with itself, a fixture you tuned on. A nonzero diff is a
+  failure even when the command exited 0.
+
+## Sending
+
+- 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. For pi,
+  `--fresh` does both in one step.
+- Use `mu agent send`, not raw mux input. Single-quote prompts
+  containing shell expansions, or use a quoted heredoc.
+- Cross-workstream wait and claim use qualified refs; only task
+  ownership crosses.
+
+## Stopping 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`.
+
+Done when every task is closed, or a decision only a human can make blocks all progress (SKILL.md § Orchestrator rules).

package/skills/mu/recipes/plan.md

@@ -0,0 +1,59 @@
+# Planning a DAG
+
+Use when you turn a spec or a clear set of requirements into tasks.
+The DAG is the plan: each task's note carries its full content, and
+`mu state` is the progress tracker. Write a markdown plan only when the
+human asks for a file.
+
+## Steps
+
+1. **Map the files first.** List what gets created or changed and what
+   each file is responsible for. Task boundaries fall out of this map.
+2. **Size the tasks.** A task is the smallest unit that carries its own
+   verification and is worth a review. Split only where a reviewer
+   could reject one task and accept its neighbour. Fold setup, config,
+   and docs into the task whose deliverable needs them.
+3. **Write the root task.** `task_0` holds the goal, the architecture
+   in two or three sentences, and the global constraints copied
+   verbatim from the spec. Every other task is blocked by it; close it
+   at once. It carries notes, not work.
+4. **Write each task's note** as a [brief](brief.md): its Shape, plus
+   INTERFACES and STEPS:
+
+   ```text
+   GOAL:       one sentence
+   DONE WHEN:  checkable, exhaustive criterion
+   FILES:      Create/Modify/Test with exact paths (line ranges if known)
+   INTERFACES: Consumes: <exact signatures from earlier tasks>
+               Produces: <exact names and types later tasks use>
+   STEPS:      one action each; code steps carry the code
+   VERIFY:     <exact command and expected result>
+   ```
+
+   The worker sees only its own task. INTERFACES is how it learns the
+   names its neighbours use.
+5. **No placeholders.** "TBD", "add error handling", "similar to
+   task 3", "write tests for the above": each is a missing decision the
+   worker will make alone. Write the actual content; tasks are read out
+   of order.
+6. **Add edges for dependencies only.** `mu task block A --by B` when A
+   consumes what B produces. Plan order is not a dependency: an extra
+   edge serialises tracks that could run in parallel. The exception:
+   tasks that edit the same files share a track ([waves](waves.md)).
+7. **Self-review before dispatch.** Walk each spec requirement and name
+   the task that implements it. Grep the notes for placeholders. Check
+   that names in INTERFACES match across tasks. Then read the graph back
+   with `mu task tree task_0 -w <ws> --down`, or `mu state -w <ws>` for the tracks.
+
+Done when every spec requirement maps to a task, no note holds a
+placeholder, and `mu state` shows the intended parallel tracks. Then
+dispatch per [orchestrator-loop](orchestrator-loop.md).
+
+## Notes
+
+- `impact` comes from what breaks without the task; `effort_days` from
+  its step count. Guess honestly rather than defaulting to 50 and 1.
+- Review gates follow [adversarial-review](adversarial-review.md): a
+  review task blocked by the work.
+- When reality disagrees with the plan, append a note saying so. Do not
+  rewrite earlier notes.

package/skills/mu/recipes/recovery.md

@@ -0,0 +1,28 @@
+# Recovery: undo, rebuild, sync
+
+Use before you undo a change, rebuild the DB, tear down a workstream,
+set up sync, or act on `mu doctor` output. Each of these can lose work
+when done in the wrong order.
+
+- **`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.
+- **`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`.
+- **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. 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 `doctor` `disk` section is report-only: an orphan dir may hold the
+  only copy of uncommitted work, so mu prints cleanup commands and runs
+  none. Read before you run them.
+
+Done when `mu doctor` reports no DRIFT and every cleanup command you ran was read first.

package/skills/mu/recipes/refute.md

@@ -0,0 +1,51 @@
+# Find, refute, synthesize
+
+Use for audits, bug sweeps, and fact-checks: anything that produces
+findings. Finders over-report; a separate agent told to kill each
+finding filters what survives. Where findings live and how triage works
+is [findings](findings.md); this recipe is the search around it. Builds
+on [fan-out](fan-out.md).
+
+**Mode:** workstream by default (an audit feeds fixes). For a quick
+fact-check nobody will track, use delegate mode from
+[findings](findings.md) and skip the tasks.
+
+## Steps
+
+1. **Pin the scope** on an umbrella task: what is searched, and what
+   counts as a finding.
+2. **Split the search** into slices (security, data integrity, one
+   module each). One finder task per slice. Finders read; they do not
+   fix.
+3. **Finders record findings** as `OPEN/triage` tasks blocking the
+   umbrella, one per finding, severity first in the title, file:line and
+   evidence in the note ([findings § Record](findings.md#record)). A
+   finder with more than 5 writes `FINDING:` lines in its own note
+   instead, and [findings § Triage](findings.md#triage) turns them into
+   tasks.
+4. **Refute each finding** with a
+   [delegate call](tasks-or-calls.md#delegate-call), not a task. The
+   refuter gets the finding and the code, not the finder's reasoning,
+   and tries to prove it false: run it, find the guard, read the caller.
+   Record its verdict on the finding, and apply the skip and
+   three-refuter rules, as in [findings § Triage](findings.md#triage).
+   Many findings: issue the calls in batches under the cap ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)); to
+   get the verdicts back as one table, see
+   [codemode-driver § Delegate calls](codemode-driver.md#delegate-calls).
+5. **Report** from the graph: accepted findings are the result, ranked
+   by impact; `mu task list --substate rejected` is what was refuted.
+   A synthesis task is needed only when the human wants prose.
+
+Done when no finding is left in triage without an `UNVERIFIED` note,
+and the umbrella closes with `--if-ready` once the accepted findings
+are fixed or handed off.
+
+## Traps
+
+- **UNVERIFIED is not REFUTED.** A refuter that hit a rate limit or
+  could not run the code disproved nothing. The finding stays in triage
+  with an `UNVERIFIED:` note, reported apart.
+- **Cheap finders, strong refuters.** Finders can run on `pi_mini`; the
+  refute step is where the judgement is (`pi_big`).
+- **No findings is a result.** A slice that finds nothing closes with
+  that in its note; do not re-run it until it finds something.

package/skills/mu/{REMOTE_WORKERS.md → recipes/remote-workers.md}

@@ -1,7 +1,8 @@
 # Remote workers
 
-mu has no remote backend, ssh code, or host registry. This is a recipe
-plus the traps that cost time.
+Use when an agent's process runs on another machine (a devserver, a
+bigger box) while its pane stays local. mu has no remote backend, ssh
+code, or host registry. This is a recipe plus the traps that cost time.
 
 **If you read one thing:** on a session-capped host, an open attach pane
 holds the only ssh channel and silently breaks `git fetch`,
@@ -49,6 +50,10 @@ mu agent send worker-1 -w big --fresh '...'
 git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
 ```
 
+Done when the worker's commits are cherry-picked locally, the merged
+tree passes the gate command (on the host, below), and the pane is
+closed.
+
 ### Step 2: the note is load-bearing
 
 Keep the exact forms `REMOTE: <host>:<path>` and

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

@@ -0,0 +1,62 @@
+# Review panel
+
+Use to review one diff, branch, or PR from several angles before it
+ships: correctness, security, simplicity, tests, the repo's own rules.
+One reviewer looking at everything finds the obvious; one reviewer per
+angle, each in a fresh context, finds more. Findings are refuted before
+anyone acts on them.
+
+This is a sweep over one change. To gate each unit of a larger job,
+use [adversarial-review](adversarial-review.md) instead.
+
+**Mode:** delegates by default: reviewing a PR, a doc, or a draft needs
+an answer, not a permanent record. Switch to workstream mode when the
+panel's findings will be fixed by agents. Both modes are in
+[findings](findings.md).
+
+## Steps
+
+1. **Pin the target**: `git diff main...HEAD`, a PR number, or a commit
+   range. Put it in every reviewer's brief (delegate mode) or on an
+   umbrella task (workstream mode), so every reviewer reads the same
+   range.
+2. **One reviewer per angle**: a delegate in delegate mode, a task in
+   workstream mode. Pick the angles that apply:
+
+   | Angle | Looks for |
+   | --- | --- |
+   | correctness | logic errors, edge cases, error paths, races |
+   | security | injection, auth and permission checks, secrets, unsafe input |
+   | simplicity | duplication, dead code, needless abstraction, an existing helper not reused |
+   | tests | changed behaviour without a test, tests that cannot fail |
+   | rules | the repo's written rules (see [rules-audit](rules-audit.md)) |
+
+   Each reviewer gets the range, its angle, and the [brief](brief.md)
+   rules; it edits nothing. A clean result (`FINDINGS: none` plus the
+   commands it ran) is a valid result.
+3. **Record findings** by mode:
+   - delegate: each reviewer ends its answer with `FINDING:` lines;
+   - workstream: each finding is an `OPEN/triage` task blocking the
+     umbrella ([findings § Record](findings.md#record)).
+4. **Merge and refute.** Merge duplicates across angles, then refute
+   with [delegate calls](tasks-or-calls.md#delegate-call) in both modes,
+   following the skip and three-refuter rules in
+   [findings § Triage](findings.md#triage).
+5. **Act:**
+   - delegate mode: post the comments or edit the doc from the merged
+     list, citing file:line and evidence;
+   - workstream mode: accept the confirmed findings, dispatch the
+     fixes, each with its own review
+     ([adversarial-review](adversarial-review.md)).
+
+Done when every finding is acted on (delegate mode) or decided in
+triage and the umbrella closes with `--if-ready` (workstream mode).
+
+## Traps
+
+- **Reviewers padding the list.** A panel that always finds ten things
+  is guessing.
+- **Use different models across angles** where you can; one model's
+  blind spot repeated five times is still one blind spot.
+- **The panel is not the gate command.** Merge verification still runs on the
+  merged tree ([orchestrator-loop](orchestrator-loop.md#merging)).