@sienklogic/plan-build-run 2.0.2 → 2.1.0

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

@@ -96,7 +96,7 @@ function main() {
         });
 
         const output = {
-          message: `${basename} warnings:\n${result.warnings.map(i => `  - ${i}`).join('\n')}`
+          additionalContext: `${basename} warnings:\n${result.warnings.map(i => `  - ${i}`).join('\n')}`
         };
         process.stdout.write(JSON.stringify(output));
       } else {
@@ -258,7 +258,7 @@ function checkPlanWrite(data) {
   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')}` } };
+    return { output: { additionalContext: `${basename} warnings:\n${result.warnings.map(i => `  - ${i}`).join('\n')}` } };
   }
 
   logHook('check-plan-format', 'PostToolUse', 'pass', { file: basename });
@@ -267,4 +267,4 @@ function checkPlanWrite(data) {
 }
 
 module.exports = { validatePlan, validateSummary, checkPlanWrite };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -80,7 +80,7 @@ function main() {
         });
 
         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.`
+          additionalContext: `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 {
@@ -238,7 +238,7 @@ function checkSync(data) {
     });
     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.`
+        additionalContext: `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.`
       }
     };
   }
@@ -319,4 +319,4 @@ function checkFilesystemDrift(roadmapContent, phasesDir) {
 }
 
 module.exports = { parseState, getRoadmapPhaseStatus, checkSync, parseRoadmapPhases, checkFilesystemDrift };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/check-skill-workflow.js

@@ -259,4 +259,4 @@ function checkWorkflow(data) {
 }
 
 module.exports = { readActiveSkill, checkSkillRules, hasPlanFile, checkWorkflow };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -437,7 +437,7 @@ function checkStateSync(data) {
     const msg = `Auto-synced tracking files: ${messages.join('; ')}`;
     logHook('check-state-sync', 'PostToolUse', 'sync', { phase: phaseNum, updates: messages });
     logEvent('workflow', 'state-sync', { phase: phaseNum, trigger: isSummary ? 'summary' : 'verification', updates: messages });
-    return { output: { message: msg } };
+    return { output: { additionalContext: msg } };
   }
 
   logHook('check-state-sync', 'PostToolUse', 'skip', { reason: 'no tracking files to update', phase: phaseNum });
@@ -464,7 +464,7 @@ function main() {
   });
 }
 
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }
 module.exports = {
   extractPhaseNum,
   countPhaseArtifacts,

package/plugins/pbr/scripts/check-subagent-output.js

@@ -141,4 +141,4 @@ function main() {
 }
 
 module.exports = { AGENT_OUTPUTS, findInPhaseDir };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/check-summary-gate.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook (Write|Edit): Blocks STATE.md updates that advance
+ * phase status to "built" or "verified" unless a SUMMARY file exists
+ * for the current phase.
+ *
+ * This prevents the scenario where verification runs and STATE.md is
+ * updated but the executor never wrote a SUMMARY — leaving the project
+ * in an inconsistent state.
+ *
+ * Trigger: Write|Edit to STATE.md (via pre-write-dispatch.js)
+ *
+ * Logic:
+ *   1. Only fires when the target file is STATE.md
+ *   2. Reads the new content being written (from tool_input)
+ *   3. Extracts the phase slug and status from frontmatter
+ *   4. If status is advancing to "built", "verified", or "complete",
+ *      checks that a SUMMARY-*.md file exists in the phase directory
+ *   5. Blocks (exit 2) if no SUMMARY found
+ *
+ * Exit codes:
+ *   0 = allowed or not applicable
+ *   2 = blocked (no SUMMARY exists for advancing phase)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+// Statuses that indicate a phase has been executed
+const ADVANCED_STATUSES = ['built', 'verified', 'complete', 'building'];
+
+/**
+ * Extract YAML frontmatter values from markdown content.
+ * Returns an object with parsed key-value pairs.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = line.match(/^(\w[\w_]*):\s*"?([^"\r\n]*)"?$/);
+    if (kv) result[kv[1]] = kv[2].trim();
+  }
+  return result;
+}
+
+/**
+ * Check if a SUMMARY file exists for the given phase directory.
+ */
+function hasSummaryFile(phaseDir) {
+  if (!fs.existsSync(phaseDir)) return false;
+  try {
+    const files = fs.readdirSync(phaseDir);
+    return files.some(f => /^SUMMARY.*\.md$/i.test(f));
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Find the phase directory matching a slug or phase number.
+ */
+function findPhaseDir(planningDir, phaseSlug, phaseNumber) {
+  const phasesDir = path.join(planningDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+
+  try {
+    const dirs = fs.readdirSync(phasesDir);
+
+    // Try exact slug match first
+    if (phaseSlug) {
+      const match = dirs.find(d => d === phaseSlug);
+      if (match) return path.join(phasesDir, match);
+    }
+
+    // Fall back to phase number prefix
+    if (phaseNumber) {
+      const padded = String(phaseNumber).padStart(2, '0');
+      const match = dirs.find(d => d.startsWith(padded + '-'));
+      if (match) return path.join(phasesDir, match);
+    }
+  } catch (_e) {
+    // best-effort
+  }
+  return null;
+}
+
+function checkSummaryGate(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  // Only check STATE.md writes
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  if (!normalizedPath.endsWith('.planning/STATE.md')) return null;
+
+  // Get the new content being written
+  // For Write: tool_input.content
+  // For Edit: tool_input.new_string (partial — check for status changes)
+  const content = data.tool_input?.content || '';
+  const newString = data.tool_input?.new_string || '';
+  const textToCheck = content || newString;
+
+  if (!textToCheck) return null;
+
+  // Parse frontmatter from the content
+  const fm = parseFrontmatter(textToCheck);
+  const newStatus = (fm.status || '').toLowerCase();
+
+  // For Edit operations, check if the new_string contains a status advancement
+  let editAdvancing = false;
+  if (!content && newString) {
+    const statusMatch = newString.match(/status:\s*"?(\w+)"?/);
+    if (statusMatch) {
+      const editStatus = statusMatch[1].toLowerCase();
+      editAdvancing = ADVANCED_STATUSES.includes(editStatus);
+    }
+  }
+
+  // Only gate on status advancement
+  if (!ADVANCED_STATUSES.includes(newStatus) && !editAdvancing) return null;
+
+  // Determine phase from content
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const phaseSlug = fm.phase_slug || '';
+  const phaseNumber = fm.current_phase || '';
+
+  // Also try to extract from body text for Edit operations
+  let effectiveSlug = phaseSlug;
+  let effectiveNumber = phaseNumber;
+  if (!effectiveSlug && !effectiveNumber) {
+    const slugMatch = textToCheck.match(/phase_slug:\s*"?([^"\r\n]+)"?/);
+    const numMatch = textToCheck.match(/current_phase:\s*(\d+)/);
+    if (slugMatch) effectiveSlug = slugMatch[1].trim();
+    if (numMatch) effectiveNumber = numMatch[1];
+  }
+
+  // For Edit operations where we only see the diff, read current STATE.md
+  if (!effectiveSlug && !effectiveNumber) {
+    try {
+      const currentState = fs.readFileSync(path.join(planningDir, 'STATE.md'), 'utf8');
+      const currentFm = parseFrontmatter(currentState);
+      effectiveSlug = currentFm.phase_slug || '';
+      effectiveNumber = currentFm.current_phase || '';
+    } catch (_e) {
+      // Can't determine phase — allow the write
+      return null;
+    }
+  }
+
+  const phaseDir = findPhaseDir(planningDir, effectiveSlug, effectiveNumber);
+  if (!phaseDir) return null; // Can't find phase dir — don't block
+
+  if (hasSummaryFile(phaseDir)) return null; // SUMMARY exists — all good
+
+  const effectiveStatus = editAdvancing
+    ? (newString.match(/status:\s*"?(\w+)"?/) || [])[1]
+    : newStatus;
+
+  logHook('check-summary-gate', 'PreToolUse', 'block', {
+    status: effectiveStatus,
+    phase: effectiveSlug || effectiveNumber,
+    phaseDir: path.basename(phaseDir)
+  });
+
+  return {
+    exitCode: 2,
+    output: {
+      decision: 'block',
+      reason: `SUMMARY gate: Cannot set status to "${effectiveStatus}" — no SUMMARY file found in ${path.basename(phaseDir)}/.\n\nThe executor must write a SUMMARY-{plan_id}.md before STATE.md can advance. This prevents inconsistent state where a phase appears complete but has no build receipt.\n\nTo fix:\n  1. Run the executor to generate the SUMMARY file\n  2. Or manually create SUMMARY-{plan_id}.md in .planning/phases/${path.basename(phaseDir)}/`
+    }
+  };
+}
+
+// Standalone mode
+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 = checkSummaryGate(data);
+      if (result) {
+        process.stdout.write(JSON.stringify(result.output));
+        process.exit(result.exitCode || 0);
+      }
+      process.exit(0);
+    } catch (_e) {
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkSummaryGate, parseFrontmatter, hasSummaryFile, findPhaseDir, ADVANCED_STATUSES };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/context-budget-check.js

@@ -284,4 +284,4 @@ function buildRecoveryContext(activeOp, roadmapSummary, currentPlan, configHighl
 }
 
 module.exports = { readRoadmapSummary, readCurrentPlan, readConfigHighlights, buildRecoveryContext, readRecentErrors, readRecentAgents };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/event-handler.js

@@ -141,11 +141,11 @@ function main() {
   writeAutoVerifySignal(planningDir, stateInfo.phase);
 
   const output = {
-    message: `Executor complete. Auto-verification queued for Phase ${stateInfo.phase}.`
+    additionalContext: `Executor complete. Auto-verification queued for Phase ${stateInfo.phase}.`
   };
   process.stdout.write(JSON.stringify(output));
   process.exit(0);
 }
 
 module.exports = { isExecutorAgent, shouldAutoVerify, getPhaseFromState };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/event-logger.js

@@ -88,5 +88,5 @@ function main() {
   process.exit(0);
 }
 
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }
 module.exports = { logEvent };

package/plugins/pbr/scripts/log-subagent.js

@@ -161,4 +161,4 @@ function buildAgentContext() {
 }
 
 module.exports = { buildAgentContext, resolveAgentType };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/pbr-tools.js

@@ -1374,5 +1374,5 @@ function atomicWrite(filePath, content) {
   }
 }
 
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }
 module.exports = { parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition };

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

@@ -63,4 +63,4 @@ function main() {
   });
 }
 
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -204,4 +204,4 @@ function detectConsoleLogs(filePath) {
 }
 
 module.exports = { checkQuality, loadHooksConfig, findLocalBin, runPrettier, runTypeCheck, detectConsoleLogs };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -83,4 +83,4 @@ function main() {
   });
 }
 
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -15,13 +15,18 @@
  *      happen at all in the current workflow state, there's no point
  *      evaluating boundary or sprawl rules. Can block (exit 2).
  *
- *   2. check-phase-boundary  — Guards against writes that target files
+ *   2. check-summary-gate    — Blocks STATE.md status advancement
+ *      (to built/verified/complete) unless a SUMMARY file exists for
+ *      the current phase. Prevents inconsistent state where a phase
+ *      appears complete but has no build receipt. Can block (exit 2).
+ *
+ *   3. check-phase-boundary  — Guards against writes that target files
  *      outside the current phase directory. Runs second because once
  *      we know the write is allowed by workflow rules, we need to
  *      verify it's scoped to the correct phase. Can block (exit 2)
  *      or warn (exit 0 with message).
  *
- *   3. check-doc-sprawl      — Prevents creation of new .md/.txt files
+ *   4. check-doc-sprawl      — Prevents creation of new .md/.txt files
  *      outside a known allowlist (when enabled in config). Runs last
  *      because it's the most granular check — only relevant for new
  *      documentation files, not all writes. Can block (exit 2).
@@ -53,6 +58,7 @@
  */
 
 const { checkWorkflow } = require('./check-skill-workflow');
+const { checkSummaryGate } = require('./check-summary-gate');
 const { checkBoundary } = require('./check-phase-boundary');
 const { checkDocSprawl } = require('./check-doc-sprawl');
 
@@ -72,6 +78,13 @@ function main() {
         process.exit(workflowResult.exitCode || 0);
       }
 
+      // SUMMARY gate — blocks STATE.md advancement without SUMMARY
+      const summaryGateResult = checkSummaryGate(data);
+      if (summaryGateResult) {
+        process.stdout.write(JSON.stringify(summaryGateResult.output));
+        process.exit(summaryGateResult.exitCode || 0);
+      }
+
       // Phase boundary check — can block or warn
       const boundaryResult = checkBoundary(data);
       if (boundaryResult) {
@@ -94,4 +107,4 @@ function main() {
   });
 }
 
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/session-cleanup.js

@@ -251,4 +251,4 @@ function main() {
 }
 
 module.exports = { writeSessionHistory, tryRemove, cleanStaleCheckpoints, rotateHooksLog, findOrphanedProgressFiles };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/status-line.js

@@ -284,5 +284,5 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
   return parts.join(` ${c.dim}\u2502${c.reset} `);
 }
 
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }
 module.exports = { buildStatusLine, buildContextBar, getContextPercent, getGitInfo, formatDuration, loadStatusLineConfig, DEFAULTS };

package/plugins/pbr/scripts/suggest-compact.js

@@ -116,4 +116,4 @@ function resetCounter(planningDir) {
 }
 
 module.exports = { checkCompaction, loadCounter, saveCounter, getThreshold, resetCounter, DEFAULT_THRESHOLD, REMINDER_INTERVAL };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/task-completed.js

@@ -41,5 +41,5 @@ function main() {
   process.exit(0);
 }
 
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }
 module.exports = { main };

package/plugins/pbr/scripts/track-context-budget.js

@@ -52,9 +52,11 @@ function main() {
         }
       }
 
-      // Estimate chars read (use limit if provided, otherwise assume ~2000 lines × 40 chars avg)
+      // Estimate chars read from actual output or limit, with a conservative default.
+      // Previous default of 80k (2000 lines × 40 chars) caused every read to cross
+      // the 50k milestone, flooding logs with warnings on every single Read call.
       const limit = data.tool_input?.limit;
-      const estimatedChars = limit ? limit * 40 : 80000;
+      const estimatedChars = limit ? limit * 40 : 8000;
       // Use actual output length if available
       const actualChars = data.tool_output ? String(data.tool_output).length : estimatedChars;
 
@@ -65,7 +67,7 @@ function main() {
       const currentSkill = readFileSafe(skillPath);
       let tracker = loadTracker(trackerPath);
 
-      if (tracker.skill !== currentSkill) {
+      if (tracker.skill !== currentSkill || tracker.files.length > 200) {
         tracker = { skill: currentSkill, reads: 0, total_chars: 0, files: [] };
       }
 
@@ -77,11 +79,14 @@ function main() {
         tracker.files.push(filePath);
       }
 
-      // Save tracker
+      // Save tracker (atomic write to avoid corruption from concurrent hooks)
       try {
-        fs.writeFileSync(trackerPath, JSON.stringify(tracker), 'utf8');
+        const tmpPath = trackerPath + '.' + process.pid;
+        fs.writeFileSync(tmpPath, JSON.stringify(tracker), 'utf8');
+        fs.renameSync(tmpPath, trackerPath);
       } catch (_e) {
-        // Best-effort
+        // Best-effort — clean up temp file if rename failed
+        try { fs.unlinkSync(trackerPath + '.' + process.pid); } catch (_e2) { /* best-effort cleanup */ }
       }
 
       // Check thresholds — only warn at milestone crossings, not every read

package/plugins/pbr/scripts/validate-commit.js

@@ -197,4 +197,4 @@ function extractCommitMessage(command) {
 }
 
 module.exports = { checkCommit };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/validate-task.js

@@ -103,4 +103,4 @@ function main() {
 }
 
 module.exports = { checkTask, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
-if (require.main === module) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main(); }