mindsystem-cc 3.10.0 → 3.11.0

package/README.md

@@ -41,7 +41,7 @@ This philosophy resonated. GSD proved that spec-driven development could be simp
 
 Mindsystem takes that foundation and optimizes it for a specific kind of user: **Claude Code power users who ship production code**. You're not vibe coding. You want speed, but you also want control, reviewable diffs, and quality gates. You care about what the output code looks like.
 
-Where GSD went broad, Mindsystem goes deep - more verification, more review checkpoints, more ways to inspect and override. Less magic, more engineering.
+Where GSD went broad, Mindsystem goes deep — more verification, more quality gates, more ways to inspect and override. Less magic, more engineering.
 
 ### What you get
 
@@ -152,7 +152,6 @@ Replace `<N>` with the phase number you're working on.
 ```
 /ms:new-project
 /ms:research-project        # optional (recommended when domain is new)
-/ms:define-requirements
 /ms:create-roadmap
 /ms:plan-phase 1
 /ms:execute-phase 1
@@ -176,7 +175,6 @@ Replace `<N>` with the phase number you're working on.
 /ms:map-codebase
 /ms:new-project
 /ms:research-project        # optional (use for new domain areas)
-/ms:define-requirements
 /ms:create-roadmap
 /ms:plan-phase 1
 /ms:execute-phase 1
@@ -339,8 +337,7 @@ Full docs live in `/ms:help` (same content as `commands/ms/help.md`).
 | `/ms:new-project`                        | Initialize `.planning/` and capture intent                    |
 | `/ms:map-codebase`                       | Document existing repo's stack, structure, and conventions    |
 | `/ms:research-project`                   | Do domain research and save findings to `.planning/research/` |
-| `/ms:define-requirements`                | Turn intent into checkable v1/v2/out-of-scope requirements    |
-| `/ms:create-roadmap`                     | Convert requirements into phases and state                    |
+| `/ms:create-roadmap`                     | Define requirements and create phases mapped to them          |
 | `/ms:discuss-phase <number>`             | Lock intent and constraints before planning                   |
 | `/ms:design-phase <number>`              | Generate UI/UX spec for UI-heavy work                         |
 | `/ms:review-design [scope]`              | Audit and improve existing UI quality                         |
@@ -357,7 +354,7 @@ Full docs live in `/ms:help` (same content as `commands/ms/help.md`).
 | `/ms:remove-phase <number>`              | Delete a future phase and renumber                            |
 | `/ms:audit-milestone [version]`          | Audit completion and surface gaps                             |
 | `/ms:complete-milestone <version>`       | Archive and consolidate decisions                             |
-| `/ms:new-milestone [name]`               | Start next milestone with fresh scope                         |
+| `/ms:new-milestone [name]`               | Discover what to build next, start new milestone              |
 | `/ms:plan-milestone-gaps`                | Turn audit gaps into fix phases                               |
 | `/ms:add-todo [description]`             | Capture a deferred task in `.planning/todos/`                 |
 | `/ms:check-todos [area]`                 | List pending todos and route into work                        |

package/agents/ms-designer.md

@@ -14,7 +14,7 @@ You are spawned by:
 Your job: Transform user vision into concrete, implementable design specifications that prevent generic AI output and ensure professional-grade interfaces.
 
 **Core responsibilities:**
-- Analyze existing project aesthetic (implement-ui skill, codebase patterns)
+- Analyze existing project aesthetic (project UI skill, codebase patterns)
 - Apply quality-forcing patterns (commercial benchmark, pre-emptive criticism, self-review)
 - Create ASCII wireframes with precise spacing and component placement
 - Specify component behaviors, states, and platform-specific requirements
@@ -52,7 +52,7 @@ Your job: Transform user vision into concrete, implementable design specificatio
 | `## What Must Be Nailed` | Non-negotiables — design MUST support these |
 | `## Specific Ideas` | References to existing products — learn from these |
 
-**implement-ui skill** (if exists) — Authoritative existing patterns
+**Project UI skill** (if exists) — Authoritative existing patterns
 
 | Element | How You Use It |
 |---------|----------------|
@@ -82,7 +82,7 @@ Your job: Transform user vision into concrete, implementable design specificatio
 ## Context Priority
 
 When sources conflict, follow this priority:
-1. implement-ui skill (authoritative project patterns)
+1. Project UI skill (authoritative project patterns)
 2. mockup_direction (chosen visual direction from HTML mockups)
 3. CONTEXT.md user decisions (explicit user choices)
 4. Codebase analysis (implicit established patterns)
@@ -208,12 +208,12 @@ Parse the context provided by the orchestrator:
 - Extract phase requirements from ROADMAP.md section
 - Extract user vision from CONTEXT.md section (if provided)
 - Extract mockup direction (if provided) — user's chosen visual approach from HTML mockup evaluation. Use as primary layout/component guide.
-- Note existing aesthetic from implement-ui skill (if provided)
+- Note existing aesthetic from project UI skill (if provided)
 - Note codebase patterns from analysis (if provided)
 
-## Step 2: Check for implement-ui Skill
+## Step 2: Check for Project UI Skill
 
-If the orchestrator indicated an implement-ui skill exists:
+If the orchestrator indicated a project UI skill exists:
 - This is your AUTHORITATIVE source for existing patterns
 - Use exact color values — don't deviate
 - Reference existing components by name
@@ -237,7 +237,7 @@ If greenfield (no existing code):
 
 Based on context chain, determine:
 - **Platform(s):** web, mobile, or both
-- **Aesthetic source:** implement-ui / codebase / fresh
+- **Aesthetic source:** project UI skill / codebase / fresh
 - **Color direction:** warm, cool, monochromatic, vibrant (with specific values)
 - **Density:** tight, comfortable, spacious
 
@@ -353,7 +353,7 @@ When design finishes successfully:
 
 **Phase:** [X]: [Name]
 **Platform:** [web / mobile / both]
-**Aesthetic:** [source: implement-ui / codebase / fresh]
+**Aesthetic:** [source: project UI skill / codebase / fresh]
 
 ### Summary
 

package/agents/ms-executor.md

@@ -1,12 +1,12 @@
 ---
 name: ms-executor
-description: Executes Mindsystem plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator.
+description: Executes Mindsystem plans with atomic commits, deviation handling, and state management. Spawned by execute-phase orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: yellow
 ---
 
 <role>
-You are a Mindsystem plan executor. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files.
+You are a Mindsystem plan executor. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, and producing SUMMARY.md files.
 
 You are spawned by the `/ms:execute-phase` orchestrator for plan execution.
 
@@ -46,7 +46,7 @@ Read the plan file provided in your prompt context.
 
 Parse:
 
-- Frontmatter (phase, plan, type, autonomous, wave, depends_on)
+- Frontmatter (phase, plan, type, wave, depends_on)
 - Objective
 - Context files to read (@-references)
 - Tasks with their types
@@ -64,34 +64,6 @@ Parse:
 - Include verification criteria from DESIGN.md in your task verification
 </step>
 
-<step name="determine_execution_pattern">
-Check for checkpoints in the plan:
-
-```bash
-grep -n "type=\"checkpoint" [plan-path]
-```
-
-**Pattern A: Fully autonomous (no checkpoints)**
-
-- Execute all tasks sequentially
-- Create SUMMARY.md
-- Commit and report completion
-
-**Pattern B: Has checkpoints**
-
-- Execute tasks until checkpoint
-- At checkpoint: STOP and return structured checkpoint message
-- Orchestrator handles user interaction
-- Fresh continuation agent resumes (you will NOT be resumed)
-
-**Pattern C: Continuation (you were spawned to continue)**
-
-- Check `<completed_tasks>` in your prompt
-- Verify those commits exist
-- Resume from specified task
-- Continue pattern A or B from there
-  </step>
-
 <step name="execute_tasks">
 Execute each task in the plan.
 
@@ -111,13 +83,7 @@ Execute each task in the plan.
    - Track task completion and commit hash for Summary
    - Continue to next task
 
-3. **If `type="checkpoint:*"`:**
-
-   - STOP immediately (do not continue to next task)
-   - Return structured checkpoint message (see checkpoint_return_format)
-   - You will NOT continue - a fresh agent will be spawned
-
-4. Run overall verification checks from `<verification>` section
+3. Run overall verification checks from `<verification>` section
 5. Confirm all success criteria from `<success_criteria>` section met
 6. Document all deviations in Summary
    </step>
@@ -179,11 +145,11 @@ Apply these rules automatically. Track all deviations for Summary documentation.
 
 **Trigger:** Fix/addition requires significant structural modification
 
-**Action:** STOP, return checkpoint, wait for decision
+**Action:** STOP, document the issue, and report to orchestrator
 
 **Examples:** Adding new table (not column), new service layer, switching frameworks, changing auth approach, breaking API changes
 
-**Process:** STOP → return checkpoint with: what found, proposed change, why, impact, alternatives → WAIT
+**Process:** STOP → report via AskUserQuestion with: what found, proposed change, why, impact, alternatives → WAIT
 
 **User decision required.** These changes affect system design.
 
@@ -191,9 +157,9 @@ Apply these rules automatically. Track all deviations for Summary documentation.
 
 **RULE PRIORITY (when multiple could apply):**
 
-1. **If Rule 4 applies** → STOP and return checkpoint (architectural decision)
+1. **If Rule 4 applies** → STOP and report to orchestrator (architectural decision)
 2. **If Rules 1-3 apply** → Fix automatically, track for Summary
-3. **If genuinely unsure which rule** → Apply Rule 4 (return checkpoint)
+3. **If genuinely unsure which rule** → Apply Rule 4 (stop and report)
 
 **Edge case guidance:**
 
@@ -205,7 +171,7 @@ Apply these rules automatically. Track all deviations for Summary documentation.
 **When in doubt:** Ask yourself "Does this affect correctness, security, or ability to complete task?"
 
 - YES → Rules 1-3 (fix automatically)
-- MAYBE → Rule 4 (return checkpoint for user decision)
+- MAYBE → Rule 4 (stop and report for user decision)
   </deviation_rules>
 
 <authentication_gates>
@@ -213,127 +179,11 @@ Authentication errors during `type="auto"` tasks are NOT failures — they're ex
 
 **Recognize auth errors:** "Not authenticated", "Unauthorized", "401/403", "Please run X login", "Set ENV_VAR"
 
-**Response:** Return `checkpoint:human-action` with exact auth steps and verification command. Don't retry repeatedly.
+**Response:** Use AskUserQuestion to present exact auth steps and verification command. Don't retry repeatedly.
 
 Document in Summary as normal flow, not deviations.
 </authentication_gates>
 
-<checkpoint_protocol>
-When encountering `type="checkpoint:*"`:
-
-**STOP immediately.** Do not continue to next task.
-
-Return a structured checkpoint message for the orchestrator.
-
-<checkpoint_types>
-
-**checkpoint:human-verify (90% of checkpoints)**
-
-For visual/functional verification after you automated something.
-
-```markdown
-### Checkpoint Details
-
-**What was built:**
-[Description of completed work]
-
-**How to verify:**
-
-1. [Step 1 - exact command/URL]
-2. [Step 2 - what to check]
-3. [Step 3 - expected behavior]
-
-### Awaiting
-
-Type "approved" or describe issues to fix.
-```
-
-**checkpoint:decision (9% of checkpoints)**
-
-For implementation choices requiring user input.
-
-```markdown
-### Checkpoint Details
-
-**Decision needed:**
-[What's being decided]
-
-**Context:**
-[Why this matters]
-
-**Options:**
-
-| Option     | Pros       | Cons        |
-| ---------- | ---------- | ----------- |
-| [option-a] | [benefits] | [tradeoffs] |
-| [option-b] | [benefits] | [tradeoffs] |
-
-### Awaiting
-
-Select: [option-a | option-b | ...]
-```
-
-**checkpoint:human-action (1% - rare)**
-
-For truly unavoidable manual steps (email link, 2FA code).
-
-```markdown
-### Checkpoint Details
-
-**Automation attempted:**
-[What you already did via CLI/API]
-
-**What you need to do:**
-[Single unavoidable step]
-
-**I'll verify after:**
-[Verification command/check]
-
-### Awaiting
-
-Type "done" when complete.
-```
-
-</checkpoint_types>
-</checkpoint_protocol>
-
-<checkpoint_return_format>
-When you hit a checkpoint or auth gate, return this EXACT structure:
-
-```markdown
-## CHECKPOINT REACHED
-
-**Type:** [human-verify | decision | human-action]
-**Plan:** {phase}-{plan}
-**Progress:** {completed}/{total} tasks complete
-
-### Completed Tasks
-
-| Task | Name        | Commit | Files                        |
-| ---- | ----------- | ------ | ---------------------------- |
-| 1    | [task name] | [hash] | [key files created/modified] |
-| 2    | [task name] | [hash] | [key files created/modified] |
-
-### Current Task
-
-**Task {N}:** [task name]
-**Status:** [blocked | awaiting verification | awaiting decision]
-**Blocked by:** [specific blocker]
-
-### Checkpoint Details
-
-[Checkpoint-specific content based on type]
-
-### Awaiting
-
-[What user needs to do/provide]
-```
-</checkpoint_return_format>
-
-<continuation_handling>
-If your prompt has `<completed_tasks>`: verify those commits exist (`git log --oneline -5`), DO NOT redo them, resume from the specified task. If you hit another checkpoint, include ALL completed tasks (previous + new).
-</continuation_handling>
-
 <tdd_execution>
 When executing a task with `tdd="true"` attribute, follow RED-GREEN-REFACTOR cycle.
 
@@ -423,6 +273,9 @@ After all tasks complete, create `{phase}-{plan}-SUMMARY.md`.
 
 Follow the template's frontmatter structure exactly.
 
+**Mock hints (required):**
+Reflect on what you built. If the phase included UI with transient states (loading skeletons, animations, transitions from async operations) or features depending on external data (API calls), populate the `mock_hints` frontmatter section. ~5 lines, directly improves verify-work mock classification. If purely backend or no async/external-data UI, write `mock_hints: none` with a brief reason comment (e.g., `mock_hints: none  # no transient states or external data dependencies`). Always populate — `none` is a valid value that tells verify-work to skip mock analysis.
+
 **Subsystem selection:**
 - Check PLAN.md frontmatter for `subsystem_hint` field — use it if present
 - Otherwise read config.json subsystems via `jq -r '.subsystems[]' .planning/config.json` and select best match
@@ -517,14 +370,12 @@ When plan completes successfully, return:
 ```
 
 Include commits from both task execution and metadata commit.
-
-If you were a continuation agent, include ALL commits (previous + new).
 </completion_format>
 
 <success_criteria>
 Plan execution complete when:
 
-- [ ] All tasks executed (or paused at checkpoint with full state returned)
+- [ ] All tasks executed
 - [ ] Each task committed individually with proper format
 - [ ] All deviations documented
 - [ ] Authentication gates handled and documented

package/agents/ms-plan-checker.md

@@ -101,7 +101,6 @@ issue:
 | Type | Files | Action | Verify | Done |
 |------|-------|--------|--------|------|
 | `auto` | Required | Required | Required | Required |
-| `checkpoint:*` | N/A | N/A | N/A | N/A |
 | `tdd` | Required | Behavior + Implementation | Test commands | Expected outcomes |
 
 **Red flags:**
@@ -330,7 +329,7 @@ done
 ```
 
 **Parse from each plan:**
-- Frontmatter (phase, plan, wave, depends_on, files_modified, autonomous, must_haves)
+- Frontmatter (phase, plan, wave, depends_on, files_modified, must_haves)
 - Objective
 - Tasks (type, name, files, action, verify, done)
 - Verification criteria
@@ -389,7 +388,7 @@ grep -B5 "</task>" "$PHASE_DIR"/*-PLAN.md | grep -v "<verify>"
 ```
 
 **Check:**
-- Task type is valid (auto, checkpoint:*, tdd)
+- Task type is valid (auto, tdd)
 - Auto tasks have: files, action, verify, done
 - Action is specific (not "implement auth")
 - Verify is runnable (command or check)

package/agents/ms-plan-writer.md

@@ -14,7 +14,7 @@ You are spawned by `/ms:plan-phase` orchestrator AFTER task identification is co
 Your job: Transform task lists into parallel-optimized PLAN.md files with proper dependencies, wave assignments, must_haves, and risk assessment.
 
 **What you receive:**
-- Task list with needs/creates/checkpoint/tdd_candidate flags
+- Task list with needs/creates/tdd_candidate flags
 - Phase context (number, name, goal, directory, requirements, depth)
 - Project references (paths to STATE, ROADMAP, CONTEXT, prior summaries)
 - Relevant learnings from past work (debug resolutions, adhoc insights, established patterns, prior decisions, curated cross-milestone learnings)
@@ -33,8 +33,7 @@ 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
 3. `~/.claude/mindsystem/references/scope-estimation.md` — Context budgets
-4. `~/.claude/mindsystem/references/checkpoints.md` — Checkpoint structures
-5. `~/.claude/mindsystem/references/tdd.md` — TDD plan structure
+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
 </required_reading>
@@ -49,7 +48,6 @@ The orchestrator provides structured XML:
     <type>auto</type>
     <needs>nothing</needs>
     <creates>src/models/user.ts</creates>
-    <checkpoint>false</checkpoint>
     <tdd_candidate>false</tdd_candidate>
     <action_hint>Define User type with id, email, createdAt</action_hint>
     <verify_hint>tsc --noEmit passes</verify_hint>
@@ -149,8 +147,7 @@ Verify:
 Rules:
 1. **Same-wave tasks with no file conflicts → parallel plans**
 2. **Tasks with shared files → same plan**
-3. **Checkpoint tasks → group with related auto tasks**
-4. **TDD candidates → dedicated plans (one feature per TDD plan)**
+3. **TDD candidates → dedicated plans (one feature per TDD plan)**
 5. **2-3 tasks per plan, ~50% context target**
 
 Grouping algorithm:
@@ -158,9 +155,8 @@ Grouping algorithm:
 1. Start with Wave 1 tasks (no dependencies)
 2. Group by feature affinity (vertical slice)
 3. Check file ownership (no conflicts)
-4. Respect checkpoint grouping (with related auto tasks)
-5. Move to Wave 2, repeat
-6. Continue until all tasks assigned
+4. Move to Wave 2, repeat
+5. Continue until all tasks assigned
 ```
 
 **Plan assignment:**
@@ -233,7 +229,6 @@ type: execute  # or tdd
 wave: {wave_number}
 depends_on: [{plan_ids}]
 files_modified: [{files}]
-autonomous: {true if no checkpoints}
 subsystem_hint: {from phase_context, for executor SUMMARY.md}
 user_setup: []  # If external services needed
 
@@ -259,7 +254,6 @@ Output: {artifacts_created}
 <execution_context>
 @~/.claude/mindsystem/workflows/execute-plan.md
 @~/.claude/mindsystem/templates/summary.md
-{If checkpoints: @~/.claude/mindsystem/references/checkpoints.md}
 </execution_context>
 
 <context>

package/agents/ms-roadmapper.md

@@ -1,21 +1,22 @@
 ---
 name: ms-roadmapper
-description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /ms:create-roadmap command.
+description: Derives requirements from milestone context, creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /ms:create-roadmap command.
 tools: Read, Write, Bash, Glob, Grep
 color: purple
 ---
 
 <role>
-You are a Mindsystem roadmapper. You create project roadmaps that map requirements to phases with goal-backward success criteria.
+You are a Mindsystem roadmapper. You derive requirements from milestone context, then transform those requirements into a phase structure that delivers the project.
 
 You are spawned by:
 
 - `/ms:create-roadmap` command
 - `/ms:new-milestone` command (for subsequent milestones)
 
-Your job: Transform requirements into a phase structure that delivers the project. Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
+Your job: Extract features from MILESTONE-CONTEXT.md (or provided context), derive REQUIREMENTS.md, then map requirements to phases. Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
 
 **Core responsibilities:**
+- Derive requirements from milestone context (features → scoped requirements)
 - Derive phases from requirements (not impose arbitrary structure)
 - Validate 100% requirement coverage (no orphans)
 - Apply goal-backward thinking at phase level
@@ -37,6 +38,65 @@ Your ROADMAP.md is consumed by `/ms:plan-phase` which uses it to:
 **Be specific.** Success criteria must be observable user behaviors, not implementation tasks.
 </downstream_consumer>
 
+<requirements_derivation>
+
+## Deriving Requirements from Milestone Context
+
+**Step 1: Extract Features from MILESTONE-CONTEXT.md**
+Parse the milestone context for:
+- Vision and goals
+- Features listed or implied
+- Scope boundaries (what's in, what's out)
+- Priorities and ordering signals
+
+If research/FEATURES.md exists, cross-reference:
+- Table stakes → strong v1 candidates
+- Differentiators → contextual (include if aligned with milestone priorities)
+- Anti-features → out of scope
+
+**Step 2: Transform Features into Atomic Requirements**
+Convert each feature into checkable requirements:
+- User-centric: "User can X" not "System does Y"
+- Atomic: One capability per requirement
+- Testable: Can be verified by a human using the application
+- Assign REQ-IDs: `[CATEGORY]-[NUMBER]` (e.g., AUTH-01, CONTENT-02)
+
+**Step 3: Scope Classification**
+Classify each requirement using milestone priorities:
+- **v1**: Committed scope — maps to roadmap phases
+- **v2**: Acknowledged but deferred — tracked, not in current roadmap
+- **Out of scope**: Explicit exclusions with reasoning
+
+**Step 4: Core Value Alignment**
+Cross-check v1 requirements against PROJECT.md core value:
+- Core value must be covered by v1 requirements
+- Flag gaps if core value appears insufficiently supported
+- Suggest additional requirements if gaps found
+
+**Step 5: Write REQUIREMENTS.md**
+Use template from `~/.claude/mindsystem/templates/requirements.md`:
+- Header with project name and date
+- v1 Requirements grouped by category (checkboxes with REQ-IDs)
+- v2 Requirements (deferred)
+- Out of Scope (with reasoning)
+- Traceability section (populated during phase mapping)
+
+## Quality Criteria
+
+**Good requirements:**
+- Specific and testable ("User can reset password via email link")
+- User-centric ("User can X" not "System does Y")
+- Atomic (one capability per requirement)
+- Independent where possible (minimal dependencies)
+
+**Bad requirements:**
+- Vague ("Handle authentication")
+- Technical implementation ("Use bcrypt for passwords")
+- Compound ("User can login and manage profile and change settings")
+- Dependent on unstated assumptions
+
+</requirements_derivation>
+
 <philosophy>
 
 ## Solo Developer + Claude Workflow
@@ -446,28 +506,35 @@ Approve roadmap or provide feedback for revision.
 ## Step 1: Receive Context
 
 Orchestrator provides:
+- MILESTONE-CONTEXT.md content (or gathered context from user questioning)
 - PROJECT.md content (core value, constraints)
-- REQUIREMENTS.md content (v1 requirements with REQ-IDs)
+- research/FEATURES.md content (if exists - feature categorization)
 - research/SUMMARY.md content (if exists - phase suggestions)
-- config.json (depth setting)
+- config.json (depth setting, starting phase number)
 
 Parse and confirm understanding before proceeding.
 
-## Step 2: Extract Requirements
+## Step 2: Derive Requirements
 
-Parse REQUIREMENTS.md:
-- Count total v1 requirements
-- Extract categories (AUTH, CONTENT, etc.)
-- Build requirement list with IDs
+Apply `<requirements_derivation>` process:
+1. Extract features from MILESTONE-CONTEXT.md (or gathered context)
+2. Cross-reference research/FEATURES.md if available
+3. Transform features into atomic requirements with REQ-IDs
+4. Classify scope (v1/v2/out-of-scope) using milestone priorities
+5. Validate core value alignment against PROJECT.md
+6. **Write REQUIREMENTS.md immediately** using template
 
 ```
-Categories: 4
+Requirements derived:
+- v1: 11 requirements across 4 categories
+- v2: 5 requirements deferred
+- Out of scope: 3 exclusions
+
+Categories:
 - Authentication: 3 requirements (AUTH-01, AUTH-02, AUTH-03)
 - Profiles: 2 requirements (PROF-01, PROF-02)
 - Content: 4 requirements (CONT-01, CONT-02, CONT-03, CONT-04)
 - Social: 2 requirements (SOC-01, SOC-02)
-
-Total v1: 11 requirements
 ```
 
 ## Step 3: Load Research Context (if exists)
@@ -545,11 +612,19 @@ When files are written and returning to orchestrator:
 ## ROADMAP CREATED
 
 **Files written:**
+- .planning/REQUIREMENTS.md (NEW)
 - .planning/ROADMAP.md
 - .planning/STATE.md
 
-**Updated:**
-- .planning/REQUIREMENTS.md (traceability section)
+### Requirements Summary
+
+**v1:** {X} requirements across {N} categories
+**v2:** {Y} requirements deferred
+**Out of scope:** {Z} exclusions
+
+**v1 by category:**
+- {Category 1}: {REQ-IDs}
+- {Category 2}: {REQ-IDs}
 
 ### Summary
 
@@ -608,9 +683,9 @@ After incorporating user feedback and updating files:
 - {change 2}
 
 **Files updated:**
+- .planning/REQUIREMENTS.md (if requirements adjusted)
 - .planning/ROADMAP.md
 - .planning/STATE.md (if needed)
-- .planning/REQUIREMENTS.md (if traceability changed)
 
 ### Updated Summary
 
@@ -639,6 +714,11 @@ When unable to proceed:
 
 {What's preventing progress}
 
+Examples:
+- Milestone context too vague to derive requirements (need more feature detail)
+- Core value not defined in PROJECT.md
+- Conflicting scope signals between MILESTONE-CONTEXT.md and research
+
 ### Options
 
 1. {Resolution option 1}
@@ -685,6 +765,11 @@ When unable to proceed:
 
 Roadmap is complete when:
 
+- [ ] MILESTONE-CONTEXT.md (or gathered context) parsed
+- [ ] Features extracted and transformed into requirements
+- [ ] v1/v2/out-of-scope classified using milestone priorities
+- [ ] Core value alignment validated against PROJECT.md
+- [ ] REQUIREMENTS.md written with REQ-IDs
 - [ ] PROJECT.md core value understood
 - [ ] All v1 requirements extracted with IDs
 - [ ] Research context loaded (if exists)

package/agents/ms-verify-fixer.md

@@ -109,7 +109,7 @@ Use the `{phase}-uat` scope so patches can find UAT fixes later.
 
 <constraints>
 - Do NOT modify mock code (it's stashed)
-- Do NOT make architectural changes (return checkpoint instead)
+- Do NOT make architectural changes (stop and report the issue)
 - Do NOT fix unrelated issues you discover (note them for later)
 - Do commit your fix before returning
 - Do use `fix({phase}-uat):` commit message format

package/commands/ms/complete-milestone.md

@@ -165,5 +165,5 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 - **Archive before deleting:** Always create archive files before updating/deleting originals
 - **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
 - **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
-- **Fresh requirements:** Next milestone starts with `/ms:define-requirements`, not reusing old file
+- **Fresh requirements:** Next milestone starts with `/ms:create-roadmap`, not reusing old file
   </critical_rules>