projecta-rrr 1.8.0 → 1.9.1

package/README.md

@@ -385,35 +385,54 @@ Pushpa Mode will skip these phases and record them in the report for manual foll
 
 ### Verification Ladder
 
-RRR uses a deterministic verification ladder that triggers based on what the plan affects:
+RRR uses a deterministic verification ladder with **mandatory two-step verification** for frontend-impacting plans:
 
 **Plan Classification:**
-- **UI_AFFECTING** — plans touching frontend files, UI keywords, API routes used by UI
-- **BACKEND_ONLY** — plans with no user-visible impact (scripts, migrations, pure utilities)
+- **frontend_impact: true** — plans touching frontend files, UI keywords, API routes used by UI, FE integration
+- **frontend_impact: false** — plans with no user-visible impact (scripts, migrations, pure utilities)
 
-**Verification by Surface:**
+**Verification by Frontend Impact:**
 
-| Surface | unit_tests | playwright | chrome_visual_check |
-|---------|------------|------------|---------------------|
-| ui_affecting | Yes | Yes | Yes (skip in Pushpa) |
-| backend_only | Yes | No | No |
+| frontend_impact | unit_tests | playwright | browser_uat |
+|-----------------|------------|------------|-------------|
+| true | Yes | Yes | Yes (agent-browse or claude --chrome) |
+| false | Yes | No | No |
+
+**Two-Step Visual Verification (frontend_impact: true):**
+1. **Step 1: Playwright** — Automated headless E2E tests
+2. **Step 2: Browser UAT** — Natural language browser automation via agent-browse (preferred) or `claude --chrome` (fallback)
+
+**Browser UAT Tool Selection:**
+- **ANTHROPIC_API_KEY set + agent-browse plugin:** Uses agent-browse (natural language browser automation via Stagehand)
+- **ANTHROPIC_API_KEY not set + interactive:** Falls back to `claude --chrome`
+- **Pushpa/CI without ANTHROPIC_API_KEY:** Skipped (no automated browser available)
+
+**Installing agent-browse plugin (in Claude Code):**
+```bash
+/plugin marketplace add browserbase/agent-browse
+/plugin install agent-browse@browserbase
+```
+
+Both steps run even when Playwright passes — we want visual/UI confirmation.
 
 The planner automatically classifies plans and adds `verification:` frontmatter:
 ```yaml
 verification:
   surface: ui_affecting
+  frontend_impact: true
   required_steps:
     - unit_tests
     - playwright
-    - chrome_visual_check
+    - browser_uat
 ```
 
-### Visual Proof (Automated UX Verification)
+### Visual Proof (Mandatory Two-Step Verification)
 
-RRR includes automated visual proof via Playwright tests and UX telemetry capture.
+RRR includes automated visual proof via Playwright tests and browser UAT verification.
 
 **What it captures:**
 - Playwright test results (pass/fail)
+- Browser UAT confirmations (page renders, interactions, layout)
 - Console errors and warnings
 - Page errors (uncaught exceptions)
 - Network failures (4xx, 5xx, failed requests)
@@ -422,15 +441,20 @@ RRR includes automated visual proof via Playwright tests and UX telemetry captur
 **Artifacts location:**
 ```
 .planning/
-├── VISUAL_PROOF.md                    # Append-only run log
+├── VISUAL_PROOF.md                    # Append-only run log (both steps)
 └── artifacts/
-    └── playwright/
-        ├── report/                    # HTML report (index.html)
-        │   └── index.html
-        └── test-results/              # Per-test artifacts
-            ├── screenshot.png         # Captured on failure
-            ├── trace.zip              # Recorded trace
-            └── video.webm             # Recorded video
+    ├── playwright/
+    │   ├── report/                    # HTML report (index.html)
+    │   │   └── index.html
+    │   └── test-results/              # Per-test artifacts
+    │       ├── screenshot.png         # Captured on failure
+    │       ├── trace.zip              # Recorded trace
+    │       └── video.webm             # Recorded video
+    └── browser-uat/
+        └── {run_id}/                  # Browser UAT artifacts
+            ├── uat.log                # Execution log
+            ├── screenshot-*.png       # Captured screenshots
+            └── chrome-notes.md        # Claude chrome notes (fallback mode)
 ```
 
 **Modes** (configured in `.planning/config.json`):
@@ -442,27 +466,57 @@ RRR includes automated visual proof via Playwright tests and UX telemetry captur
 | `hybrid` | Headless first, prompt for interactive fallback on eligible failures |
 | `interactive_only` | Skip Playwright, show manual UAT checklist |
 
+**Browser UAT Gating** (in `.planning/config.json`):
+```json
+{
+  "visual_proof": {
+    "uat_gate": "non_blocking"  // or "blocking"
+  }
+}
+```
+- `non_blocking` (default): UAT failures logged but don't block execution
+- `blocking`: UAT failures exit with code 1 (for strict enforcement)
+
 **Commands:**
 ```bash
+# Playwright
 npm run e2e              # Run Playwright tests (headless)
 npm run e2e:headed       # Run with browser visible
 npm run e2e:ui           # Playwright UI mode (interactive)
 npm run visual:open      # Open last HTML report
-bash scripts/visual-proof.sh  # Full visual proof runner
-bash scripts/chrome-visual-check.sh  # Interactive Chrome verification
+
+# Visual Proof (two-step for frontend_impact: true)
+bash scripts/visual-proof.sh           # Playwright only
+bash scripts/visual-proof.sh --chrome  # Playwright + browser UAT (REQUIRED for FE)
+bash scripts/visual-proof.sh --pushpa  # Pushpa mode (headless)
+
+# Browser UAT directly
+FRONTEND_IMPACT=true bash scripts/browser-uat.sh  # Run browser UAT step
+```
+
+**Browser UAT Tool Selection:**
+- **agent-browse** (preferred): Requires `ANTHROPIC_API_KEY` and [browserbase/agent-browse](https://github.com/browserbase/agent-browse) plugin. Uses Stagehand for natural language browser automation.
+- **claude --chrome** (fallback): Interactive mode only. Falls back when no API key set.
+- **Skipped**: In Pushpa/CI without `ANTHROPIC_API_KEY` (no automated browser available).
+
+**Installing agent-browse (in Claude Code):**
+```bash
+/plugin marketplace add browserbase/agent-browse
+/plugin install agent-browse@browserbase
 ```
 
 **Interactive verification (UI_AFFECTING plans only):**
 ```bash
 npx playwright test --ui     # Playwright UI mode for exploratory testing
 npx playwright test --headed # See tests execute in browser
-bash scripts/chrome-visual-check.sh  # Claude Chrome for human-level verification
+FRONTEND_IMPACT=true bash scripts/browser-uat.sh  # Browser UAT check
 ```
 
 **Integration:**
-- Runs automatically after `/rrr:execute-phase` (if e2e tests exist)
-- Runs automatically after `/rrr:execute-plan` (if tests exist)
-- Runs in Pushpa Mode (headless Playwright only, chrome visual check skipped)
+- **Per-plan:** Runs automatically after `/rrr:execute-plan` when `frontend_impact: true` (Playwright + Browser UAT)
+- **Per-phase:** Runs automatically after `/rrr:execute-phase` (aggregates all plans)
+- **Pushpa Mode:** Headless Playwright + agent-browse (if `ANTHROPIC_API_KEY` set); no interactive fallback
+- **Backend-only plans** (`frontend_impact: false`): Unit tests only, visual steps skipped
 - Results logged to `.planning/VISUAL_PROOF.md` (append-only)
 
 **VISUAL_PROOF.md format:**
@@ -785,22 +839,33 @@ Community skills install to `.claude/skills/community/`.
 
 ### Vendoring Skills (Maintainers)
 
-RRR uses two vendoring scripts to pull skills from external repositories into the `rrr/skills/` directory:
+RRR uses vendoring scripts to pull skills from external repositories into the `rrr/skills/` directory:
 
 **Anthropic upstream skills** (`scripts/vendor-skills.sh`):
-Vendors official Anthropic skills into `rrr/skills/upstream/anthropic/`. Run by maintainers to update the bundled Anthropic skill set.
+Vendors official Anthropic skills into `rrr/skills/upstream/anthropic/`.
+
+**Vercel Agent Skills** (`scripts/vendor-vercel-skills.sh`):
+Vendors curated React/Next.js best practices from [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills). Small and included in npm package.
 
-**Community skill packs** (`scripts/vendor-community-skills.sh`):
-Vendors community skill packs into `rrr/skills/community/<pack-name>/`. By default, pulls from [ovachiever/droid-tings](https://github.com/ovachiever/droid-tings). This script is idempotent and only touches its target directory — it never modifies `upstream/` or `projecta/` folders.
+**droid-tings Skills** (`scripts/vendor-droid-tings-skills.sh`):
+Vendors AI/ML focused skills from [ovachiever/droid-tings](https://github.com/ovachiever/droid-tings). Large (~40MB), **not included in npm** to keep package lean. Vendor on-demand when needed.
 
 ```bash
 # Vendor Anthropic skills (maintainer use)
 bash scripts/vendor-skills.sh
 
-# Vendor community skills (droid-tings pack)
-bash scripts/vendor-community-skills.sh
+# Vendor Vercel skills (small, recommended for frontend)
+bash scripts/vendor-vercel-skills.sh
+
+# Vendor droid-tings skills (large, use allowlist)
+bash scripts/vendor-droid-tings-skills.sh --list                    # List available
+DROID_TINGS_ALLOWLIST="axolotl,unsloth" bash scripts/vendor-droid-tings-skills.sh  # Specific skills
 ```
 
+**npm Package Policy:**
+- `projecta/*`, `upstream/*`, `community/vercel/*` — included in npm
+- `community/droid-tings/*` — excluded (40MB), vendor locally if needed
+
 ---
 
 ## Troubleshooting

package/agents/rrr-planner.md

@@ -397,10 +397,11 @@ skills_mode: normal         # "normal" (default) or "minimal" (skip default skil
 
 verification:
   surface: ui_affecting     # ui_affecting | backend_only (REQUIRED)
+  frontend_impact: true     # true | false (REQUIRED - enables two-step visual verification)
   required_steps:           # Steps executor MUST run (auto-derived from surface)
     - unit_tests
     - playwright
-    - chrome_visual_check
+    - chrome_visual_check   # Two-step: automated Playwright + claude --chrome
 
 must_haves:
   truths: []                # Observable behaviors
@@ -468,6 +469,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `user_setup` | No | Human-required setup items |
 | `skills` | No | Skills to load for execution (auto-inferred if empty) |
 | `skills_mode` | No | `normal` (default) or `minimal` (skip default skill) |
+| `verification.frontend_impact` | Yes | `true` enables two-step visual verification (Playwright + chrome) |
 | `must_haves` | Yes | Goal-backward verification criteria |
 
 **Wave is pre-computed:** Wave numbers are assigned during planning. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number.
@@ -543,6 +545,17 @@ Every plan MUST include `verification:` frontmatter. The planner determines `sur
    - "frontend", "client-side", "browser", "user-facing"
    - "render", "display", "show", "visible"
 
+6. **Backend changes affecting FE integration**:
+   - API routes consumed by FE (app/api, pages/api)
+   - Contracts/DTOs used by FE
+   - Schema changes affecting UI types
+   - Auth/session flow changes
+   - CORS, cookies, redirects
+   - Webhooks displayed in UI
+   - Keywords: "integration", "wiring", "connect frontend", "hook up", "end-to-end"
+
+**Reference:** @~/.claude/rrr/references/frontend-impact-detection.md
+
 **BACKEND_ONLY** - plan has NO user-visible impact:
 
 1. **File path patterns** (ONLY these, no UI files):
@@ -568,6 +581,7 @@ Every plan MUST include `verification:` frontmatter. The planner determines `sur
 ```yaml
 verification:
   surface: ui_affecting
+  frontend_impact: true
   required_steps:
     - unit_tests
     - playwright
@@ -578,6 +592,7 @@ verification:
 ```yaml
 verification:
   surface: backend_only
+  frontend_impact: false
   required_steps:
     - unit_tests
 ```