gsd-opencode 1.20.3 → 1.22.0

package/get-shit-done/bin/lib/state.cjs

@@ -4,7 +4,20 @@
 
 const fs = require('fs');
 const path = require('path');
-const { loadConfig, output, error } = require('./core.cjs');
+const { escapeRegex, loadConfig, getMilestoneInfo, getMilestonePhaseFilter, output, error } = require('./core.cjs');
+const { extractFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
+
+// Shared helper: extract a field value from STATE.md content.
+// Supports both **Field:** bold and plain Field: format.
+function stateExtractField(content, fieldName) {
+  const escaped = escapeRegex(fieldName);
+  const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*\\s*(.+)`, 'i');
+  const boldMatch = content.match(boldPattern);
+  if (boldMatch) return boldMatch[1].trim();
+  const plainPattern = new RegExp(`^${escaped}:\\s*(.+)`, 'im');
+  const plainMatch = content.match(plainPattern);
+  return plainMatch ? plainMatch[1].trim() : null;
+}
 
 function cmdStateLoad(cwd, raw) {
   const config = loadConfig(cwd);
@@ -64,11 +77,19 @@ function cmdStateGet(cwd, section, raw) {
     // Try to find markdown section or field
     const fieldEscaped = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
-    // Check for **field:** value
-    const fieldPattern = new RegExp(`\\*\\*${fieldEscaped}:\\*\\*\\s*(.*)`, 'i');
-    const fieldMatch = content.match(fieldPattern);
-    if (fieldMatch) {
-      output({ [section]: fieldMatch[1].trim() }, raw, fieldMatch[1].trim());
+    // Check for **field:** value (bold format)
+    const boldPattern = new RegExp(`\\*\\*${fieldEscaped}:\\*\\*\\s*(.*)`, 'i');
+    const boldMatch = content.match(boldPattern);
+    if (boldMatch) {
+      output({ [section]: boldMatch[1].trim() }, raw, boldMatch[1].trim());
+      return;
+    }
+
+    // Check for field: value (plain format)
+    const plainPattern = new RegExp(`^${fieldEscaped}:\\s*(.*)`, 'im');
+    const plainMatch = content.match(plainPattern);
+    if (plainMatch) {
+      output({ [section]: plainMatch[1].trim() }, raw, plainMatch[1].trim());
       return;
     }
 
@@ -86,6 +107,17 @@ function cmdStateGet(cwd, section, raw) {
   }
 }
 
+function readTextArgOrFile(cwd, value, filePath, label) {
+  if (!filePath) return value;
+
+  const resolvedPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  try {
+    return fs.readFileSync(resolvedPath, 'utf-8').trimEnd();
+  } catch {
+    throw new Error(`${label} file not found: ${filePath}`);
+  }
+}
+
 function cmdStatePatch(cwd, patches, raw) {
   const statePath = path.join(cwd, '.planning', 'STATE.md');
   try {
@@ -94,10 +126,15 @@ function cmdStatePatch(cwd, patches, raw) {
 
     for (const [field, value] of Object.entries(patches)) {
       const fieldEscaped = field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      const pattern = new RegExp(`(\\*\\*${fieldEscaped}:\\*\\*\\s*)(.*)`, 'i');
+      // Try **Field:** bold format first, then plain Field: format
+      const boldPattern = new RegExp(`(\\*\\*${fieldEscaped}:\\*\\*\\s*)(.*)`, 'i');
+      const plainPattern = new RegExp(`(^${fieldEscaped}:\\s*)(.*)`, 'im');
 
-      if (pattern.test(content)) {
-        content = content.replace(pattern, `$1${value}`);
+      if (boldPattern.test(content)) {
+        content = content.replace(boldPattern, (_match, prefix) => `${prefix}${value}`);
+        results.updated.push(field);
+      } else if (plainPattern.test(content)) {
+        content = content.replace(plainPattern, (_match, prefix) => `${prefix}${value}`);
         results.updated.push(field);
       } else {
         results.failed.push(field);
@@ -105,7 +142,7 @@ function cmdStatePatch(cwd, patches, raw) {
     }
 
     if (results.updated.length > 0) {
-      fs.writeFileSync(statePath, content, 'utf-8');
+      writeStateMd(statePath, content, cwd);
     }
 
     output(results, raw, results.updated.length > 0 ? 'true' : 'false');
@@ -123,10 +160,16 @@ function cmdStateUpdate(cwd, field, value) {
   try {
     let content = fs.readFileSync(statePath, 'utf-8');
     const fieldEscaped = field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const pattern = new RegExp(`(\\*\\*${fieldEscaped}:\\*\\*\\s*)(.*)`, 'i');
-    if (pattern.test(content)) {
-      content = content.replace(pattern, `$1${value}`);
-      fs.writeFileSync(statePath, content, 'utf-8');
+    // Try **Field:** bold format first, then plain Field: format
+    const boldPattern = new RegExp(`(\\*\\*${fieldEscaped}:\\*\\*\\s*)(.*)`, 'i');
+    const plainPattern = new RegExp(`(^${fieldEscaped}:\\s*)(.*)`, 'im');
+    if (boldPattern.test(content)) {
+      content = content.replace(boldPattern, (_match, prefix) => `${prefix}${value}`);
+      writeStateMd(statePath, content, cwd);
+      output({ updated: true });
+    } else if (plainPattern.test(content)) {
+      content = content.replace(plainPattern, (_match, prefix) => `${prefix}${value}`);
+      writeStateMd(statePath, content, cwd);
       output({ updated: true });
     } else {
       output({ updated: false, reason: `Field "${field}" not found in STATE.md` });
@@ -139,16 +182,27 @@ function cmdStateUpdate(cwd, field, value) {
 // ─── State Progression Engine ────────────────────────────────────────────────
 
 function stateExtractField(content, fieldName) {
-  const pattern = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+)`, 'i');
-  const match = content.match(pattern);
-  return match ? match[1].trim() : null;
+  const escaped = fieldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Try **Field:** bold format first
+  const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*\\s*(.+)`, 'i');
+  const boldMatch = content.match(boldPattern);
+  if (boldMatch) return boldMatch[1].trim();
+  // Fall back to plain Field: format
+  const plainPattern = new RegExp(`^${escaped}:\\s*(.+)`, 'im');
+  const plainMatch = content.match(plainPattern);
+  return plainMatch ? plainMatch[1].trim() : null;
 }
 
 function stateReplaceField(content, fieldName, newValue) {
   const escaped = fieldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const pattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
-  if (pattern.test(content)) {
-    return content.replace(pattern, `$1${newValue}`);
+  // Try **Field:** bold format first, then plain Field: format
+  const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
+  if (boldPattern.test(content)) {
+    return content.replace(boldPattern, (_match, prefix) => `${prefix}${newValue}`);
+  }
+  const plainPattern = new RegExp(`(^${escaped}:\\s*)(.*)`, 'im');
+  if (plainPattern.test(content)) {
+    return content.replace(plainPattern, (_match, prefix) => `${prefix}${newValue}`);
   }
   return null;
 }
@@ -170,14 +224,14 @@ function cmdStateAdvancePlan(cwd, raw) {
   if (currentPlan >= totalPlans) {
     content = stateReplaceField(content, 'Status', 'Phase complete — ready for verification') || content;
     content = stateReplaceField(content, 'Last Activity', today) || content;
-    fs.writeFileSync(statePath, content, 'utf-8');
+    writeStateMd(statePath, content, cwd);
     output({ advanced: false, reason: 'last_plan', current_plan: currentPlan, total_plans: totalPlans, status: 'ready_for_verification' }, raw, 'false');
   } else {
     const newPlan = currentPlan + 1;
     content = stateReplaceField(content, 'Current Plan', String(newPlan)) || content;
     content = stateReplaceField(content, 'Status', 'Ready to execute') || content;
     content = stateReplaceField(content, 'Last Activity', today) || content;
-    fs.writeFileSync(statePath, content, 'utf-8');
+    writeStateMd(statePath, content, cwd);
     output({ advanced: true, previous_plan: currentPlan, current_plan: newPlan, total_plans: totalPlans }, raw, 'true');
   }
 }
@@ -199,7 +253,6 @@ function cmdStateRecordMetric(cwd, options, raw) {
   const metricsMatch = content.match(metricsPattern);
 
   if (metricsMatch) {
-    const tableHeader = metricsMatch[1];
     let tableBody = metricsMatch[2].trimEnd();
     const newRow = `| Phase ${phase} P${plan} | ${duration} | ${tasks || '-'} tasks | ${files || '-'} files |`;
 
@@ -209,8 +262,8 @@ function cmdStateRecordMetric(cwd, options, raw) {
       tableBody = tableBody + '\n' + newRow;
     }
 
-    content = content.replace(metricsPattern, `${tableHeader}${tableBody}\n`);
-    fs.writeFileSync(statePath, content, 'utf-8');
+    content = content.replace(metricsPattern, (_match, header) => `${header}${tableBody}\n`);
+    writeStateMd(statePath, content, cwd);
     output({ recorded: true, phase, plan, duration }, raw, 'true');
   } else {
     output({ recorded: false, reason: 'Performance Metrics section not found in STATE.md' }, raw, 'false');
@@ -238,16 +291,22 @@ function cmdStateUpdateProgress(cwd, raw) {
     }
   }
 
-  const percent = totalPlans > 0 ? Math.round(totalSummaries / totalPlans * 100) : 0;
+  const percent = totalPlans > 0 ? Math.min(100, Math.round(totalSummaries / totalPlans * 100)) : 0;
   const barWidth = 10;
   const filled = Math.round(percent / 100 * barWidth);
   const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled);
   const progressStr = `[${bar}] ${percent}%`;
 
-  const progressPattern = /(\*\*Progress:\*\*\s*).*/i;
-  if (progressPattern.test(content)) {
-    content = content.replace(progressPattern, `$1${progressStr}`);
-    fs.writeFileSync(statePath, content, 'utf-8');
+  // Try **Progress:** bold format first, then plain Progress: format
+  const boldProgressPattern = /(\*\*Progress:\*\*\s*).*/i;
+  const plainProgressPattern = /^(Progress:\s*).*/im;
+  if (boldProgressPattern.test(content)) {
+    content = content.replace(boldProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
+    writeStateMd(statePath, content, cwd);
+    output({ updated: true, percent, completed: totalSummaries, total: totalPlans, bar: progressStr }, raw, progressStr);
+  } else if (plainProgressPattern.test(content)) {
+    content = content.replace(plainProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
+    writeStateMd(statePath, content, cwd);
     output({ updated: true, percent, completed: totalSummaries, total: totalPlans, bar: progressStr }, raw, progressStr);
   } else {
     output({ updated: false, reason: 'Progress field not found in STATE.md' }, raw, 'false');
@@ -258,11 +317,22 @@ function cmdStateAddDecision(cwd, options, raw) {
   const statePath = path.join(cwd, '.planning', 'STATE.md');
   if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, raw); return; }
 
-  const { phase, summary, rationale } = options;
-  if (!summary) { output({ error: 'summary required' }, raw); return; }
+  const { phase, summary, summary_file, rationale, rationale_file } = options;
+  let summaryText = null;
+  let rationaleText = '';
+
+  try {
+    summaryText = readTextArgOrFile(cwd, summary, summary_file, 'summary');
+    rationaleText = readTextArgOrFile(cwd, rationale || '', rationale_file, 'rationale');
+  } catch (err) {
+    output({ added: false, reason: err.message }, raw, 'false');
+    return;
+  }
+
+  if (!summaryText) { output({ error: 'summary required' }, raw); return; }
 
   let content = fs.readFileSync(statePath, 'utf-8');
-  const entry = `- [Phase ${phase || '?'}]: ${summary}${rationale ? ` — ${rationale}` : ''}`;
+  const entry = `- [Phase ${phase || '?'}]: ${summaryText}${rationaleText ? ` — ${rationaleText}` : ''}`;
 
   // Find Decisions section (various heading patterns)
   const sectionPattern = /(###?\s*(?:Decisions|Decisions Made|Accumulated.*Decisions)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
@@ -273,8 +343,8 @@ function cmdStateAddDecision(cwd, options, raw) {
     // Remove placeholders
     sectionBody = sectionBody.replace(/None yet\.?\s*\n?/gi, '').replace(/No decisions yet\.?\s*\n?/gi, '');
     sectionBody = sectionBody.trimEnd() + '\n' + entry + '\n';
-    content = content.replace(sectionPattern, `${match[1]}${sectionBody}`);
-    fs.writeFileSync(statePath, content, 'utf-8');
+    content = content.replace(sectionPattern, (_match, header) => `${header}${sectionBody}`);
+    writeStateMd(statePath, content, cwd);
     output({ added: true, decision: entry }, raw, 'true');
   } else {
     output({ added: false, reason: 'Decisions section not found in STATE.md' }, raw, 'false');
@@ -284,10 +354,20 @@ function cmdStateAddDecision(cwd, options, raw) {
 function cmdStateAddBlocker(cwd, text, raw) {
   const statePath = path.join(cwd, '.planning', 'STATE.md');
   if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, raw); return; }
-  if (!text) { output({ error: 'text required' }, raw); return; }
+  const blockerOptions = typeof text === 'object' && text !== null ? text : { text };
+  let blockerText = null;
+
+  try {
+    blockerText = readTextArgOrFile(cwd, blockerOptions.text, blockerOptions.text_file, 'blocker');
+  } catch (err) {
+    output({ added: false, reason: err.message }, raw, 'false');
+    return;
+  }
+
+  if (!blockerText) { output({ error: 'text required' }, raw); return; }
 
   let content = fs.readFileSync(statePath, 'utf-8');
-  const entry = `- ${text}`;
+  const entry = `- ${blockerText}`;
 
   const sectionPattern = /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
   const match = content.match(sectionPattern);
@@ -296,9 +376,9 @@ function cmdStateAddBlocker(cwd, text, raw) {
     let sectionBody = match[2];
     sectionBody = sectionBody.replace(/None\.?\s*\n?/gi, '').replace(/None yet\.?\s*\n?/gi, '');
     sectionBody = sectionBody.trimEnd() + '\n' + entry + '\n';
-    content = content.replace(sectionPattern, `${match[1]}${sectionBody}`);
-    fs.writeFileSync(statePath, content, 'utf-8');
-    output({ added: true, blocker: text }, raw, 'true');
+    content = content.replace(sectionPattern, (_match, header) => `${header}${sectionBody}`);
+    writeStateMd(statePath, content, cwd);
+    output({ added: true, blocker: blockerText }, raw, 'true');
   } else {
     output({ added: false, reason: 'Blockers section not found in STATE.md' }, raw, 'false');
   }
@@ -328,8 +408,8 @@ function cmdStateResolveBlocker(cwd, text, raw) {
       newBody = 'None\n';
     }
 
-    content = content.replace(sectionPattern, `${match[1]}${newBody}`);
-    fs.writeFileSync(statePath, content, 'utf-8');
+    content = content.replace(sectionPattern, (_match, header) => `${header}${newBody}`);
+    writeStateMd(statePath, content, cwd);
     output({ resolved: true, blocker: text }, raw, 'true');
   } else {
     output({ resolved: false, reason: 'Blockers section not found in STATE.md' }, raw, 'false');
@@ -364,7 +444,7 @@ function cmdStateRecordSession(cwd, options, raw) {
   if (result) { content = result; updated.push('Resume File'); }
 
   if (updated.length > 0) {
-    fs.writeFileSync(statePath, content, 'utf-8');
+    writeStateMd(statePath, content, cwd);
     output({ recorded: true, updated }, raw, 'true');
   } else {
     output({ recorded: false, reason: 'No session fields found in STATE.md' }, raw, 'false');
@@ -381,24 +461,17 @@ function cmdStateSnapshot(cwd, raw) {
 
   const content = fs.readFileSync(statePath, 'utf-8');
 
-  // Helper to extract **Field:** value patterns
-  const extractField = (fieldName) => {
-    const pattern = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+)`, 'i');
-    const match = content.match(pattern);
-    return match ? match[1].trim() : null;
-  };
-
   // Extract basic fields
-  const currentPhase = extractField('Current Phase');
-  const currentPhaseName = extractField('Current Phase Name');
-  const totalPhasesRaw = extractField('Total Phases');
-  const currentPlan = extractField('Current Plan');
-  const totalPlansRaw = extractField('Total Plans in Phase');
-  const status = extractField('Status');
-  const progressRaw = extractField('Progress');
-  const lastActivity = extractField('Last Activity');
-  const lastActivityDesc = extractField('Last Activity Description');
-  const pausedAt = extractField('Paused At');
+  const currentPhase = stateExtractField(content, 'Current Phase');
+  const currentPhaseName = stateExtractField(content, 'Current Phase Name');
+  const totalPhasesRaw = stateExtractField(content, 'Total Phases');
+  const currentPlan = stateExtractField(content, 'Current Plan');
+  const totalPlansRaw = stateExtractField(content, 'Total Plans in Phase');
+  const status = stateExtractField(content, 'Status');
+  const progressRaw = stateExtractField(content, 'Progress');
+  const lastActivity = stateExtractField(content, 'Last Activity');
+  const lastActivityDesc = stateExtractField(content, 'Last Activity Description');
+  const pausedAt = stateExtractField(content, 'Paused At');
 
   // Parse numeric fields
   const totalPhases = totalPhasesRaw ? parseInt(totalPhasesRaw, 10) : null;
@@ -444,9 +517,12 @@ function cmdStateSnapshot(cwd, raw) {
   const sessionMatch = content.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
   if (sessionMatch) {
     const sessionSection = sessionMatch[1];
-    const lastDateMatch = sessionSection.match(/\*\*Last Date:\*\*\s*(.+)/i);
-    const stoppedAtMatch = sessionSection.match(/\*\*Stopped At:\*\*\s*(.+)/i);
-    const resumeFileMatch = sessionSection.match(/\*\*Resume File:\*\*\s*(.+)/i);
+    const lastDateMatch = sessionSection.match(/\*\*Last Date:\*\*\s*(.+)/i)
+      || sessionSection.match(/^Last Date:\s*(.+)/im);
+    const stoppedAtMatch = sessionSection.match(/\*\*Stopped At:\*\*\s*(.+)/i)
+      || sessionSection.match(/^Stopped At:\s*(.+)/im);
+    const resumeFileMatch = sessionSection.match(/\*\*Resume File:\*\*\s*(.+)/i)
+      || sessionSection.match(/^Resume File:\s*(.+)/im);
 
     if (lastDateMatch) session.last_date = lastDateMatch[1].trim();
     if (stoppedAtMatch) session.stopped_at = stoppedAtMatch[1].trim();
@@ -472,9 +548,163 @@ function cmdStateSnapshot(cwd, raw) {
   output(result, raw);
 }
 
+// ─── State Frontmatter Sync ──────────────────────────────────────────────────
+
+/**
+ * Extract machine-readable fields from STATE.md markdown body and build
+ * a YAML frontmatter object. Allows hooks and scripts to read state
+ * reliably via `state json` instead of fragile regex parsing.
+ */
+function buildStateFrontmatter(bodyContent, cwd) {
+  const currentPhase = stateExtractField(bodyContent, 'Current Phase');
+  const currentPhaseName = stateExtractField(bodyContent, 'Current Phase Name');
+  const currentPlan = stateExtractField(bodyContent, 'Current Plan');
+  const totalPhasesRaw = stateExtractField(bodyContent, 'Total Phases');
+  const totalPlansRaw = stateExtractField(bodyContent, 'Total Plans in Phase');
+  const status = stateExtractField(bodyContent, 'Status');
+  const progressRaw = stateExtractField(bodyContent, 'Progress');
+  const lastActivity = stateExtractField(bodyContent, 'Last Activity');
+  const stoppedAt = stateExtractField(bodyContent, 'Stopped At') || stateExtractField(bodyContent, 'Stopped at');
+  const pausedAt = stateExtractField(bodyContent, 'Paused At');
+
+  let milestone = null;
+  let milestoneName = null;
+  if (cwd) {
+    try {
+      const info = getMilestoneInfo(cwd);
+      milestone = info.version;
+      milestoneName = info.name;
+    } catch {}
+  }
+
+  let totalPhases = totalPhasesRaw ? parseInt(totalPhasesRaw, 10) : null;
+  let completedPhases = null;
+  let totalPlans = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+  let completedPlans = null;
+
+  if (cwd) {
+    try {
+      const phasesDir = path.join(cwd, '.planning', 'phases');
+      if (fs.existsSync(phasesDir)) {
+        const isDirInMilestone = getMilestonePhaseFilter(cwd);
+        const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+          .filter(e => e.isDirectory()).map(e => e.name)
+          .filter(isDirInMilestone);
+        let diskTotalPlans = 0;
+        let diskTotalSummaries = 0;
+        let diskCompletedPhases = 0;
+
+        for (const dir of phaseDirs) {
+          const files = fs.readdirSync(path.join(phasesDir, dir));
+          const plans = files.filter(f => f.match(/-PLAN\.md$/i)).length;
+          const summaries = files.filter(f => f.match(/-SUMMARY\.md$/i)).length;
+          diskTotalPlans += plans;
+          diskTotalSummaries += summaries;
+          if (plans > 0 && summaries >= plans) diskCompletedPhases++;
+        }
+        totalPhases = isDirInMilestone.phaseCount > 0
+          ? Math.max(phaseDirs.length, isDirInMilestone.phaseCount)
+          : phaseDirs.length;
+        completedPhases = diskCompletedPhases;
+        totalPlans = diskTotalPlans;
+        completedPlans = diskTotalSummaries;
+      }
+    } catch {}
+  }
+
+  let progressPercent = null;
+  if (progressRaw) {
+    const pctMatch = progressRaw.match(/(\d+)%/);
+    if (pctMatch) progressPercent = parseInt(pctMatch[1], 10);
+  }
+
+  // Normalize status to one of: planning, discussing, executing, verifying, paused, completed, unknown
+  let normalizedStatus = status || 'unknown';
+  const statusLower = (status || '').toLowerCase();
+  if (statusLower.includes('paused') || statusLower.includes('stopped') || pausedAt) {
+    normalizedStatus = 'paused';
+  } else if (statusLower.includes('executing') || statusLower.includes('in progress')) {
+    normalizedStatus = 'executing';
+  } else if (statusLower.includes('planning') || statusLower.includes('ready to plan')) {
+    normalizedStatus = 'planning';
+  } else if (statusLower.includes('discussing')) {
+    normalizedStatus = 'discussing';
+  } else if (statusLower.includes('verif')) {
+    normalizedStatus = 'verifying';
+  } else if (statusLower.includes('complete') || statusLower.includes('done')) {
+    normalizedStatus = 'completed';
+  } else if (statusLower.includes('ready to execute')) {
+    normalizedStatus = 'executing';
+  }
+
+  const fm = { gsd_state_version: '1.0' };
+
+  if (milestone) fm.milestone = milestone;
+  if (milestoneName) fm.milestone_name = milestoneName;
+  if (currentPhase) fm.current_phase = currentPhase;
+  if (currentPhaseName) fm.current_phase_name = currentPhaseName;
+  if (currentPlan) fm.current_plan = currentPlan;
+  fm.status = normalizedStatus;
+  if (stoppedAt) fm.stopped_at = stoppedAt;
+  if (pausedAt) fm.paused_at = pausedAt;
+  fm.last_updated = new Date().toISOString();
+  if (lastActivity) fm.last_activity = lastActivity;
+
+  const progress = {};
+  if (totalPhases !== null) progress.total_phases = totalPhases;
+  if (completedPhases !== null) progress.completed_phases = completedPhases;
+  if (totalPlans !== null) progress.total_plans = totalPlans;
+  if (completedPlans !== null) progress.completed_plans = completedPlans;
+  if (progressPercent !== null) progress.percent = progressPercent;
+  if (Object.keys(progress).length > 0) fm.progress = progress;
+
+  return fm;
+}
+
+function stripFrontmatter(content) {
+  return content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+}
+
+function syncStateFrontmatter(content, cwd) {
+  const body = stripFrontmatter(content);
+  const fm = buildStateFrontmatter(body, cwd);
+  const yamlStr = reconstructFrontmatter(fm);
+  return `---\n${yamlStr}\n---\n\n${body}`;
+}
+
+/**
+ * write STATE.md with synchronized YAML frontmatter.
+ * All STATE.md writes should use this instead of raw writeFileSync.
+ */
+function writeStateMd(statePath, content, cwd) {
+  const synced = syncStateFrontmatter(content, cwd);
+  fs.writeFileSync(statePath, synced, 'utf-8');
+}
+
+function cmdStateJson(cwd, raw) {
+  const statePath = path.join(cwd, '.planning', 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    output({ error: 'STATE.md not found' }, raw, 'STATE.md not found');
+    return;
+  }
+
+  const content = fs.readFileSync(statePath, 'utf-8');
+  const fm = extractFrontmatter(content);
+
+  if (!fm || Object.keys(fm).length === 0) {
+    const body = stripFrontmatter(content);
+    const built = buildStateFrontmatter(body, cwd);
+    output(built, raw, JSON.stringify(built, null, 2));
+    return;
+  }
+
+  output(fm, raw, JSON.stringify(fm, null, 2));
+}
+
 module.exports = {
   stateExtractField,
   stateReplaceField,
+  writeStateMd,
   cmdStateLoad,
   cmdStateGet,
   cmdStatePatch,
@@ -487,4 +717,5 @@ module.exports = {
   cmdStateResolveBlocker,
   cmdStateRecordSession,
   cmdStateSnapshot,
+  cmdStateJson,
 };

package/get-shit-done/bin/lib/template.cjs

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { normalizePhaseName, findPhaseInternal, generateSlugInternal, output, error } = require('./core.cjs');
+const { normalizePhaseName, findPhaseInternal, generateSlugInternal, toPosixPath, output, error } = require('./core.cjs');
 const { reconstructFrontmatter } = require('./frontmatter.cjs');
 
 function cmdTemplateSelect(cwd, planPath, raw) {
@@ -210,12 +210,12 @@ function cmdTemplateFill(cwd, templateType, options, raw) {
   const outPath = path.join(cwd, phaseInfo.directory, fileName);
 
   if (fs.existsSync(outPath)) {
-    output({ error: 'File already exists', path: path.relative(cwd, outPath) }, raw);
+    output({ error: 'File already exists', path: toPosixPath(path.relative(cwd, outPath)) }, raw);
     return;
   }
 
   fs.writeFileSync(outPath, fullContent, 'utf-8');
-  const relPath = path.relative(cwd, outPath);
+  const relPath = toPosixPath(path.relative(cwd, outPath));
   output({ created: true, path: relPath, template: templateType }, raw, relPath);
 }