projecta-rrr 1.11.0 → 1.11.2

package/agents/rrr-explore.md

@@ -247,6 +247,15 @@ Am I finding files by naming pattern?
   YES --> Use Glob (file pattern)
   NO  --> Re-evaluate what you're looking for
 ```
+
+### Efficiency Reminder
+
+After each semantic search, mentally note:
+- Characters returned (divide by 4 = tokens)
+- Multiply by 5.5 = what grep would have cost
+- Track cumulative savings for final report
+
+This takes <1 second and enables the Token Efficiency report that demonstrates semantic search value.
 </tool_strategy>
 
 <query_patterns>
@@ -437,6 +446,14 @@ When exploration is complete, return organized findings:
 ### Relationships
 [If call graph was explored, key relationships]
 
+### Token Efficiency
+| Metric | Value |
+|--------|-------|
+| Semantic queries | N |
+| Tokens used | N |
+| Est. grep tokens | N |
+| Tokens saved | N (X% reduction) |
+
 ### Confidence
 [HIGH/MEDIUM/LOW based on search result quality]
 ```
@@ -621,6 +638,42 @@ Total: ~1200 tokens, 5 minutes
 ```
 </token_efficiency>
 
+<metrics_tracking>
+## Displaying Token Savings
+
+After completing an exploration, report token efficiency in results.
+
+### What to Track
+
+For each search operation, estimate tokens:
+- **Semantic search result:** Characters returned / 4
+- **Estimated grep equivalent:** Semantic tokens * 5.5 (benchmark multiplier)
+
+### Example Tracking
+
+```
+Query: "how is authentication implemented"
+GrepAI returned: 3,200 characters = 800 tokens
+Estimated grep: 800 * 5.5 = 4,400 tokens
+Savings: 3,600 tokens (82% reduction)
+```
+
+### When to Display
+
+- Always include Token Efficiency section in exploration results
+- Show cumulative savings if multiple queries were needed
+- Round percentages to nearest whole number
+
+### Benchmark Reference
+
+Based on TOKEN-BENCHMARK.md analysis:
+- Conceptual queries: 78-84% reduction typical
+- Call graph traces: 91% reduction typical
+- Overall average: 85-91% reduction
+
+If your results differ significantly from benchmarks, note why in findings (e.g., very targeted query, complex codebase).
+</metrics_tracking>
+
 <integration>
 ## How Other Agents Use rrr-explore
 
@@ -656,6 +709,14 @@ When spawned for exploration, return structured findings:
 ### Code References
 [Specific code snippets with line numbers]
 
+### Token Efficiency
+| Metric | Value |
+|--------|-------|
+| Semantic queries | N |
+| Tokens used | N |
+| Est. grep tokens | N |
+| Tokens saved | N (X% reduction) |
+
 ### Confidence: [HIGH/MEDIUM/LOW]
 [Why this confidence level]
 
@@ -705,6 +766,7 @@ Explore:
 - [ ] Minimal files read (only what's needed)
 - [ ] Findings returned in structured format
 - [ ] High relevance in search results
+- [ ] Token efficiency reported in exploration results
 
 ### Quality Metrics
 

package/bin/install.js

@@ -710,6 +710,26 @@ function install(isGlobal) {
   copyWithPathReplacement(rrrSrc, rrrDest, pathPrefix);
   console.log(`  ${green}✓${reset} Installed commands/rrr`);
 
+  // Verify critical command files exist
+  const criticalCommands = ['help.md', 'progress.md', 'update.md', 'new-project.md'];
+  const missingCommands = [];
+  for (const cmd of criticalCommands) {
+    const cmdPath = path.join(rrrDest, cmd);
+    if (!fs.existsSync(cmdPath)) {
+      missingCommands.push(cmd);
+    }
+  }
+
+  if (missingCommands.length > 0) {
+    console.log(`  ${orange}ERROR:${reset} Critical commands missing after install:`);
+    for (const cmd of missingCommands) {
+      console.log(`    - ${cmd}`);
+    }
+    console.log(`\n  Installation may be corrupted. Try: rm -rf ${claudeDir} && npx projecta-rrr --global`);
+    process.exit(1);
+  }
+  console.log(`  ${green}✓${reset} Verified ${criticalCommands.length} critical commands exist`);
+
   // Copy rrr skill with path replacement
   const skillSrc = path.join(src, 'rrr');
   const skillDest = path.join(claudeDir, 'rrr');

package/commands/rrr/add-phase.md

@@ -16,6 +16,16 @@ This command appends sequential phases to the current milestone's phase list, au
 Purpose: Add planned work discovered during execution that belongs at the end of current milestone.
 
 **v1.11 Breaking Change:** Requires active milestone and no orphan phases before creating new phases.
+
+**When to use this command:**
+- Adding planned work at the END of current milestone
+- Work that should run AFTER all existing phases
+- New features discovered during planning
+
+**When to use /rrr:insert-phase instead:**
+- Urgent work that needs to run BEFORE remaining phases
+- Work that logically fits between existing phases
+- Bug fixes that should precede planned features
 </objective>
 
 <execution_context>
@@ -304,6 +314,9 @@ Phase {N} added to current milestone:
 Roadmap updated: {roadmap-path}
 Project state updated: .planning/STATE.md
 
+**Tip:** Need this phase to run sooner?
+Use `/rrr:insert-phase` to insert between existing phases (creates decimal numbers like 5.1).
+
 ---
 
 ## ▶ Next Up
@@ -317,7 +330,8 @@ Project state updated: .planning/STATE.md
 ---
 
 **Also available:**
-- `/rrr:add-phase <description>` — add another phase
+- `/rrr:add-phase <description>` — add another phase at end
+- `/rrr:insert-phase <after> <description>` — insert between phases (e.g., after Phase 5)
 - Review roadmap
 
 ---

package/commands/rrr/check-browser-uat.md

@@ -65,24 +65,25 @@ fi
 
 ## Report
 
-Print summary report:
+Print summary report with REASONING:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- BROWSER UAT SETUP CHECK
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Browser UAT Setup Check
+=======================
 
-| Check            | Status |
-|------------------|--------|
-| ANTHROPIC_API_KEY| {✓|✗}  |
-| agent-browse     | {✓|✗}  |
-| Dev server       | {✓|⚠}  |
-| Environment      | {Interactive|Headless} |
+| Check              | Status | Details |
+|--------------------|--------|---------|
+| ANTHROPIC_API_KEY  | {Y|X}  | {set to sk-...xxx | not set} |
+| agent-browse       | {Y|X}  | {installed | not installed} |
+| Dev server         | {Y|!}  | {running at URL | not reachable} |
+| Environment        | {value}| {Interactive | Headless} |
 
-**Tool Selection:** {agent-browse | claude --chrome | Skipped}
+---
+
+Tool Selection: {TOOL_NAME}
+Reason: {SPECIFIC_REASON}
 
-{Next steps based on status}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{Additional context based on selection}
 ```
 
 ## Tool Selection Logic
@@ -90,43 +91,77 @@ Print summary report:
 ```
 if api_key_present AND plugin_installed:
   tool = "agent-browse"
-  message = "✓ Ready for autonomous browser UAT"
+  reason = "API key found + plugin installed = full automation available"
+
 elif api_key_present AND environment == "interactive":
   tool = "claude --chrome"
-  message = "⚠ Will use claude --chrome fallback (interactive only)"
+  reason = "API key found but plugin missing. Falling back to interactive Chrome."
+  suggestion = "Install plugin for autonomous testing: /plugin marketplace add browserbase/agent-browse"
+
 elif environment == "interactive":
   tool = "claude --chrome (manual)"
-  message = "⚠ No API key. Will prompt for manual browser check."
+  reason = "No API key. You'll need to test manually in Chrome."
+  suggestion = "Set ANTHROPIC_API_KEY for automated browser testing"
+
 else:
   tool = "Skipped"
-  message = "✗ Browser UAT will be skipped in headless mode"
+  reason = "Headless mode without API key = no browser testing available"
+  suggestion = "Set ANTHROPIC_API_KEY=... to enable browser UAT in Pushpa/CI"
 ```
 
 ## Next Steps (conditional)
 
-If missing API key:
+**If tool = "agent-browse":**
 ```
-To enable browser UAT:
-  export ANTHROPIC_API_KEY=your-key-here
+Ready for Browser UAT
+---------------------
+Your setup supports fully automated browser testing.
+No further action needed.
 ```
 
-If missing plugin:
+**If tool = "claude --chrome" (plugin missing):**
 ```
-To install agent-browse:
+Fallback Mode: claude --chrome
+------------------------------
+Browser UAT will work but requires you to be present.
+
+To upgrade to autonomous testing:
   /plugin marketplace add browserbase/agent-browse
   /plugin install agent-browse@browserbase
+
+Then re-run: /rrr:check-browser-uat
 ```
 
-If server not running:
+**If tool = "claude --chrome" (no API key):**
 ```
-Start dev server before running visual proof:
-  npm run dev
+Manual Mode: claude --chrome
+----------------------------
+Browser UAT will prompt you to test manually.
+
+To enable AI-powered testing:
+  export ANTHROPIC_API_KEY=your-key-here
+
+Then re-run: /rrr:check-browser-uat
+```
+
+**If tool = "Skipped":**
 ```
+Browser UAT will be SKIPPED
+---------------------------
+Running in headless mode without ANTHROPIC_API_KEY.
 
-If everything ready:
+To enable browser UAT in Pushpa/CI:
+  1. export ANTHROPIC_API_KEY=your-key-here
+  2. Ensure agent-browse plugin is installed
+
+Browser UAT is optional - Playwright tests still run.
+See: rrr/references/browser-testing.md
+```
+
+**If server not running:**
 ```
-✓ Browser UAT setup complete!
-Run /rrr:execute-plan with a frontend_impact plan to test.
+Start dev server before running visual proof:
+  npm run dev
 ```
 </behavior>
 

package/commands/rrr/help.md

@@ -364,31 +364,46 @@ Usage: `/rrr:pause-work`
 ### Verification
 
 **`/rrr:verify-work [target] [--audit | --uat]`**
-Validate built features through audit or interactive UAT.
+Validate built features through evidence audit or interactive UAT.
 
-**Two modes:**
+**Two modes (pick based on your question):**
 
-| 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. |
+| Your Question | Mode | Command |
+|---------------|------|---------|
+| "Did Claude finish the work?" | Audit | `/rrr:verify-work --audit` (default) |
+| "Does the app actually work?" | UAT | `/rrr:verify-work --uat` |
+
+**Mode details:**
+
+| Mode | What it checks | When to use |
+|------|----------------|-------------|
+| `--audit` (default) | PLAN/SUMMARY existence, git commits | Quick evidence check, pre-release validation |
+| `--uat` | Manual testing with UAT.md tracking | Hands-on testing, finding UX bugs |
 
 **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
+- 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`
 
+**`/rrr:check-browser-uat`**
+Check browser UAT prerequisites and see which tool will be used.
+
+- Reports ANTHROPIC_API_KEY status
+- Reports agent-browse plugin status
+- Shows tool selection with reasoning
+- Provides setup instructions if needed
+
+Usage: `/rrr:check-browser-uat`
+
 ### Debugging
 
 **`/rrr:debug [issue description]`**
@@ -776,6 +791,39 @@ Plans are automatically classified by `frontend_impact` (replaces legacy `ui_aff
 
 Planner adds `verification.frontend_impact: true|false` frontmatter automatically based on file paths and keywords. See `rrr/references/frontend-impact-detection.md` for classification rules.
 
+**Gap Closure Workflow**
+
+When UAT finds issues, RRR supports iterative fixing:
+
+```
+/rrr:verify-work --uat 05        # UAT finds 3 issues
+                                 # Issues logged to 05-UAT.md with root causes
+/rrr:plan-phase 05 --gaps        # Creates fix plans from diagnosed gaps
+/rrr:execute-phase 05            # Executes fix plans
+/rrr:verify-work --uat 05        # Re-test (resumes from last position)
+```
+
+**How it works:**
+1. UAT mode tracks test progress in `{phase}-UAT.md`
+2. Issues are diagnosed automatically (root cause analysis)
+3. `--gaps` flag creates targeted fix plans from diagnosed issues
+4. Re-running UAT resumes from where you left off
+
+**Progress tracking:**
+- UAT.md shows: `Progress: 3/8 tests, 2 issues found`
+- Gap closure plans reference the specific gaps they address
+- Each iteration should close more gaps until all pass
+
+**When to stop iterating:**
+- All UAT tests pass
+- Remaining issues are deferred (documented in STATE.md)
+- User decides remaining issues are acceptable
+
+**Avoid infinite loops:**
+- If same gap reappears after fix, investigate root cause
+- Consider marking as tech debt rather than blocking
+- Use `/rrr:debug` for persistent issues
+
 **Visual Proof: Two-Step Verification**
 
 Frontend-impacting plans require **both** verification steps to be green:
@@ -790,6 +838,8 @@ Frontend-impacting plans require **both** verification steps to be green:
 
 **Browser UAT Tool Selection Matrix:**
 
+See `rrr/references/browser-testing.md` for complete documentation. Quick reference:
+
 | Environment | API Key? | Plugin? | Tool Used | Notes |
 |-------------|----------|---------|-----------|-------|
 | Interactive | Yes | Yes | agent-browse | Preferred - autonomous browser automation |
@@ -848,6 +898,17 @@ agent-browse enables autonomous browser automation without manual intervention.
 | "Connection refused on port 3000" | Dev server not started | Run `npm run dev` in another terminal |
 | "Plugin initialization failed" | MCP connection error | Restart Claude Code, reinstall plugin |
 
+**For comprehensive browser testing documentation:**
+```
+@rrr/references/browser-testing.md
+```
+
+This covers:
+- All three testing tools (Playwright, agent-browse, claude --chrome)
+- Decision tree for which tool runs when
+- Environment matrix (local, Pushpa, CI)
+- Setup instructions and troubleshooting
+
 **Checking your setup:**
 ```
 /rrr:check-browser-uat
@@ -1016,6 +1077,125 @@ skills:
         └── (vendor with scripts/vendor-droid-tings-skills.sh)
 ```
 
+## Semantic Search (GrepAI)
+
+RRR integrates with [GrepAI](https://github.com/yoanbernabeu/grepai) for semantic code search. Instead of grep patterns, ask natural language questions like "how is authentication implemented" and get relevant code chunks.
+
+### Why Semantic Search?
+
+| Approach | Query | Results |
+|----------|-------|---------|
+| Traditional grep | `grep -r "auth"` | 200+ lines, mostly noise |
+| Semantic search | "how is user authentication implemented" | 5-10 relevant code chunks |
+
+**Benefits:**
+- **90%+ token reduction** — focused results, not grep noise
+- **Concept discovery** — finds related code even without exact string matches
+- **Call graph analysis** — trace callers/callees through codebase
+
+### When to Use Each Tool
+
+| Query Type | Use | Example |
+|------------|-----|---------|
+| **Concept/behavior** | Semantic | "how is authentication implemented" |
+| **Exact identifier** | Grep | `findUserById`, `validateToken` |
+| **Pattern matching** | Grep | `TODO:`, `console.log` |
+| **Understanding flow** | Semantic | "what happens when a user logs in" |
+| **Finding definition** | Grep | `function processPayment` |
+| **Finding usage** | Call graph | `grepai_trace_callers processPayment` |
+
+**Semantic search is NOT good for:**
+- Exact variable/function names (use grep)
+- String literals or patterns (use grep)
+- Single-word searches like "thing" (too vague, use grep with context)
+
+**Semantic search IS good for:**
+- Natural language questions about behavior
+- Finding code when you don't know the exact names
+- Understanding how features are implemented
+- Discovering related code across the codebase
+
+### Setup
+
+**Prerequisites:**
+1. [Ollama](https://ollama.com/) installed and running
+2. Pull embedding model: `ollama pull nomic-embed-text`
+
+**Install GrepAI:**
+```bash
+# Download to ~/.local/bin (no sudo required)
+curl -L https://github.com/yoanbernabeu/grepai/releases/latest/download/grepai-darwin-arm64 -o ~/.local/bin/grepai
+chmod +x ~/.local/bin/grepai
+
+# Initialize in your project
+cd your-project
+~/.local/bin/grepai init
+```
+
+**Configure MCP (Claude Code):**
+Add to `.mcp.json` in your project:
+```json
+{
+  "mcpServers": {
+    "grepai": {
+      "command": "~/.local/bin/grepai",
+      "args": ["mcp-serve"]
+    }
+  }
+}
+```
+
+Restart Claude Code to load the MCP server.
+
+### Starting the Indexer
+
+GrepAI needs to index your codebase first:
+
+```bash
+# Start watcher (builds index and watches for changes)
+~/.local/bin/grepai watch
+
+# Or one-time index (without watching)
+~/.local/bin/grepai index
+```
+
+**Note:** `/rrr:resume-work` automatically checks index status and offers to start the watcher if needed.
+
+### Using Semantic Search
+
+**In Claude Code (via MCP tools):**
+- `grepai_search` — Natural language code search
+- `grepai_trace_callers` — Find what calls a function
+- `grepai_trace_callees` — Find what a function calls
+- `grepai_trace_graph` — Build complete call graph
+- `grepai_index_status` — Check index health
+
+**CLI usage:**
+```bash
+~/.local/bin/grepai search "retry mechanism with exponential backoff"
+~/.local/bin/grepai trace-callers validateUser
+~/.local/bin/grepai index status
+```
+
+### RRR Integration
+
+The `rrr-explore` agent uses semantic search as its primary strategy:
+1. Semantic search first (concepts and behaviors)
+2. Call graph tools for dependency mapping
+3. Grep only for exact identifier lookup
+
+See `@agents/rrr-explore.md` for full exploration patterns.
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "No index found" | Run `~/.local/bin/grepai watch` to build index |
+| "Ollama not running" | Start Ollama: `ollama serve` |
+| "Model not found" | Pull model: `ollama pull nomic-embed-text` |
+| Empty search results | Check index status: `~/.local/bin/grepai index status` |
+| MCP tools not available | Restart Claude Code after adding .mcp.json |
+
 ## External Skills (skills.sh Ecosystem)
 
 RRR automatically installs and manages external skills from the skills.sh ecosystem using the `add-skill` CLI.

package/commands/rrr/new-milestone.md

@@ -45,7 +45,12 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
 1.5. **Version consistency check (MANDATORY):**
 
-   Before writing any milestone files, verify version consistency:
+   Before writing any milestone files, verify version consistency.
+
+   **Important context:**
+   - `package.json` is the CANONICAL source of truth for the current version
+   - `/rrr:check-version` compares against npm registry (different concern — checks if release is published)
+   - Documentation version drift is normal after updates — auto-fix is almost always the right choice
 
    ```bash
    # Read canonical version from package.json
@@ -67,38 +72,50 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    - If CHANGELOG major.minor != canonical major.minor → MISMATCH
    - If planning docs reference different milestone version → MISMATCH
 
-   **If mismatch detected → STOP:**
+   **If mismatch detected:**
 
    ```
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   ⚠ VERSION MISMATCH DETECTED
+   VERSION SYNC NEEDED
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
    Canonical (package.json): {CANONICAL_VERSION}
    CHANGELOG.md:             {CHANGELOG_VERSION}
    Planning docs:            {ROADMAP_VERSION}
 
-   Cannot create milestone until versions are consistent.
+   This is normal after updates. Auto-fix will sync docs to package.json.
    ```
 
    Use AskUserQuestion:
    - header: "Version"
-   - question: "Version mismatch detected. How would you like to proceed?"
+   - question: "Documentation versions need sync. How would you like to proceed?"
    - options:
-     - "Run /rrr:check-version (Recommended)" — Diagnose and fix version drift
-     - "Auto-fix now" — Update docs to match package.json
+     - "Auto-fix now (Recommended)" — Update docs to match package.json
+     - "Run /rrr:check-version" — Check npm registry status (different concern — won't fix doc drift)
+     - "Continue anyway" — Proceed with mismatched versions (documentation debt)
      - "Abort" — Cancel milestone creation
 
+   **If "Auto-fix now (Recommended)":**
+   - Update CHANGELOG.md with [Unreleased] header if needed
+   - Update planning docs milestone references to match canonical
+   - Continue to step 2
+
    **If "Run /rrr:check-version":**
    ```
-   Run `/rrr:check-version` to diagnose and fix version drift, then return to `/rrr:new-milestone`
+   Note: /rrr:check-version compares package.json against the npm registry.
+   This is useful for checking publish status, but won't fix documentation drift.
+   You may still need to run "Auto-fix now" after.
+
+   Run `/rrr:check-version` to check registry status, then return to `/rrr:new-milestone`
    ```
    Exit command.
 
-   **If "Auto-fix now":**
-   - Update CHANGELOG.md with [Unreleased] header if needed
-   - Update planning docs milestone references to match canonical
-   - Continue to step 2
+   **If "Continue anyway":**
+   ```
+   Continuing with version mismatch. This creates documentation debt.
+   Consider running `/rrr:new-milestone` again later with "Auto-fix now" to sync versions.
+   ```
+   Continue to step 2.
 
    **If "Abort":** Exit command.