@mu-crew/mu 3.2.0 → 3.3.0

package/skills/mu/recipes/codemode-driver.md

@@ -0,0 +1,54 @@
+# Codemode driver
+
+Use when a pi orchestrator with the `codemode` tool runs a recipe with
+many parallel units, and one tool call per spawn, send, and wait is
+slow. A script can issue those calls in parallel. It stays a driver:
+the plan, the state, and the results live in the DB.
+
+## The rule
+
+**Delete the script mid-run and nothing is lost.** That holds when:
+
+- The script calls only `mu` verbs, through `tools.bash`. It reads
+  state with `mu state --json` / `mu task notes`, never from its own
+  variables across calls.
+- Every task it dispatches exists in the DAG before the script starts.
+  The script adds no tasks the orchestrator has not planned, except the
+  ones a recipe step names (the next round, a `fix_` task).
+- `store()` / `load()` hold nothing a re-run needs. The DAG is the
+  cursor.
+- The script's source goes into the log before it runs:
+  `mu log -w <ws> --kind driver '<what it does, which tasks>'`.
+
+## Shape
+
+```js
+// @options: {"timeout_ms": 1800000}
+const ws = "audit";
+const sh = async (c) => {
+  const r = await tools.bash({ command: c });
+  if (r.exit_code !== 0) throw new Error(`${c}: ${r.output}`);
+  return r.output;
+};
+const ready = JSON.parse(await sh(`mu task next -w ${ws} -n 0 --json`)).items;
+await Promise.allSettled(ready.slice(0, 4).map(async (t, i) => {
+  const w = `worker-${i + 1}`;
+  await sh(`mu task claim ${t.name} -w ${ws} --for ${w} --evidence 'driver dispatch'`);
+  await sh(`mu agent send ${w} -w ${ws} --fresh 'Work on ${t.name}. Read: mu task notes ${t.name} -w ${ws}'`);
+}));
+const wait = await tools.bash({ command: `mu task wait -w ${ws} ${ready.slice(0, 4).map((t) => t.name).join(" ")} --first --on-stall exit --json` });
+return wait.output;
+```
+
+Check field names against `--json` output before relying on them; the
+script above is a shape, not an API.
+
+## Traps
+
+- **One wave per script.** A script that loops forever hides progress
+  from you and from the human. Dispatch, wait for the first close,
+  return; merge and verify outside the script, then run it again.
+- **A script timeout cancels the waits, not the workers.** Workers keep
+  running and their tasks stay claimed. Re-read `mu state` and carry on.
+- **Exit codes are data.** `mu task wait` exit 7 means a worker needs
+  you; return it to the model instead of retrying.

package/skills/mu/recipes/deep-research.md

@@ -0,0 +1,52 @@
+# Deep research
+
+Use when a question needs more sources than one context can read and
+checking them against each other: how a library or protocol behaves,
+what changed between versions, how competitors solve a problem, whether
+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.
+
+## Steps
+
+1. **Write the question and the bar** on an umbrella task: 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,
+   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:
+
+   ```text
+   CLAIM: c4 "Node 22 enables the permission model by default" SOURCE: <url> QUOTE: "<exact words>"
+   ```
+
+   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
+   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
+   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.
+
+Done when every claim the answer uses has a `CONFIRMED` verdict line,
+every sentence of fact in the report cites a URL, and the report meets
+the bar from step 1.
+
+## Traps
+
+- **A fetch failure is UNVERIFIED, not REFUTED.** Rate limits and
+  paywalls block checkers; say so, do not drop the claim silently.
+- **Secondary sources copy each other.** Three blog posts repeating one
+  changelog are one source. Prefer the primary source in the dedupe.
+- **Version drift.** A claim true for v2 can be false for v3. Checkers
+  confirm the version the question asks about.

package/skills/mu/recipes/fan-out.md

@@ -0,0 +1,36 @@
+# Fan-out
+
+Use when the same treatment applies to many units: files, call sites,
+failing tests, findings, modules. One context holding 50 units drops
+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
+   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.
+2. **One task per unit**, blocked into an umbrella:
+
+   ```bash
+   mu task add sweep -w <ws> -t "Sweep: <goal>" -i 60 -e 1 --note 'UNITS: 37 (rg -l ... | wc -l)'
+   mu task add sweep_auth_ts -w <ws> -t "Sweep src/auth.ts" -i 50 -e 0.2
+   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
+   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.
+
+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/hypothesis-panel.md

@@ -0,0 +1,40 @@
+# Hypothesis panel
+
+Use for root-cause work: a flaky test, an intermittent bug, a metric
+that moved. One agent that forms a theory then tests its own theory
+finds evidence for it. Separate agents, each given different evidence,
+form independent theories; separate agents then try to kill them.
+
+## Steps
+
+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>
+   ```
+
+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>`.
+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.
+5. **If none survives**, start another round
+   ([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
+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
+  50 failure. Put the run count in step 1.

package/skills/mu/recipes/long-run.md

@@ -0,0 +1,20 @@
+# Long runs
+
+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
+   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
+   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.
+
+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

@@ -0,0 +1,38 @@
+# Loop until done
+
+Use when the amount of work is unknown: fix type errors until clean,
+find flaky tests until none are new, search until nothing new turns up.
+A fixed number of passes stops too early or runs too long; a stop rule
+written down first does neither.
+
+## Steps
+
+1. **Write the stop rule** on the umbrella before the first round. It
+   names a command and a condition, plus a no-progress rule:
+
+   ```text
+   STOP: `npx tsc --noEmit` exits 0
+   NO-PROGRESS: two rounds in a row reduce the error count by zero
+   ```
+
+2. **Each round is a task**, blocked by the previous one:
+   `round_1`, `round_2`, .... Add the next round only when the current
+   one closes; never pre-create rounds.
+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.
+   - 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.
+   - Otherwise: add the next round and dispatch it.
+
+Done when the stop rule holds on the merged tree, run by you.
+
+## Traps
+
+- **A round that only reports is not progress.** Each round must change
+  something (fix, new search slice) or produce a new measurement.
+- **Moving goalposts.** Edit the stop rule only with a note saying why;
+  the old rule stays in the history.

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

@@ -0,0 +1,87 @@
+# Orchestrator loop
+
+Use when you run a workstream: you dispatch DAG tasks to workers and
+merge their commits. The hard rules in SKILL.md still apply; this is
+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.
+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,
+   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`.
+
+## 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
+pane (`mu agent read <owner>`) and answer: the worker may be waiting on
+you. Questions are cheaper than rework.
+
+For an idle worker, read the pane, then answer, retry, or release its
+task. `MU_IDLE_THRESHOLD_MS` defaults to 5m.
+
+## Merging
+
+- **Pipeline; don't barrier.** Wait for one task, cherry-pick only its
+  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
+  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
+  worker's "done" counts only once the diff shows the change.
+- **Ask whether the check could have failed.** A gate that cannot say
+  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
+
+- A plain `mu agent send` appends to prior context; use it to steer or
+  answer. Unrelated work to pi: `mu agent send worker-1 --fresh 'Claim
+  task_x...'`.
+- claude-code/codex: send `/new` (codex: `/clear`), then the prompt; a
+  send it cannot confirm prints a `warning:` on stderr. For pi,
+  `--fresh` does both in one step.
+- Use `mu agent send`, not raw mux input. Single-quote prompts
+  containing shell expansions, or use a quoted heredoc.
+- Cross-workstream wait and claim use qualified refs; only task
+  ownership crosses.
+
+## 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`.

package/skills/mu/recipes/plan.md

@@ -0,0 +1,54 @@
+# Planning a DAG
+
+Use when you turn a spec or a clear set of requirements into tasks.
+The DAG is the plan: each task's note carries its full content, and
+`mu state` is the progress tracker. Write a markdown plan only when the
+human asks for a file.
+
+## Steps
+
+1. **Map the files first.** List what gets created or changed and what
+   each file is responsible for. Task boundaries fall out of this map.
+2. **Size the tasks.** A task is the smallest unit that carries its own
+   verification and is worth a review. Split only where a reviewer
+   could reject one task and accept its neighbour. Fold setup, config,
+   and docs into the task whose deliverable needs them.
+3. **Write the root task.** `task_0` holds the goal, the architecture
+   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):
+
+   ```text
+   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>
+   STEPS:      one action each; code steps carry the code
+   VERIFY:     <exact command and expected result>
+   ```
+
+   The worker sees only its own task. INTERFACES is how it learns the
+   names its neighbours use.
+5. **No placeholders.** "TBD", "add error handling", "similar to
+   task 3", "write tests for the above": each is a missing decision the
+   worker will make alone. Write the actual content; tasks are read out
+   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.
+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.
+
+## Notes
+
+- `impact` comes from what breaks without the task; `effort_days` from
+  its step count. Guess honestly rather than defaulting to 50 and 1.
+- Review gates follow [adversarial-review](adversarial-review.md): a
+  review task blocked by the work.
+- When reality disagrees with the plan, append a note saying so. Do not
+  rewrite earlier notes.

package/skills/mu/recipes/recovery.md

@@ -0,0 +1,26 @@
+# Recovery: undo, rebuild, sync
+
+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.
+- **`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`.
+- **Sync:** set `MU_SYNC_DIR` on each machine to a shared folder
+  (Syncthing). Every command flushes and ingests ops, merged per field.
+  mu never runs ssh or rsync; `mu sync` prints the line.
+  `--repair <peer>` is always safe. Agents, workspaces, and task
+  ownership never travel.
+- **`mu doctor --deep` DRIFT** (exit 5) is a capture bug: back up and
+  report it. Do not rebuild; the live rows may hold work the log missed.
+- 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.

package/skills/mu/recipes/refute.md

@@ -0,0 +1,49 @@
+# 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).
+
+## 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:
+
+   ```text
+   FINDING: f3 src/routes/user.ts:42 high: handler skips the auth check on PUT
+   ```
+
+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
+   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.
+
+## 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`).
+- **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.