@zhixuan92/multi-model-agent 3.10.4 → 3.10.6

package/README.md

@@ -287,7 +287,7 @@ Full design rationale: [DIRECTION.md](https://github.com/zhixuan312/multi-model-
 
 ## What's new
 
-Latest: **3.10.4** — review stages were recording the implementer's model (V3 R3 violation root cause). Now record the actual reviewer's resolved tier + model. Plus: telemetry validation is fully warn-only — events never drop, and cross-field warnings now include actual offending values (model, tokens, totals) so config issues vs lifecycle bugs are distinguishable at a glance. Full history: [CHANGELOG](https://github.com/zhixuan312/multi-model-agent/blob/master/CHANGELOG.md).
+Latest: **3.10.6** — Skill docs now match executor code. Only `mma-delegate` accepts `agentType` per task — every other route hardcodes its tier and rejects `agentType` with HTTP 400 (`/execute-plan` → standard; `/audit` / `/review` / `/debug` / `/verify` / `/investigate` → complex). The router skill previously claimed `mma-execute-plan` accepts `agentType` (false) and that `mma-verify` defaults to standard (also false; defaults to complex). Also added a new "Reasoning effort: auto-inferred" section documenting the `inferEffort()` heuristics. Full history: [CHANGELOG](https://github.com/zhixuan312/multi-model-agent/blob/master/CHANGELOG.md).
 
 ## Full documentation
 

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

@@ -8,7 +8,7 @@ when_to_use: >-
   User asks for a doc/spec/config audit OR a methodology skill
   (superpowers:dispatching-parallel-agents, /security-review) points at one AND
   mmagent is running. Audit on PROSE/SPEC docs — use mma-review for source code.
-version: 3.10.4
+version: 3.10.6
 ---
 
 # mma-audit
@@ -57,6 +57,8 @@ Send a document or set of files to workers for structured auditing. Each file is
 
 Either `document` or `filePaths` (or both) must be provided.
 
+> Worker tier for `mma-audit` is hardcoded to `complex` and is not caller-configurable. Sending `agentType` is rejected with HTTP 400.
+
 ## Full example
 
 ```bash
@@ -72,26 +74,42 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/response-shape.md
 
-## Reading the review verdicts (annotation model — 3.8.1+)
-
-The terminal envelope includes:
-- `specReviewVerdict: 'not_applicable'` — read-only routes have no spec review stage.
-- `qualityReviewVerdict` — outcome of the single annotation pass.
-- `roundsUsed` — `1` when reviewer ran (annotated or errored), `0` when reviewer was skipped.
-
-There is no rework loop. The reviewer annotates each finding in place and exits — never gates, never causes the worker to re-run.
-
-Action per `qualityReviewVerdict`:
-- `'annotated'` — every finding in `findings[]` has `reviewerConfidence` (integer 0-100) and possibly `reviewerSeverity`. Sort or filter by confidence; treat low-confidence findings with skepticism.
-- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled` or per-route `MMAGENT_READ_ONLY_REVIEW_AUDIT=disabled`) bypassed the reviewer. Findings carry no reviewer fields; treat as raw worker output.
-- `'error'` — reviewer call or response parsing failed. Findings have no reviewer fields; fall back to caution.
-
-### Per-finding reviewer fields
-
-Every finding the worker emits has the standard fields (`id`, `severity`, `claim`, `evidence`, `suggestion?`). After a successful annotation pass, two more fields are added:
-
-- `reviewerConfidence` (integer 0-100): how confident the reviewer is that the finding is correct, on-brief, and grounded. Use as a filter (`>=70`) or a sort key for triage.
-- `reviewerSeverity?` (`'high' | 'medium' | 'low'`): only present when the reviewer disagrees with the worker's `severity`. Workers tend to inflate severity; use this to dial down. Trust `reviewerSeverity` over `severity` when present.
+## Reading the findings (3.10.5+)
+
+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:
+
+| Field | Type | 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. |
+| `reviewerConfidence` | `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 `reviewerConfidence`) or deterministic-fallback (with
+  `reviewerConfidence: null`). The route ALWAYS reaches `'annotated'` unless
+  the reviewer call itself fails transport.
+- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled`).
+- `'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 `reviewerConfidence` desc
+   (nulls last).
+3. `severity` is the reviewer's authoritative final value — use it directly.
+4. Mark findings with `evidenceGrounded: false` or
+   `reviewerConfidence < 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`.
 
 ## Best practices
 

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

@@ -12,7 +12,7 @@ when_to_use: >-
   `proposedInterpretation` is a hard gate — the batch is paused, not
   informational. The batch will not complete until the caller responds. Treating
   it as advisory is the clarification-as-info anti-pattern (AP5).
-version: 3.10.4
+version: 3.10.6
 ---
 
 # mma-clarifications

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

@@ -12,7 +12,7 @@ when_to_use: >-
   Register once here, then pass the ID via `contextBlockIds` on mma-delegate /
   mma-execute-plan / mma-audit / mma-review / mma-verify / mma-debug /
   mma-investigate. Cheaper and faster than inlining the same content N times.
-version: 3.10.4
+version: 3.10.6
 ---
 
 # mma-context-blocks

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: 3.10.4
+version: 3.10.6
 ---
 
 # mma-debug
@@ -63,6 +63,8 @@ Submit a problem, context, and hypothesis to a worker for focused debugging. Unl
 | `filePaths` | string[] | no | All files investigated together (cross-file reasoning) |
 | `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` (e.g. error logs, traces) |
 
+> Worker tier for `mma-debug` is hardcoded to `complex` and is not caller-configurable. Sending `agentType` is rejected with HTTP 400.
+
 ## Full example
 
 ```bash
@@ -78,26 +80,42 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/response-shape.md
 
-## Reading the review verdicts (annotation model — 3.8.1+)
-
-The terminal envelope includes:
-- `specReviewVerdict: 'not_applicable'` — read-only routes have no spec review stage.
-- `qualityReviewVerdict` — outcome of the single annotation pass.
-- `roundsUsed` — `1` when reviewer ran (annotated or errored), `0` when reviewer was skipped.
-
-There is no rework loop. The reviewer annotates each finding in place and exits — never gates, never causes the worker to re-run.
-
-Action per `qualityReviewVerdict`:
-- `'annotated'` — every finding in `findings[]` has `reviewerConfidence` (integer 0-100) and possibly `reviewerSeverity`. Sort or filter by confidence; treat low-confidence findings with skepticism.
-- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled` or per-route `MMAGENT_READ_ONLY_REVIEW_DEBUG=disabled`) bypassed the reviewer. Findings carry no reviewer fields; treat as raw worker output.
-- `'error'` — reviewer call or response parsing failed. Findings have no reviewer fields; fall back to caution.
-
-### Per-finding reviewer fields
-
-Every finding the worker emits has the standard fields (`id`, `severity`, `claim`, `evidence`, `suggestion?`). After a successful annotation pass, two more fields are added:
-
-- `reviewerConfidence` (integer 0-100): how confident the reviewer is that the finding is correct, on-brief, and grounded. Use as a filter (`>=70`) or a sort key for triage.
-- `reviewerSeverity?` (`'high' | 'medium' | 'low'`): only present when the reviewer disagrees with the worker's `severity`. Workers tend to inflate severity; use this to dial down. Trust `reviewerSeverity` over `severity` when present.
+## Reading the findings (3.10.5+)
+
+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:
+
+| Field | Type | 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. |
+| `reviewerConfidence` | `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 `reviewerConfidence`) or deterministic-fallback (with
+  `reviewerConfidence: null`). The route ALWAYS reaches `'annotated'` unless
+  the reviewer call itself fails transport.
+- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled`).
+- `'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 `reviewerConfidence` desc
+   (nulls last).
+3. `severity` is the reviewer's authoritative final value — use it directly.
+4. Mark findings with `evidenceGrounded: false` or
+   `reviewerConfidence < 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`.
 
 ## Best practices
 

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: 3.10.4
+version: 3.10.6
 ---
 
 # mma-delegate

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: 3.10.4
+version: 3.10.6
 ---
 
 # mma-execute-plan
@@ -68,7 +68,7 @@ Dispatch named tasks from a plan file to workers. Each `tasks` string must match
 
 @include _shared/verify-and-review.md
 
-> **No `agentType` here.** Worker tier is set by the plan and per-route defaults. For ad-hoc work where you need direct tier control, use `mma-delegate`.
+> **No `agentType` here.** Worker tier is hardcoded to `standard` for every plan task; sending `agentType` (top-level or per-task) is rejected with HTTP 400. For tasks that need `complex` tier, dispatch via `mma-delegate` with the plan task as the prompt and `agentType: "complex"`.
 
 If the batch reaches `awaiting_clarification`, use `mma-clarifications` to confirm or correct the proposed interpretation.
 

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: 3.10.4
+version: 3.10.6
 ---
 
 # mma-investigate
@@ -124,26 +124,42 @@ 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, a context block, or a clarification turn).
 
-## Reading the review verdicts (annotation model — 3.8.1+)
-
-The terminal envelope includes:
-- `specReviewVerdict: 'not_applicable'` — read-only routes have no spec review stage.
-- `qualityReviewVerdict` — outcome of the single annotation pass.
-- `roundsUsed` — `1` when reviewer ran (annotated or errored), `0` when reviewer was skipped.
-
-There is no rework loop. The reviewer annotates each finding in place and exits — never gates, never causes the worker to re-run.
-
-Action per `qualityReviewVerdict`:
-- `'annotated'` — every finding in `findings[]` has `reviewerConfidence` (integer 0-100) and possibly `reviewerSeverity`. Sort or filter by confidence; treat low-confidence findings with skepticism.
-- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled` or per-route `MMAGENT_READ_ONLY_REVIEW_INVESTIGATE=disabled`) bypassed the reviewer. Findings carry no reviewer fields; treat as raw worker output.
-- `'error'` — reviewer call or response parsing failed. Findings have no reviewer fields; fall back to caution.
-
-### Per-finding reviewer fields
-
-Every finding the worker emits has the standard fields (`id`, `severity`, `claim`, `evidence`, `suggestion?`). After a successful annotation pass, two more fields are added:
-
-- `reviewerConfidence` (integer 0-100): how confident the reviewer is that the finding is correct, on-brief, and grounded. Use as a filter (`>=70`) or a sort key for triage.
-- `reviewerSeverity?` (`'high' | 'medium' | 'low'`): only present when the reviewer disagrees with the worker's `severity`. Workers tend to inflate severity; use this to dial down. Trust `reviewerSeverity` over `severity` when present.
+## Reading the findings (3.10.5+)
+
+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:
+
+| Field | Type | 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. |
+| `reviewerConfidence` | `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 `reviewerConfidence`) or deterministic-fallback (with
+  `reviewerConfidence: null`). The route ALWAYS reaches `'annotated'` unless
+  the reviewer call itself fails transport.
+- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled`).
+- `'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 `reviewerConfidence` desc
+   (nulls last).
+3. `severity` is the reviewer's authoritative final value — use it directly.
+4. Mark findings with `evidenceGrounded: false` or
+   `reviewerConfidence < 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`.
 
 ## Best practices
 

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

@@ -10,7 +10,7 @@ when_to_use: >-
   you want to re-try the failed indices only. Prefer this over re-dispatching
   the whole batch or inline-retrying — it's idempotent and preserves the
   original batch's diagnostics.
-version: 3.10.4
+version: 3.10.6
 ---
 
 # mma-retry

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

@@ -10,7 +10,7 @@ when_to_use: >-
   AND mmagent is running. Delegate so each file reviews on its own worker; the
   main agent only decides what to merge. Review on SOURCE CODE — use mma-audit
   for prose specs / configs.
-version: 3.10.4
+version: 3.10.6
 ---
 
 # mma-review
@@ -60,6 +60,8 @@ Send code files to workers for structured review. Each file is reviewed independ
 
 Either `code` or `filePaths` (or both) must be provided.
 
+> Worker tier for `mma-review` is hardcoded to `complex` and is not caller-configurable. Sending `agentType` is rejected with HTTP 400.
+
 ## Full example
 
 ```bash
@@ -75,26 +77,42 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/response-shape.md
 
-## Reading the review verdicts (annotation model — 3.8.1+)
-
-The terminal envelope includes:
-- `specReviewVerdict: 'not_applicable'` — read-only routes have no spec review stage.
-- `qualityReviewVerdict` — outcome of the single annotation pass.
-- `roundsUsed` — `1` when reviewer ran (annotated or errored), `0` when reviewer was skipped.
-
-There is no rework loop. The reviewer annotates each finding in place and exits — never gates, never causes the worker to re-run.
-
-Action per `qualityReviewVerdict`:
-- `'annotated'` — every finding in `findings[]` has `reviewerConfidence` (integer 0-100) and possibly `reviewerSeverity`. Sort or filter by confidence; treat low-confidence findings with skepticism.
-- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled` or per-route `MMAGENT_READ_ONLY_REVIEW_REVIEW=disabled`) bypassed the reviewer. Findings carry no reviewer fields; treat as raw worker output.
-- `'error'` — reviewer call or response parsing failed. Findings have no reviewer fields; fall back to caution.
-
-### Per-finding reviewer fields
-
-Every finding the worker emits has the standard fields (`id`, `severity`, `claim`, `evidence`, `suggestion?`). After a successful annotation pass, two more fields are added:
-
-- `reviewerConfidence` (integer 0-100): how confident the reviewer is that the finding is correct, on-brief, and grounded. Use as a filter (`>=70`) or a sort key for triage.
-- `reviewerSeverity?` (`'high' | 'medium' | 'low'`): only present when the reviewer disagrees with the worker's `severity`. Workers tend to inflate severity; use this to dial down. Trust `reviewerSeverity` over `severity` when present.
+## Reading the findings (3.10.5+)
+
+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:
+
+| Field | Type | 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. |
+| `reviewerConfidence` | `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 `reviewerConfidence`) or deterministic-fallback (with
+  `reviewerConfidence: null`). The route ALWAYS reaches `'annotated'` unless
+  the reviewer call itself fails transport.
+- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled`).
+- `'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 `reviewerConfidence` desc
+   (nulls last).
+3. `severity` is the reviewer's authoritative final value — use it directly.
+4. Mark findings with `evidenceGrounded: false` or
+   `reviewerConfidence < 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`.
 
 ## Best practices
 

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

@@ -10,7 +10,7 @@ when_to_use: >-
   against implemented work BEFORE claiming success. Delegate so each checklist
   item gets independent evidence-gathering on a worker. Use this BEFORE saying
   "done" — never after.
-version: 3.10.4
+version: 3.10.6
 ---
 
 # mma-verify
@@ -61,6 +61,8 @@ Submit work product and a checklist to workers for independent verification. Eac
 | `filePaths` | string[] | no | Files to verify against (workers can read them) |
 | `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` (e.g. the spec the work was supposed to satisfy) |
 
+> Worker tier for `mma-verify` is hardcoded to `complex` and is not caller-configurable. Sending `agentType` is rejected with HTTP 400.
+
 ## Full example
 
 ```bash
@@ -76,26 +78,42 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/response-shape.md
 
-## Reading the review verdicts (annotation model — 3.8.1+)
-
-The terminal envelope includes:
-- `specReviewVerdict: 'not_applicable'` — read-only routes have no spec review stage.
-- `qualityReviewVerdict` — outcome of the single annotation pass.
-- `roundsUsed` — `1` when reviewer ran (annotated or errored), `0` when reviewer was skipped.
-
-There is no rework loop. The reviewer annotates each finding in place and exits — never gates, never causes the worker to re-run.
-
-Action per `qualityReviewVerdict`:
-- `'annotated'` — every finding in `findings[]` has `reviewerConfidence` (integer 0-100) and possibly `reviewerSeverity`. Sort or filter by confidence; treat low-confidence findings with skepticism.
-- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled` or per-route `MMAGENT_READ_ONLY_REVIEW_VERIFY=disabled`) bypassed the reviewer. Findings carry no reviewer fields; treat as raw worker output.
-- `'error'` — reviewer call or response parsing failed. Findings have no reviewer fields; fall back to caution.
-
-### Per-finding reviewer fields
-
-Every finding the worker emits has the standard fields (`id`, `severity`, `claim`, `evidence`, `suggestion?`). After a successful annotation pass, two more fields are added:
-
-- `reviewerConfidence` (integer 0-100): how confident the reviewer is that the finding is correct, on-brief, and grounded. Use as a filter (`>=70`) or a sort key for triage.
-- `reviewerSeverity?` (`'high' | 'medium' | 'low'`): only present when the reviewer disagrees with the worker's `severity`. Workers tend to inflate severity; use this to dial down. Trust `reviewerSeverity` over `severity` when present.
+## Reading the findings (3.10.5+)
+
+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:
+
+| Field | Type | 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. |
+| `reviewerConfidence` | `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 `reviewerConfidence`) or deterministic-fallback (with
+  `reviewerConfidence: null`). The route ALWAYS reaches `'annotated'` unless
+  the reviewer call itself fails transport.
+- `'skipped'` — kill switch (`MMAGENT_READ_ONLY_REVIEW=disabled`).
+- `'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 `reviewerConfidence` desc
+   (nulls last).
+3. `severity` is the reviewer's authoritative final value — use it directly.
+4. Mark findings with `evidenceGrounded: false` or
+   `reviewerConfidence < 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`.
 
 ## Best practices
 

package/dist/skills/multi-model-agent/SKILL.md

@@ -11,7 +11,7 @@ when_to_use: >-
   tasks — AND mmagent is running. Read this once, pick the matching mma-* skill,
   and delegate there. Applies equally whether the user invoked a superpowers
   methodology skill or asked directly.
-version: 3.10.4
+version: 3.10.6
 ---
 
 # multi-model-agent (router)
@@ -156,13 +156,34 @@ Every request requires `Authorization: Bearer $MMAGENT_AUTH_TOKEN`. The token ro
 
 ## Worker tier: `agentType`
 
-`mma-delegate` and `mma-execute-plan` accept `agentType: "standard" | "complex"`. Default is `"standard"` (cheaper, faster). Pick `"complex"` when:
+Only `mma-delegate` accepts `agentType: "standard" | "complex"` per task — default `"standard"` (cheaper, faster). Pick `"complex"` when:
 
 - The task touches many files or requires multi-step reasoning a standard-tier model cannot hold in context.
 - A prior standard run came back with `filesWritten: 0` or `incompleteReason: "turn_cap"` / `"cost_cap"` / `"timeout"`.
 - The task is security-sensitive or ambiguous enough that being wrong is costly.
 
-`mma-audit`, `mma-review`, `mma-debug`, `mma-investigate` already default to complex; `mma-verify` already defaults to standard. These are not caller-configurable.
+Every other route hardcodes its tier and rejects `agentType` with HTTP 400:
+
+| Route | Hardcoded tier |
+|---|---|
+| `mma-execute-plan` | `standard` |
+| `mma-audit` | `complex` |
+| `mma-review` | `complex` |
+| `mma-debug` | `complex` |
+| `mma-verify` | `complex` |
+| `mma-investigate` | `complex` |
+
+If you need `complex` tier on plan-style work, dispatch via `mma-delegate` with the plan task as the prompt and `agentType: "complex"`.
+
+## Reasoning effort: auto-inferred
+
+Independent of tier, every task runs through `inferEffort(prompt)` (`run-tasks/index.ts`) when `effort` is undefined:
+
+- Code block > 20 lines in the prompt → `low` (treated as exact-write).
+- File path + action verb (`edit`/`modify`/`update`/`fix`/`refactor`/`replace`) → `medium`.
+- Otherwise → falls through to provider config default.
+
+This is automatic and not caller-overridable from any `mma-*` skill — it shapes how hard the worker thinks within its tier.
 
 ## General flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhixuan92/multi-model-agent",
-  "version": "3.10.4",
+  "version": "3.10.6",
   "type": "module",
   "license": "MIT",
   "description": "Standalone HTTP server for multi-model-agent. Routes tool-invocation work to Claude, Codex, or OpenAI-compatible sub-agents with async-polling REST dispatch and installable skills for Claude Code, Gemini CLI, Codex CLI, and Cursor.",
@@ -52,7 +52,7 @@
   },
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "^8.5.0",
-    "@zhixuan92/multi-model-agent-core": "^3.10.4",
+    "@zhixuan92/multi-model-agent-core": "^3.10.6",
     "gray-matter": "^4.0.3",
     "minimist": "^1.2.8",
     "proper-lockfile": "^4.1.2",