projecta-rrr 1.16.6 → 1.16.7

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to RRR will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.16.7] - 2026-01-28
+
+### Added
+- **Memory System** (`rrr/lib/memory-store.js`) - Central library for tracking:
+  - Command history with intent extraction
+  - Current user intent persistence
+  - Decision log with rationale
+  - Drift detection (context drift, stale plans, decision conflicts)
+
+- **Visual HUD** (`scripts/rrr-hud.js`) - ASCII progress display showing:
+  - Milestone progress bar with percentage
+  - Per-phase completion status
+  - Drift status (green/yellow/red)
+  - Current intent from memory
+
+- **Proactive Guidance** (`scripts/rrr-memory/state-detector.js`) - State-aware suggestions:
+  - 4D state analysis (project, milestone, phase, action)
+  - `guidanceFor(command)` for 17 command scenarios
+  - Orphan phase detection and migration guidance
+
+- **Memory-Enriched Preflight** (`scripts/handoff-preflight.js`) - Drift detection on handoff
+
+### Changed
+- **Phase path resolution** (`rrr/lib/phase-paths.md`) - Fixed bug where phases were created outside milestones when no `:construction:` marker existed. Now errors if `.planning/milestones/` exists but no active milestone detected.
+
+- **execute-plan** - Tracks intent before execution for drift detection
+
+- **verify-work** - Shows memory context during verification
+
+- **add-phase / insert-phase** - Validates no orphan phases exist before allowing new phase creation
+
+- **Duplicate prevention** (`bin/install.js`, `scripts/doctor-rrr.js`) - Auto-cleans old quarantine directories (>7 days) to prevent duplicate command scanning
+
+### Fixed
+- **Duplicate commands** - 282 command references reduced to 41 by cleaning old quarantines
+
 ## [1.16.6] - 2026-01-28
 
 ### Added

package/bin/install.js

@@ -11,7 +11,8 @@ const {
   detectAndQuarantineDuplicates,
   writeInstallInfo,
   getCurrentVersion,
-  getCanonicalRoots
+  getCanonicalRoots,
+  cleanOldQuarantines
 } = require('../rrr/lib/install-roots');
 
 /**
@@ -909,6 +910,38 @@ function install(isGlobal) {
     console.log(`  ${green}✓${reset} Installed rrr/scripts/test-install-smoke.js`);
   }
 
+  // PATCH-01: Copy handoff-preflight.js to ~/.claude/rrr/scripts/
+  // Memory-enriched preflight for drift detection
+  const handoffSrc = path.join(src, 'scripts', 'handoff-preflight.js');
+  if (fs.existsSync(handoffSrc)) {
+    const scriptsDestDir = path.join(claudeDir, 'rrr', 'scripts');
+    fs.mkdirSync(scriptsDestDir, { recursive: true });
+    const handoffDest = path.join(scriptsDestDir, 'handoff-preflight.js');
+    fs.copyFileSync(handoffSrc, handoffDest);
+    console.log(`  ${green}✓${reset} Installed rrr/scripts/handoff-preflight.js`);
+  }
+
+  // PATCH-01: Copy rrr-hud.js to ~/.claude/rrr/scripts/
+  // Visual HUD for project state display
+  const hudSrc = path.join(src, 'scripts', 'rrr-hud.js');
+  if (fs.existsSync(hudSrc)) {
+    const scriptsDestDir = path.join(claudeDir, 'rrr', 'scripts');
+    fs.mkdirSync(scriptsDestDir, { recursive: true });
+    const hudDest = path.join(scriptsDestDir, 'rrr-hud.js');
+    fs.copyFileSync(hudSrc, hudDest);
+    console.log(`  ${green}✓${reset} Installed rrr/scripts/rrr-hud.js`);
+  }
+
+  // PATCH-01: Copy rrr-memory/ directory to ~/.claude/rrr/scripts/
+  // Memory store and state detector for proactive guidance
+  const rrrMemorySrc = path.join(src, 'scripts', 'rrr-memory');
+  if (fs.existsSync(rrrMemorySrc)) {
+    const scriptsDestDir = path.join(claudeDir, 'rrr', 'scripts');
+    const rrrMemoryDest = path.join(scriptsDestDir, 'rrr-memory');
+    copyWithPathReplacement(rrrMemorySrc, rrrMemoryDest, pathPrefix);
+    console.log(`  ${green}✓${reset} Installed rrr/scripts/rrr-memory/`);
+  }
+
   // Copy skills to ~/.claude/skills (skills system)
   const skillsSrc = path.join(src, 'rrr', 'skills');
   if (fs.existsSync(skillsSrc)) {
@@ -963,6 +996,15 @@ function install(isGlobal) {
     if (quarantineResult.quarantined.length > 0) {
       console.log(`  ${green}✓${reset} Quarantined ${quarantineResult.quarantined.length} legacy/duplicate root(s)`);
     }
+
+    // Clean up old quarantine directories (>7 days) to prevent duplicate command scanning
+    console.log(`  ${green}✓${reset} Cleaning old quarantine directories...`);
+    const cleanupResult = cleanOldQuarantines({
+      configDir: explicitConfigDir || process.env.CLAUDE_CONFIG_DIR
+    });
+    if (cleanupResult.cleaned.length > 0) {
+      console.log(`  ${green}✓${reset} Cleaned ${cleanupResult.cleaned.length} old quarantine folder(s)`);
+    }
   }
 
   // Register rrr-search MCP server and run semantic migration

package/commands/rrr/add-phase.md

@@ -33,6 +33,7 @@ Purpose: Add planned work discovered during execution that belongs at the end of
 @.planning/STATE.md
 @rrr/lib/phase-paths.md
 @rrr/lib/milestone-utils.md
+@rrr/lib/memory-store.js
 </execution_context>
 
 <process>
@@ -68,6 +69,50 @@ Example: /rrr:add-phase Add authentication system
 Exit.
 </step>
 
+<step name="check_orphan_phases_memory">
+**Check for orphan phases using state-detector (PATCH-01 enhancement)**
+
+Before creating phases, check if there are orphan phases that need migration:
+
+```bash
+# Check for orphan phases
+node -e "
+const { StateDetector } = require(process.env.HOME + '/.claude/rrr/scripts/rrr-memory/state-detector');
+const detector = new StateDetector();
+const state = detector.detectPhaseState('.planning');
+const milestone = detector.detectMilestoneState('.planning');
+
+if (milestone === 'NO_MILESTONE' && state !== 'NO_PHASES') {
+  console.log('HAS_ORPHAN_PHASES=true');
+  console.log('RUN: /rrr:new-milestone or /rrr:migrate-phases');
+}
+" 2>/dev/null
+```
+
+If `HAS_ORPHAN_PHASES=true` is output, show guidance and exit (unless --force).
+
+**If orphan phases detected:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠ ORPHAN PHASES DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Found phases not assigned to any milestone.
+New phases cannot be created until orphans are assigned.
+
+To migrate orphan phases:
+1. /rrr:new-milestone - Create milestone for orphan phases
+2. /rrr:migrate-phases - Assign phases to milestone
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Exit command.
+
+**If no orphans or --force:** Continue to validate_milestone_first step.
+</step>
+
 <step name="validate_milestone_first">
 **MILESTONE-FIRST ENFORCEMENT (v1.11 breaking change)**
 

package/commands/rrr/execute-plan.md

@@ -36,6 +36,7 @@ Plan path: $ARGUMENTS
 
 @.planning/STATE.md
 @.planning/config.json (if exists)
+@rrr/lib/memory-store.js
 </context>
 
 <process>
@@ -46,6 +47,42 @@ Plan path: $ARGUMENTS
    ```
    Cross-platform: works in PowerShell on Windows. Path resolved to installed location.
 
+0. **Track command in memory (before execution)**
+   Parse the plan to extract intent from frontmatter and context, then track this execution:
+
+   ```bash
+   # Extract plan ID and objective for intent tracking
+   PLAN_ID=$(basename "$ARGUMENTS" | sed 's/-PLAN\.md$//')
+   PLAN_DIR=$(dirname "$ARGUMENTS")
+   PHASE_DIR=$(basename "$PLAN_DIR")
+
+   # Get intent from plan frontmatter (try files_modified, then title)
+   INTENT=""
+   if [ -f "$ARGUMENTS" ]; then
+     INTENT=$(grep -E "^files_modified:" "$ARGUMENTS" 2>/dev/null | head -1 | sed 's/files_modified: *\[*\]*/Intent from plan/' || \
+              grep -E "^title:" "$ARGUMENTS" 2>/dev/null | head -1 | sed 's/title: *//' || \
+              echo "Executing plan $PLAN_ID")
+   fi
+
+   # Track in memory (if memory-store.js is available)
+   node -e "
+   const { initMemory, trackCommand } = require(process.env.HOME + '/.claude/rrr/lib/memory-store');
+   (async () => {
+     try {
+       const memory = await initMemory();
+       await trackCommand(memory, {
+         command: '/rrr:execute-plan',
+         target: '$PLAN_ID',
+         intent: '$INTENT',
+         files: []
+       });
+     } catch (e) {
+       // Memory tracking is optional
+     }
+   })();
+   " 2>/dev/null || echo "[MEMORY] Tracking skipped"
+   ```
+
 0.5. **Scope Check (validate plan is in scope)**
 
    Before executing, validate the plan's files against current scope:

package/commands/rrr/insert-phase.md

@@ -23,6 +23,7 @@ Purpose: Handle urgent work discovered during execution without renumbering enti
 @.planning/STATE.md
 @rrr/lib/phase-paths.md
 @rrr/lib/milestone-utils.md
+@rrr/lib/memory-store.js
 </execution_context>
 
 <process>
@@ -74,6 +75,50 @@ fi
 
 </step>
 
+<step name="check_orphan_phases_memory">
+**Check for orphan phases using state-detector (PATCH-01 enhancement)**
+
+Same validation as add-phase - check for orphan phases before allowing new insert:
+
+```bash
+# Check for orphan phases
+node -e "
+const { StateDetector } = require(process.env.HOME + '/.claude/rrr/scripts/rrr-memory/state-detector');
+const detector = new StateDetector();
+const state = detector.detectPhaseState('.planning');
+const milestone = detector.detectMilestoneState('.planning');
+
+if (milestone === 'NO_MILESTONE' && state !== 'NO_PHASES') {
+  console.log('HAS_ORPHAN_PHASES=true');
+  console.log('RUN: /rrr:new-milestone or /rrr:migrate-phases');
+}
+" 2>/dev/null
+```
+
+If `HAS_ORPHAN_PHASES=true`, show guidance and exit (unless --force).
+
+**If orphan phases detected:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠ ORPHAN PHASES DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Found phases not assigned to any milestone.
+Inserting new phase not allowed until orphans are assigned.
+
+To migrate orphan phases:
+1. /rrr:new-milestone - Create milestone for orphan phases
+2. /rrr:migrate-phases - Assign phases to milestone
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Exit command.
+
+**If no orphans or --force:** Continue to validate_milestone_first step.
+</step>
+
 <step name="validate_milestone_first">
 **MILESTONE-FIRST ENFORCEMENT (v1.11 breaking change)**
 

package/commands/rrr/verify-work.md

@@ -71,6 +71,7 @@ Validate built features through **audit mode by default**, or interactive UAT wi
 
 <execution_context>
 @rrr/lib/phase-paths.md
+@rrr/lib/memory-store.js
 </execution_context>
 
 <!-- ═══════════════════════════════════════════════════════════════════════════
@@ -140,6 +141,41 @@ For manual testing, use: /rrr:verify-work --uat [phase]
 
 ---
 
+### Step 0.5: Show Memory Context (PATCH-01 enhancement)
+
+Display current intent and recent commands to provide context during verification:
+
+```bash
+# Show memory context if available
+node -e "
+const { initMemory, getSummary } = require(process.env.HOME + '/.claude/rrr/lib/memory-store');
+(async () => {
+  try {
+    const memory = await initMemory();
+    const summary = await getSummary(memory);
+    console.log('');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log(' RRR ► MEMORY CONTEXT');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('Intent:', summary.currentIntent || '(no intent tracked)');
+    console.log('Recent:', summary.recentCommands.slice(0, 2).map(c =>
+      c.cmd + (c.target ? '(' + c.target + ')' : '')
+    ).join(' → ') || 'none');
+    if (summary.drift && summary.drift.drifting) {
+      console.log('Drift:', summary.drift.message);
+    }
+    console.log('───────────────────────────────────────────────────────');
+  } catch (e) {
+    // Memory not available, skip silently
+  }
+})();
+" 2>/dev/null || true
+```
+
+This helps verify-work understand what the user was working on.
+
+---
+
 ### Step 1: Determine Scope
 
 **Parse target from arguments (with flags removed):**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.16.6",
+  "version": "1.16.7",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by Projecta.ai",
   "bin": {
     "projecta-rrr": "bin/install.js"
@@ -22,7 +22,10 @@
     "sessions:index": "bash scripts/index-sessions.sh",
     "sessions:status": "bash scripts/index-sessions.sh --status",
     "semantic:verify": "bash scripts/verify-semantic-search.sh",
-    "prepublish:check": "node scripts/prepublish-check.js"
+    "prepublish:check": "node scripts/prepublish-check.js",
+    "browser:uat": "bash scripts/browser-uat.sh",
+    "scaffold:e2e": "bash scripts/scaffold-e2e.sh",
+    "chrome:visual": "bash scripts/chrome-visual-check.sh"
   },
   "files": [
     "bin",

package/rrr/lib/install-roots.js

@@ -535,6 +535,58 @@ if (require.main === module) {
   process.exit(summary.verification.valid ? 0 : 1);
 }
 
+/**
+ * Clean up old quarantine directories
+ * Removes quarantine folders older than maxAgeMs to prevent duplicates from being scanned
+ * @param {object} options
+ * @param {string} [options.configDir] - Explicit config directory
+ * @param {number} [options.maxAgeMs=7*24*60*60*1000] - Max age in ms (default 7 days)
+ * @returns {{cleaned: number, errors: string[]}}
+ */
+function cleanOldQuarantines(options = {}, maxAgeMs = 7 * 24 * 60 * 60 * 1000) {
+  const roots = getCanonicalRoots(options);
+  const quarantineRoot = roots.quarantineRoot;
+  const cleaned = [];
+  const errors = [];
+
+  if (!fs.existsSync(quarantineRoot)) {
+    return { cleaned: 0, errors: [] };
+  }
+
+  const now = Date.now();
+  const entries = fs.readdirSync(quarantineRoot, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === 'QUARANTINE_LOG.json') continue;
+
+    const dirPath = path.join(quarantineRoot, entry.name);
+    const stats = fs.statSync(dirPath);
+    const age = now - stats.mtimeMs;
+
+    if (age > maxAgeMs) {
+      try {
+        // Delete directory contents and directory itself
+        const files = fs.readdirSync(dirPath);
+        for (const file of files) {
+          const filePath = path.join(dirPath, file);
+          if (fs.statSync(filePath).isDirectory()) {
+            fs.rmSync(filePath, { recursive: true });
+          } else {
+            fs.unlinkSync(filePath);
+          }
+        }
+        fs.rmdirSync(dirPath);
+        cleaned.push(entry.name);
+      } catch (e) {
+        errors.push(`Failed to clean ${entry.name}: ${e.message}`);
+      }
+    }
+  }
+
+  return { cleaned, errors };
+}
+
 module.exports = {
   getCanonicalRoots,
   detectAllCandidateRoots,
@@ -545,5 +597,6 @@ module.exports = {
   getInstallInfo,
   detectAndQuarantineDuplicates,
   verifyInstallation,
-  getInstallationSummary
+  getInstallationSummary,
+  cleanOldQuarantines
 };