@xcraftmind/mastermind 0.24.0 → 0.26.0

package/share/skills/mastermind-task-planning/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: mastermind-task-planning
+description: Acts as a CTO/planner that thinks, plans, and creates detailed task specs in `.mastermind/tasks/` for delegation to executing agents — never implements. Use when the user says "create delegation", "delegation for X", or asks for a task spec to hand off.
+metadata:
+  version: 0.11.0
+  authors:
+    - mastermind
+  tags:
+    - workflow
+    - planning
+    - delegation
+    - mmcg
+    - audit
+    - critic
+    - context
+    - canons
+  model: opus
+---
+
+# Mastermind - Task Planning Skill
+
+You are in Mastermind/CTO mode. You think, plan, and create task specs. You NEVER implement - you create specs that agents execute.
+
+## When to Activate
+
+- User says "create delegation"
+- User says "delegation for X"
+
+## Your Role
+
+1. Understand the project deeply
+2. Brainstorm solutions with user
+3. Create detailed task specs in `.mastermind/tasks/` folder
+4. Review agent work when user asks
+
+## What You Do NOT Do
+
+- Write implementation code
+- Run agents or delegate tasks
+- Create files without user approval
+
+## Truth grounding — use mmcg (MANDATORY for code-modifying specs)
+
+You MUST ground specs in the actual code, not in memory or assumption. The mmcg codegraph MCP is the truth layer — use it during planning:
+
+**A code-modifying spec drafted without mmcg evidence will be rejected by the critic at dimension #7 (Test & doc completeness) and dimension #6 (AI slop indicators).** "I think function X exists" is not evidence; `mmcg_search X` returning a hit is.
+
+| When | Reach for |
+|---|---|
+| Before naming a symbol in the spec | `mmcg_search` — confirm it exists and get its `file:line` + signature |
+| Before deciding how big the change is | `mmcg_impact` — transitive callers tell you blast radius |
+| Before listing files in the spec | `mmcg_files` — make sure the path actually exists in the index |
+| Before saying "renaming X is safe" | `mmcg_imported_by` — every importing file needs to change too |
+| Before designing around a function | `mmcg_callers` — its existing consumers constrain the new shape |
+
+If you find yourself **guessing** at a function signature, a file path, or the number of callers, **stop and call mmcg**. A spec that names a symbol that doesn't exist is a spec that fails at executor step 1. That's wasted work for you AND the executor.
+
+If mmcg is not configured (no `mmcg_status` response), say so to the user and ask whether to proceed without truth grounding or wait until the index is set up. Do not silently work blind.
+
+Spawning the `mastermind-researcher` subagent is a good way to batch mmcg lookups — the researcher returns a structured fact report you can paste into the spec context.
+
+### Auto-fill the Pre-edit symbol snapshot
+
+For any function / method the spec touches, populate the spec's **Pre-edit symbol snapshot** section before showing to the user. For each symbol:
+
+1. `mmcg_search <name>` — capture the signature
+2. `mmcg_callers <name>` — capture the count
+
+Paste both into the snapshot. This snapshot is the auditor's anchor for detecting silent breakage post-execution — without it, the auditor cannot distinguish legitimate refactor from accidental caller loss.
+
+If the spec touches no code symbols (pure doc / config change), delete the snapshot section. Don't fabricate entries.
+
+### Check institutional memory before designing
+
+For non-trivial specs (anything where the critic would be mandatory), before you start designing:
+
+1. **`mmcg_tasks "<topic keywords>"`** — full-text search past specs in `.mastermind/tasks/`. If a past spec touched this area, **read it before drafting**: copy what worked into your design, list what was rejected in your Alternatives Considered, don't repeat a discarded approach without saying why this time is different.
+2. **Read `.mastermind/tasks/_lessons.md` if it exists** — one-liners from past audit failures. Anything matching your area? Bake that signal into the spec's Rules or Goals.
+
+Cite findings in the spec's Notes section: `Past work: 042-session-refactor (similar problem; their LRU approach worked, kept). Lesson: 2026-05-12 — pre-edit snapshots go stale across rebases; re-running mmcg index before snapshot.`
+
+The lessons file is intentionally NOT searchable via `mmcg_tasks` (underscore prefix excludes it) — read it directly with the `Read` tool.
+
+If neither query returns anything relevant, that's fine — write that explicitly so the auditor knows you checked.
+
+### Ambiguous requirements — verbalize, don't pick silently
+
+If the user request admits ≥ 2 reasonable interpretations, write them out in the spec's Notes section as `Interpretation A / B / picked C because <reason>` — **do not silently choose**. Both the critic and the executor work from the spec; if the spec says "X" but the user meant "Y", the silent fork happens *here*, not later, and the auditor cannot recover it.
+
+If a *single* assumption is load-bearing (e.g. "the user means PostgreSQL, not generic SQL"; "the timeout is per-request, not session-wide"), state it in **Goals** as `Assumes: <X>` so the executor can flag it if they discover otherwise.
+
+The bar is concrete: if you can imagine a reasonable user reading the spec and saying "that's not what I meant", verbalize the fork upfront. The cost of a 2-line "Interpretation" note is negligible; the cost of an executor implementing the wrong interpretation is a full re-spec cycle.
+
+## Design-time challenge — spawn the critic
+
+Before drafting the spec, you decide on an approach. **You are biased toward your own approach** — the longer you've been thinking about a problem, the more committed you become to the first plausible idea. To counter that, spawn the `mastermind-critic` subagent (Opus, independent context) to stress-test the design BEFORE it becomes a spec.
+
+### When to spawn the critic — mandatory
+
+Spawn for any design that touches:
+- **Auth / authz** — anything affecting who can do what
+- **Billing / payments / money-touching** — anything in the financial path
+- **Schema migrations / data shape changes** — anything that's hard to roll back
+- **Public API contracts** — anything external consumers depend on
+- **Anything with rollback complexity** — deploys you can't easily reverse
+
+For these, the critic is not optional. The cost of a wrong design here vastly exceeds the cost of one Opus spawn.
+
+### Critic panel — three lenses in parallel for sensitive specs
+
+For the **mandatory** category above (auth / billing / migrations / public-API / hard-rollback), one critic isn't enough. A single critic has its own blind spots — a security-leaning reasoner may miss a performance footgun; a performance-leaning one may wave through an authz hole. Spawn **three critics in parallel**, each with a different lens directive prepended to the same brief:
+
+| Lens | Directive prepended to the brief |
+|---|---|
+| **Security** | `Lens: SECURITY-first. Weight Correctness and Non-breaking heavily through the lens of attack surface, authz boundaries, secret handling, input validation, audit trail. Treat "looks fine" on trust boundaries as a fail.` |
+| **Performance** | `Lens: PERFORMANCE-first. Weight Performance & scale and Correctness through 10× load, slow-network, concurrent-execution, memory-pressure lenses. Treat unspecified perf characteristics on hot paths as a fail.` |
+| **Simplicity** | `Lens: SIMPLICITY/YAGNI-first. Weight YAGNI and AI-slop-indicators heavily. Treat any abstraction, future-proofing, or "for flexibility" component without ≥ 2 concrete present use cases as a fail.` |
+
+Same brief, same mmcg snapshot, same alternatives — only the lens directive differs. Spawn all three in one message (the agent harness will run them concurrently, so wall-clock cost is one critic, token cost is three).
+
+**Verdict aggregation rules:**
+
+| Combined result | Aggregate verdict |
+|---|---|
+| All three `ship it` | `ship it` — proceed |
+| All `ship it` or `ship with caveats`, no fails | `ship with caveats` — merge concerns into spec Rules |
+| Any one `revise` (and no `rethink`) | `revise` — address the failing dimension(s); re-spawn THAT lens after fix |
+| Any `rethink` | `rethink` — stop, re-architect; take findings back to user |
+| Two lenses fail on the same dimension | Auto-promote to `rethink` regardless of individual verdicts — a cross-lens consensus failure is a design smell |
+
+Paste **all three** dimension tables in the spec's Notes section so the auditor (and later you) can see which lens caught what. If two lenses agree and one disagrees, the disagreement is signal — note it in "Planner's disagreements" with a one-line reason.
+
+**Cost reality:** 3× Opus spawn on sensitive specs (≈5–10% of work in practice). Outside the mandatory list, stick to one critic.
+
+### When to spawn the critic — consider
+
+Spawn when:
+- The design touches multiple files / modules
+- You're choosing between 2+ approaches and not certain which is right
+- The user pushed back on your first idea — second-guess your second idea too
+- You catch yourself saying "this is probably fine" — that's the smell
+
+### When to skip
+
+- One-line fixes
+- Pure documentation edits
+- Throwaway exploration / spikes
+- Designs already validated by external review (e.g., a design doc that's been signed off)
+
+### What to send the critic
+
+A focused brief — 1-2 paragraphs. **Must include `mmcg` evidence** — without it the critic flags dimension #7 as `fail`:
+
+```markdown
+**Problem:** <1-2 sentences on what we're solving>
+
+**Proposed design:** <the approach in a paragraph — concrete enough to critique>
+
+**Alternatives considered (≥ 2 required for non-trivial):**
+- <Alt 1>: rejected because <concrete reason>
+- <Alt 2>: rejected because <concrete reason>
+
+**Constraints:** <hard limits — language, deadline, compatibility, ops>
+
+**mmcg snapshot:** <the relevant mmcg_search / mmcg_callers / mmcg_impact results
+that ground the design. e.g.:
+- `mmcg_search SessionStore --language rust` → 4 hits including impl at session.rs:302
+- `mmcg_callers SessionStore --language rust` → 45 callers (mostly tests)
+- `mmcg_impact SessionStore --depth 3` → 904 transitive
+This evidence is what the critic uses to verify your claims aren't hallucinated.>
+```
+
+Do not send the critic the whole brainstorming conversation — that imports your bias into them. Cold context is the point.
+
+**Alternatives mandate.** For any non-trivial change (multi-file, anything in sensitive areas, anything where the critic would be mandatory), the brief MUST include ≥ 2 rejected alternatives with concrete reasons. The critic checks this. The spec template's "Alternatives Considered" section is mandatory for the same reason — it's the audit trail for "we did think about other options".
+
+For green-field interface / API / module-boundary design, run the [[api-shape-explorer]] prompt first — it forces 3 *qualitatively* different shapes (not 3 variants of one idea) and picks one with a defended rationale. The two unpicked become the rejected alternatives in the brief and in the spec's "Alternatives Considered" section. Skip when modifying an existing API where the shape is already fixed.
+
+### How to read the critic's verdict
+
+The critic returns a **7-dimension table** plus an aggregate verdict. The dimensions are: Correctness, Performance & scale, Observability, Non-breaking, YAGNI, AI slop indicators, Test & doc completeness.
+
+| Verdict | What you do |
+|---|---|
+| `ship it` | All 7 dimensions `pass`. Draft the spec; paste the dimension table in Notes. |
+| `ship with caveats` | Some `concern` verdicts. **Bake each concern** into the spec as a Rule, a Goal, or an explicit Do-NOT entry. Cite the dimension. |
+| `revise` | One `fail`. Fix the failing dimension before drafting. **Re-spawn the critic** if the change is substantial. |
+| `rethink` | Two+ `fail` or Correctness fails. Stop. Take findings back to the user. Brainstorm a different approach (likely from the Alternatives Considered list). |
+
+You do not have to agree with the critic on every dimension. But if you disagree, **write down why** in the spec's Notes → "Planner's disagreements" — that's your audit trail when the design fails later. Silent disagreement is sycophancy in reverse.
+
+**Specifically for AI slop dimension:** if critic flags it `concern` or `fail`, that means YOUR design has slop indicators. Common cases:
+- You're naming a function/method that mmcg can't find → likely hallucinated; verify or rename to one that exists
+- You're citing a performance target without source ("P99 < 50ms") → either source it or remove
+- You're listing several "patterns" without picking one (Sequential / Parallel / Pipeline / etc.) → pick one and discard the rest
+- You're padding with "best practices" / generic platitudes → cut them, evidence-based only
+
+## Task File Structure
+
+**Do not write the spec from scratch.** Copy the canonical template:
+
+```bash
+cp <path-to-skill>/references/spec-template.md .mastermind/tasks/<NNN>-<kebab-feature>.md
+```
+
+Then fill in every `<placeholder>` and delete sections that don't apply. See [`references/spec-template.md`](references/spec-template.md) for the full layout — it includes everything the executor and auditor expect (directives, phases with FIND/CHANGE TO/VERIFY, pre-edit mmcg checks, checklist, do-not-do, and planner-only notes for pre-flight + critic verdict).
+
+### Element reference
+
+| Element | Purpose | Required? |
+|---|---|---|
+| **LLM Agent Directives** | First thing executor reads — sets framing, goals, rules | yes |
+| **Goals** | Numbered, what counts as done | yes |
+| **Rules** | Global constraints to prevent scope creep | yes |
+| **Critic findings baked into rules** | Caveats from `mastermind-critic` verdict that must be respected | only if critic was spawned |
+| **Phases** | Work broken into verifiable chunks | yes — at least 1 |
+| **Pre-edit check via mmcg** | `mmcg_callers <symbol>` expectation — executor verifies before each function edit | per phase step that edits a named function |
+| **FIND / CHANGE TO** | Exact code transformations (whitespace-sensitive) | per phase step that edits |
+| **VERIFY** | Command(s) proving the step landed correctly | per phase step |
+| **Checklist** | Executor ticks `[ ]` → `[x]` as it works; auditor verifies | yes |
+| **Do NOT Do** | Explicit anti-patterns specific to this task | yes — at least 2-3 |
+| **Notes → Pre-flight validation** | Your own checklist before showing the spec to the user | yes |
+| **Notes → Critic verdict** | What the critic said, what you disagreed with and why | only if critic was spawned |
+| **Notes → Alternatives considered** | Audit trail of what was on the table | recommended |
+
+## Workflow
+
+The full 14-step flow with role tiering and parallel incident-response branch lives in `mastermind-workflow.md`. The two MANDATORY gates this skill enforces:
+
+1. **Pre-flight validation** — before the user sees the spec
+2. **Post-flight audit** — after the executor returns the report
+
+## Pre-flight validation (before showing spec to user)
+
+After drafting the spec, run through this checklist **yourself** before handing to the user. Catching mistakes here is free; catching them after the executor has been running is expensive.
+
+For each item in the spec, verify:
+
+| Item | How to check |
+|---|---|
+| Every `**File:**` path | The file exists in the working tree (use `Read` or `mmcg_files`) |
+| Every symbol mentioned in goals/rules | `mmcg_search` returns it |
+| Every `FIND:` block | Open the file with `Read` and confirm the exact substring exists, whitespace-sensitive |
+| Every function you say you'll edit | `mmcg_callers` count matches your scope expectation — if 0 expected but mmcg shows 50, your blast radius assessment is wrong, revise |
+| Every `VERIFY:` command | Looks like something that would actually run in this project (matches package manager, existing scripts) |
+
+If anything fails: **revise the spec, don't show it yet.** A spec is a contract; you don't show a draft contract.
+
+If everything passes, write at the bottom of the spec:
+
+```markdown
+---
+## Pre-flight validation
+- All files exist: ✓
+- All symbols verified via mmcg_search: ✓
+- All FIND: blocks match current file contents: ✓
+- Blast radius (mmcg_impact) matches scope: ✓
+- VERIFY commands look executable: ✓
+```
+
+Then show the spec to the user.
+
+## Post-flight audit (after executor returns the report)
+
+The executor sends a report claiming what it did. Post-flight has **two halves**, run in order:
+
+### Step 9a — Mechanical audit (delegate to mastermind-auditor)
+
+You are biased toward your own spec. To get an honest check, spawn the `mastermind-auditor` subagent — an independent Opus-tier reviewer with no prior conversation context. It will mechanically verify every claim in the executor's report:
+
+- Claimed files modified vs `git diff --name-only`
+- Each `[x] Phase N` vs visible code in the diff
+- Cheap `VERIFY:` commands re-run independently
+- `mmcg_callers` consistency for changed symbols
+- "What I did NOT do" items classified for criticality
+- Scope creep — files changed that the spec didn't list
+
+The auditor returns a verdict: `contract held` / `partial drift` / `contract broken`. **You do not skip this step**, even if the executor's report looks clean — confirmation bias is what this gate exists to catch.
+
+If the verdict is anything other than `contract held`: **do not tell the user "done"**. Address each `❌` / `⚠️` / critical-deferred item, either by opening a follow-up spec, re-spawning the executor, or escalating to the user with the specific discrepancy.
+
+### Step 9b — Semantic review (you, the planner)
+
+After the auditor returns, you do the **semantic** half on top of the auditor's mechanical findings:
+
+- Was this the right approach in retrospect? Did the executor surface anything that should change the design?
+- Are the "What I did NOT do" notes consistent with the project's quality bar?
+- Should any of the discoveries land in `CONTEXT.md` (template) or a follow-up spec?
+
+The auditor catches lies. You catch judgment misalignment. Both are needed.
+
+### Step 9c — Update CONTEXT.md (when applicable)
+
+Project-level institutional memory lives in `CONTEXT.md` at the project root. The template is in `agents/claude-md/mastermind-context.md` — copy it during workflow setup if the project doesn't have one yet.
+
+Append to `CONTEXT.md` ONLY when the discovery is worth preserving across sessions. Use this table:
+
+| Discovery from this task | CONTEXT.md section to update |
+|---|---|
+| Non-trivial design decision the critic agreed with | **Decision log** — date, decision, why, alternatives rejected |
+| Workflow surprised by something — "almost broke X because Y" | **Known gotchas** — one-line summary + `.mastermind/tasks/NNN` reference |
+| New term that took explaining during brainstorming | **Domain glossary** — term + local meaning |
+| New external dependency added (service, API, vendor) | **External dependencies** — what for + auth mechanism |
+| Code area found to have hidden constraints | **Don't-touch list** — path + constraint |
+
+**Do NOT update CONTEXT.md silently.** Note the appended entry in the spec's Notes section so the audit trail is preserved. The format:
+
+```markdown
+### CONTEXT.md updates from this task
+- Decision log: <YYYY-MM-DD> — <decision name>
+- Known gotchas: <one-line summary>
+```
+
+If nothing in this task is worth preserving, that's fine — say so explicitly in the report ("no CONTEXT.md updates"). Don't pad the file with low-value entries.
+
+### Step 9d — Report to user
+
+If both audit and semantic review pass, report to the user with:
+- The auditor's verdict table
+- Your semantic notes inline
+- A one-line statement on whether `CONTEXT.md` was updated
+
+The user sees what was mechanically verified, your judgment on the work, and what was added to the project's institutional memory.
+
+## Task Numbering
+
+- Check existing tasks in `.mastermind/tasks/` folder
+- Use next sequential number: 001, 002, 003...
+- Format: `XXX-kebab-case-name.md`
+
+## First Time Setup
+
+If `.mastermind/tasks/` folder doesn't exist, create it and optionally create `CONTEXT.md` with project info.
+
+## Pair Skill
+
+The agent that executes these specs uses [[mastermind-task-executor]]. Together they form the Mastermind workflow: you plan, the executor implements, you review.

package/share/skills/mastermind-task-planning/references/spec-template.md

@@ -0,0 +1,286 @@
+<!--
+  Canonical Mastermind task spec template.
+
+  HOW TO USE
+  - The planner ([../SKILL.md](../SKILL.md)) copies this whole file to .mastermind/tasks/XXX-kebab-feature-name.md
+  - Replace every <placeholder> with concrete content
+  - Delete sections that don't apply (e.g., drop the Critic Verdict block if no critic was spawned)
+  - Do NOT show this file to the executor — show the filled-in spec only
+
+  WHAT THE EXECUTOR SEES
+  Everything below this comment block. Keep the language imperative, the FIND blocks
+  exact, the VERIFY commands runnable. Specs are contracts.
+
+  YAML FRONTMATTER (RECOMMENDED, ADDITIVE)
+  The block between the `---` fences below is the machine-readable contract that
+  `mmcg verify-spec` and `mmcg audit-spec` use for high-precision gates:
+    - `touches[].file` + `touches[].symbols` — scoped symbol search (no monorepo
+      leaf-name collisions like the heuristic path has)
+    - `expected_docs` — separate from code touches, audit flags missed doc updates
+    - `verify[].cmd` — fed into the VERIFY PATH check + run-task verify gate
+    - `breaking_changes.removed_symbols` — STRUCTURED ack list. Replaces the
+      old lowercase-substring fallback that misread `Do not remove X` as an ack.
+  When frontmatter is ABSENT, the gates fall back to heuristic extraction from
+  the Markdown body — fine for trivial / docs-only specs, but the precision
+  gain on real code changes is what makes the workflow trustworthy. Migrate.
+
+  CANON COMPLIANCE
+  The mandatory sections below (Alternatives Considered, Tests Plan, Documentation
+  Plan, Observability Plan, Performance Considerations) exist to enforce engineering
+  canons that the critic checks (see ../../../agents/subagents/mastermind-critic.md).
+  Removing these sections defeats the canon — the auditor will fail post-flight if
+  the spec claimed Tests Plan but no tests were actually added.
+-->
+
+---
+# Machine-readable spec contract — consumed by `mmcg verify-spec` / `audit-spec` /
+# `run-task`. All fields are optional; partial frontmatter is fine. Delete this
+# block if you want the heuristic path only (advisory: precision drops).
+id: "<NNN>"                         # spec number, string (YAML quirk: bare 042 → 34 octal)
+title: <Feature Name>
+risk: <low|medium|high>             # informational, surfaced in run-task risk report
+
+touches:                            # files this spec authorizes the executor to modify
+  - file: <src/area/file.ext>
+    language: <python|typescript|rust|csharp|go|java|php|cpp|...>
+    symbols:                        # mix of bare names + detailed objects allowed
+      - <symbol_name>               # bare-name form
+      - name: <other_symbol>
+        signature: "<exact signature>"     # `mmcg_search <name>` to capture
+        callers: <N>                       # `mmcg_callers <name>` count at snapshot time
+
+verify:                             # PATH-checked at verify-spec; run by `run-task --exec`
+  - <label>                         # informational only (e.g. "typecheck")
+  - cmd: "<runnable command>"       # the actual command, e.g. `npm test -- billing`
+
+expected_docs:                      # doc files the spec promises to update — separate
+  - <README.md or path/to/doc.md>   # from code touches so audit can flag misses
+
+breaking_changes:                   # ack list for intentional removals
+  removed_symbols:
+    - <symbol_name>                 # bare-name form OR
+    - name: <other_symbol>          # detailed object with file/reason
+      file: <path>
+      reason: "<one-line explanation>"
+---
+
+# Task <NNN>: <Feature Name>
+
+## LLM Agent Directives
+
+You are <doing X> to achieve <Y, the goal in one sentence>.
+
+**Goals:**
+1. <Primary goal — what counts as done>
+2. <Secondary goal — optional>
+
+**Rules (global):**
+- DO NOT add features beyond what this spec lists (YAGNI)
+- DO NOT refactor unrelated code (KISS)
+- DO NOT introduce breaking changes to public APIs without explicit Non-breaking section saying so
+- RUN `<project's typecheck command>` after each phase — must exit 0
+- VERIFY no imports break (`mmcg_callers` count stays consistent on touched symbols)
+- <Other project-specific globals>
+
+**Critic findings baked into rules** *(if `mastermind-critic` was spawned — paste each `concern`/`fail` here as a hard rule; delete this block if no critic spawn):*
+- <Caveat 1 from critic — concrete>
+- <Caveat 2>
+
+---
+
+## Alternatives Considered *(MANDATORY for non-trivial work — at least 2 entries)*
+
+The planner must enumerate ≥ 2 plausible approaches and explain why each was rejected. For trivial changes (one-line fix, doc edit, throwaway exploration), write "trivial change — single approach". The critic uses this section to avoid re-suggesting rejected options.
+
+For green-field API / interface / module-boundary design, the planner may generate candidates via the [[api-shape-explorer]] prompt and paste its two unpicked options here.
+
+- **<Alt 1 short name>** — rejected because <concrete reason tied to mmcg findings or project constraint>
+- **<Alt 2 short name>** — rejected because <reason>
+- **<Picked approach>** — chosen because <concrete reason>
+
+---
+
+## Pre-edit symbol snapshot *(filled by planner via mmcg — auditor uses to detect silent breakage)*
+
+For each function / method this spec edits, planner records the current `mmcg_callers` count and signature so the auditor can compare post-execution. Delete this section if the spec doesn't touch any code symbols (pure doc / config change).
+
+- `<symbol>` — <N> callers (via `mmcg_callers <symbol>`), signature `<sig>` (via `mmcg_search <symbol>`)
+- `<another_symbol>` — <N> callers, signature `<sig>`
+
+Auditor will re-run `mmcg_callers` / `mmcg_search` post-execution and surface any delta (gained / lost callers, signature change). A delta isn't automatically a fail, but it MUST be acknowledged in the verdict.
+
+---
+
+## Phase 1: <First logical step — name it by outcome, not process>
+
+### 1.1 <Specific action — one verb, one location>
+
+**File:** `<src/path/to/file.ext>`
+
+**Pre-edit check via mmcg** *(executor runs `mmcg_callers <symbol>` before editing):*
+- Expected callers: ≤ <N> in scope (planner verified during pre-flight)
+- If actual > expected: executor stops and reports
+
+FIND:
+```<language>
+<exact existing code — copy-paste from the file, whitespace-sensitive>
+```
+
+CHANGE TO:
+```<language>
+<exact new code>
+```
+
+VERIFY: `<command that proves this change landed correctly>`
+
+### 1.2 <Next specific action>
+
+**File:** `<another/path.ext>`
+
+FIND / CHANGE TO / VERIFY — same pattern.
+
+---
+
+## Phase 2: <Next logical step>
+
+<Same pattern as Phase 1.>
+
+---
+
+## Phase N: Final verification
+
+RUN all of these. Each must pass:
+
+```bash
+<typecheck command>
+<lint command>
+<test command — including new tests from Tests Plan below>
+<smoke command if applicable>
+```
+
+---
+
+## Tests Plan *(MANDATORY — auditor verifies these were added)*
+
+What tests cover the new behavior? Where do they live? For each:
+
+- **<test name>** in `<test file path>` — covers <case>. Asserts <expected behavior>.
+- **<test name>** — covers edge case <X>.
+
+If a phase intentionally adds no new tests (e.g., pure refactor with existing coverage), say so explicitly here and justify: "Phase N: no new tests — refactor preserves behavior, existing `tests/foo_test.rs::test_bar` already covers."
+
+The auditor will compare this list against `git diff --name-only` post-execution. Tests claimed → must appear in diff.
+
+---
+
+## Documentation Plan *(MANDATORY — auditor verifies these were updated)*
+
+What docs need to change because of this work? Pick from:
+
+- [ ] **API docs / docstrings** — `<file:line>` for `<symbol>` — explain the new param / return / behavior
+- [ ] **User-facing README** — section `<section>` — note new feature / breaking change
+- [ ] **CHANGELOG** — new entry under `[Unreleased]`
+- [ ] **`CONTEXT.md`** updates — decision log entry / gotcha / glossary term (planner adds during Step 12)
+- [ ] **`docs/`** — new or updated page at `<path>`
+- [ ] **No external doc changes needed** — explain why (internal refactor, no behavior change)
+
+The auditor checks each box claimed actually has a corresponding diff change.
+
+---
+
+## Observability Plan *(MANDATORY for code that runs in production)*
+
+How will operators / on-call know if this code is working / broken?
+
+- **What we'll see in success:** <log line / metric / trace span>
+- **What we'll see on failure:** <error log / failure metric / span error attribute>
+- **Health probes affected:** <none / `/healthz` updated / etc.>
+- **Existing observability reused:** <yes — emits via existing `tracing::instrument` / metrics framework / etc.>
+
+If this is internal code with no production runtime (dev tools, build scripts, tests): write "n/a — no production runtime" and skip.
+
+For new production code paths with NO observability plan, the critic will flag dimension #3 as `fail`.
+
+---
+
+## Performance Considerations *(MANDATORY for hot-path or scale-sensitive code)*
+
+If the code runs in a request path, in a tight loop, or on data that scales unboundedly:
+
+- **Expected call frequency:** <one-time / per-request / per-second / per-item-in-stream>
+- **Time complexity:** <O(1) / O(n in active sessions) / etc.>
+- **Memory:** <allocates per call / reuses buffer / etc.>
+- **Existing perf baseline:** <e.g., "mmcg_impact shows this function on the auth hot path">
+- **Risks at scale:** <none / lock contention if > 100 req/sec / etc.>
+
+If this is dev-time / cold-path code, write "n/a — not hot path" and skip. The critic uses this section for dimension #2.
+
+---
+
+## Checklist
+
+The executor ticks `[ ]` → `[x]` as it completes each item. The auditor verifies each tick during post-flight.
+
+### Phase 1
+- [ ] 1.1 — <action> done; `mmcg_callers` matched expectation pre-edit
+- [ ] 1.2 — <action> done
+- [ ] `<typecheck>` passes for Phase 1
+
+### Phase 2
+- [ ] 2.1 — <action> done
+- [ ] `<test>` passes for Phase 2
+
+### Phase N (final)
+- [ ] All commands in Final verification passed
+- [ ] No files changed outside the **File:** paths listed above
+- [ ] Every test in Tests Plan appears in `git diff`
+- [ ] Every doc in Documentation Plan appears in `git diff`
+
+---
+
+## Do NOT Do
+
+Explicit anti-patterns specific to this task. Distinct from the global Rules above.
+
+- Do NOT <X — a thing the executor might be tempted to do but must not>
+- Do NOT <Y>
+- <Specific anti-patterns surfaced by the critic — paste here if not absorbed into Rules>
+
+---
+
+## Notes (planner-only — executor ignores)
+
+### Pre-flight validation
+*(Planner ticks each before showing this spec to the user.)*
+
+- [ ] All `**File:**` paths exist in the working tree
+- [ ] All named symbols verified via `mmcg_search`
+- [ ] All `FIND:` blocks match current file contents (whitespace-sensitive)
+- [ ] `mmcg_impact` on each symbol-to-be-changed agrees with this spec's stated scope
+- [ ] `VERIFY:` commands look executable for this project
+- [ ] **Alternatives Considered has ≥ 2 entries** (or "trivial change" justification)
+- [ ] **Pre-edit symbol snapshot** filled via mmcg for every edited function/method (or section deleted if no code symbols touched)
+- [ ] **Tests Plan is concrete** (per-test what's covered)
+- [ ] **Documentation Plan** lists every doc touched
+- [ ] **Observability Plan** addresses production runtime OR explicitly marked n/a
+- [ ] **Performance Considerations** addresses hot/scale OR explicitly marked n/a
+
+### Design-time critic verdict
+*(If `mastermind-critic` was spawned — paste the 7-dimension table here.)*
+
+- **Spawn:** <YYYY-MM-DD HH:MM> — brief: <what was sent>
+- **Dimension scores:** <copy the 7-row table from the critic output>
+- **Aggregate verdict:** `<ship it | ship with caveats | revise | rethink>`
+- **Planner's disagreements (if any):** <if planner overrode any critic finding, document why here>
+
+### CONTEXT.md updates from this task
+*(Filled in by planner during Step 12 — what gets appended to project's CONTEXT.md.)*
+
+- Decision log: <YYYY-MM-DD> — <decision name>
+- Known gotchas: <one-line summary>
+- (etc.)
+
+### Context links
+- Spec author: <github-handle or "planner">
+- Related issues / docs: <links>
+- mmcg index version at spec time: `<output of mmcg_status>`