mindsystem-cc 3.12.0 → 3.13.1

package/mindsystem/workflows/plan-phase.md

@@ -36,7 +36,7 @@ PLAN.md IS the prompt that Claude executes. Plans are grouped into execution wav
 
 **Vertical slices over horizontal layers:** Group by feature (User: model + API + UI) not by type (all models → all APIs → all UIs).
 
-**Explicit dependencies:** Every plan declares what it needs (`depends_on`) and what it touches (`files_modified`). Empty dependencies = parallel candidate.
+**Explicit dependencies:** EXECUTION-ORDER.md centralizes dependency and parallelism tracking. Plans with no dependencies = parallel candidates.
 
 **Secure by design:** Assume hostile input on every boundary. Validate, parameterize, authenticate, fail closed.
 
@@ -120,7 +120,7 @@ grep -l "status: diagnosed" "$PHASE_DIR"/*-UAT.md 2>/dev/null
 
 **2. Parse gaps:**
 
-**From VERIFICATION.md** (if exists): Parse `gaps:` from YAML frontmatter.
+**From VERIFICATION.md** (if exists): Parse gaps from `## Gaps Summary` section (markdown format with `### Critical Gaps` and `### Non-Critical Gaps` subsections).
 
 **From UAT.md** (if exists with status: diagnosed): Parse gaps from `## Gaps` section (YAML format).
 
@@ -154,40 +154,49 @@ Cluster related gaps by:
 - Same concern (fetch + render → one "wire frontend" plan)
 - Dependency order (can't wire if artifact is stub → fix stub first)
 
-**6. Create gap closure tasks:**
+**6. Create gap closure changes:**
 
-For each gap:
-```xml
-<task name="{fix_description}" type="auto">
-  <files>{artifact.path}</files>
-  <action>
-    {For each item in gap.missing:}
-    - {missing item}
-
-    Reference existing code: {from SUMMARYs}
-    Gap reason: {gap.reason}
-  </action>
-  <verify>{How to confirm gap is closed}</verify>
-  <done>{Observable truth now achievable}</done>
-</task>
+For each gap, create a markdown change subsection:
+
+```markdown
+### N. {Fix description}
+**Files:** `{artifact.path}`
+
+{For each item in gap.missing:}
+- {missing item}
+
+Reference existing code: {from SUMMARYs}
+Gap reason: {gap.reason}
 ```
 
 **7. Write PLAN.md files:**
 
-Use standard template but note gap closure context:
+Use pure markdown plan format with gap closure context:
 
-```yaml
----
-phase: XX-name
-plan: NN              # Sequential after existing
-type: execute
-wave: 1               # Gap closures typically single wave
-depends_on: []        # Usually independent of each other
-files_modified: [...]
-gap_closure: true     # Flag for tracking
----
+```markdown
+# Plan NN: {Gap closure description}
+
+**Subsystem:** {subsystem} | **Type:** execute
+
+## Context
+Gap closure for phase XX. Addresses gaps identified by verification.
+
+## Changes
+
+### 1. {Fix description}
+**Files:** `{artifact.path}`
+
+{Implementation details from gap.missing items}
+
+## Verification
+- {How to confirm gap is closed}
+
+## Must-Haves
+- [ ] {Observable truth now achievable}
 ```
 
+Also create or update EXECUTION-ORDER.md to include gap closure plans (typically single wave, independent of each other).
+
 **9. Present gap closure summary:**
 
 ```markdown
@@ -432,7 +441,7 @@ cat .planning/phases/XX-name/${PHASE}-DESIGN.md 2>/dev/null
 **If DESIGN.md exists:**
 - Tasks reference specific screens/components from design
 - Verification criteria include design verification items
-- must_haves include design-specified observable behaviors
+- Must-Haves include design-specified observable behaviors
 - Task actions specify exact values (colors, spacing) from design
 
 **If none exist:** Suggest /ms:research-phase for niche domains, /ms:discuss-phase for simpler domains, or proceed with roadmap only.
@@ -573,10 +582,10 @@ Task(
 The subagent handles:
 - Building dependency graph from needs/creates
 - Assigning wave numbers
-- Grouping tasks into plans (2-3 per plan)
-- Deriving must_haves (goal-backward)
+- Grouping tasks into plans (2-3 changes per plan)
+- Deriving Must-Haves (goal-backward)
 - Estimating scope, splitting if needed
-- Writing PLAN.md files
+- Writing PLAN.md files + EXECUTION-ORDER.md
 - Git commit
 - Calculating risk score
 </step>
@@ -744,10 +753,10 @@ Tasks are instructions for Claude, not Jira tickets.
 - [ ] Prior decisions, issues, concerns synthesized
 - [ ] Tasks identified with needs/creates dependencies
 - [ ] Task list handed off to ms-plan-writer
-- [ ] PLAN file(s) created by subagent with XML structure
-- [ ] Each plan: depends_on, files_modified in frontmatter
-- [ ] Each plan: must_haves derived (truths, artifacts, key_links)
-- [ ] Each plan: 2-3 tasks (~50% context)
+- [ ] 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: 2-3 changes (~50% context)
 - [ ] Wave structure maximizes parallelism
 - [ ] PLAN file(s) committed to git
 - [ ] Risk assessment presented (score + top factors)
@@ -759,8 +768,8 @@ Tasks are instructions for Claude, not Jira tickets.
 - [ ] Existing SUMMARYs read for context
 - [ ] Gaps clustered into focused plans
 - [ ] Plan numbers sequential after existing (04, 05...)
-- [ ] PLAN file(s) exist with gap_closure: true
-- [ ] Each plan: tasks derived from gap.missing items
+- [ ] PLAN file(s) created with pure markdown format
+- [ ] EXECUTION-ORDER.md updated with gap closure plans
 - [ ] PLAN file(s) committed to git
 - [ ] User knows to run `/ms:execute-phase {X}` next
 </success_criteria>

package/mindsystem/workflows/verify-phase.md

@@ -42,7 +42,7 @@ grep -E "^| ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null
 # All SUMMARY files (claims to verify)
 ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
 
-# All PLAN files (for must_haves in frontmatter)
+# All PLAN files (for Must-Haves in plan markdown)
 ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
@@ -54,32 +54,28 @@ ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 <step name="establish_must_haves">
 **Determine what must be verified.**
 
-**Option A: Must-haves in PLAN frontmatter**
+**Option A: Must-haves in plan markdown**
 
-Check if any PLAN.md has `must_haves` in frontmatter:
+Check if any PLAN.md has a `## Must-Haves` section:
 
 ```bash
-grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
+grep -l "## Must-Haves" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
-If found, extract and use:
-```yaml
-must_haves:
-  truths:
-    - "User can see existing messages"
-    - "User can send a message"
-  artifacts:
-    - path: "src/components/Chat.tsx"
-      provides: "Message list rendering"
-  key_links:
-    - from: "Chat.tsx"
-      to: "api/chat"
-      via: "fetch in useEffect"
+If found, extract checklist items. Must-haves are markdown checklist entries:
+
+```markdown
+## Must-Haves
+- [ ] User can see existing messages
+- [ ] User can send a message
+- [ ] Messages persist after refresh
 ```
 
+Each `- [ ]` item is an observable truth to verify. Derive artifacts from `**Files:**` lines in `## Changes` sections and key links from the implementation details.
+
 **Option B: Derive from phase goal**
 
-If no must_haves in frontmatter, derive using goal-backward process:
+If no `## Must-Haves` section found in plans, derive using goal-backward process:
 
 1. **State the goal:** Take phase goal from ROADMAP.md
 
@@ -370,7 +366,7 @@ verify_state_render_link() {
 
 ### Aggregate key link results
 
-For each key link in must_haves:
+For each key link derived from plan `## Changes` and `## Must-Haves` sections:
 - Run appropriate verification function
 - Record status and evidence
 - WIRED / PARTIAL / STUB / NOT_WIRED
@@ -615,7 +611,7 @@ The orchestrator will:
 </process>
 
 <success_criteria>
-- [ ] Must-haves established (from frontmatter or derived)
+- [ ] Must-haves established (from plan ## Must-Haves section or derived)
 - [ ] All truths verified with status and evidence
 - [ ] All artifacts checked at all three levels
 - [ ] All key links verified

package/mindsystem/workflows/verify-work.md

@@ -5,7 +5,7 @@ Complete verify-and-fix session: by session end, everything verified, issues fix
 </purpose>
 
 <execution_context>
-<!-- mock-patterns.md and generate-mocks.md loaded on demand when mocks are needed (see classify_tests step) -->
+<!-- mock-patterns.md loaded on demand for transient_state mocks (see generate_mocks step) -->
 </execution_context>
 
 <template>
@@ -232,7 +232,7 @@ tests:
 <step name="create_batches">
 **Group tests into batches:**
 
-**If any tests have mock_required=true:** Read `~/.claude/mindsystem/references/mock-patterns.md` and `~/.claude/mindsystem/workflows/generate-mocks.md` now for mock generation guidance.
+**If any tests have mock_required=true AND batch includes `transient_state` mocks:** Read `~/.claude/mindsystem/references/mock-patterns.md` for delay/never-resolve strategies.
 
 **Rules:**
 1. Group by mock_type (tests needing same mock state go together)
@@ -311,7 +311,7 @@ source: [list of SUMMARY.md files]
 started: [ISO timestamp]
 updated: [ISO timestamp]
 current_batch: 1
-mock_stash: null
+mocked_files: []
 pre_work_stash: [from dirty tree handling, or null]
 ---
 
@@ -378,11 +378,11 @@ Read current batch from UAT.md.
 **1. Handle mock generation (if needed):**
 
 If `mock_type` is not null AND different from previous batch:
-- Discard old mocks if any (use stash name from `mock_stash` in UAT.md frontmatter):
+- Revert old mocks if any (from `mocked_files` in UAT.md frontmatter):
   ```bash
-  MOCK_STASH=$(git stash list | grep "mocks-batch" | head -1 | cut -d: -f1)
-  [ -n "$MOCK_STASH" ] && git stash drop "$MOCK_STASH"
+  git checkout -- <mocked_files>
   ```
+- Clear `mocked_files` in frontmatter
 - Go to `generate_mocks`
 
 If `mock_type` is null or same as previous:
@@ -394,72 +394,61 @@ Go to `present_tests`
 </step>
 
 <step name="generate_mocks">
-**Generate mocks for current batch:**
+**Generate mocks for current batch using inline approach:**
 
-Present mock generation options:
-```
-## Batch [N]: [Name]
+Count mock-requiring tests in this batch.
 
-**Mock required:** [mock_type description]
+**Decision logic:**
 
-This batch tests states that require mock data. Options:
+| Count | Approach |
+|-------|----------|
+| 1-4   | Inline: edit service methods directly in main context |
+| 5+    | Subagent: spawn ms-mock-generator for batch editing |
 
-1. Generate mocks (Recommended) — I'll create the override files
-2. I'll set up mocks manually — Skip generation, you handle it
-3. Skip this batch — Log all tests as assumptions
-```
+**Inline approach (1-4 mocks):**
 
-**If "Generate mocks":**
+For each test in the batch:
+1. Identify the service/repository method that provides the data
+2. Read the method
+3. Edit to hardcode desired return value BEFORE the real implementation:
+   ```
+   // MOCK: {description} — revert after UAT
+   {hardcoded return/throw}
+   ```
+4. For transient_state mocks: Read `~/.claude/mindsystem/references/mock-patterns.md` for delay/never-resolve strategies
+
+**Subagent approach (5+ mocks):**
 
-Spawn mock generator:
 ```
 Task(
   prompt="""
-Generate mocks for manual UAT testing.
+Generate inline mocks for manual UAT testing.
 
-Project: {from PROJECT.md}
 Phase: {phase_name}
-Mock type: {mock_type}
 
-Tests requiring this mock:
-{test list with expected behaviors}
+Tests requiring mocks:
+{test list with mock_type and expected behaviors}
 
-Follow patterns from @~/.claude/mindsystem/workflows/generate-mocks.md
+Mocked files from previous batches (avoid conflicts):
+{mocked_files from UAT.md frontmatter}
 """,
   subagent_type="ms-mock-generator",
   description="Generate {mock_type} mocks"
 )
 ```
 
-After mock generator returns:
+**After mocks applied (both approaches):**
 
-1. Update UAT.md: `mock_stash: null` (mocks are uncommitted, not stashed yet)
-2. Present toggle instructions from mock generator
-3. Ask user to confirm mocks are active:
+1. Record mocked files in UAT.md frontmatter: `mocked_files: [file1.dart, file2.dart, ...]`
+2. Tell user: "Mocks applied. Hot reload to test."
+3. Proceed directly to `present_tests` — no user confirmation needed
 
-```
-questions:
-  - question: "I've created the mock files. Have you enabled the mocks and verified they're working?"
-    header: "Mocks ready"
-    options:
-      - label: "Yes, mocks are active"
-        description: "I've toggled the flags and hot reloaded"
-      - label: "Having trouble"
-        description: "Something isn't working with the mocks"
-    multiSelect: false
-```
-
-**If "I'll set up manually":**
-- Present what mock state is needed
-- Wait for user to confirm ready
+**Skip option:**
 
-**If "Skip this batch":**
-- Prompt for reason: "Why are you skipping this batch?"
-- Mark all tests in batch as `skipped` with user's reason
+If user has previously indicated they want to skip mock batches, or if mock generation fails:
+- Mark all tests in batch as `skipped`
 - Append to Assumptions section
 - Proceed to next batch
-
-Proceed to `present_tests`.
 </step>
 
 <step name="present_tests">
@@ -574,9 +563,9 @@ For each question:
 
 **1. Stash mocks (if active):**
 ```bash
-git stash push -m "mocks-batch-{N}"
+git stash push -m "mocks-batch-{N}" -- <mocked_files>
 ```
-Update UAT.md: `mock_stash: "mocks-batch-{N}"`
+Use `mocked_files` list from UAT.md frontmatter.
 
 **2. Make the fix:**
 - Edit the file(s)
@@ -605,11 +594,11 @@ git stash pop
 
 **Handle stash conflict:**
 ```bash
-# If conflict, take fix version
+# Conflict means fix touched a mocked file — take the fix version
 git checkout --theirs <conflicted-file>
 git add <conflicted-file>
 ```
-Log that mock was discarded for that file.
+Remove conflicted file from `mocked_files` list in UAT.md (mock no longer needed for that file).
 
 **6. Request re-test:**
 ```
@@ -626,7 +615,7 @@ Go to `handle_retest`.
 
 **1. Stash mocks (if active):**
 ```bash
-git stash push -m "mocks-batch-{N}"
+git stash push -m "mocks-batch-{N}" -- <mocked_files>
 ```
 
 **2. Spawn ms-verify-fixer:**
@@ -738,13 +727,12 @@ questions:
 
 Read full UAT file.
 
-Check `mock_stash` — if exists, offer to restore:
-```
-Found stashed mocks: {mock_stash}
-
-1. Restore mocks — Continue where we left off
-2. Discard mocks — Start batch fresh
+Check `mocked_files` — if non-empty, verify mocks are still present:
+```bash
+git diff --name-only
 ```
+If mocked files have uncommitted changes, mocks are still active — continue.
+If mocked files are clean, mocks were lost — regenerate for current batch.
 
 Find current position:
 - current_batch
@@ -796,12 +784,11 @@ issues: {count}
 <step name="complete_session">
 **Complete UAT session:**
 
-**1. Discard mocks:**
+**1. Revert mocks:**
 ```bash
-# Find and drop the specific mock stash (not just the top one)
-MOCK_STASH=$(git stash list | grep "mocks-batch" | head -1 | cut -d: -f1)
-[ -n "$MOCK_STASH" ] && git stash drop "$MOCK_STASH"
+git checkout -- <mocked_files>
 ```
+Use `mocked_files` list from UAT.md frontmatter. Clear the list after reverting.
 
 **2. Generate UAT fixes patch (if fixes were made):**
 ```bash
@@ -818,7 +805,7 @@ PRE_WORK_STASH=$(git stash list | grep "pre-verify-work" | head -1 | cut -d: -f1
 
 **4. Update UAT.md:**
 - status: complete
-- Clear current_batch, mock_stash
+- Clear current_batch, mocked_files
 - Final Progress counts
 
 **5. Commit UAT.md:**
@@ -863,7 +850,7 @@ Check if more phases remain in ROADMAP.md:
 |---------|------|------|
 | Frontmatter.status | OVERWRITE | Phase transitions |
 | Frontmatter.current_batch | OVERWRITE | Batch transitions |
-| Frontmatter.mock_stash | OVERWRITE | Stash operations |
+| Frontmatter.mocked_files | OVERWRITE | Mock generation/cleanup |
 | Frontmatter.updated | OVERWRITE | Every write |
 | Progress | OVERWRITE | After each test result |
 | Current Batch | OVERWRITE | Batch transitions |
@@ -895,7 +882,7 @@ Default: **major** (safe default)
 - [ ] Dirty tree handled at start
 - [ ] Tests classified by mock requirements
 - [ ] Batches created respecting dependencies and mock types
-- [ ] Mocks generated when needed with toggle instructions
+- [ ] Mocks applied inline when needed (1-4 direct, 5+ via subagent)
 - [ ] Tests presented in batches of 4
 - [ ] Issues investigated with lightweight check (2-3 calls)
 - [ ] Simple issues fixed inline with proper commit
@@ -903,7 +890,7 @@ Default: **major** (safe default)
 - [ ] Re-test retries (2 max, tracked via retry_count) before offering options
 - [ ] Blocked tests re-presented after blocking issues resolved
 - [ ] Stash conflicts auto-resolved to fix version
-- [ ] Mocks discarded on completion
+- [ ] Mocks reverted on completion (git checkout)
 - [ ] UAT fixes patch generated
 - [ ] User's pre-existing work restored
 - [ ] UAT.md committed with final summary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.12.0",
+  "version": "3.13.1",
   "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/update-state.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+#
+# update-state.sh
+# Updates .planning/STATE.md Plan and Status lines based on plan progress.
+# Idempotent — same arguments produce the same result.
+#
+# Usage: ./scripts/update-state.sh <completed_plan_count> <total_plans>
+# Example: ./scripts/update-state.sh 2 4
+#          (2 of 4 plans complete)
+#
+
+set -e
+
+# --- Validation ---
+if [ -z "$1" ] || [ -z "$2" ]; then
+  echo "Error: Two arguments required"
+  echo "Usage: $0 <completed_plan_count> <total_plans>"
+  exit 1
+fi
+
+COMPLETED="$1"
+TOTAL="$2"
+
+if ! [[ "$COMPLETED" =~ ^[0-9]+$ ]] || ! [[ "$TOTAL" =~ ^[0-9]+$ ]]; then
+  echo "Error: Both arguments must be numeric"
+  echo "Usage: $0 <completed_plan_count> <total_plans>"
+  exit 1
+fi
+
+if [ "$COMPLETED" -gt "$TOTAL" ]; then
+  echo "Error: Completed ($COMPLETED) cannot exceed total ($TOTAL)"
+  exit 1
+fi
+
+# --- Find STATE.md 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 1
+fi
+
+STATE_FILE="$GIT_ROOT/.planning/STATE.md"
+if [ ! -f "$STATE_FILE" ]; then
+  echo "Error: STATE.md not found at $STATE_FILE"
+  exit 1
+fi
+
+# --- Update Plan line ---
+sed -i '' "s/^Plan:.*/Plan: $COMPLETED of $TOTAL complete in current phase/" "$STATE_FILE"
+
+# --- Update Status line ---
+if [ "$COMPLETED" -eq "$TOTAL" ]; then
+  sed -i '' "s/^Status:.*/Status: All plans executed, pending verification/" "$STATE_FILE"
+else
+  sed -i '' "s/^Status:.*/Status: In progress — plan $COMPLETED of $TOTAL complete/" "$STATE_FILE"
+fi
+
+echo "STATE.md updated: $COMPLETED of $TOTAL plans complete"
+exit 0

package/scripts/validate-execution-order.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+#
+# validate-execution-order.sh
+# Validates EXECUTION-ORDER.md against plan files in a phase directory.
+# Checks bidirectional consistency and warns about file conflicts within waves.
+#
+# Usage: ./scripts/validate-execution-order.sh <phase_directory>
+# Example: ./scripts/validate-execution-order.sh .planning/phases/03-auth
+#
+
+set -e
+
+# --- Validation ---
+if [ -z "$1" ]; then
+  echo "Error: Phase directory required"
+  echo "Usage: $0 <phase_directory>"
+  exit 1
+fi
+
+PHASE_DIR="$1"
+
+if [ ! -d "$PHASE_DIR" ]; then
+  echo "FAIL: Directory does not exist: $PHASE_DIR"
+  exit 1
+fi
+
+EXEC_ORDER="$PHASE_DIR/EXECUTION-ORDER.md"
+if [ ! -f "$EXEC_ORDER" ]; then
+  echo "FAIL: EXECUTION-ORDER.md not found in $PHASE_DIR"
+  exit 1
+fi
+
+# --- Collect plan files on disk ---
+DISK_PLANS=$(ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | xargs -I{} basename {} | sort)
+DISK_COUNT=$(echo "$DISK_PLANS" | grep -c . 2>/dev/null || echo 0)
+
+if [ "$DISK_COUNT" -eq 0 ]; then
+  echo "FAIL: No *-PLAN.md files found in $PHASE_DIR"
+  exit 1
+fi
+
+# --- Parse EXECUTION-ORDER.md for plan filenames ---
+ORDER_PLANS=$(grep -oE '[0-9]+-PLAN\.md' "$EXEC_ORDER" | sort -u)
+ORDER_COUNT=$(echo "$ORDER_PLANS" | grep -c . 2>/dev/null || echo 0)
+
+# --- Check 1: Every disk plan is listed in EXECUTION-ORDER.md ---
+ERRORS=""
+while IFS= read -r plan; do
+  if ! echo "$ORDER_PLANS" | grep -qx "$plan"; then
+    ERRORS="${ERRORS}  Missing from EXECUTION-ORDER.md: $plan\n"
+  fi
+done <<< "$DISK_PLANS"
+
+# --- Check 2: Every plan in EXECUTION-ORDER.md exists on disk ---
+while IFS= read -r plan; do
+  if ! echo "$DISK_PLANS" | grep -qx "$plan"; then
+    ERRORS="${ERRORS}  Listed in EXECUTION-ORDER.md but file missing: $plan\n"
+  fi
+done <<< "$ORDER_PLANS"
+
+if [ -n "$ERRORS" ]; then
+  echo "FAIL: Plan/execution-order mismatch"
+  printf "%b" "$ERRORS"
+  exit 1
+fi
+
+# --- Check 3 (warning): File conflicts within waves ---
+CURRENT_WAVE=""
+WAVE_COUNT=0
+declare -A WAVE_FILES
+
+while IFS= read -r line; do
+  if echo "$line" | grep -qE '^## Wave [0-9]+'; then
+    CURRENT_WAVE=$(echo "$line" | grep -oE '[0-9]+')
+    WAVE_COUNT=$((WAVE_COUNT + 1))
+    WAVE_FILES[$CURRENT_WAVE]=""
+  elif [ -n "$CURRENT_WAVE" ]; then
+    PLAN_FILE=$(echo "$line" | grep -oE '[0-9]+-PLAN\.md' || true)
+    if [ -n "$PLAN_FILE" ] && [ -f "$PHASE_DIR/$PLAN_FILE" ]; then
+      # Extract **Files:** lines from plan
+      FILE_PATHS=$(grep -E '^\*\*Files:\*\*' "$PHASE_DIR/$PLAN_FILE" | sed 's/\*\*Files:\*\*//g' | tr ',' '\n' | sed 's/`//g; s/^[[:space:]]*//; s/[[:space:]]*$//' | grep -v '^$' || true)
+      while IFS= read -r fpath; do
+        [ -z "$fpath" ] && continue
+        EXISTING="${WAVE_FILES[$CURRENT_WAVE]}"
+        if echo "$EXISTING" | grep -qF "|$fpath|"; then
+          echo "WARNING: File '$fpath' appears in multiple plans within Wave $CURRENT_WAVE"
+        else
+          WAVE_FILES[$CURRENT_WAVE]="${EXISTING}|$fpath|"
+        fi
+      done <<< "$FILE_PATHS"
+    fi
+  fi
+done < "$EXEC_ORDER"
+
+# --- Handle edge case: no waves parsed ---
+if [ "$WAVE_COUNT" -eq 0 ]; then
+  echo "FAIL: No '## Wave N' headers found in EXECUTION-ORDER.md"
+  exit 1
+fi
+
+echo "PASS: $DISK_COUNT plans across $WAVE_COUNT waves"
+exit 0

package/skills/flutter-code-quality/SKILL.md

@@ -24,11 +24,12 @@ Comprehensive guidelines for Flutter/Dart code quality, widget organization, and
 
 Fetch fresh guidelines before each review:
 
-```
-https://gist.githubusercontent.com/rolandtolnay/edf9ea7d5adf218f45accb3411f0627c/raw/flutter-code-quality-guidelines.md
+```bash
+gh api /gists/edf9ea7d5adf218f45accb3411f0627c \
+  --jq '.files["flutter-code-quality-guidelines.md"].content'
 ```
 
-Use WebFetch to retrieve. Contains: anti-patterns, widget patterns, state management, collections, hooks, theme/styling, etc.
+Never use WebFetch for gist content — it summarizes instead of returning raw text. Contains: anti-patterns, widget patterns, state management, collections, hooks, theme/styling, etc.
 
 ## Widget Organization Guidelines (Embedded)