@mu-crew/mu 3.2.1 → 3.4.0

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

@@ -0,0 +1,83 @@
+# Rules audit
+
+Use when the repo's written rules (`AGENTS.md`, contributing guides,
+style docs) are not being followed, or when the same correction keeps
+coming up in review and is not written down. One agent checking a diff
+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 (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"
+   ```
+
+   Skip rules no diff can show (team habits, meeting norms). Record the
+   count.
+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
+   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). 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
+is decided.
+
+## Mine: rules you keep stating but never wrote
+
+1. **Collect corrections.** Sources, any that exist: review comments
+   on merged PRs, `REJECT` notes from [adversarial-review](adversarial-review.md)
+   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
+   (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 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. **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)? 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.
+
+## Traps
+
+- **A rule a tool can check belongs in the tool.** If a linter, type,
+  or test can catch it, propose that instead of prose.
+- **Mined rules overfit.** Two corrections in one week about one file
+  may be about that file, not a rule. The refute step asks.

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

@@ -0,0 +1,67 @@
+# 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 or timeout (`keep: true` always keeps it); the bash form needs
+  `mu agent close <name> -w scratch`. You record its verdict on the task
+  it judged.
+
+## 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.
+
+Run calls within the delegate cap (`MU_DELEGATE_MAX`, default 16; 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

@@ -0,0 +1,40 @@
+# Tournament
+
+Use when several answers are possible and the best is a judgement
+call: a design, a name, an API shape, competing fixes, a ranking. Agents
+compete on the same task; judges compare pairs. Comparing two is more
+reliable than scoring one.
+
+## Steps
+
+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 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 [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.
+
+Done when one candidate has won every comparison it entered and the
+final check passed.
+
+## Traps
+
+- **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.
+- **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

@@ -0,0 +1,82 @@
+# Ultrathink
+
+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, 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. **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 ([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:
+
+   | The work is | Recipe |
+   | --- | --- |
+   | the same change over many units | [fan-out](fan-out.md) |
+   | finding problems or checking claims | [refute](refute.md) |
+   | 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 | [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) |
+
+   Phases chain: an audit (refute) feeds a fix sweep (fan-out); a
+   tournament picks the design a fan-out then implements.
+4. **Plan the whole phase as tasks** before spawning: every unit,
+   blocked into the umbrella, each note written as a
+   [brief](brief.md) ([plan](plan.md) for a spec-driven build). Rounds
+   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. 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
+   [long-run](long-run.md). With codemode, a
+   [driver](codemode-driver.md) can dispatch a wave.
+7. **Close against the stop rule**, checked by you on the merged tree,
+   not by any worker's note. Then
+   `mu task close <umbrella> --if-ready --evidence '...'`.
+
+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`.
+
+## Budget
+
+- 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
+  and the cost, then fan out the rest.
+
+## What the human sees
+
+`mu state` shows every unit, its reviewer, and what is still running.
+`mu task notes <id>` shows why any unit was accepted or rejected. A
+rejected unit stays in the DAG next to its fix. Nothing about the run
+lives only in your context.

package/skills/mu/recipes/watcher.md

@@ -0,0 +1,19 @@
+# Watcher
+
+Use when a helper polls something outside mu (a PR, CI, a log) and
+acts on change. Run it in `scratch`, or in the workstream it serves.
+
+1. **Keep last-seen state in a log ledger**, not in the helper's
+   context. Write one line per observation:
+   `mu log -w scratch --kind pr-state 'pr=1234 sha=abc ci=red'`.
+2. **Read the last entry before acting:**
+   `mu log -w scratch --kind pr-state -n 1 --json`.
+   Act only when the new observation differs.
+3. **Wait with mu, not `sleep`.** `mu agent wait <names...> --first`
+   returns when an agent goes busy → idle.
+
+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).
+
+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

@@ -0,0 +1,20 @@
+# Waves: several workers in one repo
+
+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.
+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.
+3. **Pipeline the merge.** Cherry-pick each task as it closes and
+   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 command.

package/skills/mu/recipes/worker.md

@@ -0,0 +1,26 @@
+# Worker loop
+
+Use when you are the worker: a task was claimed for you, or you were
+told to claim one.
+
+`$MU_AGENT_NAME` (injected at spawn) resolves identity; adopted panes
+fall back to the pane title. In a worker pane, bare `mu task claim <id>`
+works. In the unregistered orchestrator pane it errors; use `--self`,
+`--for <worker>`, or `mu agent adopt <pane>`.
+
+```bash
+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 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. 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 "..."`.