@ikunin/sprintpilot 2.0.10 → 2.1.0

package/_Sprintpilot/lib/orchestrator/impact-classifier.js

@@ -0,0 +1,108 @@
+// impact-classifier.js — classify the impact of a propose_alternative signal.
+//
+// The LLM proposes an alternative action. The orchestrator decides whether
+// to auto-accept (low impact) or escalate to user_prompt (medium / high).
+//
+// Design (from the plan):
+//   - Different action `type`               → high
+//   - Same type, different skill / script   → medium
+//   - Same skill, args differ:
+//       * all differing args are in LOW_RISK_ARG_WHITELIST → low
+//       * otherwise                                        → medium
+//   - LLM-supplied `urgency_hint` can only RAISE the classification,
+//     never lower it.
+//
+// Pure module. No I/O.
+
+'use strict';
+
+const LOW_RISK_ARG_WHITELIST = new Set([
+  'retry_budget',
+  'action_id',
+  'rationale',
+  'branch_name_suffix',
+]);
+
+const URGENCY_RANK = { low: 0, medium: 1, high: 2 };
+const RANK_TO_URGENCY = ['low', 'medium', 'high'];
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function diffArgs(planned, alternative) {
+  const a = isPlainObject(planned) ? planned : {};
+  const b = isPlainObject(alternative) ? alternative : {};
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  const diffs = [];
+  for (const k of keys) {
+    if (!deepEqual(a[k], b[k])) diffs.push(k);
+  }
+  return diffs;
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== 'object') return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (!deepEqual(a[k], b[k])) return false;
+  }
+  return true;
+}
+
+function bumpByUrgency(level, urgencyHint) {
+  if (!urgencyHint || !(urgencyHint in URGENCY_RANK)) return level;
+  const baseRank = URGENCY_RANK[level];
+  const hintRank = URGENCY_RANK[urgencyHint];
+  return RANK_TO_URGENCY[Math.max(baseRank, hintRank)];
+}
+
+// classifyImpact(planned, alternative, llmUrgencyHint?) → 'low' | 'medium' | 'high'
+function classifyImpact(planned, alternative, llmUrgencyHint) {
+  if (!isPlainObject(planned) || !isPlainObject(alternative)) {
+    return bumpByUrgency('high', llmUrgencyHint);
+  }
+  if (planned.type !== alternative.type) {
+    return bumpByUrgency('high', llmUrgencyHint);
+  }
+
+  // Same type. For invoke_skill we look at skill identity then args.
+  // For run_script we look at command[0] then args. For git_op we look at
+  // git subcommand.
+  if (planned.type === 'invoke_skill') {
+    if (planned.skill !== alternative.skill) return bumpByUrgency('medium', llmUrgencyHint);
+  } else if (planned.type === 'run_script') {
+    const pcmd = Array.isArray(planned.command) ? planned.command[0] : undefined;
+    const acmd = Array.isArray(alternative.command) ? alternative.command[0] : undefined;
+    if (pcmd !== acmd) return bumpByUrgency('medium', llmUrgencyHint);
+  } else if (planned.type === 'git_op') {
+    if (planned.op !== alternative.op) return bumpByUrgency('medium', llmUrgencyHint);
+  }
+
+  const argDiffs = diffArgs(planned.args, alternative.args);
+  if (argDiffs.length === 0) {
+    // No arg differences at all — only metadata changed; treat as low.
+    return bumpByUrgency('low', llmUrgencyHint);
+  }
+  const allWhitelisted = argDiffs.every((k) => LOW_RISK_ARG_WHITELIST.has(k));
+  return bumpByUrgency(allWhitelisted ? 'low' : 'medium', llmUrgencyHint);
+}
+
+module.exports = {
+  classifyImpact,
+  diffArgs,
+  LOW_RISK_ARG_WHITELIST: Array.from(LOW_RISK_ARG_WHITELIST),
+};

package/_Sprintpilot/lib/orchestrator/land.js

@@ -0,0 +1,155 @@
+// land.js — orchestrator helper for `merge_strategy: land_as_you_go`.
+//
+// This module composes existing scripts (stack-snapshot.js +
+// land-this-pr.js) into a step plan the autopilot CLI executes after
+// STORY_DONE. It does NOT define a BMad workflow — BMad's domain is
+// story creation, dev, review, retrospective. This is orchestrator
+// plumbing for the git layer.
+//
+// Pure: planLand(state, profile) → { steps, blocking_user_prompt? }
+//
+// Step shape mirrors git-plan.js: { args, description, retry? }. The CLI
+// executes steps sequentially via execFileSync.
+
+'use strict';
+
+const path = require('node:path');
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// planLand(state, profile, options) → { steps, halt?, prompt? }
+//   state.user_branch / state.story_key / state.current_epic → branch identity
+//   profile.land_when                → no_wait | ci_pass | ci_and_review
+//   profile.land_wait_minutes        → polling budget
+//   profile.squash_on_merge          → forwarded to land-this-pr.js
+//   options.scriptsDir               → absolute path to _Sprintpilot/scripts
+//   options.snapshotPath             → tmp file path the snapshot will be written to
+//   options.branch                   → resolved branch name (from git-plan.branchName)
+//   options.platform                 → 'github' | 'gitlab' | 'git_only'
+function planLand(state, profile, options) {
+  if (!state || !state.story_key) {
+    throw new Error('planLand: state.story_key required');
+  }
+  if (!profile) throw new Error('planLand: profile required');
+  if (!options || !options.scriptsDir || !options.snapshotPath) {
+    throw new Error('planLand: options.scriptsDir + snapshotPath required');
+  }
+
+  const branch = options.branch;
+  if (!branch) throw new Error('planLand: options.branch required');
+
+  const baseBranch = profile.base_branch || 'main';
+  const landWhen = profile.land_when || 'ci_pass';
+  const waitMinutes = Number.isFinite(profile.land_wait_minutes) ? profile.land_wait_minutes : 30;
+  const squash = !!profile.squash_on_merge;
+
+  const stackSnapshot = path.join(options.scriptsDir, 'stack-snapshot.js');
+  const landThisPr = path.join(options.scriptsDir, 'land-this-pr.js');
+  const createPr = path.join(options.scriptsDir, 'create-pr.js');
+
+  const steps = [];
+
+  // Step 1: capture the current stack snapshot so land-this-pr can reason
+  // about the active PR + remaining branches.
+  steps.push({
+    args: [
+      'node',
+      stackSnapshot,
+      '--project-root',
+      options.projectRoot || '.',
+      '--base-branch',
+      baseBranch,
+      '--active-branch',
+      branch,
+      '--story-key',
+      state.story_key,
+      '--output',
+      options.snapshotPath,
+    ],
+    description: `snapshot stack for ${branch}`,
+  });
+
+  // Step 2: wait for CI / review depending on land_when.
+  if (landWhen === 'ci_pass' || landWhen === 'ci_and_review') {
+    const checkArgs = [
+      'node',
+      createPr,
+      '--mode',
+      'checks',
+      '--branch',
+      branch,
+      '--wait-minutes',
+      String(waitMinutes),
+    ];
+    if (landWhen === 'ci_and_review') {
+      checkArgs.push('--require-approved-review');
+    }
+    steps.push({
+      args: checkArgs,
+      description: `wait for ${landWhen === 'ci_and_review' ? 'CI green + approved review' : 'CI green'} (max ${waitMinutes}m)`,
+      retry: { attempts: 1, on: 'never' },
+    });
+  }
+
+  // Step 3: generate the merge plan via land-this-pr.js.
+  const landArgs = [
+    'node',
+    landThisPr,
+    '--snapshot',
+    options.snapshotPath,
+    '--base',
+    baseBranch,
+  ];
+  if (squash) landArgs.push('--squash');
+  steps.push({
+    args: landArgs,
+    description: `land PR for ${branch} onto ${baseBranch}${squash ? ' (squash)' : ''}`,
+  });
+
+  return { steps, branch, base: baseBranch, land_when: landWhen };
+}
+
+// planRebaseRecovery(state, profile, options) → { steps }
+//   Called when a land step hits `git merge --ff-only` failure. Attempts
+//   an auto-rebase of the story branch onto latest origin/<base>; on
+//   rebase conflict the CLI emits a user_prompt halt (caller's job).
+function planRebaseRecovery(state, profile, options) {
+  if (!options || !options.branch) throw new Error('planRebaseRecovery: branch required');
+  const baseBranch = profile.base_branch || 'main';
+  return {
+    steps: [
+      { args: ['git', 'fetch', 'origin'], description: 'fetch latest base' },
+      {
+        args: ['git', 'rebase', `origin/${baseBranch}`, options.branch],
+        description: `rebase ${options.branch} onto origin/${baseBranch}`,
+      },
+    ],
+    on_conflict: {
+      type: 'user_prompt',
+      reason: 'rebase_conflict',
+      prompt: `Rebase conflict on ${options.branch} against origin/${baseBranch}. Resolve manually then resume autopilot — it will retry the land step.`,
+    },
+  };
+}
+
+// Classify a stderr blob from `git rebase` / `git merge` as a conflict or
+// a transient/other failure. Used by the CLI to decide whether to halt
+// or to retry.
+function isRebaseConflict(stderrText) {
+  if (typeof stderrText !== 'string') return false;
+  const conflictMarkers = [
+    /^CONFLICT \(.*\):/m,
+    /\bAutomatic merge failed; fix conflicts/i,
+    /\bCould not apply/i,
+  ];
+  return conflictMarkers.some((re) => re.test(stderrText));
+}
+
+module.exports = {
+  planLand,
+  planRebaseRecovery,
+  isRebaseConflict,
+  escapeRe,
+};

package/_Sprintpilot/lib/orchestrator/parallel-batch.js

@@ -0,0 +1,99 @@
+// parallel-batch.js — plan a parallel batch of child Actions.
+//
+// The orchestrator emits a `parallel_batch` action when (and only when):
+//   - profile.parallel_stories === true
+//   - host_supports_parallel === true
+//   - There are independent stories ready (per the inferred DAG)
+//
+// This module is pure. It does NOT spawn subprocesses; it produces the
+// batch structure the CLI/host dispatcher consumes.
+//
+// Shape returned:
+//   {
+//     type: 'parallel_batch',
+//     concurrency: number,        // capped at profile.max_parallel_stories
+//     children: ChildAction[],    // each a regular Action (invoke_skill, run_script, ...)
+//     fallback: 'sequential',     // hosts without parallel support degrade to sequential
+//   }
+
+'use strict';
+
+function planBatch(childActions, profile, hostSupportsParallel) {
+  if (!Array.isArray(childActions)) {
+    throw new Error('planBatch: childActions must be an array');
+  }
+  if (childActions.length === 0) {
+    return { type: 'parallel_batch', concurrency: 0, children: [], fallback: 'sequential' };
+  }
+
+  const requested = childActions.length;
+  const cap = Math.max(1, Math.min(profile?.max_parallel_stories ?? 2, requested));
+  const allowed = !!(profile?.parallel_stories && hostSupportsParallel);
+
+  if (!allowed) {
+    // Degrade: emit the same children as a sequence (concurrency=1).
+    return {
+      type: 'parallel_batch',
+      concurrency: 1,
+      children: childActions,
+      fallback: 'sequential',
+      degraded: true,
+      degraded_reason: !profile?.parallel_stories
+        ? 'profile.parallel_stories=false'
+        : 'host_supports_parallel=false',
+    };
+  }
+
+  return {
+    type: 'parallel_batch',
+    concurrency: cap,
+    children: childActions,
+    fallback: 'sequential',
+  };
+}
+
+// classifyResults — given the per-child results, compute an aggregate
+// signal for the orchestrator to record at batch boundary.
+//   children: { id, status, output?, reason? }[]
+// Aggregate semantics:
+//   - all success    → 'success'
+//   - any block      → 'blocked' with kind unknown + user_input_needed=true
+//   - any failure    → 'failure' (recoverable=true iff every failure was recoverable)
+//   - else (mixed)   → 'failure' (recoverable=false) — surfaces to user
+function classifyResults(children) {
+  if (!Array.isArray(children) || children.length === 0) {
+    return { status: 'success', count: 0 };
+  }
+  const statuses = children.map((c) => c.status);
+  if (statuses.every((s) => s === 'success')) {
+    return { status: 'success', count: statuses.length };
+  }
+  if (statuses.some((s) => s === 'blocked')) {
+    return {
+      status: 'blocked',
+      blocker_kind: 'unknown',
+      user_input_needed: true,
+      details: 'parallel batch had a blocked child',
+      children_blocked: children.filter((c) => c.status === 'blocked').map((c) => c.id),
+    };
+  }
+  const failures = children.filter((c) => c.status === 'failure');
+  if (failures.length > 0) {
+    const allRecoverable = failures.every((c) => c.recoverable !== false);
+    return {
+      status: 'failure',
+      reason: `${failures.length}/${children.length} children failed`,
+      diagnosis: failures.map((c) => c.reason || 'unknown').join('; '),
+      recoverable: allRecoverable,
+    };
+  }
+  // Mixed (none of the above) — surface as non-recoverable for safety.
+  return {
+    status: 'failure',
+    reason: `unexpected mixed statuses: ${statuses.join(',')}`,
+    diagnosis: 'classifyResults could not aggregate',
+    recoverable: false,
+  };
+}
+
+module.exports = { planBatch, classifyResults };

package/_Sprintpilot/lib/orchestrator/profile-rules.js

@@ -0,0 +1,167 @@
+// profile-rules.js — typed Profile, flat→typed adapter, mid-sprint escalation.
+//
+// Pure module. No I/O. Consumes the flat tree produced by resolve-profile.js
+// and produces a typed Profile object the orchestrator can consume directly.
+//
+// Mid-sprint escalation honors AGENTS.md:
+//   "if quick-dev's tests fail or its Classify severity is `high`, the
+//    autopilot escalates the session (session-scoped only — never written
+//    back to config) to `full` flow"
+//
+// See plan: BMad sequence § Profile rules.
+
+'use strict';
+
+const VALID_PROFILE_NAMES = ['nano', 'small', 'medium', 'large', 'legacy'];
+const VALID_FLOWS = ['full', 'quick'];
+const VALID_RETRO_MODES = ['auto', 'stop', 'skip'];
+const VALID_GRANULARITIES = ['story', 'epic'];
+const VALID_MERGE_STRATEGIES = ['stacked', 'land_as_you_go'];
+const VALID_LAND_WHENS = ['no_wait', 'ci_pass', 'ci_and_review'];
+
+// Per-profile defaults for fields the orchestrator manages directly
+// (verify_reject_budget, retry_budget_per_action). These are orchestrator-
+// internal — not in the shipping YAML — so they're seeded here.
+const ORCHESTRATOR_DEFAULTS_BY_PROFILE = {
+  nano: { retry_budget_per_action: 1, verify_reject_budget: 2 },
+  small: { retry_budget_per_action: 2, verify_reject_budget: 3 },
+  medium: { retry_budget_per_action: 2, verify_reject_budget: 3 },
+  large: { retry_budget_per_action: 3, verify_reject_budget: 3 },
+  legacy: { retry_budget_per_action: 2, verify_reject_budget: 3 },
+};
+
+function get(obj, dottedKey) {
+  if (obj === null || obj === undefined) return undefined;
+  const parts = dottedKey.split('.');
+  let cur = obj;
+  for (const p of parts) {
+    if (cur === null || cur === undefined || typeof cur !== 'object') return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+function coerceBool(v, fallback) {
+  if (typeof v === 'boolean') return v;
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  return fallback;
+}
+
+function coerceInt(v, fallback) {
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  if (typeof v === 'string' && /^-?\d+$/.test(v)) return Number.parseInt(v, 10);
+  return fallback;
+}
+
+function coerceEnum(v, allowed, fallback) {
+  if (typeof v === 'string' && allowed.includes(v)) return v;
+  return fallback;
+}
+
+// Convert the flat resolved-config tree (from resolve-profile.js) into a
+// typed Profile. Missing keys fall back to documented defaults.
+function flatToProfile(resolved, profileName) {
+  const name = VALID_PROFILE_NAMES.includes(profileName) ? profileName : 'medium';
+  const orch = ORCHESTRATOR_DEFAULTS_BY_PROFILE[name];
+
+  return {
+    name,
+    implementation_flow: coerceEnum(
+      get(resolved, 'autopilot.implementation_flow'),
+      VALID_FLOWS,
+      'full',
+    ),
+    session_story_limit: coerceInt(get(resolved, 'autopilot.session_story_limit'), 3),
+    retrospective_mode: coerceEnum(
+      get(resolved, 'autopilot.retrospective_mode'),
+      VALID_RETRO_MODES,
+      'auto',
+    ),
+    coalesce_state_writes: coerceBool(get(resolved, 'autopilot.coalesce_state_writes'), false),
+    conditional_boot_work: coerceBool(get(resolved, 'autopilot.conditional_boot_work'), false),
+    granularity: coerceEnum(get(resolved, 'git.granularity'), VALID_GRANULARITIES, 'story'),
+    worktree_enabled: coerceBool(get(resolved, 'git.worktree.enabled'), true),
+    squash_on_merge: coerceBool(get(resolved, 'git.squash_on_merge'), false),
+    reuse_user_branch: coerceBool(get(resolved, 'git.reuse_user_branch'), false),
+    merge_strategy: coerceEnum(
+      get(resolved, 'git.merge_strategy'),
+      VALID_MERGE_STRATEGIES,
+      'stacked',
+    ),
+    land_when: coerceEnum(get(resolved, 'git.land_when'), VALID_LAND_WHENS, 'ci_pass'),
+    land_wait_minutes: coerceInt(get(resolved, 'git.land_wait_minutes'), 30),
+    base_branch:
+      typeof get(resolved, 'git.base_branch') === 'string'
+        ? get(resolved, 'git.base_branch')
+        : 'main',
+    branch_prefix:
+      typeof get(resolved, 'git.branch_prefix') === 'string'
+        ? get(resolved, 'git.branch_prefix')
+        : 'story/',
+    parallel_stories: coerceBool(get(resolved, 'ma.parallel_stories'), false),
+    max_parallel_stories: coerceInt(get(resolved, 'ma.max_parallel_stories'), 2),
+    fallback_on_tests_fail: coerceBool(
+      get(resolved, 'autopilot.nano.fallback_on_tests_fail'),
+      name === 'nano',
+    ),
+    fallback_on_quick_dev_high_severity: coerceBool(
+      get(resolved, 'autopilot.nano.fallback_on_quick_dev_high_severity'),
+      name === 'nano',
+    ),
+    fallback_target: coerceEnum(
+      get(resolved, 'autopilot.nano.fallback_target'),
+      ['small', 'medium', 'large'],
+      'small',
+    ),
+    retry_budget_per_action: orch.retry_budget_per_action,
+    verify_reject_budget: orch.verify_reject_budget,
+  };
+}
+
+// Session-scoped mid-sprint escalation. Called when a nano `bmad-quick-dev`
+// returns failure indicators. Returns a NEW Profile object — never mutates.
+// Returns the original profile unchanged when escalation conditions are not met
+// or the profile is not nano.
+function escalateOnFailure(profile, signalOutput) {
+  if (!profile || profile.name !== 'nano') return profile;
+  if (!signalOutput || typeof signalOutput !== 'object') return profile;
+
+  const testsFailed =
+    typeof signalOutput.tests_failed === 'number' && signalOutput.tests_failed > 0;
+  const highSeverity = signalOutput.severity === 'high';
+
+  const shouldEscalate =
+    (testsFailed && profile.fallback_on_tests_fail) ||
+    (highSeverity && profile.fallback_on_quick_dev_high_severity);
+
+  if (!shouldEscalate) return profile;
+
+  const targetName = profile.fallback_target || 'small';
+  const targetDefaults =
+    ORCHESTRATOR_DEFAULTS_BY_PROFILE[targetName] || ORCHESTRATOR_DEFAULTS_BY_PROFILE.small;
+
+  return {
+    ...profile,
+    name: targetName,
+    implementation_flow: 'full',
+    retry_budget_per_action: targetDefaults.retry_budget_per_action,
+    verify_reject_budget: targetDefaults.verify_reject_budget,
+    fallback_on_tests_fail: false,
+    fallback_on_quick_dev_high_severity: false,
+    escalated_from: 'nano',
+    escalation_reason: testsFailed ? 'tests_failed' : 'high_severity',
+  };
+}
+
+module.exports = {
+  VALID_PROFILE_NAMES,
+  VALID_FLOWS,
+  VALID_RETRO_MODES,
+  VALID_GRANULARITIES,
+  VALID_MERGE_STRATEGIES,
+  VALID_LAND_WHENS,
+  ORCHESTRATOR_DEFAULTS_BY_PROFILE,
+  flatToProfile,
+  escalateOnFailure,
+};

package/_Sprintpilot/lib/orchestrator/report.js

@@ -0,0 +1,95 @@
+// report.js — session report markdown generator.
+//
+// Pure. Consumes a state snapshot + the action ledger and produces a
+// human-readable markdown report. Used by `autopilot report` and as the
+// handoff message when `session_story_limit` is hit.
+
+'use strict';
+
+const { STATES } = require('./state-machine');
+
+function header(state) {
+  return [
+    '# Autopilot Session Report',
+    '',
+    `**Current story:** ${state.current_story || '(none)'}`,
+    `**Current phase:** ${state.current_bmad_step || '(none)'}`,
+    `**Sprint complete:** ${!!state.sprint_is_complete}`,
+    `**Last updated:** ${state.last_updated || '(unknown)'}`,
+  ].join('\n');
+}
+
+function ledgerSummary(entries) {
+  const counts = Object.create(null);
+  for (const e of entries) counts[e.kind] = (counts[e.kind] || 0) + 1;
+  const lines = ['', '## Ledger summary', ''];
+  for (const k of Object.keys(counts).sort()) {
+    lines.push(`- ${k}: ${counts[k]}`);
+  }
+  return lines.join('\n');
+}
+
+function recentActions(entries, limit = 10) {
+  const actionEntries = entries.filter((e) => e.kind === 'action_emitted').slice(-limit);
+  const lines = ['', `## Last ${actionEntries.length} actions`, ''];
+  for (const e of actionEntries) {
+    const a = e.action || {};
+    const summary =
+      a.type === 'invoke_skill'
+        ? `invoke_skill ${a.skill}`
+        : a.type === 'run_script'
+          ? `run_script ${a.command ? a.command[0] : '?'}`
+          : a.type === 'git_op'
+            ? `git_op ${a.op}`
+            : a.type;
+    lines.push(`- [${e.ts}] ${e.phase} → ${summary}`);
+  }
+  return lines.join('\n');
+}
+
+function recentDecisions(entries, limit = 5) {
+  const dec = entries.filter((e) => e.kind === 'decisions_appended').slice(-limit);
+  if (dec.length === 0) return '';
+  const lines = ['', `## Recent decisions (${dec.length})`, ''];
+  for (const e of dec) {
+    lines.push(`- [${e.ts}] story=${e.story} phase=${e.phase} ids=${(e.ids || []).join(',')}`);
+  }
+  return lines.join('\n');
+}
+
+function blockers(entries) {
+  const halts = entries.filter((e) => e.kind === 'halt').slice(-3);
+  if (halts.length === 0) return '';
+  const lines = ['', '## Recent halts', ''];
+  for (const e of halts) {
+    lines.push(`- [${e.ts}] phase=${e.phase} reason=${e.reason || '(none)'}`);
+  }
+  return lines.join('\n');
+}
+
+function nextActionHint(state, profile) {
+  const phase = state.current_bmad_step;
+  if (state.sprint_is_complete && phase !== STATES.SPRINT_FINALIZE_PENDING) {
+    return '\n## Next action\n\nSprint is complete. Next `autopilot start` will run finalize in a fresh context.';
+  }
+  if (phase === STATES.SPRINT_FINALIZE_PENDING) {
+    return '\n## Next action\n\nFinalize step pending. Run `/sprint-autopilot-on` in a fresh session to complete.';
+  }
+  return `\n## Next action\n\nRun \`autopilot next\` to emit the action for phase=${phase} on profile=${profile?.name ?? '?'}.`;
+}
+
+function render(state, entries, profile) {
+  const safeEntries = Array.isArray(entries) ? entries : [];
+  return [
+    header(state || {}),
+    ledgerSummary(safeEntries),
+    recentActions(safeEntries),
+    recentDecisions(safeEntries),
+    blockers(safeEntries),
+    nextActionHint(state || {}, profile || {}),
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+module.exports = { render, header, ledgerSummary, recentActions, recentDecisions, blockers, nextActionHint };