@zhixuan92/multi-model-agent 4.9.0 → 5.0.0

package/dist/skills/mma-journal-record/SKILL.md

@@ -1,189 +0,0 @@
----
-name: mma-journal-record
-description: >-
-  Use when you've abandoned an approach, hit a constraint, or concluded
-  something worth remembering — record it to the persistent journal as a
-  fire-and-forget decision audit trail for future sessions.
-when_to_use: >-
-  You've completed analysis and want to log the outcome — abandoned an approach,
-  hit a blocking constraint, or reached a conclusion worth remembering. NOT for
-  recall/investigate/delegate; those are read routes. Journal stores conclusions
-  for cross-session reference.
-version: 4.9.0
----
-
-# mma-journal-record
-
-## Overview
-
-Record a learning, constraint, or decision outcome to the persistent journal via a fire-and-forget mmagent worker. The worker stores the entry and returns immediately; you continue on your main context.
-
-**Core principle:** Journal is an audit trail of what you've decided, discovered, or abandoned. Record it once per session; don't re-investigate.
-
-## When to Use
-
-**Use when:**
-- You've abandoned an approach and want to log why
-- You've hit a blocking constraint worth remembering
-- You've reached a conclusion (e.g., "Pattern X doesn't work in this codebase")
-- You've decided not to pursue a direction and want to avoid repeating that decision next session
-
-**Don't use when:**
-- You're asking a question → `mma-investigate`
-- You're dispatching work → `mma-delegate`
-- You want to retrieve past entries → journal is append-only, not searchable; use `git log` or `.mmagent/journal/` files directly
-- You're mid-task and want to pause → that's what `blockedBy` is for; journal is for conclusions, not temporary blockers
-
-## Endpoint
-
-`POST /journal-record?cwd=<abs-path>`
-
-@include _shared/auth.md
-
-## Request body
-
-```json
-{
-  "learning": "Tried worker self-report for grouped-dispatch cancellation; dropped it — git diff is the source of truth. Lesson: use getRealFilesChanged.",
-  "tagHints": ["dispatch", "cancellation"]
-}
-```
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| `learning` | string | yes | Natural-language entry: what you decided, why, or what you learned. Keep it concrete. |
-| `tagHints` | string[] | no | Optional tags for later cross-reference (e.g. `["perf", "refactor"]`). Tags are advisory; the journal system may group or index them. |
-
-**What gets stored & where:**
-
-Entries are integrated into a graph-structured journal store at `.mmagent/journal/`:
-- `nodes/` — individual learning entries (keyed by unique node ID)
-- `index.md` — searchable index of all entries, tags, and cross-references
-- `log.md` — append-only event log of create/refine/supersede/merge operations
-
-The worker creates, refines, or supersedes nodes in the graph (never appends blindly). You can query the index or log directly to track learning history. Writes are confined to the project's `.mmagent/` directory (no traversal).
-
-## Full example
-
-```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 '{
-    "learning": "Tried worker self-report for grouped-dispatch cancellation; dropped it — git diff is the source of truth. Lesson: use getRealFilesChanged.",
-    "tagHints": ["dispatch", "cancellation"]
-  }' \
-  "http://localhost:$PORT/journal-record?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
-```
-
-@include _shared/polling.md
-
-@include _shared/response-shape.md
-
-## Per-task report shape
-
-Each task carries a structured report containing the graph operation metadata:
-
-```json
-{
-  "summary": "created 0012; superseded 0009",
-  "filesChanged": [".mmagent/journal/nodes/0012.md", ".mmagent/journal/index.md", ".mmagent/journal/log.md"],
-  "op": "create"
-}
-```
-
-The authoritative success signal is `completed` + the presence of `filesChanged`. See "v5 wire shape" below for the full envelope.
-
-## v5 wire shape (reviewed write route)
-
-Every task result is a `ComposePayload` — seven main-agent fields plus a telemetry block.
-The main-agent fields are authoritative; the telemetry block is diagnostics.
-
-```json
-{
-  "completed": true,
-  "message": "Journal entry created (node 0012); superseded prior learning (node 0009)",
-  "findings": [],
-  "summary": "created 0012; superseded 0009",
-  "filesChanged": [".mmagent/journal/nodes/0012.md", ".mmagent/journal/index.md", ".mmagent/journal/log.md"],
-  "commitSha": null,
-  "blockId": null,
-  "telemetry": {
-    "totalDurationMs": 5400,
-    "totalCostUSD": 0.04,
-    "workerSelfAssessment": "done",
-    "reviewVerdict": "approved",
-    "commitOutcome": "not_applicable",
-    "stopReason": "normal",
-    "haltedStage": null,
-    "stages": [
-      { "name": "prepare",        "outcome": "advance", "durationMs": 2,    "costUSD": 0 },
-      { "name": "register-block", "outcome": "skip",    "comment": "register-block does not apply to route=journal", "durationMs": 0, "costUSD": 0 },
-      { "name": "implement",      "outcome": "advance", "durationMs": 3200, "costUSD": 0.02 },
-      { "name": "review",         "outcome": "advance", "durationMs": 1800, "costUSD": 0.01 },
-      { "name": "rework",         "outcome": "skip",    "comment": "rework skipped because review approved", "durationMs": 0, "costUSD": 0 },
-      { "name": "commit",         "outcome": "skip",    "comment": "commit does not apply to non-git routes", "durationMs": 0, "costUSD": 0 },
-      { "name": "annotate",       "outcome": "advance", "durationMs": 340,  "costUSD": 0.01 },
-      { "name": "compose",        "outcome": "advance", "durationMs": 56,   "costUSD": 0 },
-      { "name": "terminal",       "outcome": "advance", "durationMs": 2,    "costUSD": 0 }
-    ]
-  }
-}
-```
-
-### Key fields
-
-| Field | When populated | Notes |
-|---|---|---|
-| `completed` | always | `true` when entry is created/refined/superseded and approved; `false` on review rejection, path traversal, or write failure |
-| `message` | always | human-readable summary (e.g., "created 0012; superseded 0009"); read on failure for diagnostic |
-| `findings` | always | issues surfaced by the reviewer (e.g., unclear learning, duplicate with 0009). Empty if approved as-is. |
-| `filesChanged` | always | graph journal paths modified: `nodes/`, `index.md`, `log.md` (relative to `cwd`) |
-| `workerSelfAssessment` | always | `'done'` or `'failed'` — worker's assessment of completeness |
-| `blockId` | always `null` | journal is a task route, not register-context-block |
-| `commitSha` | always `null` | journal entries are graph mutations, not git commits |
-| `reviewVerdict` | via telemetry | `'approved'` \| `'rejected_with_rework'` \| `'rejected'` — reviewer's verdict on the learned entry |
-
-### Reviewed write lifecycle
-
-Unlike read routes (audit/investigate/debug), journal runs a full review cycle: **implement** → **review** → [optional **rework**] → **commit** (skipped for non-git routes) → **annotate**. If the reviewer finds issues (e.g., the learning is ambiguous, the node supersedes multiple prior entries), a rework round applies targeted edits before finalization.
-
-### `completed: false` — what it means
-
-Path traversal detected, write permission denied, or directory creation failed. The `message` names the blocking issue.
-
-## Best practices
-
-**One entry per decision, not per turn.**
-Log once when you decide not to pursue a direction; don't log "just checked X" on every iteration.
-
-**Keep entries concrete.**
-❌ "Didn't work"  
-✅ "Tried multicast-style dispatch with worker dedup; git diff is the source of truth, workers can't track cancellations atomically. Use getRealFilesChanged instead."
-
-**Use tags to build searchable structure.**
-```bash
-# Later, grep your journal for all perf decisions:
-grep -r "^" .mmagent/journal/ | grep -i "perf:"
-```
-
-## Common pitfalls
-
-❌ **Using journal as a scratchpad**
-> "Thinking about X. Maybe Y? Need to check Z."
-
-Journal is for **conclusions**, not work-in-progress. Keep notes in a separate working file if you need to brainstorm.
-
-❌ **Logging without context**
-> "Doesn't work."
-
-Future-you (or a teammate) won't remember what "doesn't work" means. Always include the decision frame: what did you try, why did you try it, what was the outcome, and what will you do instead?
-
-## Context blocks
-
-Write-route tasks (delegate / execute-plan / journal / retry) do **not** register terminal context blocks. Their artifact is the filesystem mutation (git commit for delegate; graph mutations for journal). Read-route tasks (audit / review / debug / investigate / research) auto-register blocks containing their findings.
-
-@include _shared/error-handling.md

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

@@ -1,223 +0,0 @@
----
-name: mma-research
-description: >-
-  Use when you need external multi-source research with citations — arxiv,
-  semantic_scholar, github_search, brave-with-site:-filters — for a focused
-  question. Worker is bibliographic, not opinionated. Pair with mma-investigate
-  (internal) under mma-explore for divergent landscape scans.
-when_to_use: >-
-  An external-research question has surfaced (state of the art, prior art, what
-  others do, what published methods exist) AND mmagent is running. Delegate the
-  multi-source web/adapter research to a worker so the main context stays on
-  judgment. NOT for codebase questions — those are mma-investigate.
-version: 4.9.0
----
-
-# mma-research
-
-## Overview
-
-Run external multi-source research via a single mmagent worker. The worker
-consults configured adapters (arxiv, semantic_scholar, github_search) and
-— when Brave keys are configured — escalates to Brave web search with `site:`
-filters. The worker is bibliographic: it returns a numbered narrative with a
-`## Sources used` table. It does not opinion or rank.
-
-**Core principle:** External research is labor (search, fetch, summarise).
-Delegate it. The main agent stays on judgment — deciding what the citations
-mean and which directions to pursue.
-
-## When to Use
-
-**Use when:**
-- "What's the state of the art for X?"
-- "Who has published on Y?"
-- "What's prior art for Z?"
-- The question is external (web, papers, github topics) — not your codebase.
-
-**Don't use when:**
-- The question is about THIS codebase → `mma-investigate`
-- You need divergent ideation across both internal and external (multiple
-  directions with synthesis) → `mma-explore` (orchestrates mma-investigate + mma-research)
-- A single web fetch is all you need → `WebFetch` inline
-
-## Endpoint
-
-`POST /research?cwd=<abs-path>`
-
-@include _shared/auth.md
-
-## Configuration prerequisites
-
-The `mma-research` worker integrates with Semantic Scholar to search academic papers. This adapter is optional but recommended for comprehensive peer-reviewed source coverage.
-
-**Required environment variable:**
-
-```bash
-export SEMANTIC_SCHOLAR_API_KEY="your-key-from-semanticscholar.org"
-```
-
-Obtain a free API key from [Semantic Scholar API](https://www.semanticscholar.org/product/api).
-
-**Degraded behavior:**
-
-If the Semantic Scholar API key is not configured:
-- The worker continues with available adapters (arxiv, github_search, brave-search)
-- Semantic Scholar queries are skipped without errors
-- Research completes successfully but may lack academic-paper coverage
-- No failure occurs; graceful fallback is automatic
-
-## Request body
-
-```json
-{
-  "researchQuestion": "What approaches exist for streaming JSON parsing under 100KB?",
-  "background": "We currently use a single-pass push parser; we want to evaluate alternatives.",
-  "subtype": "default",
-  "contextBlockIds": []
-}
-```
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| `researchQuestion` | string | yes | 20–8000 chars |
-| `background` | string | yes | 20–8000 chars; what you already know / are trying to do |
-| `subtype` | `'default'` | no (defaults to `'default'`) | Reserved for future criteria sets; only `default` is wired today. |
-| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
-
-> Worker tier is hardcoded `complex`. Sending `agentType` or `tools` is rejected with HTTP 400.
-
-The `default` subtype's criteria target primary-source preference, practitioner consensus, recency, counter-perspectives, and cross-domain analogues — the worker is bibliographic, not opinionated.
-
-## Full example
-
-```bash
-BATCH=$(curl -f -sS -X POST \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "X-MMA-Client: $MMA_CLIENT" \
-  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "researchQuestion": "State-of-the-art SIMD JSON parsers under 100KB?",
-    "background": "We use a single-pass push parser; want SIMD alternatives."
-  }' \
-  "http://localhost:$PORT/research?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
-```
-
-@include _shared/polling.md
-
-@include _shared/response-shape.md
-
-## Per-task report shape (v5 envelope)
-
-Each `results[N]` is the v5 `ComposePayload`:
-
-```json
-{
-  "completed": true,
-  "message": "Research complete; 4 sources synthesised.",
-  "findings": [
-    {
-      "id": "F1",
-      "severity": "medium",
-      "category": "evidence",
-      "claim": "Pattern X is the canonical approach as of 2026 per upstream RFC.",
-      "evidence": "https://example.org/rfc/...",
-      "source": "implementer"
-    }
-  ],
-  "summary": "Pattern X dominates; pattern Y is a 2024 fork.",
-  "filesChanged": [],
-  "commitSha": null,
-  "blockId": null,
-  "telemetry": {
-    "totalDurationMs": 12400,
-    "totalCostUSD": 0.06,
-    "workerSelfAssessment": "done",
-    "reviewVerdict": null,
-    "commitOutcome": "not_applicable",
-    "stopReason": "normal",
-    "haltedStage": null,
-    "stages": [
-      { "name": "prepare",    "outcome": "advance" },
-      { "name": "implement",  "outcome": "advance" },
-      { "name": "annotate",   "outcome": "advance" },
-      { "name": "compose",    "outcome": "advance" },
-      { "name": "terminal",   "outcome": "advance" }
-    ]
-  }
-}
-```
-
-| Field | Notes |
-|---|---|
-| `completed: true` | At least one criterion succeeded; sources synthesised. |
-| `completed: false` | Annotator transport failure OR worker self-assessed as `failed`. `message` names the blocking gate. |
-| `findings` | The deliverable. `source: 'implementer'`. Empty `findings` on a research route means "no signal found" — still a valid completion. |
-| `workerSelfAssessment` | `'done'` or `'failed'` — never `done_with_concerns`. |
-| `blockId` | Always `null` — research is a task route, not register-context-block. |
-| `contextBlockId` | The terminal context block id for this read-route task (its report as a reusable block). Pass it into a later call's `contextBlockIds` for delta follow-ups. |
-
-Legacy aliases (still emitted for back-compat):
-
-```
-results[0].structuredReport.findings[]    // mirror of findings above
-results[0].structuredReport.sourcesUsed[] // table of sources tried
-results[0].output                          // raw narrative report
-```
-
-## 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)
-
-## Best practices
-
-- Keep `researchQuestion` topical (keywords, not full sentences).
-- Use `background` to give the worker context that helps it phrase queries.
-- For multi-round research, register the previous round's findings via
-  `mma-context-blocks` and pass `contextBlockIds`.
-
-## Common pitfalls
-
-❌ **Asking a codebase question here.** External adapters can't grep your repo. **Fix:** use `mma-investigate`.
-
-❌ **Inlining the user's full question verbatim.** Multi-sentence excerpts produce poor adapter queries. **Fix:** the worker re-phrases internally; you just pass the question and let it work.
-
-❌ **Expecting opinionated output.** This worker reports what's out there with citations. Ranking and synthesis happen elsewhere — in `mma-explore` or in your own judgment. **Fix:** if you need ranked options, use `mma-explore`.
-
-## Outcome semantics
-
-Every task result carries outcome fields that describe the research investigation's conclusion status:
-
-| Field | Type | Meaning |
-|---|---|---|
-| `findingsOutcome` | `'found' \| 'clean' \| 'not_applicable'` | Answers the question: did the research produce candidate sources and insights? |
-| `findingsOutcomeReason` | `string \| null` | When `findingsOutcome` is set, this explains why (e.g. "3 primary sources identified across arxiv and semantic_scholar" or "No sources found matching the research criteria"). |
-| `outcomeInferred` | `boolean` | `true` if the system inferred the outcome from findings count; `false` if the researcher explicitly stated it. |
-| `outcomeMalformed` | `boolean` | `true` if the outcome line was malformed and had to be repaired; `false` otherwise. |
-
-### Enum values
-
-- **`found`** — the research identified one or more candidate sources or insights (findings) across one or more search criteria. This indicates the question has published material or prior art available.
-- **`clean`** — the research completed but produced zero findings. This is valid for out-of-scope or nascent topics and indicates "no signal found."
-- **`not_applicable`** — the research could not proceed (e.g., question was out of scope, search system unavailable, or preconditions failed). This is the "cannot research" state.
-
-### Empty findings ≠ failure
-
-A crucial semantic: **empty findings does NOT mean `completed: false` or a failed research task.** Research that proceeds thoroughly and produces zero sources is a valid `completed: true` outcome; it answers the question "I searched widely and found nothing," which is valuable information. An empty-findings result often surfaces a `not_applicable` outcome (topic too new, domain too narrow) but zero findings is still a success.
-
-### Per-route legal outcomes
-
-The legal outcomes for this route are: `['found', 'not_applicable']`
-
-- **`found`** — one or more candidate sources or insights were identified via the research criteria.
-- **`not_applicable`** — the research could not proceed or the question was out of scope.
-
-The outcome `clean` (zero findings + success) is not legal for `mma-research` because a research task always either identifies sources or indicates the topic is inaccessible.
-
-@include _shared/error-handling.md

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

@@ -1,221 +0,0 @@
----
-name: mma-retry
-description: >-
-  Use when a previous mma-* batch returned partial results (some tasks failed or
-  came back incomplete) and you want to re-run JUST the failed indices without
-  re-dispatching the whole batch
-when_to_use: >-
-  A previous mma-delegate / mma-execute-plan / mma-audit / mma-review /
-  mma-debug / mma-investigate batch returned partial results AND you want to
-  re-try the failed indices only. Prefer this over re-dispatching the whole
-  batch or inline-retrying — it's idempotent and preserves the original batch's
-  diagnostics.
-version: 4.9.0
----
-
-# mma-retry
-
-## Overview
-
-Re-run selected tasks from a completed or failed batch. Specify the original `batchId` and the zero-based indices of the tasks to re-run. The retry runs those tasks fresh with the same configuration as the original batch and produces a new `batchId`.
-
-**Core principle:** A batch is the unit of dispatch, but a TASK is the unit of failure. Retry at the task level so successful tasks aren't re-charged.
-
-## When to Use
-
-```dot
-digraph when_to_use {
-    "Batch returned terminal?" [shape=diamond];
-    "Some tasks failed/incomplete?" [shape=diamond];
-    "All tasks failed?" [shape=diamond];
-    "mma-retry (selected indices)" [shape=box];
-    "Re-dispatch the whole batch" [shape=box];
-    "Investigate first (mma-debug)" [shape=box];
-
-    "Batch returned terminal?" -> "Some tasks failed/incomplete?";
-    "Some tasks failed/incomplete?" -> "All tasks failed?" [label="yes"];
-    "Some tasks failed/incomplete?" -> "Done — read results" [label="no"];
-    "All tasks failed?" -> "Investigate first (mma-debug)" [label="yes"];
-    "All tasks failed?" -> "mma-retry (selected indices)" [label="no — partial"];
-}
-```
-
-**Use when:**
-- A previous batch's terminal envelope shows mixed `completed: true` / `completed: false`
-- 1–N tasks (but not all) need a re-run with the same config
-- You want to keep the original batch's diagnostics intact for comparison
-
-**Don't use when:**
-- All tasks failed → investigate the systemic cause first (`mma-debug`); retrying won't help
-- The original batch is `expired` (TTL elapsed) → re-dispatch fresh
-- You want to change the prompt → re-dispatch with the new prompt; retry preserves the original
-
-## Endpoint
-
-`POST /retry?cwd=<abs-path>`
-
-@include _shared/auth.md
-
-## Request body
-
-```json
-{
-  "batchId": "550e8400-e29b-41d4-a716-446655440000",
-  "taskIndices": [1, 3]
-}
-```
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| `batchId` | string (UUID) | yes | Batch ID from a previous dispatch (not yet expired) |
-| `taskIndices` | number[] | yes | Zero-based indices to re-run; must be non-negative integers |
-
-To re-run all tasks: pass `[0, 1, ..., tasks.length - 1]`. (But consider: if all failed, debug instead of retrying.)
-
-## Full example
-
-```bash
-# Original batch had 4 tasks; re-run tasks at index 1 and 3
-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 '{"batchId":"550e8400-e29b-41d4-a716-446655440000","taskIndices":[1,3]}' \
-  "http://localhost:$PORT/retry?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')   # NEW batchId — not the original
-```
-
-@include _shared/polling.md
-
-## Response shapes
-
-### POST /retry?cwd=<abs> — dispatch response (202)
-
-```json
-{ "batchId": "<uuid>", "statusUrl": "/batch/<uuid>" }
-```
-
-Use `batchId` to poll. `statusUrl` is a convenience pointer. **This is a new batchId** — polling the original batch returns its terminal state.
-
-### 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 |
-| `200 application/json` | Terminal — body is the batch envelope below |
-| `404` / `401` / `5xx` | Error — see Error response below; stop polling |
-
-### GET /batch/:id?taskIndex=N — single task slice
-
-Same envelope. `results` contains exactly the task at index `N`. Returns `404 unknown_task_index` if `N` is out of range.
-
-### Reading the task result
-
-Each task result is the per-task wire object (`ComposePayload`):
-
-```json
-{
-  "completed": true,
-  "message": "Task completed; tests passed; one file changed.",
-  "findings": [
-    {
-      "id": "F1",
-      "severity": "high",
-      "category": "correctness",
-      "claim": "The function does not handle empty input",
-      "evidence": "function foo() { ... } // no null check",
-      "suggestion": "Add an explicit null guard at the top",
-      "source": "reviewer"
-    }
-  ],
-  "summary": "Refactored utils.ts — removed 3 dead branches, added JSDoc",
-  "filesChanged": ["/project/src/utils.ts"],
-  "commitSha": "abc123def",
-  "blockId": null,
-  "telemetry": {
-    "totalDurationMs": 12400,
-    "totalCostUSD": 0.08,
-    "workerSelfAssessment": "done",
-    "reviewVerdict": "approved",
-    "commitOutcome": "committed",
-    "stopReason": "normal",
-    "haltedStage": null,
-    "stages": [
-      { "name": "prepare",        "outcome": "advance", "durationMs": 2,    "costUSD": 0 },
-      { "name": "register-block", "outcome": "skip",    "comment": "register-block does not apply to route=delegate", "durationMs": 0, "costUSD": 0 },
-      { "name": "implement",      "outcome": "advance", "durationMs": 8900, "costUSD": 0.05 },
-      { "name": "review",         "outcome": "advance", "durationMs": 2100, "costUSD": 0.02 },
-      { "name": "rework",         "outcome": "skip",    "comment": "rework skipped because review approved", "durationMs": 0, "costUSD": 0 },
-      { "name": "commit",         "outcome": "advance", "durationMs": 340,  "costUSD": 0 },
-      { "name": "annotate",       "outcome": "advance", "durationMs": 890,  "costUSD": 0.01 },
-      { "name": "compose",        "outcome": "advance", "durationMs": 68,   "costUSD": 0 },
-      { "name": "terminal",       "outcome": "advance", "durationMs": 100,  "costUSD": 0 }
-    ]
-  }
-}
-```
-
-**Top-level fields to read for the main-agent verdict:**
-
-| Field | When `true` / populated |
-|---|---|
-| `completed: true` | Task succeeded. `message` is the summary; `findings` are post-review issues (if any). |
-| `completed: false` | Task did not complete. `message` names the blocking gate or finding; `findings` carry any discovered issues. |
-| `findings` | Issues surfaced by the worker or reviewer. `severity` = `critical` \| `high` \| `medium` \| `low`. `source` = `implementer` \| `reviewer`. |
-| `filesChanged` | File paths modified (empty for read-only routes). |
-| `commitSha` | Git SHA of the committed diff; `null` for read-only routes or when commit was skipped. |
-| `blockId` | Always `null` (retry replays write tasks; `contextBlockId` is `null` too — no terminal block). |
-
-**The stages array** (always 9 rows) is the canonical telemetry log. `outcome` is one of:
-- `advance` — stage ran and produced its payload
-- `skip` — stage did not run; `comment` explains why
-- `halt` — stage stopped the chain; `comment` is the failure message
-- `not_run` — stage was not reached because a prior stage halted
-
-Use `telemetry.haltedStage` to find the first halt; `telemetry.stopReason` to find why.
-
-### 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.
-
-## Best practices
-
-This skill is one step in the larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-retry`:
-
-- **Recipe C — Investigate-plan-execute (last step).** After `mma-execute-plan` returns mixed results, retry the failed indices to close the loop.
-- **Recipe D — Plan-execute-retry.** Pass the **original `batchId`** as input, specify the failed indices, keep the same configuration. `mma-retry` produces a NEW `batchId` in its response — poll that one for terminal state. Any `contextBlockIds` from the original carry forward.
-
-Anti-pattern alert: **`full-batch-redispatch`** (AP4). Re-dispatching the entire batch re-charges every successful task. Always retry by index.
-
-## Common pitfalls
-
-❌ **Retrying after the batch expired**
-TTL elapsed → original task specs are gone. **Fix:** re-dispatch fresh; the retry endpoint returns 404.
-
-❌ **Retrying without addressing the root cause**
-A flaky task that failed once will likely fail again. **Fix:** investigate (`mma-debug` or read the original `result.error.message`), then retry — or escalate `agentType` to `complex` by re-dispatching.
-
-❌ **Confusing the new and original `batchId`**
-Retry produces a NEW batchId; polling the original returns the old terminal state. **Fix:** save the retry's `batchId` and poll that one.
-
-❌ **Using retry to change task config**
-Retry preserves the ORIGINAL config (prompt, agentType, filePaths, reviewPolicy). **Fix:** if you want different config, re-dispatch with `mma-delegate` / `mma-execute-plan`.
-
-## Terminal context block
-
-Write-route tasks (delegate / execute-plan / retry) do NOT register a terminal context block — their durable record is the commit (`commitSha` + changed files). The per-task result's `contextBlockId` is always `null` for these routes. Read routes (audit / review / debug / investigate / research) return a non-null `contextBlockId`; see those skills for the delta-follow-up recipe.
-
-Note: a re-run **read-route** task registers its own terminal context block (`contextBlockId`); re-run write tasks register none. Original-batch blocks remain intact and are not overwritten.
-
-@include _shared/error-handling.md