@sienklogic/plan-build-run 2.19.0 → 2.19.2

package/plugins/pbr/scripts/lib/state.js

@@ -0,0 +1,1082 @@
+/**
+ * lib/state.cjs — STATE.md operations for Plan-Build-Run tools.
+ *
+ * Handles loading, parsing, updating, patching, and advancing STATE.md.
+ * Pure-function API: all operations take planningDir as a parameter.
+ *
+ * Hybrid module merging PBR reference features with GSD-unique utilities.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  parseYamlFrontmatter,
+  findFiles,
+  lockedFileUpdate,
+  calculateProgress,
+  determinePhaseStatus
+} = require('./core');
+
+// --- Status enum ---
+
+const STATUS_VALUES = ['idle', 'planned', 'building', 'built', 'verifying', 'verified', 'complete'];
+
+const STATUS_ALIASES = {
+  'planning': 'planned',
+  'executing': 'building',
+  'done': 'complete',
+  'completed': 'complete'
+};
+
+/**
+ * Normalize a status value to the canonical 7-value enum.
+ * Returns null if the value is not a valid status or alias.
+ *
+ * @param {string} value
+ * @returns {string|null}
+ */
+function normalizeStatus(value) {
+  if (!value || typeof value !== 'string') return null;
+  const lower = value.toLowerCase().trim();
+  if (STATUS_VALUES.includes(lower)) return lower;
+  return STATUS_ALIASES[lower] || null;
+}
+
+/**
+ * Auto-regenerate STATE.md frontmatter fields from disk scan.
+ * Overwrites plans_total, plans_complete, progress_percent from filesystem truth.
+ * Normalizes status to the 7-value enum.
+ *
+ * @param {string} content - Current STATE.md content
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {string} Updated content
+ */
+function syncStateFrontmatter(content, planningDir) {
+  const fm = parseYamlFrontmatter(content);
+  if (fm.version !== 2 && fm.current_phase === undefined) return content;
+
+  const progress = stateCheckProgress(planningDir);
+  let updated = content;
+
+  updated = updateFrontmatterField(updated, 'plans_total', String(progress.total_plans));
+  updated = updateFrontmatterField(updated, 'plans_complete', String(progress.completed_plans));
+  updated = updateFrontmatterField(updated, 'progress_percent', String(progress.percentage));
+
+  // Normalize status if present
+  if (fm.status) {
+    const normalized = normalizeStatus(fm.status);
+    if (normalized && normalized !== fm.status) {
+      updated = updateFrontmatterField(updated, 'status', normalized);
+    }
+  }
+
+  return updated;
+}
+
+// --- Parsers ---
+
+function parseStateMd(content) {
+  // Normalize CRLF to LF at parse boundary for cross-platform support
+  const normalized = content.replace(/\r\n/g, '\n');
+  const result = {
+    current_phase: null,
+    phase_name: null,
+    progress: null,
+    status: null,
+    line_count: normalized.split('\n').length,
+    format: 'frontmatter'
+  };
+
+  // Check for YAML frontmatter (version 2 format)
+  const frontmatter = parseYamlFrontmatter(normalized);
+  result.format = 'frontmatter';
+  result.current_phase = frontmatter.current_phase || null;
+  result.phase_name = frontmatter.phase_slug || frontmatter.phase_name || null;
+  result.status = frontmatter.status || null;
+  result.progress = frontmatter.progress_percent !== undefined ? frontmatter.progress_percent : null;
+  result.plans_total = frontmatter.plans_total || null;
+  result.plans_complete = frontmatter.plans_complete || null;
+  result.last_activity = frontmatter.last_activity || null;
+  result.last_command = frontmatter.last_command || null;
+  result.blockers = frontmatter.blockers || [];
+  result.velocity = frontmatter.velocity || null;
+  result.session_last = frontmatter.session_last || null;
+  result.session_stopped_at = frontmatter.session_stopped_at || null;
+  result.session_resume = frontmatter.session_resume || null;
+    return result;
+}
+
+// --- Mutation helpers ---
+
+
+/**
+ * Update a field in YAML frontmatter content.
+ * Pure function: content in, content out.
+ */
+function updateFrontmatterField(content, field, value) {
+  const match = content.match(/^(---\s*\n)([\s\S]*?)(\n---)/);
+  if (!match) return content;
+
+  const before = match[1];
+  let yaml = match[2];
+  const after = match[3];
+  const rest = content.slice(match[0].length);
+
+  // Format value: null stays bare, integers stay bare, strings get quotes
+  const isNull = value === null || value === 'null';
+  const isNum = !isNull && /^\d+$/.test(String(value));
+  const formatted = isNull ? 'null' : isNum ? value : `"${value}"`;
+
+  const fieldRegex = new RegExp(`^(${field})\\s*:.*$`, 'm');
+  if (fieldRegex.test(yaml)) {
+    yaml = yaml.replace(fieldRegex, () => `${field}: ${formatted}`);
+  } else {
+    yaml = yaml + `\n${field}: ${formatted}`;
+  }
+
+  return before + yaml + after + rest;
+}
+
+// --- Body sync ---
+
+/**
+ * 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}%`;
+}
+
+/**
+ * After updating a frontmatter field, also update the corresponding body line
+ * so both representations stay in sync. Pure function: content in, content out.
+ *
+ * Field-to-body mapping:
+ *   status          -> "Status: {value}"
+ *   plans_complete  -> "Plan: {N} of ..." (replaces the number before "of")
+ *   progress_percent-> "Progress: [{bar}] {N}%"
+ *   last_activity   -> "Last activity: {value}"
+ *   current_phase   -> "Phase: {N} of ..." (replaces the number before "of")
+ *   phase_slug      -> "Phase: N of M ({Name})" (replaces the parenthesized name)
+ *
+ * Fields without body equivalents (last_command, blockers) are no-ops.
+ *
+ * @param {string} content - Full STATE.md content (frontmatter already updated)
+ * @param {string} field - The field that was updated
+ * @param {string} value - The new value
+ * @returns {string} Content with body line also updated
+ */
+function syncBodyLine(content, field, value) {
+  switch (field) {
+    case 'status': {
+      const display = String(value).replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+      return content.replace(/^Status:\s*.+/m, `Status: ${display}`);
+    }
+    case 'plans_complete': {
+      return content.replace(/^(Plan:\s*)\d+/m, `$1${value}`);
+    }
+    case 'plans_total': {
+      return content.replace(/^(Plan:\s*\d+\s+of\s+)\d+/m, `$1${value}`);
+    }
+    case 'progress_percent': {
+      const pct = parseInt(value, 10);
+      if (isNaN(pct)) return content;
+      return content.replace(/^Progress:\s*.+/m, `Progress: ${buildProgressBar(pct)}`);
+    }
+    case 'last_activity': {
+      return content.replace(/^(Last activity:\s*).+/im, `$1${value}`);
+    }
+    case 'current_phase': {
+      return content.replace(/^(Phase:\s*)\d+/m, `$1${value}`);
+    }
+    case 'phase_slug': {
+      const name = String(value).replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+      // Replace "(OldName)" or "-- OldName" in the Phase line
+      const withParens = content.replace(/^(Phase:\s*\d+\s+of\s+\d+\s*)\(.*?\)/m, `$1(${name})`);
+      if (withParens !== content) return withParens;
+      return content.replace(/^(Phase:\s*\d+\s+of\s+\d+\s*)--\s*.+/m, `$1-- ${name}`);
+    }
+    case 'session_last': {
+      const pattern = /^Last session:\s*.+/im;
+      if (pattern.test(content)) return content.replace(pattern, `Last session: ${value}`);
+      return content;
+    }
+    case 'session_stopped_at': {
+      const pattern = /^Stopped at:\s*.+/im;
+      if (pattern.test(content)) return content.replace(pattern, `Stopped at: ${value}`);
+      return content;
+    }
+    case 'session_resume': {
+      const pattern = /^Resume:\s*.+/im;
+      if (pattern.test(content)) return content.replace(pattern, `Resume: ${value}`);
+      return content;
+    }
+    default:
+      return content;
+  }
+}
+
+// --- Commands ---
+
+/**
+ * Load full project state from .planning/ directory.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} Full state object
+ */
+function stateLoad(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const { parseRoadmapMd } = require('./roadmap');
+
+  const result = {
+    exists: false,
+    config: null,
+    state: null,
+    roadmap: null,
+    phase_count: 0,
+    current_phase: null,
+    progress: null
+  };
+
+  if (!fs.existsSync(dir)) {
+    return result;
+  }
+  result.exists = true;
+
+  // Load config.json
+  const configPath = path.join(dir, 'config.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      result.config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (_) {
+      result.config = { _error: 'Failed to parse config.json' };
+    }
+  }
+
+  // Load STATE.md
+  const statePath = path.join(dir, 'STATE.md');
+  if (fs.existsSync(statePath)) {
+    const content = fs.readFileSync(statePath, 'utf8');
+    result.state = parseStateMd(content);
+  }
+
+  // Load ROADMAP.md
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  if (fs.existsSync(roadmapPath)) {
+    const content = fs.readFileSync(roadmapPath, 'utf8');
+    result.roadmap = parseRoadmapMd(content);
+    result.phase_count = result.roadmap.phases.length;
+  }
+
+  // Extract current phase
+  if (result.state && result.state.current_phase) {
+    result.current_phase = result.state.current_phase;
+  }
+
+  // Calculate progress
+  result.progress = calculateProgress(dir);
+
+  return result;
+}
+
+/**
+ * Recalculate progress from filesystem.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} Progress object
+ */
+function stateCheckProgress(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phasesDir = path.join(dir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { phases: [], total_plans: 0, completed_plans: 0, percentage: 0 };
+  }
+
+  const phases = [];
+  let totalPlans = 0;
+  let completedPlans = 0;
+
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of entries) {
+    const phaseDir = path.join(phasesDir, entry.name);
+    const plans = findFiles(phaseDir, /PLAN.*\.md$/i);
+    const summaries = findFiles(phaseDir, /^SUMMARY-.*\.md$/);
+    const verification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
+
+    const completedSummaries = summaries.filter(s => {
+      const content = fs.readFileSync(path.join(phaseDir, s), 'utf8');
+      return /status:\s*["']?complete/i.test(content);
+    });
+
+    const phaseInfoObj = {
+      directory: entry.name,
+      plans: plans.length,
+      summaries: summaries.length,
+      completed: completedSummaries.length,
+      has_verification: verification,
+      status: determinePhaseStatus(plans.length, completedSummaries.length, summaries.length, verification, phaseDir)
+    };
+
+    phases.push(phaseInfoObj);
+    totalPlans += plans.length;
+    completedPlans += completedSummaries.length;
+  }
+
+  return {
+    phases,
+    total_plans: totalPlans,
+    completed_plans: completedPlans,
+    percentage: totalPlans > 0 ? Math.round((completedPlans / totalPlans) * 100) : 0
+  };
+}
+
+/**
+ * Atomically update a field in STATE.md using lockedFileUpdate.
+ * Updates frontmatter (v2) format STATE.md.
+ *
+ * @param {string} field - One of: current_phase, status, plans_complete, last_activity,
+ *   progress_percent, phase_slug, total_phases, last_command, blockers
+ * @param {string} value - New value (use 'now' for last_activity to auto-timestamp)
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function stateUpdate(field, value, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { success: false, error: 'STATE.md not found' };
+  }
+
+  // All 13 STATE.md frontmatter fields supported by stateUpdate
+  const validFields = [
+    'current_phase',
+    'status',
+    'plans_complete',
+    'plans_total',
+    'last_activity',
+    'progress_percent',
+    'phase_slug',
+    'last_command',
+    'blockers',
+    'velocity',
+    'session_last',
+    'session_stopped_at',
+    'session_resume'
+  ];
+  if (!validFields.includes(field)) {
+    return { success: false, error: `Invalid field: ${field}. Valid fields: ${validFields.join(', ')}` };
+  }
+
+  // Auto-timestamp
+  if (field === 'last_activity' && value === 'now') {
+    value = new Date().toISOString().slice(0, 19).replace('T', ' ');
+  }
+
+  const result = lockedFileUpdate(statePath, (content) => {
+    let updated = updateFrontmatterField(content, field, value);
+    updated = syncBodyLine(updated, field, value);
+    return updated;
+  });
+
+  if (result.success) {
+    return { success: true, field, value };
+  }
+  return { success: false, error: result.error };
+}
+
+/**
+ * Batch-update multiple STATE.md fields at once.
+ *
+ * @param {string} jsonStr - JSON string of field:value pairs
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function statePatch(jsonStr, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) return { success: false, error: "STATE.md not found" };
+  let fields;
+  try { fields = JSON.parse(jsonStr); } catch (_e) { return { success: false, error: "Invalid JSON" }; }
+  const validFields = ["current_phase", "status", "plans_complete", "plans_total", "last_activity", "progress_percent", "phase_slug", "last_command", "blockers", "velocity", "session_last", "session_stopped_at", "session_resume"];
+  const invalidFields = Object.keys(fields).filter(f => !validFields.includes(f));
+  if (invalidFields.length > 0) return { success: false, error: "Unknown fields: " + invalidFields.join(", ") };
+
+  const result = lockedFileUpdate(statePath, (content) => {
+    let updated = content;
+    for (const [field, value] of Object.entries(fields)) {
+      let val = String(value);
+      if (field === 'last_activity' && val === 'now') {
+        val = new Date().toISOString().slice(0, 19).replace('T', ' ');
+      }
+      updated = updateFrontmatterField(updated, field, val);
+      updated = syncBodyLine(updated, field, val);
+    }
+    return updated;
+  });
+
+  if (!result.success) return { success: false, error: result.error };
+  return { success: true, updated: Object.keys(fields) };
+}
+
+/**
+ * Advance the plan counter in STATE.md by 1.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function stateAdvancePlan(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) return { success: false, error: "STATE.md not found" };
+
+  let resultData = {};
+  const result = lockedFileUpdate(statePath, (content) => {
+    const planMatch = content.match(/Plan:\s*(\d+)\s+of\s+(\d+)/);
+    if (!planMatch) {
+      resultData = { error: "Could not find Plan: N of M in STATE.md" };
+      return content;
+    }
+    const current = parseInt(planMatch[1], 10);
+    const total = parseInt(planMatch[2], 10);
+    const next = Math.min(current + 1, total);
+    const progressPct = total > 0 ? Math.round((next / total) * 100) : 0;
+    resultData = { previous_plan: current, current_plan: next, total_plans: total, progress_percent: progressPct };
+
+    let updated = content;
+    updated = updateFrontmatterField(updated, 'plans_complete', String(next));
+    updated = syncBodyLine(updated, 'plans_complete', String(next));
+    updated = updateFrontmatterField(updated, 'progress_percent', String(progressPct));
+    updated = syncBodyLine(updated, 'progress_percent', String(progressPct));
+    return updated;
+  });
+
+  if (resultData.error) return { success: false, error: resultData.error };
+  if (!result.success) return { success: false, error: result.error };
+  return { success: true, ...resultData };
+}
+
+/**
+ * Record a session metric in STATE.md (history section).
+ *
+ * @param {string[]} metricArgs - CLI args like ['--duration', '30m', '--plans-completed', '3']
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function stateRecordMetric(metricArgs, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  let duration = null, plansCompleted = null;
+  for (let i = 0; i < metricArgs.length; i++) {
+    if (metricArgs[i] === "--duration" && metricArgs[i + 1]) {
+      const match = metricArgs[i + 1].match(/(\d+)(m|s|h)/);
+      if (match) { const val = parseInt(match[1], 10); const unit = match[2]; duration = unit === "h" ? val * 60 : unit === "s" ? Math.round(val / 60) : val; }
+      i++;
+    } else if (metricArgs[i] === "--plans-completed" && metricArgs[i + 1]) {
+      plansCompleted = parseInt(metricArgs[i + 1], 10); i++;
+    }
+  }
+  const parts = [];
+  if (duration !== null) parts.push("duration: " + duration + "m");
+  if (plansCompleted !== null) parts.push("plans_completed: " + plansCompleted);
+
+  // Append metric to STATE.md metrics table if present
+  if (parts.length > 0) {
+    const statePath = path.join(dir, 'STATE.md');
+    if (fs.existsSync(statePath)) {
+      lockedFileUpdate(statePath, (content) => {
+        const metricsPattern = /(##\s*Performance Metrics[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n)([\s\S]*?)(?=\n##|\n$|$)/i;
+        const metricsMatch = content.match(metricsPattern);
+        if (metricsMatch) {
+          let tableBody = metricsMatch[2].trimEnd();
+          const newRow = `| Metric | ${parts.join(', ')} |`;
+          if (tableBody.trim() === '' || tableBody.includes('None yet')) {
+            tableBody = newRow;
+          } else {
+            tableBody = tableBody + '\n' + newRow;
+          }
+          return content.replace(metricsPattern, (_match, header) => `${header}${tableBody}\n`);
+        }
+        return content;
+      });
+    }
+  }
+
+  stateUpdate("last_activity", "now", dir);
+  return { success: true, duration_minutes: duration, plans_completed: plansCompleted };
+}
+
+/**
+ * Record a velocity metric in STATE.md frontmatter.
+ * Stores metrics as a JSON string in the `velocity` field.
+ * Tracks last 5 entries per metric type and calculates trend.
+ *
+ * @param {string} metricType - Metric type (e.g., 'plan_duration', 'phase_duration')
+ * @param {number|string} value - Metric value
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success, metricType, value, trend }
+ */
+function stateRecordVelocity(metricType, value, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { success: false, error: 'STATE.md not found' };
+  }
+
+  // Read current velocity from frontmatter
+  const content = fs.readFileSync(statePath, 'utf8');
+  const parsed = parseStateMd(content);
+  let velocity = {};
+  if (parsed.velocity) {
+    try {
+      velocity = typeof parsed.velocity === 'string' ? JSON.parse(parsed.velocity) : parsed.velocity;
+    } catch (_) {
+      velocity = {};
+    }
+  }
+
+  // Initialize metric history if needed
+  if (!velocity[metricType]) {
+    velocity[metricType] = { history: [], trend: 'stable' };
+  }
+
+  const numValue = Number(value);
+  const entry = { value: numValue, timestamp: new Date().toISOString() };
+  velocity[metricType].history.push(entry);
+
+  // Keep last 5 entries
+  if (velocity[metricType].history.length > 5) {
+    velocity[metricType].history = velocity[metricType].history.slice(-5);
+  }
+
+  // Calculate trend from history
+  const hist = velocity[metricType].history;
+  if (hist.length >= 2) {
+    const recent = hist.slice(-3).map(h => h.value);
+    const avg = recent.reduce((a, b) => a + b, 0) / recent.length;
+    const first = hist[0].value;
+    if (avg < first * 0.85) {
+      velocity[metricType].trend = 'improving';
+    } else if (avg > first * 1.15) {
+      velocity[metricType].trend = 'degrading';
+    } else {
+      velocity[metricType].trend = 'stable';
+    }
+  }
+
+  // Write back via stateUpdate
+  const result = stateUpdate('velocity', JSON.stringify(velocity), dir);
+  if (!result.success) return result;
+  return { success: true, metricType, value: numValue, trend: velocity[metricType].trend };
+}
+
+/**
+ * Record session continuity info in STATE.md.
+ * Updates session_last, session_stopped_at, and session_resume fields.
+ *
+ * @param {string} stoppedAt - Description of where the session stopped
+ * @param {string} resumeFile - Path to resume file (e.g., .PROGRESS-02-01)
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success, session_last, session_stopped_at, session_resume }
+ */
+function stateRecordSession(stoppedAt, resumeFile, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const now = new Date().toISOString().slice(0, 19).replace('T', ' ');
+
+  const r1 = stateUpdate('session_last', now, dir);
+  if (!r1.success) return r1;
+
+  const r2 = stateUpdate('session_stopped_at', stoppedAt, dir);
+  if (!r2.success) return r2;
+
+  const r3 = stateUpdate('session_resume', resumeFile, dir);
+  if (!r3.success) return r3;
+
+  return { success: true, session_last: now, session_stopped_at: stoppedAt, session_resume: resumeFile };
+}
+
+/**
+ * Record an activity description with today's date in STATE.md last_activity.
+ *
+ * @param {string} description - Activity description (e.g., "Built phase 3")
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success: true, last_activity: "YYYY-MM-DD description" }
+ */
+function stateRecordActivity(description, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const today = new Date().toISOString().slice(0, 10);
+  const value = `${today} ${description}`;
+  const result = stateUpdate('last_activity', value, dir);
+  if (!result.success) return result;
+  return { success: true, last_activity: value };
+}
+
+/**
+ * Recalculate progress from filesystem and atomically update STATE.md
+ * with progress_percent, plans_complete, and plans_total.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success, percent, completed_plans, total_plans }
+ */
+function stateUpdateProgress(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { success: false, error: 'STATE.md not found' };
+  }
+
+  const progress = stateCheckProgress(dir);
+  const { percentage, completed_plans, total_plans } = progress;
+
+  const result = lockedFileUpdate(statePath, (content) => {
+    let updated = content;
+    // Update frontmatter fields
+    updated = updateFrontmatterField(updated, 'progress_percent', percentage);
+    updated = updateFrontmatterField(updated, 'plans_complete', completed_plans);
+    updated = updateFrontmatterField(updated, 'plans_total', total_plans);
+    // Update body lines
+    updated = syncBodyLine(updated, 'progress_percent', percentage);
+    updated = syncBodyLine(updated, 'plans_complete', completed_plans);
+    updated = syncBodyLine(updated, 'plans_total', total_plans);
+    return updated;
+  });
+
+  if (!result.success) return { success: false, error: result.error };
+  return { success: true, percent: percentage, completed_plans, total_plans };
+}
+
+/**
+ * Get current state status summary (minimal, for quick checks).
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { status, current_phase, phase_name }
+ */
+function stateGetStatus(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { error: 'STATE.md not found' };
+  }
+  const content = fs.readFileSync(statePath, 'utf8');
+  const parsed = parseStateMd(content);
+  return {
+    status: parsed.status,
+    current_phase: parsed.current_phase,
+    phase_name: parsed.phase_name,
+    progress: parsed.progress,
+    format: parsed.format
+  };
+}
+
+/**
+ * Take a comprehensive snapshot of project state for display/reporting.
+ * Extracts all fields, decisions, blockers, and session info from STATE.md.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} Full state snapshot
+ */
+function stateSnapshot(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { error: 'STATE.md not found' };
+  }
+
+  const content = fs.readFileSync(statePath, 'utf8');
+  const parsed = parseStateMd(content);
+
+  // Extract decisions
+  const decisions = [];
+  const decisionsMatch = content.match(/###?\s*(?:Decisions|Decisions Made)[\s\S]*?\n([\s\S]*?)(?=\n###?|\n##[^#]|$)/i);
+  if (decisionsMatch) {
+    const items = decisionsMatch[1].match(/^-\s+(.+)$/gm) || [];
+    for (const item of items) {
+      decisions.push(item.replace(/^-\s+/, '').trim());
+    }
+  }
+
+  // Extract blockers
+  const blockers = [];
+  const blockersMatch = content.match(/###?\s*(?:Blockers|Blockers\/Concerns|Concerns)[\s\S]*?\n([\s\S]*?)(?=\n###?|\n##[^#]|$)/i);
+  if (blockersMatch) {
+    const items = blockersMatch[1].match(/^-\s+(.+)$/gm) || [];
+    for (const item of items) {
+      const text = item.replace(/^-\s+/, '').trim();
+      if (text && !text.match(/^None\.?$/i)) {
+        blockers.push(text);
+      }
+    }
+  }
+
+  // Extract session info
+  const session = { last_date: null, stopped_at: null, resume_file: null };
+  const lastSessionMatch = content.match(/Last session:\s*(.+)/i);
+  if (lastSessionMatch) session.last_date = lastSessionMatch[1].trim();
+  const stoppedMatch = content.match(/Stopped at:\s*(.+)/i);
+  if (stoppedMatch) session.stopped_at = stoppedMatch[1].trim();
+  const resumeMatch = content.match(/Resume file:\s*(.+)/i);
+  if (resumeMatch) session.resume_file = resumeMatch[1].trim();
+
+  return {
+    ...parsed,
+    decisions,
+    blockers: blockers.length > 0 ? blockers : (parsed.blockers || []),
+    session
+  };
+}
+
+/**
+ * Atomically mark a phase as complete in STATE.md.
+ * Updates status to "complete" and records phase completion in last_activity,
+ * all within a single lockedFileUpdate call for atomicity.
+ *
+ * @param {number|string} phaseNum - Phase number to mark complete
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success: true, phase, status } or { success: false, error }
+ */
+function statePhaseComplete(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { success: false, error: 'STATE.md not found' };
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+  const activityValue = `${today} Phase ${phaseNum} complete`;
+
+  const result = lockedFileUpdate(statePath, (content) => {
+    let updated = content;
+    // Update frontmatter fields
+    updated = updateFrontmatterField(updated, 'status', 'complete');
+    updated = updateFrontmatterField(updated, 'last_activity', activityValue);
+    // Sync body lines
+    updated = syncBodyLine(updated, 'status', 'complete');
+    updated = syncBodyLine(updated, 'last_activity', activityValue);
+    updated = syncStateFrontmatter(updated, dir);
+    return updated;
+  });
+
+  if (!result.success) {
+    return { success: false, error: result.error };
+  }
+  return { success: true, phase: Number(phaseNum), status: 'complete' };
+}
+
+/**
+ * Re-derive state from filesystem and correct any drift in STATE.md.
+ * Compares plans_complete, plans_total, and progress_percent between
+ * the current STATE.md and the filesystem-derived values from stateCheckProgress.
+ * Corrects any differences atomically via lockedFileUpdate.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success, corrected: [...fieldNames], derived: { plans_complete, plans_total, progress_percent } }
+ */
+function stateRederive(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { success: false, error: 'STATE.md not found' };
+  }
+
+  // Derive current state from filesystem
+  const progress = stateCheckProgress(dir);
+  const derived = {
+    plans_complete: progress.completed_plans,
+    plans_total: progress.total_plans,
+    progress_percent: progress.percentage
+  };
+
+  // Read current STATE.md values
+  const content = fs.readFileSync(statePath, 'utf8');
+  const current = parseStateMd(content);
+
+  // Compare and find drifted fields
+  const corrected = [];
+  if (Number(current.plans_complete || 0) !== derived.plans_complete) {
+    corrected.push('plans_complete');
+  }
+  if (Number(current.plans_total || 0) !== derived.plans_total) {
+    corrected.push('plans_total');
+  }
+  if (Number(current.progress || 0) !== derived.progress_percent) {
+    corrected.push('progress_percent');
+  }
+
+  // If drift detected, correct atomically
+  if (corrected.length > 0) {
+    const result = lockedFileUpdate(statePath, (fileContent) => {
+      let updated = fileContent;
+      for (const field of corrected) {
+        const value = derived[field];
+        updated = updateFrontmatterField(updated, field, value);
+        updated = syncBodyLine(updated, field, value);
+      }
+      return updated;
+    });
+
+    if (!result.success) {
+      return { success: false, error: result.error };
+    }
+  }
+
+  return { success: true, corrected, derived };
+}
+
+/**
+ * Signal that the project is waiting on an external action.
+ * Creates a WAITING.json file in the .planning directory.
+ *
+ * @param {string} reason - Why the project is waiting
+ * @param {string} [expectedDuration] - Expected wait duration (e.g., 'minutes', 'hours', 'unknown')
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success, path }
+ */
+function stateSignalWaiting(reason, expectedDuration, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const waitingPath = path.join(dir, 'WAITING.json');
+  const data = {
+    status: 'waiting',
+    reason,
+    expected_duration: expectedDuration || 'unknown',
+    created_at: new Date().toISOString(),
+    signal: 'waiting'
+  };
+  fs.writeFileSync(waitingPath, JSON.stringify(data, null, 2), 'utf-8');
+  return { success: true, path: waitingPath };
+}
+
+/**
+ * Clear the waiting signal by removing WAITING.json.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success, was_waiting }
+ */
+function stateSignalResume(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const waitingPath = path.join(dir, 'WAITING.json');
+  if (fs.existsSync(waitingPath)) {
+    fs.unlinkSync(waitingPath);
+    return { success: true, was_waiting: true };
+  }
+  return { success: true, was_waiting: false };
+}
+
+/**
+ * Check if the project is currently in a waiting state.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object|null} Parsed WAITING.json contents, or null if not waiting
+ */
+function stateCheckWaiting(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const waitingPath = path.join(dir, 'WAITING.json');
+  if (!fs.existsSync(waitingPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(waitingPath, 'utf-8'));
+  } catch (_) { return null; }
+}
+
+/**
+ * Reconcile STATE.md with ROADMAP.md by re-deriving phases_total and
+ * current_phase from the active milestone, and detecting phantom phase
+ * rows (ROADMAP.md progress rows with no directory on disk).
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { corrected: boolean, changes: string[], phantoms: string[] }
+ */
+function stateReconcile(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  const phasesDir = path.join(dir, 'phases');
+
+  const changes = [];
+  const phantoms = [];
+
+  if (!fs.existsSync(statePath)) {
+    return { corrected: false, changes: [], phantoms: [], error: 'STATE.md not found' };
+  }
+  if (!fs.existsSync(roadmapPath)) {
+    return { corrected: false, changes: [], phantoms: [], error: 'ROADMAP.md not found' };
+  }
+
+  // Parse ROADMAP.md to get phase list
+  const { parseRoadmapMd } = require('./roadmap');
+  const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+  const roadmap = parseRoadmapMd(roadmapContent);
+
+  // Get actual phase directories on disk
+  const dirsOnDisk = new Set();
+  if (fs.existsSync(phasesDir)) {
+    for (const entry of fs.readdirSync(phasesDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && /^\d{2}-/.test(entry.name)) {
+        const numMatch = entry.name.match(/^(\d+)/);
+        if (numMatch) dirsOnDisk.add(parseInt(numMatch[1], 10));
+      }
+    }
+  }
+
+  // Filter roadmap phases to active milestone (non-complete/shipped phases,
+  // or all phases if no milestone distinction is available)
+  const completeStatuses = new Set(['complete', 'completed', 'verified', 'shipped']);
+  const activePhases = [];
+
+  for (const phase of roadmap.phases) {
+    const numMatch = String(phase.number).match(/^(\d+)/);
+    if (!numMatch) continue;
+    const phaseNum = parseInt(numMatch[1], 10);
+    const status = (phase.status || '').toLowerCase().trim();
+
+    activePhases.push({ num: phaseNum, status });
+  }
+
+  // Derive correct phases_total: count of phases with directories on disk
+  // (active milestone phases that actually exist)
+  // Fallback: if roadmap parser found no phases (e.g., heading-only format
+  // not yet in table), use raw disk directory count to avoid writing 0
+  let phasesTotal = activePhases.filter(p => dirsOnDisk.has(p.num)).length;
+  if (phasesTotal === 0 && dirsOnDisk.size > 0) {
+    phasesTotal = dirsOnDisk.size;
+  }
+
+  // Derive correct current_phase: lowest phase that is NOT complete/verified/shipped
+  const nonCompletePhasesOnDisk = activePhases
+    .filter(p => dirsOnDisk.has(p.num) && !completeStatuses.has(p.status))
+    .sort((a, b) => a.num - b.num);
+  const currentPhase = nonCompletePhasesOnDisk.length > 0 ? nonCompletePhasesOnDisk[0].num : null;
+
+  // Detect phantom phases: roadmap rows with no corresponding directory
+  for (const phase of activePhases) {
+    if (!dirsOnDisk.has(phase.num)) {
+      const label = `Phase ${String(phase.num).padStart(2, '0')} (status: ${phase.status || 'unknown'})`;
+      phantoms.push(label);
+    }
+  }
+
+  // Read current STATE.md and compute corrections
+  const stateContent = fs.readFileSync(statePath, 'utf8');
+  const parsed = parseStateMd(stateContent);
+
+  const fieldsToUpdate = {};
+  if (phasesTotal !== Number(parsed.plans_total || 0)) {
+    fieldsToUpdate.plans_total = phasesTotal;
+    changes.push(`plans_total: ${parsed.plans_total || 0} -> ${phasesTotal}`);
+  }
+
+  // When no active phases remain (e.g., after milestone complete archives all phases),
+  // reset STATE.md to idle state so downstream consumers don't read stale data.
+  // Read raw frontmatter for accurate field checks since parseStateMd remaps some fields.
+  const rawFm = parseYamlFrontmatter(stateContent);
+
+  if (currentPhase === null && phasesTotal === 0) {
+    const currentPhaseVal = parsed.current_phase;
+    if (currentPhaseVal !== null && currentPhaseVal !== undefined && String(currentPhaseVal) !== 'null') {
+      fieldsToUpdate.current_phase = 'null';
+      changes.push(`current_phase: ${currentPhaseVal} -> null`);
+    }
+    if (rawFm.phase_slug && String(rawFm.phase_slug) !== 'null') {
+      fieldsToUpdate.phase_slug = 'null';
+      changes.push(`phase_slug: ${rawFm.phase_slug} -> null`);
+    }
+    if (rawFm.phase_name && String(rawFm.phase_name) !== 'null') {
+      fieldsToUpdate.phase_name = 'null';
+      changes.push(`phase_name: ${rawFm.phase_name} -> null`);
+    }
+    const currentStatus = (parsed.status || '').toLowerCase();
+    if (currentStatus && currentStatus !== 'idle') {
+      fieldsToUpdate.status = 'idle';
+      changes.push(`status: ${parsed.status} -> idle`);
+    }
+    if (Number(rawFm.progress_percent || 0) !== 0) {
+      fieldsToUpdate.progress_percent = 0;
+      changes.push(`progress_percent: ${rawFm.progress_percent || 0} -> 0`);
+    }
+    if (Number(parsed.plans_complete || 0) !== 0) {
+      fieldsToUpdate.plans_complete = 0;
+      changes.push(`plans_complete: ${parsed.plans_complete || 0} -> 0`);
+    }
+    if (Number(rawFm.phases_total || 0) !== 0) {
+      fieldsToUpdate.phases_total = 0;
+      changes.push(`phases_total: ${rawFm.phases_total || 0} -> 0`);
+    }
+  } else if (currentPhase !== null && currentPhase !== Number(parsed.current_phase || 0)) {
+    fieldsToUpdate.current_phase = currentPhase;
+    changes.push(`current_phase: ${parsed.current_phase || 0} -> ${currentPhase}`);
+  }
+
+  // Apply corrections atomically
+  if (Object.keys(fieldsToUpdate).length > 0) {
+    lockedFileUpdate(statePath, (content) => {
+      let updated = content;
+      for (const [field, value] of Object.entries(fieldsToUpdate)) {
+        updated = updateFrontmatterField(updated, field, value);
+        updated = syncBodyLine(updated, field, value);
+      }
+      return updated;
+    });
+  }
+
+  return { corrected: changes.length > 0, changes, phantoms };
+}
+
+/**
+ * Create a timestamped backup of STATE.md and ROADMAP.md.
+ * Writes a JSON file to .planning/.state-backup-{timestamp}.json
+ * containing the raw content of both files plus metadata.
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {{ backed_up: boolean, path: string|null, files: string[] }}
+ */
+function stateBackup(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = path.join(dir, `.state-backup-${timestamp}.json`);
+
+  const backup = { timestamp: new Date().toISOString(), files: {} };
+  let fileCount = 0;
+
+  for (const [name, filePath] of [['STATE.md', statePath], ['ROADMAP.md', roadmapPath]]) {
+    if (fs.existsSync(filePath)) {
+      backup.files[name] = fs.readFileSync(filePath, 'utf8');
+      fileCount++;
+    }
+  }
+
+  if (fileCount === 0) {
+    return { backed_up: false, path: null, files: [] };
+  }
+
+  fs.writeFileSync(backupPath, JSON.stringify(backup, null, 2));
+  return { backed_up: true, path: backupPath, files: Object.keys(backup.files) };
+}
+
+module.exports = {
+  parseStateMd,
+  updateFrontmatterField,
+  syncBodyLine,
+  buildProgressBar,
+  stateLoad,
+  stateCheckProgress,
+  stateUpdate,
+  statePatch,
+  stateAdvancePlan,
+  stateRecordMetric,
+  stateRecordActivity,
+  stateUpdateProgress,
+  stateGetStatus,
+  stateSnapshot,
+  statePhaseComplete,
+  stateRederive,
+  stateRecordVelocity,
+  stateRecordSession,
+  stateSignalWaiting,
+  stateSignalResume,
+  stateCheckWaiting,
+  stateReconcile,
+  stateBackup,
+  syncStateFrontmatter,
+  normalizeStatus,
+  STATUS_VALUES
+};