@zhixuan92/multi-model-agent 5.0.1 → 5.0.3

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

@@ -0,0 +1,242 @@
+---
+name: mma-journal-recall
+description: >-
+  Use when you're about to design or attempt something and want to know what
+  THIS project already learned — ask a vague conceptual question (no tags or
+  keywords needed); a read-only worker searches the learnings graph and returns
+  the relevant prior lessons + how they relate. Fire before re-treading ground
+  that may already have been explored. NOT for recording a new learning
+  (mma-journal-record), codebase questions (mma-investigate), or external
+  research (mma-research).
+when_to_use: >-
+  A question about THIS project's learnings, before attempting or designing
+  something — ask a vague conceptual question; skip if recording a new learning,
+  asking the codebase, or researching external docs.
+version: 5.0.3
+---
+
+# mma-journal-recall
+
+## Overview
+
+Recall relevant project learnings from the journal via a read-only mmagent worker. The worker reads the learnings graph at `.mmagent/journal/` and synthesizes answers to vague conceptual queries.
+
+**Core principle:** Recall is retrieval (read, traverse graph, synthesize). Delegate it. The main agent stays on using the results — deciding what to do with the prior lessons.
+
+## When to Use
+
+**Use when:**
+- Before attempting something, ask "what have we learned about this?".
+- The query is a conceptual question ("dispatch cancellation reliability?", "rate-limiting patterns?"), not exact tags or keywords.
+- You want prior learnings + their relationships, not isolated chunks.
+- The project has an active journal (started with `mma-journal-record`).
+
+**Don't use when:**
+- You're recording a new learning → `mma-journal-record` (write route).
+- You're asking about the codebase structure → `mma-investigate` (read codebase).
+- You're researching external docs/web → `mma-research` / `WebSearch`.
+- The journal is empty or not yet initialized.
+
+## Endpoint
+
+`POST /journal-recall?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+## Request body
+
+```json
+{
+  "query": "what have we learned about dispatch cancellation reliability?",
+  "contextBlockIds": []
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `query` | string | yes | A vague conceptual question about prior learnings. No tags or keywords needed. |
+| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` — enables follow-up / delta recall |
+| `tools` | `'none' \| 'readonly'` | no | Default `'readonly'`. `'full'` and `'no-shell'` are rejected — recall is read-only |
+
+> Worker tier for `mma-journal-recall` is hardcoded to `complex` and is not caller-configurable. Sending `agentType` is rejected with HTTP 400.
+
+**Why `query` is vague, not keyword-filtered:**
+
+❌ `{ "query": "dispatch" }` — too narrow, might miss "cancellation reliability" nodes that don't mention the word "dispatch" in title.
+✅ `{ "query": "what have we learned about dispatch cancellation reliability?" }` — the worker understands the concept and finds related nodes.
+
+**Why:** the worker traverses the journal's typed graph (supersedes, refines, contradicts, depends-on) and synthesizes across related nodes. Semantic matching is the LLM's job, just like `mma-investigate`.
+
+## 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 '{"query":"what have we learned about dispatch cancellation reliability?"}' \
+  "http://localhost:$PORT/journal-recall?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 `investigation` field on its per-task report (same shape as `mma-investigate`):
+
+```json
+{
+  "investigation": {
+    "citations": [
+      { "file": "nodes/0012-dispatch-cancellation-lifecycle.md", "lines": "1-50", "claim": "Cancellation handlers must check context before writing." }
+    ],
+    "confidence": { "level": "high", "rationale": "Direct citations from journal nodes." },
+    "diagnostics": {
+      "malformedCitationLines": 0,
+      "missingRequiredSections": [],
+      "invalidRequiredSections": []
+    }
+  }
+}
+```
+
+The authoritative success signals are `completed`, `message`, and `findings`. See "v5 wire shape" below for the full envelope.
+
+## v5 wire shape (read 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": "Recall complete; 4 relevant learnings found.",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "critical",
+      "category": "correctness",
+      "claim": "Cancellation handlers must check context before writing to avoid corruption.",
+      "evidence": "nodes/0012-dispatch-cancellation-lifecycle.md:20-35 — verbatim substring from journal node.",
+      "suggestion": null,
+      "source": "implementer"
+    }
+  ],
+  "summary": "The project learned that dispatch cancellation must synchronize context reads (node 0012) and never write without checking. Related node 0008 (refines) adds that timeout-based cancellation has race conditions under high load.",
+  "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 |
+|---|---|---|
+| `completed` | always | `true` when at least one criterion succeeded; `false` on annotator transport failure OR unmet annotate preconditions |
+| `message` | always | human-readable summary; names blocking gates or finding IDs on failure |
+| `findings` | always | `source: 'implementer'` for recall; findings are the deliverable on read routes |
+| `workerSelfAssessment` | always | `'done'` or `'failed'` — never `done_with_concerns` |
+| `blockId` | always `null` (for write routes); string (for read routes) | recall is a read route, so `blockId` is a string — a reusable context block for delta follow-up |
+
+### 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 recall that surfaces 5 relevant lessons is `completed: true`. Finding nothing relevant is also a valid completion (returns `findings: []`).
+
+### `completed: false` — what it means
+
+Only on annotator transport failure, or if the journal is inaccessible/corrupted. The `message` names the blocking gate. Re-dispatch with a broader `query` if the worker's findings were too narrow.
+
+## Best practices
+
+This skill is one step in a larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-journal-recall`:
+
+- **Recipe A — Recall before attempting.** Call `mma-journal-recall` with your question before running `mma-delegate` / `mma-execute-plan` to avoid re-treading prior dead ends.
+- **Recipe B — Recall → plan → execute.** `mma-journal-recall` → write a plan based on the learnings → `mma-execute-plan`.
+- **Recipe C — Delta follow-up recall.** Feed a prior recall's `contextBlockId` into a follow-up call to dig deeper: `contextBlockIds: [priorResult.contextBlockId]`.
+
+Anti-pattern alert: **Misusing recall as codebase search.** Recall is for the *project's learnings graph*, not the codebase. If you want to search code → `mma-investigate`. If you want to ask the journal → `mma-journal-recall`.
+
+## Common pitfalls
+
+❌ **Using exact tags instead of a conceptual question**
+> query: "dispatch cancellation"
+
+The worker expects a sentence with context, not keywords. **Fix:** phrase it as a question:
+> query: "what have we learned about dispatch cancellation and how it interacts with timeouts?"
+
+❌ **Asking about the codebase instead of the journal**
+> query: "where is DispatchCanceller called?"
+
+That's a codebase question. Use `mma-investigate` instead. Journal recall is for *learnings* stored in `.mmagent/journal/`, not code.
+
+❌ **Assuming the journal exists**
+> query: "what do we know about X?"
+
+If the project hasn't used `mma-journal-record`, the journal is empty. The worker will return `not_applicable`. **Fix:** check whether the journal is active in the project first, or start recording learnings with `mma-journal-record`.
+
+## Terminal context block
+
+Every completed **read-route** task (audit / review / debug / investigate / recall / 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 / journal-record) 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:**
+- Recall round 2: pass round 1's block into round 2's `contextBlockIds` to dig deeper on a specific thread.
+- Recall → plan → execute chain: feed recall findings as a context block into `mma-execute-plan` as shared prior context.
+- Multi-agent follow-up: capture a recall's block and hand it to another tool chain.
+
+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 recall's conclusion status:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `findingsOutcome` | `'found' \| 'not_applicable'` | Answers the question: did the recall produce substantive learnings? |
+| `findingsOutcomeReason` | `string \| null` | When `findingsOutcome` is set, this explains why (e.g. "No relevant journal nodes found for the query" or "Journal is empty"). |
+| `outcomeInferred` | `boolean` | `true` if the system inferred the outcome from findings count; `false` if the worker explicitly stated it. |
+| `outcomeMalformed` | `boolean` | `true` if the outcome line was malformed and had to be repaired; `false` otherwise. |
+
+### Enum values
+
+- **`found`** — the recall produced one or more relevant prior learnings (findings) across one or more journal nodes.
+- **`not_applicable`** — the recall could not proceed (the journal is empty, inaccessible, or nothing in it answers the query).
+
+### Empty journal ≠ failure
+
+A recall that searches the journal and finds nothing relevant is a valid `completed: true` outcome; it simply answers "no prior learnings match that question" — which is useful information before attempting something new.
+
+### Per-route legal outcomes
+
+The legal outcomes for this route are: `['found', 'not_applicable']`
+
+- **`found`** — one or more prior learnings surfaced from the journal.
+- **`not_applicable`** — the journal is empty, inaccessible, or no learnings match the query.
+
+@include _shared/error-handling.md

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

@@ -0,0 +1,202 @@
+---
+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: 5.0.3
+---
+
+# 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
+{
+  "learnings": [
+    "Tried worker self-report for grouped-dispatch cancellation; dropped it — git diff is the source of truth. Lesson: use getRealFilesChanged.",
+    "Bun.spawn lacks process groups; keep node:child_process for codex subprocess management."
+  ],
+  "tagHints": ["dispatch", "cancellation"]
+}
+```
+
+**Batch your learnings into ONE call.** Collect every learning from the session and send them together in `learnings[]` — do NOT fire multiple concurrent `journal-record` calls. One worker integrates them sequentially in a single pass (fast and collision-free).
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `learnings` | string[] | yes | 1–20 entries, each 20–8000 chars. Each is a natural-language entry: what you decided, why, or what you learned. Keep them concrete. |
+| `tagHints` | string[] | no | Optional tags applied across ALL learnings (batch-scoped); the worker revises/normalizes per node. Advisory. |
+
+**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 '{
+    "learnings": [
+      "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": "recorded 2, failed 0; created 0012, superseded 0009",
+  "filesChanged": [".mmagent/journal/nodes/0012.md", ".mmagent/journal/index.md", ".mmagent/journal/log.md"],
+  "recorded": [
+    { "learningIndex": 0, "op": "create", "ids": ["0012"] },
+    { "learningIndex": 1, "op": "supersede", "ids": ["0013"] }
+  ],
+  "failed": []
+}
+```
+
+`recorded` and `failed` partition the input learnings by `learningIndex`. To retry, re-send the `failed[]` entries' `learning` text as a new `learnings[]` batch (reuse the original `tagHints`/`contextBlockIds`).
+
+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

@@ -0,0 +1,223 @@
+---
+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: 5.0.3
+---
+
+# 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