@mu-crew/mu 3.3.0 → 3.4.0

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,53 @@ 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` 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 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 +62,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 +74,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 +94,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

@@ -24,3 +24,5 @@ when done in the wrong order.
 - 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

@@ -1,49 +1,51 @@
 # Find, refute, synthesize
 
-Use for audits, bug sweeps, research, and fact-checks: anything that
-produces findings or claims. Finders over-report; a separate agent told
-to kill each finding filters what survives. Builds on
-[fan-out](fan-out.md) and [adversarial-review](adversarial-review.md).
+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).
 
-## Steps
-
-1. **Split the search** into dimensions or slices (security, data
-   integrity, one module each). One finder task per slice. Finders read;
-   they do not fix.
-2. **Finders write structured findings** to their task note, one line
-   each:
+**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.
 
-   ```text
-   FINDING: f3 src/routes/user.ts:42 high: handler skips the auth check on PUT
-   ```
+## Steps
 
-3. **Dedupe** before refuting: one task reads every finder note and
-   merges duplicates, keeping the ids. Refuting the same bug twice pays
-   twice.
-4. **One refute task per finding**, blocked by the dedupe task. The
+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.
-   It ends with one line:
-
-   ```text
-   VERDICT: f3 CONFIRMED | REFUTED | UNVERIFIED <evidence>
-   ```
-
-   For high-severity findings, run three refuters and keep the finding
-   only if most fail to kill it.
-5. **Synthesize**: a final task blocked by every refute task writes the
-   report from the verdict lines. Confirmed findings, ranked. Unverified
-   ones listed apart. Refuted ones counted, not shown.
-
-Done when every finding id from step 3 has a verdict line, and the
-synthesis task closed.
+   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 did not disprove anything. Keep the finding in
-  its own section.
-- **Cheap finders, strong refuters.** Finders can run on `pi_mini`;
-  the refute step is where the judgement is (`pi_big`).
+  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/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