@xcraftmind/mastermind 0.28.0 → 0.28.2

package/share/skills/mastermind-prompt-refiner/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: mastermind-prompt-refiner
-description: Refines a user's rough, vague, or under-specified prompt into a clean, executable one before handing it off to another agent or skill. Use as a front-stage filter in delegation workflows, or when the user says "improve this prompt", "rewrite this prompt for an agent", "make this clearer".
+description: Intake gate that normalizes raw client prompts before the planner sees them. Use as the first stage in any Mastermind workflow when the user's request is rough, vague, client-provided, or bundles multiple intents. Also invoked when the user says "improve this prompt", "rewrite this for an agent", "make this clearer".
 metadata:
-  version: 0.1.0
+  version: 0.2.0
   authors:
     - mastermind
   tags:
@@ -11,9 +11,9 @@ metadata:
   model: sonnet
 ---
 
-# Prompt Refiner
+# Prompt Refiner — Intake Gate
 
-Sits between the user and a downstream agent (planner, executor, reviewer, …) and rewrites the raw user input into a refined prompt. The downstream agent sees the refined version, not the user's brain dump.
+Sits between the user and the planner and normalizes raw user input into clean planner input. The planner sees the refined version, not the user's brain dump.
 
 This is a **one-pass** skill: input goes in, refined prompt comes out. Not a tutorial on prompt engineering, not a general-purpose advisor. If the user wants to learn prompt engineering, point them at [`references/techniques.md`](references/techniques.md) instead.
 
@@ -28,7 +28,7 @@ This is a **one-pass** skill: input goes in, refined prompt comes out. Not a tut
 
 ### 1. Read the input. Identify three things.
 - **Goal** — what does the user actually want to accomplish?
-- **Next consumer** — who reads the refined prompt next? (planner / executor / reviewer / unspecified)
+- **Next consumer** — who reads the refined prompt next? Default: `planner`. Use `executor` only if the spawner explicitly states a valid spec already exists — routing raw user intent to an executor bypasses the planning gate.
 - **Gaps** — what's vague, missing, or contradictory?
 
 ### 2. Decide: refine inline, or ask first?
@@ -55,7 +55,7 @@ For technique-level decisions (when to add CoT, few-shot, XML structure, role fr
 
 ### 4. Hand off.
 
-Output in this exact shape. The spawner copies the `## Refined prompt` block into the next agent's input:
+Output in this exact shape. The spawner copies the `## Refined prompt` block into the planner's input:
 
 ```markdown
 ## Refined prompt
@@ -71,9 +71,25 @@ Output in this exact shape. The spawner copies the `## Refined prompt` block int
 
 - <NEEDS: gap 1>
 - <NEEDS: gap 2>
+
+## Intake metadata
+
+<!-- mastermind:intake-begin -->
+```yaml
+action: refined
+workflow_mode: strict
+risk: medium
+needs_research: false
+needs_critic: false
 ```
+<!-- mastermind:intake-end -->
+```
+
+`action` values: `refined` (prompt was rewritten) | `passthrough` (already tight, no changes) | `ask` (goal too ambiguous, questions emitted instead).
+`workflow_mode`: `strict` (auth, billing, schema, public API, rollback complexity) | `lite` (bounded, low-risk, single-file) | `unknown` (not enough context).
+`risk`: `high` (data loss, auth, production schema) | `medium` (multi-file, external API) | `low` (local, reversible, no external deps).
 
-Omit the "Gaps" section entirely if there are none.
+Omit the "Gaps" section entirely if there are none. If asking clarifying questions, emit the questions then the intake block with `action: ask` — no refined prompt section.
 
 ## What you do NOT do
 
@@ -83,6 +99,7 @@ Omit the "Gaps" section entirely if there are none.
 - Stack multiple refinement passes in one call
 - Execute the prompt — that's the next agent's job
 - Critique the user's writing style — only fix what affects machine consumption
+- Route to executor when no spec exists — that bypasses the planning gate
 
 ## Output examples
 
@@ -116,6 +133,18 @@ Feedback message:
 ## Gaps the user still needs to fill
 
 - <NEEDS: actual feedback message to analyze>
+
+## Intake metadata
+
+<!-- mastermind:intake-begin -->
+```yaml
+action: refined
+workflow_mode: lite
+risk: low
+needs_research: false
+needs_critic: false
+```
+<!-- mastermind:intake-end -->
 ```
 
 ### Already-tight prompt → passthrough
@@ -131,6 +160,18 @@ Feedback message:
 ## What I changed and why
 
 No changes needed — prompt has clear role, format, constraints, and success criterion.
+
+## Intake metadata
+
+<!-- mastermind:intake-begin -->
+```yaml
+action: passthrough
+workflow_mode: unknown
+risk: low
+needs_research: false
+needs_critic: false
+```
+<!-- mastermind:intake-end -->
 ```
 
 ### Ambiguous goal → ask
@@ -145,6 +186,18 @@ I need 2 clarifications before I can refine this:
 2. What's the next consumer of the refined prompt — are you handing this to a planner agent to scope work, or to an executor to write code?
 
 (Optional) Anything you already know is broken about the current onboarding?
+
+## Intake metadata
+
+<!-- mastermind:intake-begin -->
+```yaml
+action: ask
+workflow_mode: unknown
+risk: unknown
+needs_research: false
+needs_critic: false
+```
+<!-- mastermind:intake-end -->
 ```
 
 ## References
@@ -154,4 +207,4 @@ I need 2 clarifications before I can refine this:
 
 ## Pair pieces
 
-The runtime companion is the `mastermind-prompt-refiner` subagent. Mounted as an optional preprocessor in the `mastermind-workflow` CLAUDE.md.
+The runtime companion is the `mastermind-prompt-refiner` subagent. Mounted as the intake gate in `mastermind-workflow` — the first stage before the planner for rough client prompts.

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

@@ -57,7 +57,33 @@ If you find yourself **guessing** at a function signature, a file path, or the n
 
 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.
+### Subagent routing — researcher vs investigator vs self
+
+Before designing, pick the right fact-gathering tool:
+
+| Situation | Use |
+|---|---|
+| You need to batch mmcg lookups (callsites, imports, blast radius, config values) before drafting | `mastermind-researcher` (Haiku — cheap, read-only, returns structured facts) |
+| User reports a bug / unexpected behavior and you do **not know the cause** | `mastermind-investigator` (Sonnet — iterative, maintains Hypothesis Ledger, one probe per turn) |
+| Simple one-symbol lookup, 1-2 quick mmcg queries | Do it yourself inline — spawning a subagent for trivial lookups wastes tokens |
+
+**Researcher** gathers facts in one pass and returns. You do NOT iterate with the researcher — one question, one structured report, done.
+
+**Investigator** iterates. You spawn it with a symptom, it returns an updated ledger + one next probe. You run the probe (or hand it to the user), pass the result back, it updates the ledger again. Repeat until one hypothesis is `confirmed`. Then you open a spec.
+
+### Workflow modes — pick before drafting
+
+Every task runs in one of three modes. Pick the mode first; it determines which spec sections are required. Do NOT use `strict` ceremony for a one-liner.
+
+| Mode | When to use | Required spec sections |
+|---|---|---|
+| **lite** | One-file or trivial change, no auth/billing/migration | Goal, Scope, FIND/CHANGE TO, VERIFY |
+| **standard** | Normal feature or fix — multi-file, no sensitive areas | Everything in lite + Alternatives Considered, Codeflow, Decision Matrix, Tests Plan, Docs Plan, Observability, Performance |
+| **strict** | Auth, billing, migration, public API, data-loss risk, blast-radius ≥ 20 | Everything in standard + Evidence Ledger, Risk Register, 3-lens critic panel, Rollback Plan |
+
+`mastermind new-spec` defaults to `lite`. Pass `--mode standard` or `--mode strict` to get the richer template.
+
+For `strict` mode, the critic panel (3 parallel lenses) is mandatory before drafting the spec. For `standard`, one critic spawn is recommended but not mandatory. For `lite`, skip the critic.
 
 ### Auto-fill the Pre-edit symbol snapshot
 
@@ -91,6 +117,68 @@ If a *single* assumption is load-bearing (e.g. "the user means PostgreSQL, not g
 
 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.
 
+## Debug-time investigation — spawn the investigator
+
+When the user reports a bug, test failure, or unexpected behavior and the root cause is **not already known**, spawn `mastermind-investigator` before opening a spec. Opening a spec on a misdiagnosed bug wastes an entire executor + auditor cycle.
+
+### When to spawn the investigator — mandatory
+
+Spawn when:
+- User says "X is broken" but doesn't say why.
+- A test fails and the stack trace points to ≥ 2 plausible causes.
+- A behavior changed and no obvious commit explains it.
+- You find yourself guessing the cause ("probably the cache", "likely a race condition") without evidence.
+
+Do **not** spawn for:
+- Bugs where the cause is already known (a typo, a wrong constant, a confirmed missing import) — go straight to a spec.
+- Feature requests — the investigator is for unknown failures only.
+- Trivial one-liner fixes where the change is self-evident.
+
+### What to pass the investigator
+
+```markdown
+**Symptom:** <exact observable fact — verbatim error, log line, test name, behavior>
+
+**Scope:** <directory, file pattern, module, or service to search in>
+
+**Prior context (optional):** <any facts already known, hypotheses already considered>
+```
+
+Do not send a wall of context. The investigator needs a clean, cold start — your prior reasoning about the cause is bias, not fact.
+
+### The iteration protocol
+
+The investigator returns an updated **Hypothesis Ledger** and exactly one **Next probe**. Your job as planner:
+
+1. Read the ledger. Do not form your own opinion about which hypothesis is correct.
+2. Execute (or ask the user to run) the one Next probe.
+3. Pass the result back to the investigator as a follow-up with the updated ledger.
+4. Repeat until the ledger has one hypothesis in `confirmed` status.
+
+A `confirmed` hypothesis requires: `evidence_for` populated AND `evidence_against` checked. If the investigator returns a hypothesis as `confirmed` without an `evidence_against` entry, push back — that's premature closure.
+
+Do not run additional probes beyond the one the investigator specified. Uncoordinated parallel probes create conflicting evidence that the ledger can't cleanly incorporate.
+
+### Termination — when to stop investigating and open a spec
+
+Stop the investigation loop when:
+- Exactly one hypothesis is `confirmed` (evidence_for + evidence_against both populated).
+- The investigator's "Current best explanation" names a concrete code location, config value, or external dependency.
+
+At that point:
+1. Copy the "Current best explanation" into the spec's **Goal** section as the diagnosed root cause.
+2. Copy the Ruled out table into the spec's **Notes** — the executor should not re-investigate.
+3. Open the spec normally (pick mode, draft, critic if needed).
+
+If the investigator exhausts probes without confirming a cause: escalate to the user with the full ledger and ruled-out table. Do not guess a root cause. Do not open a spec on an unconfirmed hypothesis.
+
+### Anti-patterns
+
+- **Skipping the investigator because you think you know the answer.** "I'm pretty sure it's X" is exactly the cognitive bias the investigator exists to prevent. If you can't populate `evidence_against` for your hypothesis, you don't know — you guess.
+- **Running probes yourself in parallel with the investigator.** The investigator's probe sequence is deliberate: each result informs the next. Parallel probes create noise.
+- **Opening a spec on a `weakened` hypothesis.** Weakened ≠ confirmed. Wait for confirmation.
+- **Treating "no other hypothesis survived" as evidence_for.** Ruling out alternatives doesn't confirm the survivor — it may mean all hypotheses are wrong.
+
 ## 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.
@@ -149,7 +237,7 @@ Spawn when:
 
 ### What to send the critic
 
-A focused brief — 1-2 paragraphs. **Must include `mmcg` evidence** — without it the critic flags dimension #7 as `fail`:
+A structured design brief. **Must include `mmcg` evidence** — without it the critic flags dimension #7 as `fail`. Use the canonical format in [`references/design-review-packet.md`](references/design-review-packet.md):
 
 ```markdown
 **Problem:** <1-2 sentences on what we're solving>
@@ -160,6 +248,13 @@ A focused brief — 1-2 paragraphs. **Must include `mmcg` evidence** — without
 - <Alt 1>: rejected because <concrete reason>
 - <Alt 2>: rejected because <concrete reason>
 
+**Decision Matrix:**
+| Option | Correctness | Complexity | Blast radius | Migration risk | Observability | Reversibility | Verdict |
+|---|---|---|---|---|---|---|---|
+| A | pass | low | low | none | good | easy | reject |
+| B | concern | medium | high | medium | weak | hard | reject |
+| C | pass | medium | low | none | good | easy | chosen |
+
 **Constraints:** <hard limits — language, deadline, compatibility, ops>
 
 **mmcg snapshot:** <the relevant mmcg_search / mmcg_callers / mmcg_impact results
@@ -174,7 +269,14 @@ Do not send the critic the whole brainstorming conversation — that imports you
 
 **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.
+For green-field interface / API / module-boundary design, generate 3 qualitatively different shapes (not 3 variants of one idea) and pick 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.
+
+**Codeflow diagrams.** For each non-trivial alternative (auth, billing, data-flow, multi-module refactor, API boundary, migration, anything touching ≥ 3 files), include a small Mermaid `flowchart TD` diagram alongside the alternative. Rules:
+
+- **≤ 8 nodes per diagram.**
+- Every node must be a real file, symbol, module, or external boundary — verified via `mmcg_search` or explicitly marked `[NEW]`.
+- No generic box (`User → System → Database`) — that is AI slop and the critic will flag it.
+- Omit diagrams for trivial changes (one-line fix, docs, simple test, mechanical rename).
 
 ### How to read the critic's verdict
 

package/share/skills/mastermind-task-planning/references/design-review-packet.md

@@ -0,0 +1,120 @@
+# Design Review Packet
+
+Canonical input format for spawning `mastermind-critic`. Copy this template, fill every section, and pass it as the critic's input. Do not send raw brainstorming — cold context is the point.
+
+## When to use
+
+- Before drafting a standard or strict spec.
+- Whenever you are unsure which of several approaches to pick.
+- Always for mandatory critic categories (auth, billing, migration, public-API, blast-radius ≥ 20).
+
+---
+
+## Template
+
+```markdown
+# Design Review: <short title>
+
+## Problem
+
+<1-2 sentences — what is broken, missing, or required. Concrete, not abstract.>
+
+## Proposed design
+
+<The approach you intend to implement. 1-3 paragraphs. Concrete enough to critique — name files, symbols, modules. Vague prose like "improve the architecture" gives the critic nothing to work with.>
+
+## Alternatives considered
+
+List ≥ 2 rejected alternatives for non-trivial changes. For each:
+
+### Alternative A — <name>
+
+```mermaid
+flowchart TD
+  <real_symbol_or_file> --> <real_symbol_or_file>
+```
+
+- **Rejected because:** <concrete reason tied to mmcg findings or project constraint>
+
+### Alternative B — <name>
+
+```mermaid
+flowchart TD
+  <real_symbol_or_file> --> <real_symbol_or_file>
+```
+
+- **Rejected because:** <reason>
+
+### Picked approach — <name>
+
+```mermaid
+flowchart TD
+  <real_symbol_or_file> --> <real_symbol_or_file>
+```
+
+- **Chosen because:** <concrete reason>
+
+## Decision Matrix
+
+Crystallizes the alternatives comparison. Fill one row per option above.
+
+| Option | Correctness | Complexity | Blast radius | Migration risk | Observability | Reversibility | Verdict |
+|---|---|---|---|---|---|---|---|
+| A — <name> | pass | low | low | none | good | easy | reject |
+| B — <name> | concern | medium | high | medium | weak | hard | reject |
+| C — <name> | pass | medium | low | none | good | easy | chosen |
+
+Column values: `pass / concern / fail` for Correctness; `low / medium / high` for complexity/blast/migration; `good / weak / none` for observability; `easy / medium / hard` for reversibility. Exactly one row gets `chosen`.
+
+## Constraints
+
+<Hard limits — programming language, runtime version, deadline, backward-compatibility requirements, ops constraints. The critic uses these to distinguish intentional tradeoffs from oversights.>
+
+## mmcg snapshot
+
+<Paste the mmcg evidence that grounds the design. Without this, the critic cannot verify claims and will flag dimension #7 as `fail`. Include at minimum:>
+
+- `mmcg_search <primary_symbol>` → `<file:line>` (<brief description>)
+- `mmcg_callers <primary_symbol>` → `<N> callers` (<impact summary>)
+- `mmcg_impact <primary_symbol> --depth 3` → `<M> transitive` (if relevant)
+- `mmcg_search <secondary_symbol>` → `<file:line>` (if touching ≥ 2 symbols)
+
+For pure doc / config changes with no code symbols: write "no code symbols — mmcg not applicable".
+
+## Risk surface
+
+<Known unknowns and failure modes for the proposed design. The critic will probe these. Being explicit here prevents the critic from marking concerns you already know about as `fail`.>
+
+- <risk 1>: <what could go wrong>
+- <risk 2>: <what could go wrong>
+```
+
+---
+
+## Completeness rules
+
+- **mmcg snapshot is mandatory** for any change touching code symbols.
+- **Decision Matrix is mandatory** for standard and strict specs.
+- **Codeflow diagrams** are required for non-trivial alternatives (multi-module, auth/billing/data-flow, API boundary, migration, ≥ 3 files). All nodes must be real files, symbols, modules, or external boundaries — verified via `mmcg_search` or explicitly marked `[NEW]`. Generic boxes (`User → System → Database`) are AI slop and will cause critic `fail` on dimension #6.
+- **≥ 2 alternatives** for non-trivial changes. For trivial changes (one-line fix, doc edit, mechanical rename), write "trivial change — single approach".
+- **Constraints section must name the actual hard limits** — not vague preferences. If there are none, write "none beyond standard project conventions".
+
+## What NOT to include
+
+- The full brainstorming conversation — that imports your bias.
+- Speculative alternatives you haven't thought through — shallow rejection reasons give the critic nothing to work with.
+- Implementation details that belong in the spec's Scope section — this packet is for design validation, not execution instructions.
+
+---
+
+## For 3-lens critic panels (strict mode)
+
+When spawning three critics in parallel, prepend a lens directive to the same packet:
+
+**Security lens:** "Review primarily for authz/authn holes, secret exposure, injection, and privilege escalation. Other dimensions are secondary."
+
+**Performance lens:** "Review primarily for latency, throughput, memory pressure, and lock contention. Other dimensions are secondary."
+
+**Simplicity lens:** "Review primarily for YAGNI violations, unnecessary abstraction, complexity creep, and AI slop. Other dimensions are secondary."
+
+Same packet body, same mmcg snapshot, same alternatives — only the lens directive differs. Spawn all three in one message so they run concurrently.

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

@@ -93,11 +93,69 @@ You are <doing X> to achieve <Y, the goal in one sentence>.
 
 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.
+For non-trivial alternatives (multi-module, auth/billing/data-flow, API boundary, migration, anything touching ≥ 3 files), add a Mermaid codeflow diagram per alternative. Nodes must be real files, symbols, modules, or external boundaries — verified via `mmcg_search` or explicitly marked `[NEW]`. Keep each diagram ≤ 8 nodes. Generic boxes (`User → System → Database`) are AI slop and will be flagged by the critic.
 
-- **<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>
+### Alternative A — <name>
+
+```mermaid
+flowchart TD
+  <real_symbol_or_file> --> <real_symbol_or_file>
+```
+
+- **Grounding:** `mmcg_search <symbol>` → `<file:line>`, `mmcg_callers <symbol>` → `<N> callers`
+- **Tradeoff:** <concrete>
+- **Rejected because:** <concrete reason tied to mmcg findings or project constraint>
+
+### Alternative B — <name>
+
+```mermaid
+flowchart TD
+  <real_symbol_or_file> --> <real_symbol_or_file>
+```
+
+- **Grounding:** `mmcg_search <symbol>` → `<file:line>`
+- **Tradeoff:** <concrete>
+- **Rejected because:** <reason>
+
+### Picked approach — <name>
+
+```mermaid
+flowchart TD
+  <real_symbol_or_file> --> <real_symbol_or_file>
+```
+
+- **Grounding:** <mmcg evidence>
+- **Chosen because:** <concrete reason>
+
+---
+
+## Decision Matrix *(required for standard/strict; skip for lite)*
+
+Crystallizes the alternatives comparison into an objective grid. Fill one row per option in Alternatives Considered above.
+
+| Option | Correctness | Complexity | Blast radius | Migration risk | Observability | Reversibility | Verdict |
+|---|---|---|---|---|---|---|---|
+| A — <name> | pass | low | low | low | good | easy | reject |
+| B — <name> | concern | low | high | medium | weak | hard | reject |
+| C — <name> | pass | medium | low | none | good | easy | **chosen** |
+
+Column values: `pass / concern / fail` for Correctness; `low / medium / high` for complexity/blast/migration; `good / weak / none` for observability; `easy / medium / hard` for reversibility.
+
+The `Verdict` row must be one of: `chosen`, `reject`, `candidate` (deferred alternative). Exactly one row gets `chosen`.
+
+---
+
+## Risk Register *(required for strict specs; skip for trivial/lite)*
+
+Known risks of the chosen approach. Each risk must have mitigation assigned to a phase. If a risk has no mitigation, say so — don't omit it.
+
+| Risk | Probability | Impact | Evidence | Mitigation | Owner phase |
+|---|---|---|---|---|---|
+| breaks existing callers | medium | high | `mmcg_callers X → 45` | preserve signature, add compat wrapper | Phase 1 |
+| migration leaves stale data | low | high | schema diff shows nullable column | add backfill script, gate on count > 0 | Phase 2 |
+| no prod observability | low | medium | assumption — new code path | add log line + metric in Phase 3 | Phase 3 |
+
+A risk with `impact: high` and no mitigation = automatic critic `fail` on dimension #2 (Performance & scale) or #1 (Correctness).
 
 ---
 
@@ -112,6 +170,24 @@ Auditor will re-run `mmcg_callers` / `mmcg_search` post-execution and surface an
 
 ---
 
+## Evidence Ledger *(required for strict specs; skip for trivial/lite)*
+
+Every non-trivial claim in this spec must be backed by one of: mmcg evidence, file evidence, a runnable command, user-provided input, or an explicit assumption. If a claim has no backing, it's a guess — name it as an assumption so the critic and auditor can flag it.
+
+| Claim | Evidence type | Evidence | Confidence |
+|---|---|---|---|
+| `<symbol>` has N callers | mmcg | `mmcg_callers <symbol> → N` | high |
+| `<file>` contains `<pattern>` | file | `grep '<pattern>' <file>` | high |
+| no prod runtime | assumption | internal build script only; confirmed with user | medium |
+| `<claim>` | user-provided | user stated in session on <date> | medium |
+
+Rules:
+- No `"this should be safe"` without an evidence row
+- No `"existing callers are fine"` without a `mmcg_callers` count
+- Assumptions are allowed, but must be explicit — they become critic `concern` targets
+
+---
+
 ## Phase 1: <First logical step — name it by outcome, not process>
 
 ### 1.1 <Specific action — one verb, one location>
@@ -260,6 +336,10 @@ Explicit anti-patterns specific to this task. Distinct from the global Rules abo
 - [ ] `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)
+- [ ] **Codeflow diagrams** present for every non-trivial alternative, each node mmcg-verified or marked `[NEW]` (or section explicitly skipped as trivial)
+- [ ] **Decision Matrix** filled for standard/strict specs, or explicitly skipped (write "lite — no decision matrix")
+- [ ] **Risk Register** filled for strict specs, or explicitly skipped (write "lite/standard — no risk register")
+- [ ] **Evidence Ledger** — every non-trivial claim has a row, assumptions are explicit (or section skipped for lite)
 - [ ] **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