mindsystem-cc 3.18.1 → 3.20.0

package/mindsystem/workflows/plan-phase.md

@@ -25,8 +25,8 @@ Decimal phases enable urgent work insertion without renumbering:
 Create executable phase prompts (PLAN.md files) optimized for parallel execution.
 
 **Two-stage workflow:**
-1. **Main context:** Task identification (steps 1-8) - collaborative, keeps user in loop
-2. **Subagent (ms-plan-writer):** Plan writing (dependency graph, wave assignment, PLAN.md files, risk scoring) - autonomous, heavy lifting
+1. **Main context:** Task identification + grouping proposal (steps 1-9) - collaborative, keeps user in loop
+2. **Subagent (ms-plan-writer):** Plan writing (structural validation, PLAN.md files, risk scoring) - autonomous, heavy lifting
 
 PLAN.md IS the prompt that Claude executes. Plans are grouped into execution waves based on dependencies - independent plans run in parallel, dependent plans wait for predecessors.
 </purpose>
@@ -280,7 +280,7 @@ PHASE_NAME=$(grep -A2 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null | head
 uv run ~/.claude/mindsystem/scripts/scan-planning-context.py \
   --phase "${PHASE}" \
   --phase-name "${PHASE_NAME}" \
-  ${SUBSYSTEM:+--subsystem "${SUBSYSTEM}"}
+  ${SUBSYSTEM:+--subsystem="${SUBSYSTEM}"}
 ```
 
 The scanner outputs formatted markdown with sections for patterns, learnings,
@@ -389,7 +389,9 @@ Standard tasks (remain in standard plans):
 → Yes: Mark as tdd_candidate=true
 → No: Standard task
 
-Read `~/.claude/mindsystem/references/tdd.md` now for TDD criteria and plan structure.
+**If any tasks were marked tdd_candidate=true:** Read `~/.claude/mindsystem/references/tdd.md` for TDD plan structure guidance.
+
+**If no TDD candidates:** Skip — the heuristic above is sufficient for detection.
 
 **Decisions:** If you identify a task that requires choosing between approaches (which auth provider, which database, etc.), use AskUserQuestion to resolve it now. Don't defer decisions to execution. For purely technical choices where the user hasn't expressed preference, make the decision and document it in the plan's objective.
 
@@ -419,6 +421,56 @@ Format: numbered list with task name, key files, dependency hint, and `[TDD]` fl
 </output_format>
 </step>
 
+<step name="propose_grouping">
+**Propose plan boundaries before handing off to the plan-writer.**
+
+After presenting the task list, analyze dependencies and propose how tasks should group into plans. This is a collaborative planning decision — the user sees it and can adjust.
+
+**Process:**
+1. Map task dependencies from needs/creates
+2. Identify independent task clusters (parallel candidates = Wave 1)
+3. Group by vertical feature affinity (not horizontal layers)
+4. Estimate context budget per group using weight heuristics (L ~5%, M ~10%, H ~20%)
+5. Target 25-45% per plan, bias toward fewer plans
+
+**Present to user:**
+
+```markdown
+### Proposed Plan Structure
+
+**Plan 01: {title}** (~{budget}%)
+Tasks: {task_ids} — {brief rationale}
+
+**Plan 02: {title}** (~{budget}%)
+Tasks: {task_ids} — {brief rationale}
+
+**Waves:** {wave structure}
+```
+
+The user may adjust, merge, or split plans. Once confirmed (or if the user proceeds without objection), pass the proposed grouping to the plan-writer.
+
+**TDD plans are always standalone** — propose them as dedicated plans regardless of budget.
+</step>
+
+<step name="discover_skills">
+**Identify relevant project skills for this phase.**
+
+After the user confirms the plan structure, check if project skills could improve plan quality.
+
+**Scan:** Review the skill list in your system-reminder. Match skills against:
+- The phase's technology stack (Flutter, React, Node.js, etc.)
+- The domain of the tasks identified (UI patterns, API design, state management, etc.)
+- Keywords from RESEARCH.md or CONTEXT.md if they exist
+
+**If matches found:** Present via AskUserQuestion:
+- List each matching skill with its description
+- Always include an escape hatch option for the user to name skills manually or skip entirely
+
+**If no matches:** Skip silently — no need to ask the user.
+
+**Store result:** Keep the confirmed skill names (may be empty) for the handoff step.
+</step>
+
 <step name="handoff_to_writer">
 **Spawn ms-plan-writer subagent with task list and context.**
 
@@ -433,6 +485,14 @@ Assemble handoff payload:
   {Construct full task XML from your analysis. Each task needs: id, name, type, needs, creates, tdd_candidate, action_hint, verify_hint, done_hint. Use the same XML schema the plan-writer expects.}
 </task_list>
 
+<proposed_grouping>
+  <plan id="01" title="{title}" budget="{estimated_%}" wave="{wave_number}">
+    <tasks>{comma-separated task IDs}</tasks>
+    <rationale>{why these tasks belong together}</rationale>
+  </plan>
+  <!-- More plans... -->
+</proposed_grouping>
+
 <phase_context>
   <phase_number>{PHASE}</phase_number>
   <phase_name>{PHASE_NAME}</phase_name>
@@ -461,6 +521,10 @@ Assemble handoff payload:
   {list of services detected in task breakdown}
 </external_services>
 
+<confirmed_skills>
+  {comma-separated skill names confirmed by user, or "none"}
+</confirmed_skills>
+
 <learnings>
   <!-- Flat list from read_project_history step 6. Omit if no matches found. -->
   <learning type="debug" source=".planning/debug/resolved/{slug}.md">{root_cause} — fix: {resolution}</learning>
@@ -482,10 +546,11 @@ Task(
 
 The subagent handles:
 - Building dependency graph from needs/creates
+- Validating proposed grouping (file conflicts, circular deps, missing dependency chains)
+- Applying proposed plan boundaries (deviates only for structural issues, not budget math)
 - Assigning wave numbers
-- Grouping tasks into plans (budget-based, ~45% cost target)
 - Deriving Must-Haves (goal-backward)
-- Estimating scope, splitting if needed
+- Estimating scope (informational, for grouping rationale)
 - Writing PLAN.md files + EXECUTION-ORDER.md
 - Git commit
 - Calculating risk score
@@ -543,24 +608,24 @@ Extract:
 **Skip tier (0-39):**
 - header: "Plan Verification"
 - question: "Risk Score: {score}/100 — Low risk\n\nPlans look straightforward. Verification optional."
-- Options: "Execute now" (first), "Verify anyway"
+- Options: "Skip verification" (first), "Verify plans"
 
 **Optional tier (40-69):**
 - header: "Plan Verification"
 - question: "Risk Score: {score}/100 — Moderate complexity\n\nTop factors:\n- {factor_1}\n- {factor_2}\n\nVerification recommended but optional."
-- Options: "Verify first" (first), "Execute now", "Review plans manually"
+- Options: "Verify plans" (first), "Skip verification", "Review plans manually"
 
 **Verify tier (70-100):**
 - header: "Plan Verification Recommended"
 - question: "Risk Score: {score}/100 — Higher complexity\n\nTop factors:\n- {factor_1}\n- {factor_2}\n- {factor_3}\n\nVerification strongly recommended."
-- Options: "Verify first (Recommended)" (first), "Execute anyway", "Review plans manually"
+- Options: "Verify plans (Recommended)" (first), "Skip verification", "Review plans manually"
 
 **Handle response:**
 
-**"Execute now" / "Execute anyway":**
+**"Skip verification":**
 Continue to offer_next.
 
-**"Verify first" / "Verify anyway":**
+**"Verify plans":**
 Spawn ms-plan-checker:
 
 ```
@@ -658,13 +723,10 @@ Tasks are instructions for Claude, not Jira tickets.
 - [ ] Mandatory discovery completed (Level 0-3)
 - [ ] Prior decisions, issues, concerns synthesized
 - [ ] Tasks identified with needs/creates dependencies
-- [ ] Task list handed off to ms-plan-writer
-- [ ] PLAN file(s) created with pure markdown format
-- [ ] EXECUTION-ORDER.md created with wave groups
-- [ ] Each plan: Must-Haves section with observable truths
-- [ ] Each plan: budget-based grouping (target 25-45%, consolidate under 10%)
-- [ ] Wave structure maximizes parallelism
-- [ ] PLAN file(s) committed to git
+- [ ] Plan grouping proposed and presented to user
+- [ ] Task list + proposed grouping + confirmed skills handed off to ms-plan-writer
+- [ ] PLAN files + EXECUTION-ORDER.md created (pure markdown, Must-Haves, follows proposed grouping)
+- [ ] Plans committed with maximized wave parallelism
 - [ ] Risk assessment presented (score + top factors)
 - [ ] User chose verify/skip (or verified if chosen)
 - [ ] User knows next steps and wave structure

package/mindsystem/workflows/transition.md

@@ -141,16 +141,17 @@ cat .planning/phases/XX-current/*-SUMMARY.md
 **Assess requirement changes:**
 
 1. **Requirements validated?**
-   - Any Active requirements shipped in this phase?
-   - Move to Validated with phase reference: `- ✓ [Requirement] — Phase X`
+   - Any requirements shipped in this phase?
+   - Add to Validated with phase reference: `- ✓ [Requirement] — Phase X`
 
 2. **Requirements invalidated?**
-   - Any Active requirements discovered to be unnecessary or wrong?
-   - Move to Out of Scope with reason: `- [Requirement] — [why invalidated]`
+   - Any requirements discovered to be unnecessary or wrong?
+   - Add to Out of Scope with reason: `- [Requirement] — [why invalidated]`
 
-3. **Requirements emerged?**
-   - Any new requirements discovered during building?
-   - Add to Active: `- [ ] [New requirement]`
+3. **Business context evolved?**
+   - Has understanding of audience, problem, or differentiation changed?
+   - Update Who It's For, Core Problem, or How It's Different if so
+   - New key flows emerged? → Update Key User Flows
 
 4. **Decisions to log?**
    - Extract decisions from SUMMARY.md files
@@ -174,13 +175,11 @@ Make the edits inline. Update "Last updated" footer:
 Before:
 
 ```markdown
-### Active
+## Validated
 
-- [ ] JWT authentication
-- [ ] Real-time sync < 500ms
-- [ ] Offline mode
+- ✓ Canvas drawing tools — Phase 1
 
-### Out of Scope
+## Out of Scope
 
 - OAuth2 — complexity not needed for v1
 ```
@@ -188,27 +187,23 @@ Before:
 After (Phase 2 shipped JWT auth, discovered rate limiting needed):
 
 ```markdown
-### Validated
+## Validated
 
+- ✓ Canvas drawing tools — Phase 1
 - ✓ JWT authentication — Phase 2
 
-### Active
-
-- [ ] Real-time sync < 500ms
-- [ ] Offline mode
-- [ ] Rate limiting on sync endpoint
-
-### Out of Scope
+## Out of Scope
 
 - OAuth2 — complexity not needed for v1
+- Offline mode — real-time is core value, discovered Phase 2
 ```
 
 **Step complete when:**
 
 - [ ] Phase summaries reviewed for learnings
-- [ ] Validated requirements moved from Active
-- [ ] Invalidated requirements moved to Out of Scope with reason
-- [ ] Emerged requirements added to Active
+- [ ] Shipped requirements added to Validated
+- [ ] Invalidated requirements added to Out of Scope with reason
+- [ ] Business context sections reviewed (Who It's For, Core Problem, How It's Different, Key User Flows)
 - [ ] New decisions logged with rationale
 - [ ] "What This Is" updated if product changed
 - [ ] "Last updated" footer reflects this transition

package/mindsystem/workflows/verify-phase.md

@@ -532,7 +532,7 @@ Group related gaps into fix plans:
 ```
 
 3. **Keep plans focused:**
-   - Budget-based grouping (weights within 45%)
+   - Budget-aware grouping (target 25-45% per plan)
    - Single concern per plan
    - Include verification task
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.18.1",
+  "version": "3.20.0",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/scripts/doctor-scan.sh

@@ -0,0 +1,402 @@
+#!/bin/bash
+#
+# doctor-scan.sh
+# Single-pass diagnostic scan of the .planning/ tree.
+# Reports on 6 health check categories with structured output.
+#
+# Usage: ./scripts/doctor-scan.sh
+#
+# Exit codes:
+#   0 — all checks pass
+#   1 — one or more checks failed
+#   2 — .planning/ or config.json missing (cannot scan)
+
+set -e
+
+# --- Find .planning from git root ---
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$GIT_ROOT" ]; then
+  echo "Error: Not in a git repository"
+  exit 2
+fi
+
+PLANNING="$GIT_ROOT/.planning"
+if [ ! -d "$PLANNING" ]; then
+  echo "Error: No .planning/ directory found"
+  exit 2
+fi
+
+CONFIG="$PLANNING/config.json"
+if [ ! -f "$CONFIG" ]; then
+  echo "Error: No config.json found at $CONFIG"
+  exit 2
+fi
+
+MILESTONES_FILE="$PLANNING/MILESTONES.md"
+PHASES_DIR="$PLANNING/phases"
+MILESTONES_DIR="$PLANNING/milestones"
+KNOWLEDGE_DIR="$PLANNING/knowledge"
+
+PASS_COUNT=0
+FAIL_COUNT=0
+SKIP_COUNT=0
+FAILED_CHECKS=""
+
+# --- Helper: record check result ---
+record_result() {
+  local status="$1"
+  local name="$2"
+  case "$status" in
+    PASS) PASS_COUNT=$((PASS_COUNT + 1)) ;;
+    FAIL) FAIL_COUNT=$((FAIL_COUNT + 1)); FAILED_CHECKS="$FAILED_CHECKS $name" ;;
+    SKIP) SKIP_COUNT=$((SKIP_COUNT + 1)) ;;
+  esac
+}
+
+# --- Helper: parse phase numbers from a "Phases completed" line ---
+# Outputs one phase number per line. Handles:
+#   - Range format: "1-6" → 1 2 3 4 5 6
+#   - Comma-separated: "8, 8.3, 9, 10" → 8 8.3 9 10
+#   - Mixed (multiple milestone entries each handled independently)
+parse_phase_numbers() {
+  local line="$1"
+  local range
+  range=$(echo "$line" | grep -o '[0-9]\+-[0-9]\+' || true)
+  if [ -n "$range" ]; then
+    local range_start range_end
+    range_start=$(echo "$range" | cut -d'-' -f1)
+    range_end=$(echo "$range" | cut -d'-' -f2)
+    seq "$range_start" "$range_end"
+  else
+    echo "$line" | sed 's/.*://' | grep -oE '[0-9]+(\.[0-9]+)?' || true
+  fi
+}
+
+# --- Helper: format phase number as zero-padded directory prefix ---
+# Integer (9) → "09", Decimal (8.3) → "08.3"
+format_phase_prefix() {
+  local phase="$1"
+  if echo "$phase" | grep -q '\.'; then
+    local int_part dec_part
+    int_part=$(echo "$phase" | cut -d'.' -f1)
+    dec_part=$(echo "$phase" | cut -d'.' -f2)
+    printf "%02d.%s" "$int_part" "$dec_part"
+  else
+    printf "%02d" "$phase"
+  fi
+}
+
+# ============================================================
+# CHECK 1: Subsystem Vocabulary
+# ============================================================
+echo "=== Subsystem Vocabulary ==="
+
+SUBSYSTEM_COUNT=$(jq -r '.subsystems // [] | length' "$CONFIG" 2>/dev/null || echo "0")
+
+if [ "$SUBSYSTEM_COUNT" -eq 0 ]; then
+  echo "Status: FAIL"
+  echo "No subsystems array in config.json (or empty)"
+  record_result "FAIL" "Subsystem Vocabulary"
+else
+  echo "Subsystems: $SUBSYSTEM_COUNT configured"
+  jq -r '.subsystems[]' "$CONFIG" 2>/dev/null | sed 's/^/  - /'
+
+  # Run artifact scan to check for mismatches
+  SCAN_SCRIPT="$(dirname "$0")/scan-artifact-subsystems.sh"
+  if [ -x "$SCAN_SCRIPT" ]; then
+    CANONICAL=$(jq -r '.subsystems[]' "$CONFIG" 2>/dev/null)
+    ARTIFACT_VALUES=$("$SCAN_SCRIPT" --values-only 2>/dev/null | grep -v '^===' | sort -u)
+    MISMATCHES=""
+    while IFS= read -r val; do
+      [ -z "$val" ] && continue
+      if ! echo "$CANONICAL" | grep -qx "$val"; then
+        MISMATCHES="$MISMATCHES $val"
+      fi
+    done <<< "$ARTIFACT_VALUES"
+
+    if [ -n "$MISMATCHES" ]; then
+      echo "Status: FAIL"
+      echo "Artifact values not in canonical list:$MISMATCHES"
+      record_result "FAIL" "Subsystem Vocabulary"
+    else
+      ARTIFACT_COUNT=$("$SCAN_SCRIPT" --values-only 2>/dev/null | grep -v '^===' | wc -l | tr -d ' ')
+      echo "Artifacts scanned: $ARTIFACT_COUNT (all OK)"
+      echo "Status: PASS"
+      record_result "PASS" "Subsystem Vocabulary"
+    fi
+  else
+    echo "Status: PASS"
+    echo "(scan-artifact-subsystems.sh not found — skipped artifact validation)"
+    record_result "PASS" "Subsystem Vocabulary"
+  fi
+fi
+echo ""
+
+# ============================================================
+# CHECK 2: Milestone Directory Structure
+# ============================================================
+echo "=== Milestone Directory Structure ==="
+
+if [ ! -d "$MILESTONES_DIR" ]; then
+  # No milestones directory at all — check if MILESTONES.md has entries
+  if [ -f "$MILESTONES_FILE" ] && grep -q "^## " "$MILESTONES_FILE" 2>/dev/null; then
+    echo "Status: FAIL"
+    echo "MILESTONES.md has entries but no milestones/ directory"
+    record_result "FAIL" "Milestone Directory Structure"
+  else
+    echo "Status: SKIP"
+    echo "No completed milestones"
+    record_result "SKIP" "Milestone Directory Structure"
+  fi
+else
+  # Look for flat files matching v*-*.md directly in milestones/
+  FLAT_FILES=""
+  FLAT_COUNT=0
+  for f in "$MILESTONES_DIR"/v*-*.md; do
+    [ -f "$f" ] || continue
+    FLAT_FILES="$FLAT_FILES  $(basename "$f")"$'\n'
+    FLAT_COUNT=$((FLAT_COUNT + 1))
+  done
+
+  if [ "$FLAT_COUNT" -gt 0 ]; then
+    echo "Status: FAIL"
+    echo "Found $FLAT_COUNT flat file(s) in milestones/ (old format):"
+    echo "$FLAT_FILES"
+    # Check if corresponding versioned directories exist
+    for f in "$MILESTONES_DIR"/v*-*.md; do
+      [ -f "$f" ] || continue
+      fname=$(basename "$f")
+      # Extract version prefix: v0.1-ROADMAP.md -> v0.1
+      version=$(echo "$fname" | sed 's/^\(v[0-9.]*\)-.*/\1/')
+      if [ -d "$MILESTONES_DIR/$version" ]; then
+        echo "  $fname → directory $version/ exists (can restructure)"
+      else
+        echo "  $fname → directory $version/ missing (need to create)"
+      fi
+    done
+    record_result "FAIL" "Milestone Directory Structure"
+  else
+    # Count versioned directories
+    DIR_COUNT=0
+    for d in "$MILESTONES_DIR"/v*/; do
+      [ -d "$d" ] || continue
+      DIR_COUNT=$((DIR_COUNT + 1))
+    done
+
+    if [ "$DIR_COUNT" -eq 0 ]; then
+      echo "Status: SKIP"
+      echo "No completed milestones"
+      record_result "SKIP" "Milestone Directory Structure"
+    else
+      echo "Status: PASS"
+      echo "$DIR_COUNT versioned milestone directories"
+      record_result "PASS" "Milestone Directory Structure"
+    fi
+  fi
+fi
+echo ""
+
+# ============================================================
+# CHECK 3: Phase Archival
+# ============================================================
+echo "=== Phase Archival ==="
+
+if [ ! -f "$MILESTONES_FILE" ] || ! grep -q "Phases completed" "$MILESTONES_FILE" 2>/dev/null; then
+  echo "Status: SKIP"
+  echo "No completed milestones with phase ranges in MILESTONES.md"
+  record_result "SKIP" "Phase Archival"
+else
+  ORPHAN_COUNT=0
+  ORPHAN_LIST=""
+
+  # Parse each milestone's completed phases from MILESTONES.md
+  while IFS= read -r line; do
+    while IFS= read -r phase_num; do
+      [ -z "$phase_num" ] && continue
+      prefix=$(format_phase_prefix "$phase_num")
+      for dir in "$PHASES_DIR"/${prefix}-*/; do
+        [ -d "$dir" ] || continue
+        dirname=$(basename "$dir")
+        ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
+        ORPHAN_LIST="$ORPHAN_LIST  $dirname (should be archived)"$'\n'
+      done
+    done < <(parse_phase_numbers "$line")
+  done < <(grep "Phases completed" "$MILESTONES_FILE")
+
+  if [ "$ORPHAN_COUNT" -gt 0 ]; then
+    echo "Status: FAIL"
+    echo "Found $ORPHAN_COUNT orphaned phase directories from completed milestones:"
+    echo "$ORPHAN_LIST"
+    record_result "FAIL" "Phase Archival"
+  else
+    echo "Status: PASS"
+    echo "All completed milestone phases are archived"
+    record_result "PASS" "Phase Archival"
+  fi
+fi
+echo ""
+
+# ============================================================
+# CHECK 4: Knowledge Files
+# ============================================================
+echo "=== Knowledge Files ==="
+
+if [ "$SUBSYSTEM_COUNT" -eq 0 ]; then
+  echo "Status: SKIP"
+  echo "No subsystems configured — knowledge check requires subsystem vocabulary"
+  record_result "SKIP" "Knowledge Files"
+elif [ ! -d "$KNOWLEDGE_DIR" ]; then
+  echo "Status: FAIL"
+  echo "Knowledge directory missing: .planning/knowledge/"
+  echo "Expected files for $SUBSYSTEM_COUNT subsystems"
+  record_result "FAIL" "Knowledge Files"
+else
+  MISSING_KNOWLEDGE=""
+  MISSING_COUNT=0
+  PRESENT_COUNT=0
+  while IFS= read -r subsystem; do
+    [ -z "$subsystem" ] && continue
+    if [ -f "$KNOWLEDGE_DIR/$subsystem.md" ]; then
+      PRESENT_COUNT=$((PRESENT_COUNT + 1))
+    else
+      MISSING_COUNT=$((MISSING_COUNT + 1))
+      MISSING_KNOWLEDGE="$MISSING_KNOWLEDGE  $subsystem.md"$'\n'
+    fi
+  done < <(jq -r '.subsystems[]' "$CONFIG" 2>/dev/null)
+
+  # Check for orphaned knowledge files (not in subsystem list)
+  ORPHAN_KNOWLEDGE=""
+  ORPHAN_K_COUNT=0
+  for f in "$KNOWLEDGE_DIR"/*.md; do
+    [ -f "$f" ] || continue
+    fname=$(basename "$f" .md)
+    if ! jq -r '.subsystems[]' "$CONFIG" 2>/dev/null | grep -qx "$fname"; then
+      ORPHAN_K_COUNT=$((ORPHAN_K_COUNT + 1))
+      ORPHAN_KNOWLEDGE="$ORPHAN_KNOWLEDGE  $fname.md (not in subsystems list)"$'\n'
+    fi
+  done
+
+  if [ "$MISSING_COUNT" -gt 0 ] || [ "$ORPHAN_K_COUNT" -gt 0 ]; then
+    echo "Status: FAIL"
+    echo "Coverage: $PRESENT_COUNT/$SUBSYSTEM_COUNT subsystems have knowledge files"
+    if [ "$MISSING_COUNT" -gt 0 ]; then
+      echo "Missing:"
+      echo "$MISSING_KNOWLEDGE"
+    fi
+    if [ "$ORPHAN_K_COUNT" -gt 0 ]; then
+      echo "Orphaned:"
+      echo "$ORPHAN_KNOWLEDGE"
+    fi
+    record_result "FAIL" "Knowledge Files"
+  else
+    echo "Status: PASS"
+    echo "All $SUBSYSTEM_COUNT subsystems have knowledge files"
+    record_result "PASS" "Knowledge Files"
+  fi
+fi
+echo ""
+
+# ============================================================
+# CHECK 5: Phase Summaries
+# ============================================================
+echo "=== Phase Summaries ==="
+
+if [ ! -d "$MILESTONES_DIR" ]; then
+  echo "Status: SKIP"
+  echo "No milestones directory"
+  record_result "SKIP" "Phase Summaries"
+else
+  MISSING_SUMMARIES=""
+  MISSING_S_COUNT=0
+  CHECKED=0
+
+  for d in "$MILESTONES_DIR"/v*/; do
+    [ -d "$d" ] || continue
+    CHECKED=$((CHECKED + 1))
+    version=$(basename "$d")
+    if [ ! -f "$d/PHASE-SUMMARIES.md" ]; then
+      MISSING_S_COUNT=$((MISSING_S_COUNT + 1))
+      MISSING_SUMMARIES="$MISSING_SUMMARIES  $version/PHASE-SUMMARIES.md"$'\n'
+    fi
+  done
+
+  if [ "$CHECKED" -eq 0 ]; then
+    echo "Status: SKIP"
+    echo "No versioned milestone directories"
+    record_result "SKIP" "Phase Summaries"
+  elif [ "$MISSING_S_COUNT" -gt 0 ]; then
+    echo "Status: FAIL"
+    echo "Missing PHASE-SUMMARIES.md in $MISSING_S_COUNT milestone(s):"
+    echo "$MISSING_SUMMARIES"
+    record_result "FAIL" "Phase Summaries"
+  else
+    echo "Status: PASS"
+    echo "All $CHECKED milestones have PHASE-SUMMARIES.md"
+    record_result "PASS" "Phase Summaries"
+  fi
+fi
+echo ""
+
+# ============================================================
+# CHECK 6: PLAN Cleanup
+# ============================================================
+echo "=== PLAN Cleanup ==="
+
+if [ ! -f "$MILESTONES_FILE" ] || ! grep -q "Phases completed" "$MILESTONES_FILE" 2>/dev/null; then
+  echo "Status: SKIP"
+  echo "No completed milestones — active phase PLANs are expected"
+  record_result "SKIP" "PLAN Cleanup"
+else
+  LEFTOVER_PLANS=""
+  LEFTOVER_COUNT=0
+
+  # Check phases/ for PLANs belonging to completed milestones
+  while IFS= read -r line; do
+    while IFS= read -r phase_num; do
+      [ -z "$phase_num" ] && continue
+      prefix=$(format_phase_prefix "$phase_num")
+      for plan in "$PHASES_DIR"/${prefix}-*/*-PLAN.md; do
+        [ -f "$plan" ] || continue
+        LEFTOVER_COUNT=$((LEFTOVER_COUNT + 1))
+        LEFTOVER_PLANS="$LEFTOVER_PLANS  $(echo "$plan" | sed "s|$GIT_ROOT/.planning/||")"$'\n'
+      done
+    done < <(parse_phase_numbers "$line")
+  done < <(grep "Phases completed" "$MILESTONES_FILE")
+
+  # Check archived milestone phase directories for leftover PLANs
+  for d in "$MILESTONES_DIR"/v*/phases/*/; do
+    [ -d "$d" ] || continue
+    for plan in "$d"*-PLAN.md; do
+      [ -f "$plan" ] || continue
+      LEFTOVER_COUNT=$((LEFTOVER_COUNT + 1))
+      LEFTOVER_PLANS="$LEFTOVER_PLANS  $(echo "$plan" | sed "s|$GIT_ROOT/.planning/||")"$'\n'
+    done
+  done
+
+  if [ "$LEFTOVER_COUNT" -gt 0 ]; then
+    echo "Status: FAIL"
+    echo "Found $LEFTOVER_COUNT leftover PLAN file(s) in completed phases:"
+    echo "$LEFTOVER_PLANS"
+    record_result "FAIL" "PLAN Cleanup"
+  else
+    echo "Status: PASS"
+    echo "No leftover PLAN files in completed phases"
+    record_result "PASS" "PLAN Cleanup"
+  fi
+fi
+echo ""
+
+# ============================================================
+# SUMMARY
+# ============================================================
+TOTAL=$((PASS_COUNT + FAIL_COUNT + SKIP_COUNT))
+echo "=== Summary ==="
+echo "Checks: $TOTAL total, $PASS_COUNT passed, $FAIL_COUNT failed, $SKIP_COUNT skipped"
+
+if [ "$FAIL_COUNT" -gt 0 ]; then
+  echo "Issues:$FAILED_CHECKS"
+  exit 1
+else
+  echo "All checks passed"
+  exit 0
+fi