@mu-crew/mu 3.3.0 → 3.5.0

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

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

@@ -9,12 +9,19 @@ 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.** Record the exact range on an umbrella task:
-   `git diff main...HEAD`, a PR number, or a commit range. Every
-   reviewer reads the same range.
-2. **One reviewer task per angle.** Pick the angles that apply:
+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 |
    | --- | --- |
@@ -22,36 +29,34 @@ use [adversarial-review](adversarial-review.md) instead.
    | 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 `AGENTS.md` / contributing rules, one line per rule checked |
-
-   Each reviewer gets the range, its angle, and the
-   [brief](brief.md) rules; it edits nothing. Findings go in its note:
-
-   ```text
-   FINDING: s2 src/api/user.ts:88 high security: id from the URL reaches the query unescaped
-   ```
-
-   A reviewer that finds nothing closes with `FINDINGS: none` and the
-   commands it ran.
-3. **Dedupe** the findings across angles in one task.
-4. **Refute each finding** with a fresh agent, as in
-   [refute](refute.md) step 4. Low-severity style findings can skip this
-   and go straight to the report.
-5. **Act on confirmed findings:**
-   - fix mode: one `fix_` task per finding or file cluster, each with
-     its own review ([adversarial-review](adversarial-review.md));
-   - report mode: a synthesis task writes one ranked list with
-     file:line, the evidence, and a suggested fix.
-
-Done when every finding id has a verdict, and either every confirmed
-finding has a closed fix with an `ACCEPT` review, or the report lists
-them all.
+   | 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.** Tell them a clean result is a valid
-  result. A panel that always finds ten things is guessing.
+- **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.** Merge verification still runs on the
+- **The panel is not the gate command.** Merge verification still runs on the
   merged tree ([orchestrator-loop](orchestrator-loop.md#merging)).

package/skills/mu/recipes/rules-audit.md

@@ -8,10 +8,16 @@ against twenty rules skips some; one checker per rule does not.
 Two modes. **Check** asks "does this change follow our rules?".
 **Mine** asks "which rules are we missing?".
 
+Check on someone's PR runs as delegates; check before merging your own
+work, and mine always, run in a workstream. Violations and candidate
+rules are findings: [findings](findings.md) says where they live.
+
 ## Check: a change against the rules
 
-1. **List the rules.** A scout extracts every checkable rule from the
-   rule files into the umbrella's note, one per line with its source:
+1. **List the rules.** A scout (a delegate call) extracts every
+   checkable rule from the rule files, one per line with its source,
+   into every checker's brief (delegate mode) or the umbrella's note
+   (workstream mode):
 
    ```text
    RULE: r7 AGENTS.md:52 "Throw typed error classes, not bare Error"
@@ -21,18 +27,21 @@ Two modes. **Check** asks "does this change follow our rules?".
    count.
 2. **Pin the target**: the diff, branch, or PR, as in
    [review-panel](review-panel.md) step 1.
-3. **One checker task per rule.** The checker gets one rule and the
-   diff, and reports each violation with file:line and the rule id, or
-   `r7: no violations` with what it looked at. One rule per checker
-   keeps it from skimming.
-4. **A skeptic pass** over the flags: one fresh agent reads each flagged
+3. **One checker per rule**, as a [delegate call](tasks-or-calls.md#delegate-call)
+   The checker gets one rule and the diff, and records each violation
+   as a finding ([findings § Record](findings.md#record); title
+   `<severity>: r7 <what>`), or reports `r7: no violations` with what it
+   looked at. One rule per checker keeps it from skimming; batch under
+   the cap ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
+4. **A skeptic pass** over the flags, also a delegate call: one fresh agent reads each flagged
    line and the rule, and drops false positives (the rule does not
    apply here, the code already complies, the rule has a stated
-   exception). Ending: `VERDICT: <flag> CONFIRMED | DROPPED <reason>`.
+   exception). In workstream mode, a dropped flag is
+   `close --as rejected --why '<reason>'`; a confirmed one is accepted.
 5. **Report or fix** confirmed violations, as in review-panel step 5.
 
 Done when every rule from step 1 has a checker result, and every flag
-has a skeptic verdict.
+is decided.
 
 ## Mine: rules you keep stating but never wrote
 
@@ -41,23 +50,27 @@ has a skeptic verdict.
    tasks, and past agent sessions (with a session archive such as
    [museum](https://github.com/mu-crew/museum), search for user turns
    that correct the agent: "no, use", "don't", "we always"). One reader
-   task per source batch writes each correction as one line:
+   (a delegate call) per source batch returns each correction as one
+   line:
 
    ```text
    CORRECTION: k12 <source ref> "use the shared retry helper instead of a hand-rolled loop"
    ```
 
-2. **Cluster** the corrections in one task: the same lesson in
+2. **Cluster** the corrections in one delegate call: the same lesson in
    different words is one cluster. Keep clusters with at least two
    corrections from different occasions; a one-off is not a rule.
-3. **Refute each candidate rule** with a fresh agent: would it have
+3. **One `OPEN/triage` task per candidate rule**, the rule as the
+   title and its cluster of corrections in the note.
+4. **Refute each candidate** with a [delegate call](tasks-or-calls.md#delegate-call): would it have
    prevented the real mistakes in its cluster? Does it contradict an
    existing rule? Is it already enforced by a linter or test (then it
-   needs no prose)? Ending: `VERDICT: <rule> KEEP | DROP <reason>`.
-4. **Propose, don't commit.** Write the surviving rules as a diff to
-   the rule file, worded per [brief](brief.md) (positive, specific,
-   with the reason), each citing its cluster. A rule file change is a
-   human decision: park the umbrella with the diff in its note.
+   needs no prose)? Dropped candidates close `--as rejected`.
+5. **Propose, don't commit.** The candidates left in triage are the
+   proposal: write them as a diff to the rule file in the umbrella's
+   note, worded per [brief](brief.md) (positive, specific, with the
+   reason). A rule change is a human decision: the human accepts or
+   rejects each candidate task.
 
 Done when every cluster has a verdict and the proposal lists each kept
 rule with the corrections behind it.

package/skills/mu/recipes/tasks-or-calls.md

@@ -0,0 +1,71 @@
+# Tasks or calls
+
+Use when a recipe step spawns an agent: decide whether that agent's job
+is a **task** in the DAG or a **call** to a delegate. Getting it wrong
+one way loses track of work; the other way, one PR review creates
+hundreds of tasks and a workstream nobody wanted.
+
+## Delegate call
+
+A **delegate call** is one `mu_delegate` tool call in pi. Without the
+tool (another harness, a script):
+
+```bash
+mu agent spawn refuter-1 -w scratch
+mu agent send refuter-1 -w scratch --fresh '<brief>'
+mu agent wait refuter-1 -w scratch --json   # answer in lastText
+```
+
+- **It starts empty.** The brief carries everything: the finding or
+  claim, file paths, the criteria, and the answer line to end with
+  (`VERDICT: ...`, `WINNER: ...`). See [brief](brief.md).
+- **Fan out in one turn.** Issue every call for a step together; in pi
+  the answers arrive later as follow-up messages. Calling one, waiting,
+  then the next runs them in series.
+- **It leaves no task.** Its `scratch` pane stays attachable while it
+  runs. `mu_delegate` closes it after a clean finish and keeps it on a
+  crash, timeout, or API error (`keep: true` always keeps it); the bash
+  form needs `mu agent close <name> -w scratch`. You record its verdict
+  on the task it judged.
+- **An API error is yours to decide.** Re-issue the call, or record the
+  check as `UNVERIFIED` on its task, then close the kept pane
+  (`mu_delegate_cancel`, or `mu agent close`).
+
+## The rule
+
+**A task is a thing the graph tracks. Checking a thing is a call.**
+
+| Make it a task | Make it a delegate call |
+| --- | --- |
+| a unit of work that produces commits | refuting a finding |
+| a gate that decides whether work counts (`review_x`) | checking a claim against its source |
+| a finding, claim, or hypothesis that survives into the workstream | judging a pair in a tournament |
+| the umbrella, and each round of a loop | a skeptic or dedupe pass |
+| anything that needs its own workspace | a reader or scout whose output feeds one step |
+
+A call writes nothing to mu. Its answer lands on the task it judged:
+the orchestrator records the verdict as a note and a state change
+(`mu task accept`, `close --as rejected --why '<evidence>'`). The graph
+keeps the decision and its evidence without a node per check.
+
+## Examples
+
+- A refuter checks 30 findings: 30 delegate calls, 0 new tasks; each
+  finding task gets the refuter's evidence and is accepted or closed.
+- A tournament over 16 names: 15 judge delegate calls; the winner goes
+  in the umbrella's note.
+- A hypothesis test that reverts commits or forces a race needs a
+  workspace: that one is a task.
+
+## Counting
+
+Before a wave, count what it will add: units + gates + expected
+findings. If the count is more than a few hundred for one change, the
+steps that only check things are probably tasks by mistake.
+
+`mu_delegate` runs 16 at once (`MU_DELEGATE_MAX`) and queues the rest
+up to four times the cap; see
+[orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency).
+
+Done when every agent a recipe step spawns is either a task in the DAG
+or a delegate call whose verdict is recorded on a task.

package/skills/mu/recipes/tournament.md

@@ -9,17 +9,20 @@ reliable than scoring one.
 
 1. **Write the rubric first**, on the umbrella: what good looks like,
    in a few ranked criteria. Judges apply it; they do not invent one.
-2. **Generate.** N attempt tasks with the same brief and a different
-   approach or model each. Code attempts run in separate workspaces.
-   For ideas (names, plans), one task can generate many candidates as
-   note lines.
-3. **Filter** (when there are many candidates): one task drops the ones
-   that fail a hard rubric criterion and merges duplicates. What is left
+2. **Generate.** N attempts with the same brief and a different
+   approach or model each. Code attempts are tasks, each in its own
+   workspace. Ideas (names, plans) are delegate calls; one call can
+   generate many candidates.
+3. **Filter** (when there are many candidates): one delegate call drops
+   the ones that fail a hard rubric criterion and merges duplicates. What is left
    enters the bracket.
-4. **Judge in pairs.** One task per comparison, a fresh agent each, so no
-   judge holds the whole field. The judge sees the two candidates and
-   the rubric and ends with `WINNER: <a|b> <reason>`. Winners meet in the
-   next round; add those tasks as the round closes.
+4. **Judge in pairs.** One [delegate call](tasks-or-calls.md#delegate-call) per comparison, a fresh agent
+   each, so no judge holds the whole field
+   ([tasks-or-calls](tasks-or-calls.md)). The judge sees the two
+   candidates and the rubric and ends with `WINNER: <a|b> <reason>`.
+   Record each round's results in the umbrella's note; winners meet in
+   the next round. A round wider than the cap runs in batches
+   ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
 5. **Confirm the winner** with a final check against the rubric, then
    merge it. Free the losing workspaces.
 

package/skills/mu/recipes/ultrathink.md

@@ -3,22 +3,24 @@
 Use when a task is too large or too risky for one context: a migration
 across many files, a repo-wide audit, a hard bug, a design with real
 alternatives, any long autonomous run where you will not read every
-line. Ultrathink composes the other recipes. Every unit of work, every
-check on it, and every round is a task in the DAG, so the run is as
-visible as the code it produces.
+line. Ultrathink composes the other recipes. Every unit, gate, finding
+and round is a task in the DAG, so the run is as visible as the code it
+produces; the checks on them are delegate calls whose verdicts land on
+those tasks.
 
 It costs many agents and many tokens. For a change one agent can hold
 and check, skip it.
 
 ## Steps
 
-1. **Fix done.** Write the goal and the stop rule on an umbrella task:
+1. **Define done.** Write the goal and the stop rule on an umbrella task:
    the command that must pass, the report that must exist, the criteria
    a reviewer will apply. Ask the human now for anything only they can
    decide (scope, budget, external actions); after this step, keep
    driving.
 2. **Understand before you change.** If the shape of the work is not
-   known, run a scout or a [fan-out](fan-out.md) of readers first. Their
+   known, run a scout ([delegate call](tasks-or-calls.md#delegate-call))
+   or a [fan-out](fan-out.md) of readers first. Their
    output is the unit list and the facts the plan needs, in notes.
 3. **Pick the shape** for the main phase:
 
@@ -29,7 +31,7 @@ and check, skip it.
    | a cause to find | [hypothesis-panel](hypothesis-panel.md) |
    | a choice between real alternatives | [tournament](tournament.md) |
    | an unknown amount, until a check passes | [loop-until-done](loop-until-done.md) |
-   | a backlog of external items | [triage](triage.md) |
+   | a backlog of external items | [backlog-triage](backlog-triage.md) |
    | a question across many sources | [deep-research](deep-research.md) |
    | one change to review from every angle | [review-panel](review-panel.md) |
    | a change against the repo's written rules | [rules-audit](rules-audit.md) |
@@ -42,8 +44,8 @@ and check, skip it.
    of a loop are the one exception: add each when the last closes.
 5. **Review every unit that ships.** Each commit-producing task gets a
    review task ([adversarial-review](adversarial-review.md)), on a
-   different model where you can. Findings and claims get refuters
-   instead.
+   different model where you can. Every finding is a triage task,
+   refuted before it is accepted ([findings](findings.md)).
 6. **Run the loop** ([orchestrator-loop](orchestrator-loop.md)): pipeline
    merges, verify each merge, keep workers busy
    ([waves](waves.md) when they share files). Long runs follow
@@ -54,12 +56,19 @@ and check, skip it.
    `mu task close <umbrella> --if-ready --evidence '...'`.
 
 Done when the umbrella is closed, its stop rule holds on the merged
-tree, and every shipped unit has a review task that closed `ACCEPT`.
+tree, every shipped unit's latest review task is `CLOSED/done`
+(ACCEPT), and
+`mu task list --substate triage` is empty or only `UNVERIFIED`.
 
 ## Budget
 
-- Agree a ceiling in step 1: concurrent agents and total agents. Write
-  it on the umbrella.
+- Agree a ceiling in step 1 and write it on the umbrella
+  ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
+- Checks are calls, not tasks ([tasks-or-calls](tasks-or-calls.md)): a
+  50-unit run should add about 50 units, 50 gates and the findings that
+  survive, not a task per refuter and judge.
+- The run gets its own workstream, `<project>-ut-<topic>`, torn down
+  when the umbrella closes ([recovery](recovery.md) before teardown).
 - Cheap models scout and find (`pi_mini`); the default builds (`pi`);
   strong models review, refute, judge, and synthesize (`pi_big`).
 - Calibrate on a slice: run the phase on a few units, check the result

package/skills/mu/recipes/watcher.md

@@ -13,4 +13,7 @@ acts on change. Run it in `scratch`, or in the workstream it serves.
    returns when an agent goes busy → idle.
 
 The ledger survives a dead or fresh helper: a replacement reads the
-last line and carries on.
+last line and carries on. To act on new items (issues, alerts), see
+[backlog-triage](backlog-triage.md).
+
+Done when the watched thing reaches its end state (PR merged, CI green) and the last ledger line says so.

package/skills/mu/recipes/waves.md

@@ -10,10 +10,11 @@ runs in its own `--workspace`; this recipe decides what each one gets.
    the shared files. A blanket freeze idled four of five workers for a
    day.
 3. **Pipeline the merge.** Cherry-pick each task as it closes and
-   verify the merged tree; never wait for the whole wave.
-4. **Refresh between waves.** `mu workspace refresh <agent>` rebases
-   onto main and keeps the agent's context. Dispatch the next wave only
-   from refreshed workspaces.
+   verify the merged tree ([orchestrator-loop § Merging](orchestrator-loop.md#merging));
+   never wait for the whole wave.
+4. **Refresh before each dispatch.** `mu workspace refresh <agent>`
+   rebases onto main and keeps the agent's context; run it before every
+   `--fresh` send, so each unit starts from the latest merge.
 
 Done when every task in the wave is `CLOSED/done`, merged, and the
-merged tree passes the gate.
+merged tree passes the gate command.

package/skills/mu/recipes/worker.md

@@ -18,7 +18,9 @@ mu task close <id> --evidence "tests pass: ..."  # LAST action
 ```
 
 The note follows the task note contract in SKILL.md. Commit before you
-close: the orchestrator cherry-picks your commits, not your tree.
+close: the orchestrator cherry-picks your commits, not your tree. A
+review or audit task records each problem per
+[findings § Record](findings.md#record).
 
 Done when the task is closed. Skipping close makes the orchestrator's
 wait hang. Won't do it: `close --as wontfix --why "..."`.