@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/scripts/auto-continue.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+/**
+ * Stop hook: Auto-continue via signal files.
+ *
+ * When enabled (features.auto_continue: true in config.json),
+ * reads .planning/.auto-next signal file on session stop.
+ * If present, reads the next command and injects it.
+ * Signal file is ONE-SHOT: read and delete to prevent infinite loops.
+ *
+ * Hard stops (signal file NOT written):
+ * - Milestone completion
+ * - human_needed flag set
+ * - Execution errors
+ * - Gap closure attempted 3+ times
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { configLoad } = require('./pbr-tools');
+
+function main() {
+  try {
+    const cwd = process.cwd();
+    const planningDir = path.join(cwd, '.planning');
+    const signalPath = path.join(planningDir, '.auto-next');
+
+    // Check if auto-continue is enabled
+    const config = configLoad(planningDir);
+    if (!config || !config.features || !config.features.auto_continue) {
+      process.exit(0);
+    }
+
+    // Check for signal file
+    if (!fs.existsSync(signalPath)) {
+      logHook('auto-continue', 'Stop', 'no-signal', {});
+      process.exit(0);
+    }
+
+    // Read and DELETE the signal file (one-shot)
+    const nextCommand = fs.readFileSync(signalPath, 'utf8').trim();
+    // Retry unlink with exponential backoff for Windows file locking (antivirus/indexer)
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        fs.unlinkSync(signalPath);
+        break;
+      } catch (unlinkErr) {
+        if (attempt === 2) {
+          logHook('auto-continue', 'Stop', 'unlink-failed', { error: unlinkErr.message });
+        } else {
+          // Exponential backoff: 100ms, 200ms
+          const delay = 100 * Math.pow(2, attempt);
+          const start = Date.now();
+          while (Date.now() - start < delay) { /* busy-wait */ }
+        }
+      }
+    }
+
+    if (!nextCommand) {
+      logHook('auto-continue', 'Stop', 'empty-signal', {});
+      process.exit(0);
+    }
+
+    logHook('auto-continue', 'Stop', 'continue', { next: nextCommand });
+
+    // Output the next command for Claude Code to execute
+    const output = {
+      message: `Auto-continuing with: ${nextCommand}`,
+      command: nextCommand
+    };
+    process.stdout.write(JSON.stringify(output));
+    process.exit(0);
+  } catch (_e) {
+    // Don't block on errors
+    process.exit(0);
+  }
+}
+
+main();

package/plugins/pbr/scripts/check-dangerous-commands.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Blocks dangerous Bash commands that could destroy
+ * planning state or repository integrity.
+ *
+ * Patterns blocked (exit 2):
+ *   - rm -rf .planning (or any rm that targets .planning/)
+ *   - git reset --hard
+ *   - git push --force / -f to main/master
+ *   - git clean -fd / -fxd (removes untracked files including .planning/)
+ *
+ * Patterns warned (exit 0, additionalContext):
+ *   - Large rm operations (rm -rf on project directories)
+ *   - git checkout -- . (discards all unstaged changes)
+ *
+ * Exit codes:
+ *   0 = not a dangerous command, or a warning-only match
+ *   2 = blocked (destructive command detected)
+ */
+
+const { logHook } = require('./hook-logger');
+
+// Commands that are outright blocked
+const BLOCK_PATTERNS = [
+  {
+    pattern: /\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*r[a-zA-Z]*)\s+.*\.planning\b/,
+    reason: 'rm -rf targeting .planning/ directory — this would destroy all project state.'
+  },
+  {
+    pattern: /\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*r[a-zA-Z]*)\s+.*\.planning[/\\]/,
+    reason: 'rm -rf targeting files inside .planning/ — this would destroy project state.'
+  },
+  {
+    pattern: /\bgit\s+reset\s+--hard\b/,
+    reason: 'git reset --hard discards all uncommitted changes. Use git stash or git checkout for specific files instead.'
+  },
+  {
+    pattern: /\bgit\s+push\s+.*(-f|--force)\b.*\b(main|master)\b/,
+    reason: 'Force-pushing to main/master can destroy shared history. This is almost never what you want.'
+  },
+  {
+    pattern: /\bgit\s+push\s+.*\b(main|master)\b.*(-f|--force)\b/,
+    reason: 'Force-pushing to main/master can destroy shared history. This is almost never what you want.'
+  },
+  {
+    pattern: /\bgit\s+clean\s+(-[a-zA-Z]*f[a-zA-Z]*d|-[a-zA-Z]*d[a-zA-Z]*f)\b/,
+    reason: 'git clean -fd removes untracked files including .planning/ contents. Use specific file paths instead.'
+  }
+];
+
+// Commands that produce warnings but are not blocked
+const WARN_PATTERNS = [
+  {
+    pattern: /\bgit\s+checkout\s+--\s+\.\s*$/,
+    message: 'git checkout -- . discards ALL unstaged changes. Consider targeting specific files.'
+  },
+  {
+    pattern: /\bgit\s+push\s+.*(-f|--force)\b/,
+    message: 'Force-pushing can overwrite remote history. Ensure this is intentional.'
+  }
+];
+
+/**
+ * Check a parsed hook data object for dangerous commands.
+ * Returns { output, exitCode } if the command should be blocked/warned, or null if allowed.
+ * Used by pre-bash-dispatch.js for consolidated hook execution.
+ */
+function checkDangerous(data) {
+  const command = data.tool_input?.command || '';
+
+  // Skip empty commands
+  if (!command.trim()) {
+    return null;
+  }
+
+  // Check block patterns
+  for (const { pattern, reason } of BLOCK_PATTERNS) {
+    if (pattern.test(command)) {
+      logHook('check-dangerous-commands', 'PreToolUse', 'block', {
+        command: command.substring(0, 200),
+        reason
+      });
+      return {
+        output: {
+          decision: 'block',
+          reason: `Dangerous command blocked.\n\n${reason}\n\nCommand: ${command.substring(0, 150)}`
+        },
+        exitCode: 2
+      };
+    }
+  }
+
+  // Check warn patterns
+  for (const { pattern, message } of WARN_PATTERNS) {
+    if (pattern.test(command)) {
+      logHook('check-dangerous-commands', 'PreToolUse', 'warn', {
+        command: command.substring(0, 200),
+        warning: message
+      });
+      return {
+        output: {
+          additionalContext: `Warning: ${message}`
+        },
+        exitCode: 0
+      };
+    }
+  }
+
+  // No match — allow
+  return null;
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      const result = checkDangerous(data);
+      if (result) {
+        process.stdout.write(JSON.stringify(result.output));
+        process.exit(result.exitCode);
+      }
+      process.exit(0);
+    } catch (_e) {
+      // Parse error — don't block
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { BLOCK_PATTERNS, WARN_PATTERNS, checkDangerous };
+if (require.main === module) { main(); }

package/plugins/pbr/scripts/check-doc-sprawl.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse check: Blocks creation of new .md/.txt documentation files
+ * outside a known allowlist, preventing doc sprawl during builds.
+ *
+ * Opt-in via .planning/config.json: { "hooks": { "blockDocSprawl": true } }
+ *
+ * Allowlist:
+ *   - README.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, LICENSE.md, LICENSE, LICENSE.txt
+ *   - Any file under .planning/, .claude/, node_modules/, .git/
+ *   - Any file that already exists (edits to existing docs are always allowed)
+ *
+ * Called by pre-write-dispatch.js — not wired directly in hooks.json.
+ *
+ * Exit codes (when standalone):
+ *   0 = pass (allowed)
+ *   2 = block (not on allowlist)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+const ALLOWED_DOC_BASENAMES = new Set([
+  'readme.md',
+  'claude.md',
+  'contributing.md',
+  'changelog.md',
+  'license.md',
+  'license',
+  'license.txt',
+]);
+
+const ALLOWED_DIR_SEGMENTS = [
+  '.planning',
+  '.claude',
+  'node_modules',
+  '.git',
+];
+
+const DOC_EXTENSIONS = new Set(['.md', '.txt']);
+
+/**
+ * Check if a Write operation would create a disallowed documentation file.
+ * @param {Object} data - Parsed hook input (tool_input, etc.)
+ * @param {string} [cwd] - Working directory override (defaults to process.cwd())
+ * @returns {null|{exitCode: number, output: Object}} null if allowed, block result otherwise
+ */
+function checkDocSprawl(data, cwd) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const ext = path.extname(filePath).toLowerCase();
+  if (!DOC_EXTENSIONS.has(ext)) return null;
+
+  // Only block NEW file creation — existing docs can always be edited
+  if (fs.existsSync(filePath)) return null;
+
+  // Check config — disabled by default
+  const effectiveCwd = cwd || process.cwd();
+  if (!isBlockDocSprawlEnabled(effectiveCwd)) return null;
+
+  // Check basename allowlist
+  const basename = path.basename(filePath).toLowerCase();
+  if (ALLOWED_DOC_BASENAMES.has(basename)) return null;
+
+  // Check if file is in an allowed directory
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const seg of ALLOWED_DIR_SEGMENTS) {
+    if (normalized.includes(`/${seg}/`)) return null;
+  }
+
+  logHook('check-doc-sprawl', 'PreToolUse', 'block', {
+    file: path.basename(filePath),
+    ext
+  });
+
+  return {
+    exitCode: 2,
+    output: {
+      decision: 'block',
+      reason: `[Doc Sprawl] Blocked creation of ${path.basename(filePath)}. ` +
+        'Only known docs (README.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, LICENSE.md) ' +
+        'and .planning/ files are allowed when blockDocSprawl is enabled. ' +
+        'Add content to an existing file instead, or disable hooks.blockDocSprawl in config.'
+    }
+  };
+}
+
+function isBlockDocSprawlEnabled(cwd) {
+  try {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (!fs.existsSync(configPath)) return false;
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return !!config.hooks?.blockDocSprawl;
+  } catch (_e) {
+    return false;
+  }
+}
+
+module.exports = { checkDocSprawl, isBlockDocSprawlEnabled, ALLOWED_DOC_BASENAMES, ALLOWED_DIR_SEGMENTS, DOC_EXTENSIONS };

package/plugins/pbr/scripts/check-phase-boundary.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+// PreToolUse hook (Write|Edit): Warns or blocks when editing files
+// outside the current active phase.
+//
+// Reads STATE.md for current phase number. If the file being written
+// is under .planning/phases/NN-<slug>/ and NN does not match the
+// current phase, issues a warning or blocks depending on config.
+//
+// Config: safety.enforce_phase_boundaries
+//   - true  = block cross-phase writes (exit 2)
+//   - false = warn only (default)
+//   - absent = warn only
+//
+// Files outside .planning/phases/ are always allowed (source code,
+// config files, etc.).
+//
+// Exit codes:
+//   0 = allowed or not applicable
+//   2 = blocked (only when enforce_phase_boundaries is true)
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+
+      if (!filePath) {
+        process.exit(0);
+      }
+
+      const cwd = process.cwd();
+      const planningDir = path.join(cwd, '.planning');
+
+      // Check if the file is under .planning/phases/ using marker matching
+      // instead of absolute path comparison (avoids macOS /var -> /private/var symlink issues)
+      const normalizedPath = filePath.replace(/\\/g, '/');
+      const phasesMarker = '.planning/phases/';
+      const markerIdx = normalizedPath.indexOf(phasesMarker);
+
+      if (markerIdx === -1) {
+        process.exit(0);
+      }
+
+      // Extract phase number from path after the marker
+      // Path pattern: .planning/phases/NN-slug/...
+      const afterMarker = normalizedPath.substring(markerIdx + phasesMarker.length);
+      const phaseMatch = afterMarker.match(/^(\d+)-/);
+      if (!phaseMatch) {
+        process.exit(0);
+      }
+      const filePhase = parseInt(phaseMatch[1], 10);
+
+      // Get current phase from STATE.md
+      const stateFile = path.join(planningDir, 'STATE.md');
+      if (!fs.existsSync(stateFile)) {
+        process.exit(0);
+      }
+
+      const state = fs.readFileSync(stateFile, 'utf8');
+      const currentPhaseMatch = state.match(/Phase:\s*(\d+)\s+of\s+\d+/);
+      if (!currentPhaseMatch) {
+        process.exit(0);
+      }
+      const currentPhase = parseInt(currentPhaseMatch[1], 10);
+
+      // Same phase — always allowed
+      if (filePhase === currentPhase) {
+        process.exit(0);
+      }
+
+      // Cross-phase write detected — check config
+      const enforce = getEnforceSetting(planningDir);
+
+      logHook('check-phase-boundary', 'PreToolUse', enforce ? 'block' : 'warn', {
+        filePhase,
+        currentPhase,
+        file: path.basename(filePath)
+      });
+      logEvent('workflow', 'phase-boundary', {
+        filePhase,
+        currentPhase,
+        file: path.basename(filePath),
+        action: enforce ? 'block' : 'warn'
+      });
+
+      if (enforce) {
+        const output = {
+          decision: 'block',
+          reason: `Cross-phase write blocked: editing phase ${filePhase} file but current phase is ${currentPhase}.\n\nFile: ${filePath}\n\nIf this is intentional, either:\n  1. Update STATE.md to reflect the correct phase\n  2. Set safety.enforce_phase_boundaries: false in config.json`
+        };
+        process.stdout.write(JSON.stringify(output));
+        process.exit(2);
+      } else {
+        const output = {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
+          }
+        };
+        process.stdout.write(JSON.stringify(output));
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.exit(0);
+    }
+  });
+}
+
+function getEnforceSetting(planningDir) {
+  const configFile = path.join(planningDir, 'config.json');
+  if (!fs.existsSync(configFile)) return false;
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    return !!(config.safety && config.safety.enforce_phase_boundaries);
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Core boundary check logic for use by dispatchers.
+ * @param {Object} data - Parsed hook input (tool_input, etc.)
+ * @returns {null|{exitCode: number, output: Object}} null if pass, result otherwise
+ */
+function checkBoundary(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const phasesMarker = '.planning/phases/';
+  const markerIdx = normalizedPath.indexOf(phasesMarker);
+  if (markerIdx === -1) return null;
+
+  const afterMarker = normalizedPath.substring(markerIdx + phasesMarker.length);
+  const phaseMatch = afterMarker.match(/^(\d+)-/);
+  if (!phaseMatch) return null;
+  const filePhase = parseInt(phaseMatch[1], 10);
+
+  const stateFile = path.join(planningDir, 'STATE.md');
+  if (!fs.existsSync(stateFile)) return null;
+
+  const state = fs.readFileSync(stateFile, 'utf8');
+  const currentPhaseMatch = state.match(/Phase:\s*(\d+)\s+of\s+\d+/);
+  if (!currentPhaseMatch) return null;
+  const currentPhase = parseInt(currentPhaseMatch[1], 10);
+
+  if (filePhase === currentPhase) return null;
+
+  const enforce = getEnforceSetting(planningDir);
+
+  logHook('check-phase-boundary', 'PreToolUse', enforce ? 'block' : 'warn', {
+    filePhase, currentPhase, file: path.basename(filePath)
+  });
+  logEvent('workflow', 'phase-boundary', {
+    filePhase, currentPhase, file: path.basename(filePath), action: enforce ? 'block' : 'warn'
+  });
+
+  if (enforce) {
+    return {
+      exitCode: 2,
+      output: {
+        decision: 'block',
+        reason: `Cross-phase write blocked: editing phase ${filePhase} file but current phase is ${currentPhase}.\n\nFile: ${filePath}\n\nIf this is intentional, either:\n  1. Update STATE.md to reflect the correct phase\n  2. Set safety.enforce_phase_boundaries: false in config.json`
+      }
+    };
+  }
+
+  return {
+    exitCode: 0,
+    output: {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
+      }
+    }
+  };
+}
+
+module.exports = { getEnforceSetting, checkBoundary };
+if (require.main === module) { main(); }