@sienklogic/plan-build-run 2.21.1 → 2.22.0

package/plugins/pbr/scripts/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 may be needed. Changed pbr files without cursor-pbr/copilot-pbr counterparts:\n${missingCounterparts.map(f => `  - ${f}`).join('\n')}`;
+  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/scripts/check-dangerous-commands.js

@@ -86,7 +86,7 @@ function checkDangerous(data) {
       return {
         output: {
           decision: 'block',
-          reason: `Dangerous command blocked.\n\n${reason}\n\nCommand: ${command.substring(0, 150)}`
+          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
       };
@@ -146,7 +146,7 @@ function checkSkillSpecificBash(command) {
     return {
       output: {
         decision: 'block',
-        reason: 'CRITICAL: Use Read + Write tools for JSON files, not shell text manipulation. Shell tools can corrupt JSON structure.'
+        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
     };

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

@@ -42,10 +42,10 @@ function main() {
       const basename = path.basename(filePath);
       const isPlan = basename.endsWith('PLAN.md');
       const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
-
       const isVerification = basename === 'VERIFICATION.md';
+      const isRoadmap = basename === 'ROADMAP.md';
 
-      if (!isPlan && !isSummary && !isVerification) {
+      if (!isPlan && !isSummary && !isVerification && !isRoadmap) {
         process.exit(0);
       }
 
@@ -58,9 +58,11 @@ function main() {
         ? validatePlan(content, filePath)
         : isVerification
           ? validateVerification(content, filePath)
-          : validateSummary(content, filePath);
+          : isRoadmap
+            ? validateRoadmap(content, filePath)
+            : validateSummary(content, filePath);
 
-      const eventType = isPlan ? 'plan-validated' : isVerification ? 'verification-validated' : 'summary-validated';
+      const eventType = isPlan ? 'plan-validated' : isVerification ? 'verification-validated' : isRoadmap ? 'roadmap-validated' : 'summary-validated';
 
       if (result.errors.length > 0) {
         // Structural errors — block and force correction
@@ -74,18 +76,14 @@ function main() {
           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 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: parts.join('\n')
+          reason: `${summary}\n\n${explanation}\n\n${remediation}`
         };
         process.stdout.write(JSON.stringify(output));
       } else if (result.warnings.length > 0) {
@@ -237,8 +235,9 @@ function checkPlanWrite(data) {
   const isPlan = basename.endsWith('PLAN.md');
   const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
   const isVerification = basename === 'VERIFICATION.md';
+  const isRoadmap = basename === 'ROADMAP.md';
 
-  if (!isPlan && !isSummary && !isVerification) return null;
+  if (!isPlan && !isSummary && !isVerification && !isRoadmap) return null;
   if (!fs.existsSync(filePath)) return null;
 
   const content = fs.readFileSync(filePath, 'utf8');
@@ -246,21 +245,21 @@ function checkPlanWrite(data) {
     ? validatePlan(content, filePath)
     : isVerification
       ? validateVerification(content, filePath)
+      : isRoadmap
+        ? validateRoadmap(content, filePath)
         : validateSummary(content, filePath);
 
-  const eventType = isPlan ? 'plan-validated' : isVerification ? 'verification-validated' : 'summary-validated';
+  const eventType = isPlan ? 'plan-validated' : isVerification ? 'verification-validated' : isRoadmap ? 'roadmap-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') } };
+    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.';
+    return { output: { decision: 'block', reason: `${summary}\n\n${explanation}\n\n${remediation}` } };
   }
 
   if (result.warnings.length > 0) {
@@ -348,6 +347,12 @@ function checkStateWrite(data) {
     result.warnings.push(bodyFixed.message);
   }
 
+  // Line count advisory
+  const lineCount = content.split('\n').length;
+  if (lineCount > 150) {
+    result.warnings.push(`Advisory: STATE.md exceeds 150 lines (${lineCount} lines). Consider trimming stale session data.`);
+  }
+
   if (result.warnings.length > 0) {
     logHook('check-plan-format', 'PostToolUse', 'warn', { file: basename, warnings: result.warnings });
     logEvent('workflow', 'state-validated', { file: basename, status: 'warn', warningCount: result.warnings.length });
@@ -424,5 +429,88 @@ function syncStateBody(content, filePath) {
   }
 }
 
-module.exports = { validatePlan, validateSummary, validateVerification, validateState, checkPlanWrite, checkStateWrite, syncStateBody };
+/**
+ * Validate ROADMAP.md structure. Returns advisory warnings only (never blocking errors).
+ *
+ * Checks:
+ * - Has a # Roadmap heading
+ * - Has at least one ## Milestone: section
+ * - Each milestone has **Phases:** line
+ * - Each ### Phase NN: has **Goal:**, **Provides:**, **Depends on:**
+ * - Progress table (if present) has valid markdown table syntax
+ *
+ * @param {string} content - Full ROADMAP.md content
+ * @param {string} _filePath - File path (unused)
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateRoadmap(content, _filePath) {
+  const errors = [];
+  const warnings = [];
+
+  // Check for # Roadmap heading
+  if (!/^#\s+(Roadmap|ROADMAP)/m.test(content)) {
+    warnings.push('Missing "# Roadmap" heading');
+  }
+
+  // Check for at least one ## Milestone: section
+  const milestoneMatches = content.match(/^##\s+Milestone:/gm);
+  if (!milestoneMatches || milestoneMatches.length === 0) {
+    warnings.push('No "## Milestone:" sections found');
+  } else {
+    // Check each milestone has **Phases:** line
+    // Split content by milestone sections
+    const milestoneBlocks = content.split(/^##\s+Milestone:/m).slice(1);
+    milestoneBlocks.forEach((block, idx) => {
+      if (!/\*\*Phases:\*\*/.test(block)) {
+        warnings.push(`Milestone ${idx + 1}: missing "**Phases:**" line`);
+      }
+    });
+  }
+
+  // Check each ### Phase NN: has Goal, Provides, Depends on
+  const phaseRegex = /^###\s+Phase\s+\d+:/gm;
+  const phaseMatches = content.match(phaseRegex);
+  if (phaseMatches) {
+    const phaseBlocks = content.split(/^###\s+Phase\s+\d+:/m).slice(1);
+    phaseBlocks.forEach((block, idx) => {
+      // Only check up to the next ### or ## heading
+      const nextHeading = block.search(/^#{2,3}\s+/m);
+      const section = nextHeading !== -1 ? block.substring(0, nextHeading) : block;
+
+      if (!/\*\*Goal:\*\*/.test(section)) {
+        warnings.push(`Phase ${idx + 1}: missing "**Goal:**"`);
+      }
+      if (!/\*\*Provides:\*\*/.test(section)) {
+        warnings.push(`Phase ${idx + 1}: missing "**Provides:**"`);
+      }
+      if (!/\*\*Depends on:\*\*/.test(section)) {
+        warnings.push(`Phase ${idx + 1}: missing "**Depends on:**"`);
+      }
+    });
+  }
+
+  // Check Progress table syntax if present
+  const progressMatch = content.match(/^##\s+Progress/m);
+  if (progressMatch) {
+    const afterProgress = content.substring(progressMatch.index);
+    const headerLine = afterProgress.split('\n').find(l => l.includes('|') && /Plans\s*Complete/i.test(l));
+    if (headerLine) {
+      // Check for separator row after header
+      const lines = afterProgress.split('\n');
+      const headerIdx = lines.findIndex(l => l.includes('|') && /Plans\s*Complete/i.test(l));
+      if (headerIdx >= 0 && headerIdx + 1 < lines.length) {
+        const sepLine = lines[headerIdx + 1];
+        if (!/^\s*\|[\s-:|]+\|\s*$/.test(sepLine)) {
+          warnings.push('Progress table: missing or malformed separator row (expected |---|---|...)');
+        }
+      }
+    } else {
+      warnings.push('Progress table: header row with "Plans Complete" column not found');
+    }
+  }
+
+  return { errors, warnings };
+}
+
+module.exports = { validatePlan, validateSummary, validateVerification, validateState, validateRoadmap, checkPlanWrite, checkStateWrite, syncStateBody };
 if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -20,6 +20,78 @@ const { logEvent } = require('./event-logger');
 
 const LIFECYCLE_STATUSES = ['planned', 'built', 'partial', 'verified'];
 
+/** Ordered lifecycle statuses for regression detection. Higher index = more advanced. */
+const STATUS_ORDER = ['planned', 'partial', 'built', 'verified'];
+
+/**
+ * Determine if a STATE.md → ROADMAP.md mismatch is high-risk.
+ * High-risk scenarios:
+ *   1. Status regression: ROADMAP status is earlier in lifecycle than STATE status
+ *   2. Phase ordering gap: ROADMAP table skips phase numbers (e.g., 01 then 03)
+ *
+ * @param {string} stateContent - Contents of STATE.md
+ * @param {string} roadmapContent - Contents of ROADMAP.md
+ * @returns {boolean}
+ */
+function isHighRisk(stateContent, roadmapContent) {
+  const stateInfo = parseState(stateContent);
+  if (!stateInfo || !stateInfo.phase || !stateInfo.status) return false;
+
+  // Check status regression
+  const roadmapStatus = getRoadmapPhaseStatus(roadmapContent, stateInfo.phase);
+  if (roadmapStatus) {
+    const stateIdx = STATUS_ORDER.indexOf(stateInfo.status);
+    const roadmapIdx = STATUS_ORDER.indexOf(roadmapStatus.toLowerCase());
+    if (stateIdx !== -1 && roadmapIdx !== -1 && roadmapIdx < stateIdx) {
+      return true;
+    }
+  }
+
+  // Check phase ordering gaps
+  const phaseNumbers = getAllRoadmapPhaseNumbers(roadmapContent);
+  if (phaseNumbers.length >= 2) {
+    for (let i = 1; i < phaseNumbers.length; i++) {
+      if (phaseNumbers[i] - phaseNumbers[i - 1] > 1) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extract all phase numbers from ROADMAP.md table, sorted ascending.
+ * @param {string} content - ROADMAP.md content
+ * @returns {number[]}
+ */
+function getAllRoadmapPhaseNumbers(content) {
+  const lines = content.split('\n');
+  const numbers = [];
+  let inTable = false;
+  let phaseColIndex = -1;
+
+  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));
+        if (phaseColIndex !== -1) inTable = true;
+      }
+      continue;
+    }
+    if (/^\s*\|[\s-:|]+\|\s*$/.test(line)) continue;
+    if (!line.includes('|')) break;
+    const cols = splitTableRow(line);
+    if (cols.length > phaseColIndex) {
+      const num = parseInt(normalizePhaseNum(cols[phaseColIndex]), 10);
+      if (!isNaN(num)) numbers.push(num);
+    }
+  }
+
+  return numbers.sort((a, b) => a - b);
+}
+
 function main() {
   let input = '';
 
@@ -265,6 +337,17 @@ function checkSync(data) {
     logEvent('workflow', 'roadmap-sync', {
       phase: stateInfo.phase, stateStatus: stateInfo.status, roadmapStatus, status: 'out-of-sync'
     });
+
+    // Block on high-risk regressions, advise on non-critical drift
+    if (isHighRisk(stateContent, roadmapContent)) {
+      return {
+        output: {
+          decision: 'block',
+          reason: `ROADMAP.md status regression detected for phase ${stateInfo.phase}.\n\nPhase ${stateInfo.phase} is "${stateInfo.status}" in STATE.md but "${roadmapStatus}" in ROADMAP.md. Writing a lower-lifecycle status to ROADMAP.md would corrupt milestone tracking.\n\nUpdate ROADMAP.md to match STATE.md status ("${stateInfo.status}") or fix STATE.md if the regression is intentional.`
+        }
+      };
+    }
+
     return {
       output: {
         additionalContext: `CRITICAL: ROADMAP.md out of sync — Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
@@ -348,5 +431,61 @@ function checkFilesystemDrift(roadmapContent, phasesDir) {
   return warnings;
 }
 
-module.exports = { parseState, getRoadmapPhaseStatus, checkSync, parseRoadmapPhases, checkFilesystemDrift };
+/**
+ * Validate ROADMAP.md after a milestone is marked complete.
+ * All phases in the roadmap table must be "Verified" or "Archived".
+ * If the milestone section is already collapsed (contains "COMPLETED"), passes.
+ *
+ * @param {string} roadmapContent - ROADMAP.md content
+ * @param {string} completedMilestone - Milestone identifier (e.g., "v1.0")
+ * @returns {null|{decision: string, reason: string}} null if valid, blocking result if not
+ */
+function validatePostMilestone(roadmapContent, completedMilestone) {
+  // If milestone section is already collapsed/completed, pass
+  const collapsedPattern = new RegExp(`##\\s+Milestone\\s+${completedMilestone.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*COMPLETED`, 'i');
+  if (collapsedPattern.test(roadmapContent)) return null;
+
+  // Parse all phase statuses from the table
+  const lines = roadmapContent.split('\n');
+  let inTable = false;
+  let phaseColIndex = -1;
+  let statusColIndex = -1;
+  const unverified = [];
+
+  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;
+    }
+    if (/^\s*\|[\s-:|]+\|\s*$/.test(line)) continue;
+    if (!line.includes('|')) break;
+
+    const cols = splitTableRow(line);
+    if (cols.length <= Math.max(phaseColIndex, statusColIndex)) continue;
+
+    const phaseNum = normalizePhaseNum(cols[phaseColIndex]);
+    const status = cols[statusColIndex].toLowerCase().trim();
+
+    if (status !== 'verified' && status !== 'archived') {
+      unverified.push({ phase: phaseNum, status });
+    }
+  }
+
+  if (unverified.length > 0) {
+    const details = unverified.map(u => `Phase ${u.phase} (${u.status})`).join(', ');
+    return {
+      decision: 'block',
+      reason: `Cannot complete milestone ${completedMilestone}: unverified phases remain.\n\nThe following phases are not yet Verified or Archived: ${details}. All phases must reach Verified or Archived status before milestone completion.\n\nRun /pbr:review on each unverified phase to advance it to Verified status.`
+    };
+  }
+
+  return null;
+}
+
+module.exports = { parseState, getRoadmapPhaseStatus, checkSync, parseRoadmapPhases, checkFilesystemDrift, isHighRisk, validatePostMilestone };
 if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -305,11 +305,12 @@ function checkStateSync(data) {
   // Guard: skip STATE.md and ROADMAP.md writes (prevents circular trigger)
   if (basename === 'STATE.md' || basename === 'ROADMAP.md') return null;
 
-  // Determine if this is a SUMMARY or VERIFICATION write
+  // Determine if this is a SUMMARY, VERIFICATION, or PLAN write
   const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
   const isVerification = basename === 'VERIFICATION.md';
+  const isPlan = basename.endsWith('PLAN.md') && !basename.includes('SUMMARY');
 
-  if (!isSummary && !isVerification) return null;
+  if (!isSummary && !isVerification && !isPlan) return null;
 
   // Guard: must be inside .planning/phases/
   const normalizedPath = filePath.replace(/\\/g, '/');
@@ -501,10 +502,63 @@ function checkStateSync(data) {
     }
   }
 
+  if (isPlan) {
+    // Status ordering: only set Planning if current status is lower
+    const statusOrder = { 'not started': 0, '': 0, 'planning': 1, 'in progress': 2, 'complete': 3, 'needs fixes': 4 };
+
+    if (fs.existsSync(roadmapPath)) {
+      try {
+        const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+        const hasProgressTable = /Plans\s*Complete/i.test(roadmapContent);
+        if (!hasProgressTable) {
+          messages.push(`ROADMAP.md: No Progress table found. Add a table with columns: | Phase | Plans Complete | Status | Completed | for the current milestone phases.`);
+        } else {
+          // Read current status from the Progress table for this phase
+          const lines = roadmapContent.split('\n');
+          const paddedPhase = phaseNum.padStart(2, '0');
+          let currentStatus = '';
+          let inTable = false;
+          for (const line of lines) {
+            if (!inTable) {
+              if (line.includes('|') && /Plans\s*Complete/i.test(line)) inTable = true;
+              continue;
+            }
+            if (/^\s*\|[\s-:|]+\|\s*$/.test(line)) continue;
+            if (!line.includes('|')) break;
+            const parts = line.split('|');
+            if (parts.length < 5) continue;
+            const phaseCol = (parts[1] || '').trim();
+            const phaseMatch = phaseCol.match(/^(\d+)\./);
+            if (!phaseMatch) continue;
+            if (phaseMatch[1] === paddedPhase || String(parseInt(phaseMatch[1], 10)) === String(parseInt(phaseNum, 10))) {
+              currentStatus = (parts[3] || '').trim().toLowerCase();
+              break;
+            }
+          }
+
+          // Only update to "Planning" if current status is lower
+          const currentOrder = statusOrder[currentStatus] !== undefined ? statusOrder[currentStatus] : 0;
+          const planningOrder = statusOrder['planning'];
+          if (currentOrder < planningOrder) {
+            const plansComplete = `${artifacts.completeSummaries}/${artifacts.plans}`;
+            const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, 'Planning', null);
+            if (updatedRoadmap !== roadmapContent) {
+              atomicWrite(roadmapPath, updatedRoadmap);
+              messages.push(`ROADMAP.md: Phase ${phaseNum} → Planning`);
+            }
+          }
+        }
+      } catch (e) {
+        logHook('check-state-sync', 'PostToolUse', 'error', { reason: 'ROADMAP.md update failed', error: e.message });
+      }
+    }
+  }
+
   if (messages.length > 0) {
     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 });
+    const trigger = isSummary ? 'summary' : isVerification ? 'verification' : 'plan';
+    logEvent('workflow', 'state-sync', { phase: phaseNum, trigger, updates: messages });
     return { output: { additionalContext: msg } };
   }
 

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

@@ -29,7 +29,7 @@ const path = require('path');
 const { logHook } = require('./hook-logger');
 
 // Statuses that indicate a phase has been executed
-const ADVANCED_STATUSES = ['built', 'verified', 'complete', 'building'];
+const ADVANCED_STATUSES = ['built', 'verified', 'complete'];
 
 /**
  * Extract YAML frontmatter values from markdown content.

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

@@ -22,6 +22,46 @@ const { checkPlanWrite, checkStateWrite } = require('./check-plan-format');
 const { checkSync } = require('./check-roadmap-sync');
 const { checkStateSync } = require('./check-state-sync');
 
+// Conditionally import validateRoadmap (may not exist yet if PLAN-01 hasn't landed)
+let validateRoadmap;
+try {
+  const cpf = require('./check-plan-format');
+  validateRoadmap = cpf.validateRoadmap || null;
+} catch (_e) {
+  validateRoadmap = null;
+}
+
+/**
+ * Validate ROADMAP.md writes inside .planning/.
+ * @param {Object} data - Parsed hook input
+ * @returns {null|{output: Object}}
+ */
+function checkRoadmapWrite(data) {
+  const filePath = data.tool_input?.file_path || '';
+  if (!filePath.endsWith('ROADMAP.md')) return null;
+
+  // Only validate ROADMAP.md inside .planning/
+  const normalized = filePath.replace(/\\/g, '/');
+  if (!normalized.includes('.planning/') && !normalized.includes('.planning\\')) return null;
+
+  if (!validateRoadmap) return null;
+
+  const fs = require('fs');
+  if (!fs.existsSync(filePath)) return null;
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const errors = validateRoadmap(content);
+  if (errors && errors.length > 0) {
+    return {
+      output: {
+        additionalContext: `[ROADMAP Validation] ${errors.join('; ')}`
+      }
+    };
+  }
+
+  return null;
+}
+
 function main() {
   let input = '';
 
@@ -41,6 +81,13 @@ function main() {
         process.exit(0);
       }
 
+      // ROADMAP.md structural validation (before sync checks)
+      const roadmapResult = checkRoadmapWrite(data);
+      if (roadmapResult) {
+        process.stdout.write(JSON.stringify(roadmapResult.output));
+        process.exit(0);
+      }
+
       // Roadmap sync check (STATE.md)
       const syncResult = checkSync(data);
       if (syncResult) {

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

@@ -57,6 +57,7 @@
  *   2 = blocked (workflow violation or phase boundary enforcement)
  */
 
+const { checkAgentStateWrite } = require('./check-agent-state-write');
 const { checkWorkflow } = require('./check-skill-workflow');
 const { checkSummaryGate } = require('./check-summary-gate');
 const { checkBoundary } = require('./check-phase-boundary');
@@ -71,7 +72,14 @@ function main() {
     try {
       const data = JSON.parse(input);
 
-      // Skill workflow check first — can block
+      // Agent STATE.md write blocker — most fundamental check
+      const agentResult = checkAgentStateWrite(data);
+      if (agentResult) {
+        process.stdout.write(JSON.stringify(agentResult.output));
+        process.exit(agentResult.exitCode || 0);
+      }
+
+      // Skill workflow check — can block
       const workflowResult = checkWorkflow(data);
       if (workflowResult) {
         process.stdout.write(JSON.stringify(workflowResult.output));

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

@@ -4,7 +4,6 @@
  * SessionEnd cleanup hook.
  *
  * Removes stale planning artifacts that shouldn't persist across sessions:
- *   - .planning/.auto-next (prevents confusion on next session start)
  *   - .planning/.active-operation (stale operation lock)
  *   - .planning/.active-skill (stale skill tracking)
  *
@@ -213,9 +212,9 @@ function main() {
 
   const cleaned = [];
 
-  if (tryRemove(path.join(planningDir, '.auto-next'))) {
-    cleaned.push('.auto-next');
-  }
+  // NOTE: .auto-next is intentionally NOT cleaned here — it is a one-shot
+  // signal consumed by auto-continue.js (Stop hook). SessionEnd cleanup
+  // races with the Stop hook and would delete the signal before it is read.
   if (tryRemove(path.join(planningDir, '.active-operation'))) {
     cleaned.push('.active-operation');
   }