@mutmutco/opencode-mmi 2.48.0

package/skills/coop/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: coop
+description: Cross-repo, cross-PC multi-agent coordination — coordinator + joiners, GitHub issue handshake, #mmi-agents bus, Hub wake. Use instead of send_message or ad-hoc Slack MCP in unsupervised mode.
+---
+
+# /coop — agent coordination
+
+Opt-in **multi-agent alignment** when parallel agents (different worktrees, IDEs, PCs, or repos) must handshake before merging or continuing.
+
+## When to use
+
+- Two or more agents need to **align on a plan** before either proceeds
+- Cross-repo dependency (Agent A's API shape ↔ Agent B's consumer)
+- Cross-PC / cross-IDE coordination without human relay
+
+## When not to use
+
+- Serial merge train → use `wave land`
+- Session transfer → use `/handoff`
+- General Slack chat → not chatops; `#mmi-agents` + `COOP_*` protocol only
+
+## Quick start
+
+**Coordinator** (creates issue + posts `COOP_START`):
+
+```bash
+mmi-cli coop start --repo mutmutco/MyRepo --message-file tmp/coop-open.md
+```
+
+**Joiner**:
+
+```bash
+mmi-cli coop join <coopId> [--cloud]
+```
+
+**Handshake** (substance on the **GitHub issue**; Slack gets stubs):
+
+```bash
+mmi-cli coop say <coopId> --phase HANDSHAKE_OPEN --message-file tmp/proposal.md
+mmi-cli coop say <coopId> --phase ACK --message-file tmp/ack.md
+mmi-cli coop say <coopId> --phase SHOOK --message-file tmp/shook.md
+```
+
+**End** (coordinator, after user confirms):
+
+```bash
+mmi-cli coop end <coopId>
+```
+
+## Wake (primary path)
+
+Hub dispatches wake on every coop message targeting joiners:
+
+1. **SessionStart** — `coop pending` banner + detached `coop deliver`
+2. **Cursor cloud** — when joiner used `--cloud`
+3. **Slack Events** — inbound `#mmi-agents` coop messages re-trigger wake
+
+**Do not** rely on `coop watch` unless wake is broken — it is degraded poll only.
+
+## Rules
+
+- **Never** use Claude `send_message` or harness-specific live chat for org coordination
+- **Substance on GitHub issue**; keep Slack stubs short
+- Any **mutmutco org member** with a Hub session may join
+- Coordinator drives until `SHOOK` or explicit abort
+
+## Reference
+
+Architecture SSOT: `docs/Architecture/coop-agent-coordination.md`
+
+## Retro
+
+If this skill misfires, file one lesson on the Hub board:
+
+```powershell
+mmi-cli skill-lesson --skill coop --title "<what misfired>" --body "<what; evidence; proposed amendment>"
+```

package/skills/grind/SKILL.md

@@ -0,0 +1,469 @@
+---
+name: grind
+description: Drive one or more board items to a verified, PR-ready outcome autonomously — or, with --auto, all the way to merged into development. Verify with a fresh-eyes panel, iterate until clean, open a PR; with --auto, watch CI and merge when green. Use when the user says "grind on X", "take this to a PR", "work this issue until it's done", or invokes /grind [--explore] [--light|--standard|--deep|--ultra] [--auto].
+---
+
+# /grind — autonomous deliver-and-verify loop
+
+You drive an outcome from intake to a PR-ready state, then **stop** — or, with `--auto`, all the
+way to **merged**. By default you never merge; `--auto` is the sole exception (see its section).
+
+Two kinds of work, one loop:
+- **Convergent** (fix a known issue): iterate until zero blockers. Quality = correctness.
+- **Generative** (`--explore`): explore approaches, iterate toward a goal/metric. Quality =
+  fitness for the desired end result, not just absence of bugs. When auto-detection fires,
+  use the **generative fusion path** (fusion doctrine → fused markdown deliverable) for
+  research/explore-class outcomes — see shared doctrine and **## Generative fusion path**.
+
+**Shared doctrine:** Read `skills/_shared/doctrine.md` at session start and on resume. Fusion, parallelism, panel economics, flat fan-out, classifier-denied spawns, worktree hygiene, saga resume, enforcement matrix — single source; do not duplicate here.
+
+Flags:
+- `--explore` — brainstorm and judge approaches before building (use for open-ended,
+  "find a better/faster way" work). Without it, run the convergent loop.
+- **`--light` · `--standard` · `--deep` · `--ultra`** — force one of the four shared effort tiers
+  (same ladder `/build` uses; SSOT `_shared/doctrine.md` § Effort tiers + § Model economy). Without a
+  flag, grind self-selects from signals (default `standard`); the verify dial tracks the tier. Doctrine
+  also governs lightest-model-first, batch-to-cap, and the fusion-model `light` cap.
+- `--ultra` — the **top tier = YOLO full force** across the whole grind loop (not verify-only): ≥3
+  distinct models (cross-vendor when exposed), always multi-agent planning + judge, always tool-enabled
+  lenses on applicable hard/soft lenses, generative fusion when research/`--explore`, raised verify (8)
+  and CI-fix (5) caps under `--auto`, Ultra routing every round. Composable with `--explore`/`--auto`.
+  **Distinct from auto-ultra** (below) — escalation triggers alone do **not** unlock YOLO without `--ultra`.
+- `--auto` — fully autonomous, **zero gates**: classify + route silently, auto-frame (auto-deciding
+  whether to `--explore`), then after the PR watch CI, fix failures, and **merge into
+  `development`** when green. Accepts multiple issues and partitions them
+  (batch/serialize/parallel). See **## `--auto` — fully autonomous mode**.
+
+## Hard rules (never break these)
+- **Two gates.** Gate 1: after you state the direction + success criteria, ALWAYS stop and
+  wait for the user's go — never skip it. Gate 2: after you open the PR, wait for the merge
+  command. Run autonomously between the gates. Every gate follows **## Gates**: a
+  self-contained final message, answered through the host's question module. (`--auto` removes
+  both gates — it is the only mode that does; see its section.)
+- **Never merge — except under `--auto`.** In every other mode, do not run `mmi-cli pr merge`;
+  the human merges. `--auto` is the sole exception: it merges its own PR into `development`
+  (never `rc`/`main`, never a promotion), pre-authorized by the flag.
+- **Claim for the human.** `mmi-cli board claim <owner/repo#N> --for <login>` so the human
+  owns the work, not the bot — claiming several at once (Phase 00 sets, side-issue batches) →
+  pass every ref to ONE call (`board claim <ref> <ref> … --for <login>`; it dedupes and claims
+  in parallel), never loop one-by-one. Resolve `<login>` yourself — the session banner's
+  `current human:` line, else `mmi-cli whoami` — and echo who you're claiming for; ask only
+  when whoami returns `unknown`. Branch from the latest `origin/development` in a worktree
+  (`../mmi-worktrees/<branch>`). Never push `rc`/`main`.
+- **Verifier ≠ builder.** Verifier (and hard lenses) must use a **different model** from builder
+  whenever the host exposes two models. Under `--ultra`, the third model must also differ from
+  builder; synthesizer is never builder.
+- **Bounded.** Iteration cap = **5** verify→fix rounds (**8** when explicit `--ultra`).
+  Stuck = the same blocker survives 2 fix attempts. On cap OR stuck: STOP and ask the user — (a) open a WIP PR + report, (b) keep
+  grinding with a raised cap, or (c) stop. Never loop forever, never thrash silently. (Under
+  `--auto` you cannot ask — afk — so on cap OR stuck you **terminate and report**: open a
+  `[WIP]` PR, do not merge.)
+- **Leave nothing behind.** Every main *and* side issue *of this outcome* is resolved before you
+  stop — a second root cause, an unverified ask, a downstream break the fix exposes is part of the
+  grind, not a follow-up to punt. Fan out **parallel sub-agents** to resolve independent side issues
+  concurrently rather than serializing or skipping them. The only leftovers allowed: a
+  **truly-separate side-quest** (unrelated scope — file it out-of-scope, it was never this grind's
+  job) or the **cap/stuck hand-off** (a `[WIP]` PR — the user's, or `--auto`'s terminate-and-report).
+  "Honest scope: fixed one ask, punted the rest" is not an allowed exit.
+- **Not grindable ≠ punt.** A few issues have **no code/PR deliverable at all**: privileged
+  master-only ops (prod deploys, org-tier secret writes, box/runner admin), pure coordination
+  checklists, or work outside this run's authority. The floor is positive and hard: **if the
+  issue's deliverable is a PR to `development`, it IS grindable** — topic, difficulty, or
+  privileged-*adjacent* code never make in-scope work "not grindable" (calling it that would be
+  the punt the rule above forbids). For a genuinely non-grindable issue: classify it **before you
+  claim**, then do NOT claim it, do NOT execute its ops, do NOT open an empty/fake PR. Interactive
+  `/grind`: surface it up front (skip Phase 0a′/0a, don't propose criteria) and stop.
+  `--auto`: drop it (no claim, no branch, no PR) and surface it in the final report with the reason
+  — if it was the only issue, the run produces just that report.
+- **Data/config-fix outcomes (#1576).** Some grindable issues resolve via a **safe, authorized data or
+  config mutation** (e.g. a registry-META backfill via `mmi-cli project set`), not a code PR. When the
+  root-cause fix is data and a code change would be speculative (AGENTS §2 "least code"):
+  - **Do not** manufacture a synthetic code PR, and **do not** drop the issue as "not grindable".
+  - Confirm the mutation is **within standing authority** (`access role`) and **low-risk/reversible**;
+    under `--auto` the flag authorizes resolving the named issue its recommended way.
+  - Perform the fix, **verify empirically** (run the command whose output the acceptance pins — no diff
+    to panel), close the issue, and **file any durable-prevention enhancement** as a separate item.
+  - Terminal-done layer 1 is the live command output; layer 3 is the close, not a merge.
+- **Resumable.** After every phase: (1) silent one-line `mmi-cli saga note "<audit>"`; (2) `mmi-cli saga snapshot set --kind grind …` (or `--json-file`) — see **## Saga keep (resume snapshot)**. On resume, `mmi-cli saga snapshot show --kind grind` first; never reconstruct from collapsed chat history.
+- **Announce routing.** At phase transitions (after Phase 0a′ / model selection, before Gate 1 under
+  interactive, and at equivalent points under `--auto`), **announce explicitly** in user-visible text
+  **and** mirror the same facts in a silent `mmi-cli saga note`:
+  - **Ultra mode** when explicit `--ultra` YOLO is active (distinct from auto-ultra verify uplift).
+  - **Explore mode** when `--explore` or auto-framed explore is selected.
+  - **Routing tier** (Budget / Balanced / Paranoid / Ultra verify routing).
+  - **Models chosen** for panel roles: builder, verifier, third (when ultra), synthesizer, judge
+    (multi-plan) — slot names matching host-exposed models.
+  - **Reasoning effort** when explicit `--ultra` elevates it (model + level; see **## Reasoning effort
+    under explicit `--ultra`**).
+  Under `--auto`, emit these announcements in the run output/report even without gates — never route silently.
+- **Self-contained intake.** Given a task (issue ref, title, or fresh ask), `/grind` owns
+  grindability, task classification, explore-vs-convergent, ultra eligibility, and scope splitting.
+  Vague bodies are framed in Phase 0b — derive testable criteria, file child issues with `--parent`
+  when the scope must split, or `--explore` when the approach is open-ended.
+
+## Saga keep (resume snapshot)
+
+Grind-specific snapshot wiring — shared resume rules in `skills/_shared/doctrine.md`. Schema: `templates/saga-snapshot.md`. Use `--kind grind` for show/set. CLI maps snapshot fields → HEAD primitives (`next`, `anchor`, checklist) — no parallel store.
+
+## Gates — how every gate (and decision point) is presented
+Hosts collapse mid-turn text: anything you printed between tool calls may be invisible when
+the user reaches the gate. So:
+
+- **Self-contained final message.** Each gate message restates everything the user needs to
+  decide, in the message itself — never "as shown above", never relying on earlier mid-turn
+  output. Required content:
+  - **Gate 1:** grind **class** (bug/feature/research/task/security-critical), **routing**
+    (Budget/Balanced/Paranoid/Ultra), **effort tier** — name the chosen tier
+    (`light`/`standard`/`deep`/`ultra`), not an "Ultra: yes/no"; at `ultra` list the YOLO dimensions, and
+    note any auto-ultra verify uplift separately. Plus **planning** verdict when it ran (planner count, judge scores),
+    **tool-enabled lenses** when auto-gated (or always at `ultra`), **generative fusion** when active;
+    model slots + cost note at `ultra`; candidate approaches (with `--explore`: judge verdict/scores);
+    the chosen direction; and the full success criteria/target.
+  - **Gate 2:** the results summary — criteria/metric met, rounds run, issues filed/fixed,
+    anything unresolved.
+  - **Cap/stuck ask:** the blocker, what was tried, and the (a)/(b)/(c) options.
+- **Ask through the host's question module.** Collect the answer at EVERY gate and decision
+  point — Phase 0a classification confirm, ultra confirm (when auto-ultra), model overrides, Gate 1
+  go, cap/stuck ask, Gate 2 merge decision — with the host's structured-question UI
+  (AskUserQuestion in Claude Code; the equivalent on Codex / Cursor Composer; plain text only if
+  the host has none). Required content stays in the message body; the question module carries the
+  choice, not the context.
+
+## Phase 0a′ — Classify & route
+
+Runs immediately after the grindability check, **before** Phase 0a model questions. (`--auto`:
+apply silently for classification; still **announce** routing per **Hard rules — Announce routing**;
+`saga note "grind class=X routing=Y ultra=Z reason=…"`.)
+
+Read the issue **type label** (`bug` / `feature` / `task`), **priority**, **title/body**,
+**labels** (e.g. `security`), known **files touched**, and flags (`--explore`, `--ultra`, `--auto`).
+
+| Class | Signals | Builder bias | Default routing | Explore? |
+|-------|---------|--------------|-----------------|----------|
+| **Bug** | `bug` label, repro, regression | Fast/cheap OK | **Budget** → Balanced if security-adjacent | No |
+| **Feature** | `feature` label, new capability | Stronger | **Balanced** | Only if body open-ended |
+| **Research** | `--explore`, spike, metric goal | Brainstorm model | **Balanced**; ultra if high-stakes metric | Yes |
+| **Task / chore** | `task` label, refactor, deps, CI | Cheap | **Budget**; prose-only → reduced panel | No |
+| **Security-critical** | auth/crypto/payments/PII labels or code; agent-facing trusted corpus | Strong verifier | **Balanced** min; auto-ultra likely | Rare |
+
+### Ultra routing detail → `references/routing.md`
+
+The full **auto-ultra detection**, **explicit `--ultra` YOLO dimensions**, **cross-vendor model
+diversity**, and **reasoning-effort** rules live in `references/routing.md`. Load it when ultra is in
+play. Quick recap:
+
+- **auto-ultra** = verify-panel uplift only (≥3 models, Ultra routing, hard-lens double-pass) — fires on urgent+security, architectural scope, or after 2 failed rounds. **Not** whole-loop YOLO.
+- **Explicit `--ultra`** = whole-loop YOLO (≥3 cross-vendor models, always multi-plan, tool lenses, fusion, raised caps 8/5, elevated reasoning). List every dimension at Gate 1.
+- Verifier ≠ builder always; synthesizer never builder; document any vendor-diversity gap honestly.
+
+## Phase 0a — Choose models
+
+(`--auto`: skip questions — see **### Phase 0a — Models (auto)** under `--auto`.)
+
+First, **grindability** (Hard rule): if not grindable, stop before Phase 0a′.
+
+**Already-resolved guard (#1617):** before claiming, check the named issue's live state. If it is
+already **CLOSED/COMPLETED with its grind PR MERGED**, the outcome already shipped — no-op: do
+**not** re-claim, branch, or open a PR. Report "already done" and stop. Under `--auto` this is the
+safe landing for a stale re-invocation (e.g. a wakeup that fires after the work merged — see the
+**background-land** note in Phase 4); verify against `gh`/the board, never assume from chat.
+
+Then run **Phase 0a′**. Interactive flow:
+
+1. Present **classification summary** (class, routing, ultra yes/no + reason; cost note if ultra).
+2. **Confirm or override** builder, verifier, third model (ultra only), synthesizer — pre-filled
+   from class table + ultra rules.
+3. **Verify routing** — pre-fill Budget/Balanced/Paranoid/Ultra; Paranoid only when ultra or
+   explicit override.
+
+Offer models the **current host** exposes — do not hardcode one vendor:
+- Claude Code: Opus / Sonnet / Haiku / Fable.
+- Codex / Cursor Composer: that host's models.
+- If you cannot enumerate them, accept free-text model names.
+
+**Prioritize cross-vendor pairing** whenever the host exposes multiple vendors — verifier **≠**
+builder is the floor, mixed vendors is the target. **Hard lenses cannot drop below verifier tier.**
+See `templates/synthesize-panel.md`.
+
+**Lens tiers:**
+
+| Lens | Role |
+|------|------|
+| `requirements-match`, `tests-actually-test`, `error-handling` | **Soft** |
+| `security`, `correctness` | **Hard** (verifier tier minimum) |
+
+| Verify routing | Soft lenses | Hard lenses | Phase 2b | When |
+|----------------|-------------|-------------|----------|------|
+| **Budget** | budget tier | verifier, **≠ builder** | every round | Routine bugs, chores |
+| **Balanced** | mid/budget tier | verifier, **≠ builder** | every round | Features, default `--auto` |
+| **Paranoid** | verifier tier | **double-pass** | every round | Opt-in high-stakes (non-ultra) |
+| **Ultra** | verifier tier | **double-pass**, 2 models if possible | every round | `--ultra` or auto-ultra |
+
+**Paranoid / Ultra hard-lens double-pass:** run `security` and `correctness` twice — different
+temperature or two different models — before Phase 2b.
+
+Log each verify round: `mmi-cli saga note "verify round N: routing=X ultra=Y"`.
+
+## Phase 0b — Frame  [GATE 1]
+(`--auto`: no gate — auto-decide explore-vs-convergent, in `--explore` auto-pick the judge's
+winner, then proceed straight into Phase 1 without waiting. See **## `--auto`**.)
+
+### Multi-agent planning (auto-gated)
+
+When auto-detection fires (or **always** under explicit `--ultra`), run the **fusion doctrine**
+planning shape — **parallel planners + verifier-tier judge** — before Gate 1 / Phase 1:
+
+1. Spawn **N parallel planner sub-agents** (N=2–3; N=3 when scope is architectural, Research class,
+   wide `--explore`, or explicit `--ultra`).
+2. Each planner returns: approach summary, risks, proposed success criteria, estimated complexity.
+3. **Judge agent** (verifier-tier model, **≠** any planner/builder) scores against the goal rubric;
+   picks winner or synthesizes hybrid — synthesize-and-reconcile, not vote/debate.
+4. Winner + criteria written to issue body; North Star push; proceed to Gate 1 (interactive) or
+   Phase 1 (`--auto`). `mmi-cli saga note "multi-plan N=<n> winner=<summary>"`.
+
+**Skip multi-agent planning** for narrow bugs, low priority, or user "quick"/"small" — single
+planner + judge (or direct criteria framing) is enough.
+
+| Trigger | Multi-agent planning |
+|---------|---------------------|
+| `--explore` + wide/open-ended body | Yes (N=3) |
+| `--explore` + clear metric/goal | Yes (N=2) |
+| Class = **Research** | Yes (N=3) |
+| Architectural / cross-cutting (auto-ultra trigger #4) | Yes (N=3) |
+| Priority `urgent` + security-critical | Yes (N=2) |
+| Explicit **`--ultra`** | **Always** (N=3) |
+| Narrow bug / low priority / quick | No |
+
+Composable with **`--explore`** generative fusion (below) — fused deliverable may incorporate
+planner outputs when both paths are active.
+
+**Default (`/grind`):**
+1. Resolve the item — file it
+   (`mmi-cli issue create --type <bug|feature|task> --priority <…> --title "…" --body "…"`)
+   or claim the one the user named. Then `mmi-cli board claim <owner/repo#N> --for <login>`.
+   (`--priority` writes the board Priority **field**, never a `priority:*` label — #416.)
+   (Grindability was already settled in Phase 0a′ — a not-grindable issue never reaches here.)
+2. Convert the ask into **verifiable success criteria** — testable statements, not vibes.
+   **Vague or ambiguous body?** Read the full issue (body + comments), state the deliverable,
+   and write criteria the user can confirm at Gate 1. Umbrella scope → child issues (`--parent`),
+   one shippable unit per grind.
+   Write them into the issue body; push the criteria to North Star (`mmi-cli northstar push <slug>` —
+   the default push queues a background sync and prints "queued": that is success, not a failure;
+   `mmi-cli northstar status` checks it, `mmi-cli northstar sync` confirms durably).
+3. Present per **## Gates** (class, routing, ultra, criteria). **Wait for the user's go.**
+
+**With `--explore`:**
+1. When **generative fusion** auto-gates (see below), run the fusion panel instead of or after
+   single-builder brainstorm — fused markdown becomes the direction doc.
+2. Otherwise brainstorm **2-3 candidate approaches** (2 if the goal is clear, 3 if wide) on the
+   builder model — or use **multi-agent planning** when auto-gated.
+3. Score with the **verifier-model judge** (or fusion panel judge); pick or synthesize a direction.
+4. Define a success target — numeric metric if stated, else judged rubric. File/claim, North Star
+   push. Present per **## Gates**. **Wait for the user's go.**
+
+## Generative fusion path (auto-gated)
+
+Same **fusion doctrine** shape — parallel cross-vendor planners/agents on the explore problem,
+verifier-tier **judge** fuses into one markdown deliverable. For **research-class** and wide
+**`--explore`** grinds whose deliverable is a design conclusion, spike report, or approach doc
+(not only a code PR):
+
+1. Run **2–3 parallel planner-tier agents** (cross-vendor when the host allows) with **bounded
+   tools** (web search, repo read) on the same explore problem. **Judge** (verifier-tier, **≠**
+   any planner) synthesizes — not vote/debate.
+2. Judge output is a **fused markdown deliverable**: chosen approach, tradeoffs, criteria
+   refinement, spike findings.
+3. Land in issue body + `mmi-cli northstar push <slug>`.
+4. **Code-shipping explore:** fused doc feeds Phase 1; Phase 2 verify stays diff-pinned.
+5. **Research-only** (no code PR): fusion output is the primary artifact; stop after criteria met
+   + Gate 2 (`--auto` report).
+
+| Trigger | Generative fusion |
+|---------|-------------------|
+| `--explore` + non-purely-convergent deliverable | Candidate |
+| Class = **Research** | Yes |
+| Open-ended feature ("find best approach") | Yes |
+| Explicit **`--ultra`** + Research/`--explore` | Yes |
+| Bug / task / chore / quick | No |
+
+Auto-detection rules are also encoded in `cli/src/grind-policy.ts` (test fixtures lock inputs → path).
+
+## Phase 1 — Build
+- Cut a worktree from the latest `origin/development`. Implement to the criteria/approach on the
+  **builder model**. Write/adjust tests that lock the behavior (TDD where it fits).
+- Run **scoped repo checks** while building (shared doctrine § Verify tiers) — not the full gate mirror on every loop. Fix obvious breaks before spending verifier tokens.
+- (`--explore`) Spike a second approach if the first looks weak; let the judges choose.
+- **Checkpoint verification (build sub-loops).** Do not defer all judgment to end-of-round Phase 2.
+  At natural **increment checkpoints** — a module landed, a test suite green, a refactor slice done
+  — run a **light verify pass**: requirements slice for that increment, quick correctness read, or
+  a single lens if stakes are high. Cheap early signal; full panel still runs at Phase 2 before PR.
+- **Re-tackle when inadequate.** If a checkpoint or local check shows the approach is wrong, discard
+  the slice and rebuild — do not patch forward to green.
+- **Build gotchas → `references/build-notes.md`.** Load it before trusting a local green: edit-the-worktree
+  false-greens, clean-UTF-8/mojibake checks (and the Windows-console false-positive), Windows warm-build
+  flakes, the CI-gate mirror (incl. the `infra` `plugin-set` static guards for spine/surface diffs), and
+  the real-run requirement for IO/syscall-boundary changes.
+
+## Phase 2 — Judge (fresh eyes)
+
+**Mechanism:** spawn parallel lenses → each returns strict JSON → Phase 2b synthesizer produces
+`PanelReport` → triage uses **`PanelReport.blockers` only**. Not vote, not debate.
+
+`/grind` (`--auto` too) authorizes required panels. On Codex, use `multi_agent_v1` when
+available; report degraded fallback. Never replace an available panel with hand-written lens JSON.
+
+Spawn a **parallel panel** per lens, using **Phase 0a routing** for each lens's model tier. Under
+**Ultra**, assign soft lenses to the third model when available. Each verifier gets ONLY the diff +
+criteria/goal — never how you built it. **Pin every verifier to the change — a hard rule on EVERY
+round.** The orchestrator MUST hand each lens the *verbatim* diff — never a summarized/minified
+rendering. Form (a) inline verbatim `git diff` only when verifying from the **same checkout** that
+holds the change. **Grind default `isolation=worktree`:** form (b) only — write
+`git -C <worktree> diff …` to `tmp/grind-verify-<round>.patch` and pass that path; never rely on
+lens CWD.
+
+**Lens-prompt clauses → `references/verify.md`.** Every lens prompt MUST carry: the **verbatim-includes-test-files** rule, the **abstention** rule (`cannot-verify`, never a false "absent/missing" blocker), the **diff-shape** clause (a referenced-but-undefined symbol is pre-existing — never flag it), and the **worktree-isolation** clause (patch-only, deny repo FS, stale-checkout warning). The exact wording lives in `references/verify.md` — load it before spawning lenses.
+
+Under **Paranoid** or **Ultra**, run **hard lenses twice** before Phase 2b.
+Run **all five lenses, every round** (except prose/docs-only reduction below):
+1. **requirements-match** — does it meet the stated criteria?
+2. **correctness** — bugs, logic errors, broken edge cases.
+3. **error-handling** — failure modes, boundaries, resource cleanup.
+4. **security** — exploitable paths (attacker · input · sink · impact).
+5. **tests-actually-test** — do the tests exercise behavior, or pass vacuously?
+
+**Prose/docs-only changes** run a **reduced panel**: **requirements-match**, **correctness**
+(factual accuracy), **no-new-falsehood**. Error-handling and tests-actually-test are **N/A**.
+**Keep security** for agent-facing prose (SKILL/AGENTS/prompts, KB). Drop security only for inert
+human-only prose.
+
+(`--explore`) Add **goal judges**: metric hit? simpler path? right result?
+
+Each verifier returns strict JSON:
+`{ "verdict": "pass|fail|cannot-verify", "blockers": [{"title","file","line","why"}], "nits": [] }`.
+Do **not** triage raw lens blockers directly (Phase 2b first).
+
+**Tool-enabled lenses → `references/verify.md`.** Hard lenses should anchor to objective signals
+(failing test, typecheck error, cited source) and populate `blockers[].sources`. Bounded `webSearch`
+is the default on applicable lenses; `sandboxRepro` only when the body has repro commands. Under the
+grind default `isolation=worktree`, **repo FS tools stay forbidden even under ultra** — web search for
+external facts only. Full trigger table + domain-hygiene rules: `references/verify.md`.
+
+## Phase 2b — Synthesize (panel reconciliation)
+After Phase 2, spawn **one synthesizer sub-agent** on the **synthesizer model** (Phase 0a). Feed
+it ONLY: success criteria/goal, every lens JSON from this round (labeled by lens name), and a
+diff stat or excerpt — **never** builder reasoning or session history. Use the prompt in
+`templates/synthesize-panel.md`.
+
+The synthesizer returns a **`PanelReport`** — structured reconciliation of lens outputs:
+
+| Field | Meaning |
+|-------|---------|
+| `consensus` | Points most/all lenses agree on (higher confidence) |
+| `contradictions` | Topic + per-lens stances where they disagree |
+| `partial_coverage` | Only some lenses covered a point |
+| `unique_insights` | Something one lens raised |
+| `blind_spots` | Criteria imply it matters; no lens addressed it |
+| `blockers` | Deduped ship-stoppers — each has stable `id`, `title`, `file`, `line`, `why`, `sources` |
+| `nits` | Advisory, non-blocking |
+
+A verify round **fails if `PanelReport.blockers` is non-empty**. If synthesis errors or returns
+invalid JSON, **degrade gracefully**: union raw lens `blockers` (manual dedupe by file+line+title),
+`saga note` the degradation, and continue Phase 3 — synthesis is an uplift, not a hard dependency.
+Optional CLI path: `mmi-cli verify panel` plans lens jobs; pipe lens JSON to `mmi-cli verify synthesize`
+for deterministic blocker dedupe before the host synthesizer enriches consensus/contradictions.
+Real verifier lanes only. Empty or controller-authored all-pass stubs are invalid evidence and do
+not count toward clean rounds.
+
+**Synthesis handling → `references/verify.md`** for the detail on `blind_spots` (one micro-lens max),
+`contradictions` (escalate spec ambiguity per **## Gates**; `--auto` picks the criteria-satisfying
+reading), and **absence-claims** (drop "missing/absent" blockers contradicted by the pinned patch or
+green builder tests; re-run patch-only if lens logs show disk reads). Fusion is IDE-native multi-model
+only — no hosted provider.
+
+## Phase 3 — Triage & iterate
+
+**Each loop must deepen understanding** — of the problem and of the implementation — not merely
+retry the same shape with more tokens. Re-frame criteria and approach as evidence accumulates; a
+fix round should leave you knowing more than the last round.
+
+Triage from the **`PanelReport`** (Phase 2b), not raw lens JSON. Use stable blocker `id`s across
+rounds — the same root cause should keep the same `id` until resolved.
+
+- **Substantial or pre-existing** blocker → file a board issue
+  (`mmi-cli issue create --type bug …`), `board claim --for <login>`, then fix it. Reference the
+  `PanelReport` blocker `id` in the issue body when filing.
+- **Trivial** blocker → fix from a `tmp/` worklist (gitignored scratch), no board issue.
+- **Side issue *of this outcome*** → in scope: resolve before you stop. Fan out **parallel
+  sub-agents** for independent side issues.
+- **Truly-separate side-quest** → file out-of-scope and move on.
+- (`--explore`) A "works but a better path exists" verdict drives the next round; re-measure
+  against the target.
+- Re-run Phase 2 → 2b → 3. Repeat until **2 consecutive synthesis-stable clean rounds**:
+  - `PanelReport.blockers` empty on both rounds, **and**
+  - the blocker `id` set is identical across both (both empty counts as stable).
+  - **And** repo checks / CI green (terminal-done layer 1) — two clean rounds alone is insufficient.
+  This stability rule approximates **variance control** — one lucky clean round is not enough.
+  If round N is clean but round N+1 introduces a **new** `id`, reset the counter. OR cap/stuck
+  (then ask, per Hard rules). On round 3+, if still failing and not yet ultra, apply **auto-ultra
+  escalation** (Phase 0a′) before the next verify round.
+
+## Phase 4 — PR  [GATE 2]
+(`--auto`: no gate — open the PR, then run the **CI-merge loop** and merge into `development`
+yourself when green. See **## `--auto`**.)
+
+- **Base freshness (#1906):** before `pr create`, doctrine § worktree hygiene.
+- Open the PR: `mmi-cli pr create --base development --head <grind-branch> --title "…" --body "…"`
+  with `Closes #<issue>` for every issue resolved. **Pass `--head` explicitly** — `pr create`
+  defaults `--head` to the *current* branch, which is `development` when you run Phase 4 from the
+  main checkout (the Windows worktree-cleanup default), and `head == base == development` errors with
+  "cannot create a pull request". (`mmi-cli pr create` has no `--draft`; for a cap-hit hand-off, open
+  a regular PR with a `[WIP]` title and the unresolved blockers listed in the body.)
+- **Tick the parent's checklist (#1796).** If the resolved issue appears as a markdown task-list
+  item in a parent epic/tracking issue, flip it: `mmi-cli issue check <epic-ref> --item "<text>"`
+  — so the epic doesn't read 0% after its items shipped. (Native sub-issues auto-tick on close;
+  this is for body checklists not backed by sub-issues.)
+- A PR is done only when **every main + side issue of the outcome is resolved**. The sole
+  legitimate leftovers: a truly-separate side-quest (filed out-of-scope) or a cap/stuck `[WIP]`
+  hand-off — never an "honest residual" punt.
+- Run the **## Retro** check (silent when clean) before reporting.
+- Report per **## Gates**: criteria/metric met, rounds run, issues filed/fixed (including a
+  skill-lesson issue, if the retro filed one), and — only on a cap/stuck hand-off — what's
+  explicitly deferred and why.
+- Emit the **## End-of-grind summary** block before waiting for merge.
+- **Wait for the merge command.** Never run `mmi-cli pr merge` yourself.
+
+## Retro — one check after the PR opens
+
+See shared doctrine § Self-learning + retro. Grind-specific examples: gate message missing context; verifier lens missed a blocker; Windows worktree lock on cleanup; ambiguous phase instruction. File via `mmi-cli skill-lesson --skill grind` — at most one lesson per run.
+
+## End-of-grind summary
+
+At grind completion (PR opened + interactive stop, or `--auto` terminate/merge report), emit a **very
+brief** summary block — user-visible and mirrored in `mmi-cli saga note`:
+
+- **Tier + modes:** chosen tier (`light`/`standard`/`deep`/`ultra`); `--explore`, auto-ultra (verify uplift), `--auto` if applied.
+- **Models used:** builder / verifier / third / synthesizer / judge (host slot names).
+- **Reasoning level** when elevated under explicit `--ultra`.
+- **Fusion paths taken:** generative fusion, multi-agent planning — IDE-native only (not hosted).
+- **Verify rounds run** (and cap if hit).
+- **PR outcome:** opened, WIP, merged under `--auto`, CI state if relevant.
+
+## `--auto` — fully autonomous mode → `references/auto.md`
+
+When `--auto` is passed, **load `references/auto.md`** — it carries the full autonomous flow. Summary:
+
+- **Zero gates.** Both Gate 1 (direction) and Gate 2 (merge) are removed; never wait on the human.
+- **Authority.** `--auto` is the human's durable up-front authorization to merge *this run's* PR into
+  `development` only — never `rc`/`main`, never a promotion. Probe `mmi-cli access role <owner/repo>`
+  at start; abort if `train: false`. Branch protection under the human's `gh` token is the real guard.
+- **Bounded.** On cap/stuck you cannot ask (afk) → **terminate and report**: open a `[WIP]` PR, do not merge.
+- **Phase 00 (set):** partition multiple issues into **batch / parallel / serialize** (mode per group);
+  shared files or a shared generated artifact (e.g. `cli/dist/*`) → serialize/batch; ≤3 loops at once;
+  claim every grindable issue `--for <login>`.
+- **Phases 0a/0b (auto):** silent class/routing/model pick (2-model default; ultra mixes vendors);
+  auto-frame explore-vs-convergent; auto-pick the planning winner; straight into Phase 1.
+- **Phase 4 (CI-merge loop, replaces Gate 2):** `mmi-cli pr land <n> --json` (the recommended one call);
+  CI red → fix per Phase 3 (CI-fix cap 3, 5 under `--ultra`); permission-reject → leave green PR open.
+
+See `references/auto.md` for the per-step land mechanics, Windows worktree-cleanup rule, and the
+background-land wake-signal guidance.