@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/scripts/post-write-dispatch.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse dispatcher for Write|Edit hooks.
+ *
+ * Consolidates check-plan-format.js and check-roadmap-sync.js
+ * into a single process, reading stdin once and routing to the
+ * appropriate check based on the file path. This halves the
+ * process spawns per Write/Edit call.
+ *
+ * Routing:
+ *   - PLAN.md or SUMMARY*.md → plan format validation
+ *   - STATE.md → roadmap sync check
+ *   - SUMMARY*.md or VERIFICATION.md in .planning/phases/ → state sync (auto-update tracking files)
+ *   - Other files → exit immediately (no work needed)
+ *
+ * Exit codes:
+ *   0 = always (PostToolUse hooks are advisory)
+ */
+
+const { checkPlanWrite } = require('./check-plan-format');
+const { checkSync } = require('./check-roadmap-sync');
+const { checkStateSync } = require('./check-state-sync');
+
+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);
+
+      // Plan format check (PLAN.md, SUMMARY*.md)
+      // Note: SUMMARY files intentionally trigger BOTH this check AND the state-sync
+      // check below. The plan format check validates frontmatter structure, while
+      // state-sync auto-updates ROADMAP.md and STATE.md tracking fields.
+      const planResult = checkPlanWrite(data);
+      if (planResult) {
+        process.stdout.write(JSON.stringify(planResult.output));
+        process.exit(0);
+      }
+
+      // Roadmap sync check (STATE.md)
+      const syncResult = checkSync(data);
+      if (syncResult) {
+        process.stdout.write(JSON.stringify(syncResult.output));
+        process.exit(0);
+      }
+
+      // State sync check (SUMMARY/VERIFICATION → STATE.md + ROADMAP.md)
+      const stateSyncResult = checkStateSync(data);
+      if (stateSyncResult) {
+        process.stdout.write(JSON.stringify(stateSyncResult.output));
+        process.exit(0);
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on parse errors
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module) { main(); }

package/plugins/pbr/scripts/post-write-quality.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse quality check hook for Write|Edit.
+ *
+ * Runs opt-in code quality checks on modified JS/TS files:
+ *   1. autoFormat:        Run Prettier on the file (requires local installation)
+ *   2. typeCheck:         Run tsc --noEmit filtered to the edited file (requires local typescript)
+ *   3. detectConsoleLogs: Warn about console.log statements left in the file
+ *
+ * All checks disabled by default. Enable via .planning/config.json:
+ *   { "hooks": { "autoFormat": true, "typeCheck": true, "detectConsoleLogs": true } }
+ *
+ * Only processes JS/TS files (.js, .jsx, .ts, .tsx, .mjs, .cjs).
+ * Silently skips if tools (prettier, tsc) are not installed in the project.
+ *
+ * Exit codes:
+ *   0 = always (PostToolUse hook, advisory only)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { logHook } = require('./hook-logger');
+
+const JS_TS_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+const TS_EXTENSIONS = new Set(['.ts', '.tsx']);
+
+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 = checkQuality(data);
+      if (result) {
+        process.stdout.write(JSON.stringify(result.output));
+      }
+      process.exit(0);
+    } catch (_e) {
+      process.exit(0);
+    }
+  });
+}
+
+/**
+ * Core quality check logic for use by dispatchers or standalone.
+ * @param {Object} data - Parsed hook input (tool_input, etc.)
+ * @returns {null|{output: Object}} null if no checks fired, result otherwise
+ */
+function checkQuality(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const ext = path.extname(filePath).toLowerCase();
+  if (!JS_TS_EXTENSIONS.has(ext)) return null;
+
+  const cwd = process.cwd();
+  const config = loadHooksConfig(cwd);
+
+  // No quality hooks enabled — early exit
+  if (!config.autoFormat && !config.typeCheck && !config.detectConsoleLogs) return null;
+
+  const messages = [];
+
+  // 1. Auto-format with Prettier
+  if (config.autoFormat) {
+    const msg = runPrettier(filePath, cwd);
+    if (msg) messages.push(msg);
+  }
+
+  // 2. TypeScript type-check (only for .ts/.tsx)
+  if (config.typeCheck && TS_EXTENSIONS.has(ext)) {
+    const msg = runTypeCheck(filePath, cwd);
+    if (msg) messages.push(msg);
+  }
+
+  // 3. Console.log detection
+  if (config.detectConsoleLogs) {
+    const msg = detectConsoleLogs(filePath);
+    if (msg) messages.push(msg);
+  }
+
+  if (messages.length === 0) return null;
+
+  logHook('post-write-quality', 'PostToolUse', 'quality-check', {
+    file: path.basename(filePath),
+    checks: messages.length
+  });
+
+  return {
+    output: {
+      additionalContext: messages.join('\n')
+    }
+  };
+}
+
+/**
+ * Load the hooks section from .planning/config.json.
+ * Returns {} if not found or not configured.
+ */
+function loadHooksConfig(cwd) {
+  const configPath = path.join(cwd, '.planning', 'config.json');
+  if (!fs.existsSync(configPath)) return {};
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return config.hooks || {};
+  } catch (_e) {
+    return {};
+  }
+}
+
+/**
+ * Find a locally installed binary in node_modules/.bin/.
+ * Returns the full path or null if not found.
+ */
+function findLocalBin(cwd, name) {
+  const candidates = process.platform === 'win32'
+    ? [path.join(cwd, 'node_modules', '.bin', name + '.cmd'),
+      path.join(cwd, 'node_modules', '.bin', name)]
+    : [path.join(cwd, 'node_modules', '.bin', name)];
+  return candidates.find(c => fs.existsSync(c)) || null;
+}
+
+/**
+ * Run Prettier on the file. Returns a message string or null.
+ */
+function runPrettier(filePath, cwd) {
+  const bin = findLocalBin(cwd, 'prettier');
+  if (!bin) return null;
+
+  try {
+    execSync(`"${bin}" --write "${filePath}"`, {
+      cwd,
+      timeout: 15000,
+      stdio: 'pipe',
+    });
+    return `[Auto-format] Prettier reformatted ${path.basename(filePath)}. File on disk may differ from context — re-read before further edits.`;
+  } catch (_e) {
+    // Prettier failed (syntax error, unsupported file, etc.) — skip
+    return null;
+  }
+}
+
+/**
+ * Run tsc --noEmit and filter to errors in the modified file.
+ * Returns a message string or null.
+ */
+function runTypeCheck(filePath, cwd) {
+  const bin = findLocalBin(cwd, 'tsc');
+  if (!bin) return null;
+  if (!fs.existsSync(path.join(cwd, 'tsconfig.json'))) return null;
+
+  try {
+    execSync(`"${bin}" --noEmit`, {
+      cwd,
+      timeout: 30000,
+      stdio: 'pipe',
+      encoding: 'utf8',
+    });
+    return null; // Clean pass — no errors
+  } catch (e) {
+    const output = (e.stdout || '').toString();
+    const basename = path.basename(filePath);
+    const relevantLines = output.split('\n')
+      .filter(line => line.includes(basename) && /error TS\d+/.test(line));
+
+    if (relevantLines.length === 0) return null;
+    const detail = relevantLines.slice(0, 3).join('\n  ');
+    const extra = relevantLines.length > 3 ? `\n  ...and ${relevantLines.length - 3} more` : '';
+    return `[Type Check] ${relevantLines.length} error(s) in ${basename}:\n  ${detail}${extra}`;
+  }
+}
+
+/**
+ * Scan file for console.log statements. Returns a message string or null.
+ */
+function detectConsoleLogs(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    const matches = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (/^\s*\/\//.test(line)) continue; // skip single-line comments
+      if (/\bconsole\.log\s*\(/.test(line)) {
+        matches.push({ line: i + 1, text: line.trim().substring(0, 80) });
+      }
+    }
+
+    if (matches.length === 0) return null;
+
+    const detail = matches.slice(0, 3).map(m => `  L${m.line}: ${m.text}`).join('\n');
+    const extra = matches.length > 3 ? `\n  ...and ${matches.length - 3} more` : '';
+    return `[Console.log] ${matches.length} console.log(s) in ${path.basename(filePath)}:\n${detail}${extra}`;
+  } catch (_e) {
+    return null;
+  }
+}
+
+module.exports = { checkQuality, loadHooksConfig, findLocalBin, runPrettier, runTypeCheck, detectConsoleLogs };
+if (require.main === module) { main(); }

package/plugins/pbr/scripts/pre-bash-dispatch.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse dispatcher for Bash hooks.
+ *
+ * Consolidates check-dangerous-commands.js and validate-commit.js
+ * into a single process, reading stdin once and routing to both
+ * checks sequentially. This halves the process spawns per Bash call.
+ *
+ * Check order:
+ *   1. Dangerous commands check (can block destructive operations)
+ *   2. Commit validation (can block badly-formatted commits)
+ *
+ * Exit codes:
+ *   0 = allowed or warning only
+ *   2 = blocked (dangerous command or invalid commit format)
+ */
+
+const { logHook } = require('./hook-logger');
+const { checkDangerous } = require('./check-dangerous-commands');
+const { checkCommit } = require('./validate-commit');
+
+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);
+
+      // Dangerous commands check first — can block
+      const dangerousResult = checkDangerous(data);
+      if (dangerousResult) {
+        logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'check-dangerous-commands' });
+        process.stdout.write(JSON.stringify(dangerousResult.output));
+        process.exit(dangerousResult.exitCode);
+      }
+
+      // Commit validation check — can block
+      const commitResult = checkCommit(data);
+      if (commitResult) {
+        logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'validate-commit' });
+        process.stdout.write(JSON.stringify(commitResult.output));
+        process.exit(commitResult.exitCode);
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module) { main(); }

package/plugins/pbr/scripts/pre-write-dispatch.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse dispatcher for Write|Edit hooks.
+ *
+ * Consolidates check-skill-workflow.js, check-phase-boundary.js,
+ * and check-doc-sprawl.js into a single process, reading stdin once
+ * and running all checks sequentially.
+ *
+ * Check order matters: skill workflow runs first (can block writes
+ * that violate planning rules), then phase boundary (can block or
+ * warn about cross-phase writes), then doc sprawl (blocks new .md/.txt
+ * files outside the allowlist when enabled).
+ *
+ * Exit codes:
+ *   0 = allowed or warning only
+ *   2 = blocked (workflow violation or phase boundary enforcement)
+ */
+
+const { checkWorkflow } = require('./check-skill-workflow');
+const { checkBoundary } = require('./check-phase-boundary');
+const { checkDocSprawl } = require('./check-doc-sprawl');
+
+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);
+
+      // Skill workflow check first — can block
+      const workflowResult = checkWorkflow(data);
+      if (workflowResult) {
+        process.stdout.write(JSON.stringify(workflowResult.output));
+        process.exit(workflowResult.exitCode || 0);
+      }
+
+      // Phase boundary check — can block or warn
+      const boundaryResult = checkBoundary(data);
+      if (boundaryResult) {
+        process.stdout.write(JSON.stringify(boundaryResult.output));
+        process.exit(boundaryResult.exitCode || 0);
+      }
+
+      // Doc sprawl check — blocks new .md/.txt outside allowlist
+      const sprawlResult = checkDocSprawl(data);
+      if (sprawlResult) {
+        process.stdout.write(JSON.stringify(sprawlResult.output));
+        process.exit(sprawlResult.exitCode || 0);
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module) { main(); }

package/plugins/pbr/scripts/progress-tracker.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart hook: Auto-detects .planning/ directory and injects
+ * project state as additionalContext.
+ *
+ * If no .planning/ directory exists, exits silently (non-Plan-Build-Run project).
+ * If STATE.md exists, reads and outputs a concise summary.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+const { configLoad } = require('./pbr-tools');
+
+function main() {
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const stateFile = path.join(planningDir, 'STATE.md');
+
+  // Not a Plan-Build-Run project
+  if (!fs.existsSync(planningDir)) {
+    process.exit(0);
+  }
+
+  // Reset compaction counter for new session
+  const { resetCounter } = require('./suggest-compact');
+  resetCounter(planningDir);
+
+  const context = buildContext(planningDir, stateFile);
+
+  if (context) {
+    const output = {
+      additionalContext: context
+    };
+    process.stdout.write(JSON.stringify(output));
+    logHook('progress-tracker', 'SessionStart', 'injected', { hasState: true });
+    logEvent('workflow', 'session-start', { hasState: true });
+  } else {
+    logHook('progress-tracker', 'SessionStart', 'skipped', { hasState: false });
+    logEvent('workflow', 'session-start', { hasState: false });
+  }
+
+  process.exit(0);
+}
+
+function buildContext(planningDir, stateFile) {
+  const parts = [];
+
+  parts.push('[Plan-Build-Run Project Detected]');
+
+  // Git context
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8', timeout: 3000 }).trim();
+    const porcelain = execSync('git status --porcelain', { encoding: 'utf8', timeout: 3000 }).trim();
+    const uncommitted = porcelain ? porcelain.split('\n').length : 0;
+    const recentCommits = execSync('git log -5 --oneline', { encoding: 'utf8', timeout: 3000 }).trim();
+    parts.push(`\nGit: ${branch} (${uncommitted} uncommitted file${uncommitted !== 1 ? 's' : ''})`);
+    if (recentCommits) {
+      parts.push(`Recent commits:\n${recentCommits}`);
+    }
+  } catch (_e) {
+    // Not a git repo or git not available — skip
+  }
+
+  // Read STATE.md if it exists
+  if (fs.existsSync(stateFile)) {
+    const state = fs.readFileSync(stateFile, 'utf8');
+
+    // Extract key sections
+    const position = extractSection(state, 'Current Position');
+    if (position) {
+      parts.push(`\nPosition:\n${position}`);
+    }
+
+    const blockers = extractSection(state, 'Blockers/Concerns');
+    if (blockers && !blockers.includes('None')) {
+      parts.push(`\nBlockers:\n${blockers}`);
+    }
+
+    const continuity = extractSection(state, 'Session Continuity');
+    if (continuity) {
+      parts.push(`\nLast Session:\n${continuity}`);
+    }
+  } else {
+    parts.push('\nNo STATE.md found. Run /pbr:begin to initialize or /pbr:status to check.');
+  }
+
+  // Check for .continue-here.md files
+  const phasesDir = path.join(planningDir, 'phases');
+  if (fs.existsSync(phasesDir)) {
+    const continueFiles = findContinueFiles(phasesDir);
+    if (continueFiles.length > 0) {
+      parts.push(`\nPaused work found: ${continueFiles.join(', ')}`);
+      parts.push('Run /pbr:resume to pick up where you left off.');
+    }
+  }
+
+  // Check for config and validate
+  const config = configLoad(planningDir);
+  if (config) {
+    parts.push(`\nConfig: depth=${config.depth || 'standard'}, mode=${config.mode || 'interactive'}`);
+
+    // Validate config against schema (reuse already-loaded config)
+    const schemaPath = path.join(__dirname, 'config-schema.json');
+    if (fs.existsSync(schemaPath)) {
+      const { configValidate } = require('./pbr-tools');
+      const validation = configValidate(config);
+      if (validation.warnings.length > 0) {
+        parts.push(`\nConfig warnings: ${validation.warnings.join('; ')}`);
+      }
+      if (validation.errors.length > 0) {
+        parts.push(`\nConfig errors: ${validation.errors.join('; ')}`);
+      }
+    }
+  }
+
+  // Check for quick notes
+  const projectNotesFile = path.join(planningDir, 'NOTES.md');
+  const globalNotesFile = path.join(os.homedir(), '.claude', 'notes.md');
+  const projectNoteCount = countNotes(projectNotesFile);
+  const globalNoteCount = countNotes(globalNotesFile);
+  if (projectNoteCount > 0 || globalNoteCount > 0) {
+    const noteParts = [];
+    if (projectNoteCount > 0) noteParts.push(`${projectNoteCount} project`);
+    if (globalNoteCount > 0) noteParts.push(`${globalNoteCount} global`);
+    parts.push(`\nNotes: ${noteParts.join(', ')}. \`/pbr:note list\` to review.`);
+  }
+
+  // Check ROADMAP/STATE sync (S>M-2)
+  const roadmapFile = path.join(planningDir, 'ROADMAP.md');
+  if (fs.existsSync(stateFile) && fs.existsSync(roadmapFile)) {
+    try {
+      const roadmap = fs.readFileSync(roadmapFile, 'utf8');
+      const state = fs.readFileSync(stateFile, 'utf8');
+
+      // Extract current phase from STATE.md
+      const phaseMatch = state.match(/Phase:\s*(\d+)\s+of\s+\d+/);
+      if (phaseMatch) {
+        const currentPhase = parseInt(phaseMatch[1], 10);
+        // Check if ROADMAP shows this phase as already verified/complete
+        const progressTable = roadmap.match(/## Progress[\s\S]*?\|[\s\S]*?(?=\n##|\s*$)/);
+        if (progressTable) {
+          const rows = progressTable[0].split('\n').filter(r => r.includes('|'));
+          for (const row of rows) {
+            const cols = row.split('|').map(c => c.trim()).filter(Boolean);
+            if (cols.length >= 4) {
+              const phaseNum = parseInt(cols[0], 10);
+              const status = cols[3] ? cols[3].toLowerCase() : '';
+              if (phaseNum === currentPhase && (status === 'verified' || status === 'complete')) {
+                parts.push(`\nWarning: STATE.md may be outdated — ROADMAP.md shows phase ${currentPhase} as ${status}.`);
+              }
+            }
+          }
+        }
+      }
+    } catch (_e) {
+      // Ignore parse errors
+    }
+  }
+
+  // Check for stale .auto-next signal (S>M-9)
+  const autoNextFile = path.join(planningDir, '.auto-next');
+  if (fs.existsSync(autoNextFile)) {
+    try {
+      const stats = fs.statSync(autoNextFile);
+      const ageMs = Date.now() - stats.mtimeMs;
+      const ageMinutes = Math.floor(ageMs / 60000);
+      if (ageMinutes > 10) {
+        parts.push(`\nWarning: Stale .auto-next signal found (${ageMinutes} minutes old). This may trigger an unexpected command. Consider deleting .planning/.auto-next.`);
+        logHook('progress-tracker', 'SessionStart', 'stale-auto-next', { ageMinutes });
+      }
+    } catch (_e) {
+      // Ignore errors
+    }
+  }
+
+  parts.push('\nAvailable commands: /pbr:status, /pbr:plan, /pbr:build, /pbr:review, /pbr:help');
+
+  return parts.join('\n');
+}
+
+function extractSection(content, heading) {
+  const regex = new RegExp(`##\\s+${escapeRegex(heading)}\\s*\\n([\\s\\S]*?)(?=\\n##\\s|$)`);
+  const match = content.match(regex);
+  if (!match) return null;
+  const section = match[1].trim();
+  // Return first 5 lines max
+  return section.split('\n').slice(0, 5).join('\n');
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function findContinueFiles(dir) {
+  const results = [];
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...findContinueFiles(fullPath));
+      } else if (entry.name.includes('.continue-here')) {
+        results.push(path.relative(dir, fullPath));
+      }
+    }
+  } catch (_e) {
+    // Ignore permission errors
+  }
+  return results;
+}
+
+function countNotes(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return 0;
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    return lines.filter(l => /^- \[/.test(l) && !l.includes('[promoted]')).length;
+  } catch (_e) {
+    return 0;
+  }
+}
+
+main();