@opengsd/gsd-core 1.3.0-rc.1 → 1.3.1

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

@@ -1,2073 +0,0 @@
-/**
- * State — STATE.md operations and progression engine
- */
-
-const fs = require('fs');
-const path = require('path');
-const { escapeRegex, loadConfig, getMilestoneInfo, getMilestonePhaseFilter, extractCurrentMilestone, output, error } = require('./core.cjs');
-const { platformWriteSync, platformReadSync, platformEnsureDir } = require('./shell-command-projection.cjs');
-const { planningDir, planningPaths } = require('./planning-workspace.cjs');
-const { realClock } = require('./clock.cjs');
-const { extractFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
-const scanPhasePlans = require('./plan-scan.cjs');
-const {
-  computeProgressPercent,
-  normalizeProgressNumbers,
-  normalizeStateStatus,
-  shouldPreserveExistingProgress,
-  stateExtractField,
-  stateReplaceField,
-  KNOWN_TEMPLATE_DEFAULTS,
-  KNOWN_STATUS_PATTERNS,
-  stateReplaceFieldIfTemplate,
-} = require('./state-document.cjs');
-
-// Cache disk scan results from buildStateFrontmatter per cwd per process (#1967).
-// Avoids re-reading N+1 directories on every state write when the phase structure
-// hasn't changed within the same gsd-tools invocation.
-const _diskScanCache = new Map();
-
-/** Shorthand — every state command needs this path */
-function getStatePath(cwd) {
-  return planningPaths(cwd).state;
-}
-
-// Track all lock files held by this process so they can be removed on exit.
-// process.on('exit') fires even on process.exit(1), unlike try/finally which is
-// skipped when error() calls process.exit(1) inside a locked region (#1916).
-const _heldStateLocks = new Set();
-process.on('exit', () => {
-  for (const lockPath of _heldStateLocks) {
-    try { require('fs').unlinkSync(lockPath); } catch { /* already gone */ }
-  }
-});
-
-// Hoisted to module scope — compiled once, not per call (#320). Stateless (/i, used with .match).
-const byPhaseTablePattern = /(\|\s*Phase\s*\|\s*Plans\s*\|\s*Total\s*\|\s*Avg\/Plan\s*\|[ \t]*\n\|(?:[- :\t]+\|)+[ \t]*\n)((?:[ \t]*\|[^\n]*\n)*)(?=\n|$)/i;
-
-function cmdStateLoad(cwd, raw) {
-  const config = loadConfig(cwd);
-  const planDir = planningPaths(cwd).planning;
-
-  const stateRaw = platformReadSync(path.join(planDir, 'STATE.md')) || '';
-
-  const configExists = fs.existsSync(path.join(planDir, 'config.json'));
-  const roadmapExists = fs.existsSync(path.join(planDir, 'ROADMAP.md'));
-  const stateExists = stateRaw.length > 0;
-
-  const result = {
-    config,
-    state_raw: stateRaw,
-    state_exists: stateExists,
-    roadmap_exists: roadmapExists,
-    config_exists: configExists,
-  };
-
-  // For --raw, output a condensed key=value format
-  if (raw) {
-    const c = config;
-    const lines = [
-      `model_profile=${c.model_profile}`,
-      `commit_docs=${c.commit_docs}`,
-      `branching_strategy=${c.branching_strategy}`,
-      `phase_branch_template=${c.phase_branch_template}`,
-      `milestone_branch_template=${c.milestone_branch_template}`,
-      `parallelization=${c.parallelization}`,
-      `research=${c.research}`,
-      `plan_checker=${c.plan_checker}`,
-      `verifier=${c.verifier}`,
-      `config_exists=${configExists}`,
-      `roadmap_exists=${roadmapExists}`,
-      `state_exists=${stateExists}`,
-    ];
-    process.stdout.write(lines.join('\n'));
-    process.exit(0);
-  }
-
-  output(result);
-}
-
-function cmdStateGet(cwd, section, raw) {
-  const statePath = planningPaths(cwd).state;
-  const content = platformReadSync(statePath);
-  if (content === null) {
-    error('STATE.md not found');
-    return;
-  }
-  {
-
-    if (!section) {
-      output({ content }, raw, content);
-      return;
-    }
-
-    // Try to find markdown section or field
-    const fieldEscaped = escapeRegex(section);
-
-    // 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;
-    }
-
-    // Check for ## Section
-    const sectionPattern = new RegExp(`##\\s*${fieldEscaped}\\s*\n([\\s\\S]*?)(?=\\n##|$)`, 'i');
-    const sectionMatch = content.match(sectionPattern);
-    if (sectionMatch) {
-      output({ [section]: sectionMatch[1].trim() }, raw, sectionMatch[1].trim());
-      return;
-    }
-
-    output({ error: `Section or field "${section}" not found` }, raw, '');
-  }
-}
-
-function readTextArgOrFile(cwd, value, filePath, label) {
-  if (!filePath) return value;
-
-  // Path traversal guard: ensure file resolves within project directory
-  const { validatePath } = require('./security.cjs');
-  const pathCheck = validatePath(filePath, cwd, { allowAbsolute: true });
-  if (!pathCheck.safe) {
-    throw new Error(`${label} path rejected: ${pathCheck.error}`);
-  }
-
-  try {
-    return fs.readFileSync(pathCheck.resolved, 'utf-8').trimEnd();
-  } catch {
-    throw new Error(`${label} file not found: ${filePath}`);
-  }
-}
-
-function cmdStatePatch(cwd, patches, raw) {
-  // Validate all field names before processing
-  const { validateFieldName } = require('./security.cjs');
-  for (const field of Object.keys(patches)) {
-    const fieldCheck = validateFieldName(field);
-    if (!fieldCheck.valid) {
-      error(`state patch: ${fieldCheck.error}`);
-    }
-  }
-
-  const statePath = planningPaths(cwd).state;
-  try {
-    const results = { updated: [], failed: [] };
-
-    // Use atomic read-modify-write to prevent lost updates from concurrent agents
-    readModifyWriteStateMd(statePath, (content) => {
-      for (const [field, value] of Object.entries(patches)) {
-        const result = stateReplaceField(content, field, value);
-        if (result) {
-          content = result;
-          results.updated.push(field);
-        } else {
-          results.failed.push(field);
-        }
-      }
-      return content;
-    }, cwd);
-
-    output(results, raw, results.updated.length > 0 ? 'true' : 'false');
-  } catch {
-    error('STATE.md not found');
-  }
-}
-
-function cmdStateUpdate(cwd, field, value) {
-  if (!field || value === undefined) {
-    error('field and value required for state update');
-  }
-
-  // Validate field name to prevent regex injection via crafted field names
-  const { validateFieldName } = require('./security.cjs');
-  const fieldCheck = validateFieldName(field);
-  if (!fieldCheck.valid) {
-    error(`state update: ${fieldCheck.error}`);
-  }
-
-  const statePath = planningPaths(cwd).state;
-  try {
-    let updated = false;
-    const shouldResync = ['Progress', 'Total Plans in Phase', 'Total Phases'].includes(field);
-    // Preserve curated progress for body-only updates, but allow fields that
-    // directly project into progress.* frontmatter to rebuild after mutation.
-    readModifyWriteStateMd(statePath, (content) => {
-      const body = stripFrontmatter(content);
-      const result = stateReplaceField(body, field, value);
-      if (result) {
-        updated = true;
-        const existingFm = extractFrontmatter(content);
-        if (Object.keys(existingFm).length > 0) {
-          return `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${result}`;
-        }
-        return result;
-      }
-      return content;
-    }, cwd, { resync: shouldResync });
-    if (updated) {
-      output({ updated: true });
-    } else {
-      output({ updated: false, reason: `Field "${field}" not found in STATE.md` });
-    }
-  } catch {
-    output({ updated: false, reason: 'STATE.md not found' });
-  }
-}
-
-// ─── State Progression Engine ────────────────────────────────────────────────
-
-/**
- * Replace a STATE.md field with fallback field name support.
- * Tries `primary` first, then `fallback` (if provided), returns content unchanged
- * if neither matches. This consolidates the replaceWithFallback pattern that was
- * previously duplicated inline across phase.cjs, milestone.cjs, and state.cjs.
- */
-function stateReplaceFieldWithFallback(content, primary, fallback, value) {
-  let result = stateReplaceField(content, primary, value);
-  if (result) return result;
-  if (fallback) {
-    result = stateReplaceField(content, fallback, value);
-    if (result) return result;
-  }
-  // Neither pattern matched — field may have been reformatted or removed.
-  // Log diagnostic so template drift is detected early rather than silently swallowed.
-  process.stderr.write(
-    `[gsd-tools] WARNING: STATE.md field "${primary}"${fallback ? ` (fallback: "${fallback}")` : ''} not found — update skipped. ` +
-    `This may indicate STATE.md was externally modified or uses an unexpected format.\n`
-  );
-  return content;
-}
-
-/**
- * Update fields within the ## Current Position section of STATE.md.
- * This keeps the Current Position body in sync with the bold frontmatter fields.
- * Only updates fields that already exist in the section; does not add new lines.
- * Fixes #1365: advance-plan could not update Status/Last activity after begin-phase.
- */
-function updateCurrentPositionFields(content, fields) {
-  const posPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
-  const posMatch = content.match(posPattern);
-  if (!posMatch) return content;
-
-  let posBody = posMatch[2];
-  const statusDefaults = KNOWN_TEMPLATE_DEFAULTS['Status'];
-  const lastActivityDefaults = KNOWN_TEMPLATE_DEFAULTS['Last Activity'];
-
-  if (fields.status && /^Status:/m.test(posBody)) {
-    // Only replace when the existing Current Position Status is a known template default.
-    const existingStatusMatch = posBody.match(/^Status:\s*(.+)$/m);
-    const existingStatus = existingStatusMatch ? existingStatusMatch[1].trim() : null;
-    const isInList = existingStatus && statusDefaults.some(d => d.toLowerCase() === existingStatus.toLowerCase());
-    const matchesPattern = existingStatus && KNOWN_STATUS_PATTERNS.some(p => p.test(existingStatus));
-    const isDefault = !existingStatus || isInList || matchesPattern;
-    if (isDefault) {
-      posBody = posBody.replace(/^Status:.*$/m, `Status: ${fields.status}`);
-    }
-  }
-  if (fields.lastActivity && /^Last activity:/im.test(posBody)) {
-    // Only replace when the existing Current Position Last activity is a known template
-    // default (a bare ISO date).  Executor-authored narrative prose is preserved.
-    const existingActivityMatch = posBody.match(/^Last activity:\s*(.+)$/im);
-    const existingActivity = existingActivityMatch ? existingActivityMatch[1].trim() : null;
-    // A bare ISO date (YYYY-MM-DD with nothing after) is handler-generated.
-    // A date with a narrative suffix (e.g. "2026-02-15 -- blocked by infra...")
-    // was authored by the executor and must be preserved.
-    const isDateShape = existingActivity && /^\d{4}-\d{2}-\d{2}$/.test(existingActivity);
-    const inList = existingActivity && lastActivityDefaults.some(d => d.toLowerCase() === existingActivity.toLowerCase());
-    const isDefault = !existingActivity || isDateShape || inList;
-    if (isDefault) {
-      posBody = posBody.replace(/^Last activity:.*$/im, `Last activity: ${fields.lastActivity}`);
-    }
-  }
-  if (fields.plan && /^Plan:/m.test(posBody)) {
-    posBody = posBody.replace(/^Plan:.*$/m, `Plan: ${fields.plan}`);
-  }
-
-  return content.replace(posPattern, () => `${posMatch[1]}${posBody}`);
-}
-
-function cmdStateAdvancePlan(cwd, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, raw); return; }
-
-  const today = realClock.today();
-  let result = null;
-
-  readModifyWriteStateMd(statePath, (content) => {
-    // Try legacy separate fields first, then compound "Plan: X of Y" format
-    const legacyPlan = stateExtractField(content, 'Current Plan');
-    const legacyTotal = stateExtractField(content, 'Total Plans in Phase');
-    const planField = stateExtractField(content, 'Plan');
-
-    let currentPlan, totalPlans;
-    let useCompoundFormat = false;
-
-    if (legacyPlan && legacyTotal) {
-      currentPlan = parseInt(legacyPlan, 10);
-      totalPlans = parseInt(legacyTotal, 10);
-    } else if (planField) {
-      // Compound format: "2 of 6 in current phase" or "2 of 6"
-      currentPlan = parseInt(planField, 10);
-      const ofMatch = planField.match(/of\s+(\d+)/);
-      totalPlans = ofMatch ? parseInt(ofMatch[1], 10) : NaN;
-      useCompoundFormat = true;
-    }
-
-    if (isNaN(currentPlan) || isNaN(totalPlans)) {
-      result = { error: true };
-      return content;
-    }
-
-    const statusDefaults = KNOWN_TEMPLATE_DEFAULTS['Status'];
-    const lastActivityDefaults = KNOWN_TEMPLATE_DEFAULTS['Last Activity'];
-
-    if (currentPlan >= totalPlans) {
-      // Phase-complete branch — only replace Status/Last Activity when the existing
-      // value is a known template default (Knuth invariant: preserve executor-authored).
-      content = stateReplaceFieldIfTemplate(content, 'Status', statusDefaults, 'Phase complete — ready for verification');
-      content = stateReplaceFieldIfTemplate(content, 'Last Activity', lastActivityDefaults, today);
-      // stateReplaceFieldWithFallback tries 'Last activity' alias too
-      content = stateReplaceFieldIfTemplate(content, 'Last activity', lastActivityDefaults, today);
-      content = updateCurrentPositionFields(content, { status: 'Phase complete — ready for verification', lastActivity: today });
-      result = { advanced: false, reason: 'last_plan', current_plan: currentPlan, total_plans: totalPlans, status: 'ready_for_verification' };
-    } else {
-      const newPlan = currentPlan + 1;
-      let planDisplayValue;
-      if (useCompoundFormat) {
-        // Preserve compound format: "X of Y in current phase" → replace X only
-        planDisplayValue = planField.replace(/^\d+/, String(newPlan));
-        content = stateReplaceField(content, 'Plan', planDisplayValue) || content;
-      } else {
-        planDisplayValue = `${newPlan} of ${totalPlans}`;
-        content = stateReplaceField(content, 'Current Plan', String(newPlan)) || content;
-      }
-      // Normal advance — only replace Status/Last Activity when the existing value is
-      // a known template default (Knuth invariant: preserve executor-authored).
-      content = stateReplaceFieldIfTemplate(content, 'Status', statusDefaults, 'Ready to execute');
-      content = stateReplaceFieldIfTemplate(content, 'Last Activity', lastActivityDefaults, today);
-      content = stateReplaceFieldIfTemplate(content, 'Last activity', lastActivityDefaults, today);
-      content = updateCurrentPositionFields(content, { status: 'Ready to execute', lastActivity: today, plan: planDisplayValue });
-      result = { advanced: true, previous_plan: currentPlan, current_plan: newPlan, total_plans: totalPlans };
-    }
-    return content;
-  }, cwd);
-
-  if (!result || result.error) {
-    output({ error: 'Cannot parse Current Plan or Total Plans in Phase from STATE.md' }, raw);
-    return;
-  }
-
-  if (result.advanced === false) {
-    output(result, raw, 'false');
-  } else {
-    output(result, raw, 'true');
-  }
-}
-
-function cmdStateRecordMetric(cwd, options, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, raw); return; }
-
-  const { phase, plan, duration, tasks, files } = options;
-
-  if (!phase || !plan || !duration) {
-    output({ error: 'phase, plan, and duration required' }, raw);
-    return;
-  }
-
-  let recorded = false;
-  let created = false;
-  readModifyWriteStateMd(statePath, (content) => {
-    // Find Performance Metrics section and its table
-    const metricsPattern = /(##\s*Performance Metrics[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n)([\s\S]*?)(?=\n##|\n$|$)/i;
-    const metricsMatch = content.match(metricsPattern);
-
-    const newRow = `| Phase ${phase} P${plan} | ${duration} | ${tasks || '-'} tasks | ${files || '-'} files |`;
-
-    if (metricsMatch) {
-      let tableBody = metricsMatch[2].trimEnd();
-
-      if (tableBody.trim() === '' || tableBody.includes('None yet')) {
-        tableBody = newRow;
-      } else {
-        tableBody = tableBody + '\n' + newRow;
-      }
-
-      recorded = true;
-      return content.replace(metricsPattern, (_match, header) => `${header}${tableBody}\n`);
-    }
-
-    // Section absent — DWIM: auto-create canonical ## Performance Metrics scaffold,
-    // then append the row. Matches state begin-phase / advance-plan DWIM behavior.
-    const scaffold = [
-      '',
-      '## Performance Metrics',
-      '',
-      '| Phase | Plan | Duration | Notes |',
-      '|-------|------|----------|-------|',
-      newRow,
-      '',
-    ].join('\n');
-    recorded = true;
-    created = true;
-    return content.trimEnd() + '\n' + scaffold;
-  }, cwd);
-
-  // Auto-create fallback guarantees recorded === true; no else branch needed.
-  const result = { recorded: true, phase, plan, duration };
-  if (created) result.created = true;
-  output(result, raw, 'true');
-}
-
-function cmdStateUpdateProgress(cwd, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, raw); return; }
-
-  // Count summaries across current milestone phases only (outside lock — read-only)
-  const phasesDir = planningPaths(cwd).phases;
-  let totalPlans = 0;
-  let totalSummaries = 0;
-
-  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);
-    for (const dir of phaseDirs) {
-      const { planCount, summaryCount } = scanPhasePlans(path.join(phasesDir, dir));
-      totalPlans += planCount;
-      totalSummaries += summaryCount;
-    }
-  }
-
-  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}%`;
-
-  let updated = false;
-  const _totalPlans = totalPlans;
-  const _totalSummaries = totalSummaries;
-
-  readModifyWriteStateMd(statePath, (content) => {
-    // Try **Progress:** bold format first, then plain Progress: format
-    const boldProgressPattern = /(\*\*Progress:\*\*\s*).*/i;
-    const plainProgressPattern = /^(Progress:\s*).*/im;
-    if (boldProgressPattern.test(content)) {
-      updated = true;
-      return content.replace(boldProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
-    } else if (plainProgressPattern.test(content)) {
-      updated = true;
-      return content.replace(plainProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
-    }
-    return content;
-  }, cwd);
-
-  if (updated) {
-    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');
-  }
-}
-
-function cmdStateAddDecision(cwd, options, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, 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; }
-
-  const entry = `- [Phase ${phase || '?'}]: ${summaryText}${rationaleText ? ` — ${rationaleText}` : ''}`;
-  let added = false;
-  let created = false;
-
-  readModifyWriteStateMd(statePath, (content) => {
-    // Find Decisions section (various heading patterns)
-    const sectionPattern = /(###?\s*(?:Decisions|Decisions Made|Accumulated.*Decisions)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
-    const match = content.match(sectionPattern);
-
-    if (match) {
-      let sectionBody = match[2];
-      // Remove placeholders
-      sectionBody = sectionBody.replace(/None yet\.?\s*\n?/gi, '').replace(/No decisions yet\.?\s*\n?/gi, '');
-      sectionBody = sectionBody.trimEnd() + '\n' + entry + '\n';
-      added = true;
-      return content.replace(sectionPattern, (_match, header) => `${header}${sectionBody}`);
-    }
-
-    // Section absent — DWIM: auto-create canonical ## Decisions scaffold,
-    // then append the entry. Matches state begin-phase / advance-plan DWIM behavior.
-    const scaffold = [
-      '',
-      '## Decisions',
-      '',
-      entry,
-      '',
-    ].join('\n');
-    added = true;
-    created = true;
-    return content.trimEnd() + '\n' + scaffold;
-  }, cwd);
-
-  // Auto-create fallback guarantees added === true; no else branch needed.
-  const result = { added: true, decision: entry };
-  if (created) result.created = true;
-  output(result, raw, 'true');
-}
-
-function cmdStateAddBlocker(cwd, text, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, 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; }
-
-  const entry = `- ${blockerText}`;
-  let added = false;
-  let created = false;
-
-  readModifyWriteStateMd(statePath, (content) => {
-    const sectionPattern = /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
-    const match = content.match(sectionPattern);
-
-    if (match) {
-      let sectionBody = match[2];
-      sectionBody = sectionBody.replace(/None\.?\s*\n?/gi, '').replace(/None yet\.?\s*\n?/gi, '');
-      sectionBody = sectionBody.trimEnd() + '\n' + entry + '\n';
-      added = true;
-      return content.replace(sectionPattern, (_match, header) => `${header}${sectionBody}`);
-    }
-
-    // Section absent — DWIM: auto-create canonical ### Blockers scaffold.
-    const scaffold = [
-      '',
-      '### Blockers',
-      '',
-      entry,
-      '',
-    ].join('\n');
-    added = true;
-    created = true;
-    return content.trimEnd() + '\n' + scaffold;
-  }, cwd);
-
-  // Auto-create fallback guarantees added === true; no else branch needed.
-  const result = { added: true, blocker: blockerText };
-  if (created) result.created = true;
-  output(result, raw, 'true');
-}
-
-function cmdStateResolveBlocker(cwd, text, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, raw); return; }
-  if (!text) { output({ error: 'text required' }, raw); return; }
-
-  let resolved = false;
-
-  readModifyWriteStateMd(statePath, (content) => {
-    const sectionPattern = /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
-    const match = content.match(sectionPattern);
-
-    if (match) {
-      const sectionBody = match[2];
-      const lines = sectionBody.split('\n');
-      const filtered = lines.filter(line => {
-        if (!line.startsWith('- ')) return true;
-        return !line.toLowerCase().includes(text.toLowerCase());
-      });
-
-      let newBody = filtered.join('\n');
-      // If section is now empty, add placeholder
-      if (!newBody.trim() || !newBody.includes('- ')) {
-        newBody = 'None\n';
-      }
-
-      resolved = true;
-      return content.replace(sectionPattern, (_match, header) => `${header}${newBody}`);
-    }
-    return content;
-  }, cwd);
-
-  if (resolved) {
-    output({ resolved: true, blocker: text }, raw, 'true');
-  } else {
-    output({ resolved: false, reason: 'Blockers section not found in STATE.md' }, raw, 'false');
-  }
-}
-
-function cmdStateRecordSession(cwd, options, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, raw); return; }
-
-  const now = realClock.nowIso();
-  const updated = [];
-
-  readModifyWriteStateMd(statePath, (content) => {
-    // Update Last session / Last Date
-    let result = stateReplaceField(content, 'Last session', now);
-    if (result) { content = result; updated.push('Last session'); }
-    result = stateReplaceField(content, 'Last Date', now);
-    if (result) { content = result; updated.push('Last Date'); }
-
-    // Update Stopped at
-    if (options.stopped_at) {
-      result = stateReplaceField(content, 'Stopped At', options.stopped_at);
-      if (!result) result = stateReplaceField(content, 'Stopped at', options.stopped_at);
-      if (result) { content = result; updated.push('Stopped At'); }
-    }
-
-    // Update Resume File — only when the caller explicitly passed a value OR the
-    // existing value is a known template default.  An executor-authored path must
-    // not be silently replaced with 'None' just because --resume-file was omitted
-    // (Knuth invariant: handler-owns-transition-between-known-template-defaults).
-    const resumeFileDefaults = KNOWN_TEMPLATE_DEFAULTS['Resume File'];
-    if (options.resume_file !== undefined && options.resume_file !== null) {
-      // Caller explicitly passed a value — always honour it.
-      result = stateReplaceField(content, 'Resume File', options.resume_file);
-      if (!result) result = stateReplaceField(content, 'Resume file', options.resume_file);
-      if (result) { content = result; updated.push('Resume File'); }
-    } else {
-      // No explicit value — only set 'None' when existing value is also a known default
-      // (i.e. not executor-authored).
-      const newRf = stateReplaceFieldIfTemplate(content, 'Resume File', resumeFileDefaults, 'None');
-      if (newRf !== content) {
-        content = newRf;
-        updated.push('Resume File');
-      } else {
-        // Try alternate capitalisation
-        const newRfAlt = stateReplaceFieldIfTemplate(content, 'Resume file', resumeFileDefaults, 'None');
-        if (newRfAlt !== content) {
-          content = newRfAlt;
-          updated.push('Resume File');
-        }
-      }
-    }
-
-    return content;
-  }, cwd);
-
-  if (updated.length > 0) {
-    output({ recorded: true, updated }, raw, 'true');
-  } else {
-    output({ recorded: false, reason: 'No session fields found in STATE.md' }, raw, 'false');
-  }
-}
-
-function cmdStateSnapshot(cwd, raw) {
-  const statePath = planningPaths(cwd).state;
-
-  if (!fs.existsSync(statePath)) {
-    output({ error: 'STATE.md not found' }, raw);
-    return;
-  }
-
-  const content = fs.readFileSync(statePath, 'utf-8');
-
-  // Bug #3265: prefer YAML frontmatter for canonical scalar fields so that a
-  // body table cell containing **Status:** Y cannot shadow the authoritative
-  // frontmatter value.  Mirrors the fix in sdk/src/query/state.ts.
-  const fm = extractFrontmatter(content);
-  const body = stripFrontmatter(content);
-
-  // Helper: return frontmatter scalar value when present and non-empty.
-  // Accepts strings, numbers, and booleans — coercing non-string primitives to
-  // their string representation so callers always receive string | null.
-  // Returns null for missing, null/undefined, or empty-after-trim values so
-  // the caller falls back to body extraction.
-  const fmScalar = (key) => {
-    const v = fm[key];
-    if (v === null || v === undefined) return null;
-    if (typeof v === 'string') return v.trim() || null;
-    if (typeof v === 'number' || typeof v === 'boolean') return String(v);
-    return null;
-  };
-
-  // Extract basic fields — frontmatter keys take precedence over body
-  const currentPhase = fmScalar('current_phase') ?? stateExtractField(body, 'Current Phase');
-  const currentPhaseName = fmScalar('current_phase_name') ?? stateExtractField(body, 'Current Phase Name');
-  const totalPhasesRaw = fmScalar('total_phases') ?? stateExtractField(body, 'Total Phases');
-  const currentPlan = fmScalar('current_plan') ?? stateExtractField(body, 'Current Plan');
-  const totalPlansRaw = fmScalar('total_plans_in_phase') ?? stateExtractField(body, 'Total Plans in Phase');
-  const status = fmScalar('status') ?? stateExtractField(body, 'Status');
-  const progressRaw = fmScalar('progress') ?? stateExtractField(body, 'Progress');
-  const lastActivity = fmScalar('last_activity') ?? stateExtractField(body, 'Last Activity');
-  const lastActivityDesc = fmScalar('last_activity_desc') ?? stateExtractField(body, 'Last Activity Description');
-  const pausedAt = fmScalar('paused_at') ?? stateExtractField(body, 'Paused At');
-
-  // Parse numeric fields
-  const totalPhases = totalPhasesRaw ? parseInt(totalPhasesRaw, 10) : null;
-  const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
-  const progressPercent = progressRaw ? parseInt(progressRaw.replace('%', ''), 10) : null;
-
-  // Extract decisions table
-  const decisions = [];
-  const decisionsMatch = body.match(/##\s*Decisions Made[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n([\s\S]*?)(?=\n##|\n$|$)/i);
-  if (decisionsMatch) {
-    const tableBody = decisionsMatch[1];
-    const rows = tableBody.trim().split('\n').filter(r => r.includes('|'));
-    for (const row of rows) {
-      const cells = row.split('|').map(c => c.trim()).filter(Boolean);
-      if (cells.length >= 3) {
-        decisions.push({
-          phase: cells[0],
-          summary: cells[1],
-          rationale: cells[2],
-        });
-      }
-    }
-  }
-
-  // Extract blockers list
-  const blockers = [];
-  const blockersMatch = body.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
-  if (blockersMatch) {
-    const blockersSection = blockersMatch[1];
-    const items = blockersSection.match(/^-\s+(.+)$/gm) || [];
-    for (const item of items) {
-      blockers.push(item.replace(/^-\s+/, '').trim());
-    }
-  }
-
-  // Extract session info
-  const session = {
-    last_date: null,
-    stopped_at: null,
-    resume_file: null,
-  };
-
-  const sessionMatch = body.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
-  if (sessionMatch) {
-    const sessionSection = sessionMatch[1];
-    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();
-    if (resumeFileMatch) session.resume_file = resumeFileMatch[1].trim();
-  }
-
-  const result = {
-    current_phase: currentPhase,
-    current_phase_name: currentPhaseName,
-    total_phases: totalPhases,
-    current_plan: currentPlan,
-    total_plans_in_phase: totalPlansInPhase,
-    status,
-    progress_percent: progressPercent,
-    last_activity: lastActivity,
-    last_activity_desc: lastActivityDesc,
-    decisions,
-    blockers,
-    paused_at: pausedAt,
-    session,
-  };
-
-  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');
-  // Bug #2444: scope Stopped At extraction to the ## Session section so that
-  // historical "Stopped at:" prose elsewhere in the body (e.g. in a
-  // Session Continuity Archive section) never overwrites the current value.
-  // Fall back to full-body search only when no ## Session section exists.
-  const sessionSectionMatch = bodyContent.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
-  const sessionBodyScope = sessionSectionMatch ? sessionSectionMatch[1] : bodyContent;
-  const stoppedAt = stateExtractField(sessionBodyScope, 'Stopped At') || stateExtractField(sessionBodyScope, '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 { /* intentionally empty */ }
-  }
-
-  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 = planningPaths(cwd).phases;
-      if (fs.existsSync(phasesDir)) {
-        // Use cached disk scan when available — avoids N+1 readdirSync calls
-        // on repeated buildStateFrontmatter invocations within the same process (#1967)
-        let cached = _diskScanCache.get(cwd);
-        if (!cached) {
-          const isDirInMilestone = getMilestonePhaseFilter(cwd);
-          const allMatchingDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
-            .filter(e => e.isDirectory()).map(e => e.name)
-            .filter(isDirInMilestone);
-
-          // Bug #2445: when stale phase dirs from a prior milestone remain in
-          // .planning/phases/ alongside new dirs with the same phase number,
-          // de-duplicate by normalized phase number keeping the most recently
-          // modified dir. This prevents double-counting (e.g. two "Phase 1" dirs).
-          const seenPhaseNums = new Map(); // normalizedNum -> dirName
-          for (const dir of allMatchingDirs) {
-            const m = dir.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
-            const key = m ? m[1].toLowerCase() : dir;
-            if (!seenPhaseNums.has(key)) {
-              seenPhaseNums.set(key, dir);
-            } else {
-              // Keep the dir that is newer on disk (more likely current milestone)
-              try {
-                const existing = path.join(phasesDir, seenPhaseNums.get(key));
-                const candidate = path.join(phasesDir, dir);
-                if (fs.statSync(candidate).mtimeMs > fs.statSync(existing).mtimeMs) {
-                  seenPhaseNums.set(key, dir);
-                }
-              } catch { /* keep existing on stat error */ }
-            }
-          }
-          const phaseDirs = [...seenPhaseNums.values()];
-
-          let diskTotalPlans = 0;
-          let diskTotalSummaries = 0;
-          let diskCompletedPhases = 0;
-
-          for (const dir of phaseDirs) {
-            const phaseDir = path.join(phasesDir, dir);
-            const { planCount, summaryCount, completed } = scanPhasePlans(phaseDir);
-            diskTotalPlans += planCount;
-            diskTotalSummaries += summaryCount;
-            if (completed) diskCompletedPhases++;
-          }
-          // Count phase headings from ROADMAP using a digit-containing pattern
-          // that matches both numeric phases (01, 05.1) and project-code phases
-          // (PROJ-42, CK-05) but excludes pure-word section headers like
-          // `## Phase Overview:` or `## Phase Details:` — single source of
-          // truth for total_phases (#549).
-          let roadmapPhaseCount = 0;
-          try {
-            const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
-            const roadmapRaw = platformReadSync(roadmapPath);
-            if (roadmapRaw !== null) {
-              const roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
-              const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
-              let m;
-              while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
-                // Only count tokens that contain at least one digit — excludes
-                // pure-word section headings (Overview, Details) while keeping
-                // numeric phases (01, 05.1) and project-code IDs (PROJ-42).
-                if (/\d/.test(m[1])) roadmapPhaseCount++;
-              }
-            }
-          } catch { /* fall through: phaseDirs.length used as sole count */ }
-
-          cached = {
-            totalPhases: roadmapPhaseCount > 0
-              ? Math.max(phaseDirs.length, roadmapPhaseCount)
-              : phaseDirs.length,
-            completedPhases: diskCompletedPhases,
-            totalPlans: diskTotalPlans,
-            completedPlans: diskTotalSummaries,
-          };
-          _diskScanCache.set(cwd, cached);
-        }
-        totalPhases = cached.totalPhases;
-        completedPhases = cached.completedPhases;
-        totalPlans = cached.totalPlans;
-        completedPlans = cached.completedPlans;
-      }
-    } catch { /* intentionally empty */ }
-  }
-
-  // Derive percent from disk counts when available (ground truth).
-  // Uses min(plan_fraction, phase_fraction) via computeProgressPercent so that
-  // ROADMAP-declared-but-unrealized future phases cap the reported completion
-  // instead of a false 100% from plan-only coverage (#3242 Bug B).
-  // Falls back to the body Progress: field only when no plan files exist on disk.
-  let progressPercent = computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases);
-  if (progressPercent === null && progressRaw) {
-    const pctMatch = progressRaw.match(/(\d+)%/);
-    if (pctMatch) progressPercent = parseInt(pctMatch[1], 10);
-  }
-
-  const normalizedStatus = normalizeStateStatus(status, pausedAt);
-
-  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 = realClock.nowIso();
-  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) {
-  // Strip ALL frontmatter blocks at the start of the file.
-  // Handles CRLF line endings and multiple stacked blocks (corruption recovery).
-  // Greedy: keeps stripping ---...--- blocks separated by optional whitespace.
-  let result = content;
-   
-  while (true) {
-    const stripped = result.replace(/^\s*---\r?\n[\s\S]*?\r?\n---\s*/, '');
-    if (stripped === result) break;
-    result = stripped;
-  }
-  return result;
-}
-
-function syncStateFrontmatter(content, cwd) {
-  // Read existing frontmatter BEFORE stripping — it may contain values
-  // that the body no longer has (e.g., Status field removed by an agent).
-  const existingFm = extractFrontmatter(content);
-  const body = stripFrontmatter(content);
-  const derivedFm = buildStateFrontmatter(body, cwd);
-
-  // Preserve existing frontmatter status when body-derived status is 'unknown'.
-  // This prevents a missing Status: field in the body from overwriting a
-  // previously valid status (e.g., 'executing' → 'unknown').
-  if (derivedFm.status === 'unknown' && existingFm.status && existingFm.status !== 'unknown') {
-    derivedFm.status = existingFm.status;
-  }
-
-  const yamlStr = reconstructFrontmatter(derivedFm);
-  return `---\n${yamlStr}\n---\n\n${body}`;
-}
-
-// Transient errno codes that indicate a temporary filesystem condition under
-// concurrent O_EXCL races — Docker overlay-fs (ENOENT/EINVAL/EIO), NFS
-// (ESTALE), and OS-level interrupt/retry signals (EAGAIN/EINTR).  These are
-// recoverable; acquireStateLock retries instead of propagating them.
-// Truly fatal codes (EMFILE, ENOSPC, EROFS, EACCES) are NOT in this set and
-// will still throw immediately.
-const ACQUIRE_LOCK_RETRY_ERRNOS = new Set([
-  'EPERM',   // Windows / macOS AV scanner holds the file open during delete
-  'EBUSY',   // Windows: file in use by another process
-  'EAGAIN',  // POSIX: resource temporarily unavailable
-  'EINTR',   // POSIX: syscall interrupted by signal
-  'EINVAL',  // Docker overlay-fs: transient during concurrent O_EXCL creation
-  'EIO',     // Docker overlay-fs / NFS: transient I/O error
-  'ENOENT',  // Docker overlay-fs: parent dir transiently missing during race
-  'ESTALE',  // NFS: stale file handle (self-resolves on retry)
-]);
-
-/**
- * Acquire a lockfile for STATE.md operations.
- * Returns the lock path for later release.
- *
- * @param {string} statePath
- * @param {{ now(): number, sleep(ms: number): void }} [clock]
- *   Optional clock seam for testing. Defaults to realClock (Date.now + Atomics.wait).
- *   Pass a fake clock from tests/helpers/clock.cjs to drive timeout/stale logic
- *   without real wall-clock waits.
- */
-function acquireStateLock(statePath, clock) {
-  if (clock === undefined) clock = realClock;
-  const lockPath = statePath + '.lock';
-  const retryDelay = 200; // ms
-  const staleThresholdMs = 10000;
-  const maxWaitMs = 30000;
-  const startedAt = clock.now();
-
-   
-  while (true) {
-    try {
-      const fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
-      fs.writeSync(fd, String(process.pid));
-      fs.closeSync(fd);
-      // Exit-time cleanup keeps a crashed locked region from leaving a stale file (#1916).
-      _heldStateLocks.add(lockPath);
-      return lockPath;
-    } catch (err) {
-      // Transient filesystem errors (Docker overlay-fs, NFS, OS signals, AV scanners)
-      // are recoverable — retry the acquisition loop rather than propagating.
-      // See ACQUIRE_LOCK_RETRY_ERRNOS for the full list and rationale.
-      if (ACQUIRE_LOCK_RETRY_ERRNOS.has(err.code)) { continue; }
-      if (err.code !== 'EEXIST') throw err; // propagate — silent bypass causes lost updates
-      // Only unlink a lock we did not place when it has crossed the staleness
-      // threshold (crashed holder). Nuking a fresh lock held by a slow-but-live
-      // writer causes lost updates (#3711 regression).
-      try {
-        const stat = fs.statSync(lockPath);
-        if (clock.now() - stat.mtimeMs > staleThresholdMs) {
-          try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
-          continue;
-        }
-      } catch { continue; /* released between EEXIST and stat */ }
-      if (clock.now() - startedAt >= maxWaitMs) {
-        throw new Error(
-          'acquireStateLock: ' + lockPath + ' held by live process for ' +
-          (clock.now() - startedAt) + 'ms (exceeded ' + maxWaitMs + 'ms budget)'
-        );
-      }
-      const jitter = Math.floor(Math.random() * 50);
-      clock.sleep(retryDelay + jitter);
-    }
-  }
-}
-
-function releaseStateLock(lockPath) {
-  _heldStateLocks.delete(lockPath);
-  try { fs.unlinkSync(lockPath); } catch { /* lock already gone */ }
-}
-
-function withStateLock(statePath, fn) {
-  const lockPath = acquireStateLock(statePath);
-  try {
-    return fn();
-  } finally {
-    releaseStateLock(lockPath);
-  }
-}
-
-/**
- * Write STATE.md with synchronized YAML frontmatter.
- * All STATE.md writes should use this instead of raw writeFileSync.
- * Uses a simple lockfile to prevent parallel agents from overwriting
- * each other's changes (race condition with read-modify-write cycle).
- *
- * @param {string} statePath
- * @param {string} content
- * @param {string} [cwd]
- * @param {{ now(): number, sleep(ms: number): void }} [clock]
- *   Optional clock seam; defaults to realClock. Passed through to acquireStateLock.
- */
-function writeStateMd(statePath, content, cwd, clock) {
-  // Invalidate disk scan cache before computing new frontmatter — the write
-  // may create new PLAN/SUMMARY files that buildStateFrontmatter must see.
-  // Safe for any calling pattern, not just short-lived CLI processes (#1967).
-  if (cwd) _diskScanCache.delete(cwd);
-  const synced = syncStateFrontmatter(content, cwd);
-  const lockPath = acquireStateLock(statePath, clock);
-  try {
-    platformWriteSync(statePath, synced);
-  } finally {
-    releaseStateLock(lockPath);
-  }
-}
-
-/**
- * Atomic read-modify-write for STATE.md.
- * Holds the lock across the entire read -> transform -> write cycle,
- * preventing the lost-update problem where two agents read the same
- * content and the second write clobbers the first.
- *
- * @param {string} statePath
- * @param {function} transformFn - (content: string) => string
- * @param {string} cwd
- * @param {{ resync?: boolean }} [options]
- *   resync: when true (default) rebuilds the entire frontmatter from disk after
- *   the transform. Pass { resync: false } for body-only updates (e.g. state.update
- *   on a single field) that must not trample manually-curated cross-milestone
- *   progress.* counters in the frontmatter (#3242 Bug A).
- *   When resync is false, syncStateFrontmatter still runs to maintain/create the
- *   frontmatter block, but any existing progress.* sub-keys are preserved from
- *   the pre-transform file rather than being rebuilt from disk.
- * @param {{ now(): number, sleep(ms: number): void }} [clock]
- *   Optional clock seam; defaults to realClock. Passed through to acquireStateLock.
- */
-function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
-  const resync = !options || options.resync !== false;
-  const lockPath = acquireStateLock(statePath, clock);
-  try {
-    const content = platformReadSync(statePath) || '';
-    // Snapshot the existing progress block BEFORE the transform so we can
-    // restore it when resync is false.
-    const preFm = resync ? null : extractFrontmatter(content);
-    const modified = transformFn(content);
-    let synced = syncStateFrontmatter(modified, cwd);
-
-    if (!resync && preFm && preFm.progress) {
-      // Re-apply the curated progress block that syncStateFrontmatter just
-      // overwrote with disk-derived values.  Only restore keys that were present
-      // in the snapshot — this preserves any new non-progress frontmatter fields
-      // (e.g., status, current_phase) that syncStateFrontmatter legitimately
-      // derived from the updated body.
-      const postFm = extractFrontmatter(synced);
-      postFm.progress = preFm.progress;
-      const yamlStr = reconstructFrontmatter(postFm);
-      const body = stripFrontmatter(synced);
-      synced = `---\n${yamlStr}\n---\n\n${body}`;
-    }
-
-    platformWriteSync(statePath, synced);
-  } finally {
-    releaseStateLock(lockPath);
-  }
-}
-
-function cmdStateJson(cwd, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) {
-    output({ error: 'STATE.md not found' }, raw, 'STATE.md not found');
-    return;
-  }
-
-  const content = fs.readFileSync(statePath, 'utf-8');
-  const existingFm = extractFrontmatter(content);
-  const body = stripFrontmatter(content);
-
-  // Always rebuild from body + disk so progress counters reflect current state.
-  // Returning cached frontmatter directly causes stale percent/completed_plans
-  // when SUMMARY files were added after the last STATE.md write (#1589).
-  const built = buildStateFrontmatter(body, cwd);
-
-  // Preserve frontmatter-only fields that cannot be recovered from the body.
-  if (existingFm && existingFm.stopped_at && !built.stopped_at) {
-    built.stopped_at = existingFm.stopped_at;
-  }
-  if (existingFm && existingFm.paused_at && !built.paused_at) {
-    built.paused_at = existingFm.paused_at;
-  }
-  // Preserve existing status when body-derived status is 'unknown' (same logic as syncStateFrontmatter).
-  if (built.status === 'unknown' && existingFm && existingFm.status && existingFm.status !== 'unknown') {
-    built.status = existingFm.status;
-  }
-  // Preserve curated cross-milestone aggregates when local disk scanning sees
-  // only a narrower realized subset (#3242 Bug A). Stale lower counters still
-  // rebuild from disk because they do not exceed the derived scan.
-  if (existingFm && shouldPreserveExistingProgress(existingFm.progress, built.progress)) {
-    built.progress = normalizeProgressNumbers(existingFm.progress);
-  }
-
-  output(built, raw, JSON.stringify(built, null, 2));
-}
-
-/**
- * Update STATE.md when a new phase begins execution.
- * Updates body text fields (Current focus, Status, Last Activity, Current Position)
- * and synchronizes frontmatter via writeStateMd.
- * Fixes: #1102 (plan counts), #1103 (status/last_activity), #1104 (body text).
- */
-function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) {
-    output({ error: 'STATE.md not found' }, raw);
-    return;
-  }
-
-  const today = realClock.today();
-  const updated = [];
-
-  readModifyWriteStateMd(statePath, (content) => {
-    // Idempotency guard (#3127): if the phase is already mid-flight, do NOT
-    // overwrite execution-progress fields (Current Plan, plan body line,
-    // Last Activity Description). Only update fields that are safe to
-    // refresh on resume (Last Activity date, Status if inconsistent).
-    // A phase is considered mid-flight when Status contains 'Executing Phase N'
-    // for the current phase number.
-    const currentStatus = stateExtractField(content, 'Status') || '';
-    const isAlreadyExecuting = new RegExp(`Executing Phase\\s+${escapeRegex(String(phaseNumber))}\\b`, 'i').test(currentStatus);
-
-    // Update Status field
-    const statusValue = `Executing Phase ${phaseNumber}`;
-    let result = stateReplaceField(content, 'Status', statusValue);
-    if (result) { content = result; updated.push('Status'); }
-
-    // Update Last Activity (safe to update on resume — tracks when execute-phase ran)
-    result = stateReplaceField(content, 'Last Activity', today);
-    if (result) { content = result; updated.push('Last Activity'); }
-
-    if (!isAlreadyExecuting) {
-      // First-time execution: set all progress fields
-
-      // Update Last Activity Description
-      const activityDesc = `Phase ${phaseNumber} execution started`;
-      result = stateReplaceField(content, 'Last Activity Description', activityDesc);
-      if (result) { content = result; updated.push('Last Activity Description'); }
-
-      // Update Current Phase
-      result = stateReplaceField(content, 'Current Phase', String(phaseNumber));
-      if (result) { content = result; updated.push('Current Phase'); }
-
-      // Update Current Phase Name
-      if (phaseName) {
-        result = stateReplaceField(content, 'Current Phase Name', phaseName);
-        if (result) { content = result; updated.push('Current Phase Name'); }
-      }
-
-      // Update Current Plan to 1 (starting from the first plan)
-      result = stateReplaceField(content, 'Current Plan', '1');
-      if (result) { content = result; updated.push('Current Plan'); }
-
-      // Update Total Plans in Phase
-      if (planCount) {
-        result = stateReplaceField(content, 'Total Plans in Phase', String(planCount));
-        if (result) { content = result; updated.push('Total Plans in Phase'); }
-      }
-
-      // Update **Current focus:** body text line (#1104)
-      const focusLabel = phaseName ? `Phase ${phaseNumber} — ${phaseName}` : `Phase ${phaseNumber}`;
-      const focusPattern = /(\*\*Current focus:\*\*\s*).*/i;
-      if (focusPattern.test(content)) {
-        content = content.replace(focusPattern, (_match, prefix) => `${prefix}${focusLabel}`);
-        updated.push('Current focus');
-      }
-
-      // Update ## Current Position section (#1104, #1365)
-      const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
-      const positionMatch = content.match(positionPattern);
-      if (positionMatch) {
-        const header = positionMatch[1];
-        let posBody = positionMatch[2];
-
-        // Update or insert Phase line
-        const newPhase = `Phase: ${phaseNumber}${phaseName ? ` (${phaseName})` : ''} — EXECUTING`;
-        if (/^Phase:/m.test(posBody)) {
-          posBody = posBody.replace(/^Phase:.*$/m, newPhase);
-        } else {
-          posBody = newPhase + '\n' + posBody;
-        }
-
-        // Update or insert Plan line
-        const newPlan = `Plan: 1 of ${planCount || '?'}`;
-        if (/^Plan:/m.test(posBody)) {
-          posBody = posBody.replace(/^Plan:.*$/m, newPlan);
-        } else {
-          posBody = posBody.replace(/^(Phase:.*$)/m, `$1\n${newPlan}`);
-        }
-
-        // Update Status line if present
-        const newStatus = `Status: Executing Phase ${phaseNumber}`;
-        if (/^Status:/m.test(posBody)) {
-          posBody = posBody.replace(/^Status:.*$/m, newStatus);
-        }
-
-        // Update Last activity line if present
-        const newActivity = `Last activity: ${today} -- Phase ${phaseNumber} execution started`;
-        if (/^Last activity:/im.test(posBody)) {
-          posBody = posBody.replace(/^Last activity:.*$/im, newActivity);
-        }
-
-        content = content.replace(positionPattern, () => `${header}${posBody}`);
-        updated.push('Current Position');
-      }
-    } else {
-      // Resume path: only update Last activity timestamp in Current Position
-      // (do not touch Plan:, stopped_at, progress.percent, or plan counter)
-      const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
-      const positionMatch = content.match(positionPattern);
-      if (positionMatch) {
-        const header = positionMatch[1];
-        let posBody = positionMatch[2];
-        const resumeActivity = `Last activity: ${today} -- Phase ${phaseNumber} execution resumed (wave continue)`;
-        if (/^Last activity:/im.test(posBody)) {
-          posBody = posBody.replace(/^Last activity:.*$/im, resumeActivity);
-          content = content.replace(positionPattern, () => `${header}${posBody}`);
-          updated.push('Last activity (resume)');
-        }
-      }
-    }
-
-    return content;
-  }, cwd);
-
-  output({ updated, phase: phaseNumber, phase_name: phaseName || null, plan_count: planCount || null }, raw, updated.length > 0 ? 'true' : 'false');
-}
-
-/**
- * Write a WAITING.json signal file when GSD hits a decision point.
- * External watchers (fswatch, polling, orchestrators) can detect this.
- * File is written to .planning/WAITING.json (or .gsd/WAITING.json if .gsd exists).
- * Fixes #1034.
- */
-function cmdSignalWaiting(cwd, type, question, options, phase, raw) {
-  const gsdDir = fs.existsSync(path.join(cwd, '.gsd')) ? path.join(cwd, '.gsd') : planningDir(cwd);
-  const waitingPath = path.join(gsdDir, 'WAITING.json');
-
-  const signal = {
-    status: 'waiting',
-    type: type || 'decision_point',
-    question: question || null,
-    options: options ? options.split('|').map(o => o.trim()) : [],
-    since: realClock.nowIso(),
-    phase: phase || null,
-  };
-
-  try {
-    platformEnsureDir(gsdDir);
-    platformWriteSync(waitingPath, JSON.stringify(signal, null, 2));
-    output({ signaled: true, path: waitingPath }, raw, 'true');
-  } catch (e) {
-    output({ signaled: false, error: e.message }, raw, 'false');
-  }
-}
-
-/**
- * Remove the WAITING.json signal file when user answers and agent resumes.
- */
-function cmdSignalResume(cwd, raw) {
-  const paths = [
-    path.join(cwd, '.gsd', 'WAITING.json'),
-    path.join(planningDir(cwd), 'WAITING.json'),
-  ];
-
-  let removed = false;
-  for (const p of paths) {
-    if (fs.existsSync(p)) {
-      try { fs.unlinkSync(p); removed = true; } catch {}
-    }
-  }
-
-  output({ resumed: true, removed }, raw, removed ? 'true' : 'false');
-}
-
-// ─── Gate Functions (STATE.md consistency enforcement) ────────────────────────
-
-/**
- * Update the ## Performance Metrics section in STATE.md content.
- * Increments Velocity totals and upserts a By Phase table row.
- * Returns modified content string.
- */
-function updatePerformanceMetricsSection(content, cwd, phaseNum, planCount, summaryCount) {
-  // Update Velocity: Total plans completed
-  const totalMatch = content.match(/Total plans completed:\s*(\d+|\[N\])/);
-  const prevTotal = totalMatch && totalMatch[1] !== '[N]' ? parseInt(totalMatch[1], 10) : 0;
-  const newTotal = prevTotal + summaryCount;
-  content = content.replace(
-    /Total plans completed:\s*(\d+|\[N\])/,
-    `Total plans completed: ${newTotal}`
-  );
-
-  // Update By Phase table — upsert row for this phase
-  const byPhaseMatch = content.match(byPhaseTablePattern);
-  if (byPhaseMatch) {
-    let tableBody = byPhaseMatch[2].trim();
-    const phaseRowPattern = new RegExp(`^\\|\\s*${escapeRegex(String(phaseNum))}\\s*\\|.*$`, 'm');
-    const newRow = `| ${phaseNum} | ${summaryCount} | - | - |`;
-
-    if (phaseRowPattern.test(tableBody)) {
-      // Update existing row
-      tableBody = tableBody.replace(phaseRowPattern, newRow);
-    } else {
-      // Remove placeholder row and add new row
-      tableBody = tableBody.replace(/^\|\s*-\s*\|\s*-\s*\|\s*-\s*\|\s*-\s*\|$/m, '').trim();
-      tableBody = tableBody ? tableBody + '\n' + newRow : newRow;
-    }
-
-    content = content.replace(byPhaseTablePattern, (_match, tableHeader) => `${tableHeader}${tableBody}\n`);
-  }
-
-  return content;
-}
-
-/**
- * Gate 3a: Record state after plan-phase completes.
- * Updates Status to "Ready to execute", Total Plans, Last Activity.
- */
-function cmdStatePlannedPhase(cwd, phaseNumber, planCount, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) {
-    output({ error: 'STATE.md not found' }, raw);
-    return;
-  }
-
-  const today = realClock.today();
-  const updated = [];
-
-  const statusDefaults = KNOWN_TEMPLATE_DEFAULTS['Status'];
-  const lastActivityDefaults = KNOWN_TEMPLATE_DEFAULTS['Last Activity'];
-
-  // plan-phase updates per-phase body fields only. It must NOT resync the
-  // milestone-wide progress.* frontmatter from a half-planned disk snapshot —
-  // doing so tramples curated/known-good counters. Route through the body-only
-  // write contract (resync:false), the same guard state.update uses. (#500 RC1)
-  readModifyWriteStateMd(statePath, (content) => {
-    // Update Status — only when the existing value is a known template default
-    // (Knuth invariant: preserve executor-authored values).
-    const newContent = stateReplaceFieldIfTemplate(content, 'Status', statusDefaults, 'Ready to execute');
-    if (newContent !== content) { content = newContent; updated.push('Status'); }
-
-    // Update Total Plans in Phase
-    if (planCount !== null && planCount !== undefined) {
-      const result = stateReplaceField(content, 'Total Plans in Phase', String(planCount));
-      if (result) { content = result; updated.push('Total Plans in Phase'); }
-    }
-
-    // Update Last Activity — only when the existing value is a known template default
-    {
-      const after = stateReplaceFieldIfTemplate(content, 'Last Activity', lastActivityDefaults, today);
-      if (after !== content) { content = after; updated.push('Last Activity'); }
-    }
-
-    // Update Last Activity Description
-    {
-      const result = stateReplaceField(content, 'Last Activity Description', `Phase ${phaseNumber} planning complete — ${planCount || '?'} plans ready`);
-      if (result) { content = result; updated.push('Last Activity Description'); }
-    }
-
-    // Update Current Position section
-    content = updateCurrentPositionFields(content, {
-      status: 'Ready to execute',
-      lastActivity: `${today} -- Phase ${phaseNumber} planning complete`,
-    });
-
-    return content;
-  }, cwd, { resync: false });
-
-  output({ updated, phase: phaseNumber, plan_count: planCount }, raw, updated.length > 0 ? 'true' : 'false');
-}
-
-/**
- * Bug #2630: reset STATE.md for a new milestone cycle.
- * Stomps frontmatter milestone/milestone_name/status/progress AND rewrites
- * the Current Position body. Preserves Accumulated Context.
- * Symmetric with the SDK `stateMilestoneSwitch` handler.
- */
-function cmdStateMilestoneSwitch(cwd, version, name, raw) {
-  if (!version || !String(version).trim()) {
-    output({ error: 'milestone required (--milestone <vX.Y>)' }, raw);
-    return;
-  }
-  const resolvedName = (name && String(name).trim()) || 'milestone';
-  const statePath = planningPaths(cwd).state;
-  const today = realClock.today();
-
-  const lockPath = acquireStateLock(statePath);
-  try {
-    const content = platformReadSync(statePath) || '';
-    const existingFm = extractFrontmatter(content);
-    const body = stripFrontmatter(content);
-
-    const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
-    const resetPositionBody =
-      `\nPhase: Not started (defining requirements)\n` +
-      `Plan: —\n` +
-      `Status: Defining requirements\n` +
-      `Last activity: ${today} — Milestone ${version} started\n\n`;
-    let newBody;
-    if (positionPattern.test(body)) {
-      newBody = body.replace(positionPattern, (_m, header) => `${header}${resetPositionBody}`);
-    } else {
-      const preface = body.trim().length > 0 ? body : '# Project State\n';
-      newBody = `${preface.trimEnd()}\n\n## Current Position\n${resetPositionBody}`;
-    }
-
-    const fm = {
-      gsd_state_version: existingFm.gsd_state_version || '1.0',
-      milestone: version,
-      milestone_name: resolvedName,
-      status: 'planning',
-      last_updated: realClock.nowIso(),
-      last_activity: today,
-      progress: {
-        total_phases: 0,
-        completed_phases: 0,
-        total_plans: 0,
-        completed_plans: 0,
-        percent: 0,
-      },
-    };
-
-    const yamlStr = reconstructFrontmatter(fm);
-    const assembled = `---\n${yamlStr}\n---\n\n${newBody.replace(/^\n+/, '')}`;
-    platformWriteSync(statePath, assembled);
-    output(
-      { switched: true, version, name: resolvedName, status: 'planning' },
-      raw,
-      'true',
-    );
-  } finally {
-    releaseStateLock(lockPath);
-  }
-}
-
-/**
- * Gate 1: Validate STATE.md against filesystem.
- * Returns { valid, warnings, drift } JSON.
- */
-function cmdStateValidate(cwd, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) {
-    output({ error: 'STATE.md not found' }, raw);
-    return;
-  }
-
-  const content = fs.readFileSync(statePath, 'utf-8');
-  const warnings = [];
-  const drift = {};
-
-  const status = stateExtractField(content, 'Status') || '';
-  const currentPhase = stateExtractField(content, 'Current Phase');
-  const totalPlansRaw = stateExtractField(content, 'Total Plans in Phase');
-  const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
-
-  const phasesDir = planningPaths(cwd).phases;
-
-  // Scan disk for current phase
-  if (currentPhase && fs.existsSync(phasesDir)) {
-    const normalized = currentPhase.replace(/\s+of\s+\d+.*/, '').trim();
-    try {
-      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-      const phaseDir = entries.find(e => e.isDirectory() && e.name.startsWith(normalized.replace(/^0+/, '').padStart(2, '0')));
-      if (phaseDir) {
-        const phaseDirPath = path.join(phasesDir, phaseDir.name);
-        const { planCount: diskPlans, summaryCount: diskSummaries } = scanPhasePlans(phaseDirPath);
-
-        // Check plan count mismatch
-        if (totalPlansInPhase !== null && diskPlans !== totalPlansInPhase) {
-          warnings.push(`Plan count mismatch: STATE.md says ${totalPlansInPhase} plans, disk has ${diskPlans}`);
-          drift.plan_count = { state: totalPlansInPhase, disk: diskPlans };
-        }
-
-        // Check for VERIFICATION.md
-        const files = fs.readdirSync(phaseDirPath);
-        const verificationFiles = files.filter(f => f.includes('VERIFICATION') && f.endsWith('.md'));
-        for (const vf of verificationFiles) {
-          try {
-            const vContent = fs.readFileSync(path.join(phaseDirPath, vf), 'utf-8');
-            if (/status:\s*passed/i.test(vContent) && /executing/i.test(status)) {
-              warnings.push(`Status drift: STATE.md says "${status}" but ${vf} shows verification passed — phase may be complete`);
-              drift.verification_status = { state_status: status, verification: 'passed' };
-            }
-          } catch { /* intentionally empty */ }
-        }
-
-        // Check if all plans have summaries but status still says executing
-        if (diskPlans > 0 && diskSummaries >= diskPlans && /executing/i.test(status)) {
-          // Only warn if no verification exists (if verification passed, the above warning covers it)
-          if (verificationFiles.length === 0) {
-            warnings.push(`All ${diskPlans} plans have summaries but status is still "${status}" — phase may be ready for verification`);
-          }
-        }
-      }
-    } catch { /* intentionally empty */ }
-  }
-
-  const valid = warnings.length === 0;
-  output({ valid, warnings, drift }, raw);
-}
-
-/**
- * Gate 2: Sync STATE.md from filesystem ground truth.
- * Scans phase dirs, reconstructs counters, progress, metrics.
- * Supports --verify for dry-run mode.
- */
-function cmdStateSync(cwd, options, raw) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) {
-    output({ error: 'STATE.md not found' }, raw);
-    return;
-  }
-
-  const verify = options && options.verify;
-  const content = fs.readFileSync(statePath, 'utf-8');
-  const changes = [];
-  let modified = content;
-  const today = realClock.today();
-
-  const phasesDir = planningPaths(cwd).phases;
-  if (!fs.existsSync(phasesDir)) {
-    output({ synced: true, changes: [], dry_run: !!verify }, raw);
-    return;
-  }
-
-  // Scan all phases
-  let entries;
-  try {
-    entries = fs.readdirSync(phasesDir, { withFileTypes: true })
-      .filter(e => e.isDirectory())
-      .map(e => e.name)
-      .sort();
-  } catch {
-    output({ synced: true, changes: [], dry_run: !!verify }, raw);
-    return;
-  }
-
-  let totalDiskPlans = 0;
-  let totalDiskSummaries = 0;
-  let diskCompletedPhases = 0;
-  let highestIncompletePhase = null;
-  let highestIncompletePhaseNum = null;
-  let highestIncompletePhaseplanCount = 0;
-  let highestIncompletePhaseSummaryCount = 0;
-
-  for (const dir of entries) {
-    const dirPath = path.join(phasesDir, dir);
-    const { planCount: plans, summaryCount: summaries, completed } = scanPhasePlans(dirPath);
-    totalDiskPlans += plans;
-    totalDiskSummaries += summaries;
-    if (completed) diskCompletedPhases++;
-
-    // Track the highest phase with incomplete plans (or any plans)
-    const phaseMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
-    if (phaseMatch && plans > 0) {
-      if (summaries < plans) {
-        // Incomplete phase — this is likely the current one
-        highestIncompletePhase = dir;
-        highestIncompletePhaseNum = phaseMatch[1];
-        highestIncompletePhaseplanCount = plans;
-        highestIncompletePhaseSummaryCount = summaries;
-      } else if (!highestIncompletePhase) {
-        // All complete, track as potential current
-        highestIncompletePhase = dir;
-        highestIncompletePhaseNum = phaseMatch[1];
-        highestIncompletePhaseplanCount = plans;
-        highestIncompletePhaseSummaryCount = summaries;
-      }
-    }
-  }
-
-  // Determine total phases from ROADMAP (may be larger than realized disk dirs).
-  // Mirrors the logic in buildStateFrontmatter so both report consistent percents (#3242 Bug B).
-  let syncTotalPhases = null;
-  try {
-    let roadmapPhaseCount = 0;
-    const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
-    const roadmapRaw = platformReadSync(roadmapPath);
-    if (roadmapRaw !== null) {
-      const roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
-      const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
-      let m;
-      while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
-        // Only count tokens that contain at least one digit — excludes
-        // pure-word section headings (Overview, Details) while keeping
-        // numeric phases (01, 05.1) and project-code IDs (PROJ-42).
-        if (/\d/.test(m[1])) roadmapPhaseCount++;
-      }
-    }
-    if (roadmapPhaseCount > 0) {
-      syncTotalPhases = Math.max(entries.length, roadmapPhaseCount);
-    } else {
-      syncTotalPhases = entries.length;
-    }
-  } catch { /* intentionally empty */ }
-
-  // Sync Total Plans in Phase
-  if (highestIncompletePhase) {
-    const currentPlansField = stateExtractField(modified, 'Total Plans in Phase');
-    if (currentPlansField && parseInt(currentPlansField, 10) !== highestIncompletePhaseplanCount) {
-      changes.push(`Total Plans in Phase: ${currentPlansField} -> ${highestIncompletePhaseplanCount}`);
-      const result = stateReplaceField(modified, 'Total Plans in Phase', String(highestIncompletePhaseplanCount));
-      if (result) modified = result;
-    }
-  }
-
-  // Sync Progress — use shared helper so formula stays in one place (#3242 Bug B).
-  // computeProgressPercent applies min(plan_fraction, phase_fraction) so unrealised
-  // ROADMAP phases cap the reported percent rather than allowing a false 100%.
-  const percent = (() => {
-    const p = computeProgressPercent(totalDiskSummaries, totalDiskPlans, diskCompletedPhases, syncTotalPhases);
-    return p !== null ? p : 0;
-  })();
-  const currentProgress = stateExtractField(modified, 'Progress');
-  if (currentProgress) {
-    const currentPercent = parseInt(currentProgress.replace(/[^\d]/g, ''), 10);
-    if (currentPercent !== percent) {
-      const barWidth = 10;
-      const filled = Math.round(percent / 100 * barWidth);
-      const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled);
-      const progressStr = `[${bar}] ${percent}%`;
-      changes.push(`Progress: ${currentProgress} -> ${progressStr}`);
-      const result = stateReplaceField(modified, 'Progress', progressStr);
-      if (result) modified = result;
-    }
-  }
-
-  // Sync Last Activity
-  const result = stateReplaceField(modified, 'Last Activity', today);
-  if (result) {
-    const oldActivity = stateExtractField(modified, 'Last Activity');
-    if (oldActivity !== today) {
-      changes.push(`Last Activity: ${oldActivity} -> ${today}`);
-    }
-    modified = result;
-  }
-
-  if (verify) {
-    output({ synced: false, changes, dry_run: true }, raw);
-    return;
-  }
-
-  if (changes.length > 0 || modified !== content) {
-    writeStateMd(statePath, modified, cwd);
-  }
-
-  output({ synced: true, changes, dry_run: false }, raw);
-}
-
-/**
- * Prune old entries from STATE.md sections that grow unboundedly (#1970).
- * Moves decisions, recently-completed summaries, and resolved blockers
- * older than keepRecent phases to STATE-ARCHIVE.md.
- *
- * Options:
- *   keepRecent: number of recent phases to retain (default: 3)
- *   dryRun: if true, return what would be pruned without modifying STATE.md
- */
-function cmdStatePrune(cwd, options, raw) {
-  const silent = !!options.silent;
-  const emit = silent ? () => {} : (result, r, v) => output(result, r, v);
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) { emit({ error: 'STATE.md not found' }, raw); return; }
-
-  const keepRecent = parseInt(options.keepRecent, 10) || 3;
-  const dryRun = !!options.dryRun;
-  const currentPhaseRaw = stateExtractField(fs.readFileSync(statePath, 'utf-8'), 'Current Phase');
-  const currentPhase = parseInt(currentPhaseRaw, 10) || 0;
-  const cutoff = currentPhase - keepRecent;
-
-  if (cutoff <= 0) {
-    emit({ pruned: false, reason: `Only ${currentPhase} phases — nothing to prune with --keep-recent ${keepRecent}` }, raw, 'false');
-    return;
-  }
-
-  const archivePath = path.join(path.dirname(statePath), 'STATE-ARCHIVE.md');
-  const archived = [];
-
-  // Shared pruning logic applied to both dry-run and real passes.
-  // Returns { newContent, archivedSections }.
-  function prunePass(content) {
-    const sections = [];
-
-    // Prune Decisions section: entries like "- [Phase N]: ..."
-    const decisionPattern = /(###?\s*(?:Decisions|Decisions Made|Accumulated.*Decisions)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
-    const decMatch = content.match(decisionPattern);
-    if (decMatch) {
-      const lines = decMatch[2].split('\n');
-      const keep = [];
-      const archive = [];
-      for (const line of lines) {
-        const phaseMatch = line.match(/^\s*-\s*\[Phase\s+(\d+)/i);
-        if (phaseMatch && parseInt(phaseMatch[1], 10) <= cutoff) {
-          archive.push(line);
-        } else {
-          keep.push(line);
-        }
-      }
-      if (archive.length > 0) {
-        sections.push({ section: 'Decisions', count: archive.length, lines: archive });
-        content = content.replace(decisionPattern, (_m, header) => `${header}${keep.join('\n')}`);
-      }
-    }
-
-    // Prune Recently Completed section: entries mentioning phase numbers
-    const recentPattern = /(###?\s*Recently Completed\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
-    const recMatch = content.match(recentPattern);
-    if (recMatch) {
-      const lines = recMatch[2].split('\n');
-      const keep = [];
-      const archive = [];
-      for (const line of lines) {
-        const phaseMatch = line.match(/Phase\s+(\d+)/i);
-        if (phaseMatch && parseInt(phaseMatch[1], 10) <= cutoff) {
-          archive.push(line);
-        } else {
-          keep.push(line);
-        }
-      }
-      if (archive.length > 0) {
-        sections.push({ section: 'Recently Completed', count: archive.length, lines: archive });
-        content = content.replace(recentPattern, (_m, header) => `${header}${keep.join('\n')}`);
-      }
-    }
-
-    // Prune resolved blockers: lines marked as resolved (strikethrough ~~text~~
-    // or "[RESOLVED]" prefix) with a phase reference older than cutoff
-    const blockersPattern = /(###?\s*(?:Blockers|Blockers\/Concerns|Blockers\s*&\s*Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
-    const blockersMatch = content.match(blockersPattern);
-    if (blockersMatch) {
-      const lines = blockersMatch[2].split('\n');
-      const keep = [];
-      const archive = [];
-      for (const line of lines) {
-        const isResolved = /~~.*~~|\[RESOLVED\]/i.test(line);
-        const phaseMatch = line.match(/Phase\s+(\d+)/i);
-        if (isResolved && phaseMatch && parseInt(phaseMatch[1], 10) <= cutoff) {
-          archive.push(line);
-        } else {
-          keep.push(line);
-        }
-      }
-      if (archive.length > 0) {
-        sections.push({ section: 'Blockers (resolved)', count: archive.length, lines: archive });
-        content = content.replace(blockersPattern, (_m, header) => `${header}${keep.join('\n')}`);
-      }
-    }
-
-    // Prune Performance Metrics table rows: keep only rows for phases > cutoff.
-    // Preserves header rows (| Phase | ... and |---|...) and any prose around the table.
-    const metricsPattern = /(###?\s*Performance Metrics\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
-    const metricsMatch = content.match(metricsPattern);
-    if (metricsMatch) {
-      const sectionLines = metricsMatch[2].split('\n');
-      const keep = [];
-      const archive = [];
-      for (const line of sectionLines) {
-        // Table data row: starts with | followed by a number (phase)
-        const tableRowMatch = line.match(/^\|\s*(\d+)\s*\|/);
-        if (tableRowMatch) {
-          const rowPhase = parseInt(tableRowMatch[1], 10);
-          if (rowPhase <= cutoff) {
-            archive.push(line);
-          } else {
-            keep.push(line);
-          }
-        } else {
-          // Header row, separator row, or prose — always keep
-          keep.push(line);
-        }
-      }
-      if (archive.length > 0) {
-        sections.push({ section: 'Performance Metrics', count: archive.length, lines: archive });
-        content = content.replace(metricsPattern, (_m, header) => `${header}${keep.join('\n')}`);
-      }
-    }
-
-    return { newContent: content, archivedSections: sections };
-  }
-
-  if (dryRun) {
-    // Dry-run: compute what would be pruned without writing anything
-    const content = fs.readFileSync(statePath, 'utf-8');
-    const result = prunePass(content);
-    const totalPruned = result.archivedSections.reduce((sum, s) => sum + s.count, 0);
-    emit({
-      pruned: false,
-      dry_run: true,
-      cutoff_phase: cutoff,
-      keep_recent: keepRecent,
-      sections: result.archivedSections.map(s => ({ section: s.section, entries_would_archive: s.count })),
-      total_would_archive: totalPruned,
-      note: totalPruned > 0 ? 'Run without --dry-run to actually prune' : 'Nothing to prune',
-    }, raw, totalPruned > 0 ? 'true' : 'false');
-    return;
-  }
-
-  readModifyWriteStateMd(statePath, (content) => {
-    const result = prunePass(content);
-    archived.push(...result.archivedSections);
-    return result.newContent;
-  }, cwd);
-
-  // Write archived entries to STATE-ARCHIVE.md
-  if (archived.length > 0) {
-    const timestamp = realClock.today();
-    let archiveContent = platformReadSync(archivePath);
-    if (archiveContent === null) {
-      archiveContent = '# STATE Archive\n\nPruned entries from STATE.md. Recoverable but no longer loaded into agent context.\n\n';
-    }
-    archiveContent += `## Pruned ${timestamp} (phases 1-${cutoff}, kept recent ${keepRecent})\n\n`;
-    for (const section of archived) {
-      archiveContent += `### ${section.section}\n\n${section.lines.join('\n')}\n\n`;
-    }
-    platformWriteSync(archivePath, archiveContent);
-  }
-
-  const totalPruned = archived.reduce((sum, s) => sum + s.count, 0);
-  emit({
-    pruned: totalPruned > 0,
-    cutoff_phase: cutoff,
-    keep_recent: keepRecent,
-    sections: archived.map(s => ({ section: s.section, entries_archived: s.count })),
-    total_archived: totalPruned,
-    archive_file: totalPruned > 0 ? 'STATE-ARCHIVE.md' : null,
-  }, raw, totalPruned > 0 ? 'true' : 'false');
-}
-
-/**
- * Mark the current phase as COMPLETE in STATE.md.
- * Updates Status, Last Activity, and the Current Position section to reflect
- * that the phase execution is finished and the project is ready for the next phase.
- * Implements the `gsd state complete-phase` subcommand (issue #2735).
- */
-function resolvePhaseIdForCompletePhase(content, overridePhase) {
-  const candidate = overridePhase ||
-    stateExtractField(content, 'Current Phase') ||
-    stateExtractField(content, 'Phase') ||
-    '';
-
-  // Accept canonical phase token only (e.g. 3, 03, 3A, 3.3, 10.2)
-  const phaseMatch = String(candidate).match(/(\d+[A-Z]?(?:\.\d+)*)/i);
-  return phaseMatch ? phaseMatch[1] : null;
-}
-
-function cmdStateCompletePhase(cwd, raw, overridePhase) {
-  const statePath = planningPaths(cwd).state;
-  if (!fs.existsSync(statePath)) {
-    output({ error: 'STATE.md not found' }, raw);
-    return;
-  }
-
-  const content = fs.readFileSync(statePath, 'utf-8');
-  const resolvedPhase = resolvePhaseIdForCompletePhase(content, overridePhase);
-  if (!resolvedPhase || /^phase$/i.test(resolvedPhase)) {
-    output({ error: 'Unable to resolve current phase. Pass an explicit phase: state complete-phase --phase <N>' }, raw);
-    return;
-  }
-
-  // Idempotency guard (#3489). If STATE.md's canonical `Current Phase` field
-  // already names a phase distinct from the one we are being asked to mark
-  // complete, the project has advanced past the requested phase (e.g. a
-  // follow-up phase was inserted, or the next phase began). Re-running
-  // `state complete-phase --phase <N>` in that situation previously rolled
-  // STATE.md back to <N>'s moment-of-completion — silently clobbering Status,
-  // Last Activity, Last Activity Description, and the Current Position body.
-  // The handler is now a no-op in that case so re-invocation from downstream
-  // workflows cannot regress the project state.
-  const existingCurrentPhaseRaw = stateExtractField(content, 'Current Phase') || '';
-  const existingCurrentPhaseMatch = String(existingCurrentPhaseRaw).match(/(\d+[A-Z]?(?:\.\d+)*)/i);
-  const existingCurrentPhase = existingCurrentPhaseMatch ? existingCurrentPhaseMatch[1] : null;
-  if (existingCurrentPhase && existingCurrentPhase !== resolvedPhase) {
-    output(
-      { updated: [], phase: resolvedPhase, idempotent: true, note: 'phase already superseded; no-op' },
-      raw,
-      'false',
-    );
-    return;
-  }
-
-  const today = realClock.today();
-  const updated = [];
-
-  readModifyWriteStateMd(statePath, (content) => {
-    const currentPhase = resolvedPhase;
-
-    // Update Status field
-    const statusValue = `Phase ${currentPhase} complete`;
-    let result = stateReplaceField(content, 'Status', statusValue);
-    if (result) { content = result; updated.push('Status'); }
-
-    // Update Last Activity date
-    result = stateReplaceField(content, 'Last Activity', today);
-    if (result) { content = result; updated.push('Last Activity'); }
-
-    // Update Last Activity Description
-    const activityDesc = `Phase ${currentPhase} marked complete`;
-    result = stateReplaceField(content, 'Last Activity Description', activityDesc);
-    if (result) { content = result; updated.push('Last Activity Description'); }
-
-    // Update ## Current Position section
-    const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
-    const positionMatch = content.match(positionPattern);
-    if (positionMatch) {
-      const header = positionMatch[1];
-      let posBody = positionMatch[2];
-
-      // Update Phase line to show COMPLETE
-      const newPhase = `Phase: ${currentPhase} — COMPLETE`;
-      if (/^Phase:/m.test(posBody)) {
-        posBody = posBody.replace(/^Phase:.*$/m, newPhase);
-      }
-
-      // Update Status line if present
-      const newStatus = `Status: Phase ${currentPhase} complete`;
-      if (/^Status:/m.test(posBody)) {
-        posBody = posBody.replace(/^Status:.*$/m, newStatus);
-      }
-
-      // Update Last activity line if present
-      const newActivity = `Last activity: ${today} -- Phase ${currentPhase} marked complete`;
-      if (/^Last activity:/im.test(posBody)) {
-        posBody = posBody.replace(/^Last activity:.*$/im, newActivity);
-      }
-
-      content = content.replace(positionPattern, () => `${header}${posBody}`);
-      updated.push('Current Position');
-    }
-
-    return content;
-  }, cwd);
-
-  output(
-    { updated, phase: resolvedPhase },
-    raw,
-    updated.length > 0 ? 'true' : 'false',
-  );
-}
-
-module.exports = {
-  stateExtractField,
-  stateReplaceField,
-  stateReplaceFieldWithFallback,
-  acquireStateLock,
-  releaseStateLock,
-  writeStateMd,
-  readModifyWriteStateMd,
-  syncStateFrontmatter,
-  withStateLock,
-  updatePerformanceMetricsSection,
-  cmdStateLoad,
-  cmdStateGet,
-  cmdStatePatch,
-  cmdStateUpdate,
-  cmdStateAdvancePlan,
-  cmdStateRecordMetric,
-  cmdStateUpdateProgress,
-  cmdStateAddDecision,
-  cmdStateAddBlocker,
-  cmdStateResolveBlocker,
-  cmdStateRecordSession,
-  cmdStateSnapshot,
-  cmdStateJson,
-  cmdStateBeginPhase,
-  cmdStatePlannedPhase,
-  cmdStateCompletePhase,
-  cmdStateValidate,
-  cmdStateSync,
-  cmdStatePrune,
-  cmdStateMilestoneSwitch,
-  cmdSignalWaiting,
-  cmdSignalResume,
-};