projecta-rrr 1.9.5 → 1.9.7

package/commands/rrr/help.md

@@ -323,6 +323,34 @@ Create context handoff when pausing work mid-phase.
 
 Usage: `/rrr:pause-work`
 
+### Verification
+
+**`/rrr:verify-work [target] [--audit | --uat]`**
+Validate built features through audit or interactive UAT.
+
+**Two modes:**
+
+| Flag | Behavior |
+|------|----------|
+| `--audit` (default) | Non-interactive audit. Checks PLAN/SUMMARY existence and git evidence. Produces audit report. Does NOT touch UAT files. |
+| `--uat` | Interactive UAT. Creates/resumes UAT.md for manual testing with persistent state. |
+
+**Target options:**
+- Phase: `05`, `5`, `05-auth` — verify that phase
+- Milestone: `v1.9` — verify all phases in milestone
+- Empty — verify current milestone from STATE.md
+
+**Examples:**
+```
+/rrr:verify-work                    # Audit current milestone (default)
+/rrr:verify-work --audit            # Audit current milestone
+/rrr:verify-work --audit 05         # Audit phase 05 only
+/rrr:verify-work --audit v1.9       # Audit all phases in v1.9
+/rrr:verify-work --uat 05           # Interactive UAT for phase 05
+```
+
+**Audit output:** `.planning/artifacts/VERIFY_WORK_AUDIT.md`
+
 ### Debugging
 
 **`/rrr:debug [issue description]`**

package/commands/rrr/progress.md

@@ -236,6 +236,10 @@ Read its `<objective>` section.
 
 <sub>`/clear` first → fresh context window</sub>
 
+<sub>Already did some of this work?
+- `/rrr:verify-work --audit {phase}` — check implementation (non-interactive)
+- `/rrr:verify-work --uat {phase}` — interactive UAT testing</sub>
+
 ---
 ```
 
@@ -305,7 +309,7 @@ UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
 
 **Also available:**
 - `/rrr:execute-plan [path]` — continue with other work first
-- `/rrr:verify-work {phase}` — run more UAT testing
+- `/rrr:verify-work --uat {phase}` — interactive UAT testing
 
 ---
 ```
@@ -370,7 +374,7 @@ Full report: .planning/artifacts/VERIFY_WORK_AUDIT.md
 ---
 
 **Also available:**
-- `/rrr:verify-work {Z}` — user acceptance test before continuing
+- `/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
 
@@ -420,7 +424,7 @@ Full report: .planning/artifacts/VERIFY_WORK_AUDIT.md
 
 **Also available:**
 - `/rrr:verify-work --audit` — full implementation audit report
-- `/rrr:verify-work` — interactive user acceptance test
+- `/rrr:verify-work --uat` — interactive user acceptance test
 
 ---
 ```
@@ -462,21 +466,14 @@ Ready to plan the next milestone.
 
 ## ▶ Next Up
 
-**Discuss Next Milestone** — figure out what to build next
-
-`/rrr:discuss-milestone`
+| Option | Command | What it does |
+|--------|---------|--------------|
+| **Audit completion** | `/rrr:verify-work --audit` | Check plan/summary + git evidence (no UAT) |
+| **Interactive UAT** | `/rrr:verify-work --uat` | Manual testing with UAT.md files |
+| **Plan next milestone** | `/rrr:discuss-milestone` | Figure out what to build next |
 
 <sub>`/clear` first → fresh context window</sub>
 
----
-
-**Next milestone flow:**
-1. `/rrr:discuss-milestone` — thinking partner, creates context file
-2. `/rrr:new-milestone` — update PROJECT.md with new goals
-3. `/rrr:research-project` — (optional) research ecosystem
-4. `/rrr:define-requirements` — scope what to build
-5. `/rrr:create-roadmap` — plan how to build it
-
 ---
 ```
 

package/commands/rrr/verify-work.md

@@ -1,7 +1,7 @@
 ---
 name: rrr:verify-work
-description: Validate built features through conversational UAT
-argument-hint: "[phase number, e.g., '4'] [--audit]"
+description: Validate built features through audit (default) or interactive UAT
+argument-hint: "[target] [--audit | --uat]"
 allowed-tools:
   - Read
   - Bash
@@ -12,127 +12,300 @@ allowed-tools:
 ---
 
 <objective>
-Validate built features through conversational testing with persistent state.
+Validate built features through **audit mode by default**, or interactive UAT with `--uat`.
 
-**Default mode:** Interactive UAT - one test at a time, plain text responses.
-**Audit mode (`--audit`):** Non-interactive implementation check - verifies plans have summaries and git evidence.
+**Default behavior (no flags or --audit):** Non-interactive audit.
+- Checks PLAN/SUMMARY existence and git evidence
+- Produces audit report at `.planning/artifacts/VERIFY_WORK_AUDIT.md`
+- **Does NOT touch any UAT-related files, workflows, or templates**
 
-Output:
-- Default: {phase}-UAT.md tracking all test results, gaps logged for /rrr:plan-phase --gaps
-- Audit: .planning/artifacts/VERIFY_WORK_AUDIT.md (no UAT files created)
+**With --uat flag:** Interactive user acceptance testing.
+- Creates/resumes UAT.md files for manual testing
+- Loads workflow and template references
+
+**Critical:** Audit mode must NEVER open, read, or create `*-UAT.md` files.
 </objective>
 
-<execution_context>
-@~/.claude/rrr/workflows/verify-work.md
-@~/.claude/rrr/templates/UAT.md
-</execution_context>
+<arguments>
+**Target (optional):**
+- Phase number: `05`, `5`, `05-auth` → audit/test that phase only
+- Milestone: `v1.9`, `v2.0` → audit all phases in that milestone
+- Nothing → audit current milestone from STATE.md
+
+**Flags:**
+- `--audit` (or no flag) → Run non-interactive audit (DEFAULT)
+- `--uat` → Run interactive UAT session (explicit opt-in)
+
+**Examples:**
+```
+/rrr:verify-work                    # Audit current milestone (default)
+/rrr:verify-work --audit            # Audit current milestone
+/rrr:verify-work --audit 05         # Audit phase 05 only
+/rrr:verify-work --audit v1.9       # Audit all phases in v1.9
+/rrr:verify-work --uat 05           # Interactive UAT for phase 05
+```
+
+**Audit output:** `.planning/artifacts/VERIFY_WORK_AUDIT.md`
+</arguments>
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     MODE SELECTION - MUST EXECUTE FIRST BEFORE ANY OTHER SECTION
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+<mode_selection>
+## CRITICAL: Parse mode FIRST
+
+**Step 1: Parse arguments**
+
+```
+hasAuditFlag = $ARGUMENTS contains "--audit"
+hasUatFlag = $ARGUMENTS contains "--uat"
+target = $ARGUMENTS with flags removed (e.g., "05", "v1.9", or empty)
+```
+
+**Step 2: Route based on flags**
 
-<context>
-Phase: $ARGUMENTS (optional)
-- If provided: Test specific phase (e.g., "4")
-- If not provided: Check for active sessions or prompt for phase
+| Condition | Action |
+|-----------|--------|
+| `--uat` present | → Execute `<uat_mode>` below (loads workflow/template) |
+| `--audit` present OR no flags | → Execute `<audit_mode>` below (DEFAULT) |
 
-Flags:
-- `--audit` or `--implementation-only`: Non-interactive mode, check implementation status only
+**If --uat is present:**
+1. Execute the `<uat_mode>` section below
+2. This loads the workflow file with template references
 
-@.planning/STATE.md
-@.planning/ROADMAP.md
-</context>
+**If --audit is present OR no flags:**
+1. Execute the `<audit_mode>` section below (DEFAULT)
+2. This command file is COMPLETE for audit mode - NO @ references anywhere
+3. **EXIT IMMEDIATELY** after audit report
+</mode_selection>
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     AUDIT MODE - DEFAULT BEHAVIOR, COMPLETELY SELF-CONTAINED
+     ═══════════════════════════════════════════════════════════════════════════ -->
 
 <audit_mode>
-**If --audit flag is present:**
+## Audit Mode (Non-Interactive, Self-Contained)
+
+**HARD GUARANTEES:**
+- Does NOT open, read, create, or modify any `*-UAT.md` files
+- Does NOT load any workflow or template files (no @ references in this file)
+- Does NOT ask user to manually test anything
+- Produces ONE artifact: `.planning/artifacts/VERIFY_WORK_AUDIT.md`
 
-This mode runs a non-interactive implementation audit. It does NOT:
-- Create UAT files
-- Ask for manual verification
-- Present interactive tests
+---
 
-**Step 1: Determine scope**
+### Step 1: Determine Scope
 
-Parse $ARGUMENTS for phase number and --audit flag.
+**Parse target from arguments (with flags removed):**
 
-| Arguments | Scope |
-|-----------|-------|
-| `--audit 4` or `4 --audit` | Audit phase 4 only |
-| `--audit` (no phase) | Check STATE.md for context |
+| Target | Scope |
+|--------|-------|
+| Phase number (e.g., `05`, `5`, `05-auth`) | Audit that phase only |
+| Milestone (e.g., `v1.9`) | Audit all phases in that milestone |
+| Empty | Check STATE.md for context |
 
-**If no phase provided, read STATE.md:**
-- If active phase exists → audit that phase
-- If "Between milestones" or "Phase: N/A" → audit entire milestone (all phases)
+**If no target provided:**
 
-**Step 2: Run verification script**
+Read `.planning/STATE.md`:
+- If `Phase:` has active value (not "N/A", not "Between milestones") → audit that phase
+- If `Milestone: Between milestones` or `Phase: N/A` → audit entire current/last milestone
+
+---
+
+### Step 2: Gather Plan Inventory (Cross-Platform)
+
+**IMPORTANT: Never glob for `*-UAT.md`. Only glob for `*-PLAN.md` and `*-SUMMARY.md`.**
+
+**On any platform, use Glob tool:**
 
-```bash
-node ~/.claude/rrr/scripts/verify-milestone.js --summary-only 2>/dev/null
+```
+Glob pattern: ".planning/phases/${PHASE}*/*-PLAN.md"
 ```
 
-**If auditing single phase, filter output:**
-- Only show results for the specified phase
-- Still generate full artifact but highlight relevant section
+For milestone scope, enumerate all phase directories first:
+```
+Glob pattern: ".planning/phases/*"
+```
+Then for each phase directory:
+```
+Glob pattern: ".planning/phases/{phase-dir}/*-PLAN.md"
+```
 
-**Step 3: Output to artifact**
+**Build inventory (deterministic order by phase number, then plan ID):**
 
-The script generates:
-- `.planning/artifacts/VERIFY_MILESTONE.md` → Copy/rename to `.planning/artifacts/VERIFY_WORK_AUDIT.md`
-- `.planning/artifacts/VERIFY_MILESTONE.json` → Copy/rename to `.planning/artifacts/VERIFY_WORK_AUDIT.json`
+```
+plans = []
+for each PLAN.md found (sorted by path):
+  planId = extract from filename (e.g., "05-02")
+  planPath = full path
+  summaryPath = planPath.replace("-PLAN.md", "-SUMMARY.md")
 
-**Step 4: Display summary**
+  # Check SUMMARY existence using Read tool (returns error if missing)
+  summaryExists = try Read(summaryPath), catch = false
 
+  plans.push({ planId, planPath, summaryExists, summaryPath })
 ```
-## Implementation Audit
 
-{Scope: Phase X | Entire Milestone}
+**Sort plans by planId for deterministic output.**
 
-| Metric | Count |
-|--------|-------|
-| ✓ Done | {N} |
-| ⚠ Likely done (missing summary) | {N} |
-| ✗ Not done | {N} |
-| ? Suspicious | {N} |
+---
+
+### Step 3: Evidence Checks
+
+**For each plan:**
+
+1. **PLAN exists?** → Always yes (we found it via glob)
+
+2. **SUMMARY exists?** → From inventory check above
+
+3. **Commit hash present?** → If SUMMARY exists:
+   - Read SUMMARY file content
+   - Search for git commit hash pattern: `/[a-f0-9]{7,40}/` (7-40 hex chars)
+   - Check frontmatter `commit:` field OR body text
+   - Mark as present if found, absent if not
+
+4. **Git evidence (lightweight, optional):**
+   ```bash
+   git log --oneline -5 -- ".planning/phases/${PHASE}*/" 2>/dev/null
+   ```
+   - If git unavailable or fails, skip gracefully
+   - This is supplementary info, not required
+
+**State integrity check:**
+
+Read `.planning/STATE.md`:
+- Extract current `Phase:` value (e.g., "05" or "N/A")
+- Extract current `Plan:` value if present
 
-{If gaps exist:}
-### Gaps
+Compare against plan inventory:
+- Find highest phase number with SUMMARY files
+- If SUMMARYs exist for phases beyond STATE's phase → "stale STATE detected"
 
-| Phase | Plan | Status | Action |
-|-------|------|--------|--------|
-| ... | ... | ... | ... |
+---
+
+### Step 4: Generate Audit Report
+
+**Determine verdict:**
+- ✅ Clean = All plans have SUMMARY with commit hash, STATE is consistent
+- ⚠️ Gaps found = Any plan missing SUMMARY or commit hash
+
+**Write to `.planning/artifacts/VERIFY_WORK_AUDIT.md`:**
+
+```markdown
+# Verify Work Audit Report
+
+*Generated: {ISO timestamp}*
+
+## Scope
+
+**Target:** Phase {X} | Milestone {X} | Current Milestone
+**Verdict:** ✅ Clean | ⚠️ Gaps found
+
+## Plan Status
+
+| Plan | PLAN | SUMMARY | Commit Hash | Notes |
+|------|------|---------|-------------|-------|
+| 05-01 | ✓ | ✓ | ✓ abc1234 | — |
+| 05-02 | ✓ | ✗ | — | Missing SUMMARY |
+| 05-03 | ✓ | ✓ | ✗ | No commit hash in SUMMARY |
 
-Full report: .planning/artifacts/VERIFY_WORK_AUDIT.md
+**Summary:** {N} plans checked, {done} complete, {gaps} gaps
 
-{If all done:}
-✓ All plans verified. Ready for milestone completion.
+## State Integrity
+
+{If stale detected:}
+⚠️ **Stale STATE detected**
+STATE.md says Phase {X}, but SUMMARYs exist through Phase {Y}.
+Recommended: Run `/rrr:progress` to update position.
+
+{If consistent:}
+✓ STATE.md is consistent with plan inventory.
+
+## Recommended Next Steps
+
+{If gaps - missing SUMMARY:}
+- Execute missing plan: `/rrr:execute-plan {path-to-first-missing-plan}`
+- Or if code is done, write SUMMARY manually
+
+{If gaps - missing commit hash:}
+- Update SUMMARY files with commit references
+
+{If clean and between milestones:}
+- `/rrr:complete-milestone` — Archive and prepare next
+- `/rrr:discuss-milestone` — Plan what's next
+
+{If clean and active milestone:}
+- `/rrr:progress` — Continue to next phase
+```
+
+**Ensure artifacts directory exists:**
+```bash
+mkdir -p .planning/artifacts
 ```
 
-**Exit after audit - do not proceed to interactive UAT.**
+---
+
+### Step 5: Exit
+
+**Print summary and EXIT. Do NOT proceed to UAT mode.**
+
+```
+Audit complete. Report: .planning/artifacts/VERIFY_WORK_AUDIT.md
+
+{verdict summary - 1 line}
+```
+
+**STOP HERE. The command is complete.**
+
 </audit_mode>
 
-<process>
-1. Check for active UAT sessions (resume or start new)
-2. Find SUMMARY.md files for the phase
-3. Extract testable deliverables (user-observable outcomes)
-4. Create {phase}-UAT.md with test list
-5. Present tests one at a time:
-   - Show expected behavior
-   - Wait for plain text response
-   - "yes/y/next" = pass, anything else = issue (severity inferred)
-6. Update UAT.md after each response
-7. On completion: commit, present summary, offer next steps
-</process>
-
-<anti_patterns>
-- Don't use AskUserQuestion for test responses — plain text conversation
-- Don't ask severity — infer from description
-- Don't present full checklist upfront — one test at a time
-- Don't run automated tests — this is manual user validation
-- Don't fix issues during testing — log as gaps for /rrr:plan-phase --gaps
-</anti_patterns>
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     UAT MODE - ONLY LOADED WHEN --uat FLAG IS PRESENT
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+<uat_mode>
+## UAT Mode (Interactive)
+
+**This section is ONLY reached if `--uat` flag is present.**
+
+**Load the workflow to run interactive UAT:**
+
+Read the file at: `rrr/workflows/verify-work.md`
+
+The workflow contains the full UAT process and will reference the UAT template internally.
+
+**Expected workflow sections to follow:**
+- check_active_session → find_summaries → extract_tests → create_uat_file
+- present_test → process_response → resume_from_file → complete_session
+</uat_mode>
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     EXCLUDED PATHS - APPLY TO ALL MODES
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+<excluded_paths>
+**Never scan or read these directories:**
+- GSDWatcher/
+- GSDWatcher/upstreams/
+- GSDWatcher/reports/
+
+All Glob/Grep/Read operations must exclude these paths.
+</excluded_paths>
 
 <success_criteria>
-- [ ] UAT.md created with tests from SUMMARY.md
-- [ ] Tests presented one at a time with expected behavior
-- [ ] Plain text responses (no structured forms)
-- [ ] Severity inferred, never asked
-- [ ] Batched writes: on issue, every 5 passes, or completion
-- [ ] Committed on completion
-- [ ] Clear next steps based on results
-</success_criteria>
+**Audit mode (default):**
+- [ ] Mode selection happens FIRST, before any workflow/template load
+- [ ] Does NOT glob/read any *-UAT.md files
+- [ ] Does NOT load workflow or template files (no @ references in this file)
+- [ ] Produces single artifact: .planning/artifacts/VERIFY_WORK_AUDIT.md
+- [ ] Deterministic ordering (phase, then plan ID)
+- [ ] Detects missing SUMMARYs and commit hashes
+- [ ] Detects stale STATE
+- [ ] Exits after printing report
+
+**UAT mode (--uat):**
+- [ ] Only reached when --uat flag is present
+- [ ] Loads workflow and template
+- [ ] Creates/resumes UAT.md with tests
+</success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.9.5",
+  "version": "1.9.7",
   "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

@@ -2,8 +2,37 @@
 Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /rrr:plan-phase --gaps.
 
 User tests, Claude records. One test at a time. Plain text responses.
+
+**This workflow is for UAT mode only (`--uat`).** Audit mode (`--audit`) is handled inline in the command file and does NOT load this workflow. Only run this workflow when the `--uat` flag is present.
 </purpose>
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     MODE GATE - FAILSAFE TO CATCH ACCIDENTAL AUDIT MODE LOADING
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+<mode_gate>
+## FAILSAFE: Audit Mode Detection
+
+**Check IMMEDIATELY before doing anything else:**
+
+If `$ARGUMENTS` contains `--audit`:
+
+```
+Audit mode detected — this workflow should not be loaded.
+The command file commands/rrr/verify-work.md handles audit mode inline.
+Only run this workflow when --uat flag is present.
+```
+
+**STOP IMMEDIATELY. Do not proceed.**
+
+This workflow should ONLY be loaded when `--uat` flag is present. If you see this message:
+1. The command file failed to properly route --uat to this workflow
+2. Do NOT continue with UAT steps
+3. Exit and report the issue
+
+**If --uat is present (or no audit flag):** Continue to the next section.
+</mode_gate>
+
 <philosophy>
 **Show expected, ask if reality matches.**