mandrel 1.57.0

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/dag.js

@@ -0,0 +1,78 @@
+/**
+ * dag.js — Phase 2 of the epic-plan-decompose pipeline (Story #2466).
+ *
+ * Owns the deterministic DAG helpers used by the reconciler pipeline:
+ *   - `resolveDependencies(ticket, slugMap)`
+ *   - `orderTicketsForCreation(validated)` (topological sort within each
+ *     (parent_slug, type) group, concatenated in feature → story → task
+ *     order so parents always exist before their children get created)
+ *
+ * Extracted verbatim from `epic-plan-decompose.js` so the named exports
+ * (`resolveDependencies`, `orderTicketsForCreation`) that the
+ * `tests/ticket-decomposer.test.js` suite imports keep their contract.
+ *
+ * @module lib/orchestration/epic-plan-decompose/phases/dag
+ */
+
+export function resolveDependencies(ticket, slugMap) {
+  const resolved = [];
+  for (const dep of ticket.depends_on || []) {
+    const depId = slugMap.get(dep);
+    if (depId === undefined) {
+      // Unreachable through normal flow: validateAndNormalizeTickets
+      // already rejects unknown slugs and the topological sort guarantees
+      // creation order. A throw here turns a future regression (e.g.
+      // someone bypassing the validator) into a loud failure instead of a
+      // silently-dropped DAG edge.
+      throw new Error(
+        `[Decomposer] ${ticket.type.toUpperCase()} "${ticket.title}" (${ticket.slug}) depends on unresolved slug "${dep}". This indicates a planner bug or out-of-order ticket creation.`,
+      );
+    }
+    resolved.push(depId);
+  }
+  return resolved;
+}
+
+function topoSortGroup(group) {
+  const slugToTicket = new Map(group.map((t) => [t.slug, t]));
+  const visited = new Set();
+  const sorted = [];
+
+  function visit(t) {
+    if (visited.has(t.slug)) return;
+    visited.add(t.slug);
+    for (const dep of t.depends_on ?? []) {
+      const depTicket = slugToTicket.get(dep);
+      if (depTicket) visit(depTicket);
+    }
+    sorted.push(t);
+  }
+
+  for (const t of group) visit(t);
+  return sorted;
+}
+
+/**
+ * Topologically sort tickets within each (parent_slug, type) group, then
+ * concatenate groups in typeOrder so parents are always created before
+ * children (Feature → Story → Task) and intra-group dep chains resolve
+ * before their dependents are created.
+ */
+export function orderTicketsForCreation(validated) {
+  const typeOrder = { feature: 0, story: 1, task: 2 };
+  const groups = new Map();
+  for (const t of validated) {
+    const parentKey = t.parent_slug ?? '__epic__';
+    const key = `${t.type}::${parentKey}`;
+    if (!groups.has(key)) groups.set(key, { type: t.type, items: [] });
+    groups.get(key).items.push(t);
+  }
+  const ordered = [...groups.values()].sort(
+    (a, b) => typeOrder[a.type] - typeOrder[b.type],
+  );
+  const result = [];
+  for (const group of ordered) {
+    for (const t of topoSortGroup(group.items)) result.push(t);
+  }
+  return result;
+}

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/diagnostics.js

@@ -0,0 +1,72 @@
+/**
+ * diagnostics.js — partial-failure diagnostics for epic-plan-decompose
+ * (Story #2466).
+ *
+ * `reportPartialFailure({ epicId, provider, err })` is invoked from the
+ * CLI shell after `runDecomposePhase` throws — typically GitHub
+ * secondary-RL after dozens of issue creations. The function is
+ * intentionally defensive: never throws, never eclipses the original
+ * failure, and always emits the "to resume" hint as the final lines.
+ *
+ * @module lib/orchestration/epic-plan-decompose/phases/diagnostics
+ */
+
+import { Logger } from '../../../Logger.js';
+import { TYPE_LABELS } from '../../../label-constants.js';
+
+/**
+ * Count open child tickets under the Epic without distinguishing by
+ * type. Under the 3-tier hierarchy (Epic → Feature → Story), child
+ * tickets are always Feature or Story.
+ */
+async function emitOpenChildrenDiagnostic(provider, epicId) {
+  if (typeof provider.getSubTickets !== 'function') return;
+  // Story #3455 — scope to the Epic's sub-issue graph instead of
+  // `getTickets`'s repo-wide `state=all` scan. The diagnostic explicitly
+  // counts `state !== 'closed'`, so the scoped fetch (which still surfaces
+  // closed children) yields the same open-child count without paging
+  // every issue in the repo.
+  const existing = await provider.getSubTickets(epicId);
+  const childTypes = [TYPE_LABELS.FEATURE, TYPE_LABELS.STORY];
+  const created = (existing || []).filter(
+    (t) =>
+      (t.labels || []).some((l) => childTypes.includes(l)) &&
+      t.state !== 'closed',
+  ).length;
+  Logger.error(
+    `[epic-plan-decompose] Children currently open under Epic: ${created}`,
+  );
+}
+
+async function emitLifecycleLabelDiagnostic(provider, epicId) {
+  if (typeof provider.getEpic !== 'function') return;
+  const epic = await provider.getEpic(epicId);
+  const lifecycleLabel =
+    (epic?.labels || []).find((l) => l.startsWith('agent::')) ?? 'unknown';
+  Logger.error(
+    `[epic-plan-decompose] Epic #${epicId} current label: ${lifecycleLabel}`,
+  );
+}
+
+/**
+ * Best-effort recovery diagnostics. Never throws.
+ */
+export async function reportPartialFailure({ epicId, provider, err }) {
+  Logger.error('');
+  Logger.error('[epic-plan-decompose] ❌ Decompose phase aborted.');
+  Logger.error(`[epic-plan-decompose] Reason: ${err?.message ?? err}`);
+  try {
+    await emitLifecycleLabelDiagnostic(provider, epicId);
+    await emitOpenChildrenDiagnostic(provider, epicId);
+  } catch (probeErr) {
+    Logger.error(
+      `[epic-plan-decompose] (diagnostics probe failed: ${probeErr.message})`,
+    );
+  }
+  Logger.error('');
+  Logger.error('[epic-plan-decompose] To resume from the partial backlog:');
+  Logger.error(
+    `[epic-plan-decompose]   node .agents/scripts/epic-plan-decompose.js --epic ${epicId} --tickets <tickets-file> --resume`,
+  );
+  Logger.error('');
+}

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/persist-helpers.js

@@ -0,0 +1,155 @@
+/**
+ * persist-helpers.js — pure helpers split out of `persist.js` so the
+ * orchestrator stays under Story #2466's 200-LOC ceiling.
+ *
+ * Exports:
+ *   - `assertDecomposeInputs(epic, epicId, tickets)` — entry guards.
+ *   - `buildEpicSpecInput(epic, epicId)` — projection used by
+ *     `renderSpec`; runs `ensurePlanningArtifacts` defensively so the
+ *     spec body carries the `## Planning Artifacts` section the
+ *     cascade-close path depends on.
+ *   - `validateTickets(tickets, config)` — runs the cross-link / freshness
+ *     normaliser and the task-body validator in one pass.
+ *   - `seedPlanState(provider, epicId, epic)` — initialise + flip the
+ *     `epic-plan-state` checkpoint to the decomposing phase.
+ *   - `recordCheckpoint(provider, epicId, tickets)` — write the final
+ *     `decompose.completedAt` + `ticketCount` checkpoint after apply.
+ *   - `logCleanupSummary(cleanup, epicId, ticketCount)` — terminal log.
+ *
+ * @module lib/orchestration/epic-plan-decompose/phases/persist-helpers
+ */
+
+import { gitSpawn } from '../../../git-utils.js';
+import { Logger } from '../../../Logger.js';
+import { TYPE_LABELS } from '../../../label-constants.js';
+import {
+  initialize as initializePlanState,
+  read as readPlanState,
+  write as writePlanState,
+} from '../../epic-plan-state-store.js';
+import { validateTaskBodies } from '../../task-body-validator.js';
+import { validateAndNormalizeTickets } from '../../ticket-validator.js';
+import {
+  ensurePlanningArtifacts,
+  resolveConflictPolicy,
+} from './planning-artifacts.js';
+
+export function assertDecomposeInputs(epic, epicId, tickets) {
+  if (!epic) {
+    throw new Error(`[epic-plan-decompose] Epic #${epicId} not found.`);
+  }
+  if (!epic.labels?.includes(TYPE_LABELS.EPIC)) {
+    throw new Error(
+      `[epic-plan-decompose] Ticket #${epicId} is not a ${TYPE_LABELS.EPIC}.`,
+    );
+  }
+  if (!epic.linkedIssues?.prd || !epic.linkedIssues?.techSpec) {
+    throw new Error(
+      `[epic-plan-decompose] Epic #${epicId} is missing a linked PRD or Tech Spec. Run /epic-plan-spec first.`,
+    );
+  }
+  if (!Array.isArray(tickets)) {
+    throw new Error(
+      `[epic-plan-decompose] tickets must be an array (got ${typeof tickets}).`,
+    );
+  }
+}
+
+export function buildEpicSpecInput(epic, epicId) {
+  const epicBody = ensurePlanningArtifacts(epic.body ?? '', epic.linkedIssues);
+  const epicSpecInput = { id: epicId, title: epic.title };
+  if (epicBody.length > 0) epicSpecInput.body = epicBody;
+  return epicSpecInput;
+}
+
+/**
+ * Default fan-out counter — counts distinct files at `baseBranchRef` that
+ * reference the basename (without extension) of the deleted path. Uses
+ * `git grep -l` for a streaming-friendly probe; an empty grep returns
+ * exit code 1 which we map to a count of 0.
+ *
+ * Story #2962. Injected via opts in tests; this default runs in production.
+ */
+export function makeDefaultFanOutCounter({ baseBranchRef, cwd }) {
+  return ({ path }) => {
+    const lastSlash = path.lastIndexOf('/');
+    const base = lastSlash === -1 ? path : path.slice(lastSlash + 1);
+    const dotIdx = base.lastIndexOf('.');
+    const stem = dotIdx > 0 ? base.slice(0, dotIdx) : base;
+    if (stem.length < 3) return 0;
+    const result = gitSpawn(
+      cwd ?? process.cwd(),
+      'grep',
+      '-l',
+      '--fixed-strings',
+      stem,
+      baseBranchRef,
+    );
+    if (result.status !== 0) return 0;
+    const lines = result.stdout.split('\n').filter((l) => l.trim().length > 0);
+    // Exclude the deleted file itself from the call-site count.
+    return lines.filter((l) => !l.endsWith(`:${path}`)).length;
+  };
+}
+
+export function validateTickets(tickets, config, opts = {}) {
+  const baseBranchRef = config?.baseBranch ?? 'main';
+  const conflictPolicy = resolveConflictPolicy(config);
+  if (typeof opts.fanOutCounter === 'function') {
+    conflictPolicy.fanOutCounter = opts.fanOutCounter;
+  } else if (!conflictPolicy.fanOutCounter) {
+    conflictPolicy.fanOutCounter = makeDefaultFanOutCounter({
+      baseBranchRef,
+      cwd: opts.cwd,
+    });
+  }
+  const validated = validateAndNormalizeTickets(tickets, {
+    baseBranchRef,
+    conflictPolicy,
+  });
+  validateTaskBodies(validated);
+  return validated;
+}
+
+export async function seedPlanState(provider, epicId, epic) {
+  await initializePlanState({
+    provider,
+    epicId,
+    seed: {
+      spec: {
+        prdId: epic.linkedIssues.prd,
+        techSpecId: epic.linkedIssues.techSpec,
+        completedAt: null,
+      },
+    },
+  });
+}
+
+export async function recordCheckpoint(provider, epicId, tickets) {
+  const currentState =
+    (await readPlanState({ provider, epicId })) ??
+    (await initializePlanState({ provider, epicId }));
+  return writePlanState({
+    provider,
+    epicId,
+    state: {
+      ...currentState,
+      decompose: {
+        ...currentState.decompose,
+        ticketCount: tickets.length,
+        completedAt: new Date().toISOString(),
+      },
+    },
+  });
+}
+
+export function logCleanupSummary(cleanup, epicId, ticketCount) {
+  Logger.info(
+    `[epic-plan-decompose] ✅ Decompose phase complete for Epic #${epicId}. ${ticketCount} ticket(s) persisted via reconciler.`,
+  );
+  if (cleanup.deleted.length > 0) {
+    Logger.info(
+      `[epic-plan-decompose] 🧹 Cleaned up ${cleanup.deleted.length} temp file(s).`,
+    );
+  }
+}

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/persist.js

@@ -0,0 +1,321 @@
+/**
+ * persist.js — Phase 5 of the epic-plan-decompose pipeline (Story #2466).
+ *
+ * Owns the reconciler-based persist flow:
+ *   1. validate + normalise the ticket array
+ *   2. render the structural spec
+ *   3. write the YAML spec under `.agents/epics/<epicId>.yaml`
+ *   4. spawn `epic-reconcile.js --apply --yes`
+ *   5. run the sub-issue link safety net
+ *   6. update the `epic-plan-state` checkpoint
+ *   7. flip the Epic to `agent::ready`
+ *   8. clean up phase temp files
+ *
+ * Pure helpers (input guards, spec input projection, validation, state
+ * seed/checkpoint, cleanup logging) live in the sibling
+ * `persist-helpers.js` module so this orchestrator stays under Story
+ * #2466's 200-LOC ceiling.
+ *
+ * @module lib/orchestration/epic-plan-decompose/phases/persist
+ */
+
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+
+import { runPlanHealthcheck as defaultRunPlanHealthcheck } from '../../../../epic-plan-healthcheck.js';
+import { getLimits, PROJECT_ROOT } from '../../../config-resolver.js';
+import { Logger } from '../../../Logger.js';
+import {
+  AGENT_LABELS,
+  PLANNING_HEALTHCHECK_WAIVED,
+} from '../../../label-constants.js';
+import { cleanupPhaseTempFiles } from '../../../plan-phase-cleanup.js';
+import { writeSpec } from '../../../spec/index.js';
+import {
+  assertNoOpenPlanChildren,
+  releaseEpicPlanLease,
+} from '../../epic-plan-lease-guard.js';
+import { renderSpec } from '../../spec-renderer.js';
+import { renderHardConflictError } from '../../ticket-validator-conflicts.js';
+import {
+  reconcileSubIssueLinks,
+  setEpicLabel,
+  warnTicketCapNearLimit,
+} from './creation.js';
+import {
+  assertDecomposeInputs,
+  buildEpicSpecInput,
+  logCleanupSummary,
+  recordCheckpoint,
+  seedPlanState,
+  validateTickets,
+} from './persist-helpers.js';
+import { RECONCILE_CLI, spawnReconcilerApply } from './reconcile-spawn.js';
+
+/**
+ * Execute the decompose phase end to end. See module-doc for the 8-step
+ * flow.
+ *
+ * @param {number} epicId
+ * @param {import('../../../ITicketingProvider.js').ITicketingProvider} provider
+ * @param {{ tickets: Array<object> }} payload
+ * @param {object} config
+ * @param {{ force?: boolean, resume?: boolean, allowOverBudget?: boolean, allowLargeFanOut?: boolean, fanOutCounter?: (arg: { path: string }) => number, spawnSync?: typeof defaultSpawnSync, reconcileCli?: string, writeSpecFn?: typeof writeSpec, renderSpecFn?: typeof renderSpec, cwd?: string, runHealthcheckFn?: typeof defaultRunPlanHealthcheck, skipHealthcheck?: boolean }} [opts]
+ */
+export async function runDecomposePhase(
+  epicId,
+  provider,
+  { tickets },
+  config = {},
+  {
+    force = false,
+    resume = false,
+    allowOverBudget = false,
+    allowLargeFanOut = false,
+    fanOutCounter = undefined,
+    spawnSync = defaultSpawnSync,
+    reconcileCli = RECONCILE_CLI,
+    writeSpecFn = writeSpec,
+    renderSpecFn = renderSpec,
+    cwd = PROJECT_ROOT,
+    runHealthcheckFn = defaultRunPlanHealthcheck,
+    skipHealthcheck = false,
+  } = {},
+) {
+  if (force && resume) {
+    throw new Error(
+      '[epic-plan-decompose] --force and --resume are mutually exclusive.',
+    );
+  }
+  const epic = await provider.getEpic(epicId);
+  assertDecomposeInputs(epic, epicId, tickets);
+  const maxTickets = getLimits(config).maxTickets;
+  // Story #2798 — `maxTickets` is a reviewability budget. Over-budget
+  // persistence requires an explicit `--allow-over-budget` override so
+  // an accidental over-budget plan does not silently land.
+  if (tickets.length > maxTickets && !allowOverBudget) {
+    throw new Error(
+      `[epic-plan-decompose] Tickets (${tickets.length}) exceed the reviewability budget (${maxTickets}). ` +
+        `Re-scope the Epic into a smaller plan, or rerun with --allow-over-budget after confirming the over-budget rationale on the Epic.`,
+    );
+  }
+  warnTicketCapNearLimit(tickets, maxTickets);
+  if (tickets.length > maxTickets && allowOverBudget) {
+    Logger.warn(
+      `[epic-plan-decompose] Persisting an over-budget decomposition: ${tickets.length} tickets vs. budget ${maxTickets} (operator override --allow-over-budget).`,
+    );
+  }
+  // Story #2962 — run cross-validation BEFORE the plan-state mutation so
+  // the fan-out gate (and any future hard gate) can refuse persist
+  // without leaving a half-initialised epic-plan-state behind.
+  Logger.info(
+    `[epic-plan-decompose] Running cross-validation on ${tickets.length} tickets...`,
+  );
+  const validated = validateTickets(tickets, config, { fanOutCounter, cwd });
+
+  // Refuse to persist when any Task declares a deletion whose call-site
+  // fan-out exceeds the configured threshold, unless the operator has
+  // passed `--allow-large-fan-out`. The planner cannot reduce call sites
+  // by re-prompting, so this gate sits at persist time (like
+  // `--allow-over-budget`) rather than in the auto-redrive loop.
+  enforceFanOutGate(validated.findings, allowLargeFanOut);
+
+  // Story #3957 — surface soft cross-Story conflict findings on the
+  // validator's warning channel. `failOnSharedEditors` defaults to `false`,
+  // so a real shared-editor / implicit-dep hazard lands as `'soft'` and would
+  // otherwise be invisible during the Phase-8 operator review. Logging each
+  // soft finding here puts it in the same decompose output the operator reads
+  // before approving the plan.
+  surfaceSoftConflictFindings(validated.findings);
+
+  // Workflow-guards (Story #3481): refuse to persist when the Epic already has
+  // open Feature/Story children unless this is a deliberate re-decompose
+  // (`--force` closes + recreates the tree; `--resume` continues a partial
+  // persist). Sits immediately before the first plan-state mutation so a
+  // refusal never leaves a half-initialised epic-plan-state behind.
+  await assertNoOpenPlanChildren({
+    provider,
+    epicId,
+    force: force || resume,
+  });
+
+  await seedPlanState(provider, epicId, epic);
+
+  Logger.info(
+    `[epic-plan-decompose] Rendering spec for Epic #${epicId} (${validated.length} tickets)...`,
+  );
+  const spec = renderSpecFn(validated, {
+    epic: buildEpicSpecInput(epic, epicId),
+  });
+  const specFilePath = writeSpecFn(epicId, spec, { epicsDir: undefined });
+  Logger.info(`[epic-plan-decompose] Wrote spec → ${specFilePath}`);
+
+  Logger.info(
+    `[epic-plan-decompose] Spawning epic-reconcile.js --apply --yes for Epic #${epicId}...`,
+  );
+  // Story #3905 — a `--force` re-plan with a changed ticket set produces
+  // a plan carrying close ops for the dropped slugs. `epic-reconcile.js`
+  // hard-exits 2 on close ops unless `--explicit-delete` is passed, so a
+  // force re-decompose must thread the flag through or it fails *after*
+  // the spec was already overwritten and plan-state flipped.
+  const reconcile = spawnReconcilerApply({
+    spawnSync,
+    reconcileCli,
+    epicId,
+    cwd,
+    explicitDelete: force,
+  });
+
+  // Sub-issue link safety net — Story #2063. The reconciler's apply path
+  // opportunistically calls `addSubIssue` and swallows transient failures;
+  // re-establish missing native links before flipping the Epic to ready.
+  await reconcileSubIssueLinks(epicId, provider);
+
+  const checkpoint = await recordCheckpoint(provider, epicId, tickets);
+
+  // Story #2921 (Epic #2880 F7) — `agent::ready` handoff gate. The
+  // post-plan readiness healthcheck (`epic-plan-healthcheck.js`) is now
+  // blocking: a failing healthcheck refuses the `agent::ready` flip
+  // unless the operator has applied the `planning::healthcheck-waived`
+  // label. See `.agents/docs/SDLC.md` § "`agent::ready` exit conditions" for
+  // the full contract. Tests inject `skipHealthcheck: true` to bypass
+  // the network-bound check; production callers must not set this.
+  const healthcheck = skipHealthcheck
+    ? { ok: true, skipped: true }
+    : await runHealthcheckGate({
+        epicId,
+        epic,
+        runHealthcheckFn,
+      });
+
+  Logger.info(
+    `[epic-plan-decompose] Flipping Epic #${epicId} to ${AGENT_LABELS.READY}...`,
+  );
+  await setEpicLabel(provider, epicId, AGENT_LABELS.READY);
+
+  const cleanup = await cleanupPhaseTempFiles({ phase: 'decompose', epicId });
+  logCleanupSummary(cleanup, epicId, tickets.length);
+
+  // Workflow-guards (Story #3481): release the Epic-lease now that Phase 8 has
+  // persisted the plan. Best-effort — a release failure never fails decompose.
+  await releaseEpicPlanLease({ provider, epicId, config });
+
+  return {
+    epicId,
+    ticketCount: tickets.length,
+    checkpoint,
+    cleanup,
+    reconcile,
+    specPath: specFilePath,
+    healthcheck,
+  };
+}
+
+/**
+ * Run the post-plan readiness healthcheck and enforce the
+ * `agent::ready` handoff gate. Returns the healthcheck result on
+ * success (either `ok: true` or `ok: false` with the waiver label
+ * applied). Throws when the healthcheck failed and the operator has
+ * not applied `planning::healthcheck-waived` to the Epic.
+ *
+ * Extracted from `runDecomposePhase` so the gate is a single named
+ * code path the contract tests can target.
+ *
+ * @param {object} args
+ * @param {number} args.epicId
+ * @param {{ labels?: string[] }} args.epic
+ * @param {typeof defaultRunPlanHealthcheck} args.runHealthcheckFn
+ * @returns {Promise<{ ok: boolean, waived?: boolean, reason?: string|null }>}
+ */
+function enforceFanOutGate(findings, allowLargeFanOut) {
+  const fanOut = (findings ?? []).filter((f) => f.kind === 'fan-out-warning');
+  if (fanOut.length === 0) return;
+  if (allowLargeFanOut) {
+    for (const f of fanOut) {
+      Logger.warn(
+        `[epic-plan-decompose] Persisting a large-fan-out deletion: ` +
+          `Task "${f.taskSlug}" deletes "${f.path}" with ${f.callSiteCount} ` +
+          `call site(s) (threshold ${f.threshold}). Operator override --allow-large-fan-out.`,
+      );
+    }
+    return;
+  }
+  const lines = fanOut
+    .map(
+      (f) =>
+        `  - Task "${f.taskSlug}" (Story "${f.storySlug}") deletes "${f.path}" — ${f.callSiteCount} call site(s) (threshold ${f.threshold})`,
+    )
+    .join('\n');
+  throw new Error(
+    `[epic-plan-decompose] ${fanOut.length} Task(s) declare large-fan-out deletions:\n${lines}\n\n` +
+      `Split each deletion into a subsystem-by-subsystem migration across multiple Stories, ` +
+      `or rerun --allow-large-fan-out after confirming the deletion is intentional.`,
+  );
+}
+
+/**
+ * Story #3957 — log every `'soft'` cross-Story conflict finding on the
+ * validator's warning channel so it is visible during the Phase-8 operator
+ * review even when its policy flag (e.g. `failOnSharedEditors`) is `false`
+ * and the finding never reaches the AC-visible `errors[]` path.
+ *
+ * `fan-out-warning` findings are excluded: `enforceFanOutGate` already emits
+ * a dedicated warn/throw line for those, and double-logging would be noise.
+ * Hard findings are excluded too — they are already rendered into `errors[]`
+ * and block the decompose, so they need no advisory echo here.
+ *
+ * Each line reuses `renderHardConflictError` for the message body (the
+ * remediation hint is identical regardless of severity) under a `soft
+ * conflict:` prefix so the operator can tell advisory findings apart from
+ * blocking ones.
+ *
+ * @param {object[]} findings
+ */
+function surfaceSoftConflictFindings(findings) {
+  const soft = (findings ?? []).filter(
+    (f) => f?.severity === 'soft' && f?.kind !== 'fan-out-warning',
+  );
+  if (soft.length === 0) return;
+  Logger.warn(
+    `[epic-plan-decompose] ${soft.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
+  );
+  for (const finding of soft) {
+    Logger.warn(
+      `[epic-plan-decompose] soft conflict: ${renderHardConflictError(finding)}`,
+    );
+  }
+}
+
+async function runHealthcheckGate({ epicId, epic, runHealthcheckFn }) {
+  Logger.info(
+    `[epic-plan-decompose] Running post-plan readiness healthcheck for Epic #${epicId}...`,
+  );
+  let result;
+  try {
+    result = await runHealthcheckFn({ epicId });
+  } catch (err) {
+    // A throwing healthcheck is itself a failure — surface it as the
+    // gate reason rather than letting the throw propagate raw, so the
+    // operator sees a uniform "handoff refused" diagnostic.
+    result = { ok: false, reason: `healthcheck threw: ${err.message}` };
+  }
+
+  if (result?.ok) {
+    return { ok: true };
+  }
+
+  const labels = Array.isArray(epic?.labels) ? epic.labels : [];
+  const waived = labels.includes(PLANNING_HEALTHCHECK_WAIVED);
+  if (waived) {
+    Logger.warn(
+      `[epic-plan-decompose] Healthcheck failed for Epic #${epicId} but '${PLANNING_HEALTHCHECK_WAIVED}' is applied — proceeding with agent::ready handoff. Reason: ${result?.reason ?? '(no reason reported)'}`,
+    );
+    return { ok: false, waived: true, reason: result?.reason ?? null };
+  }
+
+  throw new Error(
+    `[epic-plan-decompose] Refusing agent::ready handoff for Epic #${epicId}: ` +
+      `post-plan healthcheck failed (${result?.reason ?? '(no reason reported)'}). ` +
+      `Resolve the failing check(s), or apply the '${PLANNING_HEALTHCHECK_WAIVED}' ` +
+      `label to the Epic to override and rerun the persist phase.`,
+  );
+}