@sienklogic/plan-build-run 2.19.0 → 2.19.2

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

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook: Validates planning artifact structure on write.
+ *
+ * Validated file types:
+ * - PLAN.md: task elements, frontmatter, max 3 tasks
+ * - SUMMARY.md: frontmatter fields, key_files paths
+ * - VERIFICATION.md: status, phase, must_haves fields
+ * - ROADMAP.md: milestone structure, phase definitions (errors for critical, warnings for minor)
+ * - LEARNINGS.md: frontmatter with phase, key_insights, patterns
+ * - STATE.md: frontmatter fields (warnings only, auto-synced)
+ * - config.json: valid JSON, required fields
+ * - RESEARCH.md: frontmatter with confidence, sources_checked
+ * - CONTEXT.md: XML-style sections (domain, decisions, canonical_refs, deferred) or legacy markdown headers
+ *
+ * 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');
+
+// Import all validators from extracted module
+const {
+  validateMustHaves,
+  PLAN_REQUIRED_FIELDS,
+  PLAN_VALID_TYPES,
+  validatePlan,
+  validateSummary,
+  validateDeviationsField,
+  checkPlanWrite,
+  VALID_STATE_STATUSES,
+  validateState,
+  validateVerification,
+  checkStateWrite,
+  syncStateBody,
+  validateRoadmap,
+  validateLearnings,
+  validateConfig,
+  validateResearch,
+  validateContext
+} = require('./lib/format-validators');
+
+async function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', async () => {
+    try {
+      const data = JSON.parse(input);
+      const sessionId = data.session_id || null;
+
+      // 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 isPlanStandard = /^PLAN.*\.md$/.test(basename);
+      const isPlanPrefixed = /^\d+-\d+-PLAN\.md$/.test(basename);
+      const isPlan = isPlanStandard || isPlanPrefixed;
+      const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
+      const isVerification = basename === 'VERIFICATION.md';
+      const isRoadmap = basename === 'ROADMAP.md';
+      const isLearnings = basename === 'LEARNINGS.md';
+      const isConfig = basename === 'config.json' && filePath.includes('.planning');
+      const isResearch = basename === 'RESEARCH.md';
+      const isContext = basename === 'CONTEXT.md' && filePath.includes('.planning');
+
+      if (!isPlan && !isSummary && !isVerification && !isRoadmap && !isLearnings && !isConfig && !isResearch && !isContext) {
+        process.exit(0);
+      }
+
+      if (!fs.existsSync(filePath)) {
+        process.exit(0);
+      }
+
+      const content = fs.readFileSync(filePath, 'utf8');
+      const result = isPlan
+        ? validatePlan(content, filePath)
+        : isVerification
+          ? validateVerification(content, filePath)
+          : isRoadmap
+            ? validateRoadmap(content, filePath)
+            : isLearnings
+              ? validateLearnings(content, filePath)
+              : isConfig
+                ? validateConfig(content, filePath)
+                : isResearch
+                  ? validateResearch(content, filePath)
+                  : isContext
+                    ? validateContext(content, filePath)
+                    : validateSummary(content, filePath);
+
+      // Warn on non-standard plan file naming (e.g., "10-02-PLAN.md" instead of "PLAN-02.md")
+      if (isPlanPrefixed && !isPlanStandard) {
+        result.warnings.push(`Plan file "${basename}" uses non-standard naming. Expected format: PLAN-{NN}.md or PLAN.md. Phase-prefixed names (e.g., "10-02-PLAN.md") bypass some validation checks.`);
+      }
+
+      const eventType = isPlan ? 'plan-validated' : isVerification ? 'verification-validated' : isRoadmap ? 'roadmap-validated' : isLearnings ? 'learnings-validated' : isConfig ? 'config-validated' : isResearch ? 'research-validated' : isContext ? 'context-validated' : 'summary-validated';
+
+      // Detect Write vs Edit: Write = full creation/overwrite (likely first attempt)
+      const isWriteTool = (data.tool_name || '').toLowerCase() === 'write';
+
+      if (result.errors.length > 0) {
+        // On Write tool, downgrade errors to warnings to avoid false positive blocks
+        if (isWriteTool) {
+          const allIssues = [...result.errors, ...result.warnings];
+          logHook('check-plan-format', 'PostToolUse', 'warn-downgraded', {
+            file: basename,
+            errors: result.errors,
+            reason: 'Write tool (first creation)',
+            sessionId
+          });
+          logEvent('workflow', eventType, {
+            file: basename,
+            status: 'warn-downgraded',
+            errorCount: result.errors.length,
+            sessionId
+          });
+
+          const output = {
+            additionalContext: `${basename} advisory (fix on next edit):\n${allIssues.map(i => `  - ${i}`).join('\n')}`
+          };
+          process.stdout.write(JSON.stringify(output));
+        } else {
+          // Structural errors on Edit -- block and force correction
+          logHook('check-plan-format', 'PostToolUse', 'block', {
+            file: basename,
+            errors: result.errors,
+            sessionId
+          });
+          logEvent('workflow', eventType, {
+            file: basename,
+            status: 'block',
+            errorCount: result.errors.length,
+            sessionId
+          });
+
+          const summary = `${basename} has structural errors that must be fixed.`;
+          const explanation = result.errors.map(i => `  - ${i}`).join('\n') +
+            (result.warnings.length > 0 ? '\n\nWarnings (non-blocking):\n' + result.warnings.map(i => `  - ${i}`).join('\n') : '');
+          const remediation = 'Fix the listed issues and re-save the file.';
+
+          const output = {
+            decision: 'block',
+            reason: `${summary}\n\n${explanation}\n\n${remediation}`
+          };
+          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,
+          sessionId
+        });
+        logEvent('workflow', eventType, {
+          file: basename,
+          status: 'warn',
+          warningCount: result.warnings.length,
+          sessionId
+        });
+
+        const output = {
+          additionalContext: `${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, sessionId });
+        logEvent('workflow', eventType, { file: basename, status: 'pass', sessionId });
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on parse errors
+      process.exit(0);
+    }
+  });
+}
+
+// Re-export validators for backward compatibility with existing tests
+module.exports = {
+  validateMustHaves,
+  PLAN_REQUIRED_FIELDS,
+  PLAN_VALID_TYPES,
+  validatePlan,
+  validateSummary,
+  validateDeviationsField,
+  checkPlanWrite,
+  VALID_STATE_STATUSES,
+  validateState,
+  validateVerification,
+  checkStateWrite,
+  syncStateBody,
+  validateRoadmap,
+  validateLearnings,
+  validateConfig,
+  validateResearch,
+  validateContext
+};
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/dist/check-read-first.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook: read_first enforcement (advisory).
+ *
+ * Tracks file Read events and warns when a Write/Edit targets a file
+ * listed in a plan task's <files> without prior reads of that task's
+ * <read_first> files.
+ *
+ * ADVISORY ONLY — returns { additionalContext } warnings, never blocks.
+ *
+ * Integration:
+ *   - trackRead() is called by track-context-budget.js on Read events
+ *   - checkReadFirst() is called by post-write-dispatch.js on Write/Edit events
+ *
+ * Exit codes:
+ *   0 = always (PostToolUse hook, advisory only)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { resolveSessionPath } = require('./lib/core');
+
+// Module-level cache: phaseDir -> parsed plan data
+const planCache = new Map();
+
+/**
+ * Normalize a file path to forward slashes and resolve to absolute.
+ * @param {string} filePath
+ * @param {string} [projectRoot]
+ * @returns {string}
+ */
+function normalizePath(filePath, projectRoot) {
+  if (!filePath) return '';
+  let resolved = filePath;
+  if (!path.isAbsolute(resolved) && projectRoot) {
+    resolved = path.resolve(projectRoot, resolved);
+  } else if (!path.isAbsolute(resolved)) {
+    resolved = path.resolve(resolved);
+  }
+  return resolved.replace(/\\/g, '/');
+}
+
+/**
+ * Read the tracker file from disk.
+ * @param {string} trackerPath
+ * @returns {{ skill: string, reads: string[] }}
+ */
+function loadTracker(trackerPath) {
+  try {
+    const content = fs.readFileSync(trackerPath, 'utf8');
+    return JSON.parse(content);
+  } catch (_e) {
+    return { skill: '', reads: [] };
+  }
+}
+
+/**
+ * Write the tracker file atomically (tmp + rename).
+ * @param {string} trackerPath
+ * @param {Object} tracker
+ */
+function saveTracker(trackerPath, tracker) {
+  try {
+    const tmpPath = trackerPath + '.' + process.pid;
+    fs.writeFileSync(tmpPath, JSON.stringify(tracker), 'utf8');
+    fs.renameSync(tmpPath, trackerPath);
+  } catch (_e) {
+    try { fs.unlinkSync(trackerPath + '.' + process.pid); } catch (_e2) { /* best-effort */ }
+  }
+}
+
+/**
+ * Read the current active skill from .active-skill file.
+ * @param {string} planningDir
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+function readActiveSkill(planningDir, sessionId) {
+  try {
+    const skillPath = sessionId
+      ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+      : path.join(planningDir, '.active-skill');
+    return fs.readFileSync(skillPath, 'utf8').trim();
+  } catch (_e) {
+    return '';
+  }
+}
+
+/**
+ * Resolve the tracker file path.
+ * @param {string} planningDir
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+function getTrackerPath(planningDir, sessionId) {
+  if (sessionId) {
+    return resolveSessionPath(planningDir, '.read-first-tracker', sessionId);
+  }
+  return path.join(planningDir, '.read-first-tracker');
+}
+
+/**
+ * Track a Read event — record the file path in the session tracker.
+ * Called by track-context-budget.js on every Read PostToolUse event.
+ *
+ * @param {Object} data - Hook event data
+ * @param {string} planningDir - Absolute path to .planning/
+ * @param {string} [sessionId] - Session identifier
+ * @returns {null}
+ */
+function trackRead(data, planningDir, sessionId) {
+  if (!planningDir || !data) return null;
+
+  const filePath = data.tool_input?.file_path || '';
+  if (!filePath) return null;
+
+  const projectRoot = path.dirname(planningDir);
+  const normalized = normalizePath(filePath, projectRoot);
+  if (!normalized) return null;
+
+  const trackerPath = getTrackerPath(planningDir, sessionId);
+  const currentSkill = readActiveSkill(planningDir, sessionId);
+  let tracker = loadTracker(trackerPath);
+
+  // Reset tracker when skill changes
+  if (tracker.skill !== currentSkill) {
+    tracker = { skill: currentSkill, reads: [] };
+    planCache.clear();
+  }
+
+  // Add path if not already tracked
+  if (!tracker.reads.includes(normalized)) {
+    tracker.reads.push(normalized);
+  }
+
+  saveTracker(trackerPath, tracker);
+  return null;
+}
+
+/**
+ * Parse all PLAN-*.md files in a phase directory and extract
+ * task-level read_first and files mappings.
+ *
+ * @param {string} phaseDir - Absolute path to the phase directory
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {Array<{ files: string[], readFirst: string[] }>}
+ */
+function parsePlanReadFirst(phaseDir, projectRoot) {
+  if (planCache.has(phaseDir)) {
+    return planCache.get(phaseDir);
+  }
+
+  const tasks = [];
+
+  try {
+    const entries = fs.readdirSync(phaseDir);
+    const planFiles = entries.filter(e => /^PLAN.*\.md$/i.test(e));
+
+    for (const planFile of planFiles) {
+      const content = fs.readFileSync(path.join(phaseDir, planFile), 'utf8');
+
+      // Extract all <task> blocks
+      const taskRegex = /<task[^>]*>([\s\S]*?)<\/task>/g;
+      let taskMatch;
+      while ((taskMatch = taskRegex.exec(content)) !== null) {
+        const taskBody = taskMatch[1];
+
+        // Extract <read_first> content
+        const rfMatch = taskBody.match(/<read_first>([\s\S]*?)<\/read_first>/);
+        const readFirstRaw = rfMatch ? rfMatch[1].trim().split(/\r?\n/).map(l => l.trim()).filter(Boolean) : [];
+
+        // Extract <files> content
+        const filesMatch = taskBody.match(/<files>([\s\S]*?)<\/files>/);
+        const filesRaw = filesMatch ? filesMatch[1].trim().split(/\r?\n/).map(l => l.trim()).filter(Boolean) : [];
+
+        if (readFirstRaw.length > 0 && filesRaw.length > 0) {
+          tasks.push({
+            readFirst: readFirstRaw.map(f => normalizePath(f, projectRoot)),
+            files: filesRaw.map(f => normalizePath(f, projectRoot))
+          });
+        }
+      }
+    }
+  } catch (_e) {
+    // If we can't read plans, return empty — no enforcement
+  }
+
+  planCache.set(phaseDir, tasks);
+  return tasks;
+}
+
+/**
+ * Check if a Write/Edit target violates read_first requirements.
+ * Returns an advisory warning if the written file is in a plan task's <files>
+ * but the corresponding <read_first> files were not previously Read.
+ *
+ * @param {Object} data - Hook event data
+ * @param {string} planningDir - Absolute path to .planning/
+ * @param {string} [sessionId] - Session identifier
+ * @returns {{ additionalContext: string }|null}
+ */
+function checkReadFirst(data, planningDir, sessionId) {
+  if (!planningDir || !data) return null;
+
+  const filePath = data.tool_input?.file_path || '';
+  if (!filePath) return null;
+
+  const projectRoot = path.dirname(planningDir);
+  const normalizedTarget = normalizePath(filePath, projectRoot);
+
+  // Load STATE.md to get current phase
+  let currentPhase;
+  try {
+    const { stateLoad } = require('./lib/state');
+    const state = stateLoad(planningDir);
+    if (!state || !state.state || !state.state.current_phase) {
+      return null; // No active phase = no enforcement
+    }
+    currentPhase = state.state.current_phase;
+  } catch (_e) {
+    return null; // Can't load state = graceful exit
+  }
+
+  // Find the phase directory
+  const phasesDir = path.join(planningDir, 'phases');
+  let phaseDir = null;
+  try {
+    const entries = fs.readdirSync(phasesDir);
+    const phaseNum = String(currentPhase);
+    const phasePadded = phaseNum.padStart(2, '0');
+    for (const entry of entries) {
+      if (entry.startsWith(phaseNum + '-') || entry.startsWith(phasePadded + '-') || entry === phaseNum) {
+        const fullPath = path.join(phasesDir, entry);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+          phaseDir = fullPath;
+          break;
+        }
+      }
+    }
+  } catch (_e) {
+    return null; // No phases directory
+  }
+
+  if (!phaseDir) return null;
+
+  // Parse plan files for read_first/files mappings
+  const tasks = parsePlanReadFirst(phaseDir, projectRoot);
+  if (tasks.length === 0) return null;
+
+  // Load tracker to see what was read
+  const trackerPath = getTrackerPath(planningDir, sessionId);
+  const tracker = loadTracker(trackerPath);
+
+  // Check if the written file is in any task's <files> list
+  for (const task of tasks) {
+    const inFiles = task.files.some(f => f === normalizedTarget);
+    if (!inFiles) continue;
+
+    // Check which read_first files were NOT read
+    const unread = task.readFirst.filter(rf => !tracker.reads.includes(rf));
+    if (unread.length > 0) {
+      const shortTarget = path.basename(filePath);
+      const shortUnread = unread.map(u => {
+        // Show relative path from project root
+        const rel = u.replace(normalizePath(projectRoot) + '/', '');
+        return rel;
+      }).join(', ');
+
+      logHook('check-read-first', 'PostToolUse', 'warn', {
+        file: filePath,
+        unread: unread.length,
+        total_read_first: task.readFirst.length
+      });
+
+      return {
+        additionalContext: `[read_first] Warning: ${shortTarget} was edited but ${shortUnread} from read_first were not read first. Consider reading them to avoid blind edits.`
+      };
+    }
+  }
+
+  logHook('check-read-first', 'PostToolUse', 'allow', { file: filePath });
+  return null;
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * Routes based on tool type: Read -> trackRead, Write/Edit -> checkReadFirst.
+ *
+ * @param {Object} reqBody - { event, tool, data, planningDir }
+ * @param {Object} _cache - Server cache (unused)
+ * @returns {Object|null}
+ */
+function handleHttp(reqBody, _cache) {
+  try {
+    const data = reqBody.data || {};
+    const planningDir = reqBody.planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+    const tool = data.tool || data.tool_name || reqBody.tool || '';
+    const sessionId = data.session_id || null;
+
+    if (tool === 'Read') {
+      return trackRead(data, planningDir, sessionId);
+    } else if (tool === 'Write' || tool === 'Edit') {
+      return checkReadFirst(data, planningDir, sessionId);
+    }
+    return null;
+  } catch (_e) {
+    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 cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+      const planningDir = path.join(cwd, '.planning');
+      const tool = data.tool || data.tool_name || '';
+      const sessionId = data.session_id || null;
+
+      let result = null;
+      if (tool === 'Read') {
+        result = trackRead(data, planningDir, sessionId);
+      } else if (tool === 'Write' || tool === 'Edit') {
+        result = checkReadFirst(data, planningDir, sessionId);
+      }
+
+      if (result) {
+        process.stdout.write(JSON.stringify(result));
+      }
+      process.exit(0);
+    } catch (_e) {
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { trackRead, checkReadFirst, handleHttp, normalizePath, parsePlanReadFirst };
+
+if (require.main === module || process.argv[1] === __filename) { main(); }