projecta-rrr 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -4,6 +4,85 @@ All notable changes to RRR will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.18.0] - 2026-01-30
+
+### Added
+
+- **Real-time Drift Detection** - PostToolUse hooks trigger `detectDrift()` on every file modification
+- **Intent Persistence** - Structured JSON (`current-intent.json`) maintains context across sessions
+- **Episode Logging** - JSONL append-only log (`.planning/episodes/YYYY-MM-DD.jsonl`) enables future Graphiti integration
+- **Scope Classification** - Heuristic classifier routes requests to correct RRR commands (PATCH/BUG/PLAN/PHASE/MILESTONE)
+- **Orphan Detection** - Identifies files modified outside planned scope with alerts
+- **Decision Recall** - Surfaces past decisions during planning from decision-store
+- **Reuse Candidate Gate** - Mandatory semantic/lexical search before code generation in execute-plan workflow
+- **Smart Drift Alerts** - UserPromptSubmit hook with intelligent skip conditions
+
+### New Libraries
+
+- `rrr/lib/scope-classifier.js` - Request classification
+- `rrr/lib/orphan-detector.js` - Out-of-scope file detection
+- `rrr/lib/decision-store.js` - Structured rationale storage
+- `rrr/lib/decision-recall.js` - Decision query and retrieval
+- `rrr/lib/reuse-candidates.js` - Semantic + lexical candidate search
+- `rrr/lib/reuse-gate.js` - Workflow gate implementation
+
+### New Scripts
+
+- `rrr/scripts/drift-detect.js` - CLI for drift detection
+- `rrr/scripts/episode-emit.js` - Episode logging
+- `rrr/scripts/save-intent.js` - Intent persistence
+- `rrr/scripts/classify-request.js` - Request classification CLI
+- `rrr/scripts/record-decision.js` - Decision recording
+- `rrr/scripts/recall-decisions.js` - Decision retrieval
+- `rrr/scripts/query-reuse-candidates.js` - Reuse candidate queries
+- `scripts/verify-hooks.js` - Hook verification debug script
+
+### New Hooks
+
+- `hooks/rrr-detect-drift.sh` - PostToolUse drift detection
+- `hooks/rrr-classify-intent.sh` - UserPromptSubmit intent classification
+- `hooks/rrr-intent-check.sh` - SessionStart drift check
+- `hooks/rrr-update-cache-stats.sh` - Cache stats on session start
+
+## [1.17.1] - 2026-01-30
+
+### Fixed
+
+- Re-release of 1.17.0 with all intent drift detection features
+
+## [1.17.0] - 2026-01-30
+
+### Added
+
+- **Smart Intent Drift Detection** (`hooks/rrr-classify-intent.sh`) - UserPromptSubmit hook that:
+  - Classifies user requests as PATCH/BUG/PLAN/PHASE/MILESTONE
+  - Compares with current intent/plan context
+  - Outputs drift warning when user is working off-plan
+  - Suggests appropriate RRR command to get back on track
+  - Smart filtering: skips conversational, questions, patch-level requests
+
+- **Enhanced Statusline** (`hooks/statusline.sh`) - ASCII-compatible footer showing:
+  - Index health: `IDX:2.2k` (indexed files count)
+  - Location: `v1.18/64 (2/2)` (milestone/phase with plan progress)
+  - Drift status: `DRIFT:11 files` or `OK`
+  - Model, directory, and context usage bar
+  - No emojis/Unicode for Claude Code compatibility
+
+- **Scope Classifier Integration** - Wired Phase 63's classifier to real-time request analysis
+
+- **Intent Check Hook** (`hooks/rrr-intent-check.sh`) - SessionStart hook for initial drift check
+
+- **Cache Stats Hook** (`hooks/rrr-update-cache-stats.sh`) - Updates semantic index stats on session start
+
+### Changed
+
+- **Install Script** - Now configures UserPromptSubmit hook for intent classification
+- **HUD State** - Added `plans_in_phase` and `plans_completed` tracking
+
+### Fixed
+
+- **Phase 61+63 Integration** - Properly wired scope classifier and episode emitter to Claude Code hooks
+
 ## [1.16.9] - 2026-01-28
 
 ### Fixed

package/bin/install.js

@@ -1361,6 +1361,69 @@ function install(isGlobal) {
     }
   }
 
+  // PATCH-01: Configure PostToolUse hook for drift detection
+  // This hook fires after every tool use to detect project drift
+  const detectDriftCommand = isGlobal
+    ? '$HOME/.claude/hooks/rrr-detect-drift.sh'
+    : `${localDirName}/hooks/rrr-detect-drift.sh`;
+
+  if (bashStatus.available && hookFileExists(claudeDir, 'rrr-detect-drift.sh')) {
+    if (!settings.hooks) {
+      settings.hooks = {};
+    }
+    if (!settings.hooks.PostToolUse) {
+      settings.hooks.PostToolUse = [];
+    }
+
+    // Check if drift detection hook already exists
+    const hasDriftHook = settings.hooks.PostToolUse.some(entry =>
+      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('rrr-detect-drift'))
+    );
+
+    if (!hasDriftHook) {
+      settings.hooks.PostToolUse.push({
+        matcher: '*',  // Required: match all tools
+        hooks: [
+          {
+            type: 'command',
+            command: detectDriftCommand
+          }
+        ]
+      });
+      console.log(`  ${green}✓${reset} Configured drift detection hook (PostToolUse)`);
+    }
+  }
+
+  // Configure UserPromptSubmit hook for intent classification (smart drift detection)
+  const classifyIntentCommand = isGlobal
+    ? '$HOME/.claude/hooks/rrr-classify-intent.sh'
+    : `${localDirName}/hooks/rrr-classify-intent.sh`;
+
+  if (bashStatus.available) {
+    if (!settings.hooks) {
+      settings.hooks = {};
+    }
+    if (!settings.hooks.UserPromptSubmit) {
+      settings.hooks.UserPromptSubmit = [];
+    }
+
+    const hasClassifyHook = settings.hooks.UserPromptSubmit.some(entry =>
+      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('rrr-classify-intent'))
+    );
+
+    if (!hasClassifyHook) {
+      settings.hooks.UserPromptSubmit.push({
+        hooks: [
+          {
+            type: 'command',
+            command: classifyIntentCommand
+          }
+        ]
+      });
+      console.log(`  ${green}✓${reset} Configured intent classification hook (UserPromptSubmit)`);
+    }
+  }
+
   // Install Pushpa Mode and MCP setup scripts to the project directory
   // For local install, use current directory; for global, also install to cwd if it has package.json
   const projectDir = process.cwd();

package/commands/rrr/execute-plan.md

@@ -37,6 +37,13 @@ Plan path: $ARGUMENTS
 @.planning/STATE.md
 @.planning/config.json (if exists)
 @rrr/lib/memory-store.js
+
+**Note:** During execution, `.planning/current-intent.json` is created with the current plan's intent, milestone, phase, and allowed paths. This file is used by drift detection hooks to validate that file changes stay within scope.
+
+**Intent lifecycle:**
+- Step 0.3: Save intent on plan start
+- Step 7.55: Clear intent on plan completion
+- Intent persists through checkpoints (not cleared until plan complete)
 </context>
 
 <process>
@@ -85,6 +92,38 @@ Plan path: $ARGUMENTS
    " 2>/dev/null || echo "[MEMORY] Tracking skipped"
    ```
 
+0.3. **Save structured intent (before execution)**
+
+   After tracking command in memory, save structured intent for drift detection:
+
+   ```bash
+   # Parse plan path to extract identifiers
+   PLAN_FILE="$ARGUMENTS"
+   PLAN_ID=$(basename "$PLAN_FILE" | sed 's/-PLAN\.md$//')
+   PHASE_DIR=$(dirname "$PLAN_FILE")
+   PHASE_NAME=$(basename "$PHASE_DIR")
+   PHASE_NUM=$(echo "$PHASE_NAME" | cut -d'-' -f1)
+
+   # Extract milestone from ROADMAP.md
+   MILESTONE=$(grep -E "^## Current Milestone:" .planning/ROADMAP.md 2>/dev/null | sed 's/.*Milestone: *\(v[0-9.]*\).*/\1/' || echo "")
+
+   # Extract allowed paths from plan frontmatter (files_modified)
+   ALLOWED_PATHS=$(grep -A100 "^files_modified:" "$PLAN_FILE" 2>/dev/null | grep -E "^  - " | head -20 | sed 's/^  - //' | tr -d '"' | tr '\n' ',' | sed 's/,$//')
+
+   # Extract intent from plan objective
+   INTENT=$(grep -A5 "<objective>" "$PLAN_FILE" 2>/dev/null | head -3 | tail -1 | sed 's/^ *//' || echo "Executing plan $PLAN_ID")
+
+   # Save intent using save-intent.js
+   node ~/.claude/rrr/scripts/save-intent.js \
+     --milestone="$MILESTONE" \
+     --phase="$PHASE_NUM" \
+     --plan="$PLAN_ID" \
+     --intent="$INTENT" \
+     --allowed-paths="$ALLOWED_PATHS" 2>/dev/null || echo "[INTENT] Save skipped"
+   ```
+
+   This creates `.planning/current-intent.json` with full context for drift detection and HUD display.
+
 0.5. **Scope Check (validate plan is in scope)**
 
    Before executing, validate the plan's files against current scope:
@@ -412,6 +451,18 @@ Config: @.planning/config.json (if exists)",
       - Do NOT proceed to step 8
       - Return control to user
 
+7.55. **Clear intent (plan complete)**
+
+   After SUMMARY.md is verified, clear the current intent:
+
+   ```bash
+   node ~/.claude/rrr/scripts/save-intent.js --clear 2>/dev/null || echo "[INTENT] Clear skipped"
+   ```
+
+   This ensures the next session starts fresh without stale "Continuing: [intent]" display.
+
+   **Note:** Intent is only cleared on plan completion (SUMMARY.md exists), not on checkpoints. This allows resuming work after session interruptions while the plan is still in progress.
+
 7.6. **Refresh Scope Cache (after SUMMARY)**
    ```bash
    node ~/.claude/rrr/scripts/refresh-scope-cache.js 2>/dev/null || echo "Cache refresh skipped"

package/commands/rrr/plan-phase.md

@@ -420,6 +420,44 @@ echo "${PHASE}" > /tmp/rrr-todo-dismissed-${PHASE}
 - Display: `Run /rrr:check-todos to review and manage your TODOs`
 - Exit command
 
+## 3.7. Recall Past Decisions
+
+**Before planning, surface relevant prior decisions to prevent re-debating settled issues.**
+
+```bash
+# Find relevant decisions for this phase
+node -e "
+const dr = require('./rrr/lib/decision-recall');
+const decisions = dr.recallRelevantDecisions({
+  phaseGoal: '${PHASE_GOAL}',
+  phaseId: '${PHASE}',
+  tags: ['${PHASE_TYPE}'],
+  limit: 5
+});
+if (decisions.length > 0) {
+  console.log(dr.formatDecisionContext(decisions));
+}
+" 2>/dev/null
+```
+
+**If relevant decisions found:**
+- Include them in planning context for the planner agent
+- Reference them when making similar choices
+- Note if any prior decision should influence current plan
+
+**If no decisions found or script not available:**
+- Continue to step 4 (first-time planning is normal)
+
+<context_guidance>
+## Prior Decisions
+
+When planning, consider:
+1. Check if similar decisions were made before
+2. Honor prior decisions unless circumstances changed
+3. If revisiting a decision, document why
+4. Reference decision IDs in plan rationale
+</context_guidance>
+
 ## 4. Ensure Phase Directory Exists (Cross-Platform)
 
 **On macOS/Linux:**
@@ -659,6 +697,9 @@ Fill prompt and spawn:
 @{phase_dir}/{phase}-VERIFICATION.md
 @{phase_dir}/{phase}-UAT.md
 
+**Prior Decisions (from step 3.7, if any):**
+{prior_decisions_context}
+
 </planning_context>
 
 <downstream_consumer>

package/docs/ohmyposh-config.md

@@ -0,0 +1,268 @@
+# OhMyPosh Integration for RRR HUD
+
+Display RRR context (intent, drift status, session duration) in your terminal prompt using OhMyPosh.
+
+## Prerequisites
+
+- [OhMyPosh](https://ohmyposh.dev/) installed
+- RRR installed (`npx @anthropic/claude-rrr@latest`)
+- `jq` installed for JSON parsing
+
+```bash
+# Install OhMyPosh (macOS)
+brew install jandedobbeleer/oh-my-posh/oh-my-posh
+
+# Install jq
+brew install jq
+```
+
+## Quick Setup
+
+### Option 1: Use RRR Statusline (Recommended)
+
+RRR provides a statusline script that outputs all HUD information in a single line. This is the simplest setup and matches Claude Code's native statusline.
+
+1. **Copy the segment to your OhMyPosh config:**
+
+   Add this segment to your `~/.ohmyposh.toml` or JSON config:
+
+   ```json
+   {
+     "type": "command",
+     "style": "plain",
+     "properties": {
+       "shell": "bash",
+       "command": "cat /dev/stdin | ~/.claude/rrr-npm/hooks/statusline.sh"
+     },
+     "template": "{{ .Output }}"
+   }
+   ```
+
+2. **Output format:**
+
+   With active intent and drift:
+   ```
+   Continuing: [intent] | !! Drift: HIGH | 45m | Claude | project [###------- 30%]
+   ```
+
+   Without intent/drift (normal state):
+   ```
+   Claude | project [###------- 30%]
+   ```
+
+### Option 2: Individual Segments
+
+For more control over styling and placement, use separate segments. Copy these from the RRR config template at `hooks/rrr-hud.ohmyposh.json`.
+
+#### Intent Segment
+
+Shows current work context (e.g., "Continuing: Implement auth flow").
+
+```json
+{
+  "type": "command",
+  "style": "powerline",
+  "foreground": "#61AFEF",
+  "background": "#2D3748",
+  "properties": {
+    "shell": "bash",
+    "command": "jq -r 'if .intent.active then \"Continuing: \" + (.intent.text | .[0:27]) else \"\" end' ~/.claude/rrr/hud-state.json 2>/dev/null"
+  },
+  "template": "{{ if .Output }} {{ .Output }} {{ end }}"
+}
+```
+
+#### Drift Segment
+
+Shows drift severity with color-coded warning levels.
+
+```json
+{
+  "type": "command",
+  "style": "powerline",
+  "foreground_templates": [
+    "{{ if contains \"HIGH\" .Output }}#FF6B6B{{ end }}",
+    "{{ if contains \"MEDIUM\" .Output }}#FFE66D{{ end }}",
+    "{{ if contains \"LOW\" .Output }}#4ECDC4{{ end }}"
+  ],
+  "background": "#2D3748",
+  "properties": {
+    "shell": "bash",
+    "command": "jq -r 'if .drifting then (if .severity == \"high\" then \"!! HIGH\" elif .severity == \"medium\" then \"! MED\" else \"~ LOW\" end) else \"\" end' .planning/.drift-status.json 2>/dev/null"
+  },
+  "template": "{{ if .Output }} {{ .Output }} {{ end }}"
+}
+```
+
+#### Duration Segment
+
+Shows time elapsed since intent started.
+
+```json
+{
+  "type": "command",
+  "style": "plain",
+  "foreground": "#ABB2BF",
+  "properties": {
+    "shell": "bash",
+    "command": "st=$(jq -r '.intent.start_time // \"\"' ~/.claude/rrr/hud-state.json 2>/dev/null); if [ -n \"$st\" ] && [ \"$st\" != \"null\" ]; then if [ \"$(uname)\" = \"Darwin\" ]; then se=$(date -j -f '%Y-%m-%dT%H:%M:%S' \"${st%.*}\" +%s 2>/dev/null); else se=$(date -d \"$st\" +%s 2>/dev/null); fi; if [ -n \"$se\" ]; then el=$(($(date +%s)-se)); if [ $el -lt 60 ]; then echo \"${el}s\"; elif [ $el -lt 3600 ]; then echo \"$((el/60))m\"; else echo \"$((el/3600))h$((el%3600/60))m\"; fi; fi; fi"
+  },
+  "template": "{{ if .Output }} {{ .Output }} {{ end }}"
+}
+```
+
+## Color Reference
+
+| Element | Color | Hex | Meaning |
+|---------|-------|-----|---------|
+| Intent | Blue | `#61AFEF` | Current work focus |
+| Drift HIGH | Red | `#FF6B6B` | Significant context switch - urgent attention |
+| Drift MEDIUM | Yellow | `#FFE66D` | Some unrelated work - caution |
+| Drift LOW | Teal | `#4ECDC4` | Minor drift detected - gentle notice |
+| Duration | Gray | `#ABB2BF` | Time since intent started |
+
+## How It Works
+
+The RRR HUD integrates with Claude Code's hook system:
+
+```
+[SessionStart] -> rrr-sync-hud-state.sh -> ~/.claude/rrr/hud-state.json
+                        |
+                        v
+                  Load intent from
+            .planning/current-intent.json
+
+[PostToolUse] -> rrr-detect-drift.sh -> .planning/.drift-status.json
+                        |
+                        v
+                  Detect drift after
+                  file modifications
+
+[Statusline] -> statusline.sh -> Terminal prompt
+                        |
+                        v
+                  Read hud-state.json
+                  and drift-status.json,
+                  format output
+
+[OhMyPosh] -> Render statusline output in prompt
+```
+
+### Data Flow
+
+1. **SessionStart hook** (`rrr-sync-hud-state.sh`) loads intent from `.planning/current-intent.json` into `~/.claude/rrr/hud-state.json`
+
+2. **PostToolUse hook** (`rrr-detect-drift.sh`) runs drift detection after file changes, writes to `.planning/.drift-status.json`
+
+3. **Statusline** (`statusline.sh`) reads both files and formats output for display
+
+4. **OhMyPosh** renders the statusline output in your terminal prompt
+
+### State Files
+
+| File | Location | Updated By | Contains |
+|------|----------|------------|----------|
+| `hud-state.json` | `~/.claude/rrr/` | `rrr-sync-hud-state.sh` | Intent text, start time, active flag |
+| `drift-status.json` | `.planning/` | `rrr-detect-drift.sh` | Drifting flag, severity, details |
+| `current-intent.json` | `.planning/` | `/rrr:execute-plan` | Plan intent, allowed paths |
+
+## Troubleshooting
+
+### Nothing appears in prompt
+
+1. Check if `~/.claude/rrr/hud-state.json` exists:
+   ```bash
+   cat ~/.claude/rrr/hud-state.json
+   ```
+
+2. Verify jq is installed:
+   ```bash
+   which jq
+   ```
+
+3. Test statusline directly:
+   ```bash
+   echo '{"model":{"display_name":"Claude"},"workspace":{"current_dir":"/tmp"},"session_id":"test"}' | ~/.claude/rrr-npm/hooks/statusline.sh
+   ```
+
+4. Check OhMyPosh is loading your config:
+   ```bash
+   oh-my-posh debug
+   ```
+
+### Intent not showing
+
+Intent is populated when you start a plan with `/rrr:execute-plan`. To see intent in the statusline:
+
+1. Start executing an RRR plan
+2. The SessionStart hook creates `hud-state.json` with the intent
+3. The statusline reads and displays it
+
+To test manually:
+```bash
+echo '{"intent":{"active":true,"text":"Test intent","start_time":"2026-01-30T12:00:00Z"}}' > ~/.claude/rrr/hud-state.json
+```
+
+### Drift not showing
+
+Drift is only detected after file-modifying operations (Write, Edit, Bash). It reads from `.planning/.drift-status.json` in your project.
+
+1. Check if `.planning/.drift-status.json` exists in your project
+2. Verify the file has `"drifting": true` when drift is expected
+3. Test manually:
+   ```bash
+   echo '{"drifting":true,"severity":"high"}' > .planning/.drift-status.json
+   ```
+
+### Slow prompt
+
+The command segments run on every prompt render. If your prompt feels slow:
+
+1. Use the unified statusline segment (Option 1) instead of individual segments
+2. Check that `jq` is installed and not being installed on-demand
+3. Ensure file paths are correct (failed file reads add latency)
+
+### Colors not appearing
+
+OhMyPosh's `foreground_templates` require the output to contain the trigger text. Verify:
+
+```bash
+# Should output "!! HIGH" for red, "! MED" for yellow, "~ LOW" for teal
+jq -r 'if .drifting then (if .severity == "high" then "!! HIGH" elif .severity == "medium" then "! MED" else "~ LOW" end) else "" end' .planning/.drift-status.json
+```
+
+## Integration with Existing Theme
+
+To add RRR segments to your existing OhMyPosh theme:
+
+1. Open your OhMyPosh config file (e.g., `~/.ohmyposh.toml` or `~/.poshthemes/mytheme.omp.json`)
+
+2. Add the RRR segments to your preferred block/position
+
+3. Reference the complete example in `hooks/rrr-hud.ohmyposh.json`
+
+Example adding to right-aligned block:
+```json
+{
+  "type": "prompt",
+  "alignment": "right",
+  "segments": [
+    // ... your existing segments ...
+    {
+      "type": "command",
+      "style": "plain",
+      "properties": {
+        "shell": "bash",
+        "command": "cat /dev/stdin | ~/.claude/rrr-npm/hooks/statusline.sh 2>/dev/null"
+      },
+      "template": "{{ .Output }}"
+    }
+  ]
+}
+```
+
+## See Also
+
+- [OHMPOSH-SETUP.md](./OHMPOSH-SETUP.md) - Full OhMyPosh theme setup with Kushal/Atomic themes
+- `hooks/statusline.sh` - The statusline script source
+- `hooks/rrr-hud.ohmyposh.json` - Full OhMyPosh segment configuration template