@mu-crew/mu 3.10.1 → 3.11.0

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 "..."`.