@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plan-build-run/bin/lib/state.cjs

@@ -0,0 +1,641 @@
+/**
+ * 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.cjs');
+
+// --- 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: 'legacy' // 'legacy' or 'frontmatter'
+  };
+
+  // Check for YAML frontmatter (version 2 format)
+  const frontmatter = parseYamlFrontmatter(normalized);
+  if (frontmatter.version === 2 || frontmatter.current_phase !== undefined) {
+    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 || [];
+    return result;
+  }
+
+  // Legacy regex-based parsing (version 1 format, no frontmatter)
+  // DEPRECATED (2026-02): v1 STATE.md format (no YAML frontmatter) is deprecated.
+  // New projects should use v2 (frontmatter) format, generated by /pbr:setup.
+  // v1 support will be removed in a future major version.
+  process.stderr.write('[pbr] WARNING: STATE.md uses legacy v1 format. Run /pbr:setup to migrate to v2 format.\n');
+
+  // Extract "Phase: N of M"
+  const phaseMatch = normalized.match(/Phase:\s*(\d+)\s+of\s+(\d+)/);
+  if (phaseMatch) {
+    result.current_phase = parseInt(phaseMatch[1], 10);
+    result.total_phases = parseInt(phaseMatch[2], 10);
+  }
+
+  // Extract phase name (line after "Phase:")
+  const nameMatch = normalized.match(/--\s+(.+?)(?:\n|$)/);
+  if (nameMatch) {
+    result.phase_name = nameMatch[1].trim();
+  }
+
+  // Extract progress percentage
+  const progressMatch = normalized.match(/(\d+)%/);
+  if (progressMatch) {
+    result.progress = parseInt(progressMatch[1], 10);
+  }
+
+  // Extract plan status
+  const statusMatch = normalized.match(/Status:\s*(.+?)(?:\n|$)/i);
+  if (statusMatch) {
+    result.status = statusMatch[1].trim();
+  }
+
+  return result;
+}
+
+// --- Mutation helpers ---
+
+/**
+ * Update a field in legacy (non-frontmatter) STATE.md content.
+ * Pure function: content in, content out.
+ */
+function updateLegacyStateField(content, field, value) {
+  const lines = content.replace(/\r\n/g, '\n').split('\n');
+
+  switch (field) {
+    case 'current_phase': {
+      const idx = lines.findIndex(l => /Phase:\s*\d+\s+of\s+\d+/.test(l));
+      if (idx !== -1) {
+        lines[idx] = lines[idx].replace(/(Phase:\s*)\d+/, (_, prefix) => `${prefix}${value}`);
+      }
+      break;
+    }
+    case 'status': {
+      const idx = lines.findIndex(l => /^Status:/i.test(l));
+      if (idx !== -1) {
+        lines[idx] = `Status: ${value}`;
+      } else {
+        const phaseIdx = lines.findIndex(l => /Phase:/.test(l));
+        if (phaseIdx !== -1) {
+          lines.splice(phaseIdx + 1, 0, `Status: ${value}`);
+        } else {
+          lines.push(`Status: ${value}`);
+        }
+      }
+      break;
+    }
+    case 'plans_complete': {
+      const idx = lines.findIndex(l => /Plan:\s*\d+\s+of\s+\d+/.test(l));
+      if (idx !== -1) {
+        lines[idx] = lines[idx].replace(/(Plan:\s*)\d+/, (_, prefix) => `${prefix}${value}`);
+      }
+      break;
+    }
+    case 'last_activity': {
+      const idx = lines.findIndex(l => /^Last Activity:/i.test(l));
+      if (idx !== -1) {
+        lines[idx] = `Last Activity: ${value}`;
+      } else {
+        const statusIdx = lines.findIndex(l => /^Status:/i.test(l));
+        if (statusIdx !== -1) {
+          lines.splice(statusIdx + 1, 0, `Last Activity: ${value}`);
+        } else {
+          lines.push(`Last Activity: ${value}`);
+        }
+      }
+      break;
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 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: integers stay bare, strings get quotes
+  const isNum = /^\d+$/.test(String(value));
+  const formatted = 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}`);
+    }
+    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.cjs');
+
+  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.
+ * Supports both legacy and frontmatter (v2) formats.
+ *
+ * @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 9 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'
+  ];
+  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) => {
+    const fm = parseYamlFrontmatter(content);
+    if (fm.version === 2 || fm.current_phase !== undefined) {
+      let updated = updateFrontmatterField(content, field, value);
+      updated = syncBodyLine(updated, field, value);
+      return updated;
+    }
+    return updateLegacyStateField(content, field, value);
+  });
+
+  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"];
+  const updates = [], errors = [];
+  for (const [field, value] of Object.entries(fields)) {
+    if (!validFields.includes(field)) { errors.push("Unknown field: " + field); continue; }
+    try { stateUpdate(field, String(value), dir); updates.push(field); } catch (e) { errors.push(field + ": " + e.message); }
+  }
+  return { success: errors.length === 0, updated: updates, errors: errors.length > 0 ? errors : undefined };
+}
+
+/**
+ * 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" };
+  const stateContent = fs.readFileSync(statePath, "utf8");
+  const planMatch = stateContent.match(/Plan:\s*(\d+)\s+of\s+(\d+)/);
+  if (!planMatch) return { success: false, error: "Could not find Plan: N of M in STATE.md" };
+  const current = parseInt(planMatch[1], 10), total = parseInt(planMatch[2], 10);
+  const next = Math.min(current + 1, total);
+  stateUpdate("plans_complete", String(next), dir);
+  const progressPct = total > 0 ? Math.round((next / total) * 100) : 0;
+  stateUpdate("progress_percent", String(progressPct), dir);
+  return { success: true, previous_plan: current, current_plan: next, total_plans: total, progress_percent: progressPct };
+}
+
+/**
+ * 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 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
+  };
+}
+
+module.exports = {
+  parseStateMd,
+  updateLegacyStateField,
+  updateFrontmatterField,
+  syncBodyLine,
+  buildProgressBar,
+  stateLoad,
+  stateCheckProgress,
+  stateUpdate,
+  statePatch,
+  stateAdvancePlan,
+  stateRecordMetric,
+  stateRecordActivity,
+  stateUpdateProgress,
+  stateGetStatus,
+  stateSnapshot
+};