projecta-rrr 1.8.0 → 1.9.1

package/bin/install.js

@@ -16,6 +16,40 @@ const reset = '\x1b[0m';
 // Get version from package.json
 const pkg = require('../package.json');
 
+/**
+ * Detect if running inside the projecta-rrr source repository root
+ * This prevents creating duplicate .claude/ when developing RRR itself
+ */
+function isRrrSourceRepo() {
+  const cwd = process.cwd();
+  const src = path.join(__dirname, '..');
+
+  // Check if cwd is the source repo root
+  if (path.resolve(cwd) !== path.resolve(src)) {
+    return false;
+  }
+
+  // Verify it's actually the RRR source repo by checking package.json name
+  // and presence of key source directories
+  try {
+    const cwdPkgPath = path.join(cwd, 'package.json');
+    if (!fs.existsSync(cwdPkgPath)) return false;
+
+    const cwdPkg = JSON.parse(fs.readFileSync(cwdPkgPath, 'utf8'));
+    if (cwdPkg.name !== 'projecta-rrr') return false;
+
+    // Check for source directories that only exist in the repo
+    const requiredDirs = ['rrr', 'commands', 'agents', 'bin'];
+    for (const dir of requiredDirs) {
+      if (!fs.existsSync(path.join(cwd, dir))) return false;
+    }
+
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
 /**
  * Render banner with TTY-aware formatting
  * - Boxed ASCII banner for TTY with sufficient width
@@ -158,6 +192,173 @@ function writeSettings(settingsPath, settings) {
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
 
+/**
+ * Get the local Claude directory name based on context
+ * Centralizes the decision for consistency
+ */
+function getLocalClaudeDirName() {
+  return isRrrSourceRepo() ? '.claude-local' : '.claude';
+}
+
+/**
+ * Check if a hook file exists at the expected location
+ */
+function hookFileExists(claudeDir, hookName) {
+  const hookPath = path.join(claudeDir, 'hooks', hookName);
+  return fs.existsSync(hookPath);
+}
+
+/**
+ * Rewrite hook paths from one directory to another
+ * Used for self-healing when hooks point to wrong location
+ * @param {object} settings - The settings object to modify
+ * @param {string} fromDir - The directory pattern to replace (e.g., '.claude')
+ * @param {string} toDir - The directory to replace with (e.g., '.claude-local')
+ * @returns {boolean} - True if any paths were rewritten
+ */
+function rewriteHookPaths(settings, fromDir, toDir) {
+  let modified = false;
+  const fromPattern = `${fromDir}/hooks/`;
+  const toPattern = `${toDir}/hooks/`;
+
+  // Rewrite Stop hooks
+  if (settings.hooks?.Stop) {
+    for (const entry of settings.hooks.Stop) {
+      if (entry.hooks) {
+        for (const h of entry.hooks) {
+          if (h.command && h.command.includes(fromPattern) && h.command.includes('rrr-')) {
+            const newCommand = h.command.replace(fromPattern, toPattern);
+            console.log(`  ${yellow}⚠${reset} Rewrote hook path: ${fromPattern} → ${toPattern}`);
+            h.command = newCommand;
+            modified = true;
+          }
+        }
+      }
+    }
+  }
+
+  // Rewrite SessionStart hooks
+  if (settings.hooks?.SessionStart) {
+    for (const entry of settings.hooks.SessionStart) {
+      if (entry.hooks) {
+        for (const h of entry.hooks) {
+          if (h.command && h.command.includes(fromPattern) && h.command.includes('rrr-')) {
+            const newCommand = h.command.replace(fromPattern, toPattern);
+            console.log(`  ${yellow}⚠${reset} Rewrote hook path: ${fromPattern} → ${toPattern}`);
+            h.command = newCommand;
+            modified = true;
+          }
+        }
+      }
+    }
+  }
+
+  // Rewrite statusLine
+  if (settings.statusLine?.command?.includes(fromPattern)) {
+    const newCommand = settings.statusLine.command.replace(fromPattern, toPattern);
+    console.log(`  ${yellow}⚠${reset} Rewrote statusline path: ${fromPattern} → ${toPattern}`);
+    settings.statusLine.command = newCommand;
+    modified = true;
+  }
+
+  return modified;
+}
+
+/**
+ * Self-heal: Remove orphaned hook entries and rewrite stale paths in settings.json
+ * @param {object} settings - The settings object to modify
+ * @param {string} claudeDir - The target Claude directory
+ * @param {string} localDirName - The local directory name (.claude or .claude-local)
+ * @param {boolean} isGlobal - Whether this is a global install
+ * @returns {boolean} - True if any entries were removed or rewritten
+ */
+function removeOrphanedHooks(settings, claudeDir, localDirName, isGlobal) {
+  let modified = false;
+
+  // Self-heal: rewrite stale paths for local installs
+  // If we're installing to .claude-local but settings point to .claude, fix them
+  if (!isGlobal && localDirName === '.claude-local') {
+    if (rewriteHookPaths(settings, '.claude', '.claude-local')) {
+      modified = true;
+    }
+  }
+  // If we're installing to .claude but settings point to .claude-local, fix them
+  if (!isGlobal && localDirName === '.claude') {
+    if (rewriteHookPaths(settings, '.claude-local', '.claude')) {
+      modified = true;
+    }
+  }
+
+  // Check Stop hooks
+  if (settings.hooks?.Stop) {
+    const originalLength = settings.hooks.Stop.length;
+    settings.hooks.Stop = settings.hooks.Stop.filter(entry => {
+      if (entry.hooks) {
+        // Check each hook in the entry
+        return entry.hooks.every(h => {
+          if (h.command && h.command.includes('rrr-notify')) {
+            // Verify rrr-notify.sh exists
+            if (!hookFileExists(claudeDir, 'rrr-notify.sh')) {
+              console.log(`  ${yellow}⚠${reset} Removed orphaned rrr-notify hook (file missing)`);
+              return false;
+            }
+          }
+          return true;
+        });
+      }
+      return true;
+    });
+    if (settings.hooks.Stop.length < originalLength) {
+      modified = true;
+    }
+    // Clean up empty Stop array
+    if (settings.hooks.Stop.length === 0) {
+      delete settings.hooks.Stop;
+    }
+  }
+
+  // Check SessionStart hooks for rrr-check-update
+  if (settings.hooks?.SessionStart) {
+    const originalLength = settings.hooks.SessionStart.length;
+    settings.hooks.SessionStart = settings.hooks.SessionStart.filter(entry => {
+      if (entry.hooks) {
+        return entry.hooks.every(h => {
+          if (h.command && h.command.includes('rrr-check-update')) {
+            if (!hookFileExists(claudeDir, 'rrr-check-update.sh')) {
+              console.log(`  ${yellow}⚠${reset} Removed orphaned rrr-check-update hook (file missing)`);
+              return false;
+            }
+          }
+          return true;
+        });
+      }
+      return true;
+    });
+    if (settings.hooks.SessionStart.length < originalLength) {
+      modified = true;
+    }
+    if (settings.hooks.SessionStart.length === 0) {
+      delete settings.hooks.SessionStart;
+    }
+  }
+
+  // Check statusLine
+  if (settings.statusLine?.command?.includes('statusline.sh')) {
+    if (!hookFileExists(claudeDir, 'statusline.sh')) {
+      console.log(`  ${yellow}⚠${reset} Removed orphaned statusline hook (file missing)`);
+      delete settings.statusLine;
+      modified = true;
+    }
+  }
+
+  // Clean up empty hooks object
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  return modified;
+}
+
 /**
  * Count skill directories in a given directory (looks for SKILL.md files)
  */
@@ -329,9 +530,15 @@ function install(isGlobal) {
   // Priority: explicit --config-dir arg > CLAUDE_CONFIG_DIR env var > default ~/.claude
   const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
   const defaultGlobalDir = configDir || path.join(os.homedir(), '.claude');
+
+  // For local installs inside the RRR source repo, use .claude-local/ to avoid duplication
+  const isSourceRepo = !isGlobal && isRrrSourceRepo();
+  const localDirName = isSourceRepo ? '.claude-local' : '.claude';
+  // Note: getLocalClaudeDirName() can be used elsewhere for consistency
+
   const claudeDir = isGlobal
     ? defaultGlobalDir
-    : path.join(process.cwd(), '.claude');
+    : path.join(process.cwd(), localDirName);
 
   const locationLabel = isGlobal
     ? claudeDir.replace(os.homedir(), '~')
@@ -341,7 +548,12 @@ function install(isGlobal) {
   // Use actual path when CLAUDE_CONFIG_DIR is set, otherwise use ~ shorthand
   const pathPrefix = isGlobal
     ? (configDir ? `${claudeDir}/` : '~/.claude/')
-    : './.claude/';
+    : `./${localDirName}/`;
+
+  // Warn if installing to .claude-local in source repo
+  if (isSourceRepo) {
+    console.log(`  ${yellow}Note:${reset} Detected RRR source repo, using ${cyan}.claude-local/${reset} to avoid duplication\n`);
+  }
 
   console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`);
 
@@ -396,6 +608,18 @@ function install(isGlobal) {
   fs.writeFileSync(versionDest, pkg.version);
   console.log(`  ${green}✓${reset} Wrote VERSION (${pkg.version})`);
 
+  // Configure statusline and hooks in settings.json
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  const settings = readSettings(settingsPath);
+
+  // Self-heal: remove any orphaned hook entries and rewrite stale paths BEFORE copying new hooks
+  // This catches orphaned entries from previous bad installs and fixes path mismatches
+  if (removeOrphanedHooks(settings, claudeDir, localDirName, isGlobal)) {
+    console.log(`  ${green}✓${reset} Cleaned up orphaned/stale hook entries`);
+    // Write settings immediately to persist the cleanup
+    writeSettings(settingsPath, settings);
+  }
+
   // Copy hooks
   const hooksSrc = path.join(src, 'hooks');
   if (fs.existsSync(hooksSrc)) {
@@ -414,42 +638,41 @@ function install(isGlobal) {
     console.log(`  ${green}✓${reset} Installed hooks`);
   }
 
-  // Configure statusline and hooks in settings.json
-  const settingsPath = path.join(claudeDir, 'settings.json');
-  const settings = readSettings(settingsPath);
   const statuslineCommand = isGlobal
     ? '$HOME/.claude/hooks/statusline.sh'
-    : '.claude/hooks/statusline.sh';
+    : `${localDirName}/hooks/statusline.sh`;
   const updateCheckCommand = isGlobal
     ? '$HOME/.claude/hooks/rrr-check-update.sh'
-    : '.claude/hooks/rrr-check-update.sh';
+    : `${localDirName}/hooks/rrr-check-update.sh`;
   const notifyCommand = isGlobal
     ? '$HOME/.claude/hooks/rrr-notify.sh'
-    : '.claude/hooks/rrr-notify.sh';
+    : `${localDirName}/hooks/rrr-notify.sh`;
 
-  // Configure SessionStart hook for update checking
-  if (!settings.hooks) {
-    settings.hooks = {};
-  }
-  if (!settings.hooks.SessionStart) {
-    settings.hooks.SessionStart = [];
-  }
+  // Configure SessionStart hook for update checking (only if hook file exists)
+  if (hookFileExists(claudeDir, 'rrr-check-update.sh')) {
+    if (!settings.hooks) {
+      settings.hooks = {};
+    }
+    if (!settings.hooks.SessionStart) {
+      settings.hooks.SessionStart = [];
+    }
 
-  // Check if RRR update hook already exists
-  const hasRrrUpdateHook = settings.hooks.SessionStart.some(entry =>
-    entry.hooks && entry.hooks.some(h => h.command && h.command.includes('rrr-check-update'))
-  );
+    // Check if RRR update hook already exists
+    const hasRrrUpdateHook = settings.hooks.SessionStart.some(entry =>
+      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('rrr-check-update'))
+    );
 
-  if (!hasRrrUpdateHook) {
-    settings.hooks.SessionStart.push({
-      hooks: [
-        {
-          type: 'command',
-          command: updateCheckCommand
-        }
-      ]
-    });
-    console.log(`  ${green}✓${reset} Configured update check hook`);
+    if (!hasRrrUpdateHook) {
+      settings.hooks.SessionStart.push({
+        hooks: [
+          {
+            type: 'command',
+            command: updateCheckCommand
+          }
+        ]
+      });
+      console.log(`  ${green}✓${reset} Configured update check hook`);
+    }
   }
 
   // Install Pushpa Mode and MCP setup scripts to the project directory
@@ -469,43 +692,118 @@ function install(isGlobal) {
     addNpmScripts(projectDir, allInstalledScripts);
   }
 
-  return { settingsPath, settings, statuslineCommand, notifyCommand };
+  return { settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, localDirName, isGlobal };
+}
+
+/**
+ * Print doctor summary showing where hooks were installed and configured paths
+ */
+function printDoctorSummary(claudeDir, settings, localDirName, isGlobal) {
+  console.log(`\n  ${cyan}Hook Configuration Summary:${reset}`);
+
+  const hooksDir = path.join(claudeDir, 'hooks');
+  const hooksExist = fs.existsSync(hooksDir);
+
+  // Show hooks directory
+  const hooksDirLabel = isGlobal
+    ? hooksDir.replace(os.homedir(), '~')
+    : hooksDir.replace(process.cwd(), '.');
+  console.log(`  ${dim}Hooks installed to:${reset} ${hooksDirLabel}`);
+
+  // Show hook files
+  if (hooksExist) {
+    const hookFiles = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh'));
+    if (hookFiles.length > 0) {
+      console.log(`  ${dim}Hook files:${reset} ${hookFiles.join(', ')}`);
+    }
+  }
+
+  // Show settings.json hook paths
+  const configuredPaths = [];
+  if (settings.statusLine?.command) {
+    configuredPaths.push(`statusline: ${settings.statusLine.command}`);
+  }
+  if (settings.hooks?.SessionStart) {
+    for (const entry of settings.hooks.SessionStart) {
+      if (entry.hooks) {
+        for (const h of entry.hooks) {
+          if (h.command) {
+            configuredPaths.push(`SessionStart: ${h.command}`);
+          }
+        }
+      }
+    }
+  }
+  if (settings.hooks?.Stop) {
+    for (const entry of settings.hooks.Stop) {
+      if (entry.hooks) {
+        for (const h of entry.hooks) {
+          if (h.command) {
+            configuredPaths.push(`Stop: ${h.command}`);
+          }
+        }
+      }
+    }
+  }
+
+  if (configuredPaths.length > 0) {
+    console.log(`  ${dim}Configured paths in settings.json:${reset}`);
+    for (const p of configuredPaths) {
+      console.log(`    ${dim}•${reset} ${p}`);
+    }
+  }
 }
 
 /**
  * Apply statusline and notification config, then print completion message
  */
-function finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, shouldInstallStatusline, shouldInstallNotify) {
+function finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, shouldInstallStatusline, shouldInstallNotify, localDirName, isGlobal) {
+  // Only configure statusline if hook file exists
   if (shouldInstallStatusline) {
-    settings.statusLine = {
-      type: 'command',
-      command: statuslineCommand
-    };
-    console.log(`  ${green}✓${reset} Configured statusline`);
+    if (hookFileExists(claudeDir, 'statusline.sh')) {
+      settings.statusLine = {
+        type: 'command',
+        command: statuslineCommand
+      };
+      console.log(`  ${green}✓${reset} Configured statusline`);
+    } else {
+      console.log(`  ${yellow}⚠${reset} Skipped statusline (hook file not found)`);
+    }
   }
 
+  // Only configure notify hook if hook file exists
   if (shouldInstallNotify) {
-    if (!settings.hooks.Stop) {
-      settings.hooks.Stop = [];
+    if (hookFileExists(claudeDir, 'rrr-notify.sh')) {
+      if (!settings.hooks) {
+        settings.hooks = {};
+      }
+      if (!settings.hooks.Stop) {
+        settings.hooks.Stop = [];
+      }
+      // Remove any existing RRR notify hook first
+      settings.hooks.Stop = settings.hooks.Stop.filter(entry =>
+        !(entry.hooks && entry.hooks.some(h => h.command && h.command.includes('rrr-notify')))
+      );
+      settings.hooks.Stop.push({
+        hooks: [
+          {
+            type: 'command',
+            command: notifyCommand
+          }
+        ]
+      });
+      console.log(`  ${green}✓${reset} Configured completion notifications`);
+    } else {
+      console.log(`  ${yellow}⚠${reset} Skipped notifications (hook file not found)`);
     }
-    // Remove any existing RRR notify hook first
-    settings.hooks.Stop = settings.hooks.Stop.filter(entry =>
-      !(entry.hooks && entry.hooks.some(h => h.command && h.command.includes('rrr-notify')))
-    );
-    settings.hooks.Stop.push({
-      hooks: [
-        {
-          type: 'command',
-          command: notifyCommand
-        }
-      ]
-    });
-    console.log(`  ${green}✓${reset} Configured completion notifications`);
   }
 
   // Always write settings (hooks were already configured in install())
   writeSettings(settingsPath, settings);
 
+  // Print doctor summary
+  printDoctorSummary(claudeDir, settings, localDirName, isGlobal);
+
   console.log(`
   ${green}Done!${reset}
 
@@ -658,22 +956,23 @@ function promptLocation() {
   const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
   const globalPath = configDir || path.join(os.homedir(), '.claude');
   const globalLabel = globalPath.replace(os.homedir(), '~');
+  const localLabel = isRrrSourceRepo() ? './.claude-local' : './.claude';
 
   console.log(`  ${yellow}Where would you like to install?${reset}
 
   ${cyan}1${reset}) Global ${dim}(${globalLabel})${reset} - available in all projects
-  ${cyan}2${reset}) Local  ${dim}(./.claude)${reset} - this project only
+  ${cyan}2${reset}) Local  ${dim}(${localLabel})${reset} - this project only
 `);
 
   rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
     rl.close();
     const choice = answer.trim() || '1';
-    const isGlobal = choice !== '2';
-    const { settingsPath, settings, statuslineCommand, notifyCommand } = install(isGlobal);
+    const isGlobalChoice = choice !== '2';
+    const { settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, localDirName, isGlobal } = install(isGlobalChoice);
     // Interactive mode - prompt for optional features
     handleStatusline(settings, true, (shouldInstallStatusline) => {
       handleNotifications(settings, true, (shouldInstallNotify) => {
-        finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, shouldInstallStatusline, shouldInstallNotify);
+        finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, shouldInstallStatusline, shouldInstallNotify, localDirName, isGlobal);
       });
     });
   });
@@ -687,19 +986,19 @@ if (hasGlobal && hasLocal) {
   console.error(`  ${yellow}Cannot use --config-dir with --local${reset}`);
   process.exit(1);
 } else if (hasGlobal) {
-  const { settingsPath, settings, statuslineCommand, notifyCommand } = install(true);
+  const { settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, localDirName, isGlobal } = install(true);
   // Non-interactive - respect flags
   handleStatusline(settings, false, (shouldInstallStatusline) => {
     handleNotifications(settings, false, (shouldInstallNotify) => {
-      finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, shouldInstallStatusline, shouldInstallNotify);
+      finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, shouldInstallStatusline, shouldInstallNotify, localDirName, isGlobal);
     });
   });
 } else if (hasLocal) {
-  const { settingsPath, settings, statuslineCommand, notifyCommand } = install(false);
+  const { settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, localDirName, isGlobal } = install(false);
   // Non-interactive - respect flags
   handleStatusline(settings, false, (shouldInstallStatusline) => {
     handleNotifications(settings, false, (shouldInstallNotify) => {
-      finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, shouldInstallStatusline, shouldInstallNotify);
+      finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, shouldInstallStatusline, shouldInstallNotify, localDirName, isGlobal);
     });
   });
 } else {

package/commands/rrr/execute-phase.md

@@ -95,19 +95,22 @@ Phase: $ARGUMENTS
       npx playwright test
       ```
 
-   c. **Run chrome visual check** (if UI_AFFECTING AND not Pushpa mode):
+   c. **Run browser UAT** (if UI_AFFECTING):
       ```bash
-      # Skip in Pushpa mode
-      if [[ -n "${PUSHPA_MODE:-}" ]]; then
-        echo "SKIP: Chrome visual check disabled in Pushpa Mode"
-      else
-        bash scripts/chrome-visual-check.sh
-      fi
+      # Run browser UAT via browser-uat.sh
+      # Handles: agent-browse (preferred) → claude --chrome (fallback) → skip (Pushpa/CI without key)
+      FRONTEND_IMPACT=true PLAN_ID={phase} bash scripts/browser-uat.sh
       ```
 
-   d. **Confirm artifact locations** (if playwright ran):
+      **Tool selection:**
+      - **ANTHROPIC_API_KEY set:** Uses agent-browse (works in Pushpa/CI)
+      - **No key + interactive:** Falls back to claude --chrome
+      - **No key + Pushpa/CI:** Skipped (no automated browser available)
+
+   d. **Confirm artifact locations** (if tests ran):
       - `.planning/artifacts/playwright/test-results/` — screenshots, traces, videos
       - `.planning/artifacts/playwright/report/` — HTML report
+      - `.planning/artifacts/browser-uat/<run_id>/` — Browser UAT artifacts
 
    e. **Update VISUAL_PROOF.md** (append-only):
       ```markdown
@@ -118,7 +121,7 @@ Phase: $ARGUMENTS
       **Commands:**
       - `npm test` — {pass/fail or "skipped"}
       - `npx playwright test` — {pass/fail or "skipped" or "n/a (backend_only)"}
-      - `chrome_visual_check` — {pass/fail or "skipped (Pushpa)" or "n/a (backend_only)"}
+      - `browser_uat` — {pass/fail or "skipped" or "n/a (backend_only)"} (tool: agent-browse | claude-chrome)
 
       **Result:** {PASS|FAIL} ({passed}/{total} steps)
 
@@ -126,17 +129,18 @@ Phase: $ARGUMENTS
       {List any console errors observed, or "None"}
 
       ### Artifact Paths
-      - Report: `.planning/artifacts/playwright/report/index.html`
-      - Failures: `.planning/artifacts/playwright/test-results/`
+      - Playwright Report: `.planning/artifacts/playwright/report/index.html`
+      - Playwright Failures: `.planning/artifacts/playwright/test-results/`
+      - Browser UAT: `.planning/artifacts/browser-uat/<run_id>/`
 
       ---
       ```
 
    **Verification by phase surface:**
 
-   | Surface | unit_tests | playwright | chrome_visual_check |
-   |---------|------------|------------|---------------------|
-   | ui_affecting | Yes | Yes | Yes (skip in Pushpa) |
+   | Surface | unit_tests | playwright | browser_uat |
+   |---------|------------|------------|-------------|
+   | ui_affecting | Yes | Yes | Yes (agent-browse or claude --chrome) |
    | backend_only | Yes | No | No |
 
    **Visual proof failure does NOT block phase completion** — logged as warning only.