mandrel 1.57.0

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/drain.js

@@ -0,0 +1,94 @@
+/**
+ * phases/drain.js — pending-cleanup drain / worktree-sweep boot phase.
+ *
+ * Runs `sweepStaleStoryWorktrees` when a ticketing `provider` is available
+ * (normal CLI boot): drains `.pending-cleanup.json` with Windows escalation,
+ * then reaps registered worktrees for done/closed stories. When `provider` is
+ * omitted (unit tests), runs `forceDrainPendingCleanup` on the manifest only.
+ */
+
+import path from 'node:path';
+import { PROJECT_ROOT } from '../../../config-resolver.js';
+import * as gitUtils from '../../../git-utils.js';
+import { forceDrainPendingCleanup } from '../../../worktree/lifecycle/force-drain.js';
+import { readManifest } from '../../../worktree/lifecycle/pending-cleanup.js';
+import { sweepStaleStoryWorktrees } from '../../plan-runner/worktree-sweep.js';
+
+/**
+ * Uses `delivery.worktreeIsolation.root` when present; defaults to
+ * `.worktrees`.
+ *
+ * Non-blocking: stuck entries stay in the manifest; plan execution continues.
+ *
+ * Exposed for integration tests.
+ *
+ * @param {{ repoRoot?: string, config?: object, provider?: object, git?: object, logger?: object, fsRm?: function }} [opts]
+ * @returns {Promise<object>} Canonical sweep/drain summary keyed on
+ *   `drainedPending` / `persistentPending` / `stillPending`.
+ */
+export async function drainPendingCleanupAtBoot(opts = {}) {
+  const repoRoot = opts.repoRoot ?? PROJECT_ROOT;
+  const config = opts.config;
+  const worktreeRoot = path.join(
+    repoRoot,
+    config?.delivery?.worktreeIsolation?.root ?? '.worktrees',
+  );
+  const git = opts.git ?? gitUtils;
+  const logger = opts.logger ?? console;
+  const fsRm = opts.fsRm;
+  const provider = opts.provider;
+
+  if (provider?.getTicket) {
+    const sweep = await sweepStaleStoryWorktrees({
+      provider,
+      repoRoot,
+      git,
+      logger,
+      worktreeRoot,
+      fsRm,
+    });
+    const remaining =
+      (sweep.persistentPending?.length ?? 0) +
+      (sweep.stillPending?.length ?? 0);
+    logger.info?.(
+      `[epic-plan-spec] worktree sweep: reaped=${sweep.reaped.length} drainedPending=${sweep.drainedPending?.length ?? 0} remaining=${remaining}`,
+    );
+    return sweep;
+  }
+
+  const before = readManifest(worktreeRoot).length;
+  if (before === 0) {
+    return {
+      reaped: [],
+      skipped: [],
+      drainedPending: [],
+      persistentPending: [],
+      stillPending: [],
+    };
+  }
+  const result = await forceDrainPendingCleanup({
+    repoRoot,
+    worktreeRoot,
+    git,
+    fsRm,
+    logger,
+  });
+  const remaining =
+    (result.persistent?.length ?? 0) + (result.stillPending?.length ?? 0);
+  logger.info?.(
+    `[epic-plan-spec] pending-cleanup drain: reaped=${result.drained?.length ?? 0} remaining=${remaining}`,
+  );
+  return {
+    reaped: [],
+    skipped: [],
+    drainedPending: result.drained,
+    persistentPending: result.persistent,
+    stillPending: result.stillPending,
+    escalated: result.escalated,
+    killedPids: result.killedPids,
+    noHolders: result.noHolders,
+    drainedDetails: result.drainedDetails,
+    persistentDetails: result.persistentDetails,
+    stillPendingDetails: result.stillPendingDetails,
+  };
+}

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

@@ -0,0 +1,414 @@
+/**
+ * phases/plan-epic.js — PRD / Tech Spec / Acceptance Spec persistence phase.
+ *
+ * Heals any prior planning artifacts (PRD / Tech Spec issues, "Planning
+ * Artifacts" body section, lifecycle labels) before writing the new issues.
+ * Idempotent against partial state: when the Epic already has a PRD but no
+ * Tech Spec, the existing PRD is reused. Pass `force: true` to re-plan: the
+ * canonical context tickets (PRD / Tech Spec / Acceptance Spec) are
+ * **overwritten in place** — same issue numbers, refreshed bodies, kept open,
+ * with a one-line regeneration audit comment on each. Only redundant
+ * duplicate artifacts are closed; Feature/Story child tickets retain
+ * close-and-recreate behaviour (handled by the decomposer, not here).
+ */
+
+import { Logger } from '../../../Logger.js';
+import { ACCEPTANCE_NA } from '../../../label-constants.js';
+import { PlanningStateManager } from '../../planning-state-manager.js';
+
+/**
+ * Resolve whether Phase 7 should persist an acceptance-spec ticket or apply
+ * the `acceptance::n-a` waiver, from the planningRisk envelope derived off
+ * the planner-authored risk verdict (`deriveRiskEnvelope`, Epic #3865).
+ *
+ * @param {import('../../planning-risk.js').PlanningRiskEnvelope|null} planningRisk
+ *   Derived envelope; `null` (direct invocations without a verdict) never
+ *   applies the waiver.
+ * @param {string|null} acceptanceSpecContent
+ * @returns {{ planningRisk: import('../../planning-risk.js').PlanningRiskEnvelope|null, wantsAcceptanceSpec: boolean, applyAcceptanceWaiver: boolean }}
+ */
+export function resolveAcceptancePersistence(
+  planningRisk,
+  acceptanceSpecContent,
+) {
+  const hasAcceptanceContent =
+    typeof acceptanceSpecContent === 'string' &&
+    acceptanceSpecContent.trim() !== '';
+
+  if (planningRisk?.acceptanceDisposition === 'not-applicable') {
+    return {
+      planningRisk,
+      wantsAcceptanceSpec: false,
+      applyAcceptanceWaiver: true,
+    };
+  }
+
+  return {
+    planningRisk: planningRisk ?? null,
+    wantsAcceptanceSpec: hasAcceptanceContent,
+    applyAcceptanceWaiver: false,
+  };
+}
+
+/**
+ * Overwrite an existing context ticket (PRD / Tech Spec / Acceptance Spec)
+ * in place: push the freshly-authored body and refresh the title prefix so a
+ * clarity-gate Epic rename does not strand a stale spec title, then post a
+ * single one-line regeneration audit comment so the preserved discussion
+ * history stays self-explanatory.
+ *
+ * The ticket keeps its issue number, its sub-issue link to the Epic, and all
+ * pre-existing comments — only the body, title, and a new audit comment are
+ * added.
+ *
+ * @param {import('../../../ITicketingProvider.js').ITicketingProvider} provider
+ * @param {number} ticketId           Existing context-ticket issue number.
+ * @param {{ title: string, body: string, artifact: string }} fields
+ *   `title` is the refreshed `[PRD] <epic title>`-style prefix; `body` is the
+ *   regenerated content; `artifact` is the human label used in the audit
+ *   comment (`PRD`, `Tech Spec`, `Acceptance Spec`).
+ * @returns {Promise<void>}
+ */
+export async function overwriteContextTicket(
+  provider,
+  ticketId,
+  { title, body, artifact },
+) {
+  await provider.updateTicket(ticketId, { title, body });
+  try {
+    await provider.postComment(ticketId, {
+      type: 'notification',
+      body: `♻️ **Regeneration Audit**: This ${artifact} body was regenerated in place by a \`/epic-plan --force\` re-plan. The issue number and prior discussion history are preserved.`,
+    });
+  } catch (_err) {
+    // Audit comment is best-effort — never fail the overwrite on a comment
+    // post error.
+  }
+}
+
+export function validatePlanEpicInputs({
+  prdContent,
+  techSpecContent,
+  acceptanceSpecContent,
+}) {
+  if (typeof prdContent !== 'string' || prdContent.trim() === '') {
+    throw new Error(
+      '[Epic Planner] prdContent is required and must be non-empty.',
+    );
+  }
+  if (typeof techSpecContent !== 'string' || techSpecContent.trim() === '') {
+    throw new Error(
+      '[Epic Planner] techSpecContent is required and must be non-empty.',
+    );
+  }
+  if (
+    acceptanceSpecContent !== null &&
+    (typeof acceptanceSpecContent !== 'string' ||
+      acceptanceSpecContent.trim() === '')
+  ) {
+    throw new Error(
+      '[Epic Planner] acceptanceSpecContent, when provided, must be a non-empty string.',
+    );
+  }
+}
+
+export function getExistingArtifactIds(epic) {
+  return {
+    prd: epic.linkedIssues?.prd ?? null,
+    techSpec: epic.linkedIssues?.techSpec ?? null,
+    acceptanceSpec: epic.linkedIssues?.acceptanceSpec ?? null,
+  };
+}
+
+export function hasAllRequestedArtifacts({ existing, wantsAcceptanceSpec }) {
+  return Boolean(
+    existing.prd &&
+      existing.techSpec &&
+      (wantsAcceptanceSpec ? existing.acceptanceSpec : true),
+  );
+}
+
+async function persistPrd({
+  provider,
+  epicId,
+  epic,
+  prdContent,
+  existingId,
+  force,
+}) {
+  if (existingId) {
+    if (force) {
+      Logger.info(
+        `[Epic Planner] --force: Overwriting PRD #${existingId} in place.`,
+      );
+      await overwriteContextTicket(provider, existingId, {
+        title: `[PRD] ${epic.title}`,
+        body: prdContent,
+        artifact: 'PRD',
+      });
+    } else {
+      Logger.info(
+        `[Epic Planner] Reusing existing PRD #${existingId}. Skipping PRD creation.`,
+      );
+    }
+    return existingId;
+  }
+
+  Logger.info(`[Epic Planner] Creating PRD issue for "${epic.title}"...`);
+  const prdTicket = await provider.createTicket(epicId, {
+    title: `[PRD] ${epic.title}`,
+    body: prdContent,
+    labels: ['context::prd'],
+    dependencies: [],
+  });
+  Logger.info(
+    `[Epic Planner] Created PRD Issue #${prdTicket.id} (${prdTicket.url})`,
+  );
+  return prdTicket.id;
+}
+
+async function persistTechSpec({
+  provider,
+  epicId,
+  epic,
+  techSpecContent,
+  prdId,
+  existingId,
+  force,
+}) {
+  if (existingId) {
+    if (force) {
+      Logger.info(
+        `[Epic Planner] --force: Overwriting Tech Spec #${existingId} in place.`,
+      );
+      await overwriteContextTicket(provider, existingId, {
+        title: `[Tech Spec] ${epic.title}`,
+        body: techSpecContent,
+        artifact: 'Tech Spec',
+      });
+    } else {
+      Logger.info(
+        `[Epic Planner] Reusing existing Tech Spec #${existingId}. Skipping Tech Spec creation.`,
+      );
+    }
+    return existingId;
+  }
+
+  Logger.info(
+    `[Epic Planner] Creating Tech Spec issue linking to PRD #${prdId}...`,
+  );
+  const techSpecTicket = await provider.createTicket(epicId, {
+    title: `[Tech Spec] ${epic.title}`,
+    body: techSpecContent,
+    labels: ['context::tech-spec'],
+    dependencies: [prdId],
+  });
+  Logger.info(
+    `[Epic Planner] Created Tech Spec Issue #${techSpecTicket.id} (${techSpecTicket.url})`,
+  );
+  return techSpecTicket.id;
+}
+
+async function persistAcceptanceSpec({
+  provider,
+  epicId,
+  epic,
+  acceptanceSpecContent,
+  techSpecId,
+  existingId,
+  force,
+}) {
+  if (existingId) {
+    if (force) {
+      Logger.info(
+        `[Epic Planner] --force: Overwriting Acceptance Spec #${existingId} in place.`,
+      );
+      await overwriteContextTicket(provider, existingId, {
+        title: `[Acceptance Spec] ${epic.title}`,
+        body: acceptanceSpecContent,
+        artifact: 'Acceptance Spec',
+      });
+    } else {
+      Logger.info(
+        `[Epic Planner] Reusing existing Acceptance Spec #${existingId}. Skipping Acceptance Spec creation.`,
+      );
+    }
+    return existingId;
+  }
+
+  Logger.info(
+    `[Epic Planner] Creating Acceptance Spec issue linking to Tech Spec #${techSpecId}...`,
+  );
+  const acceptanceTicket = await provider.createTicket(epicId, {
+    title: `[Acceptance Spec] ${epic.title}`,
+    body: acceptanceSpecContent,
+    labels: ['context::acceptance-spec'],
+    dependencies: [techSpecId],
+  });
+  Logger.info(
+    `[Epic Planner] Created Acceptance Spec Issue #${acceptanceTicket.id} (${acceptanceTicket.url})`,
+  );
+  return acceptanceTicket.id;
+}
+
+async function closeWaivedAcceptanceSpec({
+  provider,
+  epicId,
+  epic,
+  existingAcceptanceSpecId,
+}) {
+  Logger.info(
+    `[Epic Planner] Acceptance disposition now waived — closing existing Acceptance Spec #${existingAcceptanceSpecId}.`,
+  );
+  try {
+    await provider.updateTicket(existingAcceptanceSpecId, {
+      state: 'closed',
+      state_reason: 'not_planned',
+    });
+  } catch (err) {
+    if (!err.message.includes('404') && !err.message.includes('410')) {
+      throw err;
+    }
+  }
+  try {
+    await provider.removeSubIssue(epicId, existingAcceptanceSpecId);
+  } catch (_err) {
+    // Already detached or unsupported — safe to ignore.
+  }
+  if (epic.linkedIssues) epic.linkedIssues.acceptanceSpec = null;
+}
+
+/**
+ * Persist the host-authored PRD and Tech Spec under the Epic.
+ */
+export async function planEpic(
+  epicId,
+  provider,
+  { prdContent, techSpecContent, acceptanceSpecContent = null },
+  _settings = {},
+  { force = false, planningRisk = null } = {},
+) {
+  validatePlanEpicInputs({
+    prdContent,
+    techSpecContent,
+    acceptanceSpecContent,
+  });
+
+  Logger.info(`[Epic Planner] Fetching Epic #${epicId}...`);
+  const epic = await provider.getEpic(epicId);
+
+  if (!epic) {
+    throw new Error(`Epic #${epicId} not found.`);
+  }
+
+  const stateManager = new PlanningStateManager(provider);
+  await stateManager.healAndCleanupArtifacts(epic, force);
+
+  const { wantsAcceptanceSpec, applyAcceptanceWaiver } =
+    resolveAcceptancePersistence(planningRisk, acceptanceSpecContent);
+
+  Logger.info(
+    `[Epic Planner] Acceptance disposition: ${planningRisk?.acceptanceDisposition ?? 'unspecified'}` +
+      (applyAcceptanceWaiver
+        ? ` — applying ${ACCEPTANCE_NA} waiver (no acceptance-spec ticket).`
+        : wantsAcceptanceSpec
+          ? ' — persisting context::acceptance-spec.'
+          : ' — no acceptance-spec content supplied.'),
+  );
+
+  const existing = getExistingArtifactIds(epic);
+  if (!force && hasAllRequestedArtifacts({ existing, wantsAcceptanceSpec })) {
+    Logger.warn(
+      `[Epic Planner] Epic #${epicId} already has all requested planning artifacts. Aborting to prevent duplicates. Use --force to re-plan.`,
+    );
+    return;
+  }
+  // Under --force we now OVERWRITE the canonical context tickets in place
+  // (same issue numbers, refreshed bodies) rather than closing + recreating
+  // them. `healAndCleanupArtifacts(epic, force=true)` preserved the canonical
+  // IDs on `epic.linkedIssues`, so reuse them in both the force and non-force
+  // paths. The difference: under force we push the freshly-authored body via
+  // `provider.updateTicket`, whereas the non-force partial-state reuse keeps
+  // the existing body untouched.
+  const prdId = await persistPrd({
+    provider,
+    epicId,
+    epic,
+    prdContent,
+    existingId: existing.prd,
+    force,
+  });
+  const techSpecId = await persistTechSpec({
+    provider,
+    epicId,
+    epic,
+    techSpecContent,
+    prdId,
+    existingId: existing.techSpec,
+    force,
+  });
+
+  let acceptanceSpecId = null;
+  if (wantsAcceptanceSpec) {
+    acceptanceSpecId = await persistAcceptanceSpec({
+      provider,
+      epicId,
+      epic,
+      acceptanceSpecContent,
+      techSpecId,
+      existingId: existing.acceptanceSpec,
+      force,
+    });
+  } else if (applyAcceptanceWaiver && existing.acceptanceSpec) {
+    // Acceptance-spec transition: was present, now waived (acceptance::n-a).
+    // This is a genuine close — there is no longer an acceptance spec to
+    // overwrite — and the stale ticket must be detached so the Epic body's
+    // Planning Artifacts section stops referencing it.
+    await closeWaivedAcceptanceSpec({
+      provider,
+      epicId,
+      epic,
+      existingAcceptanceSpecId: existing.acceptanceSpec,
+    });
+  }
+
+  Logger.info(
+    `[Epic Planner] Updating Epic #${epicId} with linked documents...`,
+  );
+
+  // Format exactly so the issue-link-parser regexes still catch each line.
+  // The parser is the source of truth for which prefixes are accepted; we
+  // emit the canonical "PRD: #N" / "Tech Spec: #N" / "Acceptance Spec: #N"
+  // shape so the epic-deliver finalize/cascade-close call shape and the
+  // Phase 2 decomposer-context picker both see the third link.
+  const artifactLines = [
+    `- [ ] PRD: #${prdId}`,
+    `- [ ] Tech Spec: #${techSpecId}`,
+  ];
+  if (acceptanceSpecId !== null) {
+    artifactLines.push(`- [ ] Acceptance Spec: #${acceptanceSpecId}`);
+  }
+  const appendBody = `\n\n## Planning Artifacts\n${artifactLines.join('\n')}\n`;
+  const newBody = epic.body + appendBody;
+
+  /** @type {{ add?: string[], remove?: string[] }} */
+  const labelMutations = {};
+  if (applyAcceptanceWaiver) {
+    labelMutations.add = [ACCEPTANCE_NA];
+  } else if (
+    wantsAcceptanceSpec &&
+    (epic.labels ?? []).includes(ACCEPTANCE_NA)
+  ) {
+    labelMutations.remove = [ACCEPTANCE_NA];
+  }
+
+  await provider.updateTicket(epicId, {
+    body: newBody,
+    ...(labelMutations.add || labelMutations.remove
+      ? { labels: labelMutations }
+      : {}),
+  });
+
+  Logger.info(`[Epic Planner] Epic #${epicId} updated successfully.`);
+  Logger.info(`[Epic Planner] Planning pipeline complete!`);
+}

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/prompts.js

@@ -0,0 +1,55 @@
+/**
+ * phases/prompts.js — Canonical PRD / Tech Spec / Acceptance Spec system
+ * prompts for the spec phase of `/epic-plan`.
+ *
+ * These ride along on the `--emit-context` envelope as a backstop. The
+ * `epic-plan-spec-author` Skill
+ * (`.agents/skills/core/epic-plan-spec-author/SKILL.md`) embeds the
+ * authoritative copies of these strings — keep the two surfaces in sync when
+ * either is edited.
+ */
+
+export const PRD_SYSTEM_PROMPT = `You are an expert Technical Product Manager.
+Your job is to convert a high-level Epic description into a structured Product Requirements Document (PRD).
+
+The PRD should outline:
+1. Context & Goals
+2. User Stories
+3. Acceptance Criteria
+4. Out of Scope
+
+CRITICAL REQUIREMENTS:
+- Respond ONLY with valid Markdown.
+- Do not use top-level <h1> (# ) tags. Start with ## Overview.
+- Format requirements clearly with bullet points and bold text where appropriate.`;
+
+export const TECH_SPEC_SYSTEM_PROMPT = `You are an expert Engineering Architect.
+Your job is to convert a PRD into a Technical Specification for implementation.
+
+The Tech Spec should outline:
+1. Architecture & Design
+2. Data Models (if any)
+3. API Changes (if any)
+4. Core Components
+5. Security & Privacy Considerations
+
+CRITICAL REQUIREMENTS:
+- Respond ONLY with valid Markdown.
+- Do not use top-level <h1> (# ) tags. Start with ## Technical Overview.
+- Format architectural decisions clearly with bullet points.`;
+
+export const ACCEPTANCE_SPEC_SYSTEM_PROMPT = `You are an expert Acceptance Engineer.
+Your job is to convert a PRD and a Tech Spec into a structured Acceptance Specification that drives features-first BDD authoring.
+
+The Acceptance Spec should outline:
+1. Acceptance Criteria — one row per user-visible outcome, expressed as a Markdown table with columns: AC ID | Outcome | Feature File | Scenario | Disposition
+2. Stable AC IDs — assign AC-1, AC-2, ... in document order; reuse the same ID across re-plans when an Outcome is materially unchanged so scenario tags (@ac-N) stay aligned
+3. Disposition — tag each row with one of: new | updated | unchanged
+
+CRITICAL REQUIREMENTS:
+- Respond ONLY with valid Markdown.
+- Do not use top-level <h1> (# ) tags. Start with ## Acceptance Criteria.
+- Every AC row MUST have a stable AC ID of the form AC-<n> (AC-1, AC-2, ...) — do not reorder IDs across re-plans; new ACs get fresh sequential IDs.
+- Every AC row MUST carry a Disposition value from the enum: new | updated | unchanged.
+- Each Outcome MUST be a single user-visible behaviour — no DB assertions, no HTTP status codes, no internal implementation details.
+- Cite proposed feature file paths under tests/features/** so Phase 8 can scaffold matching scenarios.`;

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/risk-verdict.js

@@ -0,0 +1,105 @@
+/**
+ * phases/risk-verdict.js — read + schema-validate the planner-authored
+ * risk verdict (Epic #3865).
+ *
+ * The `epic-plan-spec-author` Skill writes `risk-verdict.json` as the
+ * fourth planning artifact; the persist half of `epic-plan-spec.js` loads
+ * it through this module before deriving the planningRisk envelope. A
+ * missing, unparseable, or schema-invalid verdict throws — the spec phase
+ * fails closed rather than mis-routing the review gate.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const RISK_VERDICT_SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'risk-verdict.schema.json',
+);
+
+/** @type {Map<string, import('ajv').ValidateFunction>} */
+const validatorCache = new Map();
+
+/**
+ * Compile (and cache) the Ajv2020 validator for the risk-verdict schema.
+ *
+ * @param {string} schemaPath
+ * @param {{ readFileSync: typeof readFileSync }} io
+ * @returns {import('ajv').ValidateFunction}
+ */
+function getRiskVerdictValidator(schemaPath, io) {
+  const cached = validatorCache.get(schemaPath);
+  if (cached) return cached;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const schema = JSON.parse(io.readFileSync(schemaPath, 'utf8'));
+  const validate = ajv.compile(schema);
+  validatorCache.set(schemaPath, validate);
+  return validate;
+}
+
+/**
+ * Validate a parsed risk verdict against the schema. Throws with the full
+ * Ajv error detail on any violation so the spec phase never routes the
+ * review gate off a malformed verdict.
+ *
+ * @param {unknown} verdict
+ * @param {{ schemaPath?: string, io?: { readFileSync: typeof readFileSync } }} [opts]
+ * @returns {import('../../planning-risk.js').RiskVerdict} The validated verdict (same reference).
+ */
+export function validateRiskVerdict(verdict, opts = {}) {
+  const validate = getRiskVerdictValidator(
+    opts.schemaPath ?? RISK_VERDICT_SCHEMA_PATH,
+    opts.io ?? { readFileSync },
+  );
+  if (!validate(verdict)) {
+    const detail = (validate.errors ?? [])
+      .map((e) => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(
+      `[epic-plan-spec] risk verdict failed schema validation: ${detail}`,
+    );
+  }
+  return /** @type {import('../../planning-risk.js').RiskVerdict} */ (verdict);
+}
+
+/**
+ * Read, parse, and schema-validate the risk-verdict file the
+ * `epic-plan-spec-author` Skill wrote.
+ *
+ * @param {string} verdictPath
+ * @param {{ schemaPath?: string, io?: { readFileSync: typeof readFileSync } }} [opts]
+ * @returns {import('../../planning-risk.js').RiskVerdict}
+ */
+export function loadRiskVerdict(verdictPath, opts = {}) {
+  const io = opts.io ?? { readFileSync };
+  let raw;
+  try {
+    raw = io.readFileSync(verdictPath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `[epic-plan-spec] cannot read risk verdict at ${verdictPath}: ${err.message}`,
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `[epic-plan-spec] risk verdict at ${verdictPath} is not valid JSON: ${err.message}`,
+    );
+  }
+  return validateRiskVerdict(parsed, opts);
+}