@zhixuan92/multi-model-agent 4.5.3 → 4.6.0

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

@@ -10,7 +10,7 @@ when_to_use: >-
   read files, reproduce, trace — OR a methodology skill
   (superpowers:systematic-debugging) points at the investigation step. Delegate
   the read/reproduce/trace; the main agent stays on the hypothesis and the fix.
-version: 4.5.3
+version: 4.6.0
 ---
 
 # mma-debug
@@ -84,41 +84,54 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/response-shape.md
 
-## Reading the findings (3.10.5+)
+## Reading the findings
 
-The terminal envelope's `results[N].annotatedFindings` is a list of structured
-findings the reviewer extracted and scored from the implementer's narrative.
-Every finding has the same shape:
+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": "Investigation complete; 1 finding.",
+  "findings": [
+    { "id": "F1", "severity": "high", "category": "root-cause",
+      "claim": "bcrypt binding fails on non-ASCII input in the Docker image.",
+      "evidence": "Worker reproduced the failure with `pass='café'`; strace shows EINVAL on encode call.",
+      "suggestion": "Normalize input to NFC form before calling bcrypt.",
+      "source": "implementer" }
+  ],
+  "filesChanged": [],
+  "commitSha": null,
+  "summary": "...",
+  "telemetry": { ... }
+}
+```
+
+### Finding shape
+
+Every finding has this shape:
 
 | Field | Type | Notes |
 |---|---|---|
-| `id` | string | Reviewer-assigned, e.g. `F1`, `F2`. |
+| `id` | string | Worker-assigned, e.g. `F1`, `F2`. Stable across chain. |
 | `severity` | `'critical' \| 'high' \| 'medium' \| 'low'` | 4-tier. |
+| `category` | string | Topical bucket, e.g. `root-cause`, `reproduction`. |
 | `claim` | string | One-sentence summary. |
-| `evidence` | string ≥20 chars | Quoted from worker output when grounded. |
+| `evidence` | string ≥20 chars | Verbatim from source when grounded. |
 | `suggestion?` | string | Optional fix recommendation. |
-| `annotatorConfidence` | `number \| null` | 0–100 from the reviewer; `null` when emitted via deterministic fallback. |
-| `evidenceGrounded` | boolean | True when `evidence` is a verbatim substring of worker output. |
-
-### Verdict states (`qualityReviewVerdict`)
+| `source` | `'implementer' \| 'reviewer'` | Who produced the finding. |
 
-- `'annotated'` — every finding is structured. May be reviewer-emitted (with
-  numeric `annotatorConfidence`) or deterministic-fallback (with
-  `annotatorConfidence: null`). The route ALWAYS reaches `'annotated'` unless
-  the reviewer call itself fails transport.
-- `'error'` — only when the reviewer call fails transport (network / 5xx).
+`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. Confidence and grounding are
-   soft signals, not gates.
-2. Default sort: severity (critical → low) then `annotatorConfidence` desc
-   (nulls last).
-3. `severity` is the reviewer's authoritative final value — use it directly.
-4. Mark findings with `evidenceGrounded: false` or
-   `annotatorConfidence < 70` as "lower-trust" (collapsed section, lighter
-   color, or `(low confidence)` annotation). User decides what to do.
-5. Severity-tier counts feed the dashboard via V3 `findingsBySeverity`.
+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.
 
 @include _shared/budget-defaults.md
 

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

@@ -11,7 +11,7 @@ when_to_use: >-
   and keep main context free. If a plan file exists → use mma-execute-plan. If
   the task is audit / review / verify / debug / investigate → use the matching
   specialized skill.
-version: 4.5.3
+version: 4.6.0
 ---
 
 # mma-delegate
@@ -86,7 +86,107 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/polling.md
 
-@include _shared/response-shape.md
+## Response shapes
+
+### POST /delegate?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 |
+| `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` is not used for the delegate route — it is always `null`. To chain results, use the `terminalBlockId` from the batch's `contextBlockIds` field instead.
+
+**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.
 
 @include _shared/budget-defaults.md
 
@@ -106,15 +206,7 @@ Anti-pattern alert: **`inline-labor-leakage`** (AP2). If you're reading 3+ files
 
 Workers run concurrently and race on the file. **Fix:** dispatch sequentially, or merge into one prompt.
 
-❌ **Vague `prompt`, no `done` criterion**
-> "improve the auth module"
-
-Worker has no completion signal — likely returns `done_with_concerns`. **Fix:** specific verb + acceptance: `"Add input validation to login.ts so all string fields reject empty/whitespace; tests pass"`.
-
-❌ **Defaulting to `agentType: "complex"` for everything**
-Standard tier is 5–10× cheaper and finishes most edits. Escalate only when standard returns `filesWritten: 0` or `incompleteReason: "turn_cap"`.
-
-❌ **Inlining a 50KB doc into every prompt**
+❌ **Two tasks writing the same file in one batch**
 N tasks × 50KB = N transmissions. **Fix:** register the doc once via `mma-context-blocks`, pass the `contextBlockIds` to each task.
 
 ❌ **Reading the worker's diff inline before review**

package/dist/skills/mma-execute-plan/SKILL.md

@@ -10,7 +10,7 @@ when_to_use: >-
   superpowers:subagent-driven-development / superpowers:executing-plans —
   workers are cheaper and don't pollute main context. Task descriptors must
   match plan headings verbatim.
-version: 4.5.3
+version: 4.6.0
 ---
 
 # mma-execute-plan
@@ -83,7 +83,106 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/polling.md
 
-@include _shared/response-shape.md
+## Response shapes
+
+### POST /execute-plan?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 |
+| `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=execute-plan", "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` | `terminalBlockId` — pass to `contextBlockIds` in a follow-up task to chain results without re-inlining. |
+
+**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.
 
 @include _shared/budget-defaults.md
 

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

@@ -12,7 +12,7 @@ when_to_use: >-
   out mma-investigate (internal) + mma-research (external) in parallel and
   synthesise the results yourself. DO NOT use for convergent single-answer
   questions — those are mma-investigate.
-version: 4.5.3
+version: 4.6.0
 ---
 
 # mma-explore
@@ -88,6 +88,21 @@ The main agent (you) issues a single message with two parallel tool calls:
   mma-research    { researchQuestion: "State-of-the-art streaming JSON parsers with backpressure?", background: "We use a single-pass push parser." }
 ```
 
+## Reading the leg results
+
+Both `mma-investigate` and `mma-research` return the v5 wire envelope (see `mma-investigate/SKILL.md` → "v5 wire shape"). Each sub-task result is a `ComposePayload` with the standard seven fields. The authoritative citation source is **`results[0].findings`** — an array of `{ id, severity, category, claim, evidence, suggestion, source }`.
+
+Explore top-level orchestration aggregates sub-task results into a valid `ImplementPayload` (read-route shape) before the final `annotate` stage runs. Each sub-task follows the same v5 wire shape; the top-level result is a composition of those sub-tasks.
+
+| Check | How |
+|---|---|
+| Did the leg succeed? | `results[0].completed === true` — findings may be zero on a read route; finding nothing wrong is a valid completion |
+| Internal citation source | `results[0].findings[i].claim` plus a `file:LINE` token from `results[0].findings[i].evidence` (workers style them as `` `path:LINE` `` markdown-linked refs) |
+| External citation source | `results[0].findings[i].claim` plus a source name / URL from `results[0].findings[i].evidence` |
+| Divergence axis | `results[0].findings[i].category` groups findings by criterion — pick across categories so threads don't collapse onto one axis |
+
+Apply a sentinel only when `findings` is empty AND `results[0].message` contains no finding-level content — i.e., the worker genuinely returned nothing. Do NOT apply a sentinel just because `results[0].message` reads tersely or `results[0].telemetry.workerSelfAssessment === 'failed'` — a worker can say `'failed'` with usable partial findings.
+
 ## Per-task report shape
 
 Synthesis output (REQUIRED — your reply MUST contain these):
@@ -96,11 +111,11 @@ Produce **3–5 threads**. Each thread MUST have:
 
 - A **title** and **one-paragraph summary**.
 - One **internal citation** (from investigate) — `file/path.ts:LINE — claim`.
-  - If investigate was skipped or returned no relevant findings, use the
-    sentinel `(no internal anchor — fully greenfield)`.
+  - Pick from `results[0].findings`: take `claim` as the citation claim and pull a `file:LINE` token out of `evidence`.
+  - Use the sentinel `(no internal anchor — fully greenfield)` ONLY when investigate was skipped, or `results[0].findings` is empty AND `results[0].message` contains no finding-level content. The top-level `message` alone is not evidence — see "Reading the leg results" above.
 - One **external citation** (from research) — `<source> — claim`.
-  - If research returned nothing usable, use the sentinel
-    `(no external source found)`.
+  - Pick from `results[0].findings`: take `claim` as the citation claim and pull a source name / URL out of `evidence`.
+  - Use the sentinel `(no external source found)` only when `results[0].findings` is empty for the research leg.
 - A **one-line divergence reason** — what makes this thread different from
   the others. No two threads may share the same divergence axis.
 
@@ -142,6 +157,7 @@ directions in the data.
 | Both failed | Report both errors to the user. Do NOT fabricate threads. |
 | Investigate returned `needsCallerClarification: true` | Pause — surface the clarification need to the user. Do NOT synthesise over an unfinished investigation. |
 | Research returned 0 usable sources | Sentinel on external lines. Add a one-line note in synthesis preamble: *"External research returned no usable sources — threads anchor on internal findings only."* |
+| Investigate headline reads "0 citations" / "confidence unparseable" but `results[0].findings.length > 0` | Known stage-sync noise — IGNORE the headline. The leg succeeded; read `results[0].findings` directly. |
 
 See `superpowers:brainstorming` as the natural follow-up — convergent narrowing
 on a chosen thread.

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

@@ -12,7 +12,7 @@ when_to_use: >-
   git-history queries. OR you are about to read 3+ files / run any grep in main
   context — that's the inline-labor-leakage anti-pattern (AP2); delegate to this
   skill instead.
-version: 4.5.3
+version: 4.6.0
 ---
 
 # mma-investigate
@@ -127,43 +127,70 @@ Each task carries an `investigation` field on its per-task report:
 }
 ```
 
-`workerStatus` is one of `done`, `done_with_concerns`, `needs_context`, `blocked`. When `done_with_concerns`, the per-task report carries `incompleteReason` (`turn_cap`, `cost_cap`, `timeout`, or `missing_sections`). When `needs_context`, the worker flagged a `[needs_context]` bullet under `## Unresolved` — re-dispatch with extra context (anchor paths or a context block).
+The authoritative success signals are `completed`, `message`, and `findings`. See "v5 wire shape" above for the full envelope.
 
-## Reading the findings (3.10.5+)
+## v5 wire shape (read route)
 
-The terminal envelope's `results[N].annotatedFindings` is a list of structured
-findings the reviewer extracted and scored from the implementer's narrative.
-Every finding has the same shape:
+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.
 
-| Field | Type | Notes |
+```json
+{
+  "completed": true,
+  "message": "Investigation complete; 3 files analysed.",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "high",
+      "category": "correctness",
+      "claim": "The refresh handler reads bearer from Authorization header unconditionally.",
+      "evidence": "src/auth/refresh.ts:45-72 — verbatim substring from worker output.",
+      "suggestion": "Add a guard to handle missing Authorization header gracefully.",
+      "source": "implementer"
+    }
+  ],
+  "summary": "...",
+  "filesChanged": [],
+  "commitSha": null,
+  "blockId": null,
+  "telemetry": {
+    "totalDurationMs": 1234,
+    "totalCostUSD": 0.08,
+    "workerSelfAssessment": "done",
+    "reviewVerdict": null,
+    "commitOutcome": "not_applicable",
+    "stopReason": "normal",
+    "haltedStage": null,
+    "stages": [...]
+  }
+}
+```
+
+### Key fields
+
+| Field | When populated | Notes |
 |---|---|---|
-| `id` | string | Reviewer-assigned, e.g. `F1`, `F2`. |
-| `severity` | `'critical' \| 'high' \| 'medium' \| 'low'` | 4-tier. |
-| `claim` | string | One-sentence summary. |
-| `evidence` | string ≥20 chars | Quoted from worker output when grounded. |
-| `suggestion?` | string | Optional fix recommendation. |
-| `annotatorConfidence` | `number \| null` | 0–100 from the reviewer; `null` when emitted via deterministic fallback. |
-| `evidenceGrounded` | boolean | True when `evidence` is a verbatim substring of worker output. |
-
-### Verdict states (`qualityReviewVerdict`)
-
-- `'annotated'` — every finding is structured. May be reviewer-emitted (with
-  numeric `annotatorConfidence`) or deterministic-fallback (with
-  `annotatorConfidence: null`). The route ALWAYS reaches `'annotated'` unless
-  the reviewer call itself fails transport.
-- `'error'` — only when the reviewer call fails transport (network / 5xx).
-
-### Recommended rendering by the main agent
-
-1. Show ALL findings — never silently drop. Confidence and grounding are
-   soft signals, not gates.
-2. Default sort: severity (critical → low) then `annotatorConfidence` desc
-   (nulls last).
-3. `severity` is the reviewer's authoritative final value — use it directly.
-4. Mark findings with `evidenceGrounded: false` or
-   `annotatorConfidence < 70` as "lower-trust" (collapsed section, lighter
-   color, or `(low confidence)` annotation). User decides what to do.
-5. Severity-tier counts feed the dashboard via V3 `findingsBySeverity`.
+| `completed` | always | `true` when at least one criterion succeeded; `false` on annotator transport failure OR unmet annotate preconditions (e.g. non-`done` worker self-assessment on a read route) |
+| `message` | always | human-readable summary; names blocking gates or finding IDs on failure |
+| `findings` | always | `source: 'implementer'` for investigate; findings are the deliverable on read routes |
+| `workerSelfAssessment` | always | `'done'` or `'failed'` — never `done_with_concerns` |
+| `blockId` | always `null` | investigate is a task route, not register-context-block |
+
+### No second review
+
+The LLM-judge stage (`annotate`) runs once, after the worker's output. Its preconditions for read-route `completed: true`:
+
+```
+gates.implement.outcome === 'advance'
+&& gates.implement.payload.workerSelfAssessment === 'done'
+&& (criteriaSucceeded.length > 0 || criteriaErrors.length === 0)
+```
+
+Findings are the deliverable — a task that surfaces 5 issues is `completed: true`. Finding nothing wrong is also a valid completion.
+
+### `completed: false` — what it means
+
+Only on annotator transport failure. The `message` names the blocking gate. Re-dispatch with tighter `filePaths` if the worker's citations were unusable.
 
 ## Best practices
 
@@ -180,15 +207,12 @@ Anti-pattern alert: **`inline-labor-leakage`** (AP2). If you find yourself readi
 
 The investigator can't write — `tools: 'readonly'`. **Fix:** use `mma-delegate` for research-then-edit, or split: investigate first, then dispatch the edit.
 
-❌ **Treating `done_with_concerns` as failure**
-The worker still produced citations and a confidence level. Read them — partial coverage with `incompleteReason: 'turn_cap'` often answers the question well enough. Re-dispatch with a tighter scope only if the citations are unusable.
-
 ❌ **Inline-reading instead of delegating**
 About to `Read` 3+ files just to answer one question? That's the wrong tradeoff — the worker reads on its cheap budget; you read its synthesis on yours.
 
 ## Terminal context block
 
-Every completed task automatically registers a terminal markdown context block containing the full task report (headline, investigation synthesis, citations, and annotated findings). The `blockId` is returned in each task result as `terminalBlockId`. This block is immutable, lives for the session duration, and counts against the project's `maxEntries` quota (default 500).
+Every completed task automatically registers a terminal markdown context block containing the full task report (headline, investigation synthesis, citations, and annotated findings). The `blockId` is returned in each task result under the shared `blockId` field (not a separate `terminalBlockId` field). This block is immutable, lives for the session duration, and counts against the project's `maxEntries` quota (default 500).
 
 **Use cases:**
 - Pass investigation results to a downstream planning step

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

@@ -10,7 +10,7 @@ when_to_use: >-
   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.5.3
+version: 4.6.0
 ---
 
 # mma-research
@@ -89,10 +89,59 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/response-shape.md
 
-## Per-task report shape
+## 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. |
+
+Legacy aliases (still emitted for back-compat):
 
 ```
-results[0].structuredReport.findings[]    // numbered findings with citations
+results[0].structuredReport.findings[]    // mirror of findings above
 results[0].structuredReport.sourcesUsed[] // table of sources tried
 results[0].output                          // raw narrative report
 ```