@mu-crew/mu 3.7.0 → 3.8.0

package/docs/ARCHITECTURE.md

@@ -120,7 +120,7 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | `src/agents/spawn.ts` | spawn: CLI resolution, pane create or reuse, liveness, readiness, ctl handshake, rollback |
 | `src/agents/spawn-lock.ts` | per-session lock around topology and row insert |
 | `src/agents/transport.ts` | send routing: ctl for pi agents, mux paste otherwise, no fallback; `expectsCtl` |
-| `src/agents/abort.ts` | stop a pi turn through the control socket |
+| `src/agents/abort.ts` | stop a pi turn through the control socket; abort + send (`--interrupt`) |
 | `src/agents/delegate.ts` | `delegateOutcome`: one wait result to `done` / `empty` / `died` / `timeout` / `pending` |
 | `src/agents/wait.ts` | block until task-less agents leave `busy` |
 | `src/agents/adopt.ts` | register an existing pane as an agent |
@@ -139,7 +139,7 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | `src/ctl/client.ts` | `ctlRequest`, `ctlProbe`, version and unknown-op errors |
 | `extension/mu-pi.ts` | pi extension, child side: serves `$MU_CTL_SOCK`; built to `dist/extension/mu-pi.js` |
 | `extension/delegate.ts` | pi extension, parent side: `mu_delegate` / `mu_delegate_cancel`, which shell out to `mu` |
-| `extension/nudge.ts` | pi extension: the keep-driving nudge. Arms on a `mu` dispatch, checks `mu state --json` at `agent_before_settle`, injects the SKILL.md rule once per prompt, logs `--kind nudge` |
+| `extension/nudge.ts` | pi extension: the keep-driving nudge. Arms on a `mu` dispatch, checks `mu state --json` at `agent_before_settle`, injects the SKILL.md rule once per prompt, logs `--kind nudge`. Also the close nudge (worker settles owning a task) and the refute nudge (`task claim --for` on a task with no refute decision in `mu task notes --json`; one notice, no continuation) |
 | `src/link.ts` | `mu link pi`: extension shim, skill symlink, `inspectLinks` for doctor |
 
 ### Tasks, workspaces and workstreams
@@ -168,7 +168,8 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | `src/cli.ts` | Commander wiring (`buildProgram`) |
 | `src/cli/*.ts` | one file per verb namespace, thin wrappers over the SDK; `format.ts` renders tables, `handle.ts` maps errors to exit codes and runs ambient sync |
 | `src/cli/tasks/*.ts` | the `mu task` namespace, including `mu me tasks` / `mu me next` |
-| `src/cli/dispatch-hints.ts` | dispatch-time `Next:` hints for pi agents (`--fresh`, `--steer`, abort) |
+| `src/cli/dispatch-hints.ts` | dispatch-time `Next:` hints for pi agents (`--fresh`, `--interrupt`, abort) |
+| `src/cli/stdin.ts` | `-` as a text argument: reads note / send text from stdin (heredoc prose) |
 | `src/cli/agents-remote.ts` | `mu agent remote-env`: prints the ssh forward and env, runs nothing |
 | `src/cli/tui-launch-focus.ts` | initial-tab focus ladder for bare `mu` and `mu state --tui` |
 | `src/cli/tui/` | the ink TUI; the only place ink and react are imported |

package/docs/architecture/control-socket.md

@@ -32,6 +32,7 @@ reply carries `v: 1`; the client (`src/ctl/client.ts`) throws
 | `send` | `pi.sendUserMessage`; when busy, `mode` is `steer` or `followUp` (default). Replies with the `status` fields measured before the dispatch, so `runs` is the baseline for a later `wait` |
 | `wait` | resolves on pi's `agent_settled` after `afterRuns`, with the run's `lastText` |
 | `abort` | `ctx.abort()` (pi's Esc) |
+| `interrupt` | busy: `ctx.abort()`, wait for `agent_settled` (up to `timeoutMs`), then `pi.sendUserMessage(text)` as a new run; idle: just the send. Replies `wasBusy`, `pending` (measured before the abort) and the `status` fields measured after the settle and before the send, so `runs` is the `wait` baseline for the new run. `timeout`: nothing sent |
 | `fresh` | new session plus prompt as one operation, through the internal `/mu-fresh` command; replies once the new run starts; refused with `busy` unless `force` |
 | `command` | `name` `new`, `reload` or `compact` (with optional `instructions`), through the internal `/mu-new`, `/mu-reload`, `/mu-compact` commands, which call `ctx.newSession()`, `ctx.reload()`, `ctx.compact()`. `new` replies once the session is replaced, `reload` after the `session_start` it causes, `compact` when compaction starts or with pi's error (`Nothing to compact ...`). Refused with `busy` unless `force` |
 
@@ -41,13 +42,14 @@ extension command, triggered with `expandPromptTemplates: true`, and
 its handler gets the command context that can replace or reload the
 session.
 
-These back `mu agent send` (`--fresh`, `--steer`, session commands), `mu agent wait`,
+These back `mu agent send` (`--fresh`, `--steer`, `--interrupt`, session commands), `mu agent wait`,
 `mu agent abort`, the agent state reading, and `mu_delegate`.
 
 ## Version skew
 
 An op the extension does not serve returns `unknown op: <op>` with its
-`ops` list. mu raises `AgentExtensionOutdatedError` (exit 4), whose
+`ops` list. `mu agent send --interrupt` then composes `abort`, `wait`
+and `send` itself. Any other op raises `AgentExtensionOutdatedError` (exit 4), whose
 next steps are `/reload` through the mux (an extension that lacks the
 `command` op cannot run it over ctl) or a respawn. `mu doctor`
 probes every pi agent's socket (the `ctl` row) and flags an
@@ -68,7 +70,10 @@ row reports whether `mu link pi` installed the extension.
 
 1. If the path already answers, another pi serves it (a nested `pi -p`
    inherited `MU_CTL_SOCK`). The extension leaves it alone and says so
-   on stderr.
+   on stderr. Identity follows the bind: that pi, and one that loses
+   the `link()` race, is nested and gets no keep-driving, close or
+   refute nudge, though it inherited the agent's `MU_AGENT_NAME`.
+   The decision lives in the process-global map, so `/reload` keeps it.
 2. Otherwise it listens on a private name in the same directory, sets
    mode 0600, and hard-links that name onto the public path. libuv
    unlinks the listened-on name at close, so the public path must never

package/docs/guide/delegate.md

@@ -23,6 +23,7 @@ Delegates called in one turn run in parallel.
 | `workspace` | Own VCS checkout, for delegates that edit files. The follow-up names its path. It isolates repository edits only. |
 | `cli` | Key for `$MU_<CLI>_COMMAND` (default `pi`), e.g. a cheaper model. |
 | `keep` | Keep the pane after it finishes, to talk to it again. |
+| `record` | `{ task, workstream? }` (or `task: "<ws>/<task>"`): write the answer's verdict onto that task as a note. See [Record a verdict](#record-a-verdict). |
 
 - Watch or steer: run the attach command.
 - Stop: `mu_delegate_cancel`, or `mu agent abort <name> -w scratch`.
@@ -45,6 +46,23 @@ Delegates called in one turn run in parallel.
 
 `MU_DELEGATE=0` hides the tool ([env vars](../reference/env.md)).
 
+### Record a verdict
+
+For a refuter or check, pass `record` so the verdict lands on the task
+it judged. The task must exist (`mu task show`), else the call fails
+and nothing spawns. When the answer arrives, the tool runs
+`mu task note <task> -w <ws> --author <delegate>` once:
+
+- Done: `REFUTER <label> (<delegate>, <elapsed>):`, then the last
+  `VERDICT:` line and every `EVIDENCE:` line after it. Without a
+  VERDICT line, the answer's last 1500 chars after `NO VERDICT LINE:`.
+  Capped at 4000 chars.
+- Timeout, died, empty, error, or cancelled:
+  `REFUTER <label>: no verdict (<outcome>)`.
+
+The follow-up still carries the full answer and ends with
+`Recorded on <ws>/<task> as a note.`, or the reason recording failed.
+
 ## Delegate without pi
 
 From a script or other shell, run what the tool runs:

package/docs/guide/dispatch.md

@@ -33,7 +33,8 @@ socket. Pick the mode by what the agent is doing:
 | Situation | Command |
 | --------- | ------- |
 | New task, any state | `mu agent send worker-1 --fresh '<brief>'` |
-| Busy, and you want to interrupt the current run | `mu agent send worker-1 --steer '<text>'` |
+| Busy, and the current work is wasted (wrong input, changed rule): act now | `mu agent send worker-1 --interrupt '<text>'` |
+| Busy, advice that can wait for the next tool boundary | `mu agent send worker-1 --steer '<text>'` |
 | Answering a question, or adding to the same task | `mu agent send worker-1 '<text>'` |
 
 - `--fresh` starts a new pi session and sends the prompt into it as
@@ -41,7 +42,14 @@ socket. Pick the mode by what the agent is doing:
   `mu agent abort` first, or pass `--force` to drop the running turn.
 - Never send `/new` and then the prompt as two sends to pi. The prompt
   can land during the reset and vanish.
-- A plain send to a busy agent queues as a follow-up.
+- A plain send to a busy agent queues as a follow-up: pi sees it after
+  the run ends. `--steer` lands between tool calls, after the running
+  tool returns; it does not stop a long tool such as a test batch, a
+  wait, or a `sleep`.
+- `--interrupt` aborts the run (kills the running tool), waits for pi
+  to settle, then sends the text as a new run. Queued messages go back
+  to the pane's editor unsent. Exit 5 when pi does not settle within
+  `--timeout` (default 30 s); the text is then not sent.
 - `/new`, `/reload` and `/compact [instructions]` run inside pi through
   the socket and report pi's answer (for example `Nothing to compact`).
   They refuse with exit 4 while pi is busy; `--force` overrides. Any
@@ -77,7 +85,9 @@ git commit -am '...' THEN
 mu task close build -w auth --evidence '...'
 ```
 
-Single-quote prompts that contain `$` or backticks. To see only what the worker wrote after the claim, run
+Single-quote short prompts. Pass prose (apostrophes, `$`, backticks) as `-` with a
+quoted heredoc: `mu agent send worker-1 - <<'EOF'`; see
+[brief](../../skills/mu/recipes/brief.md#quoting). To see only what the worker wrote after the claim, run
 `mu task notes build -w auth --since-claim`.
 
 ## Give each worker a workspace
@@ -139,6 +149,10 @@ mu task release build -w auth
 
 - Closed substates other than `done` need `--why`. Every `CLOSED`
   substate satisfies a blocker.
+- Deciding a finding (`accept`, or `close --as rejected|wontfix|duplicate`)
+  with a reason under 40 characters and no `VERDICT:` or `REFUTER` note
+  prints a warning. The exit code stays the same. A `REJECTED` or `SUPERSEDED`
+  note appends the title of each task id it names.
 - `--if-ready` closes only when every blocker is closed. Otherwise it
   lists the open blockers and exits 0.
 - A parked task leaves the ready set, and its dependents keep waiting.

package/docs/guide/getting-started.md

@@ -179,7 +179,7 @@ mu has not freed. That protects work you have not merged.
 ## Next steps
 
 - [Dispatch work to a worker](dispatch.md) covers more than one
-  worker and the `--fresh`, `--steer`, and plain send choices.
+  worker and the `--fresh`, `--interrupt`, `--steer`, and plain send choices.
 - [Use the TUI dashboard](tui.md): run bare `mu` to see every
   workstream at once.
 - [Clean up](cleanup.md) when the workstream is finished.

package/docs/reference/env.md

@@ -68,7 +68,7 @@ pi agent's `--command`. mu never reads them back.
 | --- | --- | --- |
 | `MU_DELEGATE` | `0` hides the `mu_delegate` tool. `mu doctor` reports it. | unset: shown |
 | `MU_DELEGATE_MAX` | Most delegates one pi session runs at once. Further calls queue, up to four times this; past that `mu_delegate` refuses. A positive integer. | `16` |
-| `MU_NUDGE` | `0` turns off both nudges: the keep-driving nudge (one reminder when an orchestrator ends a turn with dispatched work still IN_PROGRESS) and the close nudge (one reminder when a mu-spawned pi worker ends a turn still owning an IN_PROGRESS task). `mu doctor` reports it. | unset: on |
+| `MU_NUDGE` | `0` turns off the three nudges: the keep-driving nudge (one reminder when an orchestrator ends a turn with dispatched work still IN_PROGRESS), the close nudge (one reminder when a mu-spawned pi worker ends a turn still owning an IN_PROGRESS task), and the refute nudge (one notice when an orchestrator dispatched a task whose notes hold no `REFUTER`, `VERDICT:` or `REFUTE-EXEMPT:` line). A pi nested in an agent's pane (it found `MU_CTL_SOCK` served by another pi) gets none of them; a pi without UI (`pi -p`, json mode) gets no close or refute nudge. `mu doctor` reports it. | unset: on |
 | `MU_PI_HOME` | Root under which `mu link pi` writes `.pi/` and `.agents/`. | `$HOME` |
 | `PI_CODING_AGENT_DIR` | Read only. pi's agent dir, checked for a linked murmur extension. | `~/.pi/agent` |
 | `MU_EXTENSION_ENTRY` | Test only. Built extension the `mu link pi` shim imports. | `dist/extension/mu-pi.js` |

package/docs/specs/2026-10-03-keep-driving-nudge.md

@@ -140,3 +140,24 @@ claimed a task for a worker, ended its turn, received one
 `[mu-keep-driving]` message with `mu task wait nudgeprobe/slow ...`, and
 `mu log --kind nudge` held one entry. With nothing IN_PROGRESS, no
 nudge fired.
+
+## Refute nudge (2026-10-05)
+
+A sibling hook in the same file (`registerRefuteNudge`), registered on
+its own: it does not need the keep-driving markers and has its own
+once-per-prompt flag.
+
+- **Arm** on `mu task claim <id> --for` (`dispatchedTasks`: the id is
+  the first positional that is not an option value; `<ws>/<id>`
+  splits). `review_*` tasks never arm: their brief is the fixed
+  reviewer template, judging work against an already-refuted brief.
+- **Check** at a completed `agent_before_settle`: `mu task notes <id>
+  -w <ws> --json` per armed task. This is a second read beside
+  `mu state --json`. A task counts as refuted when a note has a line
+  starting `REFUTER `, `VERDICT:` or `REFUTE-EXEMPT:`; prose that only
+  mentions the words mid-line does not count.
+- **Notify** once per prompt: one `custom_message`
+  (`customType: "mu-refute-brief"`, `display: true`) listing every
+  unrefuted `<ws>/<id>`, and `mu log --kind nudge 'refute: ...'`. No
+  `continue`: it informs, and the orchestrator decides. `MU_NUDGE=0`
+  turns it off.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "A persistent, observable crew of pi agents running in one tmux or herdr session per workstream, coordinated through a built-in task DAG.",
   "publishConfig": {
     "access": "public"

package/skills/mu/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mu
-description: Manage AI agents in terminal-multiplexer panes (tmux or herdr) — from a single off-the-cuff helper to a persistent crew coordinated through a built-in task graph. Use when the user asks to "create/spin up a subagent to X", "run X in the background", "do this in parallel", "use one subagent per X to do Y", "kick off a helper to watch/investigate/draft X", or to spawn, send work to, observe, or coordinate one or many agents — especially work you'll keep talking to, long-lived or background agents, or anything needing a dependency graph. For zero-ceremony helpers use the reserved `scratch` workstream; for one-shot "fire and get a result back" use the `mu_delegate` tool — its pane is attachable while it runs.
+description: Fresh-context subagents and crews in tmux/herdr panes. Check before you commit: before acting on a claim, root cause, plan, fix or brief, have a `mu_delegate` call refute it. Also for a fresh delegate's second look at your own work or diff; parallel read-only research, investigation or fan-out over files; background helpers (watchers, soak runs, agents you keep talking to); persistent crews with a task graph, review gates and merges. Outside pi, delegate through the reserved `scratch` workstream.
 ---
 
 # mu — Multi-agent orchestration
@@ -53,9 +53,9 @@ Recipe words, the same in every recipe:
 - **wave** — the units dispatched from one main revision; refresh
   workspaces before the next.
 - **finding** — one reported problem, recorded as an `OPEN/triage` task.
-- **verdict** — the last line of a check's answer:
-  `VERDICT: CONFIRMED | REFUTED | UNVERIFIED <evidence>` (or ACCEPT |
-  REJECT for a review gate).
+- **verdict** — a check's answer: `VERDICT: <id> CONFIRMED | REFUTED |
+  UNVERIFIED <one line>` plus `EVIDENCE:` lines (or ACCEPT | REJECT for
+  a review gate).
 - **stop rule** — the command and condition that end a loop, written on
   the umbrella first ([loop-until-done](recipes/loop-until-done.md)).
 
@@ -65,13 +65,18 @@ Use mu for persistent helpers, parallel work, dependencies, gated review, or
 work that must survive context compaction. Stay in one context for tiny edits
 or inspection.
 
-### Off-the-cuff helpers (`scratch`)
+### Quick checks and off-the-cuff helpers (`scratch`)
 
-For one-shot work inside pi, call `mu_delegate` (installed by `mu link pi`).
-Outside pi: spawn into the reserved `scratch` workstream (no task DAG,
-auto-created), `send --fresh --json`, then `mu agent wait --after-runs <its runs> --json`
-(`lastText`); without `--after-runs` a run that ends first hangs the wait.
-Recipes call either form a **delegate call**.
+Before you act on a claim, root cause, plan, fix or brief, or to get a second
+look at your own work or diff, make a [delegate call](recipes/tasks-or-calls.md#delegate-call)
+that tries to refute it (briefs: see Orchestrator rules; many claims: [refute](recipes/refute.md)).
+
+For one-shot work inside pi, call `mu_delegate` (installed by `mu link pi`). Outside pi: spawn
+into the reserved `scratch` workstream (no task DAG, auto-created), `send --fresh --json`, then
+`mu agent wait --after-runs <its runs> --json` (`lastText`); without `--after-runs` a run that
+ends first hangs the wait. Recipes call either form a **delegate call**. A check judging a mu
+task lands its verdict there: `record: { task: "<ws>/<id>" }` on `mu_delegate`, a hand-written
+`REFUTER` note on the spawn path; with no task, skip both.
 
 - `mu agent wait <names...> --first` waits for busy → idle instead of a
   `sleep` loop; exit 0 met, 5 timeout, 6 pane died.
@@ -173,11 +178,18 @@ rules hold even when you skip it:
 - **`mu task wait --first --on-stall exit`**; exit 7 means read the
   owner's pane and answer it.
 - **Stop a worker gently**: `mu agent abort`, then `kick`, then `close`.
+  To redirect a busy pi now: `send --interrupt` (`--steer` waits for
+  the running tool).
+- **Send, don't note, a running worker**: it never sees new notes. The note is the durable copy
+  ([how to send](recipes/orchestrator-loop.md#sending)).
+- **Refute a brief claiming a cause, fix, threshold or code fact** before dispatch:
+  one `record`ed refuter call; rewrite on AMEND. Others get a `REFUTE-EXEMPT: <why>` note.
 - **Checks are calls, not tasks.** Refuters, claim checkers, judges and
   skeptics are [delegate calls](recipes/tasks-or-calls.md#delegate-call)
   (`mu_delegate`, or a `scratch` spawn without it), all issued in one
-  turn; their verdict lands on the task they judged. `mu_delegate` runs
-  `MU_DELEGATE_MAX` (default 16) at once and queues the rest.
+  turn. Refuters and claim checkers pass `record` (or hand-write the
+  `REFUTER` note) to land the verdict on the task; judges report
+  `WINNER:`. `MU_DELEGATE_MAX` (16) run at once; the rest queue.
 - **Findings are tasks.** A reviewer's or auditor's findings become
   `mu task add --triage` tasks blocking the review, decided with
   `mu task accept` or `close --as rejected|duplicate`. A review nobody
@@ -196,6 +208,8 @@ rules hold even when you skip it:
 - **For waits use `task wait`, not `log --tail`.** `mu log --kind <k>`
   entries are your own durable state (a ledger); `--intent` filters what
   mu recorded.
+- **Prose in notes, prompts, `--why` or `--evidence`**: an apostrophe
+  ends `'...'`; use a quoted heredoc ([brief](recipes/brief.md#quoting)).
 - **`mu sql`** does not pull synced ops; run any other mu command first.
 - **Never put `MU_DB_PATH` inside `MU_SYNC_DIR`**: it corrupts the DB.
 - Before undo, rebuild, teardown (dry-run without `--yes`), sync setup,
@@ -212,9 +226,15 @@ export MU_PI_COMMAND="pi --model sonnet:medium"
 mu agent spawn a --cli pi_big   # uses $MU_PI_BIG_COMMAND
 ```
 
-Convention: `pi_mini` for probing, `pi` for build and refactor,
-`pi_big` for design, review, and incidents. List models with
-`pi --list-models [search]`.
+`pi_mini` scouts and finds, `pi` builds and refactors, `pi_big` designs and
+handles incidents. A reviewer, refuter,
+judge or auditor checks level or up, never down: at least the worker's
+capability, from another family if one exists (provider or model-id prefix in
+`pi --list-models`). Small-model signs: a local runtime (ollama, lmstudio,
+llama.cpp), a size (`4b`, `27b`), mini/haiku/flash/nano/lite, thinking `no`,
+context or max-out far below the worker's. No such peer: same model, fresh
+context, higher thinking unless at max. Probe an unused model first
+(`pi --model <provider/model> -p "say ok"`); `ctl: ok` does not test it.
 
 ## Reaper and agent state
 
@@ -257,6 +277,7 @@ risky job that needs several of them, start with
 | [remote-workers](recipes/remote-workers.md) | an agent runs on another machine |
 | [waves](recipes/waves.md) | more than one worker edits the same repo at once |
 | [long-run](recipes/long-run.md) | a task or proof runs for hours, or must survive flakes |
+| [drift-audit](recipes/drift-audit.md) | hours into a long run, after a batch, compaction or resume, before a stop rule |
 | [watcher](recipes/watcher.md) | a helper polls a PR, CI, or log for change |
 | [findings](recipes/findings.md) | any review, audit, or check reports problems: where they live, how they are triaged |
 | [tasks-or-calls](recipes/tasks-or-calls.md) | a recipe step spawns an agent: DAG task or delegate call |

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

@@ -28,9 +28,8 @@ PR or diff from several angles, use [review-panel](review-panel.md).
 3. **Dispatch the work** as usual. When `x` closes, `review_x` becomes
    ready.
 4. **Spawn a fresh reviewer.** A new agent, or `--fresh` on an idle one,
-   so it has none of the author's reasoning. Use a different model from
-   the worker where you can (`--cli pi_big` reviewing `pi`): a second
-   model has different blind spots. Give it the worker's workspace path
+   so it has none of the author's reasoning, on a model chosen per
+   [Models](../SKILL.md#models-and-thinking-effort). Give it the worker's workspace path
    and commits read-only by instruction; it edits nothing.
 5. **Claim `review_x` for the reviewer**, send the brief (below), wait.
 6. **Act on the verdict:**
@@ -71,11 +70,20 @@ where it fails the acceptance criteria in `mu task notes <x>`.
   UNVERIFIED for it. Unverified is not a pass and not a fail.
 - Do not edit files.
 
-End with a note in the task note contract, then close with the verdict:
-  ACCEPT: mu task close review_<x> --evidence '<key check>'
-  REJECT: mu task close review_<x> --as rejected --why '<gap ids>'
+Write the verdict note (FILES/COMMANDS/FINDINGS/VERIFIED), then close
+(long reasons: a heredoc variable, brief.md § Quoting):
+  ACCEPT: mu task close review_<x> --evidence "<key command>: <result>"
+  REJECT: mu task close review_<x> --as rejected \
+            --why "<n> gaps: <id> (<why it fails, one clause>), ..."
 ```
 
+mu adds each named gap's title to the REJECTED note.
+
+**Closing a review yourself** (you fixed a finding, or accept without a
+fresh reviewer): write the reviewer's note plus `COMMIT: <sha> fixes
+<finding>`, and name the check in `--evidence`. Not `one finding fixed
+by orchestrator`.
+
 ## Traps
 
 - **A reviewer that sees the author's reasoning agrees with it.** Send

package/skills/mu/recipes/brief.md

@@ -32,6 +32,7 @@ not in the brief, or one pointer away, does not exist for it.
 6. **Ask for evidence, not reassurance.** The final note names the
    commands run and their exit codes (the task note contract). "Done,
    all good" is not a result.
+7. **A brief that makes claims is refuted before dispatch** ([SKILL.md](../SKILL.md#orchestrator-rules)).
 
 ## Shape
 
@@ -46,8 +47,35 @@ VERIFY: <exact command>
 
 ⚠️ FINAL ACTION
 git commit -am '<msg>' THEN
-mu task close <id> -w <ws> --evidence '<command + result>'
+mu task close <id> -w <ws> --evidence "$v"   # command + result; see Quoting
 ```
 
+## Quoting
+
+Single quotes suit short text with no `'`. Prose (an apostrophe ends
+`'...'`; `"..."` expands `$` and backticks) goes through stdin with a
+quoted heredoc, stored verbatim:
+
+```bash
+mu task note <id> -w <ws> - <<'EOF'
+it's fine: $HOME and `pwd` stay literal
+EOF
+```
+
+`mu task add --note -`, `--text -` and `mu agent send <a> -` read stdin
+the same way. `--why` and `--evidence` have no `-` form: capture the
+heredoc in a variable and double-quote it:
+
+```bash
+v=$(cat <<'EOF'
+it's fine: $HOME stays literal
+EOF
+)
+mu task close <id> -w <ws> --evidence "$v"
+```
+
+Chain batched adds with `&&`, then `mu task list`, so one
+quoting failure cannot half-apply the batch unseen.
+
 Done when a worker with no other context could finish the task from
 the brief and the notes it points at, and could tell when it is done.

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

@@ -62,16 +62,24 @@ the `scratch` form through `tools.bash`:
 
 ```js
 // @options: {"timeout_ms": 1800000}
+const ws = "audit";
 const findings = ["f_auth_put", "f_sql_order"]; // finding task ids, at most the cap per script
 const sh = async (c) => (await tools.bash({ command: c })).output;
+const json = (s) => { try { return JSON.parse(s); } catch { return {}; } };
+const el = (ms) => { const t = Math.round(ms / 1000); return t < 60 ? `${t}s` : `${Math.floor(t / 60)}m ${String(t % 60).padStart(2, "0")}s`; };
 const rows = await Promise.all(findings.map(async (id, i) => {
-  const a = `refuter-${i + 1}`;
+  const a = `refuter-${i + 1}`, t0 = Date.now();
   await sh(`mu agent spawn ${a} -w scratch`);
-  const { runs } = JSON.parse(await sh(`mu agent send ${a} -w scratch --fresh --json '<brief for ${id}: ... end with VERDICT: ...>'`));
-  const w = JSON.parse(await sh(`mu agent wait ${a} -w scratch --after-runs ${runs} --json --timeout 1200`));
-  const text = w.agents?.[0]?.lastText ?? "";
-  await sh(`mu agent close ${a} -w scratch`);
-  return `${id}\t${(text.match(/VERDICT:.*$/m) ?? ["VERDICT: UNVERIFIED no verdict line"])[0]}`;
+  const { runs } = json(await sh(`mu agent send ${a} -w scratch --fresh --json - <<'MU_EOF'\n<brief for ${id}, ending with the VERDICT block>\nMU_EOF`));
+  const w = json(await sh(`mu agent wait ${a} -w scratch --after-runs ${runs} --json --timeout 1200`)).agents?.[0] ?? {};
+  const lines = (w.lastText ?? "").trimEnd().split("\n");
+  const at = lines.findLastIndex((l) => /^[\s>*_`-]*VERDICT:/.test(l));
+  const note = w.outcome !== "done" ? `REFUTER ${i + 1}: no verdict (${w.outcome ?? "no result"})`
+    : `REFUTER ${i + 1} (${a}, ${el(Date.now() - t0)}):\n` + (at < 0 ? `NO VERDICT LINE: ${(w.lastText ?? "").slice(-1500)}`
+    : [lines[at], ...lines.slice(at + 1).filter((l) => /^[\s>*_`-]*EVIDENCE:/.test(l))].join("\n"));
+  await sh(`mu task note ${id} -w ${ws} - <<'MU_EOF'\n${note}\nMU_EOF`);
+  if (w.outcome === "done") await sh(`mu agent close ${a} -w scratch`);
+  return `${id}\t${note.split("\n")[1] ?? note}`;
 }));
 return rows.join("\n");
 ```
@@ -82,9 +90,11 @@ What the tool did for you, the script now owns:
   each script's list at or under it.
 - **Cleanup.** Close each scratch pane; a timed-out one stays, readable
   with `mu agent read <a> -w scratch`.
-- **Recording.** The table is not the record. Record each verdict on its
-  finding (`mu task accept`, `close --as rejected --why`), from the
-  script or after it returns.
+- **Recording.** The script writes each `REFUTER` note in `record`'s
+  shape, and `no verdict (<outcome>)` for a failed wait; it does not
+  cap long answers or special-case empty ones as `record` does. Decide
+  each finding after it returns ([findings § Triage](findings.md#triage)
+  step 3).
 
 ## Traps
 

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

@@ -41,12 +41,13 @@ answer rests on is an `OPEN/triage` task, decided like a finding
    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>`.
+   ends with the VERDICT block
+   ([tasks-or-calls § Delegate call](tasks-or-calls.md#delegate-call)).
    For contradicted claims, one checker per side. Batch under the cap
-   ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)). In workstream mode the
-   verdict is the claim task's state: `accept` for confirmed,
-   `close --as rejected` for refuted, an `UNVERIFIED:` note in triage
-   otherwise.
+   ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
+   In workstream mode the checker passes `record` on the claim task, and
+   the verdict is decided as in [findings § Triage](findings.md#triage)
+   step 3.
 5. **Synthesize** once every checker has answered (in workstream mode,
    when no claim task is left undecided): answer the question
    from confirmed claims only, each with its source URL. List

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

@@ -0,0 +1,72 @@
+# Drift audit
+
+Use during a long run to catch a crew drifting from what you decided:
+an instruction that never reached its worker, a batch run on stale
+inputs, work continuing on a closed task. One read-only
+[delegate call](tasks-or-calls.md#delegate-call); it edits nothing.
+
+## When
+
+- every few hours of a long run;
+- after each batch report of a chained task (sweep, campaign, soak);
+- after a context compaction or a resume;
+- before you declare a stop rule met.
+
+## Run
+
+Issue one delegate call with `record: { task: "<ws>/<umbrella>" }` and
+this brief, with `<ws>` filled in:
+
+```text
+Read-only drift audit of mu workstream <ws>. Change nothing. Sources:
+mu state -w <ws>; mu task list -w <ws> --json; mu task notes <id> -w <ws>;
+mu sql (ops, tasks, task_notes, agents); git log in the repo and in each
+owner's workspace. Never judge by a capped mu log -n window: the claim
+or close you compare against is often older than it.
+1. Unsent notes: notes on IN_PROGRESS tasks, by someone other than the
+   owner, after the owner's last task.claim or agent.send op:
+   mu sql "select t.local_id task, a.name owner, n.created_at, substr(n.content,1,80) note from tasks t join workstreams w on w.id=t.workstream_id join agents a on a.id=t.owner_id join task_notes n on n.task_id=t.id where w.name='<ws>' and t.status='IN_PROGRESS' and coalesce(n.author,'')<>a.name and n.created_at > max(coalesce((select max(o.created_at) from ops o where o.intent='task.claim' and o.key='<ws>/'||t.local_id),''), coalesce((select max(o.created_at) from ops o where o.intent='agent.send' and o.key='<ws>' and o.payload like 'agent send '||a.name||' (%'),'')) order by n.created_at"
+   Quote each task's last claim (seq, time). For each instruction it
+   lists: did the owner act on it (later commits, notes, pane)? Also read
+   mu sql "select seq, created_at, payload from ops where intent='agent.send' and key='<ws>'"
+   and flag mode=plain or mode=steer with state=busy since=<t> long
+   before the send: it queued behind a long turn and may not have landed.
+2. Stale pins: for each build/binary sha or oracle commit named in an
+   IN_PROGRESS note, and each merged fix its task's findings depend on:
+   git merge-base --is-ancestor <fix> <pinned>. Exit 1 = pin is stale.
+3. Closed-task notes: notes added after the task's last task.close op.
+   Report each of the top 5 by count as its own finding with its count,
+   even when the notes look routine. A late note that reports the
+   closed bug again usually ran on a build without the closing fix:
+   check its sha with git merge-base --is-ancestor <fix> <sha>.
+   mu sql "select t.local_id name, count(*) late from tasks t join workstreams w on w.id=t.workstream_id join task_notes n on n.task_id=t.id where w.name='<ws>' and t.status='CLOSED' and n.created_at > (select max(o.created_at) from ops o where o.intent='task.close' and o.key='<ws>/'||t.local_id) group by t.local_id order by late desc"
+4. Thin decisions: an ACCEPT/REJECTED/CLOSE/SUPERSEDED note under 40
+   chars; a refuter tally with no REFUTER or VERDICT note; a review the
+   orchestrator closed with no FILES/COMMANDS note and no commit.
+5. Silent tasks: IN_PROGRESS with no note or commit for longer than
+   the cadence its notes state (default 2h).
+6. Missing work: a task or finding a note or log line says will be
+   filed that does not exist.
+7. Unrefuted briefs: IN_PROGRESS tasks with no note line starting
+   REFUTER , VERDICT: or REFUTE-EXEMPT:.
+End with exactly this, one EVIDENCE line per finding (none when clean):
+VERDICT: <ws> DRIFT-AUDIT CLEAN | FINDINGS <n>
+EVIDENCE: FINDING <high|med|low> <file:line|task> <what> (check <1-7>)
+```
+
+`record` keeps only the VERDICT line and the `EVIDENCE:` lines after
+it, so each finding must be an `EVIDENCE: FINDING` line. The note
+lands headed `REFUTER`, which the refute nudge and decision warnings
+read as a recorded verdict; on an umbrella that is harmless.
+
+## Act
+
+Each finding becomes one of:
+
+- an `OPEN/triage` task blocking the umbrella ([findings § Record](findings.md#record));
+- a send to the worker it names, per
+  [orchestrator-loop § Sending](orchestrator-loop.md#sending)
+  (`--interrupt` when its current work is wasted, as with a stale pin).
+
+Done when the verdict is recorded on the umbrella and every finding
+is a task or a delivered send.

package/skills/mu/recipes/findings.md

@@ -69,24 +69,33 @@ across reviewers and creates one task per real problem.
    or several reviewers on one change: a `triage_<umbrella>` task, run
    by a fresh agent, so the orchestrator reads only its result.
 2. **Refute** each finding before accepting it with a
-   [delegate call](tasks-or-calls.md#delegate-call): a fresh agent tries
-   to prove it false and ends with
-   `VERDICT: <id> CONFIRMED | REFUTED | UNVERIFIED <evidence>`. Skip this
-   for low-severity style findings. High severity: three refuters,
-   accept only if at least two say CONFIRMED.
-3. **Decide** each one; the decision is the task's state:
-
-   | Decision | Command |
-   | --- | --- |
-   | real work | `mu task accept <id> --evidence '<what confirmed it>'` |
-   | false | `mu task close <id> --as rejected --why '<evidence>'` |
-   | same as another | `mu task close <id> --as duplicate --why 'same as <id>'` |
-   | valid, not worth it | `mu task close <id> --as wontfix --why '<reason>'` |
-   | could not check | stays in triage, with an `UNVERIFIED: <why>` note |
+   [delegate call](tasks-or-calls.md#delegate-call) that passes
+   `record: { task: "<ws>/<id>" }`: a fresh agent tries to prove it
+   false, and its VERDICT block lands on the finding as a
+   `REFUTER <label> (<delegate>, <elapsed>):` note (VERDICT line, 3-6
+   EVIDENCE lines), or `REFUTER <label>: no verdict (<outcome>)` when
+   it times out or dies. Without `mu_delegate`, write that note yourself
+   before deciding
+   ([tasks-or-calls § Delegate call](tasks-or-calls.md#delegate-call)).
+   Skip this for low-severity style findings. High severity: three
+   refuters, accept only if at least two say CONFIRMED.
+3. **Decide** each one; the decision is the task's state. The reason
+   names the deciding evidence, not a tally or a judgement. mu warns
+   when a reason is under 40 chars and no note holds a `VERDICT:` line
+   or `REFUTER` note. Prose reasons go through a heredoc variable
+   ([brief § Quoting](brief.md#quoting)).
+
+   | Decision | Command | Bad reason |
+   | --- | --- | --- |
+   | real work | `mu task accept <id> --evidence "2/3 CONFIRMED: refuters 1 and 3 show the checklist:3 vs :33 cycle"` | `valid`, `orchestrator: valid`, `2/3 CONFIRMED` |
+   | false | `mu task close <id> --as rejected --why "<the guard or command that disproves it>"` | `refuter REFUTED` |
+   | same as another | `mu task close <id> --as duplicate --why "same as <id>"` | |
+   | valid, not worth it | `mu task close <id> --as wontfix --why "<cost vs impact>"` | `not worth it` |
+   | could not check | stays in triage, with an `UNVERIFIED: <why>` note | |
 
 4. **Group** accepted findings that touch the same files into one fix
    task when separate workers would collide; close the grouped findings
-   `--as superseded --why 'fixed in <fix-task>'`.
+   `--as superseded --why "fixed in <fix-task>"`.
 
 Done when `mu task list --substate triage -w <ws>` lists only findings
 with an `UNVERIFIED` note, and each of those is reported to the human.

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

@@ -23,9 +23,11 @@ form independent theories; separate agents then try to kill them.
 3. **Test each hypothesis.** An experiment that changes code (force the
    race, revert the commit) needs a workspace: `mu task accept` the
    hypothesis and dispatch it as a task. One that only reads (feed the
-   data, grep the logs) is a delegate call. A killed hypothesis closes
-   `--as rejected --why '<evidence>'`; a survivor gets a
-   `SURVIVED: <evidence>` note.
+   data, grep the logs) is a delegate call with `record` on the
+   hypothesis ([tasks-or-calls § Delegate call](tasks-or-calls.md#delegate-call)).
+   A killed hypothesis closes `--as rejected --why "<the observation
+   that contradicts PREDICTS>"`; a survivor gets a `SURVIVED: <evidence>`
+   note. Prose reasons: [brief § Quoting](brief.md#quoting).
 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.