projecta-rrr 1.15.13 → 1.16.1

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to RRR will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.16.1] - 2026-01-27
+
+### Fixed
+- **Missing scripts in npm install** - All user-facing scripts now copied to target project
+  - Added: `pushpa-jarvis.sh`, `browser-uat.sh`, `scaffold-e2e.sh`, `chrome-visual-check.sh`, `index-sessions.sh`
+  - Added npm scripts: `pushpa:jarvis`, `browser:uat`, `scaffold:e2e`, `chrome:visual`, `sessions:index`
+  - Scripts copied alongside existing `pushpa-mode.sh`, `mcp-setup.sh`, `visual-proof.sh`
+- **pushpa-jarvis.sh bug fixes**
+  - Fixed `verify_phase()` using wrong variable (`$ph` instead of `$phase`)
+  - Fixed `phase_has_summary()` to search both active phases and milestone archives
+
+## [1.16.0] - 2026-01-26
+
+### Added
+- **AI QA Engineer mode** - Autonomous testing persona for exploratory browser testing
+  - Uses Playwright MCP for browser control + MiniMax for vision analysis
+  - Black-box testing: can only interact through browser, no source code access
+  - Tests edge cases: empty inputs, long text, special chars, rapid clicks
+  - Cost: ~$0.001 per validation (50-100x cheaper than agent-browse)
+
+- **CDP browser adapter** - Fast screenshot capture via Chrome DevTools Protocol
+  - Auto-launches Chrome with remote debugging port
+  - Preferred method over Playwright for non-interactive operations
+  - Method priority: cdp > minimax > playwright-mcp > api > cli
+
+- **Vitest Browser AI integration** - AI visual analysis on every test
+  - Plugin with afterEach hooks for automatic screenshot capture
+  - Helper functions: `expectVisual()`, `describeScreen()`, `waitForVisual()`
+  - Documentation and example tests included
+
+- **minimax-agent-browse package** - Drop-in replacement for agent-browse
+  - Uses local CDP instead of Browserbase (no cloud dependency)
+  - MiniMax vision API instead of Anthropic (50-100x cheaper)
+  - CLI: `npx minimax-agent-browse "go to google.com and search for cats"`
+  - Agent loop: screenshot → analyze → action → repeat
+
+- **User-facing browser API** - `rrr/lib/uat/browser.js` for project consumption
+  - `getStatus()`, `takeScreenshot()`, `getScreenshotPath()`
+  - Abstracts CDP/Playwright implementation details
+
+- **Visual failure integration** - `discover_visual_artifacts` step in diagnose-issues
+  - Finds Playwright logs, diff images, UAT screenshots
+  - Categorizes failures: Page Load, Screenshot Diff, Timeout, etc.
+
+### Changed
+- **Deprecated /rrr:fix-visual-failure** - Functionality now in diagnose-issues workflow
+
 ## [1.15.13] - 2026-01-25
 
 ### Added

package/agents/rrr-integration-checker.md

@@ -57,7 +57,9 @@ For each phase, extract what it provides and what it should consume.
 
 ```bash
 # Key exports from each phase
-for summary in .planning/phases/*/*-SUMMARY.md; do
+# Use milestone-aware paths
+PHASE_BASE=$(get_phase_base_dir)
+for summary in "$PHASE_BASE"/*/*-SUMMARY.md; do
   echo "=== $summary ==="
   grep -A 10 "Key Files\|Exports\|Provides" "$summary" 2>/dev/null
 done

package/agents/rrr-phase-researcher.md

@@ -295,7 +295,7 @@ Before submitting research:
 
 ## RESEARCH.md Structure
 
-**Location:** `.planning/phases/XX-name/{phase}-RESEARCH.md`
+**Location:** `.planning/milestones/vX.Y/phases/XX-name/{phase}-RESEARCH.md`
 
 ```markdown
 # Phase [X]: [Name] - Research
@@ -444,7 +444,8 @@ Orchestrator provides:
 **Load phase context (MANDATORY):**
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
+# Use phase-paths library for milestone-aware resolution
+PHASE_DIR=$(get_phase_dir "${PHASE}")
 
 # Read CONTEXT.md if exists (from /rrr:discuss-phase)
 cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null
@@ -520,7 +521,7 @@ Use the output format template. Populate all sections with verified findings.
 
 Write to: `${PHASE_DIR}/${PHASE}-RESEARCH.md`
 
-Where `PHASE_DIR` is the full path (e.g., `.planning/phases/01-foundation`)
+Where `PHASE_DIR` is the full path (e.g., `.planning/milestones/v1.0/phases/01-foundation`)
 
 ## Step 6: Commit Research
 

package/agents/rrr-plan-checker.md

@@ -244,8 +244,9 @@ issue:
 Gather verification context from the phase directory and project state.
 
 ```bash
-# Phase directory (provided in prompt)
-PHASE_DIR=".planning/phases/${PHASE_ARG}"
+# Phase directory (provided in prompt) - use phase-paths library
+# Searches: .planning/milestones/vX.Y/phases/NN-* (new) → .planning/phases/NN-* (legacy)
+PHASE_DIR=$(get_phase_dir "${PHASE_ARG}")
 
 # List all PLAN.md files
 ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null

package/agents/rrr-planner.md

@@ -1152,8 +1152,8 @@ git commit -m "fix(${PHASE}): revise plans based on checker feedback"
 
 ### Files Updated
 
-- .planning/phases/16-xxx/16-01-PLAN.md
-- .planning/phases/16-xxx/16-02-PLAN.md
+- .planning/milestones/vX.Y/phases/16-xxx/16-01-PLAN.md
+- .planning/milestones/vX.Y/phases/16-xxx/16-02-PLAN.md
 
 {If any issues NOT addressed:}
 
@@ -1204,7 +1204,9 @@ Check roadmap and existing phases:
 
 ```bash
 cat .planning/ROADMAP.md
-ls .planning/phases/
+# Use milestone-aware path
+PHASE_BASE=$(get_phase_base_dir)
+ls "$PHASE_BASE"/
 ```
 
 If multiple phases available, ask which one to plan. If obvious (first incomplete phase), proceed.
@@ -1223,7 +1225,7 @@ Apply discovery level protocol (see discovery_levels section).
 
 1. Scan all summary frontmatter (first ~25 lines):
 ```bash
-for f in .planning/phases/*/*-SUMMARY.md; do
+for f in "$PHASE_BASE"/*/*-SUMMARY.md; do
   sed -n '1,/^---$/p; /^---$/q' "$f" | head -30
 done
 ```

package/agents/rrr-roadmapper.md

@@ -570,9 +570,9 @@ When files are written and returning to orchestrator:
 **Files written:**
 - .planning/ROADMAP.md
 - .planning/STATE.md
-- .planning/phases/01-{phase-name}/
-- .planning/phases/02-{phase-name}/
-- ... (all phases zero-padded)
+- .planning/milestones/vX.Y/phases/01-{phase-name}/
+- .planning/milestones/vX.Y/phases/02-{phase-name}/
+- ... (all phases zero-padded under milestone)
 
 **Updated:**
 - .planning/REQUIREMENTS.md (traceability section)

package/bin/install.js

@@ -505,7 +505,16 @@ function installScripts(targetDir) {
 
   const installed = [];
   const skipped = [];
-  const scripts = ['pushpa-mode.sh', 'mcp-setup.sh', 'visual-proof.sh'];
+  const scripts = [
+    'pushpa-mode.sh',
+    'pushpa-jarvis.sh',
+    'mcp-setup.sh',
+    'visual-proof.sh',
+    'browser-uat.sh',
+    'scaffold-e2e.sh',
+    'chrome-visual-check.sh',
+    'index-sessions.sh'
+  ];
 
   for (const script of scripts) {
     const srcFile = path.join(srcScriptsDir, script);
@@ -598,6 +607,66 @@ function addNpmScripts(targetDir, installedScripts, bashAvailable = true) {
     }
   }
 
+  // Add pushpa:jarvis script if pushpa-jarvis.sh was installed
+  if (installedScripts.includes('pushpa-jarvis.sh') || fs.existsSync(path.join(targetDir, 'scripts', 'pushpa-jarvis.sh'))) {
+    if (pkgJson.scripts['pushpa:jarvis']) {
+      skipped.push('pushpa:jarvis');
+      console.log(`  ${yellow}⚠${reset} Skipped npm script "pushpa:jarvis" (already exists)`);
+    } else {
+      pkgJson.scripts['pushpa:jarvis'] = 'bash scripts/pushpa-jarvis.sh';
+      added.push('pushpa:jarvis');
+      console.log(`  ${green}✓${reset} Added npm script "pushpa:jarvis"`);
+    }
+  }
+
+  // Add browser:uat script if browser-uat.sh was installed
+  if (installedScripts.includes('browser-uat.sh') || fs.existsSync(path.join(targetDir, 'scripts', 'browser-uat.sh'))) {
+    if (pkgJson.scripts['browser:uat']) {
+      skipped.push('browser:uat');
+      console.log(`  ${yellow}⚠${reset} Skipped npm script "browser:uat" (already exists)`);
+    } else {
+      pkgJson.scripts['browser:uat'] = 'bash scripts/browser-uat.sh';
+      added.push('browser:uat');
+      console.log(`  ${green}✓${reset} Added npm script "browser:uat"`);
+    }
+  }
+
+  // Add scaffold:e2e script if scaffold-e2e.sh was installed
+  if (installedScripts.includes('scaffold-e2e.sh') || fs.existsSync(path.join(targetDir, 'scripts', 'scaffold-e2e.sh'))) {
+    if (pkgJson.scripts['scaffold:e2e']) {
+      skipped.push('scaffold:e2e');
+      console.log(`  ${yellow}⚠${reset} Skipped npm script "scaffold:e2e" (already exists)`);
+    } else {
+      pkgJson.scripts['scaffold:e2e'] = 'bash scripts/scaffold-e2e.sh';
+      added.push('scaffold:e2e');
+      console.log(`  ${green}✓${reset} Added npm script "scaffold:e2e"`);
+    }
+  }
+
+  // Add chrome:visual script if chrome-visual-check.sh was installed
+  if (installedScripts.includes('chrome-visual-check.sh') || fs.existsSync(path.join(targetDir, 'scripts', 'chrome-visual-check.sh'))) {
+    if (pkgJson.scripts['chrome:visual']) {
+      skipped.push('chrome:visual');
+      console.log(`  ${yellow}⚠${reset} Skipped npm script "chrome:visual" (already exists)`);
+    } else {
+      pkgJson.scripts['chrome:visual'] = 'bash scripts/chrome-visual-check.sh';
+      added.push('chrome:visual');
+      console.log(`  ${green}✓${reset} Added npm script "chrome:visual"`);
+    }
+  }
+
+  // Add sessions:index script if index-sessions.sh was installed
+  if (installedScripts.includes('index-sessions.sh') || fs.existsSync(path.join(targetDir, 'scripts', 'index-sessions.sh'))) {
+    if (pkgJson.scripts['sessions:index']) {
+      skipped.push('sessions:index');
+      console.log(`  ${yellow}⚠${reset} Skipped npm script "sessions:index" (already exists)`);
+    } else {
+      pkgJson.scripts['sessions:index'] = 'bash scripts/index-sessions.sh';
+      added.push('sessions:index');
+      console.log(`  ${green}✓${reset} Added npm script "sessions:index"`);
+    }
+  }
+
   // Write back if we added anything
   if (added.length > 0) {
     fs.writeFileSync(pkgPath, JSON.stringify(pkgJson, null, 2) + '\n');

package/commands/rrr/add-phase.md

@@ -111,11 +111,12 @@ Before creating any phase, validate:
 
 2. **Check for orphan phases:**
 
-   Count phases in `.planning/phases/` that are not assigned to any milestone in ROADMAP.md.
+   Count phases in the active milestone that are not assigned in ROADMAP.md.
 
    ```bash
-   # List phase directories
-   PHASE_DIRS=$(ls -d .planning/phases/*/ 2>/dev/null | wc -l)
+   # List phase directories (check both new and legacy locations)
+   PHASE_BASE=$(get_phase_base_dir)
+   PHASE_DIRS=$(ls -d "$PHASE_BASE"/*/ 2>/dev/null | wc -l)
 
    # Count phases in ROADMAP.md (look for "### Phase N:")
    ROADMAP_PHASES=$(grep -c "^### Phase" .planning/ROADMAP.md 2>/dev/null || echo "0")
@@ -358,7 +359,7 @@ Phase addition is complete when:
 
 - [ ] Active milestone exists before allowing phase creation
 - [ ] No orphan phases exist before allowing phase creation
-- [ ] Phase directory created: `.planning/phases/{NN}-{slug}/`
+- [ ] Phase directory created in MILESTONE: `.planning/milestones/v{X.Y}/phases/{NN}-{slug}/`
 - [ ] Roadmap updated with new phase entry
 - [ ] STATE.md updated with roadmap evolution note
 - [ ] New phase appears at end of current milestone

package/commands/rrr/audit-milestone.md

@@ -33,8 +33,8 @@ Version: $ARGUMENTS (optional — defaults to current milestone)
 @.planning/config.json (if exists)
 
 **Completed Work:**
-Glob: .planning/phases/*/*-SUMMARY.md
-Glob: .planning/phases/*/*-VERIFICATION.md
+Glob: .planning/milestones/vX.Y/phases/*/*-SUMMARY.md
+Glob: .planning/milestones/vX.Y/phases/*/*-VERIFICATION.md
 </context>
 
 <process>
@@ -42,8 +42,9 @@ Glob: .planning/phases/*/*-VERIFICATION.md
 ## 1. Determine Milestone Scope
 
 ```bash
-# Get phases in milestone
-ls -d .planning/phases/*/ | sort -V
+# Get phases in milestone - use milestone-aware path
+PHASE_BASE=$(get_phase_base_dir)
+ls -d "$PHASE_BASE"/*/ | sort -V
 ```
 
 - Parse version from arguments or detect current from ROADMAP.md
@@ -56,8 +57,8 @@ ls -d .planning/phases/*/ | sort -V
 For each phase directory, read the VERIFICATION.md:
 
 ```bash
-cat .planning/phases/01-*/*-VERIFICATION.md
-cat .planning/phases/02-*/*-VERIFICATION.md
+cat "$PHASE_BASE"/01-*/*-VERIFICATION.md
+cat "$PHASE_BASE"/02-*/*-VERIFICATION.md
 # etc.
 ```
 

package/commands/rrr/create-roadmap.md

@@ -130,7 +130,7 @@ Roadmap created:
 <output>
 - `.planning/ROADMAP.md`
 - `.planning/STATE.md`
-- `.planning/phases/XX-name/` directories
+- `.planning/milestones/vX.Y/phases/XX-name/` directories
 </output>
 
 <success_criteria>

package/commands/rrr/execute-phase.md

@@ -341,7 +341,7 @@ All phase goals verified ✓
 **Phase {Z}: {Name}**
 
 Score: {N}/{M} must-haves verified
-Report: `.planning/phases/{phase_dir}/{phase}-VERIFICATION.md`
+Report: `{phase_dir}/{phase}-VERIFICATION.md`
 
 ### What's Missing
 
@@ -360,7 +360,7 @@ Report: `.planning/phases/{phase_dir}/{phase}-VERIFICATION.md`
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
-- `cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md` — see full report
+- `cat {phase_dir}/{phase}-VERIFICATION.md` — see full report
 - `/rrr:verify-work {Z}` — manual testing before planning
 
 ───────────────────────────────────────────────────────────────

package/commands/rrr/execute-plan.md

@@ -144,7 +144,7 @@ Plan path: $ARGUMENTS
       Generated via `--summary-only` flag after preflight confirmed all deliverables present.
       ```
 
-   4. Write to: `.planning/phases/{phase}/{plan_id}-SUMMARY.md`
+   4. Write to: `.planning/milestones/vX.Y/phases/{phase}/{plan_id}-SUMMARY.md`
 
    5. Update STATE.md to reflect completion
 
@@ -153,7 +153,7 @@ Plan path: $ARGUMENTS
       ✓ SUMMARY.md generated (summary-only mode)
 
       Plan: {plan_id}
-      Path: .planning/phases/{phase}/{plan_id}-SUMMARY.md
+      Path: .planning/milestones/vX.Y/phases/{phase}/{plan_id}-SUMMARY.md
 
       No execution performed — existing work documented.
       ```

package/commands/rrr/fix-visual-failure.md

@@ -1,10 +1,30 @@
 ---
 name: rrr:fix-visual-failure
 description: Analyze visual proof failures and suggest fixes
+deprecated: true
 ---
 
+<!--
+DEPRECATED: This command is now integrated into /rrr:verify-work --uat
+
+The diagnose-issues workflow (called after UAT finds gaps) now includes
+visual artifact discovery and failure categorization. This provides:
+- Automatic discovery of Playwright logs, diff images, UAT screenshots
+- Failure type categorization (Page Load, Screenshot Diff, Timeout, etc.)
+- Enriched context for debug agents investigating gaps
+
+For visual testing workflows, use:
+- `/rrr:verify-work --uat` — runs UAT, diagnoses failures inline
+- `/rrr:debug` — for standalone debugging of specific issues
+
+Deprecated: 2026-01-25
+-->
+
 <objective>
-Analyze the most recent visual proof failure and provide diagnosis with targeted fix suggestions.
+**DEPRECATED:** Use `/rrr:verify-work --uat` instead.
+
+This command analyzed visual proof failures. Its functionality is now
+integrated into the diagnose-issues workflow called by verify-work --uat.
 </objective>
 
 <behavior>

package/commands/rrr/help.md

@@ -220,13 +220,13 @@ Usage: `/rrr:list-phase-assumptions 3`
 **`/rrr:plan-phase <number>`**
 Create detailed execution plan for a specific phase.
 
-- Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
+- Generates `.planning/milestones/v{X.Y}/phases/XX-phase-name/XX-YY-PLAN.md`
 - Breaks phase into concrete, actionable tasks
 - Includes verification criteria and success measures
 - Multiple plans per phase supported (XX-01, XX-02, etc.)
 
 Usage: `/rrr:plan-phase 1`
-Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
+Result: Creates `.planning/milestones/v1.0/phases/01-foundation/01-01-PLAN.md`
 
 ### Execution
 
@@ -238,7 +238,7 @@ Execute a single PLAN.md file.
 - Updates STATE.md with accumulated context
 - Use for interactive execution with checkpoints
 
-Usage: `/rrr:execute-plan .planning/phases/01-foundation/01-01-PLAN.md`
+Usage: `/rrr:execute-plan .planning/milestones/v1.0/phases/01-foundation/01-01-PLAN.md`
 
 **`/rrr:execute-phase <phase-number>`**
 Execute all unexecuted plans in a phase with parallel background agents.
@@ -777,7 +777,7 @@ verification:
 **Reviewing HITL phases after Pushpa:**
 ```
 /rrr:progress  # Shows pending HITL phases
-/rrr:execute-plan .planning/phases/05-deploy/05-03-PLAN.md  # Execute interactively
+/rrr:execute-plan .planning/milestones/v1.0/phases/05-deploy/05-03-PLAN.md  # Execute interactively
 ```
 
 **Verification Ladder**
@@ -1000,7 +1000,7 @@ FRONTEND_IMPACT=true bash scripts/browser-uat.sh
 ```
 /rrr:insert-phase 5 "Critical security fix"
 /rrr:plan-phase 5.1
-/rrr:execute-plan .planning/phases/05.1-critical-security-fix/05.1-01-PLAN.md
+/rrr:execute-plan .planning/milestones/v1.0/phases/05.1-critical-security-fix/05.1-01-PLAN.md
 ```
 
 **Completing a milestone:**
@@ -1181,6 +1181,48 @@ bash scripts/vendor-droid-tings-skills.sh --list           # See available
 DROID_TINGS_ALLOWLIST="axolotl,unsloth" bash scripts/vendor-droid-tings-skills.sh
 ```
 
+## Drift Prevention
+
+**Core Principle:** If it's not part of a plan, it doesn't get worked on. All work must be tracked.
+
+RRR includes a Drift Guard that activates when:
+1. `.planning/STATE.md` exists (RRR is initialized)
+2. You request code changes (add, fix, update, create, implement, etc.)
+3. There's no active plan context
+
+**What happens:** Claude detects you're "between phases" and asks how to proceed:
+
+| Project State | What Drift Guard Asks |
+|---------------|----------------------|
+| **mid_plan** | Resume incomplete plan or start something new? |
+| **mid_phase** | Is this part of an existing plan, urgent insert, or new work? Work must attach to a PLAN.md. |
+| **post_milestone** | Small fix (patch), medium feature (add phase), or large work (new milestone)? |
+| **between_milestones** | Start new milestone, hotfix previous, or capture as TODO? |
+| **between_phases** | Part of next phase, urgent fix for previous, or new scope? |
+| **pre_planning** | Plan the phase first, discuss context, or create quick single-task plan? |
+
+**Routing options:**
+- **Add to existing plan** — Route to `/rrr:execute-plan`
+- **Insert hotfix** — Route to `/rrr:insert-phase` (creates decimal phase like 5.1)
+- **Add new plan** — Route to `/rrr:plan-phase` with `--add`
+- **Capture as TODO** — Route to `/rrr:add-todo`
+- **Override (proceed anyway)** — Logged to STATE.md for accountability
+
+**Small changes:** For typo fixes and tiny adjustments, you can proceed with an override. These are logged but don't require full plan overhead.
+
+**Why this matters:**
+- Prevents work from falling through the cracks
+- Ensures all changes are traceable to requirements
+- Makes `/rrr:progress` accurate
+- Enables proper milestone completion tracking
+
+**Check your drift guard status:**
+```
+/rrr:progress
+```
+
+Shows current state and whether drift protection is active.
+
 ## Getting Help
 
 - Read `.planning/PROJECT.md` for project vision

package/commands/rrr/insert-phase.md

@@ -117,11 +117,12 @@ Before creating any phase, validate:
 
 2. **Check for orphan phases:**
 
-   Count phases in `.planning/phases/` that are not assigned to any milestone in ROADMAP.md.
+   Count phases in the active milestone that are not assigned in ROADMAP.md.
 
    ```bash
-   # List phase directories
-   PHASE_DIRS=$(ls -d .planning/phases/*/ 2>/dev/null | wc -l)
+   # List phase directories (check both new and legacy locations)
+   PHASE_BASE=$(get_phase_base_dir)
+   PHASE_DIRS=$(ls -d "$PHASE_BASE"/*/ 2>/dev/null | wc -l)
 
    # Count phases in ROADMAP.md (look for "### Phase N:")
    ROADMAP_PHASES=$(grep -c "^### Phase" .planning/ROADMAP.md 2>/dev/null || echo "0")
@@ -361,7 +362,7 @@ Phase insertion is complete when:
 
 - [ ] Active milestone exists before allowing phase creation
 - [ ] No orphan phases exist before allowing phase creation
-- [ ] Phase directory created: `.planning/phases/{N.M}-{slug}/`
+- [ ] Phase directory created in MILESTONE: `.planning/milestones/v{X.Y}/phases/{N.M}-{slug}/`
 - [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
 - [ ] Phase inserted in correct position (after target phase, before next integer phase)
 - [ ] STATE.md updated with roadmap evolution note

package/commands/rrr/new-milestone.md

@@ -43,6 +43,71 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    - Read STATE.md (pending todos, blockers)
    - Check for MILESTONE-CONTEXT.md (from /rrr:discuss-milestone)
 
+1.1. **Close patches from previous milestone:**
+
+   Check if the previous milestone has any patches that need to be closed.
+
+   ```bash
+   # Find the most recent milestone folder
+   PREV_MILESTONE=$(ls -d .planning/milestones/v*/ 2>/dev/null | sort -V | tail -1 | xargs basename)
+   echo "Previous milestone: $PREV_MILESTONE"
+
+   # Check if PATCHES.md exists and has actual patch entries (not just template)
+   PATCHES_FILE=".planning/milestones/${PREV_MILESTONE}/PATCHES.md"
+   if [ -f "$PATCHES_FILE" ]; then
+     # Check if it has actual patch entries (## v*.* - pattern)
+     PATCH_COUNT=$(grep -c "^## v[0-9]" "$PATCHES_FILE" 2>/dev/null || echo "0")
+     echo "Patches found: $PATCH_COUNT"
+   fi
+   ```
+
+   **If patches exist (PATCH_COUNT > 0):**
+
+   Present patch summary and close them:
+
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   CLOSING PATCHES FROM {PREV_MILESTONE}
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   The following patches were shipped for {PREV_MILESTONE}:
+
+   {List patch titles from PATCHES.md}
+
+   These will be marked as CLOSED since we're starting a new milestone.
+   ```
+
+   Update the PATCHES.md file header:
+
+   ```bash
+   # Add CLOSED status header to PATCHES.md
+   # Insert after the first line (title)
+   ```
+
+   Change the file to add a status header:
+
+   ```markdown
+   # v{X.Y} Patch Releases
+
+   **Status:** ✅ CLOSED (superseded by v{NEW_VERSION})
+   **Patches shipped:** {PATCH_COUNT}
+   **Closed:** {TODAY}
+
+   ---
+
+   [rest of file unchanged]
+   ```
+
+   Commit the closure:
+
+   ```bash
+   git add "$PATCHES_FILE"
+   git commit -m "docs: close v${PREV_MILESTONE} patches (starting v{NEW_VERSION})"
+   ```
+
+   **If no patches (PATCH_COUNT = 0 or file doesn't exist):**
+   - Skip silently, continue to step 1.5
+
 1.5. **Version consistency check (MANDATORY):**
 
    Before writing any milestone files, verify version consistency.
@@ -212,6 +277,7 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 </process>
 
 <success_criteria>
+- Previous milestone patches closed (if any existed)
 - PROJECT.md updated with Current Milestone section
 - Active requirements reflect new milestone goals
 - STATE.md reset for new milestone

package/commands/rrr/new-project.md

@@ -63,7 +63,7 @@ This is the most leveraged moment in any project. Deep questioning here means be
 - `.planning/REQUIREMENTS.md` — scoped requirements
 - `.planning/ROADMAP.md` — phase structure
 - `.planning/STATE.md` — project memory
-- `.planning/phases/` — phase directories
+- `.planning/milestones/v{X.Y}/phases/` — phase directories (under each milestone)
 
 **After this command:** Run `/rrr:plan-phase 1` to start execution.
 
@@ -1576,7 +1576,7 @@ Configure Claude Code with MCP servers for your selected stack:
 - `.planning/REQUIREMENTS.md`
 - `.planning/ROADMAP.md`
 - `.planning/STATE.md`
-- `.planning/phases/XX-name/` directories
+- `.planning/milestones/vX.Y/phases/XX-name/` directories
 
 </output>
 

package/commands/rrr/pause-work.md

@@ -38,7 +38,7 @@ Ask user for clarifications if needed.
 </step>
 
 <step name="write">
-**Write handoff to `.planning/phases/XX-name/.continue-here.md`:**
+**Write handoff to `.planning/milestones/vX.Y/phases/XX-name/.continue-here.md`:**
 
 ```markdown
 ---
@@ -91,14 +91,14 @@ Be specific enough for a fresh Claude to understand immediately.
 
 <step name="commit">
 ```bash
-git add .planning/phases/*/.continue-here.md
+git add .planning/milestones/**/phases/*/.continue-here.md
 git commit -m "wip: [phase-name] paused at task [X]/[Y]"
 ```
 </step>
 
 <step name="confirm">
 ```
-✓ Handoff created: .planning/phases/[XX-name]/.continue-here.md
+✓ Handoff created: .planning/milestones/vX.Y/phases/[XX-name]/.continue-here.md
 
 Current state:
 

package/commands/rrr/plan-milestone-gaps.md

@@ -95,7 +95,9 @@ Gap: Flow "View dashboard" broken at data fetch
 
 Find highest existing phase:
 ```bash
-ls -d .planning/phases/*/ | sort -V | tail -1
+# Use milestone-aware path
+PHASE_BASE=$(get_phase_base_dir)
+ls -d "$PHASE_BASE"/*/ | sort -V | tail -1
 ```
 
 New phases continue from there: