mandrel 1.57.0

package/.agents/scripts/lib/orchestration/plan-runner/plan-router.js

@@ -0,0 +1,86 @@
+/**
+ * plan-router — given an Epic's current labels, decide which plan-phase CLI
+ * should run next.
+ *
+ * Used by the local `/epic-plan` wrapper (chains spec → decompose).
+ *
+ * The router is intentionally stateless. Callers feed the current label set
+ * (a string array, usually from `provider.getEpic(id).labels`) and receive a
+ * `{ phase, script, command }` descriptor; no I/O is performed.
+ */
+
+import { AGENT_LABELS } from '../../label-constants.js';
+
+export const PLAN_PHASE_NAMES = Object.freeze({
+  SPEC: 'spec',
+  DECOMPOSE: 'decompose',
+});
+
+/**
+ * Canonical descriptor for each planning phase. `script` is the repo-relative
+ * path used by the local wrapper; `command` is the slash-command invocation
+ * operators fire.
+ *
+ * Spec and Decompose are served by the unified `/epic-plan` wrapper with a
+ * `--phase` flag — the phase workflows themselves live at
+ * `.agents/workflows/helpers/epic-plan-{spec,decompose}.md` and are not
+ * directly invokable slash commands.
+ *
+ * Exported as `PLAN_PHASE_DESCRIPTORS` to make the CLI-routing role explicit
+ * (it describes which wrapper script/slash-command serves each planning phase).
+ */
+export const PLAN_PHASE_DESCRIPTORS = Object.freeze({
+  [PLAN_PHASE_NAMES.SPEC]: {
+    phase: PLAN_PHASE_NAMES.SPEC,
+    script: '.agents/scripts/epic-plan-spec.js',
+    command: '/epic-plan --phase spec',
+    parkingLabel: AGENT_LABELS.REVIEW_SPEC,
+  },
+  [PLAN_PHASE_NAMES.DECOMPOSE]: {
+    phase: PLAN_PHASE_NAMES.DECOMPOSE,
+    script: '.agents/scripts/epic-plan-decompose.js',
+    command: '/epic-plan --phase decompose',
+    parkingLabel: AGENT_LABELS.READY,
+  },
+});
+
+/**
+ * Given the Epic's current labels, pick the next plan phase to run in the
+ * local `/epic-plan` wrapper.
+ *
+ * Precedence:
+ *   1. If the Epic already carries `agent::ready`, there is nothing left to
+ *      do — return `null` (the wrapper surfaces a no-op message).
+ *   2. If the Epic carries `agent::review-spec`, decomposition is the next
+ *      step (the operator has finished review).
+ *   3. Otherwise (fresh Epic), start with the spec phase.
+ *
+ * @param {string[]} labels Current labels on the Epic.
+ * @returns {object|null} Phase descriptor or null when no more work remains.
+ */
+export function nextPhaseForEpic(labels = []) {
+  const set = new Set(labels);
+  if (set.has(AGENT_LABELS.READY)) return null;
+  if (set.has(AGENT_LABELS.REVIEW_SPEC)) {
+    return PLAN_PHASE_DESCRIPTORS[PLAN_PHASE_NAMES.DECOMPOSE];
+  }
+  return PLAN_PHASE_DESCRIPTORS[PLAN_PHASE_NAMES.SPEC];
+}
+
+/**
+ * For a given current phase, return the next phase the local wrapper should
+ * advance to. Used to chain spec → decompose after operator confirmation.
+ *
+ * @param {string} currentPhase One of `PLAN_PHASE_NAMES`.
+ * @returns {object|null}
+ */
+export function advancePhase(currentPhase) {
+  switch (currentPhase) {
+    case PLAN_PHASE_NAMES.SPEC:
+      return PLAN_PHASE_DESCRIPTORS[PLAN_PHASE_NAMES.DECOMPOSE];
+    case PLAN_PHASE_NAMES.DECOMPOSE:
+      return null;
+    default:
+      return null;
+  }
+}

package/.agents/scripts/lib/orchestration/plan-runner/worktree-sweep.js

@@ -0,0 +1,212 @@
+/**
+ * plan-runner/worktree-sweep.js
+ *
+ * Reap-sweep used at the start of `/epic-plan-spec` and
+ * `/epic-plan-decompose` (via `drainPendingCleanupAtBoot` in
+ * `epic-plan-spec.js`, which see). Iterates the `.worktrees/story-<id>/`
+ * entries registered with git, looks up each parent Story, and force-removes
+ * any whose Story is already closed or labeled `agent::done`.
+ *
+ * The `--force` flag is intentional. By the time a Story is `agent::done`
+ * its branch has already been merged into the Epic branch (via
+ * `story-close.js`), so any residue left in the worktree — dirty
+ * build artifacts, an interrupted rebase, a stray Windows lock — is noise.
+ * The safety rails in `WorktreeManager.reap` exist for the _active_ close
+ * path; at plan time we already know the Story is done and want the
+ * directory gone no matter what.
+ *
+ * Public API:
+ *   - `sweepStaleStoryWorktrees({ provider, repoRoot, git?, logger?, fsRm?, worktreeRoot? })`
+ *
+ * Also drains any `.worktrees/.pending-cleanup.json` manifest left behind
+ * by Stage 1 (`removeWorktreeWithRecovery` → fs-rm-retry exhaustion, see
+ * `../worktree/lifecycle/pending-cleanup.js`). Entries whose Stage 1 retry now
+ * succeeds are removed from the manifest; entries reaching
+ * MAX_SWEEP_ATTEMPTS emit an `OPERATOR ACTION REQUIRED: persistent-lock`.
+ *
+ * Returns `{
+ *   reaped, skipped,
+ *   drainedPending, persistentPending, stillPending
+ * }`.
+ */
+
+import path from 'node:path';
+import * as defaultGit from '../../git-utils.js';
+import { NOOP_LOGGER } from '../../Logger.js';
+import { AGENT_LABELS } from '../../label-constants.js';
+import { concurrentMap } from '../../util/concurrent-map.js';
+import { parseWorktreePorcelain } from '../../worktree/inspector.js';
+import { forceDrainPendingCleanup } from '../../worktree/lifecycle/force-drain.js';
+
+const TICKET_READ_CONCURRENCY = 8;
+
+const DONE_LABEL = AGENT_LABELS.DONE;
+
+function isStoryDone(ticket) {
+  if (!ticket) return false;
+  if (ticket.state === 'closed') return true;
+  const labels = Array.isArray(ticket.labels) ? ticket.labels : [];
+  return labels.includes(DONE_LABEL);
+}
+
+function storyIdFromPath(wtPath) {
+  const parts = wtPath.replace(/\\/g, '/').split('/');
+  const last = parts[parts.length - 1] ?? '';
+  return defaultGit.parseStoryBranch(last);
+}
+
+/**
+ * Scan registered worktrees and force-remove any whose parent Story is
+ * done (closed or `agent::done`). Never touches worktrees whose Story is
+ * still open — those are live or in-flight.
+ *
+ * Provider reads are fanned out at concurrency 8 via `concurrentMap`; the
+ * subsequent `git worktree remove` calls stay sequential because they
+ * mutate `.git/worktrees/`.
+ *
+ * @param {object} opts
+ * @param {object} opts.provider    ITicketingProvider-compatible; only
+ *                                  `getTicket(id)` is required.
+ * @param {string} opts.repoRoot    Absolute path to the main checkout.
+ * @param {object} [opts.git]       `{ gitSpawn }` injection for tests.
+ * @param {object} [opts.logger]    `{ info, warn, error }`.
+ * @returns {Promise<{
+ *   reaped: Array<{ storyId: number, path: string }>,
+ *   skipped: Array<{ storyId: number|null, path: string, reason: string }>,
+ * }>}
+ */
+export async function sweepStaleStoryWorktrees(opts = {}) {
+  const ctx = opts.ctx;
+  const provider = opts.provider ?? ctx?.provider;
+  const repoRoot = opts.repoRoot ?? ctx?.cwd;
+  const git = opts.git ?? defaultGit;
+  const logger = opts.logger ?? ctx?.logger ?? NOOP_LOGGER;
+  const fsRm = opts.fsRm;
+  const worktreeRoot = opts.worktreeRoot;
+  if (!provider || typeof provider.getTicket !== 'function') {
+    throw new Error(
+      'sweepStaleStoryWorktrees: provider with getTicket(id) is required',
+    );
+  }
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    throw new Error('sweepStaleStoryWorktrees: repoRoot is required');
+  }
+
+  const resolvedWorktreeRoot =
+    worktreeRoot ?? path.join(repoRoot, '.worktrees');
+
+  // Stage 2 + Stage 3: drain pending-cleanup manifest before touching the
+  // live worktree list. Retrying the Stage 1 sequence here picks up entries
+  // whose Windows file locks have since released; entries still stuck get
+  // their handle-holders enumerated and terminated (Windows only) so the
+  // ledger self-heals across sprints instead of accumulating.
+  const drainResult = await forceDrainPendingCleanup({
+    repoRoot,
+    worktreeRoot: resolvedWorktreeRoot,
+    git,
+    fsRm,
+    logger,
+  });
+
+  const reaped = [];
+  const skipped = [];
+
+  const listRes = git.gitSpawn(repoRoot, 'worktree', 'list', '--porcelain');
+  if (listRes.status !== 0) {
+    logger.warn(
+      `worktree-sweep: git worktree list failed: ${listRes.stderr || listRes.stdout || 'unknown'}`,
+    );
+    return { reaped, skipped };
+  }
+
+  const entries = parseWorktreePorcelain(listRes.stdout || '');
+
+  // Phase 1 — fan out provider reads. Each mapper call captures its own
+  // error so a single transient provider hiccup doesn't trip
+  // concurrentMap's first-rejection-wins policy and abort the whole sweep;
+  // we want the original per-entry skip/continue semantics preserved.
+  const reads = await concurrentMap(
+    entries,
+    async (entry) => {
+      const wtPath = entry.path;
+      if (!wtPath) return { kind: 'no-path' };
+      const storyId = storyIdFromPath(wtPath);
+      if (storyId === null) return { kind: 'non-story' };
+      try {
+        const ticket = await provider.getTicket(storyId);
+        return { kind: 'ok', wtPath, storyId, ticket };
+      } catch (err) {
+        return { kind: 'provider-error', wtPath, storyId, error: err };
+      }
+    },
+    { concurrency: TICKET_READ_CONCURRENCY },
+  );
+
+  // Phase 2 — sequential `git worktree remove`. These mutate
+  // .git/worktrees/ and the per-worktree admin dir; serializing avoids
+  // racing git's own locking on Windows where a half-removed entry can
+  // leave a partial admin dir that the next remove then trips over.
+  for (const r of reads) {
+    if (r.kind === 'no-path' || r.kind === 'non-story') continue;
+    if (r.kind === 'provider-error') {
+      skipped.push({
+        storyId: r.storyId,
+        path: r.wtPath,
+        reason: `provider-error: ${r.error.message}`,
+      });
+      logger.warn(
+        `worktree-sweep: provider.getTicket(#${r.storyId}) failed: ${r.error.message}`,
+      );
+      continue;
+    }
+
+    if (!isStoryDone(r.ticket)) {
+      skipped.push({
+        storyId: r.storyId,
+        path: r.wtPath,
+        reason: 'story-open',
+      });
+      continue;
+    }
+
+    const res = git.gitSpawn(
+      repoRoot,
+      'worktree',
+      'remove',
+      '--force',
+      r.wtPath,
+    );
+    if (res.status !== 0) {
+      const reason = (
+        res.stderr ||
+        res.stdout ||
+        'worktree-remove-failed'
+      ).trim();
+      skipped.push({
+        storyId: r.storyId,
+        path: r.wtPath,
+        reason: `remove-failed: ${reason}`,
+      });
+      logger.warn(
+        `worktree-sweep: failed to reap storyId=${r.storyId} path=${r.wtPath}: ${reason}`,
+      );
+      continue;
+    }
+    reaped.push({ storyId: r.storyId, path: r.wtPath });
+    logger.info(
+      `worktree-sweep: reaped stale worktree storyId=${r.storyId} path=${r.wtPath}`,
+    );
+  }
+
+  // Drop any lingering worktree registrations. Cheap; safe to run whether
+  // or not we actually removed anything.
+  git.gitSpawn(repoRoot, 'worktree', 'prune');
+
+  return {
+    reaped,
+    skipped,
+    drainedPending: drainResult.drained,
+    persistentPending: drainResult.persistent,
+    stillPending: drainResult.stillPending,
+  };
+}

package/.agents/scripts/lib/orchestration/planning-context-budget.js

@@ -0,0 +1,213 @@
+/**
+ * planning-context-budget.js
+ *
+ * Bounded planning-context budget for the `--emit-context` planning scripts
+ * (Epic #817 Story 9). Provides a summary representation of large markdown
+ * payloads (project docs, PRD body, Tech Spec body) so the host LLM is not
+ * handed multi-100KB envelopes when the underlying material exceeds the
+ * configured `maxBytes` budget.
+ *
+ * Two pure helpers:
+ *   - `summarizeDoc(filePath, content, maxBytes)` extracts headings + bounded
+ *     excerpts for one document.
+ *   - `applyBudget(items, limits, opts)` decides full vs summary for a
+ *     collection of `{ path, content }` items based on `summaryMode` and the
+ *     total payload size.
+ *
+ * Both functions are deterministic and have no I/O.
+ */
+
+const HEADING_RE = /^(#{2,3})\s+(.+?)\s*$/;
+
+/**
+ * Default per-excerpt cap so a single section heading does not consume the
+ * entire per-doc byte budget. The bounded sum across excerpts is enforced
+ * separately by {@link summarizeDoc}.
+ */
+const DEFAULT_PER_EXCERPT_BYTES = 800;
+
+/**
+ * Default planning-context limits when callers do not pass through
+ * `getLimits(config).planningContext`. Mirrors `LIMITS_DEFAULTS` in
+ * `lib/config/limits.js` so this module is usable in standalone tests.
+ */
+export const PLANNING_CONTEXT_DEFAULTS = Object.freeze({
+  maxBytes: 50000,
+  summaryMode: 'auto',
+});
+
+function byteLen(s) {
+  if (s == null) return 0;
+  return Buffer.byteLength(String(s), 'utf-8');
+}
+
+function extractHeadings(content) {
+  if (!content) return [];
+  const lines = String(content).split(/\r?\n/);
+  const out = [];
+  for (const line of lines) {
+    const m = HEADING_RE.exec(line);
+    if (m) out.push({ level: m[1].length, text: m[2] });
+  }
+  return out;
+}
+
+/**
+ * Split a markdown body into preamble + per-heading sections so excerpts can
+ * be emitted with the heading they belong to. Lines preceding the first
+ * `## ` / `### ` heading become the `preamble` section (heading: null).
+ */
+function splitSections(content) {
+  if (!content) return [];
+  const lines = String(content).split(/\r?\n/);
+  const sections = [{ heading: null, body: [] }];
+  for (const line of lines) {
+    const m = HEADING_RE.exec(line);
+    if (m) {
+      sections.push({ heading: m[2], body: [] });
+    } else {
+      sections[sections.length - 1].body.push(line);
+    }
+  }
+  return sections;
+}
+
+/**
+ * Trim a multi-line section to the first non-empty paragraph, capped at
+ * `maxBytes` of utf-8. Preserves whitespace inside the kept paragraph but
+ * collapses leading/trailing blank lines so excerpts stay compact.
+ */
+function firstParagraph(lines, maxBytes) {
+  const text = lines.join('\n').replace(/^\s+|\s+$/g, '');
+  if (!text) return '';
+  // Take up to the first blank-line break (paragraph boundary).
+  const para = text.split(/\n\s*\n/)[0] ?? '';
+  const trimmed = para.trim();
+  if (byteLen(trimmed) <= maxBytes) return trimmed;
+  // Hard truncate at maxBytes utf-8 with an ellipsis marker so callers can
+  // tell the excerpt is bounded rather than corrupt.
+  const buf = Buffer.from(trimmed, 'utf-8').subarray(0, maxBytes);
+  // Avoid splitting a multi-byte codepoint at the boundary.
+  let safe = buf.toString('utf-8');
+  if (safe.length > 1 && safe.charCodeAt(safe.length - 1) === 0xfffd) {
+    safe = safe.slice(0, -1);
+  }
+  return `${safe.replace(/\s+$/, '')}…`;
+}
+
+/**
+ * Summarise a single markdown doc. Emits headings + per-section excerpts
+ * (preamble first), each bounded so a runaway section never blows the budget.
+ *
+ * @param {string} filePath repo-relative path used as the `path` field
+ * @param {string} content full markdown body
+ * @param {number} [maxBytes=50000] total per-doc byte budget for excerpts
+ * @returns {{ path: string, headings: string[], excerpts: Array<{heading: string|null, snippet: string}>, byteSize: number }}
+ */
+export function summarizeDoc(filePath, content, maxBytes = 50000) {
+  const safeContent = typeof content === 'string' ? content : '';
+  const byteSize = byteLen(safeContent);
+  const headingObjs = extractHeadings(safeContent);
+  const headings = headingObjs.map((h) => h.text);
+
+  const sections = splitSections(safeContent);
+  const perExcerptCap = Math.min(
+    DEFAULT_PER_EXCERPT_BYTES,
+    Math.max(120, Math.floor(maxBytes / Math.max(1, sections.length))),
+  );
+
+  const excerpts = [];
+  let used = 0;
+  for (const sec of sections) {
+    if (used >= maxBytes) break;
+    const remaining = Math.max(0, maxBytes - used);
+    const cap = Math.min(perExcerptCap, remaining);
+    const snippet = firstParagraph(sec.body, cap);
+    if (!snippet) continue;
+    excerpts.push({ heading: sec.heading, snippet });
+    used += byteLen(snippet);
+  }
+
+  return {
+    path: filePath,
+    headings,
+    excerpts,
+    byteSize,
+  };
+}
+
+function normalizeItems(items) {
+  if (!Array.isArray(items)) return [];
+  return items
+    .filter((it) => it && typeof it === 'object')
+    .map((it) => ({
+      path: it.path ?? it.name ?? '',
+      content: typeof it.content === 'string' ? it.content : '',
+    }));
+}
+
+function totalBytes(items) {
+  let n = 0;
+  for (const it of items) n += byteLen(it.content);
+  return n;
+}
+
+function buildFullItems(items) {
+  return items.map((it) => ({
+    path: it.path,
+    content: it.content,
+    byteSize: byteLen(it.content),
+  }));
+}
+
+function buildSummaryItems(items, maxBytes) {
+  // Distribute the byte budget across docs proportional to their size, with
+  // a per-doc floor so even tiny docs get a heading + tiny excerpt.
+  const total = totalBytes(items) || 1;
+  const floor = Math.max(512, Math.floor(maxBytes / Math.max(1, items.length)));
+  return items.map((it) => {
+    const share = Math.max(
+      floor,
+      Math.floor((byteLen(it.content) / total) * maxBytes),
+    );
+    return summarizeDoc(it.path, it.content, share);
+  });
+}
+
+/**
+ * Apply the planning-context budget to a collection of doc-shaped items.
+ *
+ * @param {Array<{path?: string, name?: string, content: string}>} items
+ * @param {{ maxBytes?: number, summaryMode?: 'auto'|'always'|'never' }} [limits]
+ * @param {{ fullContext?: boolean }} [opts] — `fullContext: true` forces full
+ *   mode regardless of `summaryMode` (mirrors the `--full-context` CLI flag).
+ * @returns {{ mode: 'full'|'summary', items: Array<object>, totalBytes: number }}
+ */
+export function applyBudget(items, limits = {}, opts = {}) {
+  const merged = { ...PLANNING_CONTEXT_DEFAULTS, ...(limits || {}) };
+  const { maxBytes, summaryMode } = merged;
+  const { fullContext = false } = opts;
+
+  const norm = normalizeItems(items);
+  const total = totalBytes(norm);
+
+  if (fullContext || summaryMode === 'never') {
+    return { mode: 'full', items: buildFullItems(norm), totalBytes: total };
+  }
+  if (summaryMode === 'always') {
+    return {
+      mode: 'summary',
+      items: buildSummaryItems(norm, maxBytes),
+      totalBytes: total,
+    };
+  }
+  // auto — summarise iff payload exceeds the budget.
+  if (total > maxBytes) {
+    return {
+      mode: 'summary',
+      items: buildSummaryItems(norm, maxBytes),
+      totalBytes: total,
+    };
+  }
+  return { mode: 'full', items: buildFullItems(norm), totalBytes: total };
+}

package/.agents/scripts/lib/orchestration/planning-risk.js

@@ -0,0 +1,155 @@
+/**
+ * planning-risk.js — derive the Epic planning-risk envelope from a
+ * planner-authored risk verdict.
+ *
+ * Pure ESM, no I/O. The planner (the `epic-plan-spec-author` Skill) judges
+ * the Epic it just specced and supplies a verdict of shape
+ * `{ axes: [{ axis, level, rationale }], summary }`, validated against
+ * `.agents/schemas/risk-verdict.schema.json` before it reaches this module.
+ * This module owns the deterministic control-flow outputs — overall level,
+ * review requirement, acceptance disposition, and gate decision — so the
+ * model supplies the *judgment input* while the harness owns the *gate
+ * decision* (Epic #3865 hard cutover from the retired keyword-regex
+ * classifier; see `docs/roadmap.md` Part 1).
+ */
+
+/** @typedef {'low' | 'medium' | 'high'} RiskLevel */
+/** @typedef {'required' | 'recommended' | 'not-applicable'} AcceptanceDisposition */
+/** @typedef {'review-required' | 'auto-proceed'} GateDecision */
+
+/**
+ * @typedef {Object} PlanningRiskAxis
+ * @property {string} axis
+ * @property {RiskLevel} level
+ * @property {string} rationale
+ */
+
+/**
+ * @typedef {Object} RiskVerdict
+ * @property {PlanningRiskAxis[]} axes
+ * @property {string} summary
+ */
+
+/**
+ * @typedef {Object} PlanningRiskEnvelope
+ * @property {PlanningRiskAxis[]} axes
+ * @property {RiskLevel} overallLevel
+ * @property {boolean} requiresReview
+ * @property {AcceptanceDisposition} acceptanceDisposition
+ * @property {GateDecision} gateDecision
+ */
+
+const LEVEL_RANK = Object.freeze({ low: 0, medium: 1, high: 2 });
+
+/**
+ * Axes whose presence forces a `required` acceptance disposition. Mirrored
+ * by the `axis` enum in `.agents/schemas/risk-verdict.schema.json` — keep
+ * the two lists in sync.
+ */
+export const REQUIRED_AXES = new Set([
+  'visible-behavior',
+  'public-api',
+  'security',
+  'data-migration',
+  'billing',
+  'destructive-mutation',
+  'critical-workflow',
+]);
+
+/**
+ * Axes that, when they are the only signals present, waive the acceptance
+ * spec (`not-applicable`). Mirrored by the `axis` enum in
+ * `.agents/schemas/risk-verdict.schema.json` — keep the two lists in sync.
+ */
+export const NOT_APPLICABLE_AXES = new Set([
+  'docs-only',
+  'test-harness',
+  'internal-refactor',
+]);
+
+/**
+ * @param {PlanningRiskAxis[]} axes
+ * @returns {RiskLevel}
+ */
+function resolveOverallLevel(axes) {
+  if (axes.length === 0) return 'low';
+  return axes.reduce(
+    (highest, entry) =>
+      LEVEL_RANK[entry.level] > LEVEL_RANK[highest] ? entry.level : highest,
+    'low',
+  );
+}
+
+/**
+ * @param {PlanningRiskAxis[]} axes
+ * @param {RiskLevel} overallLevel
+ * @returns {AcceptanceDisposition}
+ */
+function resolveAcceptanceDisposition(axes, overallLevel) {
+  const requiredAxes = axes.filter((entry) => REQUIRED_AXES.has(entry.axis));
+  if (requiredAxes.length > 0) {
+    return 'required';
+  }
+  if (
+    overallLevel === 'medium' ||
+    axes.some((entry) => entry.level === 'medium')
+  ) {
+    return 'recommended';
+  }
+  if (
+    axes.length > 0 &&
+    axes.every((entry) => NOT_APPLICABLE_AXES.has(entry.axis))
+  ) {
+    return 'not-applicable';
+  }
+  if (overallLevel === 'low') return 'not-applicable';
+  return 'recommended';
+}
+
+/**
+ * @param {RiskLevel} overallLevel
+ * @param {PlanningRiskAxis[]} axes
+ * @returns {boolean}
+ */
+function resolveRequiresReview(overallLevel, axes) {
+  if (overallLevel === 'high') return true;
+  if (overallLevel === 'medium') {
+    return axes.some(
+      (entry) =>
+        entry.level === 'medium' &&
+        (REQUIRED_AXES.has(entry.axis) || entry.axis === 'visible-behavior'),
+    );
+  }
+  return false;
+}
+
+/**
+ * Derive the stable planningRisk envelope from a schema-validated planner
+ * verdict. Pure derivation — schema validation happens at the read boundary
+ * (`epic-plan-spec.js`), never here, so a malformed verdict fails closed
+ * before this function runs.
+ *
+ * @param {RiskVerdict} [verdict]
+ * @returns {PlanningRiskEnvelope}
+ */
+export function deriveRiskEnvelope(verdict = {}) {
+  const axes = (Array.isArray(verdict.axes) ? verdict.axes : []).map(
+    ({ axis, level, rationale }) => ({ axis, level, rationale }),
+  );
+
+  const overallLevel = resolveOverallLevel(axes);
+  const acceptanceDisposition = resolveAcceptanceDisposition(
+    axes,
+    overallLevel,
+  );
+  const requiresReview = resolveRequiresReview(overallLevel, axes);
+  const gateDecision = requiresReview ? 'review-required' : 'auto-proceed';
+
+  return {
+    axes,
+    overallLevel,
+    requiresReview,
+    acceptanceDisposition,
+    gateDecision,
+  };
+}