projecta-rrr 1.16.8 → 1.17.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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.9] - 2026-01-28
+
+### Fixed
+
+- **SUMMARY Path Derivation Bug** - During parallel wave execution, SUMMARY files were incorrectly written to the wrong phase directory because `PHASE_DIR` was derived from where the PLAN file physically existed rather than from the PLAN's `phase:` frontmatter value. Now uses `find_phase_dir()` with phase frontmatter to ensure SUMMARYs always go to the correct phase folder.
+
 ## [1.16.8] - 2026-01-28
 
 ### Added

package/agents/rrr-executor.md

@@ -601,10 +601,25 @@ Track for SUMMARY.md generation.
 <summary_creation>
 After all tasks complete, create `{phase}-{plan}-SUMMARY.md`.
 
-**Location:** `{phase-dir}/{phase}-{plan}-SUMMARY.md`
+**Location calculation (milestone-aware):**
+
+```bash
+# Extract phase from PLAN frontmatter (NOT from file location)
+PLAN_PATH="$phase_dir/$phase-$plan-PLAN.md"
+PHASE_VALUE=$(grep -E "^phase:" "$PLAN_PATH" | sed 's/phase: *"\?//' | tr -d '"')
+
+# Use find_phase_dir to get the correct phase directory
+# Searches .planning/milestones/vX.X/phases/ first, then falls back to .planning/phases/
+PHASE_DIR=$(find_phase_dir "$PHASE_VALUE")
+
+# Build SUMMARY path
+SUMMARY_FILE="${PHASE_DIR}/${phase}-${plan}-SUMMARY.md"
+```
 
 **Phase directory:** `.planning/milestones/v{X.Y}/phases/{phase-number}-{name}/` (milestone-aware structure since v1.11)
 
+The SUMMARY goes to the phase directory matching the PLAN's `phase:` frontmatter value, not where the PLAN file physically exists. This ensures consistent behavior during parallel execution.
+
 **Use template from:** @~/.claude/rrr/templates/summary.md
 
 **Frontmatter population:**
@@ -717,7 +732,7 @@ After SUMMARY.md and STATE.md updates:
 **1. Stage execution artifacts:**
 
 ```bash
-git add "{phase-dir}/{phase}-{plan}-SUMMARY.md"
+git add "${PHASE_DIR}/${phase}-${plan}-SUMMARY.md"
 git add .planning/STATE.md
 ```
 
@@ -730,7 +745,7 @@ Tasks completed: [N]/[N]
 - [Task 1 name]
 - [Task 2 name]
 
-SUMMARY: {phase-dir}/{phase}-{plan}-SUMMARY.md
+SUMMARY: ${PHASE_DIR}/${phase}-${plan}-SUMMARY.md
 "
 ```
 

package/bin/install.js

@@ -206,6 +206,7 @@ const hasHelp = args.includes('--help') || args.includes('-h');
 const forceStatusline = args.includes('--force-statusline');
 const forceNotify = args.includes('--force-notify');
 const noNotify = args.includes('--no-notify');
+const hudOnly = args.includes('--hud-only');
 
 console.log(banner);
 
@@ -221,6 +222,7 @@ if (hasHelp) {
     ${cyan}--force-statusline${reset}        Replace existing statusline config
     ${cyan}--force-notify${reset}            Replace existing notification hook
     ${cyan}--no-notify${reset}               Skip notification hook installation
+    ${cyan}--hud-only${reset}                Install only HUD components (themes + stop hook)
 
   ${yellow}Examples:${reset}
     ${dim}# Install to default ~/.claude directory${reset}
@@ -235,6 +237,9 @@ if (hasHelp) {
     ${dim}# Install to current project only${reset}
     npx projecta-rrr --local
 
+    ${dim}# Install only HUD components (OhMyPosh themes + stop hook)${reset}
+    npx projecta-rrr --hud-only
+
   ${yellow}Notes:${reset}
     The --config-dir option is useful when you have multiple Claude Code
     configurations (e.g., for different subscriptions). It takes priority
@@ -730,6 +735,199 @@ function runExternalSkillsBootstrap() {
   }
 }
 
+/**
+ * Backup settings.json before modification
+ * @param {string} settingsPath - Path to settings.json
+ * @returns {string|null} - Path to backup file, or null if backup failed
+ */
+function backupSettings(settingsPath) {
+  if (!fs.existsSync(settingsPath)) {
+    return null;
+  }
+
+  const backupPath = settingsPath + '.bak';
+  try {
+    fs.copyFileSync(settingsPath, backupPath);
+    console.log(`  ${dim}Backed up settings.json → settings.json.bak${reset}`);
+    return backupPath;
+  } catch (e) {
+    console.log(`  ${yellow}⚠${reset} Could not backup settings.json: ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Install OhMyPosh themes to ~/.poshthemes/
+ * @param {string} claudeDir - Claude config directory
+ * @param {boolean} isGlobal - Whether this is a global install
+ * @returns {object} - { installed: string[], skipped: string[] }
+ */
+function installOhMyPoshThemes(claudeDir, isGlobal) {
+  const src = path.join(__dirname, '..', 'rrr', 'ohmyposh');
+  const installed = [];
+  const skipped = [];
+
+  // Check if source themes directory exists
+  if (!fs.existsSync(src)) {
+    console.log(`  ${dim}No OhMyPosh themes found in rrr/ohmyposh/${reset}`);
+    return { installed, skipped };
+  }
+
+  // Determine destination path
+  const poshthemesDir = path.join(os.homedir(), '.poshthemes');
+  fs.mkdirSync(poshthemesDir, { recursive: true });
+
+  // Copy each theme file
+  const themes = fs.readdirSync(src).filter(f => f.endsWith('.omp.json'));
+  for (const theme of themes) {
+    const srcFile = path.join(src, theme);
+    const destFile = path.join(poshthemesDir, theme);
+
+    if (fs.existsSync(destFile)) {
+      skipped.push(theme);
+      console.log(`  ${yellow}⚠${reset} Skipped ~/.poshthemes/${theme} (already exists)`);
+    } else {
+      try {
+        fs.copyFileSync(srcFile, destFile);
+        installed.push(theme);
+        console.log(`  ${green}✓${reset} Installed ~/.poshthemes/${theme}`);
+      } catch (e) {
+        console.log(`  ${yellow}⚠${reset} Could not install ~/.poshthemes/${theme}: ${e.message}`);
+      }
+    }
+  }
+
+  return { installed, skipped };
+}
+
+/**
+ * Install HUD stop hook and configure it in settings.json
+ * @param {string} claudeDir - Claude config directory
+ * @param {object} settings - Settings object to modify
+ * @param {boolean} isGlobal - Whether this is a global install
+ * @param {boolean} bashAvailable - Whether bash is available
+ * @returns {boolean} - True if hook was configured
+ */
+function installHudStopHook(claudeDir, settings, isGlobal, bashAvailable) {
+  const src = path.join(__dirname, '..', 'hooks', 'rrr-update-hud-state.sh');
+
+  // Check if source hook exists
+  if (!fs.existsSync(src)) {
+    console.log(`  ${dim}HUD stop hook not found${reset}`);
+    return false;
+  }
+
+  // Skip if bash is not available
+  if (!bashAvailable) {
+    console.log(`  ${yellow}⚠${reset} Skipped HUD stop hook (bash not available)`);
+    return false;
+  }
+
+  // Copy hook file
+  const hooksDest = path.join(claudeDir, 'hooks');
+  fs.mkdirSync(hooksDest, { recursive: true });
+  const destFile = path.join(hooksDest, 'rrr-update-hud-state.sh');
+
+  try {
+    fs.copyFileSync(src, destFile);
+    fs.chmodSync(destFile, 0o755);
+    console.log(`  ${green}✓${reset} Installed hooks/rrr-update-hud-state.sh`);
+  } catch (e) {
+    console.log(`  ${yellow}⚠${reset} Could not install HUD hook: ${e.message}`);
+    return false;
+  }
+
+  // Configure hook in settings.json
+  const hookCommand = isGlobal
+    ? '$HOME/.claude/hooks/rrr-update-hud-state.sh'
+    : `${path.basename(claudeDir)}/hooks/rrr-update-hud-state.sh`;
+
+  // Check if HUD hook already exists
+  const hasHudHook = settings.hooks?.Stop?.some(entry =>
+    entry.hooks && entry.hooks.some(h => h.command && h.command.includes('rrr-update-hud-state'))
+  );
+
+  if (hasHudHook) {
+    console.log(`  ${dim}HUD stop hook already configured${reset}`);
+    return true;
+  }
+
+  // Add hook to Stop hooks
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+  if (!settings.hooks.Stop) {
+    settings.hooks.Stop = [];
+  }
+
+  settings.hooks.Stop.push({
+    hooks: [
+      {
+        type: 'command',
+        command: hookCommand
+      }
+    ]
+  });
+
+  console.log(`  ${green}✓${reset} Configured HUD stop hook`);
+  return true;
+}
+
+/**
+ * HUD-only installation mode
+ * Installs only OhMyPosh themes and HUD stop hook
+ */
+function installHudOnly() {
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  const claudeDir = configDir || path.join(os.homedir(), '.claude');
+  const isGlobal = true;
+
+  console.log(`\n  ${cyan}Installing RRR HUD components${reset}\n`);
+
+  // Check bash availability
+  let bashStatus = { available: true };
+  if (isWindows()) {
+    bashStatus = checkBashAvailability();
+    if (!bashStatus.available) {
+      printWindowsBashWarning();
+    }
+  }
+
+  // Install OhMyPosh themes
+  console.log(`  ${cyan}OhMyPosh Themes${reset}`);
+  const themesResult = installOhMyPoshThemes(claudeDir, isGlobal);
+
+  // Read and backup settings
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  const settings = readSettings(settingsPath);
+
+  if (fs.existsSync(settingsPath)) {
+    backupSettings(settingsPath);
+  }
+
+  // Install HUD stop hook
+  console.log(`\n  ${cyan}HUD Stop Hook${reset}`);
+  installHudStopHook(claudeDir, settings, isGlobal, bashStatus.available);
+
+  // Write settings if modified
+  if (settings.hooks?.Stop) {
+    writeSettings(settingsPath, settings);
+    console.log(`  ${green}✓${reset} Updated settings.json`);
+  }
+
+  console.log(`
+  ${green}HUD installation complete!${reset}
+
+  ${yellow}Next steps:${reset}
+  1. Add to your shell profile:
+     source ~/.claude/rrr/ohmyposh/rrr-env.sh
+     eval "$(oh-my-posh init bash)"
+     oh-my-posh --config ~/.poshthemes/rrr-kushal.omp.json
+
+  2. Restart your terminal or source ~/.zshrc
+  `);
+}
+
 /**
  * Install to the specified directory
  */
@@ -932,6 +1130,17 @@ function install(isGlobal) {
     console.log(`  ${green}✓${reset} Installed rrr/scripts/rrr-hud.js`);
   }
 
+  // PATCH-01: Copy rrr-hud-dynamic.js to ~/.claude/rrr/scripts/
+  // Dynamic HUD state sync from RRR project files
+  const hudDynamicSrc = path.join(src, 'scripts', 'rrr-hud-dynamic.js');
+  if (fs.existsSync(hudDynamicSrc)) {
+    const scriptsDestDir = path.join(claudeDir, 'rrr', 'scripts');
+    fs.mkdirSync(scriptsDestDir, { recursive: true });
+    const hudDynamicDest = path.join(scriptsDestDir, 'rrr-hud-dynamic.js');
+    fs.copyFileSync(hudDynamicSrc, hudDynamicDest);
+    console.log(`  ${green}✓${reset} Installed rrr/scripts/rrr-hud-dynamic.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');
@@ -1121,6 +1330,37 @@ function install(isGlobal) {
     }
   }
 
+  // Configure SessionStart hook for HUD state sync (only if hook file exists AND bash available)
+  const hudSyncCommand = isGlobal
+    ? '$HOME/.claude/hooks/rrr-sync-hud-state.sh'
+    : `${localDirName}/hooks/rrr-sync-hud-state.sh`;
+
+  if (bashStatus.available && hookFileExists(claudeDir, 'rrr-sync-hud-state.sh')) {
+    if (!settings.hooks) {
+      settings.hooks = {};
+    }
+    if (!settings.hooks.SessionStart) {
+      settings.hooks.SessionStart = [];
+    }
+
+    // Check if HUD sync hook already exists
+    const hasHudSyncHook = settings.hooks.SessionStart.some(entry =>
+      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('rrr-sync-hud-state'))
+    );
+
+    if (!hasHudSyncHook) {
+      settings.hooks.SessionStart.push({
+        hooks: [
+          {
+            type: 'command',
+            command: hudSyncCommand
+          }
+        ]
+      });
+      console.log(`  ${green}✓${reset} Configured HUD state sync hook`);
+    }
+  }
+
   // 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();
@@ -1599,7 +1839,11 @@ function promptLocation() {
 }
 
 // Main
-if (hasGlobal && hasLocal) {
+if (hudOnly) {
+  // HUD-only installation mode
+  installHudOnly();
+  process.exit(0);
+} else if (hasGlobal && hasLocal) {
   console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
   process.exit(1);
 } else if (explicitConfigDir && hasLocal) {

package/commands/rrr/check-upstream.md

@@ -0,0 +1,37 @@
+# Check for RRR-impacting upstream changes
+
+Runs all upstream watchers (Claude Code, Get-Shit-Done, Taches CC Resources) and reports changes that may affect RRR workflows.
+
+## Usage
+
+```
+/rrr:check-upstream
+/rrr:check-upstream --verbose    # Show detailed change list
+/rrr:check-upstream --watcher    # Run specific watcher only
+```
+
+## Output
+
+Reports:
+- Current version of each upstream
+- NEW releases with HIGH risk changes (hooks, permissions, tasks)
+- NEW releases with MEDIUM risk changes (subagents, statusline, setup, fileops, context)
+- Links to release notes for further review
+
+HIGH risk changes require immediate attention for RRR compatibility.
+MEDIUM risk changes should be reviewed for improvement opportunities.
+
+## Watchers
+
+| Upstream | Role | What's Monitored |
+|----------|------|------------------|
+| Claude Code | toolchain | CLI changes affecting RRR workflows |
+| Get-Shit-Done | strict_baseline | Commands, agents, scripts that RRR extends |
+| Taches CC Resources | capability_harvest | Skills, prompts, workflows for pattern harvest |
+
+## Examples
+
+```
+/rrr:check-upstream           # Quick check for new releases with impact
+/rrr:check-upstream --verbose # Show all RRR-impacting changes
+```

package/commands/rrr/doctor.md

@@ -1,7 +1,7 @@
 ---
 name: rrr:doctor
 description: Diagnose and fix duplicate RRR installs - non-destructive with rollback
-argument-hint: [--report | --fix | --phases | --include-local]
+argument-hint: [--report | --fix | --phases | --include-local | --footer | --fix-footer]
 allowed-tools: Read, Bash, Glob, Grep, Edit, Write
 ---
 
@@ -19,6 +19,8 @@ Diagnose RRR installation for issues and optionally fix them safely.
 - `--fix`: Quarantine duplicate roots safely, keeping one canonical root
 - `--phases`: Check and fix duplicate phase directories (v1.15.9+)
 - `--include-local`: Also scan/fix repo-local `.claude/commands/rrr`
+- `--footer`: Check HUD/footer installation (OhMyPosh themes, hooks, settings)
+- `--fix-footer`: Auto-repair HUD/footer installation issues
 </objective>
 
 <windows_compatible>true</windows_compatible>
@@ -216,6 +218,75 @@ RECOMMENDED ACTIONS:
 ```
 </step>
 
+<step name="footer_check_mode">
+**Footer/HUD Installation Check (--footer)**
+
+Check OhMyPosh HUD installation status:
+
+```bash
+node ~/.claude/rrr/scripts/doctor-rrr.js --footer
+```
+
+**Checks performed:**
+- OhMyPosh themes installed (`rrr-atomic.omp.json`, `rrr-kushal.omp.json`)
+- HUD stop hook installed (`rrr-update-hud-state.sh`)
+- HUD sync hook configured in settings.json (`rrr-sync-hud-state.sh`)
+- `rrr-env.sh` sourced for environment variables
+- `hud-state.json` exists
+
+**Example output:**
+```
+RRR HUD / Footer Installation Check
+═══════════════════════════════════════════════════════════════
+
+  ✓ OhMyPosh themes: 2/2 installed
+  ✓ HUD stop hook: rrr-update-hud-state.sh exists
+  ✓ HUD hook config: Configured in settings.json
+  ⚠ RRR env script: rrr-env.sh not found (optional)
+  ✓ HUD state file: hud-state.json exists
+
+─────────────────────────────────────────────────────────────
+Status: HEALTHY
+─────────────────────────────────────────────────────────────
+
+Run with --fix-footer to auto-repair issues.
+```
+</step>
+
+<step name="footer_fix_mode">
+**Footer/HUD Repair (--fix-footer)**
+
+Auto-repair HUD installation issues:
+
+```bash
+node ~/.claude/rrr/scripts/doctor-rrr.js --fix-footer
+```
+
+**Repairs performed:**
+1. Copies OhMyPosh themes to `~/.claude/rrr/ohmyposh/`
+2. Installs HUD stop hook to `~/.claude/hooks/`
+3. Installs HUD sync hook to `~/.claude/hooks/`
+4. Configures both hooks in `settings.json`
+5. Copies `rrr-env.sh` for shell integration
+
+**What it fixes:**
+- Missing theme files
+- Missing hook files
+- Hooks not configured in settings.json
+- Stale hook paths
+
+**Example output:**
+```
+Repaired:
+
+  ✓ Installed rrr-atomic.omp.json
+  ✓ Installed rrr-kushal.omp.json
+  ✓ Installed rrr-update-hud-state.sh
+  ✓ Installed rrr-sync-hud-state.sh
+  ✓ Configured HUD hooks in settings.json
+```
+</step>
+
 </process>
 
 <success_criteria>
@@ -227,6 +298,9 @@ RECOMMENDED ACTIONS:
 - [ ] Validation confirms exactly one root remains
 - [ ] Repo-local roots are protected by default
 - [ ] Works on Windows (no bash constructs)
+- [ ] Footer mode checks all HUD components (themes, hooks, settings)
+- [ ] Fix-footer mode repairs missing/broken HUD components
+- [ ] HUD state syncs dynamically from RRR project files
 </success_criteria>
 
 <notes>

package/commands/rrr/update.md

@@ -203,6 +203,50 @@ Run /rrr:doctor --fix to complete cleanup.
 ```
 </step>
 
+<step name="refresh_hud_components">
+After successful update, refresh HUD components (OhMyPosh themes and stop hook):
+
+```bash
+# Check if HUD components need refresh
+HUD_REFRESH_NEEDED=false
+
+# Check if themes exist in source
+if [ -d "rrr/ohmyposh" ]; then
+  # Compare modification times
+  SOURCE_THEMES_MTIME=$(stat -f "%m" rrr/ohmyposh/rrr-atomic.omp.json 2>/dev/null || stat -c "%Y" rrr/ohmyposh/rrr-atomic.omp.json 2>/dev/null)
+  INSTALLED_THEMES_MTIME=$(stat -f "%m" ~/.claude/rrr/ohmyposh/rrr-atomic.omp.json 2>/dev/null || stat -c "%Y" ~/.claude/rrr/ohmyposh/rrr-atomic.omp.json 2>/dev/null)
+
+  if [ "$SOURCE_THEMES_MTIME" -gt "$INSTALLED_THEMES_MTIME" ]; then
+    HUD_REFRESH_NEEDED=true
+  fi
+fi
+
+# Check if HUD hook exists and needs refresh
+if [ -f "hooks/rrr-update-hud-state.sh" ] && [ -f ~/.claude/hooks/rrr-update-hud-state.sh ]; then
+  SOURCE_HOOK_MTIME=$(stat -f "%m" hooks/rrr-update-hud-state.sh 2>/dev/null || stat -c "%Y" hooks/rrr-update-hud-state.sh 2>/dev/null)
+  INSTALLED_HOOK_MTIME=$(stat -f "%m" ~/.claude/hooks/rrr-update-hud-state.sh 2>/dev/null || stat -c "%Y" ~/.claude/hooks/rrr-update-hud-state.sh 2>/dev/null)
+
+  if [ "$SOURCE_HOOK_MTIME" -gt "$INSTALLED_HOOK_MTIME" ]; then
+    HUD_REFRESH_NEEDED=true
+  fi
+fi
+
+# Refresh if needed
+if [ "$HUD_REFRESH_NEEDED" = true ]; then
+  node bin/install.js --hud-only --global
+  echo "+ HUD components refreshed"
+fi
+```
+
+**Note:** The update process automatically runs `node bin/install.js --hud-only --global` as part of the postinstall hook when installing via npm. This step is for verification only.
+
+**Display result:**
+```
+✓ OhMyPosh themes up to date
+✓ HUD stop hook configured
+```
+</step>
+
 <step name="fetch_secrets_optional">
 **Optional: Auto-fetch secrets from Infisical**