@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/scripts/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(); }

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

@@ -17,9 +17,86 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
+const { extractFrontmatter } = require('./lib/frontmatter');
 
 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) {
+  // Strip <details>/<summary> HTML tags so phases inside collapsed milestone blocks are found
+  const stripped = content
+    .replace(/<\/?details>/gi, '')
+    .replace(/<\/?summary>/gi, '');
+  const lines = stripped.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 = '';
 
@@ -49,7 +126,7 @@ function main() {
       if (!stateInfo || !stateInfo.phase || !stateInfo.status) {
         logHook('check-roadmap-sync', 'PostToolUse', 'skip', { reason: 'could not parse STATE.md' });
         const output = {
-          additionalContext: '[Roadmap Sync] Could not parse phase/status from STATE.md — ensure it contains **Phase**: and **Status**: fields.'
+          additionalContext: '[Roadmap Sync — WARN] Could not parse STATE.md: missing **Phase**: or **Status**: fields. Expected format: "**Phase**: 3 of 8" and "**Status**: Planning". To fix: run /pbr:health for a guided repair, or manually add the missing fields to .planning/STATE.md.'
         };
         process.stdout.write(JSON.stringify(output));
         process.exit(0);
@@ -73,7 +150,7 @@ function main() {
           status: 'missing-phase'
         });
         const output = {
-          additionalContext: `CRITICAL: Phase ${stateInfo.phase} has status "${stateInfo.status}" in STATE.md but is not listed in ROADMAP.md Progress table. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
+          additionalContext: `CRITICAL: Phase ${stateInfo.phase} has status "${stateInfo.status}" in STATE.md but is not listed in ROADMAP.md Progress table. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node pbr-tools.js state load\` to check current state.`
         };
         process.stdout.write(JSON.stringify(output));
         process.exit(0);
@@ -93,7 +170,7 @@ function main() {
         });
 
         const 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.`
+          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 pbr-tools.js state load\` to check current state.`
         };
         process.stdout.write(JSON.stringify(output));
       } else {
@@ -121,29 +198,32 @@ function main() {
 
 /**
  * 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"
+ * Tries frontmatter first (v2), falls back to body regex (legacy).
+ * Delegates frontmatter parsing to canonical extractFrontmatter.
+ * Returns { phase, status } or null if unparseable.
  */
-function parseState(content) {
+const parseState = (content) => {
+  // Try frontmatter first (v2 format)
+  const fm = extractFrontmatter(content);
+  if (fm.current_phase && fm.status) {
+    return {
+      phase: normalizePhaseNum(String(fm.current_phase)),
+      status: fm.status.toLowerCase()
+    };
+  }
+  // Fallback: body regex for legacy formats
   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.
@@ -153,7 +233,11 @@ function parseState(content) {
  *   | 01    | ...  | ...  | ...   | ...  | pending |
  */
 function getRoadmapPhaseStatus(content, phaseNum) {
-  const lines = content.split('\n');
+  // Strip <details>/<summary> HTML tags so phases inside collapsed milestone blocks are found
+  const stripped = content
+    .replace(/<\/?details>/gi, '')
+    .replace(/<\/?summary>/gi, '');
+  const lines = stripped.split('\n');
 
   let statusColIndex = -1;
   let phaseColIndex = -1;
@@ -253,7 +337,7 @@ function checkSync(data) {
     });
     return {
       output: {
-        additionalContext: `CRITICAL: Phase ${stateInfo.phase} has status "${stateInfo.status}" in STATE.md but is not listed in ROADMAP.md Progress table. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
+        additionalContext: `CRITICAL: Phase ${stateInfo.phase} has status "${stateInfo.status}" in STATE.md but is not listed in ROADMAP.md Progress table. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node pbr-tools.js state load\` to check current state.`
       }
     };
   }
@@ -265,9 +349,20 @@ 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.`
+        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 pbr-tools.js state load\` to check current state.`
       }
     };
   }
@@ -285,7 +380,11 @@ function checkSync(data) {
  */
 function parseRoadmapPhases(content) {
   const phases = new Set();
-  const lines = content.split('\n');
+  // Strip <details>/<summary> HTML tags so phases inside collapsed milestone blocks are found
+  const stripped = content
+    .replace(/<\/?details>/gi, '')
+    .replace(/<\/?summary>/gi, '');
+  const lines = stripped.split('\n');
 
   for (const line of lines) {
     // Match NN-slug patterns (at least two-digit prefix with hyphen and slug)
@@ -348,5 +447,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:verify-work 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(); }