@ikunin/sprintpilot 2.0.10 → 2.1.0

package/_Sprintpilot/lib/orchestrator/state-machine.js

@@ -0,0 +1,402 @@
+// state-machine.js — BMad 7-step state machine (pure, table-driven).
+//
+// States (story-scoped, in order):
+//   1. create_story
+//   2. check_readiness
+//   3. dev_red
+//   4. dev_green
+//   5. code_review
+//   6a. patch_apply       (entered only if review has any 'patch' finding)
+//   6b. patch_retest      (entered after 6a)
+//   7. story_done
+//   8. epic_boundary_check
+//   9. retrospective      (per-epic; only when retrospective_mode != 'skip')
+//   10. sprint_finalize_pending
+//
+// Nano profile collapses 1–6 into a single `nano_quick_dev` state that
+// emits `invoke_skill: bmad-quick-dev`.
+//
+// Pure. nextAction(state, profile, world) → Action object.
+//
+// `state` is the orchestrator's runtime state shape:
+//   {
+//     phase,                  // one of STATES below
+//     story_key,              // current story
+//     story_file_path,        // resolved path for story file
+//     current_epic,           // epic key for current story
+//     ac_summary,             // compact AC summary
+//     prior_diagnosis,        // last failure diagnosis (or null)
+//     relevant_decisions,     // decision-log entries scoped to this story
+//     prior_signals_summary,
+//     patch_findings,         // structured findings[] from review (when in step 6)
+//     tests_to_rerun,
+//     remaining_stories_in_epic, // count
+//     remaining_epics,           // count
+//     sprint_is_complete,
+//     escalation_note,        // when nano escalated, populated for template
+//   }
+//
+// `profile` is the typed Profile from profile-rules.js.
+
+'use strict';
+
+const STATES = Object.freeze({
+  CREATE_STORY: 'create_story',
+  CHECK_READINESS: 'check_readiness',
+  DEV_RED: 'dev_red',
+  DEV_GREEN: 'dev_green',
+  CODE_REVIEW: 'code_review',
+  PATCH_APPLY: 'patch_apply',
+  PATCH_RETEST: 'patch_retest',
+  STORY_DONE: 'story_done',
+  // STORY_LAND — entered only when profile.merge_strategy === 'land_as_you_go'.
+  // Composes stack-snapshot.js + land-this-pr.js to merge the just-finished
+  // story's PR into base. Skipped (STORY_DONE → EPIC_BOUNDARY_CHECK directly)
+  // under the default 'stacked' strategy.
+  STORY_LAND: 'story_land',
+  EPIC_BOUNDARY_CHECK: 'epic_boundary_check',
+  RETROSPECTIVE: 'retrospective',
+  SPRINT_FINALIZE_PENDING: 'sprint_finalize_pending',
+  // Nano-only collapsed state.
+  NANO_QUICK_DEV: 'nano_quick_dev',
+});
+
+const TERMINAL_STATES = new Set([STATES.SPRINT_FINALIZE_PENDING]);
+
+// Successor table for the FULL flow. Used to enumerate "structurally valid
+// successors" when a next_skill_hint disambiguation is needed. Conditional
+// edges (e.g. patch_apply only when findings.action==='patch') are
+// enforced in `nextStateAfterSuccess`.
+const FULL_FLOW_SUCCESSORS = {
+  [STATES.CREATE_STORY]: [STATES.CHECK_READINESS],
+  [STATES.CHECK_READINESS]: [STATES.DEV_RED],
+  [STATES.DEV_RED]: [STATES.DEV_GREEN],
+  [STATES.DEV_GREEN]: [STATES.CODE_REVIEW],
+  [STATES.CODE_REVIEW]: [STATES.PATCH_APPLY, STATES.STORY_DONE], // conditional
+  [STATES.PATCH_APPLY]: [STATES.PATCH_RETEST],
+  [STATES.PATCH_RETEST]: [STATES.CODE_REVIEW, STATES.STORY_DONE], // conditional (re-review if still blocking)
+  [STATES.STORY_DONE]: [STATES.STORY_LAND, STATES.EPIC_BOUNDARY_CHECK], // STORY_LAND only under land_as_you_go
+  [STATES.STORY_LAND]: [STATES.EPIC_BOUNDARY_CHECK],
+  [STATES.EPIC_BOUNDARY_CHECK]: [STATES.RETROSPECTIVE, STATES.CREATE_STORY, STATES.SPRINT_FINALIZE_PENDING],
+  [STATES.RETROSPECTIVE]: [STATES.CREATE_STORY, STATES.SPRINT_FINALIZE_PENDING],
+};
+
+const NANO_FLOW_SUCCESSORS = {
+  [STATES.NANO_QUICK_DEV]: [STATES.STORY_DONE],
+  [STATES.STORY_DONE]: [STATES.STORY_LAND, STATES.EPIC_BOUNDARY_CHECK],
+  [STATES.STORY_LAND]: [STATES.EPIC_BOUNDARY_CHECK],
+  [STATES.EPIC_BOUNDARY_CHECK]: [STATES.RETROSPECTIVE, STATES.NANO_QUICK_DEV, STATES.SPRINT_FINALIZE_PENDING],
+  [STATES.RETROSPECTIVE]: [STATES.NANO_QUICK_DEV, STATES.SPRINT_FINALIZE_PENDING],
+};
+
+// Build instruction template content slots from state + profile. This is the
+// LLM-intelligence preservation channel: every skill invocation gets a rich
+// context bundle, not a free-form prose blob.
+function buildTemplateSlots(state, profile, extra = {}) {
+  return {
+    story_key: state.story_key || null,
+    story_file_path: state.story_file_path || null,
+    ac_summary: state.ac_summary || null,
+    prior_diagnosis: state.prior_diagnosis || null,
+    relevant_decisions: state.relevant_decisions || [],
+    prior_signals_summary: state.prior_signals_summary || null,
+    patch_findings: state.patch_findings || null,
+    tests_to_rerun: state.tests_to_rerun || null,
+    profile_name: profile.name,
+    profile_specific_notes: state.escalation_note || profileNotes(profile),
+    ...extra,
+  };
+}
+
+function profileNotes(profile) {
+  if (profile.name === 'nano') {
+    return 'nano: bmad-quick-dev one-shot; escalate to full flow on test fail or high severity.';
+  }
+  return null;
+}
+
+// nextAction(state, profile) → Action
+//   Returns the canonical action for the current `state.phase`.
+function nextAction(state, profile) {
+  if (!state || !state.phase) {
+    throw new Error('nextAction: state.phase required');
+  }
+  if (state.sprint_is_complete && state.phase !== STATES.SPRINT_FINALIZE_PENDING) {
+    return {
+      type: 'halt',
+      reason: 'sprint_complete',
+      handoff: 'sprint_finalize_pending',
+    };
+  }
+
+  switch (state.phase) {
+    case STATES.CREATE_STORY:
+      return {
+        type: 'invoke_skill',
+        skill: 'bmad-create-story',
+        phase: state.phase,
+        template: 'bmad-create-story.tmpl.md',
+        template_slots: buildTemplateSlots(state, profile),
+      };
+    case STATES.CHECK_READINESS:
+      return {
+        type: 'invoke_skill',
+        skill: 'bmad-check-implementation-readiness',
+        phase: state.phase,
+        template: 'bmad-check-implementation-readiness.tmpl.md',
+        template_slots: buildTemplateSlots(state, profile),
+      };
+    case STATES.DEV_RED:
+      return {
+        type: 'invoke_skill',
+        skill: 'bmad-dev-story',
+        phase: state.phase,
+        template: 'bmad-dev-story.red.tmpl.md',
+        template_slots: buildTemplateSlots(state, profile, { tdd_phase: 'red' }),
+      };
+    case STATES.DEV_GREEN:
+      return {
+        type: 'invoke_skill',
+        skill: 'bmad-dev-story',
+        phase: state.phase,
+        template: 'bmad-dev-story.green.tmpl.md',
+        template_slots: buildTemplateSlots(state, profile, { tdd_phase: 'green' }),
+      };
+    case STATES.CODE_REVIEW:
+      return {
+        type: 'invoke_skill',
+        skill: 'bmad-code-review',
+        phase: state.phase,
+        template: 'bmad-code-review.tmpl.md',
+        template_slots: buildTemplateSlots(state, profile),
+      };
+    case STATES.PATCH_APPLY:
+      return {
+        type: 'invoke_skill',
+        skill: 'bmad-dev-story',
+        phase: state.phase,
+        template: 'bmad-dev-story.patch.tmpl.md',
+        template_slots: buildTemplateSlots(state, profile, { tdd_phase: 'patch' }),
+      };
+    case STATES.PATCH_RETEST:
+      return {
+        type: 'invoke_skill',
+        skill: 'bmad-dev-story',
+        phase: state.phase,
+        template: 'bmad-dev-story.rereview.tmpl.md',
+        template_slots: buildTemplateSlots(state, profile, { tdd_phase: 'rereview' }),
+      };
+    case STATES.STORY_DONE:
+      return {
+        type: 'git_op',
+        phase: state.phase,
+        op: 'commit_and_push_story',
+        story_key: state.story_key,
+        profile: profile.name,
+      };
+    case STATES.STORY_LAND:
+      // Land-as-you-go: orchestrator plumbing emits a `run_script` that
+      // wraps the existing stack-snapshot.js + land-this-pr.js scripts.
+      // Honors land_when (no_wait | ci_pass | ci_and_review) and
+      // land_wait_minutes from the profile.
+      return {
+        type: 'run_script',
+        phase: state.phase,
+        op: 'land_story',
+        story_key: state.story_key,
+        profile: profile.name,
+        land_when: profile.land_when || 'ci_pass',
+        land_wait_minutes:
+          typeof profile.land_wait_minutes === 'number' ? profile.land_wait_minutes : 30,
+        squash_on_merge: !!profile.squash_on_merge,
+        // The CLI edge composes the actual argv via land.js#planLand; this
+        // action only declares intent so the harness/log can see it.
+        helper: 'lib/orchestrator/land.js',
+      };
+    case STATES.EPIC_BOUNDARY_CHECK:
+      return {
+        type: 'noop',
+        phase: state.phase,
+        reason: 'epic_boundary_check',
+      };
+    case STATES.RETROSPECTIVE: {
+      if (profile.retrospective_mode === 'stop') {
+        return {
+          type: 'user_prompt',
+          phase: state.phase,
+          reason: 'retrospective_mode_stop',
+          prompt:
+            'Retrospective requested in `stop` mode. Run `/bmad-retrospective` interactively, then resume autopilot.',
+        };
+      }
+      return {
+        type: 'invoke_skill',
+        skill: 'bmad-retrospective',
+        phase: state.phase,
+        template: 'bmad-retrospective.tmpl.md',
+        template_slots: buildTemplateSlots(state, profile, {
+          epic_key: state.current_epic || null,
+        }),
+      };
+    }
+    case STATES.SPRINT_FINALIZE_PENDING:
+      return {
+        type: 'halt',
+        phase: state.phase,
+        reason: 'sprint_complete',
+        handoff: 'sprint_finalize_pending',
+      };
+    case STATES.NANO_QUICK_DEV:
+      return {
+        type: 'invoke_skill',
+        skill: 'bmad-quick-dev',
+        phase: state.phase,
+        template: 'bmad-quick-dev.tmpl.md',
+        template_slots: buildTemplateSlots(state, profile),
+      };
+    default:
+      throw new Error(`nextAction: unknown phase ${state.phase}`);
+  }
+}
+
+// nextStateAfterSuccess(currentState, profile, signal) → newPhase
+// Encodes the conditional edges (code_review→patch_apply only when any
+// finding.action==='patch'; patch_retest→code_review when blocking remains;
+// epic_boundary_check → retrospective when end of epic; etc.)
+//
+// Returns the next phase string, or null when the LLM should pause (the
+// orchestrator will look at the previous action's success.output for hints).
+function nextStateAfterSuccess(currentState, profile, signal) {
+  if (!currentState || !currentState.phase) throw new Error('nextStateAfterSuccess: phase required');
+  const phase = currentState.phase;
+  const output = (signal && signal.output) || {};
+
+  // First: hint tiebreaker. If the LLM provided a structurally-valid hint, prefer it.
+  const successors = (profile.implementation_flow === 'quick' ? NANO_FLOW_SUCCESSORS : FULL_FLOW_SUCCESSORS)[phase] || [];
+  const hint = signal && signal.next_skill_hint;
+  // We only consult the hint when the deterministic decision below has more
+  // than one valid successor. Compute the deterministic answer first.
+
+  const det = deterministicNext(currentState, profile, output);
+  if (det && successors.length > 1 && hint && hintMatchesPhase(hint, det.allValid)) {
+    const chosen = mapHintToPhase(hint, det.allValid);
+    if (chosen) return chosen;
+  }
+  return det ? det.chosen : null;
+}
+
+function deterministicNext(state, profile, output) {
+  const phase = state.phase;
+  switch (phase) {
+    case STATES.CREATE_STORY:
+      return { chosen: STATES.CHECK_READINESS, allValid: [STATES.CHECK_READINESS] };
+    case STATES.CHECK_READINESS:
+      return { chosen: STATES.DEV_RED, allValid: [STATES.DEV_RED] };
+    case STATES.DEV_RED:
+      return { chosen: STATES.DEV_GREEN, allValid: [STATES.DEV_GREEN] };
+    case STATES.DEV_GREEN:
+      return { chosen: STATES.CODE_REVIEW, allValid: [STATES.CODE_REVIEW] };
+    case STATES.CODE_REVIEW: {
+      const findings = Array.isArray(output.findings) ? output.findings : [];
+      const hasPatch = findings.some((f) => f && f.action === 'patch');
+      const hasBlock = findings.some((f) => f && f.action === 'block');
+      // `block` findings produce a user_prompt via the adapt layer — not a
+      // forward state transition. Here we just choose the structural successor.
+      if (hasBlock) return null;
+      const chosen = hasPatch ? STATES.PATCH_APPLY : STATES.STORY_DONE;
+      return { chosen, allValid: [STATES.PATCH_APPLY, STATES.STORY_DONE] };
+    }
+    case STATES.PATCH_APPLY:
+      return { chosen: STATES.PATCH_RETEST, allValid: [STATES.PATCH_RETEST] };
+    case STATES.PATCH_RETEST: {
+      const findings = Array.isArray(output.remaining_findings) ? output.remaining_findings : [];
+      const stillBlocking = findings.some((f) => f && f.action === 'block');
+      const chosen = stillBlocking ? STATES.CODE_REVIEW : STATES.STORY_DONE;
+      return { chosen, allValid: [STATES.CODE_REVIEW, STATES.STORY_DONE] };
+    }
+    case STATES.STORY_DONE: {
+      // Land-as-you-go: route through STORY_LAND before EPIC_BOUNDARY_CHECK.
+      // The default 'stacked' strategy skips STORY_LAND entirely.
+      const goLand =
+        profile && profile.merge_strategy === 'land_as_you_go'
+          ? STATES.STORY_LAND
+          : STATES.EPIC_BOUNDARY_CHECK;
+      return { chosen: goLand, allValid: [STATES.STORY_LAND, STATES.EPIC_BOUNDARY_CHECK] };
+    }
+    case STATES.STORY_LAND:
+      return { chosen: STATES.EPIC_BOUNDARY_CHECK, allValid: [STATES.EPIC_BOUNDARY_CHECK] };
+    case STATES.EPIC_BOUNDARY_CHECK: {
+      const remainingInEpic = state.remaining_stories_in_epic || 0;
+      const sprintDone = !!state.sprint_is_complete;
+      // End of epic?
+      if (remainingInEpic <= 0) {
+        if (profile.retrospective_mode === 'skip') {
+          return {
+            chosen: sprintDone ? STATES.SPRINT_FINALIZE_PENDING : nextStoryStart(profile),
+            allValid: [STATES.SPRINT_FINALIZE_PENDING, nextStoryStart(profile)],
+          };
+        }
+        return { chosen: STATES.RETROSPECTIVE, allValid: [STATES.RETROSPECTIVE] };
+      }
+      // More stories in the same epic.
+      return { chosen: nextStoryStart(profile), allValid: [nextStoryStart(profile)] };
+    }
+    case STATES.RETROSPECTIVE: {
+      const sprintDone = !!state.sprint_is_complete;
+      const chosen = sprintDone ? STATES.SPRINT_FINALIZE_PENDING : nextStoryStart(profile);
+      return { chosen, allValid: [STATES.SPRINT_FINALIZE_PENDING, nextStoryStart(profile)] };
+    }
+    case STATES.NANO_QUICK_DEV:
+      return { chosen: STATES.STORY_DONE, allValid: [STATES.STORY_DONE] };
+    case STATES.SPRINT_FINALIZE_PENDING:
+      return null;
+    default:
+      return null;
+  }
+}
+
+function nextStoryStart(profile) {
+  return profile.implementation_flow === 'quick' ? STATES.NANO_QUICK_DEV : STATES.CREATE_STORY;
+}
+
+// Best-effort mapping from a next_skill_hint string (e.g. "bmad-code-review")
+// to a phase identifier. Used only as a tiebreaker.
+const HINT_TO_PHASE = {
+  'bmad-create-story': STATES.CREATE_STORY,
+  'bmad-check-implementation-readiness': STATES.CHECK_READINESS,
+  'bmad-dev-story:red': STATES.DEV_RED,
+  'bmad-dev-story:green': STATES.DEV_GREEN,
+  'bmad-dev-story:patch': STATES.PATCH_APPLY,
+  'bmad-dev-story:rereview': STATES.PATCH_RETEST,
+  'bmad-code-review': STATES.CODE_REVIEW,
+  'bmad-retrospective': STATES.RETROSPECTIVE,
+  'bmad-quick-dev': STATES.NANO_QUICK_DEV,
+  story_done: STATES.STORY_DONE,
+  sprint_finalize_pending: STATES.SPRINT_FINALIZE_PENDING,
+};
+
+function mapHintToPhase(hint, allValidPhases) {
+  if (typeof hint !== 'string') return null;
+  const phase = HINT_TO_PHASE[hint];
+  if (!phase) return null;
+  if (!allValidPhases.includes(phase)) return null;
+  return phase;
+}
+
+function hintMatchesPhase(hint, allValidPhases) {
+  return mapHintToPhase(hint, allValidPhases) !== null;
+}
+
+module.exports = {
+  STATES,
+  TERMINAL_STATES,
+  FULL_FLOW_SUCCESSORS,
+  NANO_FLOW_SUCCESSORS,
+  nextAction,
+  nextStateAfterSuccess,
+  // Exposed for adapt.js to construct fresh-story states.
+  nextStoryStart,
+  // Exposed for tests / inspection.
+  buildTemplateSlots,
+  HINT_TO_PHASE,
+};

package/_Sprintpilot/lib/orchestrator/state-store.js

@@ -0,0 +1,260 @@
+// state-store.js — single chokepoint for autopilot state writes.
+//
+// Honors `coalesce_state_writes` from the active profile:
+//
+//   coalesce_state_writes: false  (legacy v1.0.5 path)
+//     → every write goes straight to autopilot-state.yaml
+//
+//   coalesce_state_writes: true   (M3 / PR 6 path)
+//     → CRITICAL_KEYS write straight through (crash-recovery semantics)
+//     → non-critical fields accumulate in a pending buffer per story
+//     → buffer is flushed at story boundary + session checkpoint
+//
+// CRITICAL_KEYS mirror state-shard.js so the two implementations stay
+// semantically aligned. Tests cover both code paths.
+//
+// All I/O goes through an injected `fs` so tests use tmp dirs and the
+// orchestrator can wire in alternative stores later.
+
+'use strict';
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+
+// Mirrors _Sprintpilot/scripts/state-shard.js#CRITICAL_KEYS.
+const CRITICAL_KEYS = new Set([
+  'current_story',
+  'current_bmad_step',
+  'in_worktree',
+  'patch_commits',
+]);
+
+// In-memory pending buffer. Process-scoped — flushed at story boundary or
+// session checkpoint. Keyed by story.
+const _pendingBuffers = new Map();
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function deepMerge(target, source) {
+  if (!isPlainObject(source)) return source;
+  const out = isPlainObject(target) ? { ...target } : {};
+  for (const key of Object.keys(source)) {
+    const sv = source[key];
+    const tv = out[key];
+    if (isPlainObject(sv) && isPlainObject(tv)) out[key] = deepMerge(tv, sv);
+    else out[key] = sv;
+  }
+  return out;
+}
+
+function dumpYaml(obj, indent = 0) {
+  const pad = '  '.repeat(indent);
+  const lines = [];
+  for (const key of Object.keys(obj)) {
+    const val = obj[key];
+    if (val === null || val === undefined) lines.push(`${pad}${key}: null`);
+    else if (Array.isArray(val)) lines.push(`${pad}${key}: ${JSON.stringify(val)}`);
+    else if (isPlainObject(val)) {
+      lines.push(`${pad}${key}:`);
+      const inner = dumpYaml(val, indent + 1);
+      if (inner) lines.push(inner);
+    } else if (typeof val === 'boolean' || typeof val === 'number') {
+      lines.push(`${pad}${key}: ${val}`);
+    } else {
+      const s = String(val);
+      const needsQuote = /^(true|false|null|~)$/i.test(s) || /^-?\d/.test(s) || /[:#]/.test(s);
+      lines.push(`${pad}${key}: ${needsQuote ? JSON.stringify(s) : s}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+// Atomic write via tmp sibling + rename.
+function atomicWrite(fs, filePath, text) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+  fs.writeFileSync(tmp, text, 'utf8');
+  fs.renameSync(tmp, filePath);
+}
+
+function readStateFile(fs, filePath) {
+  try {
+    const text = fs.readFileSync(filePath, 'utf8');
+    return parseYamlNarrow(text);
+  } catch (_e) {
+    return {};
+  }
+}
+
+// Narrow YAML parser sufficient for our write shape (the same shape we
+// produce via dumpYaml above). We deliberately avoid js-yaml so we don't
+// pull a runtime dep into the install-time script bundle.
+function parseYamlNarrow(text) {
+  if (!text) return {};
+  const lines = text.split(/\r?\n/);
+  const root = {};
+  const stack = [{ indent: -1, obj: root }];
+  for (const raw of lines) {
+    const hashIdx = raw.indexOf('#');
+    const line = hashIdx === -1 ? raw : raw.slice(0, hashIdx);
+    if (!line.trim()) continue;
+    const indent = line.match(/^( *)/)[1].length;
+    const content = line.slice(indent).trimEnd();
+    const colon = content.indexOf(':');
+    if (colon === -1) continue;
+    const key = content.slice(0, colon).trim();
+    const rest = content.slice(colon + 1).trim();
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) stack.pop();
+    const parent = stack[stack.length - 1].obj;
+    if (rest === '') {
+      const child = {};
+      parent[key] = child;
+      stack.push({ indent, obj: child });
+      continue;
+    }
+    parent[key] = parseScalar(rest);
+  }
+  return root;
+}
+
+function parseScalar(raw) {
+  if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+    try {
+      return JSON.parse(raw);
+    } catch (_e) {
+      return raw.slice(1, -1);
+    }
+  }
+  if (raw.startsWith('[') || raw.startsWith('{')) {
+    try {
+      return JSON.parse(raw);
+    } catch (_e) {
+      return raw;
+    }
+  }
+  if (raw === 'null' || raw === '~') return null;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (/^-?\d+$/.test(raw)) return Number.parseInt(raw, 10);
+  if (/^-?\d+\.\d+$/.test(raw)) return Number.parseFloat(raw);
+  return raw;
+}
+
+function resolveStatePath(projectRoot) {
+  return path.join(
+    projectRoot,
+    '_bmad-output',
+    'implementation-artifacts',
+    'autopilot-state.yaml',
+  );
+}
+
+function bufferKey(story) {
+  return story || 'sprint';
+}
+
+// write(updates, profile, context)
+//   updates: object of key→value updates (deep-merged into the file)
+//   profile: typed Profile (only `coalesce_state_writes` is consulted here)
+//   context: { projectRoot, story, fs? }
+// Returns { mode: 'direct' | 'critical' | 'pending', flushed: boolean }
+function write(updates, profile, context) {
+  if (!isPlainObject(updates)) throw new Error('write: updates must be an object');
+  if (!profile) throw new Error('write: profile required');
+  if (!context || !context.projectRoot) throw new Error('write: context.projectRoot required');
+  const fs = (context && context.fs) || nodeFs;
+  const story = context.story;
+
+  // Legacy path: direct write.
+  if (!profile.coalesce_state_writes) {
+    return writeDirect(fs, context.projectRoot, updates);
+  }
+
+  // Coalesce path. Split critical vs non-critical.
+  const critical = {};
+  const nonCritical = {};
+  let hasCritical = false;
+  let hasNonCritical = false;
+  for (const k of Object.keys(updates)) {
+    if (CRITICAL_KEYS.has(k)) {
+      critical[k] = updates[k];
+      hasCritical = true;
+    } else {
+      nonCritical[k] = updates[k];
+      hasNonCritical = true;
+    }
+  }
+
+  // If we have critical writes, flush pending first then write critical + accumulated.
+  if (hasCritical) {
+    const key = bufferKey(story);
+    const buf = _pendingBuffers.get(key) || {};
+    const merged = { ...buf, ...nonCritical, ...critical };
+    _pendingBuffers.delete(key);
+    writeDirect(fs, context.projectRoot, merged);
+    return { mode: 'critical', flushed: true };
+  }
+
+  // Non-critical only → buffer.
+  if (hasNonCritical) {
+    const key = bufferKey(story);
+    const buf = _pendingBuffers.get(key) || {};
+    _pendingBuffers.set(key, deepMerge(buf, nonCritical));
+    return { mode: 'pending', flushed: false };
+  }
+  return { mode: 'noop', flushed: false };
+}
+
+// writeDirect — write to autopilot-state.yaml directly, merging on top.
+function writeDirect(fs, projectRoot, updates) {
+  const filePath = resolveStatePath(projectRoot);
+  const existing = readStateFile(fs, filePath);
+  const merged = deepMerge(existing, updates);
+  merged.last_updated = new Date().toISOString();
+  atomicWrite(fs, filePath, `${dumpYaml(merged)}\n`);
+  return { mode: 'direct', flushed: true };
+}
+
+// flush(profile, context) — flush pending buffer for the given story.
+// Called at story boundary and session checkpoint.
+function flush(profile, context) {
+  if (!profile || !profile.coalesce_state_writes) return { flushed: false, mode: 'noop' };
+  if (!context || !context.projectRoot) throw new Error('flush: context.projectRoot required');
+  const fs = (context && context.fs) || nodeFs;
+  const key = bufferKey(context.story);
+  const buf = _pendingBuffers.get(key);
+  if (!buf || Object.keys(buf).length === 0) return { flushed: false, mode: 'noop' };
+  _pendingBuffers.delete(key);
+  writeDirect(fs, context.projectRoot, buf);
+  return { flushed: true, mode: 'flush' };
+}
+
+// read(context) — read full state object from disk.
+function read(context) {
+  if (!context || !context.projectRoot) throw new Error('read: context.projectRoot required');
+  const fs = (context && context.fs) || nodeFs;
+  return readStateFile(fs, resolveStatePath(context.projectRoot));
+}
+
+// peekPending(story) — for tests + debugging.
+function peekPending(story) {
+  const buf = _pendingBuffers.get(bufferKey(story));
+  return buf ? { ...buf } : null;
+}
+
+// resetPending() — clear all buffers; tests only.
+function resetPending() {
+  _pendingBuffers.clear();
+}
+
+module.exports = {
+  CRITICAL_KEYS: Array.from(CRITICAL_KEYS),
+  write,
+  flush,
+  read,
+  peekPending,
+  resetPending,
+  resolveStatePath,
+};