projecta-rrr 1.9.4 → 1.9.5

package/commands/rrr/execute-phase.md

@@ -48,6 +48,50 @@ Phase: $ARGUMENTS
    - Count PLAN.md files
    - Error if no plans found
 
+1.5. **Run phase-level preflight**
+
+   Before execution, run preflight in phase mode:
+
+   ```bash
+   node ~/.claude/rrr/scripts/handoff-preflight.js --phase $ARGUMENTS
+   ```
+
+   Parse the JSON output.
+
+   **Handle by recommendation:**
+
+   | Recommendation | Action |
+   |----------------|--------|
+   | `proceed` | Continue to step 2 |
+   | `warn_and_proceed` | Show warning, continue |
+   | `reconcile_first` | Show decision gate |
+   | `review_instead_of_execute` | Show decision gate, pause |
+
+   **Decision gate:**
+
+   ```
+   ⚠ PHASE DRIFT DETECTED
+
+   {overlap_ratio}% of phase files already changed.
+   ```
+
+   Use AskUserQuestion:
+   - question: "Phase work may have started. How to proceed?"
+   - header: "Preflight"
+   - options:
+     - "Continue anyway" — Override, proceed
+     - "Review per-plan" — Run preflight per plan during execution
+     - "Capture as TODO" — Defer phase execution
+     - "Cancel" — Exit
+
+   **If "Review per-plan":**
+   - Set flag: `per_plan_preflight = true`
+   - Continue to step 2
+   - Run preflight for each plan in step 5
+
+   **If script not found:**
+   - Log warning, continue without preflight
+
 2. **Discover plans**
    - List all *-PLAN.md files in phase directory
    - Check which have *-SUMMARY.md (already complete)
@@ -68,6 +112,20 @@ Phase: $ARGUMENTS
 
 5. **Execute waves**
    For each wave in order:
+
+   **5a. Per-plan preflight (if `per_plan_preflight` flag set):**
+
+   Before spawning executor for each plan:
+
+   ```bash
+   node ~/.claude/rrr/scripts/handoff-preflight.js --plan "{plan_path}"
+   ```
+
+   - If `review_instead_of_execute`: Show decision gate for that plan
+   - If user chooses to skip: Mark plan as skipped, continue to next
+   - If user chooses to continue: Proceed with execution
+
+   **5b. Execute plans:**
    - For each plan, inject `<skills>` block into executor prompt
    - Spawn `rrr-executor` for each plan in wave (parallel Task calls)
    - Wait for completion (Task blocks)

package/commands/rrr/execute-plan.md

@@ -1,7 +1,7 @@
 ---
 name: rrr:execute-plan
 description: Execute a PLAN.md file
-argument-hint: "[path-to-PLAN.md]"
+argument-hint: "[path-to-PLAN.md] [--summary-only]"
 allowed-tools:
   - Read
   - Glob
@@ -31,6 +31,9 @@ Context budget: ~15% orchestrator, 100% fresh for subagent.
 <context>
 Plan path: $ARGUMENTS
 
+**Flags:**
+- `--summary-only` — Skip execution, generate SUMMARY.md from existing work (use after preflight review confirms all deliverables present)
+
 @.planning/STATE.md
 @.planning/config.json (if exists)
 </context>
@@ -94,6 +97,126 @@ Plan path: $ARGUMENTS
    - Confirm file at $ARGUMENTS exists
    - Error if not found: "Plan not found: {path}"
 
+1.1. **Check for --summary-only flag**
+
+   If `--summary-only` is present in $ARGUMENTS:
+
+   **Purpose:** Generate SUMMARY.md from existing work without re-executing. Use after preflight review confirms all deliverables are already present.
+
+   **Process:**
+   1. Parse plan to extract:
+      - Plan ID, title, objective
+      - Task list from `<task>` elements
+      - Expected files from frontmatter
+
+   2. Verify existing work:
+      - Check each expected file exists
+      - Run any verification commands from plan
+      - Note: Do NOT execute any tasks
+
+   3. Generate SUMMARY.md:
+      ```markdown
+      ---
+      plan: {plan_id}
+      status: complete
+      method: summary-only
+      timestamp: {ISO-8601}
+      ---
+
+      # Summary: {plan_title}
+
+      ## Goal
+      {objective from plan}
+
+      ## Tasks Completed
+      {For each task in plan:}
+      - [x] {task_name} — (pre-existing)
+
+      ## Outcome
+      All deliverables verified as present via preflight review.
+      No execution was performed — work was already complete.
+
+      ## Evidence
+      - Review checklist: .planning/reviews/{plan_id}-REVIEW.md
+      - Verified files: {list of files confirmed present}
+
+      ## Method
+      Generated via `--summary-only` flag after preflight confirmed all deliverables present.
+      ```
+
+   4. Write to: `.planning/phases/{phase}/{plan_id}-SUMMARY.md`
+
+   5. Update STATE.md to reflect completion
+
+   6. Display:
+      ```
+      ✓ SUMMARY.md generated (summary-only mode)
+
+      Plan: {plan_id}
+      Path: .planning/phases/{phase}/{plan_id}-SUMMARY.md
+
+      No execution performed — existing work documented.
+      ```
+
+   7. Exit (do not continue to step 1.5 or beyond)
+
+1.5. **Run handoff preflight**
+
+   Before any execution, check for drift:
+
+   ```bash
+   node ~/.claude/rrr/scripts/handoff-preflight.js --plan "$ARGUMENTS"
+   ```
+
+   Parse the JSON output (after `---JSON---` marker).
+
+   **Handle by recommendation:**
+
+   | Recommendation | Action |
+   |----------------|--------|
+   | `proceed` | Continue to step 2 |
+   | `warn_and_proceed` | Show warning, continue to step 2 |
+   | `reconcile_first` | Show decision gate (see below) |
+   | `review_instead_of_execute` | Show decision gate, do NOT proceed until user chooses |
+
+   **Decision gate (for reconcile_first or review_instead_of_execute):**
+
+   ```
+   ⚠ DRIFT DETECTED
+
+   {overlap_ratio}% of expected files already changed.
+   Changed: {changed_files_count} files
+   Expected: {expected_files_count} files
+   ```
+
+   Use AskUserQuestion:
+   - question: "Work may have started. How to proceed?"
+   - header: "Preflight"
+   - options:
+     - "Continue anyway" — Override, proceed to step 2
+     - "Review and mark progress (Recommended)" — Generate review checklist, exit
+     - "Capture as TODO" — Create pending todo, exit
+     - "Switch plan" — Show alternatives, exit
+
+   **If user selects "Review and mark progress":**
+   - Run: `node ~/.claude/rrr/scripts/handoff-preflight.js --plan "$ARGUMENTS" --generate-review`
+   - Display: "Review checklist created. Use it to assess progress."
+   - Exit without executing
+
+   **If user selects "Capture as TODO":**
+   - Create `.planning/todos/pending/{timestamp}-{plan}-preflight.md`
+   - Display: "TODO created for later review."
+   - Exit without executing
+
+   **If user selects "Switch plan":**
+   - If `possible_matching_plans` exists, show them
+   - Otherwise: "Run `/rrr:progress` to see available plans."
+   - Exit without executing
+
+   **If script not found or fails:**
+   - Log warning: `[PREFLIGHT] Script not found, skipping preflight check`
+   - Continue to step 2
+
 2. **Check if already executed**
    - Derive SUMMARY path from plan path (replace PLAN.md with SUMMARY.md)
    - If SUMMARY exists: "Plan already executed. SUMMARY: {path}"

package/commands/rrr/plan-phase.md

@@ -137,6 +137,43 @@ Use Grep tool: `Grep pattern: "Phase ${PHASE}:" path: ".planning/ROADMAP.md"` wi
 
 **If not found:** Error with available phases. **If found:** Extract phase number, name, description.
 
+## 3.5. Check for Drift Before Planning
+
+If existing plans exist for this phase, run preflight to detect if work may have already started:
+
+```bash
+node ~/.claude/rrr/scripts/handoff-preflight.js --phase ${PHASE}
+```
+
+**If `likely_already_started: true`:**
+
+Display warning:
+```
+⚠ You may have started Phase ${PHASE} work already.
+
+Changed files overlap with existing plan inventory.
+Overlap: {overlap_ratio}%
+```
+
+Use AskUserQuestion:
+- question: "Proceed with planning or reconcile first?"
+- header: "Drift"
+- options:
+  - "Continue planning" — Proceed normally
+  - "Review existing work first (Recommended)" — Generate review, then plan
+  - "Skip to execution" — Execute existing plans instead
+
+**If "Review existing work first":**
+- Run: `node ~/.claude/rrr/scripts/handoff-preflight.js --phase ${PHASE} --generate-review`
+- Display checklist
+- Return to planning after review
+
+**If "Skip to execution":**
+- Display: "Use `/rrr:execute-phase ${PHASE}` to run existing plans"
+- Exit
+
+**If script not found:** Continue without warning.
+
 ## 4. Ensure Phase Directory Exists (Cross-Platform)
 
 **On macOS/Linux:**

package/commands/rrr/progress.md

@@ -117,6 +117,15 @@ Exit.
 **Check active debug sessions (Cross-Platform):**
 - On macOS/Linux: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
 - On Windows: `Glob pattern: ".planning/debug/*.md"` — count results (exclude resolved/)
+
+**Run quick preflight check:**
+```bash
+node ~/.claude/rrr/scripts/handoff-preflight.js --phase {current_phase} 2>/dev/null
+```
+Parse result for `likely_already_started` and `overlap_ratio`.
+- If script fails or not found: set preflight_status = "unknown"
+- If `likely_already_started`: set preflight_status = "drift detected ({overlap_ratio}%)"
+- Otherwise: set preflight_status = "clean"
 </step>
 
 <step name="report">
@@ -150,6 +159,10 @@ CONTEXT: [✓ if CONTEXT.md exists | - if not]
 - [count] active — /rrr:debug to continue
 (Only show this section if count > 0)
 
+## Preflight Status
+- {preflight_status}
+(Show "✓ clean" if no drift, "⚠ drift detected (X%)" if overlap found, "? unknown" if script unavailable)
+
 ## What's Next
 [Next phase/plan objective from ROADMAP]
 ```
@@ -322,11 +335,30 @@ State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
 
 Read ROADMAP.md to get the next phase's name and goal.
 
+**Auto-run audit if progress >= 90%:**
+
+Calculate overall progress: `completed_plans / total_plans`.
+
+If progress >= 90%, run implementation audit:
+```bash
+node ~/.claude/rrr/scripts/verify-milestone.js --summary-only 2>/dev/null || node scripts/verify-milestone.js --summary-only 2>/dev/null
+```
+
+Include audit summary in output (if run).
+
 ```
 ---
 
 ## ✓ Phase {Z} Complete
 
+{If audit ran (progress >= 90%):}
+### Implementation Audit
+  ✓ Done: {done_count}
+  ⚠ Missing summaries: {likely_done_count}
+  ✗ Not done: {not_done_count}
+
+Full report: .planning/artifacts/VERIFY_WORK_AUDIT.md
+
 ## ▶ Next Up
 
 **Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
@@ -339,6 +371,7 @@ Read ROADMAP.md to get the next phase's name and goal.
 
 **Also available:**
 - `/rrr:verify-work {Z}` — user acceptance test before continuing
+- `/rrr:verify-work --audit` — full implementation audit
 - `/rrr:discuss-phase {Z+1}` — gather context first
 
 ---
@@ -348,6 +381,18 @@ Read ROADMAP.md to get the next phase's name and goal.
 
 **Route D: Milestone complete**
 
+**Auto-run implementation audit:**
+
+Before displaying the completion message, run verify-work in audit mode:
+
+```bash
+node ~/.claude/rrr/scripts/verify-milestone.js --summary-only 2>/dev/null || node scripts/verify-milestone.js --summary-only 2>/dev/null
+```
+
+This generates `.planning/artifacts/VERIFY_WORK_AUDIT.md` and prints summary counts.
+
+**Display result:**
+
 ```
 ---
 
@@ -355,6 +400,14 @@ Read ROADMAP.md to get the next phase's name and goal.
 
 All {N} phases finished!
 
+### Implementation Audit
+{Include summary counts from audit output}
+  ✓ Done: {done_count}
+  ⚠ Missing summaries: {likely_done_count}
+  ✗ Not done: {not_done_count}
+
+Full report: .planning/artifacts/VERIFY_WORK_AUDIT.md
+
 ## ▶ Next Up
 
 **Complete Milestone** — archive and prepare for next
@@ -366,7 +419,8 @@ All {N} phases finished!
 ---
 
 **Also available:**
-- `/rrr:verify-work` — user acceptance test before completing milestone
+- `/rrr:verify-work --audit` — full implementation audit report
+- `/rrr:verify-work` — interactive user acceptance test
 
 ---
 ```
@@ -377,7 +431,17 @@ All {N} phases finished!
 
 STATE.md indicates "Between milestones" — this is the expected state after completing a milestone.
 
-**Display status directly (no prompts needed):**
+**Auto-run implementation audit:**
+
+Before displaying the between-milestones message, run verify-work in audit mode:
+
+```bash
+node ~/.claude/rrr/scripts/verify-milestone.js --summary-only 2>/dev/null || node scripts/verify-milestone.js --summary-only 2>/dev/null
+```
+
+This generates `.planning/artifacts/VERIFY_WORK_AUDIT.md` and prints summary counts for the completed milestone.
+
+**Display status (with audit summary):**
 
 Read MILESTONES.md to find the last completed milestone version.
 
@@ -386,6 +450,14 @@ Read MILESTONES.md to find the last completed milestone version.
 
 ## ✓ Milestone v{X.Y} Complete
 
+### Implementation Audit
+{Include summary counts from audit output}
+  ✓ Done: {done_count}
+  ⚠ Missing summaries: {likely_done_count}
+  ✗ Not done: {not_done_count}
+
+Full report: .planning/artifacts/VERIFY_WORK_AUDIT.md
+
 Ready to plan the next milestone.
 
 ## ▶ Next Up

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']"
+argument-hint: "[phase number, e.g., '4'] [--audit]"
 allowed-tools:
   - Read
   - Bash
@@ -14,9 +14,12 @@ allowed-tools:
 <objective>
 Validate built features through conversational testing with persistent state.
 
-Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation.
+**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.
 
-Output: {phase}-UAT.md tracking all test results, gaps logged for /rrr:plan-phase --gaps
+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)
 </objective>
 
 <execution_context>
@@ -29,10 +32,80 @@ Phase: $ARGUMENTS (optional)
 - If provided: Test specific phase (e.g., "4")
 - If not provided: Check for active sessions or prompt for phase
 
+Flags:
+- `--audit` or `--implementation-only`: Non-interactive mode, check implementation status only
+
 @.planning/STATE.md
 @.planning/ROADMAP.md
 </context>
 
+<audit_mode>
+**If --audit flag is present:**
+
+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**
+
+Parse $ARGUMENTS for phase number and --audit flag.
+
+| Arguments | Scope |
+|-----------|-------|
+| `--audit 4` or `4 --audit` | Audit phase 4 only |
+| `--audit` (no phase) | 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)
+
+**Step 2: Run verification script**
+
+```bash
+node ~/.claude/rrr/scripts/verify-milestone.js --summary-only 2>/dev/null
+```
+
+**If auditing single phase, filter output:**
+- Only show results for the specified phase
+- Still generate full artifact but highlight relevant section
+
+**Step 3: Output to artifact**
+
+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`
+
+**Step 4: Display summary**
+
+```
+## Implementation Audit
+
+{Scope: Phase X | Entire Milestone}
+
+| Metric | Count |
+|--------|-------|
+| ✓ Done | {N} |
+| ⚠ Likely done (missing summary) | {N} |
+| ✗ Not done | {N} |
+| ? Suspicious | {N} |
+
+{If gaps exist:}
+### Gaps
+
+| Phase | Plan | Status | Action |
+|-------|------|--------|--------|
+| ... | ... | ... | ... |
+
+Full report: .planning/artifacts/VERIFY_WORK_AUDIT.md
+
+{If all done:}
+✓ All plans verified. Ready for milestone completion.
+```
+
+**Exit after audit - do not proceed to interactive UAT.**
+</audit_mode>
+
 <process>
 1. Check for active UAT sessions (resume or start new)
 2. Find SUMMARY.md files for the phase

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.9.4",
+  "version": "1.9.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/templates/review-checklist.md

@@ -0,0 +1,165 @@
+# Review Checklist Template
+
+*Template for preflight review checklists.*
+
+---
+
+## Usage
+
+This template is used by the handoff preflight workflow to generate review checklists when drift is detected.
+
+**Generated file location:** `.planning/reviews/{phase}-{plan}-REVIEW.md`
+
+---
+
+## Template Structure
+
+```markdown
+# Review Checklist: {phase}-{plan}
+
+*Generated by preflight on {timestamp}*
+*Overlap detected: {overlap_ratio}%*
+
+---
+
+## Plan Details
+
+| Field | Value |
+|-------|-------|
+| Plan ID | {plan_id} |
+| Title | {plan_title} |
+| Objective | {plan_objective} |
+| Expected files | {expected_files_count} |
+| Changed files | {changed_files_count} |
+
+---
+
+## Overlapping Files
+
+Files that appear in both "expected" and "changed":
+
+| File | Status | Notes |
+|------|--------|-------|
+| `{file_1}` | ☐ Review | |
+| `{file_2}` | ☐ Review | |
+
+**Status options:**
+- ☐ Review — Not yet checked
+- ✓ Aligned — Matches plan intent
+- ⚠ Partial — Partially complete
+- ✗ Diverged — Does not match plan
+
+---
+
+## Deliverables Checklist
+
+{Extracted from plan tasks}
+
+| # | Deliverable | Status | Evidence |
+|---|-------------|--------|----------|
+| 1 | {task_1_name} | ☐ Check | |
+| 2 | {task_2_name} | ☐ Check | |
+
+**Status options:**
+- ☐ Check — Not yet verified
+- ✓ Present — Already implemented
+- ○ Missing — Needs implementation
+- ? Unclear — Cannot determine
+
+---
+
+## Verification Commands
+
+{If plan has verification section}
+
+```bash
+# Command 1: {description}
+{verify_command_1}
+
+# Command 2: {description}
+{verify_command_2}
+```
+
+---
+
+## Recommendation
+
+### If all deliverables present (✓):
+
+The work appears complete. Generate SUMMARY.md with evidence instead of re-executing:
+
+1. Document what was found in SUMMARY.md
+2. Run `/rrr:execute-plan {plan_path} --summary-only`
+3. Or manually write: `.planning/phases/{phase}/{plan_id}-SUMMARY.md`
+
+### If partially complete (mixed ✓ and ○):
+
+Continue execution from current state:
+
+1. The executor will detect existing work
+2. It will skip completed tasks
+3. It will continue from first incomplete task
+
+```
+/rrr:execute-plan {plan_path}
+```
+
+### If mostly missing (○):
+
+Execute normally — previous changes may be unrelated:
+
+```
+/rrr:execute-plan {plan_path}
+```
+
+### If unclear (?):
+
+Manual review needed. Options:
+
+1. Read the changed files directly
+2. Run tests to verify behavior
+3. Ask team about recent changes
+
+---
+
+## Sign-off
+
+| Reviewer | Date | Decision |
+|----------|------|----------|
+| | | ☐ Execute / ☐ Mark complete / ☐ Defer |
+
+---
+
+*Review checklist generated by RRR handoff preflight.*
+```
+
+---
+
+## Field Descriptions
+
+| Field | Source | Description |
+|-------|--------|-------------|
+| phase | Plan path | Phase number (e.g., "05") |
+| plan | Plan path | Plan ID (e.g., "05-04") |
+| timestamp | System | ISO-8601 timestamp |
+| overlap_ratio | Preflight | Percentage overlap (0-100) |
+| plan_id | Plan frontmatter | Unique plan identifier |
+| plan_title | Plan frontmatter | Human-readable title |
+| plan_objective | Plan content | First line of objective |
+| expected_files | Plan frontmatter | files_modified + files_exclusive |
+| changed_files | Git diff | Working tree + staged changes |
+| task_N_name | Plan tasks | Extracted from task elements |
+| verify_command | Plan verification | Commands from verification section |
+
+---
+
+## Integration
+
+The preflight script generates this review by:
+
+1. Parsing PLAN.md for deliverables
+2. Comparing expected vs changed files
+3. Extracting verification commands
+4. Writing to `.planning/reviews/{phase}-{plan}-REVIEW.md`
+
+The workflow presents the review and routes based on user assessment.