projecta-rrr 1.9.8 → 1.9.9

package/bin/install.js

@@ -6,6 +6,14 @@ const os = require('os');
 const readline = require('readline');
 const { execSync } = require('child_process');
 
+// Import install-roots utilities for duplicate detection and quarantine
+const {
+  detectAndQuarantineDuplicates,
+  writeInstallInfo,
+  getCurrentVersion,
+  getCanonicalRoots
+} = require('../rrr/lib/install-roots');
+
 /**
  * Detect if running on Windows
  */
@@ -670,13 +678,35 @@ function install(isGlobal) {
 
   console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`);
 
+  // GUARD: Prevent nested install paths
+  // If claudeDir is inside ~/.claude/rrr/, refuse to install to avoid nested ~/.claude/rrr/rrr/...
+  if (isGlobal && claudeDir.includes('/.claude/rrr/')) {
+    console.log(`  ${orange}⚠${reset} Warning: Detected nested .claude path`);
+    console.log(`  ${orange}⚠${reset} Refusing to install to avoid: ${claudeDir}`);
+    console.log(`  ${orange}⚠${reset} This looks like a corrupted or nested installation.`);
+    console.log(`\n  ${cyan}Fix:${reset} Run /rrr:doctor --fix to quarantine duplicates first.`);
+    console.log(`  ${cyan}Or:${reset} Remove the nested directory manually:`);
+    console.log(`     rm -rf ${claudeDir}`);
+    process.exit(1);
+  }
+
   // Create commands directory
   const commandsDir = path.join(claudeDir, 'commands');
   fs.mkdirSync(commandsDir, { recursive: true });
 
   // Copy commands/rrr with path replacement
+  // Dest must be: ~/.claude/commands/rrr (NOT ~/.claude/rrr/commands/rrr)
   const rrrSrc = path.join(src, 'commands', 'rrr');
   const rrrDest = path.join(commandsDir, 'rrr');
+
+  // Double-check we're not creating a nested structure
+  if (rrrDest.includes('/rrr/rrr/') || rrrDest.includes('\\rrr\\rrr\\')) {
+    console.log(`  ${orange}⚠${reset} Refusing to create nested install path:`);
+    console.log(`     ${rrrDest}`);
+    console.log(`  This would cause duplicate command issues.`);
+    process.exit(1);
+  }
+
   copyWithPathReplacement(rrrSrc, rrrDest, pathPrefix);
   console.log(`  ${green}✓${reset} Installed commands/rrr`);
 
@@ -737,6 +767,30 @@ function install(isGlobal) {
   fs.writeFileSync(versionDest, pkg.version);
   console.log(`  ${green}✓${reset} Wrote VERSION (${pkg.version})`);
 
+  // Write INSTALL_INFO.json for idempotency tracking
+  const installSource = isGlobal ? 'npx projecta-rrr --global' : 'npx projecta-rrr --local';
+  writeInstallInfo({
+    version: pkg.version,
+    installRoot: claudeDir,
+    npmDistTag: 'latest', // Will be updated by /rrr:update if needed
+    installerSource: installSource
+  }, { configDir: explicitConfigDir || process.env.CLAUDE_CONFIG_DIR });
+  console.log(`  ${green}✓${reset} Wrote INSTALL_INFO.json`);
+
+  // Quarantine any duplicate/legacy command roots BEFORE configuring hooks
+  // This ensures only one canonical root exists
+  if (isGlobal) {
+    console.log(`  ${green}✓${reset} Checking for duplicate installs...`);
+    const quarantineResult = detectAndQuarantineDuplicates({
+      configDir: explicitConfigDir || process.env.CLAUDE_CONFIG_DIR,
+      dryRun: false,
+      quiet: true
+    });
+    if (quarantineResult.quarantined.length > 0) {
+      console.log(`  ${green}✓${reset} Quarantined ${quarantineResult.quarantined.length} legacy/duplicate root(s)`);
+    }
+  }
+
   // Configure statusline and hooks in settings.json
   const settingsPath = path.join(claudeDir, 'settings.json');
   const settings = readSettings(settingsPath);

package/commands/rrr/doctor.md

@@ -0,0 +1,202 @@
+---
+name: rrr:doctor
+description: Diagnose and fix duplicate RRR installs - non-destructive with rollback
+argument-hint: [--report | --fix | --include-local]
+allowed-tools: Read, Bash, Glob, Grep, Edit, Write
+---
+
+<objective>
+Diagnose RRR installation for duplicate command roots and optionally fix them safely.
+
+**Safety first:**
+- NEVER deletes anything - only moves to quarantine
+- Always creates rollback script
+- Safe mode: doesn't auto-fix if ambiguous
+- Canonical override: always keeps healthy modern root
+
+**Two modes:**
+- `--report` (default): Show diagnostic report without making changes
+- `--fix`: Quarantine duplicate roots safely, keeping one canonical root
+- `--include-local`: Also scan/fix repo-local `.claude/commands/rrr`
+</objective>
+
+<windows_compatible>true</windows_compatible>
+
+<process>
+
+<step name="determine_script_path">
+Resolve the doctor script path:
+
+**If running from installed RRR:**
+```bash
+node ~/.claude/rrr/scripts/doctor-rrr.js --report
+```
+
+**If running from repo source (development):**
+```bash
+node scripts/doctor-rrr.js --report
+```
+
+Use whichever path exists.
+</step>
+
+<step name="run_report_mode">
+Run in report mode (default):
+
+```bash
+node <script-path> --report
+```
+
+**Expected output format:**
+```
+RRR Doctor Report
+════════════════════════════════════════════════════════════════
+
+Found 3 command root(s):
+
+  #   Score  Ver    Cmds  Status   Path
+  ────────────────────────────────────────────────────────────────
+  1   1100   1.9.8  44    ✅ active ~/.claude/rrr/commands/rrr
+  2   1005   1.9.7  44    ⚠ will q~ ~/.claude/commands/rrr
+  3    180   -      1     📁 local  ./claude/commands/rrr
+
+Selected active root: ~/.claude/rrr/commands/rrr
+  Score: 1100 | Commands: 44 | Version: 1.9.8
+
+Will quarantine:
+  • ~/.claude/commands/rrr
+
+════════════════════════════════════════════════════════════════
+```
+</step>
+
+<step name="interpret_report">
+Interpret the scoring:
+
+| Signal | Points |
+|--------|--------|
+| Canonical path (`~/.claude/rrr/commands/rrr`) | +1000 |
+| Legacy path (`~/.claude/commands/rrr`) | +900 |
+| Nested bad path (`~/.claude/rrr/rrr/...`) | +100 |
+| 40+ commands | +50 |
+| 30+ commands | +30 |
+| 10+ commands | +10 |
+| Required files (progress, update, verify-work, help) | +10 each |
+| Has valid VERSION file | +50 |
+| No VERSION but has commands | +20 |
+| Newest commands | +5 |
+
+**Canonical override:** If `~/.claude/rrr/commands/rrr` exists and is healthy (30+ commands, has progress.md + update.md), it is ALWAYS selected.
+
+**Safe mode:** If top two candidates are within 20 points, doctor doesn't auto-fix.
+</step>
+
+<step name="run_fix_mode">
+If `--fix` flag is present:
+
+```bash
+node <script-path> --fix
+```
+
+**What happens:**
+1. Duplicates are MOVED to `~/.claude/rrr/_quarantine/<timestamp>/`
+2. Rollback scripts are created (`.sh` and `.ps1`)
+3. Validation runs to confirm exactly one root remains
+
+**Expected output:**
+```
+RRR Doctor --fix Complete
+════════════════════════════════════════════════════════════════
+
+✓ Selected: ~/.claude/rrr/commands/rrr
+  Score: 1100 | Commands: 44
+
+Quarantined 1 duplicate(s):
+  • ~/.claude/commands/rrr → quarantine
+
+───────────────────────────────────────────────────────────────
+Rollback available:
+  macOS/Linux: bash "~/.claude/rrr/_quarantine/<ts>/rollback.sh"
+  Windows:     powershell "...rollback.ps1"
+
+Validation:
+  ✓ Exactly one active root: YES
+  ✓ Required files present: YES
+  ⚠ Skills registry: exists
+
+Next step: Restart Claude Code to refresh commands.
+════════════════════════════════════════════════════════════════
+```
+</step>
+
+<step name="show_rollback_instructions">
+After --fix, show rollback instructions:
+
+**To rollback (undo the fix):**
+
+macOS/Linux:
+```bash
+bash ~/.claude/rrr/_quarantine/<timestamp>/rollback.sh
+```
+
+Windows (PowerShell):
+```powershell
+powershell "$env:USERPROFILE\.claude\rrr\_quarantine\<timestamp>\rollback.ps1"
+```
+
+**Important:** Rollback restores the quarantined duplicates. After rollback, you'll see duplicate commands again until you re-run doctor or reinstall.
+</step>
+
+<step name="include_local_mode">
+For repo-local installs, use `--include-local`:
+
+```bash
+node <script-path> --report --include-local
+node <script-path> --fix --include-local
+```
+
+This also scans for `./.claude/commands/rrr` and quarantines it along with other duplicates.
+
+**Default behavior:** Repo-local roots are reported but NOT quarantined unless `--include-local` is passed. This protects user-authored local overrides.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Report mode shows all detected command roots with scores
+- [ ] Report explains selection reason (canonical override or highest score)
+- [ ] Safe mode triggers when candidates are ambiguous
+- [ ] Fix mode quarantines duplicates (moves, never deletes)
+- [ ] Rollback scripts are created for both Unix and Windows
+- [ ] Validation confirms exactly one root remains
+- [ ] Repo-local roots are protected by default
+- [ ] Works on Windows (no bash constructs)
+</success_criteria>
+
+<notes>
+**Quarantine location:**
+- `~/.claude/rrr/_quarantine/<timestamp>-<original-name>/`
+- Contains original directory structure
+- Logged in `~/.claude/rrr/_quarantine/QUARANTINE_LOG.json`
+
+**Rollback scripts:**
+- macOS/Linux: `rollback.sh` (bash)
+- Windows: `rollback.ps1` (PowerShell)
+- Safe to delete quarantine folder if you don't need rollback
+
+**Canonical root priority (highest wins):**
+1. `~/.claude/rrr/commands/rrr` (+1000) - MODERN CANONICAL
+2. `~/.claude/commands/rrr` (+900) - LEGACY VALID
+3. `~/.claude/rrr/rrr/commands/rrr` (+100) - BAD NESTED
+4. Others (+0)
+
+**Safe mode triggers when:**
+- Top two candidates score within 20 points
+- AND canonical override doesn't apply
+- Prevents guessing when installation state is unclear
+
+**Symptoms of duplicates:**
+- Seeing "two /rrr:progress" commands
+- Commands appearing multiple times in help
+- Update not taking effect
+</notes>

package/commands/rrr/help.md

@@ -68,18 +68,45 @@ Output ONLY the reference content below. Do NOT add:
 
 ## Staying Updated
 
-RRR evolves fast. Check for updates periodically:
+RRR evolves fast. Check for updates and diagnose issues:
 
 ```
-/rrr:whats-new
+/rrr:update
 ```
 
-Shows what changed since your installed version. Update with:
+Updates RRR to latest version with idempotent install:
+- Detects and quarantines duplicate/legacy install roots
+- Installs exact version from npm (version-pinned via `@latest`)
+- Verifies installation integrity
+- Displays changelog for versions in range
+- Safe to run multiple times - never creates duplicates
 
-```bash
-npx projecta-rrr@latest
+```
+/rrr:doctor
+```
+
+Diagnoses and fixes duplicate RRR installs:
+- Detects multiple command roots that cause duplicate commands
+- Shows table of all found roots with status (preferred/duplicate)
+- Lists duplicate command names (e.g., two rrr:progress)
+- With `--fix`: quarantines duplicates safely to `~/.claude/rrr/_quarantine/`
+- Keeps only one canonical root active
+
+**If you see duplicate commands** (two /rrr:progress, etc.):
+```
+/rrr:doctor          # See what's wrong
+/rrr:doctor --fix    # Quarantine duplicates
+```
+Then restart Claude Code.
+
+```
+/rrr:whats-new
 ```
 
+See what's changed since your installed version.
+
+Shows installed vs latest version comparison and changelog entries for versions you've missed.
+
 ## Core Workflow
 
 ```
@@ -461,6 +488,29 @@ To include: add to PLAN frontmatter `skills: [projecta.shadcn-ui, projecta.mcp-s
 **`/rrr:help`**
 Show this command reference.
 
+**`/rrr:doctor`**
+Diagnose and fix duplicate RRR installs - non-destructive with rollback.
+
+**If you see duplicate commands (two /rrr:progress), run this!**
+
+Features:
+- Detects all command roots (global + repo-local)
+- Scores each root by completeness, version, freshness
+- Canonical override: keeps healthy modern root (`~/.claude/rrr/commands/rrr`)
+- Safe mode: doesn't auto-fix if scores are ambiguous
+- `--fix`: Quarantines duplicates (moves, never deletes)
+- `--include-local`: Also scan/fix repo-local `.claude/commands/rrr`
+- Creates rollback scripts (`.sh` and `.ps1`)
+
+Usage:
+```
+/rrr:doctor                  # Report only
+/rrr:doctor --fix            # Quarantine duplicates safely
+/rrr:doctor --fix --include-local  # Include repo-local roots
+```
+
+After `--fix`, restart Claude Code. To undo: run the rollback script shown.
+
 **`/rrr:check-version`**
 Check version consistency across package.json, CHANGELOG, and planning docs.
 

package/commands/rrr/update.md

@@ -1,49 +1,61 @@
 ---
 name: rrr:update
-description: Update RRR to latest version with changelog display
+description: Update RRR to latest version with idempotent install + duplicate prevention
 ---
 
 <objective>
-Check for RRR updates, install if available, and display what changed.
+Update RRR to the latest version with guaranteed idempotency.
 
-Provides a better update experience than raw `npx projecta-rrr` by showing version diff and changelog entries.
+This command:
+1. Checks npm for the latest version
+2. Installs using npx (not npm install -g, which can fail on macOS due to EACCES)
+3. Quarantines any duplicate/legacy install roots automatically
+4. Verifies installation integrity
+5. Recommends running /rrr:doctor if duplicates are detected
+
+Safe to run multiple times - will never create duplicate command roots.
 </objective>
 
+<windows_compatible>true</windows_compatible>
+
 <process>
 
-<step name="get_installed_version">
-Read installed version:
+<step name="get_current_version">
+Read current installed version from INSTALL_INFO.json (preferred) or VERSION file:
+
+**Check INSTALL_INFO.json first:**
+```bash
+cat ~/.claude/rrr/INSTALL_INFO.json 2>/dev/null | jq -r '.version'
+```
 
+**Fallback to VERSION file:**
 ```bash
 cat ~/.claude/rrr/VERSION 2>/dev/null
 ```
 
-**If VERSION file missing:**
+**If both missing:**
 ```
 ## RRR Update
 
-**Installed version:** Unknown
+**Installed version:** Unknown (fresh install)
 
-Your installation doesn't include version tracking.
-
-Running fresh install...
+Proceeding with fresh install...
 ```
-
-Proceed to install step (treat as version 0.0.0 for comparison).
+Treat as version 0.0.0 for comparison.
 </step>
 
 <step name="check_latest_version">
-Check npm for latest version:
+Get the latest version from npm:
 
 ```bash
-npm view projecta-rrr version 2>/dev/null
+npm view projecta-rrr dist-tags.latest 2>/dev/null
 ```
 
 **If npm check fails:**
 ```
 Couldn't check for updates (offline or npm unavailable).
 
-To update manually: `npx projecta-rrr --global`
+To update manually: npx --yes projecta-rrr@latest --global
 ```
 
 STOP here if npm unavailable.
@@ -60,6 +72,8 @@ Compare installed vs latest:
 **Latest:** X.Y.Z
 
 You're already on the latest version.
+
+Run /rrr:doctor to verify installation integrity.
 ```
 
 STOP here if already up to date.
@@ -77,15 +91,33 @@ You're ahead of the latest release (development version?).
 STOP here if ahead.
 </step>
 
-<step name="run_update">
-Run the update:
+<step name="run_idempotent_update">
+Run the update with version pinning:
 
 ```bash
-npx projecta-rrr --global
+npx --yes projecta-rrr@latest --global
 ```
 
-Capture output. If install fails, show error and STOP.
+**Critical:**
+- Uses `@latest` to pin to exact version at install time
+- Uses `--yes` to skip interactive prompts
+- Does NOT use `npm install -g` (avoids EACCES errors on macOS)
+
+**On Windows (PowerShell):**
+```powershell
+npx --yes projecta-rrr@latest --global
+```
 
+**Capture output and verify:**
+1. Should complete without error
+2. Should show "Wrote INSTALL_INFO.json"
+3. Should show "Quarantined X legacy/duplicate root(s)" if any were found
+
+**If install fails:**
+Show error and STOP. Do not proceed.
+</step>
+
+<step name="clear_update_cache">
 Clear the update cache so statusline indicator disappears:
 
 ```bash
@@ -93,6 +125,30 @@ rm -f ~/.claude/cache/rrr-update-check.json
 ```
 </step>
 
+<step name="verify_and_recommend_doctor">
+Verify the installation and recommend doctor if needed:
+
+```bash
+node ~/.claude/rrr/scripts/doctor-rrr.js --report
+```
+
+**If duplicates were detected during install:**
+```
+## RRR Update
+
+⚠️ Duplicates were detected and quarantined during install.
+
+Run /rrr:doctor --fix to complete cleanup.
+```
+
+**If installation verified healthy:**
+```
+## RRR Update
+
+✓ Installation verified healthy (no duplicates)
+```
+</step>
+
 <step name="fetch_changelog">
 Fetch changelog from GitHub:
 
@@ -116,13 +172,16 @@ Parse each `## [X.Y.Z]` section and collect all versions in the range.
 </step>
 
 <step name="display_result">
-Format beautiful output:
+Format output:
 
 ```
 ╔═══════════════════════════════════════════════════════════╗
 ║  RRR Updated: v1.5.10 → v1.5.15                           ║
 ╚═══════════════════════════════════════════════════════════╝
 
+✓ Installation verified (no duplicates)
+✓ quarantined 2 legacy install root(s)
+
 ✨ What's New
 ────────────────────────────────────────────────────────────
 
@@ -139,27 +198,47 @@ Format beautiful output:
 
 ────────────────────────────────────────────────────────────
 
-⚠️  Restart Claude Code to pick up the new commands.
+Restart Claude Code to pick up the new commands:
+
+  1. Type: exit
+  2. Run: claude
 
 [View full changelog](https://github.com/PA-Ai-Team/projecta-rrr/blob/main/CHANGELOG.md)
 ```
-
-**Key elements:**
-- Box header with version transition
-- All changelog entries in the range
-- **BREAKING:** changes surfaced prominently
-- Restart reminder (critical for picking up new commands)
-- Link to full changelog
 </step>
 
 </process>
 
 <success_criteria>
-- [ ] Installed version read correctly
+- [ ] Current version read correctly (INSTALL_INFO.json preferred)
 - [ ] Latest version checked via npm
+- [ ] Update uses npx (NOT npm install -g)
 - [ ] Update skipped if already current
-- [ ] Update executed successfully
+- [ ] Update executed with version-pinned npx
+- [ ] Duplicates quarantined automatically
+- [ ] Installation verified after update
+- [ ] Doctor recommended if issues found
 - [ ] Changelog fetched (remote or local fallback)
 - [ ] Changes between versions displayed
 - [ ] Restart reminder shown
 </success_criteria>
+
+<notes>
+**Why npx instead of npm install -g?**
+
+- `npm install -g` often fails on macOS due to EACCES permission errors
+- `npx` downloads and runs the package directly, avoiding global install issues
+- Version-pinned `@latest` ensures deterministic installs
+
+**Duplicate prevention:**
+- Before install, any existing duplicate roots are quarantined
+- After install, verification confirms only canonical root exists
+- Quarantine location: `~/.claude/rrr/_quarantine/<timestamp>/`
+
+**If you see duplicate commands:**
+Run: `/rrr:doctor --fix`
+
+**Windows compatibility:**
+- Uses Node.js file operations (no bash constructs like `||`, `find`, `head`)
+- Verification via `node doctor-rrr.js --report` works on all platforms
+</notes>