mindsystem-cc 3.14.0 → 3.16.0

package/agents/ms-verifier.md

@@ -112,6 +112,8 @@ If no `## Must-Haves` section found in plans, derive using goal-backward process
 
    - List 3-7 observable behaviors from user perspective
    - Each truth should be testable by a human using the app
+   - Good: "User can see existing messages in the chat" (observable, testable)
+   - Bad: "Chat component works correctly" (vague, untestable)
 
 3. **Derive artifacts:** For each truth, ask "What must EXIST?"
 
@@ -150,109 +152,26 @@ For each required artifact, verify three levels:
 
 ### Level 1: Existence
 
-```bash
-check_exists() {
-  local path="$1"
-  if [ -f "$path" ]; then
-    echo "EXISTS"
-  elif [ -d "$path" ]; then
-    echo "EXISTS (directory)"
-  else
-    echo "MISSING"
-  fi
-}
-```
-
-If MISSING → artifact fails, record and continue.
+Check the file or directory exists. If MISSING → artifact fails, record and continue.
 
 ### Level 2: Substantive
 
-Check that the file has real implementation, not a stub.
-
-**Line count check:**
-
-```bash
-check_length() {
-  local path="$1"
-  local min_lines="$2"
-  local lines=$(wc -l < "$path" 2>/dev/null || echo 0)
-  [ "$lines" -ge "$min_lines" ] && echo "SUBSTANTIVE ($lines lines)" || echo "THIN ($lines lines)"
-}
-```
-
-Minimum lines by type:
-
-- Component: 15+ lines
-- API route: 10+ lines
-- Hook/util: 10+ lines
-- Schema model: 5+ lines
-
-**Stub pattern check:**
-
-```bash
-check_stubs() {
-  local path="$1"
-
-  # Universal stub patterns
-  local stubs=$(grep -c -E "TODO|FIXME|placeholder|not implemented|coming soon" "$path" 2>/dev/null || echo 0)
-
-  # Empty returns
-  local empty=$(grep -c -E "return null|return undefined|return \{\}|return \[\]" "$path" 2>/dev/null || echo 0)
-
-  # Placeholder content
-  local placeholder=$(grep -c -E "will be here|placeholder|lorem ipsum" "$path" 2>/dev/null || echo 0)
-
-  local total=$((stubs + empty + placeholder))
-  [ "$total" -gt 0 ] && echo "STUB_PATTERNS ($total found)" || echo "NO_STUBS"
-}
-```
-
-**Export check (for components/hooks):**
+Verify the file has real implementation, not a stub:
 
-```bash
-check_exports() {
-  local path="$1"
-  grep -E "^export (default )?(function|const|class)" "$path" && echo "HAS_EXPORTS" || echo "NO_EXPORTS"
-}
-```
-
-**Combine level 2 results:**
+1. **Adequate length** for its type — component: 15+ lines, route: 10+, hook/util: 10+, schema: 5+
+2. **No stub patterns** — grep for: `TODO`, `FIXME`, `placeholder`, `not implemented`, `coming soon`, `return null`, `return undefined`, `return {}`, `return []`, `lorem ipsum`
+3. **Has exports** — the file exports its primary functionality
 
-- SUBSTANTIVE: Adequate length + no stubs + has exports
-- STUB: Too short OR has stub patterns OR no exports
-- PARTIAL: Mixed signals (length OK but has some stubs)
+**Status:** SUBSTANTIVE (all pass), STUB (too short OR stub patterns OR no exports), PARTIAL (mixed signals)
 
 ### Level 3: Wired
 
-Check that the artifact is connected to the system.
-
-**Import check (is it used?):**
-
-```bash
-check_imported() {
-  local artifact_name="$1"
-  local search_path="${2:-src/}"
-  local imports=$(grep -r "import.*$artifact_name" "$search_path" --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l)
-  [ "$imports" -gt 0 ] && echo "IMPORTED ($imports times)" || echo "NOT_IMPORTED"
-}
-```
-
-**Usage check (is it called?):**
-
-```bash
-check_used() {
-  local artifact_name="$1"
-  local search_path="${2:-src/}"
-  local uses=$(grep -r "$artifact_name" "$search_path" --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "import" | wc -l)
-  [ "$uses" -gt 0 ] && echo "USED ($uses times)" || echo "NOT_USED"
-}
-```
+Verify the artifact is connected to the system. Adapt grep patterns to the project's tech stack (file extensions, import syntax, module system):
 
-**Combine level 3 results:**
+1. **Imported** — other files reference/import the artifact
+2. **Used** — the artifact is called/rendered/instantiated (not just imported)
 
-- WIRED: Imported AND used
-- ORPHANED: Exists but not imported/used
-- PARTIAL: Imported but not used (or vice versa)
+**Status:** WIRED (imported AND used), ORPHANED (exists but not imported/used), PARTIAL (imported but not used or vice versa)
 
 ### Final artifact status
 
@@ -265,112 +184,21 @@ check_used() {
 
 ## Step 5: Verify Key Links (Wiring)
 
-Key links are critical connections. If broken, the goal fails even with all artifacts present.
-
-### Pattern: Component → API
+Key links are critical connections. If broken, the goal fails even with all artifacts present. This is where 80% of stubs hide — the pieces exist but aren't connected.
 
-```bash
-verify_component_api_link() {
-  local component="$1"
-  local api_path="$2"
-
-  # Check for fetch/axios call to the API
-  local has_call=$(grep -E "fetch\(['\"].*$api_path|axios\.(get|post).*$api_path" "$component" 2>/dev/null)
-
-  if [ -n "$has_call" ]; then
-    # Check if response is used
-    local uses_response=$(grep -A 5 "fetch\|axios" "$component" | grep -E "await|\.then|setData|setState" 2>/dev/null)
-
-    if [ -n "$uses_response" ]; then
-      echo "WIRED: $component → $api_path (call + response handling)"
-    else
-      echo "PARTIAL: $component → $api_path (call exists but response not used)"
-    fi
-  else
-    echo "NOT_WIRED: $component → $api_path (no call found)"
-  fi
-}
-```
-
-### Pattern: API → Database
-
-```bash
-verify_api_db_link() {
-  local route="$1"
-  local model="$2"
-
-  # Check for Prisma/DB call
-  local has_query=$(grep -E "prisma\.$model|db\.$model|$model\.(find|create|update|delete)" "$route" 2>/dev/null)
-
-  if [ -n "$has_query" ]; then
-    # Check if result is returned
-    local returns_result=$(grep -E "return.*json.*\w+|res\.json\(\w+" "$route" 2>/dev/null)
-
-    if [ -n "$returns_result" ]; then
-      echo "WIRED: $route → database ($model)"
-    else
-      echo "PARTIAL: $route → database (query exists but result not returned)"
-    fi
-  else
-    echo "NOT_WIRED: $route → database (no query for $model)"
-  fi
-}
-```
+Identify the project's tech stack from file extensions and project structure. For each key link, verify the connection using grep patterns appropriate to the technology.
 
-### Pattern: Form → Handler
+**Common link types to check:**
 
-```bash
-verify_form_handler_link() {
-  local component="$1"
-
-  # Find onSubmit handler
-  local has_handler=$(grep -E "onSubmit=\{|handleSubmit" "$component" 2>/dev/null)
-
-  if [ -n "$has_handler" ]; then
-    # Check if handler has real implementation
-    local handler_content=$(grep -A 10 "onSubmit.*=" "$component" | grep -E "fetch|axios|mutate|dispatch" 2>/dev/null)
-
-    if [ -n "$handler_content" ]; then
-      echo "WIRED: form → handler (has API call)"
-    else
-      # Check for stub patterns
-      local is_stub=$(grep -A 5 "onSubmit" "$component" | grep -E "console\.log|preventDefault\(\)$|\{\}" 2>/dev/null)
-      if [ -n "$is_stub" ]; then
-        echo "STUB: form → handler (only logs or empty)"
-      else
-        echo "PARTIAL: form → handler (exists but unclear implementation)"
-      fi
-    fi
-  else
-    echo "NOT_WIRED: form → handler (no onSubmit found)"
-  fi
-}
-```
+- **UI → Data source:** Component/widget fetches or subscribes to data. Verify the call exists AND the response is used (not just fired and ignored).
+- **Data layer → Backend/DB:** API route or repository queries the database. Verify the query result is returned/used (not a static placeholder).
+- **User action → Handler:** Form/button has a handler with real implementation. Red flag: handler only logs, only prevents default, or is an empty closure.
+- **State → Display:** State variable or model is declared AND rendered/displayed (not just stored).
 
-### Pattern: State → Render
+**For each link, verify two things:**
 
-```bash
-verify_state_render_link() {
-  local component="$1"
-  local state_var="$2"
-
-  # Check if state variable exists
-  local has_state=$(grep -E "useState.*$state_var|\[$state_var," "$component" 2>/dev/null)
-
-  if [ -n "$has_state" ]; then
-    # Check if state is used in JSX
-    local renders_state=$(grep -E "\{.*$state_var.*\}|\{$state_var\." "$component" 2>/dev/null)
-
-    if [ -n "$renders_state" ]; then
-      echo "WIRED: state → render ($state_var displayed)"
-    else
-      echo "NOT_WIRED: state → render ($state_var exists but not displayed)"
-    fi
-  else
-    echo "N/A: state → render (no state var $state_var)"
-  fi
-}
-```
+1. **Connection exists** — grep confirms the call/import/reference
+2. **Connection is functional** — the result is consumed, not ignored. A fetch with no await, a query whose result isn't returned, or a handler that only logs are all PARTIAL, not WIRED.
 
 ## Step 6: Check Requirements Coverage
 
@@ -394,36 +222,14 @@ For each requirement:
 
 ## Step 7: Scan for Anti-Patterns
 
-Identify files modified in this phase:
+Identify files modified in this phase from PLAN.md `**Files:**` lines or git history — do NOT rely on SUMMARY.md for file lists.
 
 ```bash
-# Extract files from SUMMARY.md
-grep -E "^\- \`" "$PHASE_DIR"/*-SUMMARY.md | sed 's/.*`\([^`]*\)`.*/\1/' | sort -u
+# Extract files from PLAN.md (trustworthy source)
+grep "^\*\*Files:\*\*" "$PHASE_DIR"/*-PLAN.md | sed 's/.*`\([^`]*\)`.*/\1/' | sort -u
 ```
 
-Run anti-pattern detection:
-
-```bash
-scan_antipatterns() {
-  local files="$@"
-
-  for file in $files; do
-    [ -f "$file" ] || continue
-
-    # TODO/FIXME comments
-    grep -n -E "TODO|FIXME|XXX|HACK" "$file" 2>/dev/null
-
-    # Placeholder content
-    grep -n -E "placeholder|coming soon|will be here" "$file" -i 2>/dev/null
-
-    # Empty implementations
-    grep -n -E "return null|return \{\}|return \[\]|=> \{\}" "$file" 2>/dev/null
-
-    # Console.log only implementations
-    grep -n -B 2 -A 2 "console\.log" "$file" 2>/dev/null | grep -E "^\s*(const|function|=>)"
-  done
-}
-```
+Scan each file for anti-patterns: `TODO/FIXME/XXX/HACK` comments, placeholder content (`coming soon`, `will be here`), empty implementations (`return null`, `return {}`, `=> {}`), console.log-only handlers.
 
 Categorize findings:
 
@@ -689,95 +495,13 @@ Automated checks passed. Awaiting human verification.
 
 </critical_rules>
 
-<stub_detection_patterns>
-
-## Universal Stub Patterns
-
-```bash
-# Comment-based stubs
-grep -E "(TODO|FIXME|XXX|HACK|PLACEHOLDER)" "$file"
-grep -E "implement|add later|coming soon|will be" "$file" -i
-
-# Placeholder text in output
-grep -E "placeholder|lorem ipsum|coming soon|under construction" "$file" -i
-
-# Empty or trivial implementations
-grep -E "return null|return undefined|return \{\}|return \[\]" "$file"
-grep -E "console\.(log|warn|error).*only" "$file"
-
-# Hardcoded values where dynamic expected
-grep -E "id.*=.*['\"].*['\"]" "$file"
-```
-
-## React Component Stubs
-
-```javascript
-// RED FLAGS:
-return <div>Component</div>
-return <div>Placeholder</div>
-return <div>{/* TODO */}</div>
-return null
-return <></>
-
-// Empty handlers:
-onClick={() => {}}
-onChange={() => console.log('clicked')}
-onSubmit={(e) => e.preventDefault()}  // Only prevents default
-```
-
-## API Route Stubs
-
-```typescript
-// RED FLAGS:
-export async function POST() {
-  return Response.json({ message: "Not implemented" });
-}
-
-export async function GET() {
-  return Response.json([]); // Empty array with no DB query
-}
-
-// Console log only:
-export async function POST(req) {
-  console.log(await req.json());
-  return Response.json({ ok: true });
-}
-```
-
-## Wiring Red Flags
-
-```typescript
-// Fetch exists but response ignored:
-fetch('/api/messages')  // No await, no .then, no assignment
-
-// Query exists but result not returned:
-await prisma.message.findMany()
-return Response.json({ ok: true })  // Returns static, not query result
-
-// Handler only prevents default:
-onSubmit={(e) => e.preventDefault()}
-
-// State exists but not rendered:
-const [messages, setMessages] = useState([])
-return <div>No messages</div>  // Always shows "no messages"
-```
-
-</stub_detection_patterns>
-
 <success_criteria>
 
-- [ ] Previous VERIFICATION.md checked (Step 0)
-- [ ] If re-verification: must-haves loaded from previous, focus on failed items
-- [ ] 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
-- [ ] Requirements coverage assessed (if applicable)
-- [ ] Anti-patterns scanned and categorized
-- [ ] Human verification items identified
-- [ ] Overall status determined
-- [ ] Gaps structured in YAML frontmatter (if gaps_found)
-- [ ] Re-verification metadata included (if previous existed)
-- [ ] VERIFICATION.md created with complete report
-- [ ] Results returned to orchestrator (NOT committed)
+- [ ] Gaps structured in YAML frontmatter (if gaps_found) — planner depends on this
+- [ ] Key links verified — not just artifact existence; this is where stubs hide
+- [ ] Artifacts checked at all three levels (exists → substantive → wired)
+- [ ] SUMMARY.md claims verified against actual code, not trusted
+- [ ] Human verification items identified for what can't be checked programmatically
+- [ ] Re-verification: focus on previously-failed items, regression-check passed items
+- [ ] Results returned to orchestrator — NOT committed
 </success_criteria>

package/agents/ms-verify-fixer.md

@@ -1,6 +1,7 @@
 ---
 name: ms-verify-fixer
 description: Investigates and fixes single UAT issues. Spawned by verify-work when lightweight investigation fails.
+model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: orange
 ---

package/commands/ms/check-phase.md

@@ -10,11 +10,11 @@ allowed-tools:
   - Task
 ---
 
-<purpose>
+<objective>
 On-demand plan verification. Use when a plan seems large or complex and you want a structured review before executing.
 
 This spawns ms-plan-checker to analyze your PLAN.md files against the phase goal.
-</purpose>
+</objective>
 
 <what_it_checks>
 1. **Requirement Coverage** — Does every phase requirement have tasks addressing it?
@@ -48,23 +48,6 @@ ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 If no PLAN.md files found, remind user to run `/ms:plan-phase` first.
 </step>
 
-<step name="load_context">
-Read the phase goal from ROADMAP.md:
-
-```bash
-grep -A 15 "Phase ${PHASE}:" .planning/ROADMAP.md | head -20
-```
-
-Count plans and tasks:
-
-```bash
-for plan in "$PHASE_DIR"/*-PLAN.md; do
-  echo "=== $(basename $plan) ==="
-  grep -c "^### " "$plan" 2>/dev/null || echo "0 changes"
-done
-```
-</step>
-
 <step name="spawn_checker">
 Spawn the plan checker agent:
 
@@ -93,57 +76,37 @@ Present the checker's findings clearly.
 **Format for VERIFICATION PASSED:**
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN VERIFICATION: PASSED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Phase: [name]
-Plans: [count]
-Tasks: [total count]
-
-All checks passed:
-✓ Requirement coverage complete
-✓ All tasks have required fields
-✓ Dependency graph valid
-✓ Key links planned
-✓ Scope within budget
-✓ Verification criteria derived
-✓ Context compliance verified (if CONTEXT.md exists)
-
-Ready to execute: /ms:execute-phase $ARGUMENTS
+## Plan Verification: PASSED
+
+Phase: [name] | Plans: [count] | Tasks: [total count]
+
+All checks passed.
+
+Ready to execute: `/ms:execute-phase $ARGUMENTS`
 ```
 
 **Format for ISSUES FOUND:**
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN VERIFICATION: ISSUES FOUND
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Phase: [name]
-Plans: [count]
-Issues: [X blockers, Y warnings]
+## Plan Verification: ISSUES FOUND
 
-BLOCKERS (must fix):
+Phase: [name] | Plans: [count] | Issues: [X blockers, Y warnings]
 
-1. [dimension] [description]
-   Plan: [which plan]
-   Fix: [specific fix hint]
+### Blockers (must fix)
 
-2. [dimension] [description]
-   Plan: [which plan]
-   Fix: [specific fix hint]
+1. **[dimension]** [description]
+   Plan: [which plan] | Fix: [specific fix hint]
 
-WARNINGS (should fix):
+### Warnings (should fix)
 
-1. [dimension] [description]
+1. **[dimension]** [description]
    Fix: [hint]
 
 ---
 
 Options:
-- Fix the issues and run /ms:check-phase $ARGUMENTS again
-- Proceed anyway: /ms:execute-phase $ARGUMENTS (not recommended if blockers exist)
+- Fix the issues and run `/ms:check-phase $ARGUMENTS` again
+- Proceed anyway: `/ms:execute-phase $ARGUMENTS` (not recommended if blockers exist)
 ```
 </step>
 
@@ -163,3 +126,9 @@ Options:
 /ms:execute-phase 5   # Execute
 ```
 </examples>
+
+<success_criteria>
+- Blockers and warnings presented distinctly — blockers have plan name and fix hint
+- Output includes actionable next command (`/ms:execute-phase` or `/ms:check-phase` rerun)
+- Checker agent spawned with correct phase directory path
+</success_criteria>

package/commands/ms/complete-milestone.md

@@ -68,31 +68,14 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
    - Present milestone scope and stats
    - Wait for confirmation
 
-1.5. **Consolidate decisions:**
+1.5. **Clean up raw artifacts:**
 
-   Spawn ms-consolidator to extract decisions from phase artifacts:
+   Delete remaining raw artifacts from phase directories. Knowledge files are already current from phase-level consolidation in execute-phase.
 
-   ```
-   Task(
-     prompt="Consolidate decisions from milestone v{{version}}.
-     Phase range: [PHASE_START]-[PHASE_END]
-     Create v{{version}}-DECISIONS.md.
-     Delete source files (PLAN, CONTEXT, RESEARCH, DESIGN).",
-     subagent_type="ms-consolidator"
-   )
-   ```
-
-   Wait for completion. Verify DECISIONS.md created:
    ```bash
-   ls .planning/milestones/v{{version}}-DECISIONS.md
+   ~/.claude/mindsystem/scripts/cleanup-phase-artifacts.sh $PHASE_START $PHASE_END
    ```
 
-1.7. **Extract learnings:**
-
-   Scan debug resolutions, adhoc summaries, phase summaries, and completed todos.
-   Curate 4-8 reusable patterns into `.planning/LEARNINGS.md` (or skip gracefully if none found).
-   See workflow `extract_learnings` step for full process.
-
 2. **Gather stats:**
 
    - Count phases, plans, tasks
@@ -128,7 +111,7 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 
 7. **Commit and tag:**
 
-   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, LEARNINGS.md, archive files
+   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
    - Commit: `chore: archive v{{version}} milestone`
    - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
    - Ask about pushing tag
@@ -144,9 +127,7 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 
 <success_criteria>
 
-- Decisions consolidated to `.planning/milestones/v{{version}}-DECISIONS.md`
-- Phase artifacts cleaned (PLAN, CONTEXT, RESEARCH, DESIGN deleted)
-- Learnings extracted to `.planning/LEARNINGS.md` (or gracefully skipped if none found)
+- Raw artifacts cleaned from phase directories (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
 - Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
 - Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
 - `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
@@ -162,7 +143,7 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 - **Load workflow first:** Read complete-milestone.md before executing
 - **Verify completion:** All phases must have SUMMARY.md files
 - **User confirmation:** Wait for approval at verification gates
-- **Archive before deleting:** Always create archive files before updating/deleting originals
+- **Archive before deleting:** Always create archive files (ROADMAP, REQUIREMENTS) 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:create-roadmap`, not reusing old file

package/commands/ms/create-roadmap.md

@@ -13,25 +13,15 @@ allowed-tools:
 <objective>
 Define project requirements and create roadmap with phase breakdown.
 
-Derives REQUIREMENTS.md from MILESTONE-CONTEXT.md (or through lightweight questioning for first milestones), then maps requirements to phases.
-
 Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-project`.
-
-**How it works:** Spawns ms-roadmapper agent which derives requirements AND creates roadmap in one pass, then presents combined results for approval.
 </objective>
 
 <execution_context>
-@~/.claude/mindsystem/references/principles.md
-@~/.claude/mindsystem/workflows/define-requirements.md
-@~/.claude/mindsystem/templates/requirements.md
-@~/.claude/mindsystem/templates/roadmap.md
 @~/.claude/mindsystem/templates/state.md
-@~/.claude/mindsystem/references/goal-backward.md
 </execution_context>
 
 <context>
 @.planning/PROJECT.md
-@.planning/config.json
 @.planning/MILESTONE-CONTEXT.md (if exists)
 @.planning/research/FEATURES.md (if exists)
 @.planning/research/SUMMARY.md (if exists)
@@ -342,13 +332,11 @@ Update `.planning/STATE.md` Last Command field:
 </process>
 
 <success_criteria>
-- [ ] PROJECT.md validated
-- [ ] Context gathered (from MILESTONE-CONTEXT.md, research, or questioning)
-- [ ] ms-roadmapper spawned with context
-- [ ] REQUIREMENTS.md created with REQ-IDs and scope classification
 - [ ] All v1 requirements mapped to phases (no orphans)
 - [ ] Success criteria derived for each phase (2-5 observable behaviors)
-- [ ] Requirements and roadmap presented to user for approval
 - [ ] User feedback incorporated (if any)
+- [ ] Requirements and roadmap presented to user for approval
+- [ ] ms-roadmapper spawned with full planning context
+- [ ] REQUIREMENTS.md created with REQ-IDs and scope classification
 - [ ] REQUIREMENTS.md, ROADMAP.md, STATE.md committed after approval
 </success_criteria>

package/commands/ms/design-phase.md

@@ -107,6 +107,23 @@ If exists, extract:
 - What Must Be Nailed (essentials)
 - Specific Ideas (references to products)
 
+**3b2. Optional context — prior knowledge:**
+
+Match subsystem(s) to this phase by comparing ROADMAP phase description against subsystem names in config.json. Load matching knowledge files:
+
+```bash
+jq -r '.subsystems[]' .planning/config.json 2>/dev/null
+cat .planning/knowledge/{matched_subsystem}.md 2>/dev/null
+```
+
+If knowledge files exist, extract:
+- Architecture patterns (tech constraints the design must respect)
+- Prior design patterns (visual consistency)
+- Key decisions (constraints)
+- Pitfalls (design must avoid known traps)
+
+Pass the extracted knowledge to ms-designer in the design prompt (see step 5 `<prior_knowledge>` block).
+
 **3c. Optional context — project UI skill:**
 
 Scan the skills list in the most recent system-reminder for a skill whose description mentions UI patterns, components, design system, or implementation styling (e.g., "Flutter/Dart patterns", "React component library", "UI implementation patterns").
@@ -238,6 +255,23 @@ Vision inferred from phase requirements and PROJECT.md context.
 Reference products: [From Q&A if asked, or "None specified"]
 </user_vision>
 
+<prior_knowledge>
+[If knowledge files exist:]
+
+Architecture constraints:
+[From knowledge Architecture sections]
+
+Prior design patterns:
+[From knowledge Design sections]
+
+Pitfalls to avoid:
+[From knowledge Pitfalls sections]
+
+[If no knowledge files exist:]
+
+No prior knowledge files. First phase or no prior execution.
+</prior_knowledge>
+
 <existing_aesthetic>
 [If project UI skill exists:]