projecta-rrr 1.16.3 → 1.16.5

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.5] - 2026-01-27
+
+### 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 for both phase and milestone UAT files
+
+## [1.16.4] - 2026-01-27
+  - `playwright` → run_playwright_batch
+  - `manual` → present_test
+
 ## [1.16.3] - 2026-01-27
 
 ### Changed

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.3",
+  "version": "1.16.5",
   "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/workflows/verify-work.md

@@ -179,31 +179,123 @@ Check if zeroshot validation is available:
 
 **If ZEROSHOT_AVAILABLE and MODULE_EXISTS:**
 
-Check for Playwright MCP availability:
+Check for Playwright MCP availability (multiple detection methods):
+
+```bash
+# Enhanced Playwright MCP detection - checks multiple locations
+PLAYWRIGHT_STATUS="NO_PLAYWRIGHT_MCP"
+
+# Method 1: Check ~/.claude/mcp.json
+if [ -f "$HOME/.claude/mcp.json" ]; then
+  if grep -qi "playwright" "$HOME/.claude/mcp.json" 2>/dev/null; then
+    PLAYWRIGHT_STATUS="PLAYWRIGHT_MCP_AVAILABLE"
+  fi
+fi
+
+# Method 2: Check ~/.claude/settings.json (alternate location)
+if [ "$PLAYWRIGHT_STATUS" = "NO_PLAYWRIGHT_MCP" ] && [ -f "$HOME/.claude/settings.json" ]; then
+  if grep -qi "playwright" "$HOME/.claude/settings.json" 2>/dev/null; then
+    PLAYWRIGHT_STATUS="PLAYWRIGHT_MCP_AVAILABLE"
+  fi
+fi
+
+# Method 3: Check if playwright-mcp command exists
+if [ "$PLAYWRIGHT_STATUS" = "NO_PLAYWRIGHT_MCP" ]; then
+  if command -v playwright-mcp >/dev/null 2>&1; then
+    PLAYWRIGHT_STATUS="PLAYWRIGHT_MCP_AVAILABLE"
+  fi
+fi
+
+# Method 4: Check MCP servers via ps or other running processes
+if [ "$PLAYWRIGHT_STATUS" = "NO_PLAYWRIGHT_MCP" ]; then
+  if ps aux 2>/dev/null | grep -qi "[p]laywright-mcp"; then
+    PLAYWRIGHT_STATUS="PLAYWRIGHT_MCP_AVAILABLE"
+  fi
+fi
+
+echo "$PLAYWRIGHT_STATUS"
+```
+
+Check for MiniMax API key (enables AI visual validation):
+
+```bash
+[ -n "$MINIMAX_API_KEY" ] && echo "MINIMAX_AVAILABLE" || echo "NO_MINIMAX"
+```
+
+**Determine Recommended Mode:**
+
+Based on what's available, calculate the recommended mode:
+
+| Available | Recommended Mode | Why |
+|-----------|-----------------|-----|
+| Playwright MCP + MiniMax | AI QA Engineer | Best for web UI - browser control + visual validation |
+| MiniMax only | Zeroshot (Screenshot) | Fast, cheap visual validation |
+| Anthropic API only | Zeroshot (Screenshot) | Uses Claude vision |
+| No API keys | Manual | User testing required |
+
+**Auto-detect test type from SUMMARY.md:**
+
 ```bash
-# Check if Playwright MCP is configured
-[ -f "$HOME/.claude/mcp.json" ] && grep -q "playwright" "$HOME/.claude/mcp.json" && echo "PLAYWRIGHT_MCP_AVAILABLE" || echo "NO_PLAYWRIGHT_MCP"
+# Check SUMMARY.md content to determine test type
+# 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"
+elif echo "$SUMMARY_CONTENT" | grep -qiE "(api|endpoint|database|backend|voice|sip|telephony|audio|websocket)"; then
+  TEST_TYPE="API_BACKEND"
+else
+  TEST_TYPE="MIXED"
+fi
+echo "$TEST_TYPE"
+```
+
+**Mode Selection UX:**
+
+```
+╔══════════════════════════════════════════════════════════════════════╗
+║  UAT Testing Mode (auto-detected: Web UI tests)                      ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  Recommended:                                                       ║
+║  ────────────────────                                               ║
+║  ⭐ AI QA Engineer (Recommended for web UI)                          ║
+║     • Browser automation + visual AI validation                     ║
+║     • Explores edge cases, tests like a real user                   ║
+║     • Cost: ~$0.001/test (MiniMax vision)                           ║
+║                                                                      ║
+║  Alternative:                                                       ║
+║  ────────────                                                       ║
+║  • Zeroshot (Screenshot) — Fast, fully automated                     ║
+║  • Manual — You test each feature and report results                 ║
+║                                                                      ║
+╚══════════════════════════════════════════════════════════════════════╝
 ```
 
 Use AskUserQuestion:
 - header: "Testing Mode"
-- question: "How would you like to run UAT?"
+- question: "How would you like to run UAT? (Recommended: AI QA Engineer for web UI)"
 - options:
-  {If PLAYWRIGHT_MCP_AVAILABLE:}
-  - "AI QA Engineer (Recommended)" — Claude acts as a QA engineer, controlling the browser interactively. Explores like a real user, tests edge cases.
+  {If PLAYWRIGHT_MCP_AVAILABLE and MINIMAX_AVAILABLE:}
+  - "AI QA Engineer (Recommended)" — Claude acts as a QA engineer, controlling the browser interactively with visual validation. Tests edge cases automatically. Best for web UI.
   - "Zeroshot (Screenshot)" — Claude validates UI using screenshots. Faster, less thorough.
   - "Manual" — You'll test each feature and report results. More control, slower.
-  {Else:}
+  {ElseIf PLAYWRIGHT_MCP_AVAILABLE and TEST_TYPE = "WEB_UI":}
+  - "Playwright MCP (Interactive)" — Use browser automation for testing. No visual AI validation.
+  - "Manual" — You'll test each feature and report results.
+  {ElseIf MINIMAX_AVAILABLE or ANTHROPIC_API_KEY:}
   - "Zeroshot (Automated) (Recommended)" — Claude validates UI autonomously using screenshots. Faster, no input needed per test.
   - "Manual" — You'll test each feature and report results. More control, slower.
+  {Else:}
+  - "Manual" — You'll test each feature and report results.
 
-Store result in `TESTING_MODE` (qa-engineer, zeroshot, or manual).
+Store result in `TESTING_MODE` (qa-engineer, zeroshot, playwright, or manual).
 
 **If MANUAL_ONLY or MODULE_MISSING:**
 
 ```
 UAT will run in manual mode.
-(Set ANTHROPIC_API_KEY to enable automated zeroshot testing)
+(Set ANTHROPIC_API_KEY to enable automated testing)
 ```
 
 Set `TESTING_MODE=manual`.
@@ -215,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:**
@@ -250,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:**
@@ -261,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.
@@ -300,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.
@@ -310,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]
@@ -350,10 +475,12 @@ 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`
 - If `TESTING_MODE=zeroshot` → Go to `run_zeroshot_batch`
+- If `TESTING_MODE=playwright` → Go to `run_playwright_batch`
 - If `TESTING_MODE=manual` → Go to `present_test`
 </step>
 
@@ -444,6 +571,128 @@ Falling back to manual mode for remaining tests.
 Set `TESTING_MODE=manual` and continue from current test.
 </step>
 
+<step name="run_qa_engineer_batch">
+**Run AI QA Engineer mode for all tests:**
+
+This mode combines Playwright MCP (browser control) with MiniMax (visual AI) for comprehensive exploratory testing.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  AI QA ENGINEER: Autonomous Testing                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+Running {N} tests with browser automation + AI visual validation...
+```
+
+**For each test in the UAT file:**
+
+1. Extract test name and expected behavior
+2. Determine the URL to test
+3. Run QA Engineer validation:
+   ```javascript
+   const { zeroshotValidate } = require('~/.claude/rrr/lib/uat/zeroshot-validator.js');
+
+   const result = await zeroshotValidate({
+     url: testUrl,
+     task: `Verify: ${expectedBehavior}`,
+     mode: 'qa-engineer',        // QA engineer persona
+     interactive: true,          // Use Playwright MCP for browser control
+     timeout: 60000              // Longer timeout for exploratory testing
+   });
+   ```
+
+4. Process result:
+   - If `result.passed === true`:
+     - Update test result to "pass"
+     - Log: `✓ Test {N}: {name}`
+   - If `result.passed === false`:
+     - Update test result to "issue"
+     - Capture observations and reasoning
+     - Add to Gaps section
+     - Log: `✗ Test {N}: {name} - {brief reason}`
+
+5. Update UAT.md after each test (checkpoint)
+
+6. Display progress:
+   ```
+   Progress: [████████░░] 8/10 tests complete
+   ✓ Test 1: Login page loads with form fields
+   ✓ Test 2: Form validation on submit
+   ✗ Test 3: Password reset email not sent (edge case found)
+   ...
+   ```
+
+**QA Engineer specific behaviors:**
+- Tests edge cases automatically (empty fields, long inputs, special chars)
+- Explores navigation paths beyond the happy path
+- Screenshots any issues found
+- Validates visual correctness with MiniMax vision
+
+**After all tests complete:**
+
+Update frontmatter status to "complete".
+
+**Display summary:**
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  AI QA ENGINEER: Complete                                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+Results:
+  ✓ Passed:  {N}
+  ✗ Issues:  {N}
+  ⏭ Skipped: {N}
+
+Exploratory Testing Notes:
+  - {N} edge cases tested automatically
+  - {N} navigation paths explored
+
+{If issues > 0:}
+Issues Found:
+  1. Test 3: Password reset - Edge case: special chars in email cause error
+  2. Test 7: Form submission - Visual: error message clipped on mobile
+```
+
+Go to `complete_session`.
+
+**On error (Playwright MCP not available, timeout):**
+
+```
+⚠ QA Engineer mode error: {error}
+Falling back to Zeroshot mode...
+```
+
+Set `TESTING_MODE=zeroshot` and continue to `run_zeroshot_batch`.
+</step>
+
+<step name="run_playwright_batch">
+**Run Playwright-only mode (no visual AI):**
+
+Use Playwright MCP for browser automation without visual AI validation.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAYWRIGHT UAT: Browser Automation                           ║
+╚══════════════════════════════════════════════════════════════╝
+
+Running {N} tests with Playwright browser automation...
+```
+
+**For each test:**
+
+1. Navigate to URL using Playwright MCP
+2. Perform interactions described in test
+3. Take screenshot at key points
+4. Report findings (manual AI analysis not used)
+
+**After all tests:**
+
+Display summary and prompt for manual verification of screenshots.
+
+Go to `complete_session`.
+</step>
+
 <step name="present_test">
 **Present current test to user (Manual Mode):**
 
@@ -567,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 |
 |--------|-------|