@zhixuan92/multi-model-agent 4.9.1 → 5.0.1

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

@@ -1,270 +0,0 @@
----
-name: mma-audit
-description: >-
-  Use when the user asks to audit a spec / plan / design doc / skill file. The
-  `subtype` field picks the criteria set. `default` (prose-coherence) is the
-  general doc auditor. `plan` verifies a code-execution plan against the actual
-  codebase — run this before any `mma-execute-plan` dispatch. `spec` audits
-  requirement prose for testability and decision-trace. `skill` audits a
-  SKILL.md against reader-effectiveness criteria.
-when_to_use: >-
-  User asks for a doc / spec / plan / skill 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.
-  Audit a CODE-EXECUTION PLAN against the codebase — use subtype=plan.
-version: 4.9.1
----
-
-# mma-audit
-
-## Overview
-
-`mma-audit` sends a prose artifact to workers for structured auditing. The `subtype` field picks WHICH criteria set the workers apply — every subtype runs through the same sequential-criteria read-only lifecycle, but each one carries its own criteria list, semantics, and prompt scaffolding.
-
-**Four subtypes — picked by the kind of artifact, not by the lens you want:**
-
-| You're auditing… | Use… | What it checks |
-|---|---|---|
-| A general prose artifact (design doc, recommendation, post-mortem, README) | `subtype: 'default'` | Comprehensive prose-coherence — would a literal-following worker produce the right outcome from this prose alone? Catches ambiguity, contradictions, missing branches, drift, scope-creep. **Does NOT verify against any codebase.** |
-| A **code-execution PLAN** (`docs/superpowers/plans/*.md` or similar) before running it via `mma-execute-plan` | `subtype: 'plan'` | Plan-vs-codebase coherence — for every method / type / file path / signature / import / verify command the plan names, the codebase actually contains it as described. Catches the bug class the prose-coherence audit cannot see (e.g. plan says `registerBlock` but actual interface is `register`). |
-| A **requirement spec** (what we want, why; success criteria) | `subtype: 'spec'` | Requirement-prose executability across 9 criteria — testability, scope explicitness AND decomposability, acceptance-criteria coverage, non-functional capture, requirement conflicts, decision-trace, assumption exposure, placeholder scan, and design-decomposition presence (architecture / components / data flow / error handling / testing). |
-| A **SKILL.md** for an `mma-*` skill or comparable agent-facing playbook | `subtype: 'skill'` | Skill-file reader-effectiveness — when-to-use specificity, endpoint contract integrity, example correctness, anti-pattern coverage, link integrity. |
-
-If you want to bias workers toward a narrow lens (security only, performance only, accessibility only), put that in the free-text `background` portion of the prompt — `subtype` is criteria machinery, not a lens selector.
-
-## When to Use
-
-- `subtype: 'default'` — a general prose artifact needs a critical read for internal executability (the artifact will be acted on by a worker reading the prose alone).
-- `subtype: 'plan'` — you have a written code-execution plan on disk and you're about to dispatch tasks from it via `mma-execute-plan`. This is the ONLY subtype that grounds findings against real source files.
-- `subtype: 'spec'` — you have a requirement / brainstorming-output spec and want to verify every requirement is testable, traceable, and unambiguous BEFORE writing the plan. Typical predecessor to `writing-plans`.
-- `subtype: 'skill'` — you're authoring or revising an `mma-*` skill or comparable SKILL.md and want to know whether agents will actually read it the right way.
-
-**Don't use mma-audit when:** the thing being audited is source code (→ `mma-review`); a 30-second `Read` would answer it; or you want to verify a plan that hasn't been written yet (write the plan first).
-
-## Endpoint
-
-`POST /audit?cwd=<abs-path>`
-
-@include _shared/auth.md
-
-## Request body
-
-```json
-{
-  "document": "inline content to audit (optional if filePaths given)",
-  "subtype": "default",
-  "filePaths": ["/project/docs/spec.md"],
-  "contextBlockIds": []
-}
-```
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| `document` | string | no | Inline document content |
-| `subtype` | `'default' \| 'plan' \| 'spec' \| 'skill'` | no (defaults to `'default'`) | See "Picking subtype" below. |
-| `filePaths` | string[] | no | Files to audit (one worker per file, parallel) |
-| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
-
-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.
-
-### Picking subtype
-
-| Value | When to use |
-|---|---|
-| `default` (or omit the field) | **General prose — design doc, recommendation, post-mortem, README, brief.** Comprehensive prose-coherence audit. Does NOT verify against any codebase. |
-| `plan` | **Code-execution plans being audited against a real codebase.** Single-file input (the plan markdown). Workers grep / read source files under `cwd` to verify every named symbol / path / signature / import / verify command. Use this BEFORE every `mma-execute-plan` dispatch. |
-| `spec` | **Requirement spec / brainstorming-output / what-we-want prose.** 9 criteria target testability, scope explicitness + decomposability, acceptance-criteria coverage, non-functional capture, requirement conflicts, decision-trace, assumption exposure, placeholder scan, and design-decomposition presence. |
-| `skill` | **`SKILL.md` or comparable agent-facing playbook.** Criteria target when-to-use specificity, endpoint contract integrity, example correctness, anti-pattern coverage, link integrity. |
-
-You can run BOTH on a plan: first `spec` or `default` (prose quality), then `plan` (does the plan match the codebase?). They cover orthogonal failure modes.
-
-The legacy `auditType` field and its `correctness` / `style` / `general` / `security` / `performance` values no longer exist. Sending `auditType` returns `400 invalid_request`. Sending unknown `subtype` values returns `400 invalid_request` with the allowed enum.
-
-### Plan-audit specifics
-
-When `subtype: 'plan'`:
-
-- `filePaths` MUST contain exactly **one entry** — the plan markdown. Sending zero or 2+ entries → `400 invalid_request` with the message: *"Plan audit takes exactly one filePath (the plan markdown). The worker discovers and verifies source files itself via its tool surface — do not pre-list source files."*
-- `document` (inline content) is not used in plan mode — the plan must be on disk so workers can reference it by `?cwd=`-relative path.
-- The worker runs the sequential-criteria loop with the plan-audit criteria set across 12 perspectives in three groups: **EXTERNAL CODEBASE COHERENCE** (1 PATH EXISTENCE, 2 SYMBOL EXISTENCE, 3 SIGNATURE MATCH, 4 IMPORT GRAPH, 5 TEST HARNESS AVAILABILITY, 6 STEP SEQUENCE WITHIN TASK, 7 CROSS-TASK DEPENDENCIES, 8 VERIFICATION COMMAND VALIDITY), **INTRA-PLAN STRUCTURE** (9 TASK GRANULARITY, 11 PLACEHOLDER LANGUAGE, 12 PLAN SKELETON), and **SPEC ALIGNMENT** (10 SPEC COVERAGE).
-- To enable perspective 10 (SPEC COVERAGE), register the upstream spec as a context block via `mma-context-blocks` and pass its `blockId` in `contextBlockIds`. Without a spec in context, perspective 10 emits "No findings for this criterion." and the other 11 still run.
-- Read the findings list. Fix the plan and re-audit if any `critical` or `high` plan-audit findings remain.
-
-## Full example
-
-### Default audit (general prose)
-
-```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 '{"subtype":"default","filePaths":["/project/docs/api-spec.md"]}' \
-  "http://localhost:$PORT/audit?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
-```
-
-### Spec audit (requirement prose)
-
-```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 '{"subtype":"spec","filePaths":["/project/docs/superpowers/specs/2026-05-12-feature-design.md"]}' \
-  "http://localhost:$PORT/audit?cwd=/project")
-```
-
-### Skill audit (SKILL.md)
-
-```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 '{"subtype":"skill","filePaths":["/project/packages/server/src/skills/mma-audit/SKILL.md"]}' \
-  "http://localhost:$PORT/audit?cwd=/project")
-```
-
-### Plan audit (verify a code-execution plan against the codebase)
-
-```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 '{"subtype":"plan","filePaths":["/project/docs/superpowers/plans/2026-05-10-feature.md"]}' \
-  "http://localhost:$PORT/audit?cwd=/project")
-```
-
-@include _shared/polling.md
-
-@include _shared/response-shape.md
-
-## Reading the findings
-
-The main agent reads `completed` + `message` + `findings` — the findings are the answer. For
-read-only routes, `filesChanged` is always `[]` and `commitSha` is always `null`.
-
-```json
-{
-  "completed": true,
-  "message": "Plan audit complete; 2 findings.",
-  "findings": [
-    { "id": "F1", "severity": "high", "category": "path-existence",
-      "claim": "Step 3 names `src/utils/foo.ts` which does not exist.",
-      "evidence": "Worker grepped for the file under cwd — no match found.",
-      "suggestion": "Use `src/utils/bar.ts` instead.",
-      "source": "implementer" }
-  ],
-  "filesChanged": [],
-  "commitSha": null,
-  "summary": "...",
-  "telemetry": { ... }
-}
-```
-
-### Finding shape
-
-Every finding has this shape:
-
-| Field | Type | Notes |
-|---|---|---|
-| `id` | string | Worker-assigned, e.g. `F1`, `F2`. Stable across chain. |
-| `severity` | `'critical' \| 'high' \| 'medium' \| 'low'` | 4-tier. |
-| `category` | string | Topical bucket, e.g. `path-existence`, `prose-coherence`. |
-| `claim` | string | One-sentence summary. |
-| `evidence` | string ≥20 chars | Verbatim from source when grounded. |
-| `suggestion?` | string | Optional fix recommendation. |
-| `source` | `'implementer' \| 'reviewer'` | Who produced the finding. |
-
-`annotatorConfidence` and `evidenceGrounded` are retired — they were v4 fields with no producers.
-
-### Recommended rendering by the main agent
-
-1. Show ALL findings — never silently drop. Severity and grounding are soft
-   signals, not gates.
-2. Default sort: severity (critical → low), then `id` ascending.
-3. `severity` is the authoritative value — use it directly.
-4. Mark findings with `evidence` shorter than 30 chars as "low-evidence"
-   (lighter color or `(low evidence)` annotation). User decides what to do.
-5. Severity-tier counts feed the dashboard.
-
-## Best practices
-
-This skill is one step in the larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-audit`:
-
-- **Recipe A — Audit-iterate-clean.** `mma-audit` → fix → `mma-audit` again. Sequential rounds. Register the doc via `mma-context-blocks` before round 1 and reuse the same ID across all rounds — avoids re-inlining the same content into every audit call.
-
-- **Recipe E — Plan-validate-execute.** Before any `mma-execute-plan` batch, run `mma-audit` with `subtype: 'plan'` on the plan file. Read the findings. If any `critical` / `high` finding survives, fix the plan and re-audit. This catches the bug class where the plan's named methods/files don't actually exist in the codebase — symbols a prose-coherence audit cannot see.
-
-- **Recipe F — Spec-then-plan-then-execute (the canonical flow).** When working from a brainstorming spec: `mma-audit` (`subtype: 'spec'`) → fix → `writing-plans` → register the spec as a context block via `mma-context-blocks` → `mma-audit` (`subtype: 'plan'`, `contextBlockIds: [specBlockId]`) → fix → `mma-execute-plan`. Spec audit covers requirement-prose executability; plan audit covers BOTH plan-vs-codebase coherence AND plan-vs-spec coverage (perspective 10 fires only when the spec is in context, which is why the context-block step is load-bearing in this recipe).
-
-Anti-pattern alert: **`parallel-rounds-same-target`** (AP1). Three parallel audits on the same document re-flag the same issues without seeing each other's fixes. Run rounds sequentially with a fix between each.
-
-## Common pitfalls
-
-❌ **Auditing source code with `mma-audit`**
-The auditor lacks codebase context (no type info, no call-site lookup, no test awareness). Findings are speculative. **Fix:** use `mma-review` — it pulls in surrounding source context and validates against the actual types.
-
-❌ **Single huge `document` string instead of `filePaths`**
-Inline docs lose the file boundary, so the per-file parallel split degenerates to one worker. **Fix:** save to disk first, pass `filePaths`.
-
-❌ **Sending the legacy `auditType` field**
-The field was renamed to `subtype` and the value set was narrowed. **Fix:** use `subtype` with one of `default` / `plan` / `spec` / `skill`. For "security only" / "performance only" lenses, put the bias in the free-text prompt — there is no narrow-lens subtype.
-
-❌ **Re-auditing the same files round after round without delta context**
-Round 2 worker has no idea what round 1 found. **Fix:** register the round 1 findings as a context block (`mma-context-blocks`) and pass `contextBlockIds` to round 2.
-
-## 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)
-
-**Use cases:**
-- Pass round-N audit findings to round N+1 via `contextBlockIds`
-- Feed audit results into a downstream `mma-delegate` fix step
-- Accumulate findings across iterative audit rounds
-
-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 audit's conclusion status:
-
-| Field | Type | Meaning |
-|---|---|---|
-| `findingsOutcome` | `'found' \| 'clean' \| 'not_applicable'` | Answers the question: did the audit uncover issues? |
-| `findingsOutcomeReason` | `string \| null` | When `findingsOutcome` is set, this explains why (e.g. "3 critical findings: broken paths, missing symbols, mismatched signatures" or "Document is clean across all audit criteria"). |
-| `outcomeInferred` | `boolean` | `true` if the system inferred the outcome from findings count; `false` if the auditor explicitly stated it. |
-| `outcomeMalformed` | `boolean` | `true` if the outcome line was malformed and had to be repaired; `false` otherwise. |
-
-### Enum values
-
-- **`found`** — the audit surfaced one or more issues (findings) in the artifact across one or more criteria. This indicates the artifact needs rework before downstream use.
-- **`clean`** — the audit completed and found zero issues. The artifact is clear across all audit criteria and ready for downstream use.
-- **`not_applicable`** — the audit could not proceed (e.g., wrong input type, missing preconditions, or system error). This is rare; most audits resolve to `found` or `clean`.
-
-### Empty findings ≠ failure
-
-A crucial semantic: **empty findings does NOT mean `completed: false` or a failed task.** Finding nothing wrong is a successful audit outcome — it means the document passed the bar. An audit with zero findings is `completed: true` with `findingsOutcome: 'clean'`.
-
-### Per-route legal outcomes
-
-The legal outcomes for this route are: `['found', 'clean']`
-
-- **`found`** — one or more issues were detected across the audit criteria.
-- **`clean`** — zero issues were detected; the artifact is ready for downstream use.
-
-The outcome `not_applicable` is not legal for `mma-audit` (except on actual precondition failures) because an audit always produces a verdict: either issues found or clean.
-
-@include _shared/error-handling.md

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

@@ -1,148 +0,0 @@
----
-name: mma-context-blocks
-description: >-
-  Use when a document larger than ~2 KB will be referenced by 2+ subsequent
-  mma-* calls — register once, pass the returned ID to each call instead of
-  re-uploading the same content. OR a spec / plan / error log was already
-  inlined into one task and is about to be inlined into a second — register on
-  the second reference, never the third.
-when_to_use: >-
-  A document (spec, plan, codebase summary, prior round's findings, error log)
-  larger than ~2 KB will be referenced by two or more mma-* calls in a row.
-  Register once here, then pass the ID via `contextBlockIds` on mma-delegate /
-  mma-execute-plan / mma-audit / mma-review / mma-debug / mma-investigate.
-  Cheaper and faster than inlining the same content N times.
-version: 4.9.1
----
-
-# mma-context-blocks
-
-## Overview
-
-Store large documents once; reference them by ID in subsequent `mma-*` calls via `contextBlockIds`. The service prepends the block content to each task prompt that references the ID — content is transmitted ONCE to the daemon, then reused server-side.
-
-**Core principle:** Without context blocks, the same document is sent N times for N tasks. Blocks transmit once. The savings compound on shared specs, prior-round findings, and codebase summaries.
-
-## When to Use
-
-**Use when:**
-- A doc >2 KB will be referenced by ≥2 mma-* calls
-- You're running iterative audit/review rounds (round 2 references round 1's findings)
-- A spec or design doc is the shared input across N parallel tasks
-- A long error log is the context for debug + delegate calls
-
-**Don't use when:**
-- The doc is <2 KB and used once → just inline it (registration overhead exceeds savings)
-- The doc changes between calls → context blocks are immutable; register a new one
-- Single task that doesn't reference any large shared content → no benefit
-
-## Endpoints
-
-### Register a context block
-
-`POST /context-blocks?cwd=<abs-path>`
-
-@include _shared/auth.md
-
-#### Request body
-
-```json
-{
-  "content": "# Project spec\n...",
-  "ttlMs": 3600000
-}
-```
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| `content` | string | yes | Document content (min 1 char, max 50 MiB) |
-| `ttlMs` | number | no | Time-to-live in ms; omit for idle-expiry (default 24 h idle). A block that is not referenced by any active batch for 24 h is eligible for eviction. |
-
-#### Response (201)
-
-```json
-{ "id": "cb_abc123" }
-```
-
-Use this `id` as a `contextBlockIds` entry in any `mma-*` skill that supports it.
-
-### Delete a context block
-
-`DELETE /context-blocks/:id?cwd=<abs-path>`
-
-Returns `200 { ok: true }` on success. Returns `409 pinned` if the block is held by one or more active batches — wait for those batches to complete before deleting.
-
-## Full example
-
-```bash
-# Register spec document once
-ID=$(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 "{\"content\":$(jq -Rs . < /project/docs/spec.md)}" \
-  "http://localhost:$PORT/context-blocks?cwd=/project" | jq -r '.id')
-
-# Reference from N delegate tasks
-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 "{\"tasks\":[
-    {\"prompt\":\"Implement section 3 per spec\",\"contextBlockIds\":[\"$ID\"]},
-    {\"prompt\":\"Implement section 4 per spec\",\"contextBlockIds\":[\"$ID\"]}
-  ]}" \
-  "http://localhost:$PORT/delegate?cwd=/project"
-```
-
-## v5 wire shape (register-context-block route)
-
-Every task result is a `ComposePayload`. For the `register-context-block` route, the envelope has one additional field beyond the standard seven:
-
-```json
-{
-  "completed": true,
-  "message": "Context block cb_abc123 registered (12345 bytes)",
-  "findings": [],
-  "summary": "",
-  "filesChanged": [],
-  "commitSha": null,
-  "blockId": "cb_abc123",
-  "telemetry": { ... }
-}
-```
-
-`blockId` is **non-null only for the `register-context-block` route**. For every other route (`delegate`, `execute-plan`, `investigate`, etc.), `blockId` is `null`. This is the only signal that distinguishes a register-context-block result from any other route — no route-keyed discriminated union, just one extra nullable field on the shared shape.
-
-The terminal context block (per-task, auto-registered) uses a different ID format and is separate from the `blockId` in the wire envelope.
-
-## Best practices
-
-This skill is the cross-cutting state mechanism described in `multi-model-agent` → "Best practices". Recipes that use context blocks:
-
-- **Recipe A — Audit-iterate-clean.** Register the doc once before round 1; pass round-N's findings block ID into round N+1.
-- **Recipe B — Debug-fix-verify.** Register the failing test output / reproduction log before the debug call; reuse on verify.
-- **Recipe C — Investigate-plan-execute.** Register the plan file before `mma-execute-plan`.
-- **Recipe D — Plan-execute-retry.** No new registration needed — `mma-retry` inherits the original batch's `contextBlockIds`.
-
-Anti-pattern alert: **`re-inlined-shared-content`** (AP3). Pasting the same spec into 5 task prompts costs N× tokens. Register once; pass `contextBlockIds`.
-
-## Common pitfalls
-
-❌ **Inlining the same 50KB spec into every task prompt**
-> tasks: [{prompt: "Implement section 3:\n[50KB spec]"}, {prompt: "Implement section 4:\n[50KB spec]"}]
-
-N×50KB transmissions; main context burns through tokens. **Fix:** register the spec once, pass `contextBlockIds: ["cb_xxx"]` to each task.
-
-❌ **Forgetting to delete unused blocks**
-Blocks count against the project's context-block quota (`maxEntries` 500). **Fix:** explicitly `DELETE` after the dependent batches finish — or let idle expiry (24 h) evict them.
-
-❌ **Trying to update a block's content**
-Blocks are immutable. **Fix:** register a new block with the new content; switch the `contextBlockIds` to the new ID.
-
-❌ **Deleting a block while a batch still references it**
-Returns `409 pinned`. **Fix:** poll the dependent batches to terminal first, then delete.
-
-@include _shared/error-handling.md

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

@@ -1,208 +0,0 @@
----
-name: mma-debug
-description: >-
-  Use when a test fails, a build breaks, or behavior is unexpected AND narrowing
-  the root cause requires reading files, reproducing the failure, or tracing
-  across multiple modules — the worker investigates so the main agent stays on
-  the hypothesis
-when_to_use: >-
-  A failure has surfaced (test/build/runtime) AND you need investigation work —
-  read files, reproduce, trace — OR a methodology skill
-  (superpowers:systematic-debugging) points at the investigation step. Delegate
-  the read/reproduce/trace; the main agent stays on the hypothesis and the fix.
-version: 4.9.1
----
-
-# mma-debug
-
-## Overview
-
-Submit a problem, context, and hypothesis to a worker for focused debugging. Unlike `mma-audit` and `mma-review`, all `filePaths` are investigated TOGETHER in a single task (not parallelized per file) — debugging needs cross-file reasoning.
-
-**Core principle:** The hypothesis is judgment (your job). Reading files and reproducing the failure is labor (the worker's job). Pass the hypothesis as input; receive structured findings.
-
-## When to Use
-
-**Use when:**
-- A test fails / build breaks / runtime behavior is unexpected
-- The root cause likely spans 2+ files
-- You have a hypothesis to test (or want the worker to suggest one)
-- A methodology skill (`superpowers:systematic-debugging`) routed here
-
-**Don't use when:**
-- The error message points at one file you can read in 30 seconds → just `Read`
-- You don't know what's broken yet → use `mma-investigate` first to map the area
-- You already know the fix → skip debug, dispatch `mma-delegate` with the fix
-
-## Endpoint
-
-`POST /debug?cwd=<abs-path>`
-
-@include _shared/auth.md
-
-## Request body
-
-```json
-{
-  "problem": "POST /login returns 500 when password contains special characters",
-  "context": "Regression introduced in commit abc123; only affects production config",
-  "hypothesis": "The bcrypt binding fails on non-ASCII input in the Docker image",
-  "subtype": "default",
-  "filePaths": [
-    "/project/src/auth/login.ts",
-    "/project/src/auth/password.ts"
-  ],
-  "contextBlockIds": []
-}
-```
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| `problem` | string | yes | What is broken (one sentence; concrete symptom) |
-| `context` | string | no | Background — what changed recently, what works, what doesn't |
-| `hypothesis` | string | no | Your initial theory; worker tests it first, then explores |
-| `subtype` | `'default'` | no (defaults to `'default'`) | Reserved for future criteria sets; only `default` is wired today. |
-| `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
-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 '{"problem":"Tests fail on CI only","hypothesis":"Missing env var","filePaths":["/project/src/config.ts"]}' \
-  "http://localhost:$PORT/debug?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
-```
-
-@include _shared/polling.md
-
-@include _shared/response-shape.md
-
-## Reading the findings
-
-The main agent reads `completed` + `message` + `findings` — the findings are the answer. For
-read-only routes, `filesChanged` is always `[]` and `commitSha` is always `null`.
-
-```json
-{
-  "completed": true,
-  "message": "Investigation complete; 1 finding.",
-  "findings": [
-    { "id": "F1", "severity": "high", "category": "root-cause",
-      "claim": "bcrypt binding fails on non-ASCII input in the Docker image.",
-      "evidence": "Worker reproduced the failure with `pass='café'`; strace shows EINVAL on encode call.",
-      "suggestion": "Normalize input to NFC form before calling bcrypt.",
-      "source": "implementer" }
-  ],
-  "filesChanged": [],
-  "commitSha": null,
-  "summary": "...",
-  "telemetry": { ... }
-}
-```
-
-### Finding shape
-
-Every finding has this shape:
-
-| Field | Type | Notes |
-|---|---|---|
-| `id` | string | Worker-assigned, e.g. `F1`, `F2`. Stable across chain. |
-| `severity` | `'critical' \| 'high' \| 'medium' \| 'low'` | 4-tier. |
-| `category` | string | Topical bucket, e.g. `root-cause`, `reproduction`. |
-| `claim` | string | One-sentence summary. |
-| `evidence` | string ≥20 chars | Verbatim from source when grounded. |
-| `suggestion?` | string | Optional fix recommendation. |
-| `source` | `'implementer' \| 'reviewer'` | Who produced the finding. |
-
-`annotatorConfidence` and `evidenceGrounded` are retired — they were v4 fields with no producers.
-
-### Recommended rendering by the main agent
-
-1. Show ALL findings — never silently drop. Severity and grounding are soft
-   signals, not gates.
-2. Default sort: severity (critical → low), then `id` ascending.
-3. `severity` is the authoritative value — use it directly.
-4. Mark findings with `evidence` shorter than 30 chars as "low-evidence"
-   (lighter color or `(low evidence)` annotation). User decides what to do.
-5. Severity-tier counts feed the dashboard.
-
-## Best practices
-
-This skill is one step in the larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-debug`:
-
-- **Recipe B — Debug-fix-review.** `mma-debug` → `mma-delegate` (apply fix) → `mma-review` with the acceptance criteria in the brief. Strict order. Register the failing test output / reproduction log as a context block before the debug call; reuse it on the review call.
-
-Anti-pattern alert: **`inline-labor-leakage`** (AP2). If you're about to read 3+ files in main context to "understand the bug," that's the labor we delegate — call `mma-debug` with the hypothesis instead.
-
-## Common pitfalls
-
-❌ **Vague `problem`**
-> "The login is broken"
-
-Worker has no symptom to chase. **Fix:** specific reproducer — `"POST /login with body {user:'a@b.c', pass:'café'} returns 500 with 'invalid character' in stderr"`.
-
-❌ **No `hypothesis`**
-The worker explores blindly, often investigates the wrong area first. **Fix:** even a weak hypothesis ("might be encoding-related") narrows the search space.
-
-❌ **Splitting one bug across multiple `mma-debug` calls**
-Debug intentionally bundles `filePaths` for cross-file reasoning. Splitting defeats this. **Fix:** one call with all suspect files; if you really have N independent failures, use `mma-delegate` with N tasks.
-
-❌ **Treating `mma-debug` as the fix step**
-Debug investigates and proposes; it doesn't necessarily write the fix. **Fix:** if the worker identifies a fix, dispatch `mma-delegate` to implement it (or write it inline if you understand it).
-
-❌ **Skipping when an error message looks self-explanatory**
-Often the obvious cause isn't the real one. **Fix:** a 30-second debug pass costs less than a wrong fix that breaks something else.
-
-## 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)
-
-**Use cases:**
-- Pass debug findings to a downstream `mma-delegate` fix step
-- Feed the root-cause analysis into a follow-up `mma-review` with acceptance criteria in the brief
-- Carry debug context forward through the debug → fix → review 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 debugging investigation's conclusion status:
-
-| Field | Type | Meaning |
-|---|---|---|
-| `findingsOutcome` | `'found' \| 'clean' \| 'not_applicable'` | Answers the question: did the investigation identify a root cause? |
-| `findingsOutcomeReason` | `string \| null` | When `findingsOutcome` is set, this explains why (e.g. "Root cause identified with high confidence: bcrypt binding fails on non-ASCII input" or "No evidence supports the hypothesis; root cause remains unknown"). |
-| `outcomeInferred` | `boolean` | `true` if the system inferred the outcome from findings count; `false` if the investigator explicitly stated it. |
-| `outcomeMalformed` | `boolean` | `true` if the outcome line was malformed and had to be repaired; `false` otherwise. |
-
-### Enum values
-
-- **`found`** — the investigation identified one or more root-cause hypotheses (findings) with supporting evidence. This indicates the problem has a diagnosed cause.
-- **`clean`** — the investigation completed but found zero root causes. This is rare for debug and indicates the failure remains unexplained despite thorough investigation.
-- **`not_applicable`** — the investigation could not proceed (e.g., inability to reproduce the failure, missing context, or out of scope). This is the "unable to diagnose" state.
-
-### Empty findings ≠ failure
-
-A crucial semantic: **empty findings does NOT mean `completed: false` or a failed debug session.** An investigation that proceeds thoroughly and produces zero root-cause candidates is a valid `completed: true` outcome; it means "I looked hard and found nothing." For debug, this often surfaces a `not_applicable` outcome instead (root cause is elsewhere), 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 root-cause hypotheses were identified across the investigation criteria.
-- **`not_applicable`** — the failure could not be diagnosed (reproduction failed, wrong area, or scope issue).
-
-The outcome `clean` (zero findings + success) is not legal for `mma-debug` because a debug session always either identifies a root cause or cannot proceed.
-
-@include _shared/error-handling.md