projecta-rrr 1.16.4 → 1.16.6

package/CHANGELOG.md

@@ -4,6 +4,49 @@ 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.6] - 2026-01-28
+
+### Added
+- **Proactive Progress Routing** - Enhanced `/rrr:progress` to ask clarifying questions:
+  - **Route C** (phase complete): Asks "Continue to next phase?", "Discuss first?", or "Different work?"
+  - **Route F.1** (between milestones with context): Asks "Create milestone now?", "Discuss more?", or "Quick fix?"
+  - **Route F.2** (between milestones no context): Asks about work scope (quick fix, new feature, new milestone)
+  - Routes based on user intent, not just sequential progression
+
+### Changed
+- **Progress command now uses AskUserQuestion** for all decision points instead of just presenting options
+- Clearer guidance for Patch vs Phase vs Milestone decisions at milestone boundaries
+
+## [1.16.5] - 2026-01-28
+
+### Fixed
+- **Verify-Work UAT Workflow Path** - Fixed workflow file loading for UAT mode:
+  - Changed from relative path (`rrr/workflows/verify-work.md`) to `@` reference (`@rrr/workflows/verify-work.md`)
+  - Workflow now loads correctly from RRR framework (`~/.claude/rrr/workflows/verify-work.md`)
+- **Milestone-Level UAT Support** - Added comprehensive milestone support:
+  - Detects milestone targets (`v1.2`, `v2.0`) and finds all phases in that milestone
+  - Creates UAT file at `.planning/milestones/{milestone}/phases/{milestone}-UAT.md`
+  - Updates frontmatter with `target_type` (phase/milestone) and `target`
+  - Fixed commit message generation for milestone-level UAT
+- **PHASE_ARG Variable Propagation** - Added export of `PHASE_ARG` for workflow consumption
+- **SUMMARY Path Detection** - Fixed test type detection to search both old and new directory structures
+- **UAT File Discovery** - Updated active session detection to search `.planning/` recursively
+
+### Added
+- **Project State Decision Tree** - New reference document at `rrr/references/project-state-flow.md`:
+  - Visual state machine diagram showing all project states and transitions
+  - Decision tables for each state (Between Milestones, Active Milestone, Active Phase, Phase Complete, Milestone Complete)
+  - Quick reference: which command to use for each scenario
+  - Patch vs Phase vs Milestone comparison guide
+  - Decimal phase semantics explained
+
+### Changed
+- **Proactive Progress Routing** - Enhanced `/rrr:progress` command to ask clarifying questions:
+  - **Route C** (phase complete): Asks "Continue to next phase?", "Discuss first?", or "Different work?"
+  - **Route F.1** (between milestones with context): Asks "Create milestone now?", "Discuss more?", or "Quick fix?"
+  - **Route F.2** (between milestones no context): Asks about work scope (quick fix, new feature, new initiative)
+  - Clear routing based on user intent rather than assuming sequential progression
+
 ## [1.16.4] - 2026-01-27
 
 ### Fixed

package/commands/rrr/progress.md

@@ -461,20 +461,60 @@ Include audit summary in output (if run).
 
 Full report: .planning/artifacts/VERIFY_WORK_AUDIT.md
 
-## ▶ Next Up
+<AskUserQuestion>
+<questions>
+[
+  {
+    "question": "Phase {Z} is complete. What's next?",
+    "header": "Next",
+    "options": [
+      {
+        "label": "Continue to Phase {Z+1}",
+        "description": "Execute next phase in current milestone"
+      },
+      {
+        "label": "Discuss Phase {Z+1} first",
+        "description": "Gather context before planning (recommended for UI/UX)"
+      },
+      {
+        "label": "Actually, different work",
+        "description": "Maybe a patch, or skip to another phase?"
+      }
+    ]
+  }
+]
+</questions>
+</AskUserQuestion>
 
-**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
+---
 
-`/rrr:plan-phase {Z+1}`
+**Based on response:**
 
-<sub>`/clear` first → fresh context window</sub>
+| Response | Action | Command |
+|----------|--------|---------|
+| Continue to Phase {Z+1} | Plan and execute | `/rrr:plan-phase {Z+1}` |
+| Discuss first | Gather context | `/rrr:discuss-phase {Z+1}` |
+| Different work | Clarify intent | Present options (patch, skip phase, complete milestone) |
+
+**For "Actually, different work" response:**
+```
+## → What would you like to work on instead?
+
+**Options:**
+
+1. **Quick fix/patch** — `/rrr:insert-phase` as decimal (e.g., {Z}.1)
+2. **Skip to different phase** — `/rrr:execute-phase {XX}`
+3. **Complete milestone** — All remaining phases done? `/rrr:complete-milestone`
+4. **Different scope entirely** — Between milestones? `/rrr:discuss-milestone`
+
+What type of work did you have in mind?
+```
 
 ---
 
 **Also available:**
 - `/rrr:verify-work --uat {Z}` — user acceptance test before continuing
 - `/rrr:verify-work --audit` — full implementation audit
-- `/rrr:discuss-phase {Z+1}` — gather context first
 
 ---
 ```
@@ -560,19 +600,40 @@ Key features from discussion:
 - [feature 2]
 - [feature 3]
 
-## ▶ Next Up
-
-**Create the milestone** — formalize what you discussed
-
-`/rrr:new-milestone`
-
-<sub>`/clear` first → fresh context window</sub>
+<AskUserQuestion>
+<questions>
+[
+  {
+    "question": "Ready to formalize this milestone, or want to discuss more?",
+    "header": "Milestone",
+    "options": [
+      {
+        "label": "Create milestone now",
+        "description": "Formalize vX.(Y+1) with requirements and roadmap"
+      },
+      {
+        "label": "Discuss more first",
+        "description": "Continue the discussion, add more context"
+      },
+      {
+        "label": "Actually, it's a quick fix",
+        "description": "This is just a patch, not a new milestone"
+      }
+    ]
+  }
+]
+</questions>
+</AskUserQuestion>
 
 ---
 
-**Also available:**
-- `/rrr:discuss-milestone` — continue the discussion
-- `/rrr:verify-work --audit` — audit completed work
+**Based on response:**
+
+| Response | Action | Command |
+|----------|--------|---------|
+| Create milestone now | Formalize vX.(Y+1) | `/rrr:new-milestone` |
+| Discuss more | Continue discussion | `/rrr:discuss-milestone` |
+| Quick fix | Create patch | `/rrr:insert-phase` (decimal) |
 
 ---
 ```
@@ -612,29 +673,99 @@ Full report: .planning/artifacts/VERIFY_WORK_AUDIT.md
 
 ---
 
-## What's Next?
+## What would you like to do next?
 
-**Choose based on scope of work:**
+<AskUserQuestion>
+<questions>
+[
+  {
+    "question": "What's the scope of your next piece of work?",
+    "header": "Scope",
+    "options": [
+      {
+        "label": "Quick fix/hotfix",
+        "description": "Bug fix, small tweak, or one-line change → Creates a PATCH (vX.Y.1)"
+      },
+      {
+        "label": "New feature (current milestone)",
+        "description": "Fits current milestone scope → Creates a new PHASE in vX.Y"
+      },
+      {
+        "label": "New initiative (new milestone)",
+        "description": "New scope, capabilities, or requirements → Creates MILESTONE vX.(Y+1)"
+      }
+    ]
+  }
+]
+</questions>
+</AskUserQuestion>
 
-### Small Work → Track as Patch
-Bugs, hotfixes, small improvements belong in v{X.Y} as patches.
-- Document in `.planning/milestones/v{X.Y}/PATCHES.md`
-- Commit with `fix:` or `chore:` prefix
-- Bump patch version (v{X.Y}.1, v{X.Y}.2, etc.)
-- No formal phase/plan needed
+---
 
-### Larger Scope → Start New Milestone
-Features, multi-file changes, new capabilities need proper planning.
+**Based on response, route accordingly:**
 
----
+| Response | Action | Command |
+|----------|--------|---------|
+| Quick fix/hotfix | Create decimal phase as patch | `/rrr:insert-phase` (decimal like 9.1) |
+| New feature | Add phase to current milestone | `/rrr:add-phase` |
+| New initiative | Discuss and create milestone | `/rrr:discuss-milestone` |
 
-## ▶ Next Up (for new milestone)
+**For "Quick fix/hotfix" response:**
+```
+## → Creating a Patch (v{X.Y}.1)
 
-**Discuss what to build next** — thinking partner for next milestone
+Quick fixes don't need full phase/plan structure.
 
-`/rrr:discuss-milestone`
+**To create a patch:**
+1. `/rrr:insert-phase` — I'll insert as decimal phase (e.g., {current_phase}.1)
+2. This creates a minimal phase directory for tracking
+3. Or simply commit directly with `fix:` prefix — patches are documented in PATCHES.md
 
-<sub>`/clear` first → fresh context window</sub>
+**Patch vs Phase Decision Guide:**
+- Patch: Hours of work, 1-2 files changed, bug fix
+- Phase: Days of work, multiple files, feature addition
+
+Want me to create a decimal phase for this patch?
+```
+
+**For "New feature (current milestone)" response:**
+```
+## → Adding Phase to v{X.Y}
+
+**Current phases in v{X.Y}:**
+- [list phases from ROADMAP.md]
+
+**To add a new phase:**
+`/rrr:add-phase` — I'll ask for phase number and description
+
+**Phase Naming:**
+- Next sequential: {next_phase_num}
+- Or specify custom number
+
+Ready to add the phase?
+```
+
+**For "New initiative (new milestone)" response:**
+```
+## → Starting New Milestone v{X.(Y+1)}
+
+**To begin a new milestone:**
+
+1. **Discuss first** (recommended): `/rrr:discuss-milestone`
+   - Thinking partner for next scope
+   - Creates MILESTONE-CONTEXT.md with decisions
+   - Then `/rrr:new-milestone` formalizes it
+
+2. **Skip discussion**: `/rrr:new-milestone`
+   - Directly creates milestone structure
+   - Less context gathered upfront
+
+**New Milestone vs Patch Decision Guide:**
+- New Milestone: New capabilities, integrations, multi-sprint work
+- Patch: Quick fixes, small improvements, bug fixes
+
+How would you like to proceed?
+```
 
 ---
 

package/commands/rrr/verify-work.md

@@ -86,6 +86,14 @@ Validate built features through **audit mode by default**, or interactive UAT wi
 hasAuditFlag = $ARGUMENTS contains "--audit"
 hasUatFlag = $ARGUMENTS contains "--uat"
 target = $ARGUMENTS with flags removed (e.g., "05", "v1.9", or empty)
+
+# Set PHASE_ARG for workflow consumption (UAT mode needs this)
+if [ -n "$target" ]; then
+  PHASE_ARG="$target"
+else
+  PHASE_ARG=""
+fi
+export PHASE_ARG
 ```
 
 **Step 2: Route and explain selection**
@@ -98,6 +106,7 @@ target = $ARGUMENTS with flags removed (e.g., "05", "v1.9", or empty)
 **If --uat is present:**
 1. Execute the `<uat_mode>` section below
 2. This loads the workflow file which runs component tests then UAT
+3. The workflow uses `$PHASE_ARG` to find summaries
 
 **If --audit is present OR no flags:**
 1. Execute the `<audit_mode>` section below (DEFAULT)
@@ -331,9 +340,9 @@ Purpose: Component tests → Zeroshot/Manual user acceptance testing
 For quick evidence check, use: /rrr:verify-work --audit
 ```
 
-**Load the workflow to run UAT:**
+**Load the UAT workflow:**
 
-Read the file at: `rrr/workflows/verify-work.md`
+@rrr/workflows/verify-work.md
 
 The workflow contains the full UAT process including:
 1. **Component tests** — Runs vitest --browser if configured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.16.4",
+  "version": "1.16.6",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by Projecta.ai",
   "bin": {
     "projecta-rrr": "bin/install.js"

package/rrr/references/project-state-flow.md

@@ -0,0 +1,208 @@
+# Project State Decision Tree
+
+Comprehensive decision guide for all project states and transitions in RRR.
+
+## State Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        RRR PROJECT STATE MACHINE                            │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                              ┌─────────────────┐
+                              │   START/NEW     │
+                              │    PROJECT      │
+                              └────────┬────────┘
+                                       │
+                                       ▼
+                    ┌──────────────────────────────────┐
+                    │     Between Milestones           │
+                    │  Milestone: Between milestones   │
+                    │  Phase: N/A                      │
+                    └──────────┬───────────────────────┘
+                               │
+            ┌──────────────────┼──────────────────┐
+            │                  │                  │
+            ▼                  ▼                  ▼
+    ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐
+    │ Discuss      │  │ Quick Fix    │  │ Skip Discussion  │
+    │ Milestone    │  │ (Patch)      │  │ Direct Milestone │
+    └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘
+           │                 │                    │
+           ▼                 ▼                    ▼
+    ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐
+    │ New Milestone│  │ Add Decimal  │  │ New Milestone    │
+    │ vX.(Y+1)     │  │ Phase (9.1)  │  │ vX.(Y+1)         │
+    └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘
+           │                 │                    │
+           └─────────────────┼────────────────────┘
+                             ▼
+                    ┌──────────────────┐
+                    │   Active         │
+                    │   Milestone      │
+                    │   vX.Y           │
+                    └────────┬─────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │              │              │
+              ▼              ▼              ▼
+      ┌────────────┐ ┌────────────┐ ┌──────────────────┐
+      │ Add Phase  │ │ Execute    │ │ Complete         │
+      │ (X+1)      │ │ Phase      │ │ Milestone        │
+      └──────┬─────┘ └─────┬──────┘ └────────┬─────────┘
+             │             │                 │
+             │             ▼                 │
+             │    ┌──────────────────┐       │
+             │    │   Active Phase   │       │
+             │    │   XX-name        │       │
+             │    └────────┬─────────┘       │
+             │             │                 │
+             │    ┌────────┼────────┐        │
+             │    │        │        │        │
+             │    ▼        ▼        ▼        │
+             │ ┌──────┐ ┌──────┐ ┌───────┐  │
+             │ │ Add  │ │ Pause │ │ Next  │  │
+             │ │Sub   │ │/Defer │ │ Phase │  │
+             │ │Phase │ │       │ │       │  │
+             │ └──┬───┘ └──┬───┘ └───┬───┘  │
+             │    │        │         │       │
+             │    ▼        ▼         ▼       │
+             │    ┌─────────────────────┐    │
+             └────│  Phase Complete     │◄───┘
+                  │  (SUMMARY.md exists)│
+                  └──────────┬──────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │              │              │
+              ▼              ▼              ▼
+      ┌────────────┐ ┌────────────┐ ┌──────────────────┐
+      │ Next Phase │ │ Different  │ │ Complete         │
+      │ (X+1)      │ │ Phase      │ │ Milestone        │
+      └──────┬─────┘ └─────┬──────┘ └────────┬─────────┘
+             │             │                 │
+             │             └────────┬────────┘
+             │                      │
+             └──────────────────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │  Milestone Complete  │
+                  │  All phases done     │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │  Between Milestones  │
+                  └──────────────────────┘
+```
+
+## State Definitions
+
+| State | Trigger | Exit Condition | Next States |
+|-------|---------|----------------|-------------|
+| **Between Milestones** | Milestone completion | User starts new work | Active Milestone, Patch Phase |
+| **Active Milestone** | New milestone created | All phases complete | Milestone Complete |
+| **Active Phase** | Phase execution starts | SUMMARY.md written | Phase Complete |
+| **Phase Complete** | Phase finishes | User continues | Next Phase, Different Phase, Complete Milestone |
+| **Milestone Complete** | All phases done | User starts new | Between Milestones |
+
+## Decision Trees by Current State
+
+### 1. From "Between Milestones"
+
+**Question:** "What do you want to work on?"
+
+| Answer | Classification | Action | Command |
+|--------|---------------|--------|---------|
+| "New feature/initiative" | New Scope | Create milestone vX.(Y+1) | `/rrr:discuss-milestone` |
+| "Bug fix / small change" | Patch | Create decimal phase (e.g., 9.1) | `/rrr:insert-phase` |
+| "Already know what I want" | Direct | Skip discussion, create milestone | `/rrr:new-milestone` |
+| "Not sure" | Uncertain | Offer discussion options | `/rrr:discuss-milestone` |
+
+### 2. From "Active Milestone"
+
+**Question:** "What's next for this milestone?"
+
+| Answer | Classification | Action | Command |
+|--------|---------------|--------|---------|
+| "Continue current phase" | Continue | Execute phase in STATE.md | `/rrr:execute-phase` |
+| "Add new phase" | Expand | Create phase in current milestone | `/rrr:add-phase` |
+| "Finish milestone" | Complete | Audit → Complete milestone | `/rrr:complete-milestone` |
+| "Move to next milestone" | Defer | Complete current, start new | `/rrr:complete-milestone` |
+
+### 3. From "Active Phase"
+
+**Question:** "What do you want to do with this phase?"
+
+| Answer | Classification | Action | Command |
+|--------|---------------|--------|---------|
+| "Keep working" | Continue | Resume execution | `/rrr:execute-phase` |
+| "Add sub-work" | Expand | Decimal phase (e.g., 5.1) | `/rrr:insert-phase` |
+| "Pause/defer" | Pause | Set Phase: N/A in STATE.md | Edit STATE.md |
+| "Done early" | Complete | Write SUMMARY.md | `/rrr:execute-phase` → checkpoint |
+
+### 4. From "Phase Complete"
+
+**Question:** "Where to next?"
+
+| Answer | Classification | Action | Command |
+|--------|---------------|--------|---------|
+| "Next numbered phase" | Sequential | Execute X+1 | `/rrr:execute-phase` |
+| "Different phase" | Non-sequential | Execute specific phase | `/rrr:execute-phase XX` |
+| "Finish milestone" | Milestone | Complete milestone | `/rrr:complete-milestone` |
+
+### 5. From "Milestone Complete"
+
+**Question:** "What's next?"
+
+| Answer | Classification | Action | Command |
+|--------|---------------|--------|---------|
+| "New milestone" | New Scope | Create vX.(Y+1) | `/rrr:discuss-milestone` |
+| "Quick fix" | Patch | Decimal phase (9.1) | `/rrr:insert-phase` |
+| "Just checking" | Idle | Stay between milestones | No action |
+
+## Quick Reference: Which Command?
+
+| Scenario | Command |
+|----------|---------|
+| Start fresh project | `/rrr:new-project` |
+| Discuss next milestone | `/rrr:discuss-milestone` |
+| Create milestone directly | `/rrr:new-milestone` |
+| Add phase to current milestone | `/rrr:add-phase` |
+| Insert between phases (or patch) | `/rrr:insert-phase` |
+| Execute current phase | `/rrr:execute-phase` |
+| Execute specific phase | `/rrr:execute-phase XX` |
+| Check milestone readiness | `/rrr:audit-milestone` |
+| Archive milestone | `/rrr:complete-milestone` |
+| Check current state | `/rrr:progress` |
+
+## Decimal Phase Semantics
+
+| Phase Number | Meaning | Use Case |
+|--------------|---------|----------|
+| `05` | Main phase | Standard milestone phase |
+| `05.1` | First patch | Bug fix after milestone complete |
+| `05.2` | Second patch | Additional quick fix |
+| `05.01` | Sub-phase | Work within a phase (less common) |
+
+## Patch vs Phase vs Milestone
+
+| Type | Version | Scope | Duration | When to Use |
+|------|---------|-------|----------|-------------|
+| **Patch** | vX.Y.1 | 1-2 files | Hours | Bug fixes, small tweaks |
+| **Phase** | vX.(Y+1) | 1-3 plans | Days | Feature additions, refactors |
+| **Milestone** | vX.(Y+1) | Multiple phases | Weeks | New capabilities, integrations |
+
+## Error Recovery
+
+| Problem | Solution |
+|---------|----------|
+| Stuck in wrong state | Edit STATE.md directly |
+| Phases in wrong location | `/rrr:doctor --phases` → cleanup |
+| Missing milestone marker | Create ROADMAP.md with current milestone |
+| Orphaned phases | `/rrr:migrate-phases` |
+
+---
+
+*Reference: rrr/workflows/progress.md*
+*Version: 1.0*

package/rrr/workflows/verify-work.md

@@ -237,7 +237,8 @@ Based on what's available, calculate the recommended mode:
 
 ```bash
 # Check SUMMARY.md content to determine test type
-SUMMARY_CONTENT=$(cat .planning/phases/*/phases/*-SUMMARY.md 2>/dev/null | head -100)
+# Search in both old (.planning/phases/*/) and new (.planning/milestones/*/phases/*/) structures
+SUMMARY_CONTENT=$(cat .planning/phases/*/*-SUMMARY.md .planning/milestones/*/phases/*/*-SUMMARY.md 2>/dev/null | head -100)
 
 if echo "$SUMMARY_CONTENT" | grep -qiE "(ui|page|screen|button|form|input|click|navigation|redirect|layout|visual|interface)"; then
   TEST_TYPE="WEB_UI"
@@ -306,34 +307,35 @@ Proceed to `check_active_session`.
 **First: Check for active UAT sessions**
 
 ```bash
-find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5
+# Search for UAT files in both old (.planning/phases/) and new (.planning/milestones/*/phases/) structures
+UAT_FILES=$(find .planning -name "*-UAT.md" -type f 2>/dev/null | head -10)
 ```
 
 **If active sessions exist AND no $ARGUMENTS provided:**
 
-Read each file's frontmatter (status, phase) and Current Test section.
+Read each file's frontmatter (status, target, target_type) and Current Test section.
 
 Display inline:
 
 ```
 ## Active UAT Sessions
 
-| # | Phase | Status | Current Test | Progress |
-|---|-------|--------|--------------|----------|
-| 1 | 04-comments | testing | 3. Reply to Comment | 2/6 |
-| 2 | 05-auth | testing | 1. Login Form | 0/4 |
+| # | Target | Type | Status | Current Test | Progress |
+|---|--------|------|--------|--------------|----------|
+| 1 | 04-comments | phase | testing | 3. Reply to Comment | 2/6 |
+| 2 | v1.2 | milestone | testing | 1. Login Form | 0/4 |
 
-Reply with a number to resume, or provide a phase number to start new.
+Reply with a number to resume, or provide a target to start new.
 ```
 
 Wait for user response.
 
 - If user replies with number (1, 2) → Load that file, go to `resume_from_file`
-- If user replies with phase number → Treat as new session, go to `create_uat_file`
+- If user replies with phase number or milestone → Treat as new session, go to `create_uat_file`
 
 **If active sessions exist AND $ARGUMENTS provided:**
 
-Check if session exists for that phase. If yes, offer to resume or restart.
+Check if session exists for that target (phase or milestone). If yes, offer to resume or restart.
 If no, continue to `create_uat_file`.
 
 **If no active sessions AND no $ARGUMENTS:**
@@ -341,7 +343,7 @@ If no, continue to `create_uat_file`.
 ```
 No active UAT sessions.
 
-Provide a phase number to start testing (e.g., /rrr:verify-work 4)
+Provide a phase number (e.g., 4) or milestone (e.g., v1.2) to start testing:
 ```
 
 **If no active sessions AND $ARGUMENTS provided:**
@@ -352,15 +354,32 @@ Continue to `create_uat_file`.
 <step name="find_summaries">
 **Find what to test:**
 
-Parse $ARGUMENTS as phase number (e.g., "4") or plan number (e.g., "04-02").
+Parse $ARGUMENTS to determine scope:
 
-```bash
-# Find phase directory
-# Find phase directory using phase-paths library (handles milestone-aware structure)
-PHASE_DIR=$(find_phase_dir "${PHASE_ARG}")
+- **Phase number** (e.g., `4`, `05`, `05-auth`): Test that phase only
+- **Milestone** (e.g., `v1.9`, `v2.0`): Test all phases in that milestone
+- **Empty**: Use current milestone from ROADMAP.md
 
-# Find SUMMARY files
-ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
+```bash
+# Determine if target is a milestone (starts with 'v' followed by digits)
+if [[ "$PHASE_ARG" =~ ^v[0-9]+\.[0-9]+$ ]]; then
+  # Milestone target - find all SUMMARY files in that milestone's phases
+  MILESTONE="$PHASE_ARG"
+  MILESTONE_DIR=".planning/milestones/${MILESTONE}/phases"
+  if [ -d "$MILESTONE_DIR" ]; then
+    find "$MILESTONE_DIR" -maxdepth 2 -name "*-SUMMARY.md" 2>/dev/null | sort
+  else
+    echo "ERROR: Milestone directory not found: $MILESTONE_DIR" >&2
+  fi
+else
+  # Phase target - use find_phase_dir
+  PHASE_DIR=$(find_phase_dir "${PHASE_ARG}")
+  if [ -n "$PHASE_DIR" ]; then
+    ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
+  else
+    echo "ERROR: Phase directory not found for: $PHASE_ARG" >&2
+  fi
+fi
 ```
 
 Read each SUMMARY.md to extract testable deliverables.
@@ -391,7 +410,21 @@ Skip internal/non-observable items (refactors, type changes, etc.).
 **Create UAT file with all tests:**
 
 ```bash
-mkdir -p "$PHASE_DIR"
+# Determine if milestone target and set up output location
+if [[ "$PHASE_ARG" =~ ^v[0-9]+\.[0-9]+$ ]]; then
+  # Milestone-level UAT - create in milestone's phases directory
+  MILESTONE="$PHASE_ARG"
+  MILESTONE_DIR=".planning/milestones/${MILESTONE}/phases"
+  mkdir -p "$MILESTONE_DIR"
+  UAT_FILE="$MILESTONE_DIR/${MILESTONE}-UAT.md"
+  TARGET_TYPE="milestone"
+else
+  # Phase-level UAT - use existing phase directory
+  mkdir -p "$PHASE_DIR"
+  PHASE_NAME=$(basename "$PHASE_DIR")
+  UAT_FILE="$PHASE_DIR/${PHASE_NAME}-UAT.md"
+  TARGET_TYPE="phase"
+fi
 ```
 
 Build test list from extracted deliverables.
@@ -401,7 +434,8 @@ Create file:
 ```markdown
 ---
 status: testing
-phase: XX-name
+target_type: {TARGET_TYPE}
+target: {PHASE_ARG}
 source: [list of SUMMARY.md files]
 started: [ISO timestamp]
 updated: [ISO timestamp]
@@ -441,7 +475,7 @@ skipped: 0
 [none yet]
 ```
 
-Write to `{phase_dir}/{phase}-UAT.md` (where phase_dir is from get_phase_dir)
+Write to `$UAT_FILE`
 
 **Route based on testing mode:**
 - If `TESTING_MODE=qa-engineer` → Go to `run_qa_engineer_batch`
@@ -782,13 +816,19 @@ Clear Current Test section:
 
 Commit the UAT file:
 ```bash
-git add "{phase_dir}/{phase}-UAT.md"
-git commit -m "test({phase}): complete UAT - {passed} passed, {issues} issues"
+# Use target from frontmatter (phase or milestone)
+if [ "$TARGET_TYPE" = "milestone" ]; then
+  git add "$UAT_FILE"
+  git commit -m "test(${TARGET}): complete UAT - ${passed} passed, ${issues} issues"
+else
+  git add "$UAT_FILE"
+  git commit -m "test(${TARGET}): complete UAT - ${passed} passed, ${issues} issues"
+fi
 ```
 
 Present summary:
 ```
-## UAT Complete: Phase {phase}
+## UAT Complete: {TARGET_TYPE} {TARGET}
 
 | Result | Count |
 |--------|-------|