@mu-crew/mu 3.7.0 → 3.8.0

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

@@ -6,15 +6,25 @@ or may hit flakes.
 1. **Define 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.
+   the bar, not at the first green. For chained batches (sweeps,
+   campaigns, soaks) it also names the **inputs** each batch runs on
+   (build sha, oracle commit, config) and when to refresh them
+   ("rebuild from main before each batch"); each batch report states
+   the inputs it used, and the stop rule counts only batches on
+   current inputs.
 2. **Split into independent units** ([fan-out](fan-out.md)). 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**
-   ([orchestrator-loop § Merging](orchestrator-loop.md#merging)).
+4. **Bound each tool call** to minutes: batches of ≤10 minutes,
+   `mu task wait --timeout` re-issued, no open-ended `sleep` loops.
+   A `--steer` lands only when the running tool returns.
+5. **Accept evidence, not close notes**
+   ([orchestrator-loop § Merging](orchestrator-loop.md#merging)), and
+   run a [drift-audit](drift-audit.md) after each batch report and
+   every few hours.
 
 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

@@ -25,11 +25,12 @@ written down first does neither.
    `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: `mu task close <umbrella> --if-ready --evidence '<stop
-     command + result>'` (each round blocks the umbrella).
+   - Rule met: `mu task close <umbrella> --if-ready --evidence "<stop
+     command + result>"` (each round blocks 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.
+     `mu task park <umbrella> --why "<what is stuck>"` and tell the human.
+     Prose reasons: [brief § Quoting](brief.md#quoting).
    - Otherwise: add the next round and dispatch it.
 
 Done when the stop rule holds on the merged tree, run by you.

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

@@ -39,8 +39,8 @@ keeps it.
 - **Answers arrive when you stop**, as pi follow-up messages, never
   mid-turn. pi's `followUpMode: "all"` delivers every waiting answer in
   one turn instead of one turn each; each answer names its delegate and
-  ends with its `VERDICT: <id>` line, so a batch still maps back. Record
-  every verdict in the batch before acting on any.
+  ends with its `VERDICT: <id>` block, so a batch still maps back. Read
+  every verdict in the batch before deciding any.
 - **Workers with workspaces** build and test: about one per CPU core,
   fewer when each runs the full suite. A remote host has its own
   session cap ([remote-workers](remote-workers.md)).
@@ -79,7 +79,8 @@ per turn ([remote-workers](remote-workers.md#step-5-poll-once-per-turn)).
   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.
+  worker's "done" counts only once the diff shows the change. Your own
+  accept and close notes name the check run and the commit.
 - **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
@@ -87,16 +88,24 @@ per turn ([remote-workers](remote-workers.md#step-5-poll-once-per-turn)).
 
 ## 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...'`.
+A running worker sees what you send, never a new task note: deliver
+an instruction for it with a send (or the next `--fresh` brief), and
+keep the note as the durable copy. pi:
+
+| `mu agent send` | busy pi acts | Use for |
+| --- | --- | --- |
+| plain | after the run ends | answers, same-task additions |
+| `--steer` | after the current tool call | advice that can wait for the tool boundary |
+| `--interrupt` | now: kills the running tool | a correction that wastes the current work (stale input, wrong target, changed stop rule) |
+| `--fresh` | refused (`--force` drops the run) | unrelated work: new session + prompt |
+
 - 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.
+  send it cannot confirm prints a `warning:` on stderr.
+- Use `mu agent send`, not raw mux input. Quote prompts per
+  [brief](brief.md#quoting).
 - Cross-workstream wait and claim use qualified refs; only task
   ownership crosses.
+- A long run drifts unseen: audit it per [drift-audit](drift-audit.md).
 
 ## Stopping a worker
 

package/skills/mu/recipes/plan.md

@@ -40,14 +40,18 @@ human asks for a file.
    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)).
-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.
+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,
+   ambiguous, or would make a correct worker fail review? Cite
+   file:line." Rewrite each AMEND. 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, and `mu state` shows the intended parallel tracks. Then
-dispatch per [orchestrator-loop](orchestrator-loop.md).
+placeholder, every claim-making brief has a verdict, and `mu state`
+shows the intended parallel tracks. Then dispatch per [orchestrator-loop](orchestrator-loop.md).
 
 ## Notes
 

package/skills/mu/recipes/refute.md

@@ -27,8 +27,9 @@ fact-check nobody will track, use delegate mode from
    [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.
-   Record its verdict on the finding, and apply the skip and
-   three-refuter rules, as in [findings § Triage](findings.md#triage).
+   Pass `record` so its verdict lands 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).

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

@@ -56,7 +56,7 @@ triage and the umbrella closes with `--if-ready` (workstream mode).
 
 - **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.
+- **Vary models across angles** ([Models](../SKILL.md#models-and-thinking-effort)); one model's blind spot
+  repeated five times is still one blind spot.
 - **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

@@ -37,7 +37,10 @@ rules are findings: [findings](findings.md) says where they live.
    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.
+   `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
@@ -62,10 +65,12 @@ is decided.
    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`.
+4. **Refute each candidate** with a
+   [delegate call](tasks-or-calls.md#delegate-call) that passes
+   `record`: 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 --why` naming the deciding answer.
 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

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

@@ -7,34 +7,49 @@ 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):
+A **delegate call** is one `mu_delegate` tool call in pi.
 
-```bash
-mu agent spawn refuter-1 -w scratch
-runs=$(mu agent send refuter-1 -w scratch --fresh '<brief>' --json | jq .runs)
-mu agent wait refuter-1 -w scratch --after-runs "$runs" --json   # answer in lastText
-```
+- **It starts empty.** The brief carries everything: the finding or
+  claim, file paths, the criteria, and the answer to end with. See
+  [brief](brief.md). A tournament judge ends with `WINNER: ...`
+  ([tournament](tournament.md)). A refuter or claim checker passes
+  `record: { task: "<ws>/<id>" }` and ends with:
 
-`--after-runs` takes the run count the send reported, so a run that
-finished before the wait started still counts. A plain wait would sit
-until `--timeout`.
+  ```text
+  VERDICT: <id> CONFIRMED|REFUTED|UNVERIFIED <one line>
+  EVIDENCE: <file:line or command + result>   (3-6 lines)
+  ```
 
-- **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.
+- **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 (or always, with `keep: true`).
 - **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`).
 
+Without the tool, write the note `record` would, before deciding:
+
+```bash
+mu agent spawn refuter-1 -w scratch
+runs=$(mu agent send refuter-1 -w scratch --fresh - --json <<'EOF' | jq .runs
+<brief, ending with the VERDICT block>
+EOF
+)
+mu agent wait refuter-1 -w scratch --after-runs "$runs" --json   # answer in lastText
+mu task note <id> -w <ws> - <<'EOF'
+REFUTER 1 (refuter-1, 4m 05s):
+<the VERDICT line and EVIDENCE lines, verbatim>
+EOF
+mu agent close refuter-1 -w scratch
+```
+
+A wait that times out or dies leaves `REFUTER 1: no verdict (<outcome>)`.
+`--after-runs` counts a run that finished before the wait started; the
+quoted heredocs keep the evidence verbatim ([brief § Quoting](brief.md#quoting)).
+
 ## The rule
 
 **A task is a thing the graph tracks. Checking a thing is a call.**
@@ -47,17 +62,15 @@ until `--timeout`.
 | 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.
+A call adds no node: its note and your decision land on the task it
+judged ([findings § Triage](findings.md#triage)).
 
 ## 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.
+- 30 findings to refute: 30 delegate calls, 0 new tasks; each finding
+  gets a `REFUTER` note, then your decision.
+- A tournament over 16 names: 15 judge calls; each round's `WINNER:`
+  lines go on the umbrella.
 - A hypothesis test that reverts commits or forces a race needs a
   workspace: that one is a task.
 

package/skills/mu/recipes/tournament.md

@@ -20,8 +20,9 @@ reliable than scoring one.
    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
+   A judge decides a pair, not a task: no `record`. Record each round
+   (pair, winner, reason) 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.
@@ -35,6 +36,6 @@ final check passed.
   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.
+  model that made no attempt ([Models](../SKILL.md#models-and-thinking-effort)).
 - **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

@@ -43,8 +43,8 @@ and check, skip it.
    [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,
+   review task ([adversarial-review](adversarial-review.md)) on a
+   [comparable model](../SKILL.md#models-and-thinking-effort). 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

package/skills/mu/recipes/worker.md

@@ -17,8 +17,9 @@ 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
+The note follows the task note contract in SKILL.md. Keep each tool
+call to minutes (short batches, waits with a timeout): steering reaches
+you only between tool calls. 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).