@zhixuan92/multi-model-agent 5.0.1 → 5.0.3

package/dist/skills/_shared/auth.md

@@ -0,0 +1,41 @@
+## Authentication & identity headers
+
+Every request to the multi-model-agent server requires:
+
+| Header | Required for | Purpose |
+|---|---|---|
+| `Authorization: Bearer <token>` | All routes (except `/health`) | Auth — token from `mmagent print-token` |
+| `X-MMA-Client: <client>` | All tool routes | Identifies your client. One of `claude-code`, `cursor`, `codex-cli`, `gemini-cli`. **Server returns `400 client_required` if missing.** |
+| `X-MMA-Main-Model: <model-id>` | All tool routes | Calling agent's model id (e.g. `claude-opus-4-7`, `gpt-5.4`). Used as `mainModel` in wire telemetry so cost-delta-vs-main and family attribution can be computed. **Server returns `400 main_model_required` if missing.** Auto-detection is intentionally not attempted — the calling client is the only reliable source. |
+
+### Obtain the token
+
+**From environment variable** (preferred):
+```
+MMAGENT_AUTH_TOKEN=<token>
+```
+
+**From CLI**:
+```bash
+mmagent print-token
+```
+
+### Shell helper
+
+```bash
+TOKEN="${MMAGENT_AUTH_TOKEN:-$(mmagent print-token)}"
+MMA_CLIENT="${MMAGENT_CLIENT:-claude-code}"
+MMA_MAIN_MODEL="${MMAGENT_MAIN_MODEL:-claude-opus-4-7}"
+
+curl \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-MMA-Client: $MMA_CLIENT" \
+  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
+  ...
+```
+
+### Errors
+
+- `401 unauthorized` — re-run `mmagent print-token`; the token may have changed after a server restart.
+- `400 client_required` — `X-MMA-Client` header is missing on a tool route. Set it to one of: `claude-code`, `cursor`, `codex-cli`, `gemini-cli`.
+- `400 main_model_required` — `X-MMA-Main-Model` header is missing on a tool route. Set it to the calling agent's model id (e.g. `claude-opus-4-7`, `gpt-5.4`).

package/dist/skills/_shared/error-handling.md

@@ -0,0 +1,31 @@
+## Error handling
+
+### HTTP status decision table
+
+| Status | Code | Action |
+|---|---|---|
+| `400` | `invalid_request` | Fix the request body or query params |
+| `401` | `unauthorized` | Re-fetch token; check `MMAGENT_AUTH_TOKEN` |
+| `403` | `forbidden` | `cwd` query param missing or out of scope |
+| `404` | `not_found` | Wrong `batchId` or resource does not exist |
+| `409` | `invalid_batch_state` / `pinned` | Batch in wrong state; check current state first |
+| `413` | `payload_too_large` | Reduce content size (context block or body) |
+| `429` | `rate_limited` | Wait `Retry-After` seconds, then retry |
+| `503` | `project_cap_exceeded` | Too many concurrent projects; wait and retry |
+| `5xx` | server error | Retry once after 2 s; escalate if it persists |
+
+### Network failures
+
+Retry up to 3 times with exponential backoff (1 s → 2 s → 4 s).
+If the server is unreachable, check that `mmagent serve` is running:
+```bash
+curl -s http://localhost:$PORT/health   # expects { "status": "ok" }  (v4.0 — see spec C13)
+```
+
+### Auth errors (401)
+
+```bash
+export MMAGENT_AUTH_TOKEN=$(mmagent print-token)
+```
+
+The token changes on every server restart. Re-export before retrying.

package/dist/skills/_shared/polling.md

@@ -0,0 +1,88 @@
+## Polling for batch completion
+
+After a tool call returns a `batchId`, poll `GET /batch/:id` until the batch
+reaches a terminal state.
+
+### HTTP response shapes (3.1.0)
+
+| Status | Content-Type | Meaning |
+|---|---|---|
+| `202` | `text/plain` | Still working — body is the running headline (e.g. `1/1 running, 47s elapsed`) |
+| `200` | `application/json` | Terminal — body is the uniform 6-field envelope (see `response-shape.md`) |
+| `404` / `401` / other | — | Error — stop polling |
+
+### Terminal envelope states
+
+Every terminal envelope has the same six fields; inspect `error` to tell
+which terminal state you're in:
+
+| Shape | Meaning |
+|---|---|
+| `error` is a real object | Batch failed — read `error.code` + `error.message` |
+| `error` is `{kind: "not_applicable", ...}` | Batch succeeded — read `results` |
+
+### Poll loop (POSIX sh)
+
+```bash
+DELAY=1
+START=$(date +%s)
+TIMEOUT_S=${MMAGENT_POLL_TIMEOUT_S:-1800}
+BODY_FILE=$(mktemp -t mmagent-poll.XXXXXX)
+trap 'rm -f "$BODY_FILE"' EXIT
+
+while true; do
+  NOW=$(date +%s)
+  if [ $((NOW - START)) -ge "$TIMEOUT_S" ]; then
+    echo "mmagent: poll timed out after ${TIMEOUT_S}s" >&2
+    exit 124
+  fi
+
+  STATUS=$(curl -f --show-error -o "$BODY_FILE" -w "%{http_code}" -s \
+    -H "Authorization: Bearer $TOKEN" \
+    "http://127.0.0.1:$PORT/batch/$BATCH_ID" || true)
+
+  case "$STATUS" in
+    202)
+      cat "$BODY_FILE"; echo
+      sleep "$DELAY"
+      DELAY=$(( DELAY < 30 ? DELAY * 2 : 30 ))
+      ;;
+    200)
+      cat "$BODY_FILE"
+      exit 0
+      ;;
+    "")
+      echo "mmagent: unreachable (curl failed)" >&2; exit 1 ;;
+    *)
+      echo "mmagent: HTTP $STATUS"; cat "$BODY_FILE" >&2; exit 1 ;;
+  esac
+done
+```
+
+Start at 1 s, double each iteration, cap at 30 s. The 1800-second client-side
+timeout is a safety cap; most batches complete in under 60 s. Discover `$PORT`
+at runtime with `mmagent info --json | jq -r .port` (default: 7337).
+
+### Caller-side tool-timeout note
+
+The poll helper's internal `TIMEOUT_S` default is 1800s (30 minutes). If your
+agent's shell tool (e.g. Claude Code's Bash) caps command wall-clock at
+10 minutes by default, the helper will be killed at 10m regardless of
+`TIMEOUT_S` — long-running delegations then appear to "fail" before terminal.
+
+When invoking this poll loop, pick one:
+
+- **Preferred — pass a 30-minute tool timeout explicitly** (e.g. Claude Code
+  Bash accepts `timeout: 1800000`, up to 600000ms/10 min by default; pass the
+  max the tool allows, or bump the tool's allowed ceiling via harness
+  settings).
+- **Alternative — cap the helper to match the tool's limit** by exporting
+  `MMAGENT_POLL_TIMEOUT_S=600` before running the loop. The helper will then
+  exit 124 cleanly at 10 minutes and the caller can decide whether to
+  re-poll or surface the timeout.
+
+Never let the helper run longer than the caller's tool cap — the process
+gets killed mid-poll, the caller sees a generic failure, and diagnostics
+from the `TIMEOUT_S` exit path are lost.
+
+Windows/PowerShell equivalent is planned for a later release.

package/dist/skills/_shared/response-shape.md

@@ -0,0 +1,55 @@
+## Response shapes
+
+### POST /<tool>?cwd=<abs> — dispatch response (202)
+
+```json
+{ "batchId": "<uuid>", "statusUrl": "/batch/<uuid>" }
+```
+
+Use `batchId` to poll. `statusUrl` is a convenience pointer.
+
+### GET /batch/:id — polling response
+
+The HTTP status is the state discriminator:
+
+| Status | Meaning |
+|---|---|
+| `202 text/plain` | Still pending — body is the running headline string (e.g. `"1/2 running, 47s elapsed"`) |
+| `200 application/json` | Terminal — body is the uniform 7-field envelope below |
+| `404` / `401` / `5xx` | Error — see Error response below; stop polling |
+
+The terminal JSON envelope always has these 6 fields. Each may be a real value or a `not_applicable` sentinel:
+
+```json
+{
+  "headline": "<string>",
+  "results": [ /* per-task result objects */ ],
+  "batchTimings": { /* timings */ },
+  "costSummary": { /* cost roll-up */ },
+  "structuredReport": { /* parsed sections */ },
+  "error": { "kind": "not_applicable", "reason": "batch succeeded" }
+}
+```
+
+Read the envelope by the shape of `error`:
+
+| Shape | Meaning |
+|---|---|
+| `error` is a real object (with `code` / `message`) | Batch failed — read `error.code` + `error.message` |
+| `error` is `{kind: "not_applicable", ...}` | Batch succeeded — read `results` |
+
+### GET /batch/:id?taskIndex=N — single task slice
+
+Same 6-field envelope. `results` contains exactly the task at index `N`. Returns `404 unknown_task_index` if `N` is out of range.
+
+### Error response (4xx / 5xx)
+
+```json
+{
+  "error": "<code>",
+  "message": "<human-readable>",
+  "details": { /* optional structured context, e.g. fieldErrors for 400 */ }
+}
+```
+
+`details` is optional and present only when the server has structured additional context.

package/dist/skills/_shared/review-policy.md

@@ -0,0 +1,15 @@
+### `reviewPolicy` — review lifecycle per task
+
+**Applies to write routes only** (`delegate`, `execute-plan`, `retry`).
+Read-only routes (audit, review, debug, investigate, research) do not expose
+this field — they are hardcoded to `"none"` because the review stage is
+write-routes-only. They still run the always-on **annotate** judge (a
+standard-tier LLM pass that summarizes the worker's report); their findings
+come from the worker itself, not from a second-pass code review.
+
+| Value | Behavior | Use when |
+|---|---|---|
+| `"full"` | Spec review + quality review (default) | Default for new code or risky edits |
+| `"quality_only"` | Quality review only | Write task where spec-conformance is already certain but you still want a quality pass |
+| `"diff_only"` | Single-pass review of the produced diff | Cheap mechanical refactors (file moves, renames, import-path updates) |
+| `"none"` | Skip the review stage | Trivially mechanical edits or throwaway scripts where a second-pass reviewer adds nothing |

package/dist/skills/mma-audit/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: mma-audit
+description: >-
+  Use when the user asks to audit a spec / plan / design doc / skill file. The
+  `subtype` field picks the criteria set. `default` (prose-coherence) is the
+  general doc auditor. `plan` verifies a code-execution plan against the actual
+  codebase — run this before any `mma-execute-plan` dispatch. `spec` audits
+  requirement prose for testability and decision-trace. `skill` audits a
+  SKILL.md against reader-effectiveness criteria.
+when_to_use: >-
+  User asks for a doc / spec / plan / skill audit OR a methodology skill
+  (superpowers:dispatching-parallel-agents, /security-review) points at one AND
+  mmagent is running. Audit on PROSE/SPEC docs — use mma-review for source code.
+  Audit a CODE-EXECUTION PLAN against the codebase — use subtype=plan.
+version: 5.0.3
+---
+
+# mma-audit
+
+## Overview
+
+`mma-audit` sends a prose artifact to workers for structured auditing. The `subtype` field picks WHICH criteria set the workers apply — every subtype runs through the same sequential-criteria read-only lifecycle, but each one carries its own criteria list, semantics, and prompt scaffolding.
+
+**Four subtypes — picked by the kind of artifact, not by the lens you want:**
+
+| You're auditing… | Use… | What it checks |
+|---|---|---|
+| A general prose artifact (design doc, recommendation, post-mortem, README) | `subtype: 'default'` | Comprehensive prose-coherence — would a literal-following worker produce the right outcome from this prose alone? Catches ambiguity, contradictions, missing branches, drift, scope-creep. **Does NOT verify against any codebase.** |
+| A **code-execution PLAN** (`docs/superpowers/plans/*.md` or similar) before running it via `mma-execute-plan` | `subtype: 'plan'` | Plan-vs-codebase coherence — for every method / type / file path / signature / import / verify command the plan names, the codebase actually contains it as described. Catches the bug class the prose-coherence audit cannot see (e.g. plan says `registerBlock` but actual interface is `register`). |
+| A **requirement spec** (what we want, why; success criteria) | `subtype: 'spec'` | Requirement-prose executability across 9 criteria — testability, scope explicitness AND decomposability, acceptance-criteria coverage, non-functional capture, requirement conflicts, decision-trace, assumption exposure, placeholder scan, and design-decomposition presence (architecture / components / data flow / error handling / testing). |
+| A **SKILL.md** for an `mma-*` skill or comparable agent-facing playbook | `subtype: 'skill'` | Skill-file reader-effectiveness — when-to-use specificity, endpoint contract integrity, example correctness, anti-pattern coverage, link integrity. |
+
+If you want to bias workers toward a narrow lens (security only, performance only, accessibility only), put that in the free-text `background` portion of the prompt — `subtype` is criteria machinery, not a lens selector.
+
+## When to Use
+
+- `subtype: 'default'` — a general prose artifact needs a critical read for internal executability (the artifact will be acted on by a worker reading the prose alone).
+- `subtype: 'plan'` — you have a written code-execution plan on disk and you're about to dispatch tasks from it via `mma-execute-plan`. This is the ONLY subtype that grounds findings against real source files.
+- `subtype: 'spec'` — you have a requirement / brainstorming-output spec and want to verify every requirement is testable, traceable, and unambiguous BEFORE writing the plan. Typical predecessor to `writing-plans`.
+- `subtype: 'skill'` — you're authoring or revising an `mma-*` skill or comparable SKILL.md and want to know whether agents will actually read it the right way.
+
+**Don't use mma-audit when:** the thing being audited is source code (→ `mma-review`); a 30-second `Read` would answer it; or you want to verify a plan that hasn't been written yet (write the plan first).
+
+## Endpoint
+
+`POST /audit?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+## Request body
+
+```json
+{
+  "document": "inline content to audit (optional if filePaths given)",
+  "subtype": "default",
+  "filePaths": ["/project/docs/spec.md"],
+  "contextBlockIds": []
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `document` | string | no | Inline document content |
+| `subtype` | `'default' \| 'plan' \| 'spec' \| 'skill'` | no (defaults to `'default'`) | See "Picking subtype" below. |
+| `filePaths` | string[] | no | Files to audit (one worker per file, parallel) |
+| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
+
+Either `document` or `filePaths` (or both) must be provided.
+
+> Worker tier for `mma-audit` is hardcoded to `complex` and is not caller-configurable. Sending `agentType` is rejected with HTTP 400.
+
+### Picking subtype
+
+| Value | When to use |
+|---|---|
+| `default` (or omit the field) | **General prose — design doc, recommendation, post-mortem, README, brief.** Comprehensive prose-coherence audit. Does NOT verify against any codebase. |
+| `plan` | **Code-execution plans being audited against a real codebase.** Single-file input (the plan markdown). Workers grep / read source files under `cwd` to verify every named symbol / path / signature / import / verify command. Use this BEFORE every `mma-execute-plan` dispatch. |
+| `spec` | **Requirement spec / brainstorming-output / what-we-want prose.** 9 criteria target testability, scope explicitness + decomposability, acceptance-criteria coverage, non-functional capture, requirement conflicts, decision-trace, assumption exposure, placeholder scan, and design-decomposition presence. |
+| `skill` | **`SKILL.md` or comparable agent-facing playbook.** Criteria target when-to-use specificity, endpoint contract integrity, example correctness, anti-pattern coverage, link integrity. |
+
+You can run BOTH on a plan: first `spec` or `default` (prose quality), then `plan` (does the plan match the codebase?). They cover orthogonal failure modes.
+
+The legacy `auditType` field and its `correctness` / `style` / `general` / `security` / `performance` values no longer exist. Sending `auditType` returns `400 invalid_request`. Sending unknown `subtype` values returns `400 invalid_request` with the allowed enum.
+
+### Plan-audit specifics
+
+When `subtype: 'plan'`:
+
+- `filePaths` MUST contain exactly **one entry** — the plan markdown. Sending zero or 2+ entries → `400 invalid_request` with the message: *"Plan audit takes exactly one filePath (the plan markdown). The worker discovers and verifies source files itself via its tool surface — do not pre-list source files."*
+- `document` (inline content) is not used in plan mode — the plan must be on disk so workers can reference it by `?cwd=`-relative path.
+- The worker runs the sequential-criteria loop with the plan-audit criteria set across 12 perspectives in three groups: **EXTERNAL CODEBASE COHERENCE** (1 PATH EXISTENCE, 2 SYMBOL EXISTENCE, 3 SIGNATURE MATCH, 4 IMPORT GRAPH, 5 TEST HARNESS AVAILABILITY, 6 STEP SEQUENCE WITHIN TASK, 7 CROSS-TASK DEPENDENCIES, 8 VERIFICATION COMMAND VALIDITY), **INTRA-PLAN STRUCTURE** (9 TASK GRANULARITY, 11 PLACEHOLDER LANGUAGE, 12 PLAN SKELETON), and **SPEC ALIGNMENT** (10 SPEC COVERAGE).
+- To enable perspective 10 (SPEC COVERAGE), register the upstream spec as a context block via `mma-context-blocks` and pass its `blockId` in `contextBlockIds`. Without a spec in context, perspective 10 emits "No findings for this criterion." and the other 11 still run.
+- Read the findings list. Fix the plan and re-audit if any `critical` or `high` plan-audit findings remain.
+
+## Full example
+
+### Default audit (general prose)
+
+```bash
+BATCH=$(curl -f --show-error -s -X POST \
+  -H "X-MMA-Client: $MMA_CLIENT" \
+  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"subtype":"default","filePaths":["/project/docs/api-spec.md"]}' \
+  "http://localhost:$PORT/audit?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+### Spec audit (requirement prose)
+
+```bash
+BATCH=$(curl -f --show-error -s -X POST \
+  -H "X-MMA-Client: $MMA_CLIENT" \
+  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"subtype":"spec","filePaths":["/project/docs/superpowers/specs/2026-05-12-feature-design.md"]}' \
+  "http://localhost:$PORT/audit?cwd=/project")
+```
+
+### Skill audit (SKILL.md)
+
+```bash
+BATCH=$(curl -f --show-error -s -X POST \
+  -H "X-MMA-Client: $MMA_CLIENT" \
+  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"subtype":"skill","filePaths":["/project/packages/server/src/skills/mma-audit/SKILL.md"]}' \
+  "http://localhost:$PORT/audit?cwd=/project")
+```
+
+### Plan audit (verify a code-execution plan against the codebase)
+
+```bash
+BATCH=$(curl -f --show-error -s -X POST \
+  -H "X-MMA-Client: $MMA_CLIENT" \
+  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"subtype":"plan","filePaths":["/project/docs/superpowers/plans/2026-05-10-feature.md"]}' \
+  "http://localhost:$PORT/audit?cwd=/project")
+```
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+## Reading the findings
+
+The main agent reads `completed` + `message` + `findings` — the findings are the answer. For
+read-only routes, `filesChanged` is always `[]` and `commitSha` is always `null`.
+
+```json
+{
+  "completed": true,
+  "message": "Plan audit complete; 2 findings.",
+  "findings": [
+    { "id": "F1", "severity": "high", "category": "path-existence",
+      "claim": "Step 3 names `src/utils/foo.ts` which does not exist.",
+      "evidence": "Worker grepped for the file under cwd — no match found.",
+      "suggestion": "Use `src/utils/bar.ts` instead.",
+      "source": "implementer" }
+  ],
+  "filesChanged": [],
+  "commitSha": null,
+  "summary": "...",
+  "telemetry": { ... }
+}
+```
+
+### Finding shape
+
+Every finding has this shape:
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | string | Worker-assigned, e.g. `F1`, `F2`. Stable across chain. |
+| `severity` | `'critical' \| 'high' \| 'medium' \| 'low'` | 4-tier. |
+| `category` | string | Topical bucket, e.g. `path-existence`, `prose-coherence`. |
+| `claim` | string | One-sentence summary. |
+| `evidence` | string ≥20 chars | Verbatim from source when grounded. |
+| `suggestion?` | string | Optional fix recommendation. |
+| `source` | `'implementer' \| 'reviewer'` | Who produced the finding. |
+
+`annotatorConfidence` and `evidenceGrounded` are retired — they were v4 fields with no producers.
+
+### Recommended rendering by the main agent
+
+1. Show ALL findings — never silently drop. Severity and grounding are soft
+   signals, not gates.
+2. Default sort: severity (critical → low), then `id` ascending.
+3. `severity` is the authoritative value — use it directly.
+4. Mark findings with `evidence` shorter than 30 chars as "low-evidence"
+   (lighter color or `(low evidence)` annotation). User decides what to do.
+5. Severity-tier counts feed the dashboard.
+
+## Best practices
+
+This skill is one step in the larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-audit`:
+
+- **Recipe A — Audit-iterate-clean.** `mma-audit` → fix → `mma-audit` again. Sequential rounds. Register the doc via `mma-context-blocks` before round 1 and reuse the same ID across all rounds — avoids re-inlining the same content into every audit call.
+
+- **Recipe E — Plan-validate-execute.** Before any `mma-execute-plan` batch, run `mma-audit` with `subtype: 'plan'` on the plan file. Read the findings. If any `critical` / `high` finding survives, fix the plan and re-audit. This catches the bug class where the plan's named methods/files don't actually exist in the codebase — symbols a prose-coherence audit cannot see.
+
+- **Recipe F — Spec-then-plan-then-execute (the canonical flow).** When working from a brainstorming spec: `mma-audit` (`subtype: 'spec'`) → fix → `writing-plans` → register the spec as a context block via `mma-context-blocks` → `mma-audit` (`subtype: 'plan'`, `contextBlockIds: [specBlockId]`) → fix → `mma-execute-plan`. Spec audit covers requirement-prose executability; plan audit covers BOTH plan-vs-codebase coherence AND plan-vs-spec coverage (perspective 10 fires only when the spec is in context, which is why the context-block step is load-bearing in this recipe).
+
+Anti-pattern alert: **`parallel-rounds-same-target`** (AP1). Three parallel audits on the same document re-flag the same issues without seeing each other's fixes. Run rounds sequentially with a fix between each.
+
+## Common pitfalls
+
+❌ **Auditing source code with `mma-audit`**
+The auditor lacks codebase context (no type info, no call-site lookup, no test awareness). Findings are speculative. **Fix:** use `mma-review` — it pulls in surrounding source context and validates against the actual types.
+
+❌ **Single huge `document` string instead of `filePaths`**
+Inline docs lose the file boundary, so the per-file parallel split degenerates to one worker. **Fix:** save to disk first, pass `filePaths`.
+
+❌ **Sending the legacy `auditType` field**
+The field was renamed to `subtype` and the value set was narrowed. **Fix:** use `subtype` with one of `default` / `plan` / `spec` / `skill`. For "security only" / "performance only" lenses, put the bias in the free-text prompt — there is no narrow-lens subtype.
+
+❌ **Re-auditing the same files round after round without delta context**
+Round 2 worker has no idea what round 1 found. **Fix:** register the round 1 findings as a context block (`mma-context-blocks`) and pass `contextBlockIds` to round 2.
+
+## Terminal context block
+
+Every completed **read-route** task (audit / review / debug / investigate / research) auto-registers a reusable terminal context block containing its report (headline + findings). The block id is returned on each per-task result as **`contextBlockId`**. Write routes (delegate / execute-plan / retry) return `contextBlockId: null` — their record is the commit, not a block. This block is immutable, lives for the session duration, and counts against the project's `maxEntries` quota (default 500).
+
+Use it for delta follow-ups — feed prior results' block ids into a later call's `contextBlockIds`, filtering out nulls:
+
+    contextBlockIds: priorResults.map(r => r.contextBlockId).filter((id) => id !== null)
+
+**Use cases:**
+- Pass round-N audit findings to round N+1 via `contextBlockIds`
+- Feed audit results into a downstream `mma-delegate` fix step
+- Accumulate findings across iterative audit rounds
+
+The block is registered server-side at task completion; no caller action is needed to create it. Delete it explicitly via `DELETE /context-blocks/:id` when no longer needed, or let it expire on session teardown.
+
+## Outcome semantics
+
+Every task result carries outcome fields that describe the audit's conclusion status:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `findingsOutcome` | `'found' \| 'clean' \| 'not_applicable'` | Answers the question: did the audit uncover issues? |
+| `findingsOutcomeReason` | `string \| null` | When `findingsOutcome` is set, this explains why (e.g. "3 critical findings: broken paths, missing symbols, mismatched signatures" or "Document is clean across all audit criteria"). |
+| `outcomeInferred` | `boolean` | `true` if the system inferred the outcome from findings count; `false` if the auditor explicitly stated it. |
+| `outcomeMalformed` | `boolean` | `true` if the outcome line was malformed and had to be repaired; `false` otherwise. |
+
+### Enum values
+
+- **`found`** — the audit surfaced one or more issues (findings) in the artifact across one or more criteria. This indicates the artifact needs rework before downstream use.
+- **`clean`** — the audit completed and found zero issues. The artifact is clear across all audit criteria and ready for downstream use.
+- **`not_applicable`** — the audit could not proceed (e.g., wrong input type, missing preconditions, or system error). This is rare; most audits resolve to `found` or `clean`.
+
+### Empty findings ≠ failure
+
+A crucial semantic: **empty findings does NOT mean `completed: false` or a failed task.** Finding nothing wrong is a successful audit outcome — it means the document passed the bar. An audit with zero findings is `completed: true` with `findingsOutcome: 'clean'`.
+
+### Per-route legal outcomes
+
+The legal outcomes for this route are: `['found', 'clean']`
+
+- **`found`** — one or more issues were detected across the audit criteria.
+- **`clean`** — zero issues were detected; the artifact is ready for downstream use.
+
+The outcome `not_applicable` is not legal for `mma-audit` (except on actual precondition failures) because an audit always produces a verdict: either issues found or clean.
+
+@include _shared/error-handling.md

package/dist/skills/mma-context-blocks/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: mma-context-blocks
+description: >-
+  Use when a document larger than ~2 KB will be referenced by 2+ subsequent
+  mma-* calls — register once, pass the returned ID to each call instead of
+  re-uploading the same content. OR a spec / plan / error log was already
+  inlined into one task and is about to be inlined into a second — register on
+  the second reference, never the third.
+when_to_use: >-
+  A document (spec, plan, codebase summary, prior round's findings, error log)
+  larger than ~2 KB will be referenced by two or more mma-* calls in a row.
+  Register once here, then pass the ID via `contextBlockIds` on mma-delegate /
+  mma-execute-plan / mma-audit / mma-review / mma-debug / mma-investigate.
+  Cheaper and faster than inlining the same content N times.
+version: 5.0.3
+---
+
+# mma-context-blocks
+
+## Overview
+
+Store large documents once; reference them by ID in subsequent `mma-*` calls via `contextBlockIds`. The service prepends the block content to each task prompt that references the ID — content is transmitted ONCE to the daemon, then reused server-side.
+
+**Core principle:** Without context blocks, the same document is sent N times for N tasks. Blocks transmit once. The savings compound on shared specs, prior-round findings, and codebase summaries.
+
+## When to Use
+
+**Use when:**
+- A doc >2 KB will be referenced by ≥2 mma-* calls
+- You're running iterative audit/review rounds (round 2 references round 1's findings)
+- A spec or design doc is the shared input across N parallel tasks
+- A long error log is the context for debug + delegate calls
+
+**Don't use when:**
+- The doc is <2 KB and used once → just inline it (registration overhead exceeds savings)
+- The doc changes between calls → context blocks are immutable; register a new one
+- Single task that doesn't reference any large shared content → no benefit
+
+## Endpoints
+
+### Register a context block
+
+`POST /context-blocks?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+#### Request body
+
+```json
+{
+  "content": "# Project spec\n...",
+  "ttlMs": 3600000
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `content` | string | yes | Document content (min 1 char, max 50 MiB) |
+| `ttlMs` | number | no | Time-to-live in ms; omit for idle-expiry (default 24 h idle). A block that is not referenced by any active batch for 24 h is eligible for eviction. |
+
+#### Response (201)
+
+```json
+{ "id": "cb_abc123" }
+```
+
+Use this `id` as a `contextBlockIds` entry in any `mma-*` skill that supports it.
+
+### Delete a context block
+
+`DELETE /context-blocks/:id?cwd=<abs-path>`
+
+Returns `200 { ok: true }` on success. Returns `409 pinned` if the block is held by one or more active batches — wait for those batches to complete before deleting.
+
+## Full example
+
+```bash
+# Register spec document once
+ID=$(curl -f --show-error -s -X POST \
+  -H "X-MMA-Client: $MMA_CLIENT" \
+  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"content\":$(jq -Rs . < /project/docs/spec.md)}" \
+  "http://localhost:$PORT/context-blocks?cwd=/project" | jq -r '.id')
+
+# Reference from N delegate tasks
+curl -f --show-error -s -X POST \
+  -H "X-MMA-Client: $MMA_CLIENT" \
+  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"tasks\":[
+    {\"prompt\":\"Implement section 3 per spec\",\"contextBlockIds\":[\"$ID\"]},
+    {\"prompt\":\"Implement section 4 per spec\",\"contextBlockIds\":[\"$ID\"]}
+  ]}" \
+  "http://localhost:$PORT/delegate?cwd=/project"
+```
+
+## v5 wire shape (register-context-block route)
+
+Every task result is a `ComposePayload`. For the `register-context-block` route, the envelope has one additional field beyond the standard seven:
+
+```json
+{
+  "completed": true,
+  "message": "Context block cb_abc123 registered (12345 bytes)",
+  "findings": [],
+  "summary": "",
+  "filesChanged": [],
+  "commitSha": null,
+  "blockId": "cb_abc123",
+  "telemetry": { ... }
+}
+```
+
+`blockId` is **non-null only for the `register-context-block` route**. For every other route (`delegate`, `execute-plan`, `investigate`, etc.), `blockId` is `null`. This is the only signal that distinguishes a register-context-block result from any other route — no route-keyed discriminated union, just one extra nullable field on the shared shape.
+
+The terminal context block (per-task, auto-registered) uses a different ID format and is separate from the `blockId` in the wire envelope.
+
+## Best practices
+
+This skill is the cross-cutting state mechanism described in `multi-model-agent` → "Best practices". Recipes that use context blocks:
+
+- **Recipe A — Audit-iterate-clean.** Register the doc once before round 1; pass round-N's findings block ID into round N+1.
+- **Recipe B — Debug-fix-verify.** Register the failing test output / reproduction log before the debug call; reuse on verify.
+- **Recipe C — Investigate-plan-execute.** Register the plan file before `mma-execute-plan`.
+- **Recipe D — Plan-execute-retry.** No new registration needed — `mma-retry` inherits the original batch's `contextBlockIds`.
+
+Anti-pattern alert: **`re-inlined-shared-content`** (AP3). Pasting the same spec into 5 task prompts costs N× tokens. Register once; pass `contextBlockIds`.
+
+## Common pitfalls
+
+❌ **Inlining the same 50KB spec into every task prompt**
+> tasks: [{prompt: "Implement section 3:\n[50KB spec]"}, {prompt: "Implement section 4:\n[50KB spec]"}]
+
+N×50KB transmissions; main context burns through tokens. **Fix:** register the spec once, pass `contextBlockIds: ["cb_xxx"]` to each task.
+
+❌ **Forgetting to delete unused blocks**
+Blocks count against the project's context-block quota (`maxEntries` 500). **Fix:** explicitly `DELETE` after the dependent batches finish — or let idle expiry (24 h) evict them.
+
+❌ **Trying to update a block's content**
+Blocks are immutable. **Fix:** register a new block with the new content; switch the `contextBlockIds` to the new ID.
+
+❌ **Deleting a block while a batch still references it**
+Returns `409 pinned`. **Fix:** poll the dependent batches to terminal first, then delete.
+
+@include _shared/error-handling.md