@sienklogic/plan-build-run 2.18.1 → 2.19.1

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

@@ -26,7 +26,82 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
-const { atomicWrite } = require('./pbr-tools');
+
+/**
+ * Path to PBR lib modules for lazy-requiring state/core functions.
+ * Lazy-loaded to avoid circular dependency issues at module load time.
+ */
+const pbrToolsPath = path.join(__dirname, 'lib');
+
+/** @returns {typeof import('./lib/state')} */
+function getStateLib() {
+  return require(path.join(pbrToolsPath, 'state'));
+}
+
+/** @returns {typeof import('./lib/core')} */
+function getCoreLib() {
+  return require(path.join(pbrToolsPath, 'core'));
+}
+
+/** @returns {typeof import('./lib/state-queue')} */
+function getQueueLib() {
+  return require(path.join(pbrToolsPath, 'state-queue'));
+}
+
+/**
+ * Module-level mtime cache for dirty flag detection.
+ * Keyed by absolute file path, value is the mtimeMs after our last write.
+ * Used to detect external edits between state-sync invocations.
+ */
+const _lastWriteTimes = new Map();
+
+/**
+ * Clear the mtime cache. Exported for testing.
+ */
+function clearMtimeCache() {
+  _lastWriteTimes.clear();
+}
+
+/**
+ * Check if a file has been externally modified since our last write.
+ * Returns true if dirty (external edit detected), false if clean.
+ * On first call for a file (no cached mtime), records current mtime and returns false.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {boolean} true if external edit detected
+ */
+function isDirty(filePath) {
+  try {
+    const currentMtime = fs.statSync(filePath).mtimeMs;
+    const lastMtime = _lastWriteTimes.get(filePath);
+
+    if (lastMtime === undefined) {
+      // First run — record current mtime, allow write
+      _lastWriteTimes.set(filePath, currentMtime);
+      return false;
+    }
+
+    // If mtime differs from what we last wrote, someone else edited it
+    return currentMtime !== lastMtime;
+  } catch (_e) {
+    // File doesn't exist or stat failed — not dirty
+    return false;
+  }
+}
+
+/**
+ * Record the current mtime of a file after we wrote it.
+ *
+ * @param {string} filePath - Absolute path to the file
+ */
+function recordWriteMtime(filePath) {
+  try {
+    const mtime = fs.statSync(filePath).mtimeMs;
+    _lastWriteTimes.set(filePath, mtime);
+  } catch (_e) {
+    // Best effort
+  }
+}
 
 /**
  * Extract phase number from a phase directory name.
@@ -49,7 +124,7 @@ function extractPhaseNum(dirName) {
 function countPhaseArtifacts(phaseDir) {
   try {
     const files = fs.readdirSync(phaseDir);
-    const plans = files.filter(f => /-PLAN\.md$/.test(f));
+    const plans = files.filter(f => /PLAN.*\.md$/i.test(f));
     const summaries = files.filter(f => /SUMMARY.*\.md$/.test(f) || /.*SUMMARY.*\.md$/.test(f));
 
     // Filter for summaries that have status: complete in frontmatter
@@ -94,12 +169,24 @@ function updateProgressTable(content, phaseNum, plansComplete, status, completed
 
   // Find the Progress table by looking for a header row with "Plans Complete"
   let inProgressTable = false;
+  let colIdx = { phase: -1, plans: -1, status: -1, completed: -1 };
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
 
     if (!inProgressTable) {
-      if (line.includes('|') && /Plans\s*Complete/i.test(line)) {
+      if (line.includes('|') && /Plans?\s*Complete/i.test(line)) {
+        // Dynamically detect column positions from header row
+        const headers = line.split('|').map(h => h.trim().toLowerCase());
+        colIdx = {
+          phase: headers.findIndex(h => /phase/i.test(h)),
+          milestone: headers.findIndex(h => /milestone/i.test(h)),
+          plans: headers.findIndex(h => /plans?\s*complete/i.test(h)),
+          status: headers.findIndex(h => /status/i.test(h)),
+          completed: headers.findIndex(h => /completed/i.test(h))
+        };
+        // Need at least phase and plans columns
+        if (colIdx.phase === -1) colIdx.phase = 1; // fallback
         inProgressTable = true;
       }
       continue;
@@ -113,18 +200,22 @@ function updateProgressTable(content, phaseNum, plansComplete, status, completed
 
     // Check if this row matches our phase number
     const parts = line.split('|');
-    if (parts.length < 5) continue; // Need at least: empty | Phase | Plans | Status | Completed | empty
+    if (parts.length < 3) continue;
 
-    const phaseCol = (parts[1] || '').trim();
+    const phaseCol = (parts[colIdx.phase] || '').trim();
     const phaseMatch = phaseCol.match(/^(\d+)\./);
     if (!phaseMatch) continue;
 
     if (phaseMatch[1] === paddedPhase || String(parseInt(phaseMatch[1], 10)) === String(parseInt(phaseNum, 10))) {
-      // Update this row
-      parts[2] = ` ${plansComplete} `;
-      parts[3] = ` ${status} `;
-      if (completedDate !== undefined && completedDate !== null) {
-        parts[4] = ` ${completedDate} `;
+      // Update columns using dynamic indices
+      if (colIdx.plans !== -1 && colIdx.plans < parts.length) {
+        parts[colIdx.plans] = ` ${plansComplete} `;
+      }
+      if (colIdx.status !== -1 && colIdx.status < parts.length) {
+        parts[colIdx.status] = ` ${status} `;
+      }
+      if (completedDate !== undefined && completedDate !== null && colIdx.completed !== -1 && colIdx.completed < parts.length) {
+        parts[colIdx.completed] = ` ${completedDate} `;
       }
       lines[i] = parts.join('|');
 
@@ -136,134 +227,6 @@ function updateProgressTable(content, phaseNum, plansComplete, status, completed
   return content;
 }
 
-/**
- * Update the Current Position section in STATE.md.
- *
- * Handles the legacy (non-frontmatter) format:
- *   ## Current Position
- *   Phase: 1 of 10 (Setup)
- *   Plan: 0 of 2 in current phase
- *   Status: Ready to plan
- *   Last activity: 2026-02-08 -- Project initialized
- *   Progress: [████░░░░░░░░░░░░░░░░] 20%
- *
- * @param {string} content - Full STATE.md content
- * @param {object} updates - Fields to update
- * @param {string} [updates.planLine] - New Plan: line value (e.g., "2 of 3 in current phase")
- * @param {string} [updates.status] - New Status: value (e.g., "Building")
- * @param {string} [updates.lastActivity] - New Last activity: value
- * @param {number} [updates.progressPct] - New progress percentage (0-100)
- * @returns {string} Updated content
- */
-function updateStatePosition(content, updates) {
-  const lines = content.split('\n');
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-
-    if (updates.phaseLine !== undefined && /^Phase:\s/.test(line)) {
-      lines[i] = `Phase: ${updates.phaseLine}`;
-    }
-
-    if (updates.planLine !== undefined && /^Plan:\s/.test(line)) {
-      lines[i] = `Plan: ${updates.planLine}`;
-    }
-
-    if (updates.status !== undefined && /^Status:\s/.test(line)) {
-      lines[i] = `Status: ${updates.status}`;
-    }
-
-    if (updates.lastActivity !== undefined && /^Last activity:\s/i.test(line)) {
-      lines[i] = `Last activity: ${updates.lastActivity}`;
-    }
-
-    if (updates.progressPct !== undefined && /^Progress:\s/.test(line)) {
-      lines[i] = `Progress: ${buildProgressBar(updates.progressPct)}`;
-    }
-  }
-
-  // Also update frontmatter fields if present
-  if (content.startsWith('---')) {
-    const fmEnd = content.indexOf('---', 3);
-    if (fmEnd !== -1) {
-      let fm = content.substring(0, fmEnd + 3);
-      const body = content.substring(fmEnd + 3);
-
-      if (updates.fmCurrentPhase !== undefined) {
-        fm = fm.replace(/^(current_phase:\s*).*/m, (_, p) => `${p}${updates.fmCurrentPhase}`);
-      }
-      if (updates.fmTotalPhases !== undefined) {
-        fm = fm.replace(/^(total_phases:\s*).*/m, (_, p) => `${p}${updates.fmTotalPhases}`);
-      }
-      if (updates.fmPhaseSlug !== undefined) {
-        fm = fm.replace(/^(phase_slug:\s*).*/m, (_, p) => `${p}"${updates.fmPhaseSlug}"`);
-      }
-      if (updates.fmPhaseName !== undefined) {
-        fm = fm.replace(/^(phase_name:\s*).*/m, (_, p) => `${p}"${updates.fmPhaseName}"`);
-      }
-      if (updates.fmPlansComplete !== undefined) {
-        fm = fm.replace(/^(plans_complete:\s*).*/m, (_, p) => `${p}${updates.fmPlansComplete}`);
-      }
-      if (updates.fmStatus !== undefined) {
-        fm = fm.replace(/^(status:\s*).*/m, (_, p) => `${p}"${updates.fmStatus}"`);
-      }
-      if (updates.fmLastActivity !== undefined) {
-        fm = fm.replace(/^(last_activity:\s*).*/m, (_, p) => `${p}"${updates.fmLastActivity}"`);
-      }
-      if (updates.fmProgressPct !== undefined) {
-        fm = fm.replace(/^(progress_percent:\s*).*/m, (_, p) => `${p}${updates.fmProgressPct}`);
-      }
-
-      // Reconstruct with updated frontmatter + body with line updates
-      const updatedBody = updateStatePositionBody(body, updates);
-      return fm + updatedBody;
-    }
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Update only the body (after frontmatter) of STATE.md.
- */
-function updateStatePositionBody(body, updates) {
-  const lines = body.split('\n');
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-
-    if (updates.phaseLine !== undefined && /^Phase:\s/.test(line)) {
-      lines[i] = `Phase: ${updates.phaseLine}`;
-    }
-    if (updates.planLine !== undefined && /^Plan:\s/.test(line)) {
-      lines[i] = `Plan: ${updates.planLine}`;
-    }
-    if (updates.status !== undefined && /^Status:\s/.test(line)) {
-      lines[i] = `Status: ${updates.status}`;
-    }
-    if (updates.lastActivity !== undefined && /^Last activity:\s/i.test(line)) {
-      lines[i] = `Last activity: ${updates.lastActivity}`;
-    }
-    if (updates.progressPct !== undefined && /^Progress:\s/.test(line)) {
-      lines[i] = `Progress: ${buildProgressBar(updates.progressPct)}`;
-    }
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Build a text progress bar: [████░░░░░░░░░░░░░░░░] 20%
- * @param {number} pct - Percentage 0-100
- * @returns {string}
- */
-function buildProgressBar(pct) {
-  const width = 20;
-  const filled = Math.round((pct / 100) * width);
-  const empty = width - filled;
-  return `[${'█'.repeat(filled)}${'░'.repeat(empty)}] ${pct}%`;
-}
-
 /**
  * Calculate overall progress percentage from all phase directories.
  * Counts completed summaries vs total plans across all phases.
@@ -305,11 +268,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 = /PLAN.*\.md$/i.test(basename) && !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, '/');
@@ -325,7 +289,7 @@ function checkStateSync(data) {
     return null;
   }
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const roadmapPath = path.join(planningDir, 'ROADMAP.md');
   const statePath = path.join(planningDir, 'STATE.md');
@@ -347,9 +311,9 @@ function checkStateSync(data) {
   const phaseSlug = phaseDirName.replace(/^\d+-/, '');
   const phaseName = phaseSlug.replace(/-/g, ' ')
     .replace(/\b\w/g, c => c.toUpperCase());
-  let totalPhases = 0;
+  let _totalPhases = 0;
   try {
-    totalPhases = fs.readdirSync(phasesDir, { withFileTypes: true })
+    _totalPhases = fs.readdirSync(phasesDir, { withFileTypes: true })
       .filter(e => e.isDirectory() && /^\d+-/.test(e.name)).length;
   } catch (_e) { /* leave as 0 */ }
 
@@ -359,52 +323,72 @@ function checkStateSync(data) {
     const newStatus = allComplete ? 'Complete' : 'In progress';
     const completedDate = allComplete ? today : null;
 
-    // Update ROADMAP.md Progress table
+    // Update ROADMAP.md Progress table via lockedFileUpdate
     if (fs.existsSync(roadmapPath)) {
       try {
-        const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
-        const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, newStatus, completedDate);
-        if (updatedRoadmap !== roadmapContent) {
-          atomicWrite(roadmapPath, updatedRoadmap);
-          messages.push(`ROADMAP.md: Phase ${phaseNum} → ${plansComplete} plans, ${newStatus}`);
+        if (isDirty(roadmapPath)) {
+          logHook('check-state-sync', 'PostToolUse', 'skip-dirty', { file: path.basename(roadmapPath), reason: 'external edit detected' });
+        } else {
+          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 {
+            const coreLib = getCoreLib();
+            coreLib.lockedFileUpdate(roadmapPath, (content) => {
+              return updateProgressTable(content, phaseNum, plansComplete, newStatus, completedDate);
+            });
+            recordWriteMtime(roadmapPath);
+            messages.push(`ROADMAP.md: Phase ${phaseNum} → ${plansComplete} plans, ${newStatus}`);
+          }
         }
       } catch (e) {
         logHook('check-state-sync', 'PostToolUse', 'error', { reason: 'ROADMAP.md update failed', error: e.message });
       }
     }
 
-    // Update STATE.md
+    // Drain any queued state updates before our own write
+    try {
+      const { stateDrain } = getQueueLib();
+      const drainResult = stateDrain(planningDir);
+      if (drainResult.success && drainResult.processed > 0) {
+        logHook('check-state-sync', 'PostToolUse', 'drain', { processed: drainResult.processed });
+      }
+    } catch (_drainErr) {
+      // Queue drain is best-effort; don't block the sync
+    }
+
+    // Update STATE.md via lib/state.cjs (locked, atomic per-field updates)
     if (fs.existsSync(statePath)) {
       try {
-        const stateContent = fs.readFileSync(statePath, 'utf8');
-        const overallPct = calculateOverallProgress(phasesDir);
-        const stateUpdates = {
-          planLine: `${artifacts.completeSummaries} of ${artifacts.plans} in current phase`,
-          status: allComplete ? 'Built' : 'Building',
-          lastActivity: `${today} -- Phase ${phaseNum} plan completed`,
-          progressPct: overallPct,
-          fmPlansComplete: artifacts.completeSummaries,
-          fmStatus: allComplete ? 'built' : 'building',
-          fmLastActivity: today,
-          fmProgressPct: overallPct
-        };
-
-        // Detect phase mismatch and add phase updates
-        const currentPhaseMatch = stateContent.match(/^current_phase:\s*(\d+)/m)
-          || stateContent.match(/^Phase:\s*(\d+)\s/m);
-        const currentPhase = currentPhaseMatch ? parseInt(currentPhaseMatch[1], 10) : null;
-        if (currentPhase !== null && currentPhase !== phaseNumInt) {
-          stateUpdates.phaseLine = `${phaseNumInt} of ${totalPhases} (${phaseName})`;
-          stateUpdates.fmCurrentPhase = phaseNumInt;
-          stateUpdates.fmTotalPhases = totalPhases;
-          stateUpdates.fmPhaseSlug = phaseSlug;
-          stateUpdates.fmPhaseName = phaseName;
-          messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);
-        }
-
-        const updatedState = updateStatePosition(stateContent, stateUpdates);
-        if (updatedState !== stateContent) {
-          atomicWrite(statePath, updatedState);
+        if (isDirty(statePath)) {
+          logHook('check-state-sync', 'PostToolUse', 'skip-dirty', { file: path.basename(statePath), reason: 'external edit detected' });
+        } else {
+          const stateContent = fs.readFileSync(statePath, 'utf8');
+          const overallPct = calculateOverallProgress(phasesDir);
+          const stateLib = getStateLib();
+
+          stateLib.stateUpdate('plans_complete', String(artifacts.completeSummaries), planningDir);
+          stateLib.stateUpdate('status', allComplete ? 'built' : 'building', planningDir);
+          stateLib.stateUpdate('last_activity', `${today} -- Phase ${phaseNum} plan completed`, planningDir);
+          stateLib.stateUpdate('progress_percent', String(overallPct), planningDir);
+
+          // Detect phase mismatch and add phase updates
+          const currentPhaseMatch = stateContent.match(/^current_phase:\s*(\d+)/m)
+            || stateContent.match(/^Phase:\s*(\d+)\s/m);
+          const currentPhase = currentPhaseMatch ? parseInt(currentPhaseMatch[1], 10) : null;
+          if (currentPhase !== null && currentPhase !== phaseNumInt) {
+            stateLib.stateUpdate('current_phase', String(phaseNumInt), planningDir);
+            stateLib.stateUpdate('phase_slug', phaseSlug, planningDir);
+            // phase_name frontmatter not in stateUpdate's valid fields — use lockedFileUpdate directly
+            const coreLib = getCoreLib();
+            coreLib.lockedFileUpdate(statePath, (content) => {
+              return stateLib.updateFrontmatterField(content, 'phase_name', phaseName);
+            });
+            messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);
+          }
+
+          recordWriteMtime(statePath);
           messages.push(`STATE.md: ${artifacts.completeSummaries}/${artifacts.plans} plans, ${overallPct}%`);
         }
       } catch (e) {
@@ -439,50 +423,71 @@ function checkStateSync(data) {
     const completedDate = isPassed ? today : null;
     const plansComplete = `${artifacts.completeSummaries}/${artifacts.plans}`;
 
-    // Update ROADMAP.md Progress table
+    // Update ROADMAP.md Progress table via lockedFileUpdate
     if (fs.existsSync(roadmapPath)) {
       try {
-        const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
-        const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, roadmapStatus, completedDate);
-        if (updatedRoadmap !== roadmapContent) {
-          atomicWrite(roadmapPath, updatedRoadmap);
-          messages.push(`ROADMAP.md: Phase ${phaseNum} → ${roadmapStatus}`);
+        if (isDirty(roadmapPath)) {
+          logHook('check-state-sync', 'PostToolUse', 'skip-dirty', { file: path.basename(roadmapPath), reason: 'external edit detected' });
+        } else {
+          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 {
+            const coreLib = getCoreLib();
+            coreLib.lockedFileUpdate(roadmapPath, (content) => {
+              return updateProgressTable(content, phaseNum, plansComplete, roadmapStatus, completedDate);
+            });
+            recordWriteMtime(roadmapPath);
+            messages.push(`ROADMAP.md: Phase ${phaseNum} → ${roadmapStatus}`);
+          }
         }
       } catch (e) {
         logHook('check-state-sync', 'PostToolUse', 'error', { reason: 'ROADMAP.md update failed', error: e.message });
       }
     }
 
-    // Update STATE.md
+    // Drain any queued state updates before our own write
+    try {
+      const { stateDrain } = getQueueLib();
+      const drainResult = stateDrain(planningDir);
+      if (drainResult.success && drainResult.processed > 0) {
+        logHook('check-state-sync', 'PostToolUse', 'drain', { processed: drainResult.processed });
+      }
+    } catch (_drainErr) {
+      // Queue drain is best-effort; don't block the sync
+    }
+
+    // Update STATE.md via lib/state.cjs (locked, atomic per-field updates)
     if (fs.existsSync(statePath)) {
       try {
-        const stateContent = fs.readFileSync(statePath, 'utf8');
-        const overallPct = calculateOverallProgress(phasesDir);
-        const stateUpdates = {
-          status: stateStatus,
-          lastActivity: `${today} -- Phase ${phaseNum} ${isPassed ? 'verified' : 'needs fixes'}`,
-          progressPct: overallPct,
-          fmStatus: isPassed ? 'verified' : 'needs_fixes',
-          fmLastActivity: today,
-          fmProgressPct: overallPct
-        };
-
-        // Detect phase mismatch and add phase updates
-        const currentPhaseMatch = stateContent.match(/^current_phase:\s*(\d+)/m)
-          || stateContent.match(/^Phase:\s*(\d+)\s/m);
-        const currentPhase = currentPhaseMatch ? parseInt(currentPhaseMatch[1], 10) : null;
-        if (currentPhase !== null && currentPhase !== phaseNumInt) {
-          stateUpdates.phaseLine = `${phaseNumInt} of ${totalPhases} (${phaseName})`;
-          stateUpdates.fmCurrentPhase = phaseNumInt;
-          stateUpdates.fmTotalPhases = totalPhases;
-          stateUpdates.fmPhaseSlug = phaseSlug;
-          stateUpdates.fmPhaseName = phaseName;
-          messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);
-        }
-
-        const updatedState = updateStatePosition(stateContent, stateUpdates);
-        if (updatedState !== stateContent) {
-          atomicWrite(statePath, updatedState);
+        if (isDirty(statePath)) {
+          logHook('check-state-sync', 'PostToolUse', 'skip-dirty', { file: path.basename(statePath), reason: 'external edit detected' });
+        } else {
+          const stateContent = fs.readFileSync(statePath, 'utf8');
+          const overallPct = calculateOverallProgress(phasesDir);
+          const stateLib = getStateLib();
+
+          stateLib.stateUpdate('status', isPassed ? 'verified' : 'needs_fixes', planningDir);
+          stateLib.stateUpdate('last_activity', `${today} -- Phase ${phaseNum} ${isPassed ? 'verified' : 'needs fixes'}`, planningDir);
+          stateLib.stateUpdate('progress_percent', String(overallPct), planningDir);
+
+          // Detect phase mismatch and add phase updates
+          const currentPhaseMatch = stateContent.match(/^current_phase:\s*(\d+)/m)
+            || stateContent.match(/^Phase:\s*(\d+)\s/m);
+          const currentPhase = currentPhaseMatch ? parseInt(currentPhaseMatch[1], 10) : null;
+          if (currentPhase !== null && currentPhase !== phaseNumInt) {
+            stateLib.stateUpdate('current_phase', String(phaseNumInt), planningDir);
+            stateLib.stateUpdate('phase_slug', phaseSlug, planningDir);
+            // phase_name frontmatter not in stateUpdate's valid fields — use lockedFileUpdate directly
+            const coreLib = getCoreLib();
+            coreLib.lockedFileUpdate(statePath, (content) => {
+              return stateLib.updateFrontmatterField(content, 'phase_name', phaseName);
+            });
+            messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);
+          }
+
+          recordWriteMtime(statePath);
           messages.push(`STATE.md: ${stateStatus}, ${overallPct}%`);
         }
       } catch (e) {
@@ -491,10 +496,68 @@ 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}`;
+            if (isDirty(roadmapPath)) {
+              logHook('check-state-sync', 'PostToolUse', 'skip-dirty', { file: path.basename(roadmapPath), reason: 'external edit detected' });
+            } else {
+              const coreLib = getCoreLib();
+              coreLib.lockedFileUpdate(roadmapPath, (content) => {
+                return updateProgressTable(content, phaseNum, plansComplete, 'Planning', null);
+              });
+              recordWriteMtime(roadmapPath);
+              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 } };
   }
 
@@ -517,12 +580,72 @@ function main() {
       }
       process.exit(0);
     } catch (_e) {
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] check-state-sync failed: ' + _e.message }));
       process.exit(0);
     }
   });
 }
 
 if (require.main === module || process.argv[1] === __filename) { main(); }
+// Re-export lib functions for backward compatibility with existing tests.
+// These were previously defined locally but are now delegated to lib/state.cjs.
+// DEPRECATED: Use stateUpdate() from lib/state.cjs for STATE.md mutations instead.
+function buildProgressBar(pct) {
+  return getStateLib().buildProgressBar(pct);
+}
+
+/**
+ * @deprecated Use stateUpdate() from lib/state.cjs instead.
+ * Kept as a re-export shim for backward compatibility with existing tests.
+ */
+function updateStatePosition(content, updates) {
+  const stateLib = getStateLib();
+  let result = content;
+
+  // Frontmatter field updates
+  if (result.startsWith('---')) {
+    if (updates.fmCurrentPhase !== undefined)
+      result = stateLib.updateFrontmatterField(result, 'current_phase', updates.fmCurrentPhase);
+    if (updates.fmPhaseSlug !== undefined)
+      result = stateLib.updateFrontmatterField(result, 'phase_slug', updates.fmPhaseSlug);
+    if (updates.fmPhaseName !== undefined)
+      result = stateLib.updateFrontmatterField(result, 'phase_name', updates.fmPhaseName);
+    if (updates.fmPlansComplete !== undefined)
+      result = stateLib.updateFrontmatterField(result, 'plans_complete', updates.fmPlansComplete);
+    if (updates.fmStatus !== undefined)
+      result = stateLib.updateFrontmatterField(result, 'status', updates.fmStatus);
+    if (updates.fmLastActivity !== undefined)
+      result = stateLib.updateFrontmatterField(result, 'last_activity', updates.fmLastActivity);
+    if (updates.fmProgressPct !== undefined)
+      result = stateLib.updateFrontmatterField(result, 'progress_percent', updates.fmProgressPct);
+  }
+
+  // Body line updates via syncBodyLine
+  if (updates.status !== undefined)
+    result = stateLib.syncBodyLine(result, 'status', updates.status);
+  if (updates.planLine !== undefined) {
+    // planLine sets "Plan: N of M in current phase" — extract N for plans_complete sync
+    result = result.replace(/^(Plan:\s*).+/m, `$1${updates.planLine}`);
+  }
+  if (updates.phaseLine !== undefined) {
+    result = result.replace(/^(Phase:\s*).+/m, `$1${updates.phaseLine}`);
+  }
+  if (updates.lastActivity !== undefined)
+    result = stateLib.syncBodyLine(result, 'last_activity', updates.lastActivity);
+  if (updates.progressPct !== undefined)
+    result = stateLib.syncBodyLine(result, 'progress_percent', updates.progressPct);
+
+  // Legacy (no frontmatter) — update body lines directly
+  if (!content.startsWith('---')) {
+    if (updates.status !== undefined)
+      result = result.replace(/^(Status:\s*).+/m, `$1${updates.status}`);
+    if (updates.progressPct !== undefined)
+      result = result.replace(/^(Progress:\s*).+/m, `$1${buildProgressBar(updates.progressPct)}`);
+  }
+
+  return result;
+}
+
 module.exports = {
   extractPhaseNum,
   countPhaseArtifacts,
@@ -530,5 +653,6 @@ module.exports = {
   updateStatePosition,
   buildProgressBar,
   calculateOverallProgress,
-  checkStateSync
+  checkStateSync,
+  clearMtimeCache
 };