@mu-crew/mu 3.3.0 → 3.5.0

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

@@ -1,54 +1,102 @@
 # Codemode driver
 
-Use when a pi orchestrator with the `codemode` tool runs a recipe with
-many parallel units, and one tool call per spawn, send, and wait is
-slow. A script can issue those calls in parallel. It stays a driver:
-the plan, the state, and the results live in the DB.
+Use when a pi orchestrator with the `codemode` tool has one step that
+dispatches many workers, or many [delegate calls](tasks-or-calls.md#delegate-call)
+whose verdicts you want back as one table. A script issues those calls
+in parallel. It stays a driver: the script is the agent's, not mu's,
+and the plan, the state, and the results live in the DB.
 
 ## The rule
 
 **Delete the script mid-run and nothing is lost.** That holds when:
 
-- The script calls only `mu` verbs, through `tools.bash`. It reads
-  state with `mu state --json` / `mu task notes`, never from its own
-  variables across calls.
+- The script calls only `mu` verbs, through `tools.bash` (or
+  `tools.mu_delegate`, below). It reads state with `mu state --json` /
+  `mu task notes`, never from its own variables across calls.
 - Every task it dispatches exists in the DAG before the script starts.
   The script adds no tasks the orchestrator has not planned, except the
-  ones a recipe step names (the next round, a `fix_` task).
+  ones a recipe step names (the next round, a finding).
 - `store()` / `load()` hold nothing a re-run needs. The DAG is the
   cursor.
-- The script's source goes into the log before it runs:
-  `mu log -w <ws> --kind driver '<what it does, which tasks>'`.
+- Before it runs, log a one-line summary and the task ids it touches:
+  `mu log -w <ws> --kind driver 'dispatch wave 2: sweep_a sweep_b'`.
 
-## Shape
+## Workers
 
 ```js
 // @options: {"timeout_ms": 1800000}
 const ws = "audit";
+const workers = ["worker-1", "worker-2", "worker-3", "worker-4"]; // within the ceiling
 const sh = async (c) => {
   const r = await tools.bash({ command: c });
   if (r.exit_code !== 0) throw new Error(`${c}: ${r.output}`);
   return r.output;
 };
-const ready = JSON.parse(await sh(`mu task next -w ${ws} -n 0 --json`)).items;
-await Promise.allSettled(ready.slice(0, 4).map(async (t, i) => {
-  const w = `worker-${i + 1}`;
-  await sh(`mu task claim ${t.name} -w ${ws} --for ${w} --evidence 'driver dispatch'`);
-  await sh(`mu agent send ${w} -w ${ws} --fresh 'Work on ${t.name}. Read: mu task notes ${t.name} -w ${ws}'`);
+const ready = JSON.parse(await sh(`mu task next -w ${ws} -n 0 --json`)).items.slice(0, workers.length);
+await Promise.allSettled(ready.map(async (t, i) => {
+  await sh(`mu task claim ${t.name} -w ${ws} --for ${workers[i]} --evidence 'driver dispatch'`);
+  await sh(`mu workspace refresh ${workers[i]} -w ${ws}`);
+  await sh(`mu agent send ${workers[i]} -w ${ws} --fresh 'Work on ${t.name}. Read: mu task notes ${t.name} -w ${ws}'`);
 }));
-const wait = await tools.bash({ command: `mu task wait -w ${ws} ${ready.slice(0, 4).map((t) => t.name).join(" ")} --first --on-stall exit --json` });
+const wait = await tools.bash({ command: `mu task wait -w ${ws} ${ready.map((t) => t.name).join(" ")} --first --on-stall exit --json` });
 return wait.output;
 ```
 
-Check field names against `--json` output before relying on them; the
-script above is a shape, not an API.
+Size the worker list from the ceiling on the umbrella
+([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)),
+one per ready track. Merge and verify outside the script
+([orchestrator-loop § Merging](orchestrator-loop.md#merging)). Check
+field names against `--json` output; the script is a shape, not an API.
+
+## Delegate calls
+
+`tools.mu_delegate` works from a script, but it returns at once and the
+answers arrive after the script, as follow-up messages: the script
+gains nothing over issuing the calls in one turn. Use it from a script
+only when `codemode.mode` is `only` and the tool is not offered
+directly. Check `Promise.allSettled` results for rejections: past the
+cap, `mu_delegate` refuses.
+
+To get the verdicts back as one table instead of one message each, use
+the `scratch` form through `tools.bash`:
+
+```js
+// @options: {"timeout_ms": 1800000}
+const findings = ["f_auth_put", "f_sql_order"]; // finding task ids, at most the cap per script
+const sh = async (c) => (await tools.bash({ command: c })).output;
+const rows = await Promise.all(findings.map(async (id, i) => {
+  const a = `refuter-${i + 1}`;
+  await sh(`mu agent spawn ${a} -w scratch`);
+  await sh(`mu agent send ${a} -w scratch --fresh '<brief for ${id}: ... end with VERDICT: ...>'`);
+  const w = JSON.parse(await sh(`mu agent wait ${a} -w scratch --json --timeout 1200`));
+  const text = w.agents?.[0]?.lastText ?? "";
+  await sh(`mu agent close ${a} -w scratch`);
+  return `${id}\t${(text.match(/VERDICT:.*$/m) ?? ["VERDICT: UNVERIFIED no verdict line"])[0]}`;
+}));
+return rows.join("\n");
+```
+
+What the tool did for you, the script now owns:
+
+- **The cap.** `MU_DELEGATE_MAX` does not apply to bash spawns: keep
+  each script's list at or under it.
+- **Cleanup.** Close each scratch pane; a timed-out one stays, readable
+  with `mu agent read <a> -w scratch`.
+- **Recording.** The table is not the record. Record each verdict on its
+  finding (`mu task accept`, `close --as rejected --why`), from the
+  script or after it returns.
 
 ## Traps
 
 - **One wave per script.** A script that loops forever hides progress
   from you and from the human. Dispatch, wait for the first close,
-  return; merge and verify outside the script, then run it again.
+  return; merge and verify outside the script, then run it again. A
+  tournament runs one round per script.
 - **A script timeout cancels the waits, not the workers.** Workers keep
   running and their tasks stay claimed. Re-read `mu state` and carry on.
 - **Exit codes are data.** `mu task wait` exit 7 means a worker needs
   you; return it to the model instead of retrying.
+
+Done when the script returned, `mu state` shows the dispatched tasks
+claimed (workers) or every verdict is recorded on its finding (delegate
+calls), and no scratch pane the script opened is left running.

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

@@ -7,13 +7,21 @@ 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** on an umbrella task: the exact
+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 search task per angle: official docs,
+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:
@@ -24,16 +32,23 @@ sources. Workers need a web search tool (pi's `brave_search`, or
 
    A claim without a source and a quote is not a claim. Searchers can
    run on a cheap model.
-3. **Dedupe claims** in one task: merge the same fact from several
-   sources (keep every source), and flag claims that contradict each
-   other.
-4. **One check task per claim** that the answer depends on. The checker
+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.
-5. **Synthesize** in a task blocked by every check: answer the question
+   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.

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

@@ -6,7 +6,7 @@ some and calls the job done; one task per unit cannot.
 
 ## Steps
 
-1. **Enumerate first, as its own task.** A scout lists the units and
+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.
@@ -18,19 +18,23 @@ some and calls the job done; one task per unit cannot.
    mu task block sweep -w <ws> --by sweep_auth_ts
    ```
 
-   Put the shared brief and acceptance criteria on the umbrella; each
-   unit task's note holds only what differs.
-3. **Cap concurrency.** Spawn at most one agent per ready track, and no
-   more than the machine can build and test at once. Tell workers to
-   avoid repo-wide commands so more can run.
-4. **Pipeline.** Dispatch, wait `--first`, merge, dispatch the next unit
-   to the freed worker with `--fresh`. Units that touch the same files
+   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: a final
-   task blocked by every unit reads their notes and writes one result.
-   It reads notes, not transcripts.
+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

@@ -9,19 +9,23 @@ form independent theories; separate agents then try to kill them.
 
 1. **Write the symptom** on the umbrella: what happens, how often, the
    repro command, and what would count as fixed.
-2. **One hypothesis task per evidence source**: logs, the code path,
-   recent commits, data, environment. Each agent sees only its source,
-   so the theories do not anchor on each other. Each ends with:
-
-   ```text
-   HYPOTHESIS: h2 <cause>
-   PREDICTS: <an observation that is true if h2 is the cause, false otherwise>
+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. **One test task per hypothesis**, in its own workspace. The tester
-   builds the experiment that would kill the hypothesis (force the race,
-   revert the commit, feed the data) and reports
-   `VERDICT: h2 SURVIVES | KILLED <evidence>`.
+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.
@@ -29,12 +33,13 @@ form independent theories; separate agents then try to kill them.
    ([loop-until-done](loop-until-done.md)): the new hypothesis tasks get
    the killed hypotheses and their evidence as input.
 
-Done when a fix closed `ACCEPT` and the repro from step 1 no longer
+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.** "Passed once" proves nothing for a 1 in
+- **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

@@ -3,18 +3,18 @@
 Use when a task or proof runs for hours, crosses context compaction,
 or may hit flakes.
 
-1. **Fix done first.** Before dispatch, write the completion criterion
+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.** Shard a long proof into tasks
+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.** Re-run the key measurement
-   from a clean checkout before you count a unit as done.
+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

@@ -15,14 +15,18 @@ written down first does neither.
    NO-PROGRESS: two rounds in a row reduce the error count by zero
    ```
 
-2. **Each round is a task**, blocked by the previous one:
+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.
+   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: close the umbrella.
+   - 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.

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

@@ -8,42 +8,59 @@ the loop and the reasons behind them.
 
 1. `mu state -w <ws>` — read agents, IN_PROGRESS, ready tasks,
    parallel tracks.
-2. Spawn at most one agent per independent ready track.
+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.
-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,
+   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.
-8. Repeat from `mu state`.
+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` runs at most
+  `MU_DELEGATE_MAX` (default 16) and queues up to four times that
+  (`queued-N`, started as slots free); past that it refuses.
+- **Answers arrive when you stop**, as pi follow-up messages, never
+  mid-turn. pi's `followUpMode: "all"` delivers every waiting answer in
+  one turn instead of one turn each; each answer names its delegate and
+  ends with its `VERDICT: <id>` line, so a batch still maps back. Record
+  every verdict in the batch before acting on any.
+- **Workers with workspaces** build and test: about one per CPU core,
+  fewer when each runs the full suite. A remote host has its own
+  session cap ([remote-workers](remote-workers.md)).
+- **Stream, do not batch.** Keep the pool full: dispatch the next unit
+  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 is a dead pane; exit 7 is an owner in `needs_input`. Read that
+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. Questions are cheaper than rework.
+you.
 
 For an idle worker, read the pane, then answer, retry, or release its
-task. `MU_IDLE_THRESHOLD_MS` defaults to 5m.
+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
 
@@ -51,10 +68,10 @@ task. `MU_IDLE_THRESHOLD_MS` defaults to 5m.
   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; that found three breaks rerunning found none
-  of. Remote hosts: [run the merged gate there](remote-workers.md#run-the-merged-gate-on-the-host).
-- **Push only from a green gate.** Make `git push` the last line under
-  `set -e`. Check the gate runs what it claims: an env-gated randomized
+  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
@@ -63,8 +80,6 @@ task. `MU_IDLE_THRESHOLD_MS` defaults to 5m.
   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.
-- **Dispatch from current main.** Reset the worker's worktree to main
-  before each task.
 
 ## Sending
 
@@ -85,3 +100,5 @@ task. `MU_IDLE_THRESHOLD_MS` defaults to 5m.
 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

@@ -17,9 +17,12 @@ human asks for a file.
    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):
+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>
@@ -35,14 +38,16 @@ human asks for a file.
    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.
+   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.
+placeholder, and `mu state` shows the intended parallel tracks. Then
+dispatch per [orchestrator-loop](orchestrator-loop.md).
 
 ## Notes
 

package/skills/mu/recipes/recovery.md

@@ -19,8 +19,13 @@ when done in the wrong order.
   mu never runs ssh or rsync; `mu sync` prints the line.
   `--repair <peer>` is always safe. Agents, workspaces, and task
   ownership never travel.
+- **`mu db forget <ws...>`** deletes torn-down workstreams' ops for
+  good (no undo); `mu db compact` only blanks redundant tombstones. Both
+  back up beside the DB first. Forget only what the human named.
 - **`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.