projecta-rrr 1.16.7 → 1.16.8

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.8] - 2026-01-28
+
+### Added
+
+- **Install-Time Project Context** (`scripts/build-project-context.js`) - Builds comprehensive project memory at install/upgrade:
+  - Enumerates all milestones and phases with status
+  - Analyzes git history for project evolution narrative
+  - Stores context in `.planning/rrr-project-context.json`
+  - Auto-rebuilds on RRR upgrade
+
+- **Enhanced HUD with Drift Detection** (`scripts/rrr-hud.js`) - Bulletproof drift detection:
+  - Prominent red "DRIFT DETECTED" warning with stale plan counts
+  - Context signals (files changed without active plan)
+  - Changed file tracking with code file detection
+  - Actionable numbered guidance: verify-work, complete plans, or pause-work
+  - Robust error handling for all git/file operations
+
+- **HUD Integration** - Added visual HUD display to 9 commands:
+  - Tier 1: progress, execute-plan, verify-work, execute-phase, plan-phase
+  - Tier 2: complete-milestone, resume-work, check-todos
+  - Tier 3: debug, new-milestone, pause-work
+
+### Changed
+
+- **bin/install.js** - Runs context builder after install for any project with `.planning/`
+
+- **hooks/rrr-check-update.sh** - Rebuilds project context when RRR upgrade detected
+
 ## [1.16.7] - 2026-01-28
 
 ### Added

package/bin/install.js

@@ -942,6 +942,17 @@ function install(isGlobal) {
     console.log(`  ${green}✓${reset} Installed rrr/scripts/rrr-memory/`);
   }
 
+  // PATCH-01: Copy build-project-context.js to ~/.claude/rrr/scripts/
+  // Builds project memory (milestones, phases, git history) at install/upgrade
+  const projectContextSrc = path.join(src, 'scripts', 'build-project-context.js');
+  if (fs.existsSync(projectContextSrc)) {
+    const scriptsDestDir = path.join(claudeDir, 'rrr', 'scripts');
+    fs.mkdirSync(scriptsDestDir, { recursive: true });
+    const projectContextDest = path.join(scriptsDestDir, 'build-project-context.js');
+    fs.copyFileSync(projectContextSrc, projectContextDest);
+    console.log(`  ${green}✓${reset} Installed rrr/scripts/build-project-context.js`);
+  }
+
   // Copy skills to ~/.claude/skills (skills system)
   const skillsSrc = path.join(src, 'rrr', 'skills');
   if (fs.existsSync(skillsSrc)) {
@@ -1247,6 +1258,27 @@ function install(isGlobal) {
         // Silent fail - cleanup is optional, don't block install
       }
     }
+
+    // PATCH-01: Build project context (milestones, phases, git history)
+    // This creates a persistent memory of project structure for HUD and decisions
+    // Runs once, AFTER all project-specific setup, for any project with .planning
+    const projectContextScript = path.join(src, 'scripts', 'build-project-context.js');
+    if (fs.existsSync(projectContextScript)) {
+      try {
+        const { buildProjectContext } = require(projectContextScript);
+        const planningDir = path.join(projectDir, '.planning');
+        if (fs.existsSync(planningDir)) {
+          const context = buildProjectContext();
+          if (context) {
+            console.log(`  ${green}✓${reset} Built project context (${context.stats.totalMilestones} milestones, ${context.stats.totalPlans} plans)`);
+          } else {
+            console.log(`  ${green}✓${reset} Project context up to date`);
+          }
+        }
+      } catch (e) {
+        // Silent fail - context building is optional
+      }
+    }
   }
 
   return { settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, localDirName, isGlobal, bashAvailable: bashStatus.available };

package/commands/rrr/check-todos.md

@@ -23,6 +23,11 @@ Enables reviewing captured ideas and deciding what to work on next.
 
 <process>
 
+**Show HUD (first)**
+```bash
+node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
+```
+
 <step name="check_exist">
 ```bash
 TODO_COUNT=$(ls .planning/todos/pending/*.md 2>/dev/null | wc -l | tr -d ' ')

package/commands/rrr/complete-milestone.md

@@ -37,6 +37,11 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 
 <process>
 
+**Show HUD (first)**
+```bash
+node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
+```
+
 **Follow complete-milestone.md workflow:**
 
 0. **Check for audit:**

package/commands/rrr/debug.md

@@ -28,6 +28,11 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
 
 <process>
 
+**Show HUD (first)**
+```bash
+node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
+```
+
 ## 1. Check Active Sessions
 
 If active sessions exist AND no $ARGUMENTS:

package/commands/rrr/execute-phase.md

@@ -38,11 +38,12 @@ Phase: $ARGUMENTS
 
 <process>
 
-0. **Refresh Scope Cache (first)**
+0. **Show HUD and refresh cache (first)**
    ```bash
+   node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
    node ~/.claude/rrr/scripts/refresh-scope-cache.js 2>/dev/null || echo "Cache refresh skipped"
    ```
-   Cross-platform: works in PowerShell on Windows. Path resolved to installed location.
+   Cross-platform: works in PowerShell on Windows. Shows visual project state before execution.
 
 1. **Validate phase exists**
    - Use `find_phase_dir()` from phase-paths library to locate phase directory:

package/commands/rrr/execute-plan.md

@@ -41,11 +41,13 @@ Plan path: $ARGUMENTS
 
 <process>
 
-0. **Refresh Scope Cache (first)**
+0. **Refresh Scope Cache and HUD (first)**
    ```bash
    node ~/.claude/rrr/scripts/refresh-scope-cache.js 2>/dev/null || echo "Cache refresh skipped"
+   node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
    ```
    Cross-platform: works in PowerShell on Windows. Path resolved to installed location.
+   Shows visual project state before execution.
 
 0. **Track command in memory (before execution)**
    Parse the plan to extract intent from frontmatter and context, then track this execution:

package/commands/rrr/new-milestone.md

@@ -37,6 +37,11 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
 <process>
 
+**Show HUD (first)**
+```bash
+node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
+```
+
 1. **Load context:**
    - Read PROJECT.md (existing project, Validated requirements, decisions)
    - Read MILESTONES.md (what shipped previously)

package/commands/rrr/pause-work.md

@@ -19,6 +19,11 @@ Enables seamless resumption in fresh session with full context restoration.
 
 <process>
 
+**Show HUD (first)**
+```bash
+node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
+```
+
 <step name="detect">
 Find current phase directory from most recently modified files.
 </step>

package/commands/rrr/plan-phase.md

@@ -71,6 +71,13 @@ Use Glob tool with both structures:
 
 <process>
 
+0. **Show HUD and refresh cache (first)**
+   ```bash
+   node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
+   node ~/.claude/rrr/scripts/refresh-scope-cache.js 2>/dev/null || echo "Cache refresh skipped"
+   ```
+   Cross-platform: works in PowerShell on Windows. Shows visual context before planning.
+
 ## 1. Validate Environment (Cross-Platform)
 
 **Step 1: Check .planning/ exists via STATE.md**

package/commands/rrr/progress.md

@@ -24,19 +24,20 @@ Provides situational awareness before continuing work.
 <process>
 
 <step name="refresh_cache">
-**Refresh Scope Cache (first, before any reads):**
+**Refresh Scope Cache and HUD (first, before any reads):**
 
 **On macOS/Linux:**
 ```bash
 node ~/.claude/rrr/scripts/refresh-scope-cache.js 2>/dev/null || echo "Cache refresh skipped"
+node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
 ```
 
 **On Windows (Platform: win32):**
-Same command works in PowerShell. If Node unavailable, skip silently.
+Same commands work in PowerShell. If Node unavailable, skip silently.
 
-**Note:** Path is resolved to installed location (e.g., `$HOME/.claude/` or `./.claude/`).
+**Note:** Paths resolve to installed location (e.g., `$HOME/.claude/` or `./.claude/`).
 
-This ensures SCOPE_CACHE.md is current before displaying status.
+This ensures SCOPE_CACHE.md is current and shows visual HUD before displaying status.
 </step>
 
 <step name="verify">

package/commands/rrr/resume-work.md

@@ -27,13 +27,14 @@ Routes to the resume-project workflow which handles:
 
 <process>
 
-**0. Refresh Scope Cache (first)**
+**0. Show HUD and refresh cache (first)**
 
 ```bash
+node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
 node ~/.claude/rrr/scripts/refresh-scope-cache.js 2>/dev/null || echo "Cache refresh skipped"
 ```
 
-Cross-platform: works in PowerShell on Windows. Path resolved to installed location.
+Cross-platform: works in PowerShell on Windows. Shows visual project state on resume.
 
 **Follow the resume-project workflow** from `@~/.claude/rrr/workflows/resume-project.md`.
 

package/commands/rrr/verify-work.md

@@ -74,6 +74,17 @@ Validate built features through **audit mode by default**, or interactive UAT wi
 @rrr/lib/memory-store.js
 </execution_context>
 
+<process>
+
+0. **Show HUD and refresh cache (first)**
+   ```bash
+   node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
+   node ~/.claude/rrr/scripts/refresh-scope-cache.js 2>/dev/null || echo "Cache refresh skipped"
+   ```
+   Cross-platform: works in PowerShell on Windows. Shows visual project state and drift before verification.
+
+</process>
+
 <!-- ═══════════════════════════════════════════════════════════════════════════
      MODE SELECTION - MUST EXECUTE FIRST BEFORE ANY OTHER SECTION
      ═══════════════════════════════════════════════════════════════════════════ -->

package/hooks/rrr-check-update.sh

@@ -7,10 +7,14 @@
 # Graceful degradation: if npm is not available, exit silently
 command -v npm >/dev/null 2>&1 || exit 0
 
+# Graceful degradation: if jq is not available, exit silently
+command -v jq >/dev/null 2>&1 || exit 0
+
 # Catch any errors and exit gracefully (non-blocking hook)
 set +e
 
 CACHE_FILE="$HOME/.claude/cache/rrr-update-check.json"
+CONTEXT_FILE=".planning/rrr-project-context.json"
 mkdir -p "$HOME/.claude/cache"
 
 # Run check in background (non-blocking)
@@ -18,11 +22,22 @@ mkdir -p "$HOME/.claude/cache"
   installed=$(cat "$HOME/.claude/rrr/VERSION" 2>/dev/null || echo "0.0.0")
   latest=$(npm view projecta-rrr version 2>/dev/null)
 
+  update_available=false
   if [[ -n "$latest" && "$installed" != "$latest" ]]; then
+    update_available=true
+  fi
+
+  if [[ "$update_available" == "true" ]]; then
     echo "{\"update_available\":true,\"installed\":\"$installed\",\"latest\":\"$latest\",\"checked\":$(date +%s)}" > "$CACHE_FILE"
   else
     echo "{\"update_available\":false,\"installed\":\"$installed\",\"latest\":\"${latest:-unknown}\",\"checked\":$(date +%s)}" > "$CACHE_FILE"
   fi
+
+  # If upgrade available, rebuild project context in background
+  # This ensures new RRR capabilities get fresh context data
+  if [[ "$update_available" == "true" ]] && [[ -f "scripts/build-project-context.js" ]]; then
+    node scripts/build-project-context.js 2>/dev/null &
+  fi
 ) &
 
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.16.7",
+  "version": "1.16.8",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by Projecta.ai",
   "bin": {
     "projecta-rrr": "bin/install.js"

package/scripts/build-project-context.js

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+
+/**
+ * RRR Project Context Builder
+ *
+ * Builds comprehensive project context at install/upgrade time:
+ * - Enumerates all milestones and their phases
+ * - Analyzes git history for project evolution narrative
+ * - Stores context for HUD, decisions, and drift detection
+ *
+ * This creates a "memory" of the project structure that persists
+ * across sessions, avoiding repeated disk scanning.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Paths
+const PLANNING_DIR = '.planning';
+const MILESTONES_DIR = path.join(PLANNING_DIR, 'milestones');
+const CONTEXT_FILE = path.join(PLANNING_DIR, 'rrr-project-context.json');
+
+/**
+ * Safely read file content
+ */
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Parse milestone version from directory name (e.g., v1.16 -> 1.16)
+ */
+function parseMilestoneVersion(dirName) {
+  const match = dirName.match(/^v(\d+)\.(\d+)$/);
+  if (match) {
+    return { major: parseInt(match[1]), minor: parseInt(match[2]), full: match[0] };
+  }
+  return null;
+}
+
+/**
+ * Parse frontmatter from markdown
+ */
+function parseFrontmatter(content) {
+  if (!content) return {};
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const yaml = match[1];
+  const result = {};
+
+  for (const line of yaml.split('\n')) {
+    const kvMatch = line.match(/^(\w+):\s*(.*)/);
+    if (kvMatch) {
+      const [, key, value] = kvMatch;
+      result[key] = value.trim().replace(/^["']|["']$/g, '');
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extract objective from PLAN.md
+ */
+function extractObjective(content) {
+  if (!content) return null;
+  const match = content.match(/<objective>([\s\S]*?)<\/objective>/);
+  if (!match) return null;
+  return match[1].trim().split('\n')[0];
+}
+
+/**
+ * Parse ROADMAP.md to get phase list and status
+ */
+function parseMilestoneRoadmap(content) {
+  if (!content) return { phases: [], completedMilestones: [] };
+
+  const result = {
+    phases: [],
+    completedMilestones: [],
+    status: 'active'
+  };
+
+  // Extract phases
+  const phaseMatches = content.matchAll(/###?\s*Phase\s+(\d+)(?:\.\d+)?:?\s*(.+)/gi);
+  for (const match of phaseMatches) {
+    result.phases.push({
+      number: match[1],
+      name: match[2].trim()
+    });
+  }
+
+  // Extract completed milestones
+  const completedMatch = content.match(/## Completed Milestones([\s\S]*)/i);
+  if (completedMatch) {
+    const milestoneMatches = completedMatch[1].matchAll(/\*\*v([0-9]+\.[0-9]+)\*\*.*?Phases\s*(\d+)[-–](\d+)/g);
+    for (const m of milestoneMatches) {
+      result.completedMilestones.push({
+        version: m[1],
+        phasesRange: `${m[2]}-${m[3]}`
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get git commit history with filtering
+ */
+function getGitHistory(options = {}) {
+  const {
+    maxCommits = 100,
+    since = null,
+    includeMessages = true,
+    includeFiles = false
+  } = options;
+
+  try {
+    let cmd = `git log --oneline -n ${maxCommits}`;
+    if (since) {
+      cmd += ` --since="${since}"`;
+    }
+
+    const output = execSync(cmd, { encoding: 'utf8', cwd: process.cwd() });
+    const lines = output.trim().split('\n').filter(Boolean);
+
+    return lines.map(line => {
+      const match = line.match(/^([a-f0-9]+)\s+(.*)$/);
+      if (!match) return { hash: line.slice(0, 7), message: line };
+
+      const hash = match[1];
+      const message = match[2];
+
+      // Extract plan ID from commit message if present
+      const planMatch = message.match(/(\d+-\d+)/);
+      const planId = planMatch ? planMatch[0] : null;
+
+      // Try to categorize the commit type
+      let type = 'other';
+      if (message.includes('feat:')) type = 'feature';
+      else if (message.includes('fix:')) type = 'fix';
+      else if (message.includes('chore:')) type = 'chore';
+      else if (message.includes('docs:')) type = 'docs';
+      else if (message.includes('refactor:')) type = 'refactor';
+      else if (planId) {
+        // Check if it's a planning commit
+        if (message.includes('PLAN') || message.includes('plan')) type = 'planning';
+        else if (message.includes('SUMMARY') || message.includes('summary')) type = 'summary';
+        else if (message.includes('VERIFICATION') || message.includes('verification')) type = 'verification';
+      }
+
+      return {
+        hash: hash.slice(0, 7),
+        fullHash: hash,
+        message,
+        planId,
+        type,
+        timestamp: null // Would need additional git command to get timestamp
+      };
+    });
+  } catch (e) {
+    return [];
+  }
+}
+
+/**
+ * Analyze git history to build project evolution narrative
+ */
+function analyzeGitHistory(commits) {
+  const narrative = {
+    totalCommits: commits.length,
+    byType: {},
+    planActivity: [],
+    recentMilestones: []
+  };
+
+  // Count by type
+  for (const commit of commits) {
+    narrative.byType[commit.type] = (narrative.byType[commit.type] || 0) + 1;
+  }
+
+  // Extract plan-related activity
+  for (const commit of commits) {
+    if (commit.planId) {
+      narrative.planActivity.push({
+        planId: commit.planId,
+        message: commit.message.slice(0, 80),
+        type: commit.type,
+        hash: commit.hash
+      });
+    }
+  }
+
+  return narrative;
+}
+
+/**
+ * Enumerate all milestones in .planning/milestones/
+ */
+function enumerateMilestones() {
+  if (!fs.existsSync(MILESTONES_DIR)) {
+    return { milestones: [], activeMilestone: null };
+  }
+
+  const dirs = fs.readdirSync(MILESTONES_DIR, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .filter(name => name.startsWith('v'))
+    .sort((a, b) => {
+      const va = parseMilestoneVersion(a);
+      const vb = parseMilestoneVersion(b);
+      if (!va || !vb) return 0;
+      return va.major - vb.major || va.minor - vb.minor;
+    });
+
+  // Determine active milestone from root ROADMAP.md
+  const rootRoadmap = safeReadFile(path.join(PLANNING_DIR, 'ROADMAP.md'));
+  let activeMilestone = null;
+  if (rootRoadmap) {
+    const match = rootRoadmap.match(/^## Current Milestone:\s*(v[0-9]+\.[0-9]+)/m);
+    if (match) activeMilestone = match[1];
+  }
+
+  const milestones = [];
+
+  for (const dir of dirs) {
+    const version = parseMilestoneVersion(dir);
+    if (!version) continue;
+
+    const milestonePath = path.join(MILESTONES_DIR, dir);
+    const roadmapPath = path.join(milestonePath, 'ROADMAP.md');
+    const requirementsPath = path.join(milestonePath, 'REQUIREMENTS.md');
+    const phasesDir = path.join(milestonePath, 'phases');
+
+    const roadmapContent = safeReadFile(roadmapPath);
+    const requirementsContent = safeReadFile(requirementsPath);
+
+    const roadmapInfo = parseMilestoneRoadmap(roadmapContent);
+
+    // Count phases
+    let phaseCount = 0;
+    let planCount = 0;
+    let completedPlans = 0;
+
+    if (fs.existsSync(phasesDir)) {
+      const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name);
+
+      phaseCount = phaseDirs.length;
+
+      for (const phaseDir of phaseDirs) {
+        const phasePath = path.join(phasesDir, phaseDir);
+        const planFiles = fs.readdirSync(phasePath).filter(f => f.endsWith('-PLAN.md'));
+        planCount += planFiles.length;
+
+        for (const planFile of planFiles) {
+          const summaryFile = planFile.replace('-PLAN.md', '-SUMMARY.md');
+          const summaryPath = path.join(phasePath, summaryFile);
+          if (fs.existsSync(summaryPath)) {
+            completedPlans++;
+          }
+        }
+      }
+    }
+
+    milestones.push({
+      version: version.full,
+      major: version.major,
+      minor: version.minor,
+      isActive: dir === activeMilestone,
+      phases: roadmapInfo.phases,
+      phaseCount,
+      planCount,
+      completedPlans,
+      progress: planCount > 0 ? Math.round((completedPlans / planCount) * 100) : 0,
+      requirements: parseFrontmatter(requirementsContent),
+      completedMilestonesInHistory: roadmapInfo.completedMilestones
+    });
+  }
+
+  return { milestones, activeMilestone };
+}
+
+/**
+ * Build comprehensive project context
+ */
+function buildProjectContext() {
+  console.log('Building project context...\n');
+
+  const startTime = Date.now();
+
+  // Enumerate milestones
+  const { milestones, activeMilestone } = enumerateMilestones();
+  console.log(`  Found ${milestones.length} milestone(s)`);
+  if (activeMilestone) {
+    console.log(`  Active milestone: ${activeMilestone}`);
+  }
+
+  // Get git history
+  const commits = getGitHistory({ maxCommits: 200 });
+  console.log(`  Analyzed ${commits.length} recent commits`);
+
+  // Analyze git history
+  const historyAnalysis = analyzeGitHistory(commits);
+
+  // Build project evolution narrative
+  const narrative = [];
+  let currentPhase = null;
+  let lastDate = null;
+
+  for (const commit of commits.slice(0, 50)) {
+    const dateMatch = execSync(`git log -1 --format=%ci ${commit.fullHash}`, { encoding: 'utf8' }).trim();
+    const date = dateMatch ? dateMatch.split('T')[0] : null;
+
+    if (commit.planId && commit.planId !== currentPhase) {
+      if (currentPhase && narrative.length > 0) {
+        // Close previous phase
+        const last = narrative[narrative.length - 1];
+        if (last.endDate && date) {
+          last.duration = Math.ceil((new Date(last.endDate) - new Date(last.startDate)) / (1000 * 60 * 60 * 24));
+        }
+      }
+      currentPhase = commit.planId;
+      narrative.push({
+        planId: commit.planId,
+        startDate: date,
+        endDate: null,
+        type: commit.type,
+        commits: 1,
+        keyChange: commit.message.slice(0, 60)
+      });
+    } else if (commit.planId) {
+      const existing = narrative.find(n => n.planId === commit.planId);
+      if (existing) {
+        existing.commits++;
+        existing.endDate = date;
+      }
+    }
+  }
+
+  // Compute project statistics
+  const stats = {
+    totalMilestones: milestones.length,
+    activeMilestone,
+    totalPhases: milestones.reduce((sum, m) => sum + m.phaseCount, 0),
+    totalPlans: milestones.reduce((sum, m) => sum + m.planCount, 0),
+    completedPlans: milestones.reduce((sum, m) => sum + m.completedPlans, 0),
+    overallProgress: 0
+  };
+
+  if (stats.totalPlans > 0) {
+    stats.overallProgress = Math.round((stats.completedPlans / stats.totalPlans) * 100);
+  }
+
+  // Build the context object
+  const context = {
+    version: 1,
+    builtAt: new Date().toISOString(),
+    rrrVersion: safeReadFile(path.join(__dirname, '..', 'VERSION'))?.trim() || null,
+
+    milestones,
+    activeMilestone,
+
+    // Git-derived context
+    gitHistory: {
+      recentCommits: commits.slice(0, 50),
+      analysis: historyAnalysis,
+      projectNarrative: narrative
+    },
+
+    // Project statistics
+    stats,
+
+    // For caching purposes
+    cacheMetadata: {
+      file: CONTEXT_FILE,
+      validUntil: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // 24 hours
+      rebuildTriggers: [
+        'milestone added',
+        'phase added',
+        'plan created',
+        'summary completed'
+      ]
+    }
+  };
+
+  // Write context file
+  fs.writeFileSync(CONTEXT_FILE, JSON.stringify(context, null, 2));
+  console.log(`\n  Wrote ${CONTEXT_FILE}`);
+
+  const elapsed = Date.now() - startTime;
+  console.log(`  Built in ${elapsed}ms\n`);
+
+  // Print summary
+  console.log('Project Context Summary:');
+  console.log(`  Milestones: ${stats.totalMilestones}`);
+  console.log(`  Phases: ${stats.totalPhases}`);
+  console.log(`  Plans: ${stats.completedPlans}/${stats.totalPlans} (${stats.overallProgress}%)`);
+  if (activeMilestone) {
+    console.log(`  Active: ${activeMilestone}`);
+  }
+
+  return context;
+}
+
+/**
+ * Check if context needs rebuilding
+ */
+function needsRebuild() {
+  if (!fs.existsSync(CONTEXT_FILE)) return true;
+
+  try {
+    const existing = JSON.parse(fs.readFileSync(CONTEXT_FILE, 'utf8'));
+
+    // Check if cache is expired
+    if (existing.cacheMetadata?.validUntil) {
+      const validUntil = new Date(existing.cacheMetadata.validUntil);
+      if (new Date() > validUntil) return true;
+    }
+
+    // Check if RRR version changed
+    const currentVersion = safeReadFile(path.join(__dirname, '..', 'VERSION'))?.trim();
+    if (existing.rrrVersion !== currentVersion) {
+      console.log(`  Version change detected: ${existing.rrrVersion} -> ${currentVersion}`);
+      return true;
+    }
+
+    return false;
+  } catch (e) {
+    return true;
+  }
+}
+
+/**
+ * Main entry point
+ */
+function main() {
+  const projectDir = process.cwd();
+  const planningDir = path.join(projectDir, PLANNING_DIR);
+
+  // Check if .planning exists
+  if (!fs.existsSync(planningDir)) {
+    console.log('No .planning directory found - skipping context build');
+    console.log('  Run /rrr:new-project or /rrr:new-milestone to initialize\n');
+    return null;
+  }
+
+  // Check if rebuild is needed
+  if (!needsRebuild()) {
+    console.log('Project context up to date - skipping rebuild\n');
+    return null;
+  }
+
+  return buildProjectContext();
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+// Export for use as module
+module.exports = {
+  buildProjectContext,
+  needsRebuild,
+  enumerateMilestones,
+  getGitHistory,
+  analyzeGitHistory
+};

package/scripts/rrr-hud.js

@@ -3,16 +3,22 @@
  *
  * Run via: node scripts/rrr-hud.js
  * Or integrate into existing commands for auto-show
+ *
+ * Enhanced with prominent drift detection and actionable guidance.
  */
 
 const fs = require('fs');
 const path = require('path');
-const { initMemory, getSummary, detectDrift, getProjectState } = require('../lib/memory-store');
+const { execSync } = require('child_process');
+
+// Resolve memory-store from rrr/lib/ regardless of cwd
+const memoryStorePath = path.join(__dirname, '..', 'rrr', 'lib', 'memory-store');
+const { initMemory, getSummary, detectDrift, getProjectState } = require(memoryStorePath);
 
 const COLORS = {
   reset: '\x1b[0m', bright: '\x1b[1m', dim: '\x1b[2m',
   green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m',
-  cyan: '\x1b[36m', magenta: '\x1b[35m'
+  cyan: '\x1b[36m', magenta: '\x1b[35m', orange: '\x1b[91m'
 };
 
 function progressBar(current, total, width = 20) {
@@ -47,33 +53,115 @@ function getPhaseStatus(milestone) {
 
 function getDriftStatus() {
   let drifting = 0, pending = 0;
+  const stalePlans = [];
   const phasesDir = path.join(process.cwd(), '.planning', 'milestones');
-  if (!fs.existsSync(phasesDir)) return { drifting: 0, pending: 0 };
+  if (!fs.existsSync(phasesDir)) return { drifting: 0, pending: 0, stalePlans: [] };
 
   for (const milestone of fs.readdirSync(phasesDir)) {
     const msPhases = path.join(phasesDir, milestone, 'phases');
     if (!fs.existsSync(msPhases)) continue;
     for (const phase of fs.readdirSync(msPhases)) {
       const phaseDir = path.join(msPhases, phase);
-      const plans = fs.readdirSync(phaseDir).filter(f => f.endsWith('-PLAN.md'));
-      const summaries = fs.readdirSync(phaseDir).filter(f => f.endsWith('-SUMMARY.md'));
-      for (const plan of plans) {
-        if (!summaries.some(s => s.replace('SUMMARY', 'PLAN') === plan)) {
-          const planPath = path.join(phaseDir, plan);
-          const age = (Date.now() - fs.statSync(planPath).mtimeMs) / (1000 * 60 * 60);
-          if (age > 48) drifting++; else pending++;
+      if (!fs.existsSync(phaseDir)) continue;
+      try {
+        const plans = fs.readdirSync(phaseDir).filter(f => f.endsWith('-PLAN.md'));
+        const summaries = fs.readdirSync(phaseDir).filter(f => f.endsWith('-SUMMARY.md'));
+        for (const plan of plans) {
+          if (!summaries.some(s => s.replace('SUMMARY', 'PLAN') === plan)) {
+            const planPath = path.join(phaseDir, plan);
+            try {
+              const stats = fs.statSync(planPath);
+              const age = (Date.now() - stats.mtimeMs) / (1000 * 60 * 60);
+              const planId = plan.replace('-PLAN.md', '');
+              if (age > 48) {
+                drifting++;
+                stalePlans.push({ planId, age: Math.round(age), phase });
+              } else {
+                pending++;
+              }
+            } catch (e) {
+              // Skip plans we can't stat
+            }
+          }
         }
+      } catch (e) {
+        // Skip phases we can't read
       }
     }
   }
-  return { drifting, pending };
+  return { drifting, pending, stalePlans };
+}
+
+function getChangedFiles() {
+  try {
+    const unstaged = execSync('git diff --name-only 2>/dev/null', { encoding: 'utf8', timeout: 5000 }).trim().split('\n').filter(Boolean);
+    const staged = execSync('git diff --cached --name-only 2>/dev/null', { encoding: 'utf8', timeout: 5000 }).trim().split('\n').filter(Boolean);
+    const untracked = execSync('git ls-files --others --exclude-standard 2>/dev/null', { encoding: 'utf8', timeout: 5000 }).trim().split('\n').filter(Boolean);
+    return { unstaged, staged, untracked, total: unstaged.length + staged.length + untracked.length };
+  } catch (e) {
+    // Git not available or error - no changed files
+    return { unstaged: [], staged: [], untracked: [], total: 0 };
+  }
+}
+
+function checkContextDrift() {
+  const signals = [];
+
+  // Check 1: Are there changed files but no recent intent?
+  const changedFiles = getChangedFiles();
+  if (changedFiles.total > 0) {
+    const statePath = path.join(process.cwd(), '.planning', 'STATE.md');
+    try {
+      const state = fs.readFileSync(statePath, 'utf8');
+      const statusMatch = state.match(/Status:\s*(.+)/);
+      if (statusMatch && !statusMatch[1].includes('executing') && !statusMatch[1].includes('Planning')) {
+        signals.push({
+          type: 'context_drift',
+          severity: 'medium',
+          message: `${changedFiles.total} file(s) changed but no active plan`
+        });
+      }
+    } catch (e) {
+      // STATE.md missing
+    }
+  }
+
+  // Check 2: Are there incomplete plans in multiple phases?
+  const phasesDir = path.join(process.cwd(), '.planning', 'milestones');
+  let phasesWithIncomplete = 0;
+  try {
+    for (const ms of fs.readdirSync(phasesDir)) {
+      const msPhases = path.join(phasesDir, ms, 'phases');
+      if (!fs.existsSync(msPhases)) continue;
+      for (const phase of fs.readdirSync(msPhases)) {
+        const phaseDir = path.join(msPhases, phase);
+        const plans = fs.readdirSync(phaseDir).filter(f => f.endsWith('-PLAN.md'));
+        const summaries = fs.readdirSync(phaseDir).filter(f => f.endsWith('-SUMMARY.md'));
+        if (plans.length > summaries.length) phasesWithIncomplete++;
+      }
+    }
+  } catch (e) {
+    // Ignore
+  }
+
+  if (phasesWithIncomplete > 1) {
+    signals.push({
+      type: 'scattered_work',
+      severity: 'low',
+      message: `Work spread across ${phasesWithIncomplete} phases`
+    });
+  }
+
+  return signals;
 }
 
 async function renderHUD() {
   const planningDir = path.join(process.cwd(), '.planning');
   if (!fs.existsSync(planningDir)) {
-    console.log('No .planning directory found');
-    console.log('Run /rrr:mvp to get started');
+    console.log(`${COLORS.orange}╔════════════════════════════════════════════════════════════════════╗${COLORS.reset}`);
+    console.log(`${COLORS.orange}║${COLORS.reset} ${COLORS.red}No .planning directory found${COLORS.reset}`);
+    console.log(`${COLORS.orange}║${COLORS.reset} Run ${COLORS.cyan}/rrr:new-project${COLORS.reset} or ${COLORS.cyan}/rrr:mvp${COLORS.reset} to initialize`);
+    console.log(`${COLORS.orange}╚════════════════════════════════════════════════════════════════════╝${COLORS.reset}`);
     return;
   }
 
@@ -81,11 +169,13 @@ async function renderHUD() {
   let memory = null;
   let memorySummary = null;
   let projectState = null;
+  let memoryDrift = null;
 
   try {
     memory = await initMemory();
     memorySummary = await getSummary(memory);
     projectState = await getProjectState();
+    memoryDrift = await detectDrift(memory, []);
   } catch (e) {
     // Memory not initialized
   }
@@ -100,62 +190,112 @@ async function renderHUD() {
     const donePlans = phases.reduce((sum, p) => sum + p.completed, 0);
     const overallPct = totalPlans > 0 ? Math.round((donePlans / totalPlans) * 100) : 0;
 
-    console.log(`${COLORS.bright}║ Milestone ${milestone.version}${COLORS.reset} ${milestone.description}`);
+    console.log(`${COLORS.bright}║ ${COLORS.cyan}Milestone ${milestone.version}${COLORS.reset} ${milestone.description}`);
     console.log(`${COLORS.bright}║ ${progressBar(donePlans, totalPlans, 60)} ${overallPct}%${COLORS.reset}`);
 
     for (const phase of phases) {
       const icon = phase.completed === phase.plans ? '✓' : phase.completed > 0 ? '◐' : '○';
-      console.log(`${COLORS.bright}║   ${icon} ${phase.name}${COLORS.reset} ${progressBar(phase.completed, phase.plans, 30)} ${phase.completed}/${phase.plans} plans`);
+      const color = phase.completed === phase.plans ? COLORS.green : phase.completed > 0 ? COLORS.yellow : COLORS.dim;
+      console.log(`${COLORS.bright}║   ${icon} ${phase.name}${COLORS.reset} ${progressBar(phase.completed, phase.plans, 30)} ${phase.completed}/${phase.plans}`);
     }
   } else {
-    console.log(`${COLORS.bright}║ 📋 Between Milestones${COLORS.reset}`);
+    console.log(`${COLORS.bright}║ ${COLORS.cyan}📋 Between Milestones${COLORS.reset}`);
     console.log(`${COLORS.bright}║${COLORS.reset}`);
-    console.log(`${COLORS.bright}║   Run /rrr:discuss-milestone to plan next milestone${COLORS.reset}`);
+    console.log(`${COLORS.bright}║   Run ${COLORS.cyan}/rrr:discuss-milestone${COLORS.reset} to plan next milestone`);
   }
 
-  console.log(`${COLORS.bright}║${COLORS.reset}`);
-
-  // Drift status from filesystem
+  // === DRIFT SECTION - PROMINENT ===
   const driftStatus = getDriftStatus();
-  let driftIcon = '🟢', driftText = 'On track';
-  if (driftStatus.drifting > 0) {
-    driftIcon = '🔴';
-    driftText = `${driftStatus.drifting} stale (>48h)`;
-  } else if (driftStatus.pending > 0) {
-    driftIcon = '🟡';
-    driftText = `${driftStatus.pending} in progress`;
-  }
+  const changedFiles = getChangedFiles();
+  const contextSignals = checkContextDrift();
+  const isDrifting = driftStatus.drifting > 0 || (memoryDrift?.drifting) || contextSignals.length > 0;
+
+  if (isDrifting) {
+    console.log(`${COLORS.bright}║${COLORS.reset}`);
+    console.log(`${COLORS.bright}║ ${COLORS.red}⚠ DRIFT DETECTED ⚠${COLORS.reset}`);
+
+    // Show stale plans
+    if (driftStatus.stalePlans.length > 0) {
+      console.log(`${COLORS.bright}║   Stale plans (>48h):${COLORS.reset}`);
+      for (const sp of driftStatus.stalePlans.slice(0, 3)) {
+        console.log(`${COLORS.bright}║     - ${sp.planId}${COLORS.reset} in ${sp.phase} (${sp.age}h old)`);
+      }
+      if (driftStatus.stalePlans.length > 3) {
+        console.log(`${COLORS.bright}║     ... and ${driftStatus.stalePlans.length - 3} more${COLORS.reset}`);
+      }
+    }
+
+    // Show memory drift signals
+    if (memoryDrift?.signals) {
+      for (const signal of memoryDrift.signals.slice(0, 2)) {
+        const severityColor = signal.severity === 'high' ? COLORS.red : signal.severity === 'medium' ? COLORS.orange : COLORS.yellow;
+        console.log(`${COLORS.bright}║   ${severityColor}${signal.type}${COLORS.reset}: ${signal.message.slice(0, 50)}`);
+      }
+    }
+
+    // Show context drift signals
+    if (contextSignals.length > 0) {
+      for (const signal of contextSignals) {
+        const severityColor = signal.severity === 'high' ? COLORS.red : signal.severity === 'medium' ? COLORS.orange : COLORS.yellow;
+        console.log(`${COLORS.bright}║   ${severityColor}${signal.type}${COLORS.reset}: ${signal.message.slice(0, 50)}`);
+      }
+    }
+
+    // Show changed files
+    if (changedFiles.total > 0) {
+      console.log(`${COLORS.bright}║   Changed files: ${changedFiles.total}${COLORS.reset}`);
+      const codeFiles = changedFiles.untracked.filter(f => f.match(/\.(js|ts|tsx|jsx|py|go|rs|java)$/));
+      if (codeFiles.length > 0) {
+        console.log(`${COLORS.bright}║     Code: ${codeFiles.slice(0, 3).join(', ')}${COLORS.reset}`);
+      }
+    }
 
-  console.log(`${COLORS.bright}║ DRIFT: ${driftIcon} ${driftText}${COLORS.reset}`);
+    // Show actionable guidance
+    console.log(`${COLORS.bright}║${COLORS.reset}`);
+    console.log(`${COLORS.bright}║ ${COLORS.yellow}Action needed:${COLORS.reset}`);
+    console.log(`${COLORS.bright}║   ${COLORS.cyan}1.${COLORS.reset} Run ${COLORS.cyan}/rrr:verify-work${COLORS.reset} to audit current state`);
+    console.log(`${COLORS.bright}║   ${COLORS.cyan}2.${COLORS.reset} Complete stale plans or create SUMMARY.md`);
+    console.log(`${COLORS.bright}║   ${COLORS.cyan}3.${COLORS.reset} Or run ${COLORS.cyan}/rrr:pause-work${COLORS.reset} to reset intent`);
+  } else {
+    // Clean state
+    console.log(`${COLORS.bright}║${COLORS.reset}`);
+    console.log(`${COLORS.bright}║ ${COLORS.green}✓ On Track${COLORS.reset}`);
+    if (changedFiles.total > 0) {
+      console.log(`${COLORS.bright}║   ${changedFiles.total} file(s) changed${COLORS.reset}`);
+    }
+  }
+  // === END DRIFT SECTION ===
 
   // Memory status
+  console.log(`${COLORS.bright}║${COLORS.reset}`);
   if (memorySummary) {
-    const memDriftIcon = memorySummary.drift?.drifting ? '🔴' : '🟢';
-    console.log(`${COLORS.bright}║ MEMORY ${memDriftIcon} ${memorySummary.drift?.message || 'Initializing...'}${COLORS.reset}`);
-    console.log(`${COLORS.bright}║   Intent: ${memorySummary.currentIntent}${COLORS.reset}`);
+    const memStatus = memorySummary.drift?.drifting ? 'Drifting' : memorySummary.drift?.severity === 'medium' ? 'Caution' : 'Clean';
+    const memColor = memorySummary.drift?.drifting ? COLORS.red : memorySummary.drift?.severity === 'medium' ? COLORS.orange : COLORS.green;
+    console.log(`${COLORS.bright}║ ${COLORS.cyan}MEMORY${COLORS.reset} ${memColor}${memStatus}${COLORS.reset} | Intent: ${memorySummary.currentIntent?.slice(0, 30) || 'none'}`);
 
     if (memorySummary.recentCommands.length > 0) {
-      console.log(`${COLORS.bright}║   Recent: ${COLORS.reset}${memorySummary.recentCommands.slice(0, 2).map(c =>
-        `${c.cmd}${c.target ? '(' + c.target + ')' : ''}`
-      ).join(' → ')}`);
+      const recent = memorySummary.recentCommands.slice(0, 2).map(c =>
+        `${c.cmd}${c.target ? '(' + c.target.split('-').slice(0, 2).join('-') + ')' : ''}`
+      ).join(' → ');
+      console.log(`${COLORS.bright}║   Recent: ${COLORS.reset}${recent}`);
     }
   }
 
-  // Project state info
+  // Project state
   if (projectState) {
     console.log(`${COLORS.bright}║${COLORS.reset}`);
-    console.log(`${COLORS.bright}║ STATE: ${projectState.projectType} / ${projectState.milestoneState}${COLORS.reset}`);
+    console.log(`${COLORS.bright}║ ${COLORS.cyan}STATE${COLORS.reset}: ${projectState.projectType} / ${projectState.milestoneState}`);
   }
 
   // Guidance based on state
-  if (projectState && projectState.milestoneState === 'ACTIVE_MILESTONE') {
+  if (projectState && projectState.milestoneState === 'ACTIVE_MILESTONE' && !isDrifting) {
     const incompletePhase = projectState.phases.find(p => p.completed < p.plans && p.completed > 0);
     if (incompletePhase) {
       console.log(`${COLORS.bright}║${COLORS.reset}`);
-      console.log(`${COLORS.bright}║ GUIDANCE:${COLORS.reset}`);
-      console.log(`${COLORS.bright}║   ${incompletePhase.name} is ${incompletePhase.pct}% complete${COLORS.reset}`);
+      console.log(`${COLORS.bright}║ ${COLORS.cyan}SUGGESTED:${COLORS.reset}`);
       const nextPlan = incompletePhase.completed + 1;
-      console.log(`${COLORS.bright}║   Try: /rrr:execute-plan ${incompletePhase.name.split('-')[0]}-${nextPlan}${COLORS.reset}`);
+      console.log(`${COLORS.bright}║   ${incompletePhase.name} is ${incompletePhase.pct}% complete${COLORS.reset}`);
+      console.log(`${COLORS.bright}║   Try: ${COLORS.cyan}/rrr:execute-plan ${incompletePhase.name.split('-')[0]}-${nextPlan}${COLORS.reset}`);
     }
   }