@zhixuan92/multi-model-agent 4.7.19 → 4.8.0

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

@@ -3,31 +3,36 @@ name: mma-explore
 description: >-
   Use when about to brainstorm or plan and need a divergent landscape scan —
   orchestrates parallel internal-codebase investigation + external multi-source
-  research, then synthesises 3–5 distinct directions. Not for "where is X"
-  single-answer questions (use mma-investigate).
+  research + prior-learnings recall from the project journal, then synthesises
+  3–5 distinct directions. Not for "where is X" single-answer questions (use
+  mma-investigate).
 when_to_use: >-
   You are about to brainstorm or plan and need a broad landscape scan before
   narrowing. The question is exploratory ("what are our options", "what
   approaches exist", "survey how others handle"). The skill instructs you to fan
-  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.7.19
+  out mma-investigate (internal), mma-research (external), and
+  mma-journal-recall (prior learnings/decisions) in parallel and synthesise the
+  results yourself. DO NOT use for convergent single-answer questions — those
+  are mma-investigate.
+version: 4.8.0
 ---
 
 # mma-explore
 
 ## Overview
 
-Codebase + external sources, synthesised into 3–5 distinct directions. Two
-delegated calls (`mma-investigate` for the internal codebase, `mma-research`
-for external sources) run in parallel; **you** synthesise their results into
-the final output.
+Codebase + external sources + prior learnings, synthesised into 3–5 distinct
+directions. Three delegated calls run in parallel — `mma-investigate` (internal
+codebase), `mma-research` (external sources), and `mma-journal-recall` (what
+this project already learned/decided, from the `.mmagent/journal/` graph) —
+and **you** synthesise their results into the final output.
 
 **Core principle:** Exploration is divergent (survey, enumerate, compare).
-Synthesis turns raw threads into ranked, citable directions. The internal and
-external research is delegated; the synthesis is your judgment work and stays
-in main context.
+Synthesis turns raw threads into ranked, citable directions. The three legs
+are delegated; the synthesis is your judgment work and stays in main context.
+The journal leg is what keeps you from re-proposing a direction the project
+already tried and dropped — it grounds the scan in your own history, not just
+the code and the outside world.
 
 ## When to Use
 
@@ -56,41 +61,50 @@ digraph when_to_use {
 
 ## How to run
 
-Dispatch BOTH in ONE message (parallel tool use):
+Dispatch ALL THREE in ONE message (parallel tool use):
 
 1. `mma-investigate` — internal codebase research
    - You MAY skip this only if the question is unambiguously greenfield (no
      codebase touch-points exist). When in doubt, run it.
 2. `mma-research` — external multi-source research
+3. `mma-journal-recall` — prior learnings/decisions from the project journal
+   - Always run it. If the project has no journal yet (or nothing relevant),
+     it returns zero findings — a valid result you handle with the
+     `(no prior learning)` sentinel. Never skip it to "save a call": a
+     superseded prior decision is exactly the signal you most want before
+     brainstorming.
 
-Wait for both to return. Do NOT proceed to synthesis until you have both
-results (or have decided to skip investigate).
+Wait for all legs to return. Do NOT proceed to synthesis until you have every
+result (or have decided to skip investigate as greenfield).
 
 ## Endpoint
 
 This is a main-agent skill — there is no dedicated `/explore` HTTP endpoint.
-Behind the scenes, you dispatch the two delegated tools `mma-investigate`
-(`POST /investigate`) and `mma-research` (`POST /research`) yourself.
+Behind the scenes, you dispatch the three delegated tools `mma-investigate`
+(`POST /investigate`), `mma-research` (`POST /research`), and
+`mma-journal-recall` (`POST /journal-recall`) yourself.
 
 ## Request body
 
-(Not applicable — this skill orchestrates two other skills.) See
-[`mma-investigate`](../mma-investigate/SKILL.md) and
-[`mma-research`](../mma-research/SKILL.md) for their request bodies.
+(Not applicable — this skill orchestrates three other skills.) See
+[`mma-investigate`](../mma-investigate/SKILL.md),
+[`mma-research`](../mma-research/SKILL.md), and
+[`mma-journal-recall`](../mma-journal-recall/SKILL.md) for their request bodies.
 
 ## Full example
 
-The main agent (you) issues a single message with two parallel tool calls:
+The main agent (you) issues a single message with three parallel tool calls:
 
 ```
 [parallel tool use]
-  mma-investigate { question: "How does our streaming JSON parser handle backpressure?", filePaths: ["src/parsers/"] }
-  mma-research    { researchQuestion: "State-of-the-art streaming JSON parsers with backpressure?", background: "We use a single-pass push parser." }
+  mma-investigate    { question: "How does our streaming JSON parser handle backpressure?", filePaths: ["src/parsers/"] }
+  mma-research       { researchQuestion: "State-of-the-art streaming JSON parsers with backpressure?", background: "We use a single-pass push parser." }
+  mma-journal-recall { query: "what have we learned about streaming-parser backpressure or buffering tradeoffs?" }
 ```
 
 ## 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 }`.
+All three legs (`mma-investigate`, `mma-research`, `mma-journal-recall`) 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.
 
@@ -99,6 +113,7 @@ Explore top-level orchestration aggregates sub-task results into a valid `Implem
 | 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` |
+| Prior-learning source | `results[0].findings[i].claim` plus a journal node id from `results[0].findings[i].evidence` (recall cites `` `.mmagent/journal/nodes/NNNN-…` `` or `node NNNN`). Watch the node's status: a **superseded** learning is a "we tried this and moved on" signal — surface it, don't bury it |
 | 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.
@@ -116,11 +131,21 @@ Produce **3–5 threads**. Each thread MUST have:
 - One **external citation** (from research) — `<source> — claim`.
   - 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.
+- One **prior-learning citation** (from journal-recall) WHEN a relevant node exists — `(journal) node NNNN — claim`.
+  - Pick from the recall leg's `results[0].findings`: take `claim` as the citation and pull the node id out of `evidence`.
+  - If the cited node is **superseded**, say so inline (e.g. `(journal) node 0012 [superseded by 0013] — …`) so the thread carries the "we already moved past this" signal.
+  - Use the sentinel `(no prior learning)` when the recall leg returned no relevant node — most threads on a young project will use this, and that's fine.
 - A **one-line divergence reason** — what makes this thread different from
   the others. No two threads may share the same divergence axis.
 
+If the recall leg surfaced a learning that **invalidates** a direction (a
+superseded or dropped decision that maps onto a thread you'd otherwise
+propose), do not silently omit it — keep the thread but mark it
+`⚠ already explored — see (journal) node NNNN` and weight it down in the
+recommendation. Prior learnings prune the search; they don't just decorate it.
+
 End with `## Recommended next step` — one paragraph naming which thread to
-pursue first and why.
+pursue first and why. If a prior learning rules a thread in or out, cite it here.
 
 ## Best practices
 
@@ -154,7 +179,9 @@ directions in the data.
 |---|---|
 | `mma-research` failed | Use `(no external source found)` sentinel on every external line. If `mma-investigate` also failed, do NOT synthesise — surface both errors to the user. |
 | `mma-investigate` failed | Treat as greenfield — use `(no internal anchor — fully greenfield)` sentinel. |
-| Both failed | Report both errors to the user. Do NOT fabricate threads. |
+| `mma-journal-recall` failed OR returned 0 findings | Use the `(no prior learning)` sentinel on every prior-learning line and continue — the journal leg is additive, never blocking. A young project with an empty journal hits this every time; it is not an error. |
+| All three failed | Report all errors to the user. Do NOT fabricate threads. |
+| Both investigate and research 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. |

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.7.19
+version: 4.8.0
 ---
 
 # mma-investigate
@@ -212,7 +212,11 @@ About to `Read` 3+ files just to answer one question? That's the wrong tradeoff
 
 ## 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 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).
+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 investigation results to a downstream planning step

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: 4.8.0
+---
+
+# 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,189 @@
+---
+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.8.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