mindsystem-cc 3.12.0 → 3.13.1

package/agents/ms-plan-writer.md

@@ -1,7 +1,7 @@
 ---
 name: ms-plan-writer
-description: Generates framework-specific PLAN.md files from task breakdown. Spawned by /ms:plan-phase after task identification.
-model: sonnet
+description: Generates pure markdown PLAN.md files and EXECUTION-ORDER.md from task breakdown. Spawned by /ms:plan-phase after task identification.
+model: opus
 tools: Read, Write, Bash, Glob, Grep
 color: blue
 ---
@@ -11,7 +11,7 @@ You are a Mindsystem plan writer. You receive a structured task breakdown from t
 
 You are spawned by `/ms:plan-phase` orchestrator AFTER task identification is complete.
 
-Your job: Transform task lists into parallel-optimized PLAN.md files with proper dependencies, wave assignments, must_haves, and risk assessment.
+Your job: Transform task lists into parallel-optimized PLAN.md files with wave groups, must-haves, and risk assessment.
 
 **What you receive:**
 - Task list with needs/creates/tdd_candidate flags
@@ -20,8 +20,9 @@ Your job: Transform task lists into parallel-optimized PLAN.md files with proper
 - Relevant learnings from past work (debug resolutions, adhoc insights, established patterns, prior decisions, curated cross-milestone learnings)
 
 **What you produce:**
-- PLAN.md files following phase-prompt template
-- Git commit of plans
+- Pure markdown PLAN.md files (no YAML frontmatter, no XML containers)
+- EXECUTION-ORDER.md with wave groups and dependency notes
+- Git commit of all plan files
 - Risk score with top factors
 
 **Critical mindset:** Plans are prompts that Claude executes. Optimize for parallel execution, explicit dependencies, and goal-backward verification.
@@ -30,12 +31,13 @@ Your job: Transform task lists into parallel-optimized PLAN.md files with proper
 <required_reading>
 Load these references for plan writing:
 
-1. `~/.claude/mindsystem/templates/phase-prompt.md` — PLAN.md structure
-2. `~/.claude/mindsystem/references/plan-format.md` — Format conventions
+1. `~/.claude/mindsystem/templates/phase-prompt.md` — Process guidance for plan generation
+2. `~/.claude/mindsystem/references/plan-format.md` — Plan format specification
 3. `~/.claude/mindsystem/references/scope-estimation.md` — Context budgets
-4. `~/.claude/mindsystem/references/tdd.md` — TDD plan structure
-6. `~/.claude/mindsystem/references/goal-backward.md` — must_haves derivation
-7. `~/.claude/mindsystem/references/plan-risk-assessment.md` — Risk scoring
+4. `~/.claude/mindsystem/references/goal-backward.md` — Must-haves derivation
+5. `~/.claude/mindsystem/references/plan-risk-assessment.md` — Risk scoring
+
+Read `~/.claude/mindsystem/references/tdd.md` only if any task has `tdd_candidate: true`. Conditional loading saves ~1,000 tokens for non-TDD phases.
 </required_reading>
 
 <input_format>
@@ -90,8 +92,14 @@ Read required references to understand plan structure and scope rules.
 
 ```bash
 cat ~/.claude/mindsystem/templates/phase-prompt.md
+cat ~/.claude/mindsystem/references/plan-format.md
 cat ~/.claude/mindsystem/references/scope-estimation.md
 ```
+
+If any task has `tdd_candidate: true`, also read:
+```bash
+cat ~/.claude/mindsystem/references/tdd.md
+```
 </step>
 
 <step name="build_dependency_graph">
@@ -138,6 +146,8 @@ Verify:
 - All roots have wave = 1
 - Dependents have wave > all dependencies
 - No cycles exist (error if found)
+
+Wave assignments are written to EXECUTION-ORDER.md, not to individual plans.
 </step>
 
 <step name="group_into_plans">
@@ -147,7 +157,8 @@ Rules:
 1. **Same-wave tasks with no file conflicts → parallel plans**
 2. **Tasks with shared files → same plan**
 3. **TDD candidates → dedicated plans (one feature per TDD plan)**
-5. **2-3 tasks per plan, ~50% context target**
+4. **2-3 tasks per plan, ~50% context target**
+5. **Default to 3 tasks for simple-medium work, 2 for complex**
 
 Grouping algorithm:
 ```
@@ -159,37 +170,27 @@ Grouping algorithm:
 ```
 
 **Plan assignment:**
-- Each plan gets a number (01, 02, 03...)
-- Plans inherit wave from their highest-wave task
-- Plans inherit depends_on from task dependencies (translated to plan IDs)
+- Each plan gets a sequential number (01, 02, 03...)
 </step>
 
 <step name="derive_must_haves">
-**Derive must_haves from phase goal using goal-backward analysis.**
-
-For EACH plan, derive:
-
-```yaml
-must_haves:
-  truths:
-    - "Observable behavior 1 from user perspective"
-    - "Observable behavior 2 from user perspective"
-  artifacts:
-    - path: "src/path/to/file.ts"
-      provides: "What this delivers"
-      min_lines: 30  # Optional
-  key_links:
-    - from: "src/component.tsx"
-      to: "/api/endpoint"
-      via: "fetch in useEffect"
+**Derive must-haves from phase goal using goal-backward analysis.**
+
+For EACH plan, derive a markdown checklist:
+
+```markdown
+## Must-Haves
+- [ ] Valid credentials return 200 with Set-Cookie header
+- [ ] Invalid credentials return 401
+- [ ] Passwords compared with bcrypt, never plaintext
 ```
 
 **Process:**
 1. What must be TRUE for tasks in this plan to achieve their goals?
-2. What artifacts must EXIST with real implementation?
-3. What connections (key_links) must be WIRED between artifacts?
+2. Each item is a user-observable truth, not an implementation detail
+3. 3-7 items per plan
 
-Truths should be user-observable, not implementation details.
+The verifier derives artifacts and key_links from the plan's ## Changes section.
 </step>
 
 <step name="estimate_scope">
@@ -205,115 +206,113 @@ If any plan exceeds:
 - 10+ files: Split by subsystem
 - Complex domain (auth, payments): Consider extra split
 
+Default to 3 tasks for simple-medium work, 2 for complex. Executor overhead reduction creates headroom for the third task.
 </step>
 
 <step name="write_plan_files">
-**Write PLAN.md files following template structure.**
+**Write PLAN.md files following pure markdown format.**
 
 For each plan, create `.planning/phases/{phase_dir}/{phase}-{plan}-PLAN.md`:
 
 ```markdown
----
-phase: {phase_number}-{phase_name}
-plan: {plan_number}
-type: execute  # or tdd
-wave: {wave_number}
-depends_on: [{plan_ids}]
-files_modified: [{files}]
-subsystem_hint: {from phase_context, for executor SUMMARY.md}
-user_setup: []  # If external services needed
-
-must_haves:
-  truths:
-    - {observable_behaviors}
-  artifacts:
-    - path: {file_path}
-      provides: {description}
-  key_links:
-    - from: {source}
-      to: {target}
-      via: {method}
----
+# Plan {NN}: {Descriptive Title}
 
-<objective>
-{plan_goal}
+**Subsystem:** {subsystem_hint} | **Type:** tdd
 
-Purpose: {why_this_matters}
-Output: {artifacts_created}
-</objective>
+## Context
+{Why this work exists. Approach chosen and WHY.}
 
-<execution_context>
-@~/.claude/mindsystem/workflows/execute-plan.md
-@~/.claude/mindsystem/templates/summary.md
-</execution_context>
+## Changes
 
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-{Prior SUMMARYs only if genuinely needed}
-{If debug resolution directly relevant to a plan task: @.planning/debug/resolved/{slug}.md}
-{Relevant source files}
-</context>
+### 1. {Change title}
+**Files:** `{file_path}`
 
-<tasks>
-{Task XML from input, expanded with full structure}
-</tasks>
+{Implementation details. Reference existing utilities with paths.}
 
-<verification>
-- [ ] {verification_checks}
-</verification>
+### 2. {Another change}
+**Files:** `{file_path}`, `{another_path}`
 
-<success_criteria>
-- All tasks completed
-- {plan_specific_criteria}
-</success_criteria>
+{Details with inline code blocks where needed.}
 
-<output>
-After completion, create `.planning/phases/{phase_dir}/{phase}-{plan}-SUMMARY.md`
-</output>
-```
+## Verification
+- `{bash command}` {expected result}
+- `{another command}` {expected result}
 
-**Task expansion:** Convert input task hints to full task structure:
-```xml
-<task type="{type}">
-  <name>Task {N}: {name}</name>
-  <files>{creates}</files>
-  <action>{action_hint expanded}</action>
-  <verify>{verify_hint}</verify>
-  <done>{done_hint}</done>
-</task>
+## Must-Haves
+- [ ] {observable truth}
+- [ ] {observable truth}
 ```
 
-**Learnings-aware expansion:** When expanding `action_hint` to full `<action>`, check `<learnings>` for entries relevant to this specific task:
-- Debug resolution whose domain matches task files or subsystem
-- Established pattern that applies to this task's implementation
-- Curated learning matching the task's technical area
+**Format rules:**
+- Omit `| **Type:** tdd` when type is execute (type defaults to execute)
+- Plans carry no `<execution_context>`, `<context>`, or @-references — the executor loads its own workflow and project files via its agent definition
+- No `<tasks>`, `<verification>`, `<success_criteria>`, `<output>` XML containers
 
-For each relevant learning, append a directive to `<action>`:
+**Learnings integration:** When expanding tasks to ## Changes subsections, check `<learnings>` for entries relevant to each change:
 
-```xml
-<action>
-  {expanded action_hint}
+```markdown
+### 2. Create auth endpoint
+**Files:** `src/api/auth/login.ts`
+
+POST endpoint accepting {email, password}...
 
-  Based on prior learning ({source}): {actionable directive}
-</action>
+**From prior work:** CommonJS libraries fail silently in Edge runtime — verify ESM compat.
 ```
 
 Rules:
-- Maximum 2 learning directives per task (context budget)
+- Maximum 2 learning directives per change
 - Only include learnings that change what the executor would do
 - Phrase as imperative directives, not history
-- If no learnings match a task, add nothing
+- If no learnings match a change, add nothing
 
-**TDD plans:** Use `type: tdd` with feature structure instead of tasks.
+**TDD plans:** When type is tdd, use RED/GREEN/REFACTOR structure in ## Changes:
+
+```markdown
+### 1. RED — Write failing tests
+**Files:** `src/lib/__tests__/validate-email.test.ts`
+
+{Test cases and expectations.}
+
+### 2. GREEN — Implement minimal solution
+**Files:** `src/lib/validate-email.ts`
+
+{Minimal implementation to pass tests.}
+
+### 3. REFACTOR — Improve structure
+**Files:** `src/lib/validate-email.ts`
+
+{Structural improvements. Run tests — all must still pass.}
+```
+</step>
+
+<step name="write_execution_order">
+**Generate EXECUTION-ORDER.md alongside plans.**
+
+Create `.planning/phases/{phase_dir}/EXECUTION-ORDER.md`:
+
+```markdown
+# Execution Order
+
+## Wave 1 (parallel)
+- 01-PLAN.md — {description}
+- 02-PLAN.md — {description}
+
+## Wave 2 (parallel)
+- 03-PLAN.md — {description} (depends on 01 for {reason})
+```
+
+Rules:
+- One wave per dependency level
+- Plans within a wave execute in parallel
+- Brief dependency notes for waves > 1
+- All plans listed
 </step>
 
 <step name="git_commit">
 **Commit all plan files.**
 
 ```bash
-git add .planning/phases/${PHASE}*/*-PLAN.md
+git add .planning/phases/${PHASE_DIR}/*-PLAN.md .planning/phases/${PHASE_DIR}/EXECUTION-ORDER.md
 git commit -m "$(cat <<'EOF'
 docs(${PHASE}): create phase plans
 
@@ -346,8 +345,8 @@ if plan_count >= 5:
   score += 15
   factors.append(f"{plan_count} plans in phase")
 
-# External services (from user_setup)
-services = collect from user_setup frontmatter
+# External services (from task descriptions)
+services = external services mentioned in task descriptions
 if services:
   score += min(len(services) * 10, 20)
   factors.append(f"External services: {', '.join(services)}")
@@ -411,6 +410,7 @@ Return structured markdown to orchestrator:
 
 ### Files Created
 
+- `.planning/phases/{phase_dir}/EXECUTION-ORDER.md`
 - `.planning/phases/{phase_dir}/{phase}-01-PLAN.md`
 - `.planning/phases/{phase_dir}/{phase}-02-PLAN.md`
 - ...
@@ -421,6 +421,10 @@ The orchestrator parses this to present risk via AskUserQuestion and offer next
 
 <anti_patterns>
 
+**DO NOT use YAML frontmatter or XML containers in plans.** Plans are pure markdown.
+
+**DO NOT put wave numbers or dependencies in individual plans.** Use EXECUTION-ORDER.md.
+
 **DO NOT reflexively chain dependencies.**
 Plan 02 does not depend on Plan 01 just because 01 comes first. Check actual needs/creates.
 
@@ -444,12 +448,13 @@ Only reference prior SUMMARYs if this plan genuinely imports types/exports from
 
 Plan writing complete when:
 
-- [ ] References loaded (phase-prompt, scope-estimation, etc.)
+- [ ] References loaded (phase-prompt, plan-format, scope-estimation, + tdd if needed)
 - [ ] Dependency graph built from needs/creates
 - [ ] Waves assigned (all roots wave 1, dependents correct)
 - [ ] Tasks grouped into plans (2-3 tasks, ~50% context)
-- [ ] must_haves derived for each plan
-- [ ] PLAN.md files written with full structure
+- [ ] Must-haves derived as markdown checklists
+- [ ] PLAN.md files written with pure markdown format
+- [ ] EXECUTION-ORDER.md generated with wave groups
 - [ ] Plans committed to git
 - [ ] Risk score calculated with factors
 - [ ] Structured result returned to orchestrator

package/agents/ms-verifier.md

@@ -74,33 +74,37 @@ Extract phase goal from ROADMAP.md. This is the outcome to verify, not the tasks
 
 Determine what must be verified. In re-verification mode, must-haves come from Step 0.
 
-**Option A: Must-haves in PLAN frontmatter**
+**Option A: Must-Haves from PLAN.md**
 
-Check if any PLAN.md has `must_haves` in frontmatter:
+Check if any PLAN.md has a `## Must-Haves` section:
 
 ```bash
-grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
+grep -l "## Must-Haves" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
-If found, extract and use:
+If found, parse the markdown checklist items:
 
-```yaml
-must_haves:
-  truths:
-    - "User can see existing messages"
-    - "User can send a message"
-  artifacts:
-    - path: "src/components/Chat.tsx"
-      provides: "Message list rendering"
-  key_links:
-    - from: "Chat.tsx"
-      to: "api/chat"
-      via: "fetch in useEffect"
+```markdown
+## Must-Haves
+- [ ] User can see existing messages
+- [ ] User can send a message
 ```
 
+Each `- [ ]` item is a **truth** to verify.
+
+**Derive artifacts** from `## Changes` section by parsing `**Files:**` lines:
+
+```bash
+grep "^\*\*Files:\*\*" "$PHASE_DIR"/*-PLAN.md
+```
+
+Each `**Files:**` line identifies artifacts to verify (existence, substantiveness, wiring).
+
+**Derive key_links** from `## Changes` content — look for references between components (fetch calls, imports, database queries mentioned in implementation details).
+
 **Option B: Derive from phase goal**
 
-If no must_haves in frontmatter, derive using goal-backward process:
+If no `## Must-Haves` section found in plans, derive using goal-backward process:
 
 1. **State the goal:** Take phase goal from ROADMAP.md
 
@@ -764,7 +768,7 @@ return <div>No messages</div>  // Always shows "no messages"
 
 - [ ] Previous VERIFICATION.md checked (Step 0)
 - [ ] If re-verification: must-haves loaded from previous, focus on failed items
-- [ ] If initial: must-haves established (from frontmatter or derived)
+- [ ] If initial: must-haves established (from ## Must-Haves section or derived from phase goal)
 - [ ] All truths verified with status and evidence
 - [ ] All artifacts checked at all three levels (exists, substantive, wired)
 - [ ] All key links verified

package/commands/ms/check-phase.md

@@ -18,11 +18,11 @@ This spawns ms-plan-checker to analyze your PLAN.md files against the phase goal
 
 <what_it_checks>
 1. **Requirement Coverage** — Does every phase requirement have tasks addressing it?
-2. **Task Completeness** — Does every task have files, action, verify, done?
+2. **Task Completeness** — Does every change have Files, implementation details, and verification?
 3. **Dependency Correctness** — Are plan dependencies valid and acyclic?
 4. **Key Links Planned** — Are artifacts wired together, not just created in isolation?
 5. **Scope Sanity** — Will plans complete within context budget (2-3 tasks per plan)?
-6. **Verification Derivation** — Are must_haves user-observable, not implementation-focused?
+6. **Verification Derivation** — Are Must-Haves user-observable, not implementation-focused?
 7. **Context Compliance** — Do plans honor decisions from CONTEXT.md?
 </what_it_checks>
 
@@ -60,7 +60,7 @@ Count plans and tasks:
 ```bash
 for plan in "$PHASE_DIR"/*-PLAN.md; do
   echo "=== $(basename $plan) ==="
-  grep -c "<task" "$plan" 2>/dev/null || echo "0 tasks"
+  grep -c "^### " "$plan" 2>/dev/null || echo "0 changes"
 done
 ```
 </step>

package/commands/ms/execute-phase.md

@@ -17,7 +17,7 @@ allowed-tools:
 <objective>
 Execute all plans in a phase using wave-based parallel execution.
 
-Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
+Orchestrator stays lean: discover plans, read execution order, spawn subagents in waves, collect results. Each subagent loads the full execute-plan context and handles its own plan.
 
 Context budget: ~15% orchestrator, 100% fresh per subagent.
 </objective>
@@ -49,11 +49,12 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
 2. **Discover plans**
    - List all *-PLAN.md files in phase directory
    - Check which have *-SUMMARY.md (already complete)
+   - Verify EXECUTION-ORDER.md exists
    - Build list of incomplete plans
 
-3. **Group by wave**
-   - Read `wave` from each plan's frontmatter
-   - Group plans by wave number
+3. **Validate and read execution order**
+   - Run `validate-execution-order.sh` on phase directory
+   - Parse EXECUTION-ORDER.md wave structure
    - Report wave structure to user
 
 4. **Execute waves**
@@ -61,6 +62,7 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
    - Spawn `ms-executor` for each plan in wave (parallel Task calls)
    - Wait for completion (Task blocks)
    - Verify SUMMARYs created
+   - Run `update-state.sh` to update plan progress
    - Proceed to next wave
 
 5. **Aggregate results**
@@ -75,7 +77,7 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
 
 7. **Verify phase goal**
    - Spawn `ms-verifier` subagent with phase directory and goal
-   - Verifier checks must_haves against actual codebase (not SUMMARY claims)
+   - Verifier checks Must-Haves against actual codebase (not SUMMARY claims)
    - Creates VERIFICATION.md with detailed report
    - Route by status:
      - `passed` → continue to step 8
@@ -226,7 +228,7 @@ After all plans in phase complete:
 - [ ] All incomplete plans in phase executed
 - [ ] Each plan has SUMMARY.md
 - [ ] Code review completed (or skipped if config says "skip")
-- [ ] Phase goal verified (must_haves checked against codebase)
+- [ ] Phase goal verified (Must-Haves checked against codebase)
 - [ ] VERIFICATION.md created in phase directory
 - [ ] Patch file generated OR explicitly skipped with message
 - [ ] STATE.md reflects phase completion

package/commands/ms/plan-phase.md

@@ -112,8 +112,9 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
 <success_criteria>
 
 - One or more PLAN.md files created in .planning/phases/XX-name/
-- Each plan has: objective, execution_context, context, tasks, verification, success_criteria, output
-- must_haves derived from phase goal and documented in frontmatter (truths, artifacts, key_links)
-- Tasks are specific enough for Claude to execute
+- Each plan has: Context, Changes, Verification, Must-Haves (pure markdown format)
+- Must-Haves derived as markdown checklist of user-observable truths
+- Changes are specific enough for Claude to execute
+- EXECUTION-ORDER.md created with wave groups and dependencies
 - User knows next steps (execute plan or review/adjust)
   </success_criteria>

package/commands/ms/verify-work.md

@@ -43,9 +43,9 @@ Phase: $ARGUMENTS (optional)
 4. **Extract testable deliverables** from summaries
 5. **Classify tests by mock requirements** — Use SUMMARY.md mock_hints when available; classify inline with keyword heuristics when absent. Confirm data availability with user before batching.
 6. **Group into batches** — By mock type, max 4 per batch, no-mock tests first
-   - If any tests require mocks: Read `~/.claude/mindsystem/references/mock-patterns.md` and `~/.claude/mindsystem/workflows/generate-mocks.md` for mock generation guidance
+   - If any tests require transient_state mocks: Read `~/.claude/mindsystem/references/mock-patterns.md` for delay strategies
 7. **For each batch:**
-   - If mock needed: Generate mocks, present toggle instructions, wait for confirmation
+   - If mock needed: Apply inline mocks (1-4 direct edits, 5+ via ms-mock-generator subagent), tell user to hot reload
    - Present tests via AskUserQuestion (Pass / Can't test / Skip / Other)
    - Process results, update UAT.md
    - **For each issue found:**
@@ -54,10 +54,10 @@ Phase: $ARGUMENTS (optional)
      - If complex: Spawn ms-verify-fixer subagent
      - 2 retries on failed re-test, then offer options
 8. **On batch transition:**
-   - If new mock_type: Discard old mocks, generate new ones
+   - If new mock_type: Revert old mocks (`git checkout -- <mocked_files>`), apply new ones
    - If same mock_type: Keep mocks active
 9. **On completion:**
-   - Discard all mocks (git stash drop)
+   - Revert all mocks (`git checkout -- <mocked_files>`)
    - Generate UAT fixes patch
    - Restore user's pre-existing work (if stashed)
    - Commit UAT.md, present summary
@@ -77,7 +77,7 @@ Phase: $ARGUMENTS (optional)
 - Don't run automated tests — this is manual user validation
 - Don't skip investigation — always try 2-3 tool calls before escalating
 - Don't fix complex issues inline — spawn fixer subagent for multi-file or architectural changes
-- Don't commit mock code — always stash before fixing
+- Don't commit mock code — stash mocked files before fixing, restore after
 - Don't re-present skipped tests — assumptions stand
 </anti_patterns>
 
@@ -85,14 +85,14 @@ Phase: $ARGUMENTS (optional)
 - [ ] Dirty tree handled at start (stash/commit/abort)
 - [ ] Tests extracted from SUMMARY.md and classified
 - [ ] Tests batched by mock requirements
-- [ ] Mocks generated when needed with clear toggle instructions
+- [ ] Mocks applied inline when needed (1-4 direct, 5+ via subagent)
 - [ ] Tests presented in batches of 4 using AskUserQuestion
 - [ ] Issues investigated with lightweight check first
 - [ ] Simple issues fixed inline with proper commit message
 - [ ] Complex issues escalated to fixer subagent
 - [ ] Failed re-tests get 2 retries then options
 - [ ] Stash conflicts auto-resolved to fix version
-- [ ] Mocks discarded on completion
+- [ ] Mocks reverted on completion (git checkout)
 - [ ] UAT fixes patch generated
 - [ ] User's pre-existing work restored
 - [ ] UAT.md committed with final summary

package/mindsystem/references/goal-backward.md

@@ -117,31 +117,16 @@ Key links get extra verification attention. These are where stubs and placeholde
 </the_process>
 
 <output_format>
-The derive_must_haves step produces a structured list for PLAN.md frontmatter:
-
-```yaml
-must_haves:
-  truths:
-    - "User can see existing messages"
-    - "User can send a message"
-    - "Messages persist across refresh"
-  artifacts:
-    - path: "src/components/Chat.tsx"
-      provides: "Message list rendering"
-    - path: "src/app/api/chat/route.ts"
-      provides: "Message CRUD operations"
-    - path: "prisma/schema.prisma"
-      provides: "Message model"
-  key_links:
-    - from: "Chat.tsx"
-      to: "api/chat"
-      via: "fetch in useEffect"
-    - from: "api/chat POST"
-      to: "database"
-      via: "prisma.message.create"
+The derive_must_haves step produces a markdown checklist for the plan's ## Must-Haves section:
+
+```markdown
+## Must-Haves
+- [ ] User can see existing messages
+- [ ] User can send a message
+- [ ] Messages persist across refresh
 ```
 
-This structure is machine-readable for verification after execution.
+Each item is a user-observable truth. The verifier derives artifacts and key_links from the plan's ## Changes section.
 </output_format>
 
 <examples>
@@ -261,7 +246,7 @@ Key links are verification priorities. Without them, you check everything equall
 
 The `derive_must_haves` step runs after gathering context, before breaking into tasks.
 
-Output: `must_haves` structure written to PLAN.md frontmatter.
+Output: must-haves written to the plan's ## Must-Haves section.
 
 Tasks are then designed to CREATE the artifacts and ESTABLISH the wiring.
 
@@ -269,7 +254,7 @@ Tasks are then designed to CREATE the artifacts and ESTABLISH the wiring.
 
 The `verify_phase_goal` step runs after all plans execute, before updating roadmap.
 
-Input: `must_haves` from PLAN.md frontmatter (or derived from goal if missing).
+Input: ## Must-Haves from plan markdown (or derived from goal if missing).
 
 Process: Check each truth against codebase, verify artifacts exist and aren't stubs, trace key links.