@zhixuan92/multi-model-agent 3.10.4 → 3.10.5

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.5
 ---
 
 # mma-audit
@@ -72,26 +72,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.5
 ---
 
 # 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.5
 ---
 
 # 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.5
 ---
 
 # mma-debug
@@ -78,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_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.5
 ---
 
 # 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.5
 ---
 
 # mma-execute-plan

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.5
 ---
 
 # 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.5
 ---
 
 # 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.5
 ---
 
 # mma-review
@@ -75,26 +75,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.5
 ---
 
 # mma-verify
@@ -76,26 +76,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.5
 ---
 
 # multi-model-agent (router)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhixuan92/multi-model-agent",
-  "version": "3.10.4",
+  "version": "3.10.5",
   "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.5",
     "gray-matter": "^4.0.3",
     "minimist": "^1.2.8",
     "proper-lockfile": "^4.1.2",