mindsystem-cc 3.20.0 → 3.21.0

package/commands/ms/config.md

@@ -0,0 +1,202 @@
+---
+name: ms:config
+description: Configure Mindsystem preferences — code reviewers, gitignore, git remote
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+
+Configure Mindsystem preferences for the current project.
+
+Manages code reviewer agents, .gitignore patterns for `.planning/` artifacts, and git remote setup. Run anytime to reconfigure — idempotent.
+
+</objective>
+
+<process>
+
+<step name="load_context">
+
+**Load current state:**
+
+```bash
+# Check for existing config
+[ -f .planning/config.json ] && cat .planning/config.json || echo "NO_CONFIG"
+
+# Check for PROJECT.md (tech stack detection)
+[ -f .planning/PROJECT.md ] && echo "HAS_PROJECT" || echo "NO_PROJECT"
+
+# Check for STACK.md (precise tech detection)
+[ -f .planning/codebase/STACK.md ] && echo "HAS_STACK" || echo "NO_STACK"
+
+# Check git remote
+git remote -v 2>/dev/null || echo "NO_REMOTE"
+```
+
+**Run this before proceeding.**
+
+</step>
+
+<step name="git_remote">
+
+**Skip if remote already configured.**
+
+If no remote exists:
+
+Explain: "Your project has a local git repo but no remote. Want to create one on GitHub?"
+
+Use AskUserQuestion:
+- header: "Git remote"
+- question: "Create a GitHub repository for this project?"
+- options:
+  - "Create with gh CLI" — Run `gh repo create` to set up remote and push
+  - "Skip for now" — Continue without remote
+
+If "Create with gh CLI":
+- Derive repo name from directory name
+- Show the command: `gh repo create [name] --source=. --push`
+- Confirm with user before executing
+- Execute via Bash tool
+
+</step>
+
+<step name="code_reviewers">
+
+Show current code_review values from config.json (if loaded).
+
+**If PROJECT.md or STACK.md exists:** Detect tech stack and suggest appropriate reviewers:
+
+- **Flutter/Dart:** adhoc=`ms-flutter-code-quality`, phase=`ms-flutter-code-quality`, milestone=`ms-flutter-reviewer`
+- **All others:** adhoc=`ms-code-simplifier`, phase=`ms-code-simplifier`, milestone=null
+
+**If no PROJECT.md or STACK.md:** Warn: "No PROJECT.md found — can't suggest reviewers based on tech stack. Run `/ms:new-project` first, or pick manually."
+
+Use AskUserQuestion:
+- header: "Code review"
+- question: "Which code reviewer configuration do you want?"
+- options:
+  - "[Suggested based on stack]" — e.g., "Flutter reviewers (ms-flutter-code-quality)" (Recommended)
+  - "Skip code review" — Disable review for all tiers
+  - "Custom" — I'll specify reviewers manually
+
+If "Custom": ask for each tier (adhoc, phase, milestone) individually.
+
+If "Skip code review": set all three values to `"skip"`.
+
+Update config.json with selected values.
+
+</step>
+
+<step name="gitignore_patterns">
+
+Check if `.gitignore` exists and current `.planning/` ignore patterns:
+
+```bash
+[ -f .gitignore ] && grep -n "planning" .gitignore || echo "NO_PLANNING_PATTERNS"
+```
+
+Explain: "We recommend committing `.planning/` to git — it's your project's memory (decisions, requirements, knowledge files). But some artifacts are large or environment-specific."
+
+Use AskUserQuestion (multiSelect):
+- header: "Gitignore"
+- question: "Which `.planning/` artifacts should be git-ignored?"
+- options:
+  - "Phase patch files (`.planning/phases/**/*.patch`)" — Large binary diffs, regeneratable
+  - "Design mockups (`.planning/phases/**/*.html`)" — Generated HTML mockups from design-phase
+
+Apply selected patterns to `.gitignore`. Create the file if needed.
+
+If no selections: skip gitignore changes.
+
+</step>
+
+<step name="validation_summary">
+
+Show final config state:
+
+```
+Configuration updated:
+
+- Code reviewers: [adhoc / phase / milestone values]
+- Gitignore: [patterns added, or "no changes"]
+- Git remote: [remote URL, or "none configured"]
+```
+
+Check subsystems in config.json. If empty or missing, note:
+"Subsystems are derived during `/ms:new-project`. Run `/ms:doctor` to update or verify them."
+
+</step>
+
+<step name="commit">
+
+**Skip if no changes made.**
+
+```bash
+git add .planning/config.json .gitignore
+git commit -m "$(cat <<'EOF'
+chore: configure mindsystem preferences
+EOF
+)"
+```
+
+</step>
+
+<step name="done">
+
+Present next steps:
+
+**If PROJECT.md exists:**
+
+```
+---
+
+## ▶ Next Up
+
+`/ms:new-milestone` — Discover what to build next, create requirements and roadmap
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/ms:doctor` — Verify subsystems and artifact health
+
+---
+```
+
+**If no PROJECT.md:**
+
+```
+---
+
+## ▶ Next Up
+
+`/ms:new-project` — Initialize project with business context and vision
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/ms:doctor` — Verify subsystems and artifact health
+
+---
+```
+
+</step>
+
+</process>
+
+<success_criteria>
+
+- [ ] Changes committed (if any)
+- [ ] User routed to next step
+- [ ] Gitignore patterns applied (if selected)
+- [ ] Git remote offered (if missing)
+- [ ] Validation summary displayed
+- [ ] Config.json code_review values set (or preserved if skipped)
+
+</success_criteria>

package/commands/ms/design-phase.md

@@ -41,17 +41,12 @@ ls .planning/phases/${PHASE}-*/*DESIGN.md 2>/dev/null
 ## 1. Parse and Validate Phase
 
 ```bash
-# Extract and normalize phase number from arguments
-PHASE_ARG="$ARGUMENTS"
-PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
-
-# Validate phase exists in roadmap
-grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
+ms-tools find-phase "$ARGUMENTS"
 ```
 
-**If not found:** Error and exit with message: "Phase ${PHASE} not found in ROADMAP.md"
+**If not found (dir is null):** Error and exit with message: "Phase not found in ROADMAP.md"
 
-**If found:** Extract phase number, name, description. Store for later use.
+**If found:** Extract phase number, name, description from the returned JSON and ROADMAP.md.
 
 ## 2. Check Existing Design
 

package/commands/ms/discuss-phase.md

@@ -1,6 +1,6 @@
 ---
 name: ms:discuss-phase
-description: Gather phase context through adaptive questioning before planning
+description: Gather phase context through product-informed collaborative thinking before planning
 argument-hint: "[phase]"
 allowed-tools:
   - Read
@@ -8,14 +8,15 @@ allowed-tools:
   - Bash
   - Glob
   - AskUserQuestion
+  - Task
 ---
 
 <objective>
-Help the user articulate their vision for a phase through collaborative thinking.
+Act as a collaborative product owner — loading milestone-level artifacts, surfacing assumptions, optionally researching competitors, and grounding every question in product analysis.
 
-Purpose: Understand HOW the user imagines this phase working — what it looks like, what's essential. You're a thinking partner helping them crystallize their vision, not an interviewer gathering technical requirements.
+Purpose: Understand HOW the user imagines this phase working, informed by target audience, competitive landscape, and industry patterns. You're a thinking partner with product sense helping them crystallize their vision.
 
-Output: {phase}-CONTEXT.md capturing the user's vision for the phase
+Output: {phase}-CONTEXT.md capturing the user's vision with reasoning-backed decisions
 </objective>
 
 <execution_context>
@@ -25,10 +26,9 @@ Output: {phase}-CONTEXT.md capturing the user's vision for the phase
 <context>
 Phase number: $ARGUMENTS (required)
 
-**Normalize phase number:**
+**Resolve phase:**
 ```bash
-PHASE_ARG="$ARGUMENTS"
-PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
+ms-tools find-phase "$ARGUMENTS"
 ```
 
 **Load project state first:**
@@ -36,31 +36,35 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
 
 **Load roadmap:**
 @.planning/ROADMAP.md
+
+**Load project context:**
+@.planning/PROJECT.md
 </context>
 
 <process>
 1. Validate phase number argument (error if missing or invalid)
 2. Check if phase exists in roadmap
-3. Check if CONTEXT.md already exists (offer to update if yes)
-3.5. **Load prior knowledge** — determine relevant subsystem(s) by matching ROADMAP.md phase description against subsystem names in config.json. Load matching `.planning/knowledge/{subsystem}.md` files. If knowledge exists, present brief "What we know so far" summary before questioning.
-4. Follow discuss-phase.md workflow with **ALL questions using AskUserQuestion**:
-   - Present phase from roadmap
-   - Use AskUserQuestion: "How do you imagine this working?" with interpretation options
-   - Use AskUserQuestion to follow their thread — probe what excites them
-   - Use AskUserQuestion to sharpen the core — what's essential for THIS phase
-   - Use AskUserQuestion for decision gate (ready / ask more / let me add context)
-   - Create CONTEXT.md capturing their vision
-5. Present pre-work status: Read `~/.claude/mindsystem/references/prework-status.md` and show what's done vs still needed for this phase
-6. Update `.planning/STATE.md` Last Command field:
-   - Format: `Last Command: ms:discuss-phase $ARGUMENTS | YYYY-MM-DD HH:MM`
+3. **Load milestone artifacts** — extract Who It's For, Core Value, How It's Different from PROJECT.md. Parse requirements mapped to this phase from REQUIREMENTS.md. Graceful if any artifact missing.
+4. **Load prior knowledge** — determine relevant subsystem(s) by matching ROADMAP.md phase description against subsystem names in config.json. Load matching `.planning/knowledge/{subsystem}.md` files. If knowledge exists, present brief "What we know so far" summary.
+5. Check if CONTEXT.md already exists (offer to update if yes)
+6. **Assess and research** — evaluate if phase involves user-facing product decisions. If yes, offer product research via AskUserQuestion → spawn ms-product-researcher if accepted. Skip silently for backend/infra phases.
+7. **Present briefing** — weave together: requirements for this phase, Claude's assumptions (approach, scope, risks with confidence levels), and research findings if available. Ask user to validate/correct assumptions.
+8. **Informed discussion** — follow discuss-phase.md workflow. ALL questions use AskUserQuestion.
+9. Create CONTEXT.md capturing their vision with reasoning-backed decisions
+10. Present pre-work status: Read `~/.claude/mindsystem/references/prework-status.md` and show what's done vs still needed for this phase
+11. Update `.planning/STATE.md` Last Command field:
+    - Format: `Last Command: ms:discuss-phase $ARGUMENTS | YYYY-MM-DD HH:MM`
 
 **CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
 </process>
 
 <success_criteria>
 
-- Phase validated against roadmap
-- Vision gathered through collaborative thinking (not interrogation)
-- CONTEXT.md captures: how it works, what's essential
+- Phase validated and milestone artifacts loaded (graceful if missing)
+- Assumptions surfaced and validated before deep questioning
+- Product research offered for user-facing phases
+- Vision gathered through product-informed collaborative thinking (not interrogation)
+- CONTEXT.md captures: how it works, what's essential, decisions with inline reasoning
+- CONTEXT.md committed and STATE.md Last Command updated
 - User knows next steps (research or plan the phase)
 </success_criteria>

package/commands/ms/doctor.md

@@ -13,11 +13,15 @@ allowed-tools:
 ---
 
 <objective>
-Run comprehensive health checks on project configuration. Detect and fix structural drift across 6 categories: subsystem vocabulary, milestone directory structure, phase archival, knowledge files, phase summaries, and PLAN cleanup.
+Run health checks on project configuration. Detect and fix structural drift across 8 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, and CLI wrappers.
 
-Idempotent — safe to run repeatedly.
+Idempotent.
 </objective>
 
+<execution_context>
+@~/.claude/mindsystem/workflows/doctor-fixes.md
+</execution_context>
+
 <context>
 @.planning/config.json
 @.planning/MILESTONES.md
@@ -68,7 +72,7 @@ Proceed to next step.
 Run the diagnostic scan:
 
 ```bash
-~/.claude/mindsystem/scripts/doctor-scan.sh
+ms-tools doctor-scan
 ```
 
 Capture the full output. Parse each check's Status (PASS/FAIL/SKIP) and detail lines.
@@ -84,10 +88,12 @@ Display results as a markdown table:
 |--------------------------|--------|----------------------------------|
 | Subsystem vocabulary     | PASS   | 9 subsystems, all artifacts OK   |
 | Milestone directories    | FAIL   | 2 flat files need restructuring  |
+| Milestone naming         | FAIL   | 2 version-prefixed dirs need migration |
 | Phase archival           | FAIL   | 8 orphaned phase directories     |
 | Knowledge files          | FAIL   | Directory missing                |
 | Phase summaries          | FAIL   | 2 milestones missing summaries   |
 | PLAN cleanup             | FAIL   | 9 leftover PLAN.md files         |
+| CLI wrappers             | FAIL   | ms-tools not on PATH             |
 ```
 
 Populate Result and Details from scan output. Use concise detail summaries.
@@ -109,210 +115,22 @@ If "Skip" → go to `report`.
 
 If "Review each" → use AskUserQuestion for each failed check with its details and options: "Fix" / "Skip". Only run fixes for accepted checks.
 
-Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_phase_archival → fix_plan_cleanup → fix_knowledge. Skip any fix whose check passed or was skipped by user.
-</step>
-
-<step name="fix_subsystems">
-**Only if Subsystem Vocabulary failed.**
-
-If subsystems array is empty (State A):
-
-1. Scan all artifacts for existing values:
-
-```bash
-~/.claude/mindsystem/scripts/scan-artifact-subsystems.sh --values-only
-```
-
-2. Read `.planning/PROJECT.md` and `.planning/ROADMAP.md`.
-
-3. Derive 5-12 canonical subsystem identifiers from:
-   - Unique values found in artifacts
-   - Project domain from PROJECT.md
-   - Phase structure from ROADMAP.md
-
-   Rules:
-   - Lowercase, single-word or hyphenated (e.g., "auth", "real-time", "ui")
-   - Merge synonyms into one canonical value (pick shortest/most common)
-   - Cover all existing usage plus obvious gaps
-   - Include infrastructure-level subsystems if relevant (api, database, infra, testing)
-
-4. Present the proposed list with merge mappings (e.g., "authentication" -> "auth").
-
-5. Use AskUserQuestion:
-   - header: "Subsystems"
-   - question: "These subsystems were derived from your project. Look good?"
-   - options:
-     - "Looks good" — accept and apply
-     - "Add/remove some" — iterate on the list
-     - "Start over" — re-derive from scratch
-
-6. After confirmation: update `config.json` (subsystems as first field), standardize existing artifact `subsystem:` fields using Edit tool.
-
-If subsystems exist but artifacts have mismatches (State B):
-
-1. Classify each artifact as OK/MISMATCH/MISSING.
-2. For MISMATCH: propose closest canonical value.
-3. For MISSING: propose based on artifact content/path.
-4. Apply fixes using Edit tool.
-
-Commit:
-
-```bash
-git add .planning/config.json
-git add .planning/phases/*/*-SUMMARY.md 2>/dev/null
-git add .planning/adhoc/*-SUMMARY.md 2>/dev/null
-git add .planning/debug/*.md 2>/dev/null
-git add .planning/debug/resolved/*.md 2>/dev/null
-git add .planning/todos/pending/*.md 2>/dev/null
-git add .planning/todos/done/*.md 2>/dev/null
-```
-
-```bash
-git commit -m "$(cat <<'EOF'
-chore(doctor): fix subsystem vocabulary
-
-Standardized subsystem configuration and artifact values.
-EOF
-)"
-```
-</step>
-
-<step name="fix_milestone_dirs">
-**Only if Milestone Directory Structure failed.**
-
-For each flat file like `milestones/v0.1-ROADMAP.md`:
-
-1. Extract version prefix (e.g., `v0.1`).
-2. Create versioned directory if it doesn't exist: `mkdir -p .planning/milestones/v0.1`
-3. `git mv` the file, stripping the version prefix from the filename:
-   `git mv .planning/milestones/v0.1-ROADMAP.md .planning/milestones/v0.1/ROADMAP.md`
-
-Commit:
-
-```bash
-git add .planning/milestones/
-```
-
-```bash
-git commit -m "$(cat <<'EOF'
-chore(doctor): restructure milestone directories
-
-Moved flat milestone files into versioned directories.
-EOF
-)"
-```
-</step>
-
-<step name="fix_phase_archival">
-**Only if Phase Archival failed.**
-
-Parse MILESTONES.md for completed milestones and their phase ranges (`**Phases completed:** X-Y`).
-
-For each completed milestone with orphaned phases in `.planning/phases/`:
-
-1. Determine the version and phase range from MILESTONES.md.
-2. Ensure the milestone directory exists: `mkdir -p .planning/milestones/{version}`
-3. Run the archive script:
-
-```bash
-~/.claude/mindsystem/scripts/archive-milestone-phases.sh <start> <end> <version>
-```
-
-This simultaneously:
-- Consolidates PHASE-SUMMARIES.md (fixes Phase Summaries check)
-- Deletes raw artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION)
-- Moves phase directories to milestone archive
+Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_knowledge. Skip any fix whose check passed or was skipped by user.
 
-**If MILESTONES.md doesn't have parseable phase ranges:** Use AskUserQuestion to ask the user for the phase range for each milestone.
-
-After archive completes, clean up leftover PLAN files in archived phases (fixes PLAN Cleanup check):
-
-```bash
-find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
-```
-
-Commit:
-
-```bash
-git add .planning/phases/ .planning/milestones/
-```
-
-```bash
-git commit -m "$(cat <<'EOF'
-chore(doctor): archive completed milestone phases
-
-Consolidated summaries, deleted raw artifacts, moved phase directories.
-EOF
-)"
-```
+Phase summaries are resolved by fix_phase_archival. CLI wrappers require manual PATH configuration (no automated fix).
 </step>
 
-<step name="fix_plan_cleanup">
-**Only if PLAN Cleanup failed AND fix_phase_archival did not already handle it.**
-
-Delete leftover PLAN files in completed phase directories:
-
-```bash
-find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
-```
-
-For any leftover PLANs in `phases/` belonging to completed milestones (identified by the scan), delete those too.
-
-Commit:
-
-```bash
-git add .planning/
-```
-
-```bash
-git commit -m "$(cat <<'EOF'
-chore(doctor): clean up leftover PLAN files
-
-Removed PLAN files from completed phase directories.
-EOF
-)"
-```
-</step>
-
-<step name="fix_knowledge">
-**Only if Knowledge Files failed.**
-
-Spawn a `general-purpose` subagent (Task tool) to generate knowledge files retroactively. Provide the subagent with:
-
-- Subsystem vocabulary from config.json
-- Instructions to read all PHASE-SUMMARIES.md from `milestones/*/PHASE-SUMMARIES.md` AND any remaining SUMMARY files in `phases/`
-- The knowledge template at `~/.claude/mindsystem/templates/knowledge.md`
-- Instructions to read any existing knowledge files and merge (rewrite semantics — current state, not append)
-- Instructions to create `.planning/knowledge/` directory if missing
-- Instructions to write `.planning/knowledge/{subsystem}.md` for each missing subsystem
-
-After subagent completes, verify files exist:
-
-```bash
-ls .planning/knowledge/*.md
-```
-
-Commit:
-
-```bash
-git add .planning/knowledge/
-```
-
-```bash
-git commit -m "$(cat <<'EOF'
-chore(doctor): generate knowledge files
-
-Created per-subsystem knowledge files from phase summaries.
-EOF
-)"
-```
+<step name="apply_fixes">
+Execute fix steps from doctor-fixes workflow in dependency order. For "Fix all": run all
+applicable steps. For "Review each": run only user-accepted steps. Skip any step whose
+check passed.
 </step>
 
 <step name="verify">
 Re-run the diagnostic scan:
 
 ```bash
-~/.claude/mindsystem/scripts/doctor-scan.sh
+ms-tools doctor-scan
 ```
 
 All checks should now PASS. If any still fail, report which checks remain and why.
@@ -328,10 +146,12 @@ Final summary table:
 |--------------------------|--------|----------------------------------|
 | Subsystem vocabulary     | PASS   | ...                              |
 | Milestone directories    | PASS   | ...                              |
+| Milestone naming         | PASS   | ...                              |
 | Phase archival           | PASS   | ...                              |
 | Knowledge files          | PASS   | ...                              |
 | Phase summaries          | PASS   | ...                              |
 | PLAN cleanup             | PASS   | ...                              |
+| CLI wrappers             | PASS   | ...                              |
 
 All checks passed.
 ```
@@ -342,11 +162,11 @@ Include counts: checks total, passed, fixed during this run.
 </process>
 
 <success_criteria>
-- [ ] Each fix group committed atomically
-- [ ] Re-scan verifies all checks pass after fixes
 - [ ] User confirms fix strategy before changes (Fix all / Review each / Skip)
-- [ ] Fixes applied in dependency order: subsystems → dirs → archival → cleanup → knowledge
 - [ ] Results displayed as markdown table before any action
-- [ ] All 6 categories reported with PASS/FAIL/SKIP
+- [ ] Re-scan verifies all checks pass after fixes
+- [ ] Each fix group committed atomically
+- [ ] Fixes applied in dependency order: subsystems → dirs → milestone naming → archival → cleanup → knowledge
+- [ ] All 8 categories reported with PASS/FAIL/SKIP
 - [ ] Clean project reports all PASS with no fix prompts
 </success_criteria>

package/commands/ms/execute-phase.md

@@ -30,10 +30,9 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 <context>
 Phase: $ARGUMENTS
 
-**Normalize phase number:**
+**Resolve phase:**
 ```bash
-PHASE_ARG="$ARGUMENTS"
-PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
+ms-tools find-phase "$ARGUMENTS"
 ```
 
 @.planning/ROADMAP.md
@@ -53,7 +52,7 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
    - Build list of incomplete plans
 
 3. **Validate and read execution order**
-   - Run `validate-execution-order.sh` on phase directory
+   - Run `ms-tools validate-execution-order` on phase directory
    - Parse EXECUTION-ORDER.md wave structure
    - Report wave structure to user
 
@@ -62,7 +61,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
+   - Run `ms-tools update-state` to update plan progress
    - Proceed to next wave
 
 5. **Aggregate results**
@@ -85,7 +84,7 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
    - If changes made: commit as `refactor({phase}): code review improvements`
 
 8. **Generate phase patch**
-   - Run: `~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER}`
+   - Run: `ms-tools generate-phase-patch ${PHASE_NUMBER}`
    - Outputs to `.planning/phases/{phase_dir}/{phase}-changes.patch`
    - Verify: patch file exists OR skip message logged
    - Note: Patch captures all changes including simplifications
@@ -127,7 +126,19 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
 <offer_next>
 **MANDATORY: Present copy/paste-ready next command.**
 
-After verification completes, route based on status:
+After verification completes:
+
+**First, surface user actions from all SUMMARYs:**
+
+Extract `## User Actions Required` sections from all `*-SUMMARY.md` files in the phase directory. If any contain actions (not "None"), present before route-specific content:
+
+```
+## ⚠ Action Required
+
+{Consolidated list from all SUMMARYs — deduplicate if overlapping}
+```
+
+Then route based on status:
 
 | Status | Route |
 |--------|-------|