@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/dist/check-cross-plugin-sync.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Bash hook: Advisory warning when committing pbr skill/agent
+ * changes without corresponding cursor-pbr/copilot-pbr counterparts.
+ *
+ * Only fires on `git commit` commands. Scripts directory is excluded
+ * because cursor-pbr and copilot-pbr share scripts via ../pbr/scripts/.
+ *
+ * Exit codes:
+ *   0 = always (advisory only, never blocks)
+ */
+
+const { execSync } = require('child_process');
+const { logHook } = require('./hook-logger');
+
+/**
+ * Check if a git commit has cross-plugin sync drift.
+ * @param {Object} data - Parsed hook input
+ * @returns {null|{additionalContext: string}} null if clean, advisory if drift
+ */
+function checkCrossPluginSync(data) {
+  const command = data.tool_input?.command || '';
+
+  // Only check git commit commands
+  if (!/\bgit\s+commit\b/.test(command)) {
+    return null;
+  }
+
+  let stagedFiles;
+  try {
+    stagedFiles = execSync('git diff --cached --name-only', { encoding: 'utf8' }).trim().split('\n').filter(Boolean);
+  } catch (_e) {
+    return null;
+  }
+
+  // Find pbr skill/agent files (not scripts — those are shared)
+  const pbrSyncFiles = stagedFiles.filter(f =>
+    /^plugins\/pbr\/(skills|agents)\//.test(f)
+  );
+
+  if (pbrSyncFiles.length === 0) {
+    return null;
+  }
+
+  // Check for missing counterparts
+  const missingCounterparts = [];
+  for (const pbrFile of pbrSyncFiles) {
+    const relativePath = pbrFile.replace(/^plugins\/pbr\//, '');
+    const cursorPath = `plugins/cursor-pbr/${relativePath}`;
+    const copilotPath = `plugins/copilot-pbr/${relativePath}`;
+
+    const hasCursor = stagedFiles.some(f => f === cursorPath);
+    const hasCopilot = stagedFiles.some(f => f === copilotPath);
+
+    if (!hasCursor || !hasCopilot) {
+      const missing = [];
+      if (!hasCursor) missing.push('cursor-pbr');
+      if (!hasCopilot) missing.push('copilot-pbr');
+      missingCounterparts.push(`${pbrFile} (missing: ${missing.join(', ')})`);
+    }
+  }
+
+  if (missingCounterparts.length === 0) {
+    return null;
+  }
+
+  const msg = `[Advisory] Cross-plugin sync required. These pbr files were changed without matching cursor-pbr/copilot-pbr updates:\n${missingCounterparts.map(f => `  - ${f}`).join('\n')}\nTo fix: copy each changed file to the matching path in plugins/cursor-pbr/ and plugins/copilot-pbr/, applying plugin-specific adjustments. Run: npm test -- tests/cross-plugin-compat.test.js to verify.`;
+  logHook('check-cross-plugin-sync', 'PreToolUse', 'warn', { missingCounterparts });
+
+  return { additionalContext: msg };
+}
+
+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 = checkCrossPluginSync(data);
+      if (result) {
+        process.stdout.write(JSON.stringify(result));
+      }
+    } catch (_e) {
+      // Don't block on errors
+    }
+    process.exit(0);
+  });
+}
+
+module.exports = { checkCrossPluginSync };
+if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -0,0 +1,193 @@
+#!/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 fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { resolveSessionPath } = require('./lib/core');
+
+// 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.'
+  },
+  {
+    pattern: /\bgit\s+stash\b(?!\s+show)(?!\s+list)/,
+    message: 'git stash may capture .planning/ files if they were previously tracked. After stash pop, verify .planning/STATE.md and ROADMAP.md are current. Run: node plugins/pbr/scripts/pbr-tools.js state reconcile'
+  },
+  {
+    pattern: /\bgit\s+checkout\s+(?!-b\b)(?!--orphan\b)[^\s-]/,
+    message: 'git checkout to a branch/commit may overwrite .planning/ files if they were previously tracked. After checkout, verify .planning/STATE.md and ROADMAP.md are current. Run: node plugins/pbr/scripts/pbr-tools.js state reconcile'
+  }
+];
+
+/**
+ * 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} Command: ${command.substring(0, 150)}\n\nUse a safer alternative or ask the user for explicit confirmation before running destructive commands.`
+        },
+        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
+      };
+    }
+  }
+
+  // Skill-specific checks
+  const sessionId = data.session_id || null;
+  const skillResult = checkSkillSpecificBash(command, sessionId);
+  if (skillResult) return skillResult;
+
+  // No match — allow
+  return null;
+}
+
+/**
+ * Skill-specific bash command checks.
+ * Currently: statusline skill cannot use sed/awk/perl on JSON files.
+ */
+function checkSkillSpecificBash(command, sessionId) {
+  const planningDir = path.join(process.cwd(), '.planning');
+  const skillFile = sessionId
+    ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+    : path.join(planningDir, '.active-skill');
+
+  let activeSkill = null;
+  try {
+    activeSkill = fs.readFileSync(skillFile, 'utf8').trim();
+  } catch (_e) {
+    return null;
+  }
+
+  if (activeSkill !== 'statusline') return null;
+
+  // Block sed/awk/perl targeting .json files
+  const jsonManipPattern = /\b(sed|awk|perl)\b.*\.json/;
+  const echoRedirectPattern = /echo\s.*>\s*.*\.json/;
+
+  if (jsonManipPattern.test(command) || echoRedirectPattern.test(command)) {
+    logHook('check-dangerous-commands', 'PreToolUse', 'block', {
+      command: command.substring(0, 200),
+      reason: 'JSON shell manipulation during statusline'
+    });
+    return {
+      output: {
+        decision: 'block',
+        reason: 'JSON shell manipulation blocked.\n\nShell tools like sed, awk, and perl can corrupt JSON structure. The statusline skill must use structured tools for JSON editing.\n\nUse the Read and Write tools to modify JSON files instead of shell text manipulation.'
+      },
+      exitCode: 2
+    };
+  }
+
+  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.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] check-dangerous-commands failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { BLOCK_PATTERNS, WARN_PATTERNS, checkDangerous };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/dist/check-direct-state-write.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse advisory hook: warns when STATE.md or ROADMAP.md is written
+ * directly via the Write/Edit tool, bypassing lockedFileUpdate() locking.
+ * Advisory only — cannot block (PostToolUse limitation).
+ */
+
+/**
+ * Detect direct writes to STATE.md or ROADMAP.md and return an advisory warning.
+ *
+ * @param {Object} data - Parsed hook input from PostToolUse
+ * @returns {null|{output: {additionalContext: string}}}
+ */
+function checkDirectStateWrite(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const normalized = filePath.replace(/\\/g, '/');
+
+  const isStateMd = normalized.endsWith('.planning/STATE.md');
+  const isRoadmapMd = normalized.endsWith('.planning/ROADMAP.md');
+  if (!isStateMd && !isRoadmapMd) return null;
+
+  const file = isStateMd ? 'STATE.md' : 'ROADMAP.md';
+  const cliHint = isStateMd
+    ? 'Use: node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update <field> <value>'
+    : 'Use: node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-status <phase> <status>';
+
+  return {
+    output: {
+      additionalContext: `[DirectWrite Warning] Direct Write to ${file} bypasses lockedFileUpdate() and is unsafe in multi-session environments. ${cliHint} for atomic, lock-protected mutations.`
+    }
+  };
+}
+
+module.exports = { checkDirectStateWrite };

package/plugins/pbr/dist/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/dist/check-phase-boundary.js

@@ -0,0 +1,191 @@
+#!/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 = {
+          additionalContext: `[Advisory] Cross-phase edit: modifying phase ${filePhase} file while current phase is ${currentPhase}. If unintentional: check STATE.md to confirm correct phase. If intentional (e.g. backfilling docs): no action needed. To suppress: set safety.enforce_phase_boundaries: false in config.json.`
+        };
+        process.stdout.write(JSON.stringify(output));
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] check-phase-boundary failed: ' + _e.message }));
+      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: {
+      additionalContext: `[Advisory] Cross-phase edit: modifying phase ${filePhase} file while current phase is ${currentPhase}. If unintentional: check STATE.md to confirm correct phase. If intentional (e.g. backfilling docs): no action needed. To suppress: set safety.enforce_phase_boundaries: false in config.json.`
+    }
+  };
+}
+
+module.exports = { getEnforceSetting, checkBoundary };
+if (require.main === module || process.argv[1] === __filename) { main(); }