@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/scripts/check-plan-format.js

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook: Validates PLAN.md and SUMMARY.md structure.
+ *
+ * PLAN.md checks:
+ * - Each task has <name>, <files>, <action>, <verify>, <done> elements
+ * - Max 3 tasks per plan
+ * - Has YAML frontmatter with required fields (phase, plan, wave, must_haves)
+ *
+ * SUMMARY.md checks:
+ * - Has YAML frontmatter with required fields (phase, plan, status, provides, requires, key_files)
+ * - key_files paths exist on disk
+ * - Warns if no deferred field in frontmatter
+ *
+ * Returns decision: "block" for structural errors (forces Claude to fix and retry).
+ * Returns message for non-blocking warnings.
+ *
+ * Exit codes:
+ *   0 = always (PostToolUse hook, never blocks via exit code)
+ */
+
+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);
+
+      // Get the file path that was written/edited
+      const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+
+      // Determine file type
+      const basename = path.basename(filePath);
+      const isPlan = basename.endsWith('PLAN.md');
+      const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
+
+      if (!isPlan && !isSummary) {
+        process.exit(0);
+      }
+
+      if (!fs.existsSync(filePath)) {
+        process.exit(0);
+      }
+
+      const content = fs.readFileSync(filePath, 'utf8');
+      const result = isPlan
+        ? validatePlan(content, filePath)
+        : validateSummary(content, filePath);
+
+      const eventType = isPlan ? 'plan-validated' : 'summary-validated';
+
+      if (result.errors.length > 0) {
+        // Structural errors — block and force correction
+        logHook('check-plan-format', 'PostToolUse', 'block', {
+          file: basename,
+          errors: result.errors
+        });
+        logEvent('workflow', eventType, {
+          file: basename,
+          status: 'block',
+          errorCount: result.errors.length
+        });
+
+        const parts = [`${basename} has structural errors that must be fixed:`];
+        parts.push(...result.errors.map(i => `  - ${i}`));
+
+        if (result.warnings.length > 0) {
+          parts.push('');
+          parts.push('Warnings (non-blocking):');
+          parts.push(...result.warnings.map(i => `  - ${i}`));
+        }
+
+        const output = {
+          decision: 'block',
+          reason: parts.join('\n')
+        };
+        process.stdout.write(JSON.stringify(output));
+      } else if (result.warnings.length > 0) {
+        // Warnings only — non-blocking feedback
+        logHook('check-plan-format', 'PostToolUse', 'warn', {
+          file: basename,
+          warnings: result.warnings
+        });
+        logEvent('workflow', eventType, {
+          file: basename,
+          status: 'warn',
+          warningCount: result.warnings.length
+        });
+
+        const output = {
+          message: `${basename} warnings:\n${result.warnings.map(i => `  - ${i}`).join('\n')}`
+        };
+        process.stdout.write(JSON.stringify(output));
+      } else {
+        // Clean pass
+        logHook('check-plan-format', 'PostToolUse', 'pass', { file: basename });
+        logEvent('workflow', eventType, { file: basename, status: 'pass' });
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on parse errors
+      process.exit(0);
+    }
+  });
+}
+
+function validatePlan(content, _filePath) {
+  const errors = [];
+  const warnings = [];
+
+  // Check frontmatter
+  if (!content.startsWith('---')) {
+    errors.push('Missing YAML frontmatter');
+  } else {
+    const frontmatterEnd = content.indexOf('---', 3);
+    if (frontmatterEnd === -1) {
+      errors.push('Unclosed YAML frontmatter');
+    } else {
+      const frontmatter = content.substring(3, frontmatterEnd);
+      const requiredFields = ['phase', 'plan', 'wave'];
+      for (const field of requiredFields) {
+        if (!frontmatter.includes(`${field}:`)) {
+          errors.push(`Frontmatter missing "${field}" field`);
+        }
+      }
+      if (!frontmatter.includes('must_haves:')) {
+        errors.push('Frontmatter missing "must_haves" field (truths/artifacts/key_links required)');
+      }
+    }
+  }
+
+  // Count tasks
+  const taskMatches = content.match(/<task\b[^>]*>/g) || [];
+  const taskCount = taskMatches.length;
+
+  if (taskCount === 0) {
+    errors.push('No <task> elements found');
+  } else if (taskCount > 3) {
+    errors.push(`Too many tasks: ${taskCount} (max 3 per plan)`);
+  }
+
+  // Check each task has required elements
+  const taskTags = content.match(/<task\b[^>]*>/g) || [];
+  const taskBlocks = content.split(/<task\b[^>]*>/).slice(1);
+  const requiredElements = ['name', 'files', 'action', 'verify', 'done'];
+
+  taskBlocks.forEach((block, index) => {
+    const taskEnd = block.indexOf('</task>');
+    const taskContent = taskEnd !== -1 ? block.substring(0, taskEnd) : block;
+
+    // Skip checkpoint tasks - they have different required elements
+    const taskTag = taskTags[index] || '';
+    if (taskTag.includes('checkpoint')) {
+      return; // Checkpoint tasks have different structure
+    }
+
+    for (const elem of requiredElements) {
+      if (!taskContent.includes(`<${elem}>`) && !taskContent.includes(`<${elem} `)) {
+        errors.push(`Task ${index + 1}: missing <${elem}> element`);
+      }
+    }
+  });
+
+  return { errors, warnings };
+}
+
+function validateSummary(content, _filePath) {
+  const errors = [];
+  const warnings = [];
+
+  // Check frontmatter
+  if (!content.startsWith('---')) {
+    errors.push('Missing YAML frontmatter');
+  } else {
+    const frontmatterEnd = content.indexOf('---', 3);
+    if (frontmatterEnd === -1) {
+      errors.push('Unclosed YAML frontmatter');
+    } else {
+      const frontmatter = content.substring(3, frontmatterEnd);
+
+      // Required fields — structural errors
+      const requiredFields = ['phase', 'plan', 'status', 'provides', 'requires', 'key_files'];
+      for (const field of requiredFields) {
+        if (!frontmatter.includes(`${field}:`)) {
+          errors.push(`Frontmatter missing "${field}" field`);
+        }
+      }
+
+      // Optional but encouraged — warnings
+      if (!frontmatter.includes('deferred:')) {
+        warnings.push('Frontmatter missing "deferred" field (forces executor to consciously record scope creep)');
+      }
+
+      // Validate key_files paths exist on disk — warning only (files may not exist yet during planning)
+      const keyFilesMatch = frontmatter.match(/key_files:\s*\n((?:\s+-\s+.*\n?)*)/);
+      if (keyFilesMatch) {
+        const lines = keyFilesMatch[1].split('\n').filter(l => l.trim().startsWith('-'));
+        for (const line of lines) {
+          // Parse "- path: description" or "- path" format
+          const entryMatch = line.match(/^\s*-\s+"?([^":]+?)(?::.*)?"?\s*$/);
+          if (entryMatch) {
+            const filePortion = entryMatch[1].trim();
+            if (filePortion && !fs.existsSync(filePortion)) {
+              warnings.push(`key_files path not found on disk: ${filePortion}`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Core plan/summary check logic for use by dispatchers.
+ * @param {Object} data - Parsed hook input (tool_input, etc.)
+ * @returns {null|{output: Object}} null if pass or not applicable, result otherwise
+ */
+function checkPlanWrite(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  const basename = path.basename(filePath);
+  const isPlan = basename.endsWith('PLAN.md');
+  const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
+
+  if (!isPlan && !isSummary) return null;
+  if (!fs.existsSync(filePath)) return null;
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const result = isPlan
+    ? validatePlan(content, filePath)
+    : validateSummary(content, filePath);
+
+  const eventType = isPlan ? 'plan-validated' : 'summary-validated';
+
+  if (result.errors.length > 0) {
+    logHook('check-plan-format', 'PostToolUse', 'block', { file: basename, errors: result.errors });
+    logEvent('workflow', eventType, { file: basename, status: 'block', errorCount: result.errors.length });
+
+    const parts = [`${basename} has structural errors that must be fixed:`];
+    parts.push(...result.errors.map(i => `  - ${i}`));
+    if (result.warnings.length > 0) {
+      parts.push('', 'Warnings (non-blocking):');
+      parts.push(...result.warnings.map(i => `  - ${i}`));
+    }
+    return { output: { decision: 'block', reason: parts.join('\n') } };
+  }
+
+  if (result.warnings.length > 0) {
+    logHook('check-plan-format', 'PostToolUse', 'warn', { file: basename, warnings: result.warnings });
+    logEvent('workflow', eventType, { file: basename, status: 'warn', warningCount: result.warnings.length });
+    return { output: { message: `${basename} warnings:\n${result.warnings.map(i => `  - ${i}`).join('\n')}` } };
+  }
+
+  logHook('check-plan-format', 'PostToolUse', 'pass', { file: basename });
+  logEvent('workflow', eventType, { file: basename, status: 'pass' });
+  return null;
+}
+
+module.exports = { validatePlan, validateSummary, checkPlanWrite };
+if (require.main === module) { main(); }

package/plugins/pbr/scripts/check-roadmap-sync.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook (async): Checks that ROADMAP.md phase status
+ * stays in sync with STATE.md after state updates.
+ *
+ * When STATE.md is written/edited and contains a phase status
+ * (planned, built, partial, verified), this hook checks if the
+ * ROADMAP.md Phase Overview table has a matching status for that
+ * phase. If not, it warns Claude to update ROADMAP.md.
+ *
+ * Runs asynchronously (non-blocking). Issues are reported but
+ * don't prevent saving.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+
+const LIFECYCLE_STATUSES = ['planned', 'built', 'partial', 'verified'];
+
+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 || '';
+
+      if (!filePath.endsWith('STATE.md')) {
+        process.exit(0);
+      }
+
+      const cwd = process.cwd();
+      const planningDir = path.join(cwd, '.planning');
+      const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+
+      if (!fs.existsSync(filePath) || !fs.existsSync(roadmapPath)) {
+        process.exit(0);
+      }
+
+      const stateContent = fs.readFileSync(filePath, 'utf8');
+      const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+
+      const stateInfo = parseState(stateContent);
+      if (!stateInfo || !stateInfo.phase || !stateInfo.status) {
+        logHook('check-roadmap-sync', 'PostToolUse', 'skip', { reason: 'could not parse STATE.md' });
+        process.exit(0);
+      }
+
+      if (!LIFECYCLE_STATUSES.includes(stateInfo.status)) {
+        logHook('check-roadmap-sync', 'PostToolUse', 'skip', {
+          reason: `status "${stateInfo.status}" not a lifecycle status`
+        });
+        process.exit(0);
+      }
+
+      const roadmapStatus = getRoadmapPhaseStatus(roadmapContent, stateInfo.phase);
+      if (!roadmapStatus) {
+        logHook('check-roadmap-sync', 'PostToolUse', 'skip', {
+          reason: `phase ${stateInfo.phase} not found in ROADMAP.md table`
+        });
+        process.exit(0);
+      }
+
+      if (roadmapStatus.toLowerCase() !== stateInfo.status) {
+        logHook('check-roadmap-sync', 'PostToolUse', 'warn', {
+          phase: stateInfo.phase,
+          stateStatus: stateInfo.status,
+          roadmapStatus: roadmapStatus
+        });
+        logEvent('workflow', 'roadmap-sync', {
+          phase: stateInfo.phase,
+          stateStatus: stateInfo.status,
+          roadmapStatus: roadmapStatus,
+          status: 'out-of-sync'
+        });
+
+        const output = {
+          message: `ROADMAP.md out of sync: Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the Phase Overview table in ROADMAP.md to match.`
+        };
+        process.stdout.write(JSON.stringify(output));
+      } else {
+        logHook('check-roadmap-sync', 'PostToolUse', 'pass', {
+          phase: stateInfo.phase,
+          status: stateInfo.status
+        });
+        logEvent('workflow', 'roadmap-sync', {
+          phase: stateInfo.phase,
+          status: 'in-sync'
+        });
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      process.exit(0);
+    }
+  });
+}
+
+/**
+ * Extract current phase number and status from STATE.md.
+ * Handles common formats:
+ *   "**Phase**: 03 - slug-name"
+ *   "Phase: 3"
+ *   "Current phase: 03-slug-name"
+ *   "**Status**: planned"
+ *   "Phase status: built"
+ */
+function parseState(content) {
+  const phaseMatch = content.match(
+    /\*{0,2}(?:Current\s+)?Phase\*{0,2}:\s*(\d+(?:\.\d+)?)/i
+  );
+
+  const statusMatch = content.match(
+    /\*{0,2}(?:Phase\s+)?Status\*{0,2}:\s*["']?(\w+)["']?/i
+  );
+
+  if (!phaseMatch || !statusMatch) return null;
+
+  return {
+    phase: normalizePhaseNum(phaseMatch[1]),
+    status: statusMatch[1].toLowerCase()
+  };
+}
+
+/**
+ * Find the status for a given phase in ROADMAP.md's Phase Overview table.
+ * Table format:
+ *   | Phase | Name | Goal | Plans | Wave | Status |
+ *   |-------|------|------|-------|------|--------|
+ *   | 01    | ...  | ...  | ...   | ...  | pending |
+ */
+function getRoadmapPhaseStatus(content, phaseNum) {
+  const lines = content.split('\n');
+
+  let statusColIndex = -1;
+  let phaseColIndex = -1;
+  let inTable = false;
+
+  for (const line of lines) {
+    if (!inTable) {
+      if (line.includes('|') && /Phase/i.test(line) && /Status/i.test(line)) {
+        const cols = splitTableRow(line);
+        phaseColIndex = cols.findIndex(c => /^Phase$/i.test(c));
+        statusColIndex = cols.findIndex(c => /^Status$/i.test(c));
+        if (phaseColIndex !== -1 && statusColIndex !== -1) {
+          inTable = true;
+        }
+      }
+      continue;
+    }
+
+    // Skip separator row
+    if (/^\s*\|[\s-:|]+\|\s*$/.test(line)) continue;
+
+    // Non-table line ends the table
+    if (!line.includes('|')) break;
+
+    const cols = splitTableRow(line);
+    if (cols.length <= Math.max(phaseColIndex, statusColIndex)) continue;
+
+    const rowPhase = normalizePhaseNum(cols[phaseColIndex]);
+    if (rowPhase === phaseNum) {
+      return cols[statusColIndex];
+    }
+  }
+
+  return null;
+}
+
+/** Split a markdown table row into trimmed cell values. */
+function splitTableRow(line) {
+  return line.split('|').map(c => c.trim()).filter(Boolean);
+}
+
+/**
+ * Extract and normalize a phase number from various formats:
+ *   "03"                    → "3"
+ *   "3.1"                   → "3.1"
+ *   "01. Project Scaffolding" → "1"
+ *   "Phase 02"              → "2"
+ */
+function normalizePhaseNum(raw) {
+  const match = raw.match(/(?:Phase\s+)?0*(\d+(?:\.\d+)?)/i);
+  return match ? match[1] : raw.trim();
+}
+
+/**
+ * Core roadmap sync check logic for use by dispatchers.
+ * @param {Object} data - Parsed hook input (tool_input, etc.)
+ * @returns {null|{output: Object}} null if pass or not applicable, result otherwise
+ */
+function checkSync(data) {
+  const filePath = data.tool_input?.file_path || '';
+
+  if (!filePath.endsWith('STATE.md')) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+
+  if (!fs.existsSync(filePath) || !fs.existsSync(roadmapPath)) return null;
+
+  const stateContent = fs.readFileSync(filePath, 'utf8');
+  const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+
+  const stateInfo = parseState(stateContent);
+  if (!stateInfo || !stateInfo.phase || !stateInfo.status) {
+    logHook('check-roadmap-sync', 'PostToolUse', 'skip', { reason: 'could not parse STATE.md' });
+    return null;
+  }
+
+  if (!LIFECYCLE_STATUSES.includes(stateInfo.status)) {
+    logHook('check-roadmap-sync', 'PostToolUse', 'skip', {
+      reason: `status "${stateInfo.status}" not a lifecycle status`
+    });
+    return null;
+  }
+
+  const roadmapStatus = getRoadmapPhaseStatus(roadmapContent, stateInfo.phase);
+  if (!roadmapStatus) {
+    logHook('check-roadmap-sync', 'PostToolUse', 'skip', {
+      reason: `phase ${stateInfo.phase} not found in ROADMAP.md table`
+    });
+    return null;
+  }
+
+  if (roadmapStatus.toLowerCase() !== stateInfo.status) {
+    logHook('check-roadmap-sync', 'PostToolUse', 'warn', {
+      phase: stateInfo.phase, stateStatus: stateInfo.status, roadmapStatus
+    });
+    logEvent('workflow', 'roadmap-sync', {
+      phase: stateInfo.phase, stateStatus: stateInfo.status, roadmapStatus, status: 'out-of-sync'
+    });
+    return {
+      output: {
+        message: `ROADMAP.md out of sync: Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the Phase Overview table in ROADMAP.md to match.`
+      }
+    };
+  }
+
+  logHook('check-roadmap-sync', 'PostToolUse', 'pass', { phase: stateInfo.phase, status: stateInfo.status });
+  logEvent('workflow', 'roadmap-sync', { phase: stateInfo.phase, status: 'in-sync' });
+  return null;
+}
+
+module.exports = { parseState, getRoadmapPhaseStatus, checkSync };
+if (require.main === module) { main(); }