@mu-crew/mu 3.10.2 → 3.11.0

package/skills/mu/recipes/models.md

@@ -0,0 +1,102 @@
+# Model tiers
+
+Read when you pick a model for a spawn or a delegate call. mu passes the
+model through and never picks one; the choice is yours. Recipes name a
+tier (cheap, mid, strong, frontier) and say which one their roles need;
+this file says how to tell a model's tier.
+
+## Tiers
+
+Rank a model within its own family. The model-id prefix in
+`pi --list-models` (`anthropic/`, `openai/`, `google/`) names the family
+when it names a lab; the provider column is often one shared gateway, so
+it does not tell families apart.
+
+| Tier | Where it sits in its family | Names as of 2026-10 |
+| --- | --- | --- |
+| **frontier** | an exceptional tier above the lab's normal flagship, priced well above it, often gated | fable, astra |
+| **strong** | the lab's normal flagship | opus, sol |
+| **mid** | the everyday default | sonnet, terra |
+| **cheap** | the lab's small, fast hosted model | haiku, luna, flash, mini, nano, lite |
+| **local** | runs on this machine (ollama, lmstudio, llama.cpp) | qwen, gemma, gpt-oss |
+
+Names go stale within months; the position in the family does not. Rank
+a model you cannot place by the lab's own description of its lineup
+(flagship, balanced, fast). `pi --list-models` shows context and max
+output, not price or quality, and siblings often share both. Still
+unsure: run it on a small slice of the real work and compare it with a
+model you can place. Until then, pick conservatively: a model you know
+is strong enough for the work, and for a checker never one that might
+sit below the author.
+
+Thinking effort strengthens a model within its tier. It does not change
+the tier, and it does not stand in for another family.
+
+## Local models are a last resort
+
+A hosted cheap model beats a small local one at agent work: tool calls,
+long briefs, multi-step edits. Small local models lose the thread of a
+brief and fake tool results; in `pi --list-models` they tend to show
+thinking `no` and small context and output limits. Use one only when no
+hosted model is available, or the work must stay on the machine, and
+then only for cheap-tier work whose output something stronger checks. A
+local model never reviews, refutes or judges.
+
+## Roles
+
+| Work | Tier |
+| --- | --- |
+| fan-out scouting (listing units), searchers collecting quoted claims, watchers, first-pass finders | cheap |
+| building, refactoring, tests, routine fixes | mid |
+| review, refute, judge, audit, synthesize | the tier of whoever wrote the thing being checked, or higher; another family when one exists |
+| design, plans, incidents, root cause, final synthesis of a large run | strong |
+| a strong attempt failed, or the final judge of a close call | frontier; none available: the strongest model, from a family not yet used on the job |
+
+Cheap work suits bounded tasks whose output can be checked: a searcher's
+claim carries a quote a checker verifies. A cheap finder's misses stay
+missed, since refuters only test what was reported. When an omission is
+costly (a security audit, a coverage sweep), run the finders mid or
+strong, or add a second finder from another family.
+
+## Checkers
+
+A checker (reviewer, refuter, judge, auditor) must not share the
+author's blind spots. The author is whoever wrote the thing being
+checked: the worker for a diff, the planner for a brief, the finder for
+a finding.
+
+- **Level or up.** At least the author's tier; never down.
+- **Another family when one exists**, at that tier. One model's blind
+  spot repeated is still one blind spot.
+- **No peer in another family**: the same model, fresh context, higher
+  thinking unless at max.
+
+A delegate with no `model` runs the cli's configured default, which is
+your own model only if you are on that default. When the tier or family
+matters, pass `model`.
+
+## How to pass a model and effort level
+
+pi takes both in one `--model` value: `<provider/id>:<level>`, where the
+thinking (effort) level is one of `off`, `minimal`, `low`, `medium`,
+`high`, `xhigh`, `max`. Leave `:<level>` off to keep the model's default. With `:<level>`, pi
+reads the first segment as the provider, so copy `<provider>/<model>`
+exactly from `pi --list-models`. Through a gateway that is
+`modelbridge/anthropic/claude-sonnet-5-5:high`; `anthropic/…:high` fails
+with "No API key".
+
+- `mu_delegate`: `model: "<provider>/<model>:high"`.
+- Spawn: `mu agent spawn r -w <ws> --command "pi --model <provider>/<model>:high"`.
+- A `cli` key (`--cli pi_big`) works only if `$MU_<KEY>_COMMAND` is set
+  in the environment; check before you rely on one.
+- herdr refuses a command override, so neither model nor level can be
+  set per agent there: every helper runs the cli's default. The only
+  independence left is fresh context; say so in the verdict.
+
+Probe a model you have not used this session
+(`pi --model <id> -p "say ok"`); `ctl: ok` after spawn does not test the
+model.
+
+Done when the chosen `model` is placed in a tier, a checker is at the
+author's tier or higher and from another family (or the verdict says why
+not), and a model new this session answered `pi --model <id> -p "say ok"`.

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

@@ -6,10 +6,10 @@ 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).
+1. `mu state -w <ws>` — read agents, IN_PROGRESS, ready tasks.
+2. Spawn one agent per ready task, up to the ceiling below. Tasks that
+   edit the same files are chained with `block`, so only one is ready
+   ([waves](waves.md)).
 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
@@ -109,9 +109,7 @@ keep the note as the durable copy. pi:
 
 ## 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`.
+`mu agent abort <w>` first for pi, then `mu agent kick` (pi
+unresponsive, or non-pi), 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

@@ -38,20 +38,20 @@ 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. The exception:
-   tasks that edit the same files share a track ([waves](waves.md)).
+   edge serialises tasks that could run in parallel. The exception:
+   tasks that edit the same files are chained ([waves](waves.md)).
 7. **Self-review before dispatch.** Map each spec requirement to its
    task, grep the notes for placeholders, match INTERFACES names across
    tasks, and read the graph back (`mu task tree task_0 -w <ws> --down`).
    Then refute each brief that makes claims ([call](tasks-or-calls.md#delegate-call),
-   all in one turn): "What in this brief is false about the code,
+   all in one turn, at your tier from another family: [models](models.md#checkers)): "What in this brief is false about the code,
    ambiguous, or would make a correct worker fail review? Cite
-   file:line." Rewrite each AMEND. Five of six briefs refuted in one run had
+   file:line." Rewrite each REFUTED brief. Five of six briefs refuted in one run had
    such a defect, e.g. a fallback test old extensions made unpassable.
 
 Done when every spec requirement maps to a task, no note holds a
 placeholder, every claim-making brief has a verdict, and `mu state`
-shows the intended parallel tracks. Then dispatch per [orchestrator-loop](orchestrator-loop.md).
+lists the tasks you meant to run in parallel as Ready together. Then dispatch per [orchestrator-loop](orchestrator-loop.md).
 
 ## Notes
 

package/skills/mu/recipes/recovery.md

@@ -4,13 +4,10 @@ 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.
+- **`workstream teardown`** is reversible: `workstream list --torn-down`
+  lists the group ids to `mu undo`; the log is the backup.
+- **`mu undo`** restores rows only: killed panes and freed workspace
+  dirs do not come back. Redo = undo the undo.
 - **`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`.
@@ -28,4 +25,8 @@ when done in the wrong order.
   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.
+Done when, per operation: undo or teardown was previewed, then applied
+with `--yes`; rebuild was swapped in and agents re-spawned; `mu sync`
+lists the peer; forget touched only the named workstreams. Any
+`doctor --deep` DRIFT is backed up and reported to the human, and you
+read every cleanup command before you ran it.

package/skills/mu/recipes/refute.md

@@ -38,15 +38,18 @@ fact-check nobody will track, use delegate mode from
    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.
+and the accepted findings are fixed or handed off. The umbrella closes
+with `--if-ready` once no finding is open; while an `UNVERIFIED` finding
+remains it stays open and the human gets the list.
 
 ## 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`).
+- **Cheap finders, strong refuters.** Finders can run cheap when a
+  missed finding is affordable: refuters test what was reported, not
+  what was missed. Refuters run at the finder's tier or higher, and no
+  lower than mid, from another family ([models](models.md#checkers)).
 - **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

@@ -45,7 +45,8 @@ mu task claim t1 -w big --for worker-1 --evidence 'remote on dev'
 mu agent send worker-1 -w big --fresh '...'
 
 # 5. WAIT: pi: mu agent wait worker-1 -w big --after-runs <send's runs> --json,
-#    then the claim's Next: once. non-pi: run the claim's Next: once per turn
+#    then the claim's Next: once, after the worker reports done.
+#    non-pi: the same, once per reported-done turn
 
 # 6. COLLECT: fetch straight from the remote worktree
 git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
@@ -89,15 +90,15 @@ plus a 10 s cache.
 
 ### Step 5: poll once per turn
 
-The claim's `Next:` mule poll is mandatory. It proves the commit is on
-the host and closes the task. For a pi worker, first block on
+The claim's `Next:` mule poll closes the task as done on any change of
+the remote HEAD. Run it once, only after the worker reports done (its
+close or final answer). For a pi worker, first block on
 `mu agent wait <name> --after-runs <runs> --json`, with `runs` from
-`mu agent send --json`. It settles exactly over the forwarded socket.
-Without `--after-runs`, a worker that is already idle blocks until
-`--timeout`. If the worker may already be done, pass `<runs-1>`: the
-wait then returns the last answer at once. Then run `Next:` once instead
-of on every turn. On exit 5 (timeout), or on a wait that returns while
-the worker asks a question, run `Next:` anyway.
+`mu agent send --json`. It settles exactly over the forwarded socket,
+and it returns at once for a run that settled before the wait started.
+Pass `<runs>` unchanged. On exit 5 (timeout), or on a wait that returns
+while the worker asks a question, do not poll: read the pane
+(`mu agent read <name> -n 20`) and answer.
 
 - Never `sleep` in a tool call. Aborting the loop can leave remote work
   and a capped channel running.
@@ -122,11 +123,16 @@ there with its warm dependencies:
 
 ```bash
 git cherry-pick <sha>
-git push -q "ssh://dev/~/hacking/<repo>.git" HEAD:refs/heads/main
-mule run --cwd ~/hacking/<checkout> --wait \
-  'git fetch -q origin && git reset -q --hard origin/main && npm run check'
+git push -q "ssh://dev/~/hacking/<repo>.git" HEAD:refs/heads/gate-tmp
+mule run --cwd ~/hacking/<gate-checkout> --wait \
+  'git fetch -q origin gate-tmp && git checkout -q --detach FETCH_HEAD && npm run check'
 ```
 
+`<gate-checkout>` is a scratch checkout or worktree used only for
+gates, never one holding work. Push to a temporary ref, never `main`;
+delete it afterwards (`git push origin :gate-tmp`). Push to `main` only
+after the gate passes.
+
 `--wait` exits with the suite's code. A bare ssh would hold the capped
 channel for minutes. Keep two gates local: platform-sensitive tests (macOS `ps` returns argv,
 Linux `ps -e` appends the environment, and a real bug lived there), and
@@ -307,8 +313,10 @@ command but cannot serve `git fetch`.
 et dev        # or your site's wrapper, such as `x2ssh -et dev`
 ```
 
-An aborted `et` or `x2ssh` leaves local processes behind. Run
-`pkill -f x2ssh` before retrying.
+An aborted `et` or `x2ssh` leaves local processes behind. Find them
+with `ps -o pid=,command= -ax | grep "[x]2ssh"` and kill only those of
+the aborted invocation (match its host or tty), not every x2ssh, before
+retrying.
 
 On a capped host: ET for you, mule for tooling, detached tmux for mu
 agents. None of them competes for the slot.

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

@@ -56,8 +56,9 @@ triage and the umbrella closes with `--if-ready` (workstream mode).
 
 - **Reviewers padding the list.** A panel that always finds ten things
   is guessing.
-- **Vary models across angles** ([Models](../SKILL.md#models-and-thinking-effort)); one model's blind spot
-  repeated five times is still one blind spot. In delegate mode pass
-  `model` to `mu_delegate`; `cli` keys exist only if `$MU_<KEY>_COMMAND` is set.
+- **Vary families across angles, not tiers.** Every reviewer is at the
+  author's tier or higher ([models](models.md#checkers)); one model's
+  blind spot repeated five times is still one blind spot. Pass `model`
+  to `mu_delegate`.
 - **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

@@ -28,22 +28,23 @@ rules are findings: [findings](findings.md) says where they live.
 2. **Pin the target**: the diff, branch, or PR, as in
    [review-panel](review-panel.md) step 1.
 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
+   The checker gets one rule and the diff. Delegate mode: end the answer
+   with `FINDING: … r7 …` lines. Workstream mode: one triage task per
+   violation ([findings § Record](findings.md#record); title
+   `<severity>: r7 <what>`). With no violation it 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
+4. **A skeptic pass** over the findings, 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). In workstream mode, a dropped flag is
+   exception). In workstream mode, a dropped finding is
    `close --as rejected --why "<why the rule does not bite here>"`; a
    confirmed one is accepted with `--evidence` naming the flagged line
    ([findings § Triage](findings.md#triage) step 3; quoting:
    [brief § Quoting](brief.md#quoting)).
 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
+Done when every rule from step 1 has a checker result, and every finding
 is decided.
 
 ## Mine: rules you keep stating but never wrote

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

@@ -7,7 +7,8 @@ hundreds of tasks and a workstream nobody wanted.
 
 ## Delegate call
 
-A **delegate call** is one `mu_delegate` tool call in pi.
+A **delegate call** is one `mu_delegate` tool call in pi, or outside pi
+a `scratch` spawn + `send --fresh` + `wait --after-runs` (below).
 
 - **It starts empty.** The brief carries everything: the finding or
   claim, file paths, the criteria, and the answer to end with. See
@@ -80,9 +81,9 @@ 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).
+Cap and queue: [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.
+or a delegate call whose answer landed where its step says: a
+`REFUTER` note on the task it judged, a `WINNER` line in the umbrella's
+note, or a unit list in the umbrella's note.

package/skills/mu/recipes/tournament.md

@@ -35,7 +35,10 @@ final check passed.
 - **Position bias.** Judges favour the first candidate shown. For close
   calls, judge the pair twice with the order swapped; a split decision
   goes to a third judge.
-- **Same model, same taste.** Vary the attempt models, and judge with a
-  model that made no attempt ([Models](../SKILL.md#models-and-thinking-effort)).
+- **Same model, same taste.** Vary the attempts across families at the
+  same tier, and judge with a model that made no attempt, at that tier
+  or above ([models](models.md#checkers)). A close final goes to a
+  frontier judge, or with none available, the strongest model from a
+  family that made no attempt.
 - **Ranking many items** (tickets by severity): bucket them in parallel,
   then run pairwise comparisons only within and across bucket edges.

package/skills/mu/recipes/ultrathink.md

@@ -44,7 +44,7 @@ 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
-   [comparable model](../SKILL.md#models-and-thinking-effort). Every finding is a triage task,
+   [comparable model](models.md#checkers). 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
@@ -58,7 +58,7 @@ and check, skip it.
 Done when the umbrella is closed, its stop rule holds on the merged
 tree, every shipped unit's latest review task is `CLOSED/done`
 (ACCEPT), and
-`mu task list --substate triage` is empty or only `UNVERIFIED`.
+`mu task list --substate triage` is empty.
 
 ## Budget
 
@@ -69,8 +69,10 @@ tree, every shipped unit's latest review task is `CLOSED/done`
   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`).
+- Tiers per phase ([models](models.md#roles)): cheap scouts and finds,
+  mid builds, strong plans and synthesizes; each checker at the tier of
+  whoever wrote what it checks, or higher, another family. Calibrate the
+  tier split on the slice, not only the cost.
 - Calibrate on a slice: run the phase on a few units, check the result
   and the cost, then fan out the rest.
 

package/skills/mu/recipes/watcher.md

@@ -12,6 +12,10 @@ acts on change. Run it in `scratch`, or in the workstream it serves.
 3. **Wait with mu, not `sleep`.** `mu agent wait <names...> --first`
    returns when an agent goes busy → idle.
 
+A watcher runs cheap (hosted): polling and diffing a ledger line needs
+no judgement. It hands anything that does to you or a stronger helper
+([models](models.md#roles)).
+
 The ledger survives a dead or fresh helper: a replacement reads the
 last line and carries on. To act on new items (issues, alerts), see
 [backlog-triage](backlog-triage.md).

package/skills/mu/recipes/waves.md

@@ -4,8 +4,8 @@ Use when two or more workers edit the same repo at once. Every worker
 runs in its own `--workspace`; this recipe decides what each one gets.
 
 1. **Bucket by file cluster, not severity.** Two agents editing one
-   file conflict, whatever the priority. Put tasks that share files on
-   one track (`mu task block`) so only one agent holds them.
+   file conflict, whatever the priority. Chain tasks that share files
+   (`mu task block B --by A`) so only one is ready at a time.
 2. **Freeze only what conflicts.** Give idle workers tasks that avoid
    the shared files. A blanket freeze idled four of five workers for a
    day.
@@ -13,8 +13,9 @@ runs in its own `--workspace`; this recipe decides what each one gets.
    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.
+   rebases onto the tracked main (git: `origin/HEAD`, so unpushed local
+   merges are missed; pass `--from <local-branch>` to include them) and
+   keeps the agent's context; run it before every `--fresh` send.
 
 Done when every task in the wave is `CLOSED/done`, merged, and the
 merged tree passes the gate command.

package/skills/mu/recipes/worker.md

@@ -13,7 +13,7 @@ mu me
 mu me next
 mu task show <id>; mu task notes <id>
 mu task claim <id> --evidence "starting; read notes"
-mu task note <id> "FILES: ...\nDECISION: ...\nVERIFIED: ..."
+mu task note <id> "FILES: ...\nCOMMANDS: ... (exit codes)\nDECISION: ...\nVERIFIED: ..."
 mu task close <id> --evidence "tests pass: ..."  # LAST action
 ```
 
@@ -23,5 +23,5 @@ you only between tool calls. Commit before you close: the orchestrator cherry-pi
 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
+Done when your changes are committed in the workspace, the task note holds FILES, COMMANDS (with exit codes) and VERIFIED, and `mu task close` succeeded as your last action. Skipping close makes the orchestrator's
 wait hang. Won't do it: `close --as wontfix --why "..."`.