mandrel 1.57.0

package/.agents/scripts/lib/orchestration/model-attribution.js

@@ -0,0 +1,390 @@
+/**
+ * model-attribution.js — per-ticket model attribution comments + rollup
+ * (Story #2813).
+ *
+ * Records which Claude model executed a given ticket as a structured comment
+ * on that ticket. Epic-level mixes are computed at query time by walking the
+ * child tickets' comments — no Epic-scope emission is written.
+ *
+ * Surface:
+ *
+ *   - {@link resolveModelIdentity} — pure resolver that picks an identity
+ *     from the fallback chain (SDK metadata → env var → 'unknown'
+ *     sentinel) and tags the source. Pure: no IO, no Date.now().
+ *   - {@link buildModelAttributionPayload} — shape the canonical payload
+ *     from a resolved identity + ticketId + timestamp.
+ *   - {@link validateModelAttributionPayload} — hand-rolled validator
+ *     matching `.agents/schemas/model-attribution.schema.json`. Returns
+ *     `{ ok: true }` or `{ ok: false, errors: string[] }`.
+ *   - {@link renderModelAttributionBody} — markdown body + fenced JSON
+ *     block (same fence convention as the other structured comments in
+ *     this repo so the shared `parseFencedJsonComment` can read it back).
+ *   - {@link emitModelAttribution} — idempotent upsert against a Task
+ *     ticket. Throws on validator failure (no comment written).
+ *   - {@link parseModelAttributionComment} — readback helper for the
+ *     rollup walker; returns `null` on missing/malformed payloads.
+ *   - {@link rollupModelAttribution} — given a Story or Epic ticket id,
+ *     walks `getSubTickets`, collects attribution comments, returns
+ *     `{ totalChildren, byModel: {...}, missing: N }`.
+ */
+
+import { parseFencedJsonComment } from './structured-comment-parser.js';
+import { findStructuredComment, upsertStructuredComment } from './ticketing.js';
+
+export const MODEL_ATTRIBUTION_TYPE = 'model-attribution';
+
+/**
+ * Sentinel returned by {@link resolveModelIdentity} when neither the SDK
+ * metadata nor the runtime env var supplied a model id. Exported so tests
+ * and downstream consumers can compare without re-spelling the literal.
+ */
+export const UNKNOWN_MODEL_ID = 'unknown';
+
+/**
+ * Env vars consulted as the second-priority resolver source. Listed in
+ * priority order — the first one set wins.
+ */
+const ENV_VAR_CANDIDATES = Object.freeze(['CLAUDE_MODEL', 'ANTHROPIC_MODEL']);
+
+/**
+ * Derive the coarse family label from a canonical model id. Used for the
+ * rollup-friendly `family` field. Returns `null` when the id does not
+ * match a recognised family pattern (the rollup helper falls back to the
+ * full id in that case so unknown models still aggregate distinctly).
+ *
+ * Recognises Anthropic Claude families: Opus, Sonnet, Haiku.
+ *
+ * @param {string} id
+ * @returns {string | null}
+ */
+export function deriveFamily(id) {
+  if (typeof id !== 'string') return null;
+  const lower = id.toLowerCase();
+  if (lower.includes('opus')) return 'Opus';
+  if (lower.includes('sonnet')) return 'Sonnet';
+  if (lower.includes('haiku')) return 'Haiku';
+  return null;
+}
+
+/**
+ * Resolve the active model identity using the documented fallback chain:
+ *
+ *   1. `sdkMetadata.modelId` (or `.model`) when present and non-empty.
+ *   2. `CLAUDE_MODEL` / `ANTHROPIC_MODEL` env vars (first non-empty wins).
+ *   3. The `UNKNOWN_MODEL_ID` sentinel.
+ *
+ * Pure: accepts the env bag as an injectable argument so tests can pin
+ * the resolver without mutating `process.env`. Production callers default
+ * to `process.env`.
+ *
+ * @param {object} [opts]
+ * @param {object|null} [opts.sdkMetadata] — SDK response metadata.
+ * @param {Record<string, string|undefined>} [opts.env=process.env]
+ * @returns {{ id: string, family: string|null, source: 'sdk-metadata'|'env'|'unknown', sdkMetadata?: object }}
+ */
+export function resolveModelIdentity(opts = {}) {
+  const { sdkMetadata = null, env = process.env } = opts;
+
+  const sdkId =
+    sdkMetadata && typeof sdkMetadata === 'object'
+      ? (typeof sdkMetadata.modelId === 'string' && sdkMetadata.modelId) ||
+        (typeof sdkMetadata.model === 'string' && sdkMetadata.model) ||
+        null
+      : null;
+  if (sdkId) {
+    return {
+      id: sdkId,
+      family: deriveFamily(sdkId),
+      source: 'sdk-metadata',
+      sdkMetadata,
+    };
+  }
+
+  for (const name of ENV_VAR_CANDIDATES) {
+    const value = env?.[name];
+    if (typeof value === 'string' && value.length > 0) {
+      return {
+        id: value,
+        family: deriveFamily(value),
+        source: 'env',
+      };
+    }
+  }
+
+  return {
+    id: UNKNOWN_MODEL_ID,
+    family: null,
+    source: 'unknown',
+  };
+}
+
+/**
+ * Build the canonical payload object from a resolved identity. Separated
+ * from {@link emitModelAttribution} so callers (and tests) can shape the
+ * payload without triggering the upsert side-effect.
+ *
+ * @param {{
+ *   ticketId: number,
+ *   identity: ReturnType<typeof resolveModelIdentity>,
+ *   recordedAt?: string,
+ * }} args
+ * @returns {object}
+ */
+export function buildModelAttributionPayload(args) {
+  const { ticketId, identity, recordedAt } = args ?? {};
+  const payload = {
+    kind: MODEL_ATTRIBUTION_TYPE,
+    ticketId,
+    model: identity?.family
+      ? { id: identity.id, family: identity.family }
+      : { id: identity?.id },
+    source: identity?.source,
+    recordedAt: recordedAt ?? new Date().toISOString(),
+  };
+  if (identity?.sdkMetadata && typeof identity.sdkMetadata === 'object') {
+    payload.sdkMetadata = identity.sdkMetadata;
+  }
+  return payload;
+}
+
+const VALID_SOURCES = new Set(['sdk-metadata', 'env', 'unknown']);
+const ISO_8601_RE =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * Hand-rolled validator matching
+ * `.agents/schemas/model-attribution.schema.json`. Returns
+ * `{ ok: true }` on success, `{ ok: false, errors: string[] }` on
+ * failure. The error strings are stable enough to assert against in
+ * tests.
+ *
+ * The codebase does not pull in `ajv` for runtime schema validation
+ * (signals + structured comments use hand-rolled shape guards — see
+ * `lib/signals/schema.js`). We follow the same pattern here so the
+ * schema file stays the documented SSOT and the validator is the
+ * runtime gate.
+ *
+ * @param {unknown} payload
+ * @returns {{ ok: true } | { ok: false, errors: string[] }}
+ */
+export function validateModelAttributionPayload(payload) {
+  const errors = [];
+  if (
+    payload === null ||
+    typeof payload !== 'object' ||
+    Array.isArray(payload)
+  ) {
+    return { ok: false, errors: ['payload must be a plain object'] };
+  }
+  if (payload.kind !== MODEL_ATTRIBUTION_TYPE) {
+    errors.push(`kind must be "${MODEL_ATTRIBUTION_TYPE}"`);
+  }
+  if (!Number.isInteger(payload.ticketId) || payload.ticketId <= 0) {
+    errors.push('ticketId must be a positive integer');
+  }
+  if (
+    !payload.model ||
+    typeof payload.model !== 'object' ||
+    Array.isArray(payload.model)
+  ) {
+    errors.push('model must be an object');
+  } else {
+    if (typeof payload.model.id !== 'string' || payload.model.id.length === 0) {
+      errors.push('model.id must be a non-empty string');
+    }
+    if (
+      payload.model.family !== undefined &&
+      (typeof payload.model.family !== 'string' ||
+        payload.model.family.length === 0)
+    ) {
+      errors.push('model.family, when present, must be a non-empty string');
+    }
+  }
+  if (
+    typeof payload.source !== 'string' ||
+    !VALID_SOURCES.has(payload.source)
+  ) {
+    errors.push(`source must be one of: ${[...VALID_SOURCES].join(', ')}`);
+  }
+  if (
+    typeof payload.recordedAt !== 'string' ||
+    !ISO_8601_RE.test(payload.recordedAt)
+  ) {
+    errors.push('recordedAt must be an ISO-8601 timestamp string');
+  }
+  if (
+    payload.sdkMetadata !== undefined &&
+    (payload.sdkMetadata === null ||
+      typeof payload.sdkMetadata !== 'object' ||
+      Array.isArray(payload.sdkMetadata))
+  ) {
+    errors.push('sdkMetadata, when present, must be an object');
+  }
+  return errors.length ? { ok: false, errors } : { ok: true };
+}
+
+/**
+ * Render the markdown body that gets upserted as the structured comment.
+ * Body is a one-line summary followed by the canonical payload inside a
+ * fenced ```json``` block so downstream readers can use the shared
+ * `parseFencedJsonComment` helper without bespoke parsing.
+ *
+ * @param {object} payload — already validated.
+ * @returns {string}
+ */
+export function renderModelAttributionBody(payload) {
+  const id = payload.model?.id ?? UNKNOWN_MODEL_ID;
+  const family = payload.model?.family ? ` (${payload.model.family})` : '';
+  const sourceLabel =
+    payload.source === 'sdk-metadata'
+      ? 'SDK metadata'
+      : payload.source === 'env'
+        ? 'env var'
+        : 'unknown source';
+  const header = `🤖 Model attribution: \`${id}\`${family} · via ${sourceLabel}`;
+  return [header, '', '```json', JSON.stringify(payload, null, 2), '```'].join(
+    '\n',
+  );
+}
+
+/**
+ * Emit (idempotently) the model-attribution comment onto a Task ticket.
+ * Validates the payload before any IO — a malformed payload throws and
+ * writes nothing to the provider.
+ *
+ * @param {{
+ *   provider: import('../ITicketingProvider.js').ITicketingProvider,
+ *   ticketId: number,
+ *   sdkMetadata?: object|null,
+ *   env?: Record<string, string|undefined>,
+ *   recordedAt?: string,
+ * }} args
+ * @returns {Promise<{ payload: object, body: string }>}
+ */
+export async function emitModelAttribution(args) {
+  const { provider, ticketId, sdkMetadata, env, recordedAt } = args ?? {};
+  if (!provider || typeof provider.postComment !== 'function') {
+    throw new TypeError(
+      'emitModelAttribution requires a provider with postComment',
+    );
+  }
+  if (!Number.isInteger(ticketId) || ticketId <= 0) {
+    throw new TypeError(
+      'emitModelAttribution requires a positive integer ticketId',
+    );
+  }
+  const identity = resolveModelIdentity({ sdkMetadata, env });
+  const payload = buildModelAttributionPayload({
+    ticketId,
+    identity,
+    recordedAt,
+  });
+  const result = validateModelAttributionPayload(payload);
+  if (!result.ok) {
+    throw new Error(
+      `model-attribution payload failed validation: ${result.errors.join('; ')}`,
+    );
+  }
+  const body = renderModelAttributionBody(payload);
+  await upsertStructuredComment(
+    provider,
+    ticketId,
+    MODEL_ATTRIBUTION_TYPE,
+    body,
+  );
+  return { payload, body };
+}
+
+/**
+ * Read back a model-attribution comment from a ticket. Returns the
+ * parsed payload, or `null` when the comment is missing or its payload
+ * fails validation (malformed payloads are treated as "no attribution"
+ * so a single corrupt comment does not poison the whole rollup).
+ *
+ * @param {{
+ *   provider: import('../ITicketingProvider.js').ITicketingProvider,
+ *   ticketId: number,
+ * }} args
+ * @returns {Promise<object|null>}
+ */
+export async function parseModelAttributionComment(args) {
+  const { provider, ticketId } = args ?? {};
+  const comment = await findStructuredComment(
+    provider,
+    ticketId,
+    MODEL_ATTRIBUTION_TYPE,
+  );
+  if (!comment) return null;
+  const parsed = parseFencedJsonComment(comment);
+  if (!parsed) return null;
+  const result = validateModelAttributionPayload(parsed);
+  return result.ok ? parsed : null;
+}
+
+/**
+ * Walk the immediate child tickets of a parent (e.g. an Epic's Stories),
+ * read each child's model-attribution comment (when present), and
+ * aggregate per-model counts. Children with no attribution comment are
+ * counted under `missing`.
+ *
+ * Rollup is keyed by `model.family` when present, otherwise by
+ * `model.id` so unknown families still aggregate distinctly. The
+ * envelope also exposes the per-id breakdown for callers that want a
+ * finer-grained view.
+ *
+ * @param {{
+ *   provider: import('../ITicketingProvider.js').ITicketingProvider,
+ *   parentId: number,
+ * }} args
+ * @returns {Promise<{
+ *   parentId: number,
+ *   totalChildren: number,
+ *   missing: number,
+ *   byModel: Record<string, number>,
+ *   byId: Record<string, number>,
+ * }>}
+ */
+export async function rollupModelAttribution(args) {
+  const { provider, parentId } = args ?? {};
+  if (!provider || typeof provider.getSubTickets !== 'function') {
+    throw new TypeError(
+      'rollupModelAttribution requires a provider with getSubTickets',
+    );
+  }
+  if (!Number.isInteger(parentId) || parentId <= 0) {
+    throw new TypeError(
+      'rollupModelAttribution requires a positive integer parentId',
+    );
+  }
+  const children = (await provider.getSubTickets(parentId)) ?? [];
+  const byModel = {};
+  const byId = {};
+  let missing = 0;
+  for (const child of children) {
+    const childId = Number(child?.id);
+    if (!Number.isInteger(childId) || childId <= 0) {
+      missing += 1;
+      continue;
+    }
+    const payload = await parseModelAttributionComment({
+      provider,
+      ticketId: childId,
+    });
+    if (!payload) {
+      missing += 1;
+      continue;
+    }
+    const familyKey =
+      payload.model?.family ?? payload.model?.id ?? UNKNOWN_MODEL_ID;
+    const idKey = payload.model?.id ?? UNKNOWN_MODEL_ID;
+    byModel[familyKey] = (byModel[familyKey] ?? 0) + 1;
+    byId[idKey] = (byId[idKey] ?? 0) + 1;
+  }
+  return {
+    parentId,
+    totalChildren: children.length,
+    missing,
+    byModel,
+    byId,
+  };
+}

package/.agents/scripts/lib/orchestration/parked-follow-ons.js

@@ -0,0 +1,147 @@
+/**
+ * Classify Stories that exist under an Epic but are absent from the frozen
+ * dispatch manifest. Two cases:
+ *
+ *   - "recut"  — the Story carries a `<!-- recut-of: #N -->` marker whose
+ *                parent ID matches a manifest entry. These are attributable
+ *                to a manifest Story and must be satisfied alongside it.
+ *
+ *   - "parked" — the Story is genuinely outside the manifest (carved off
+ *                mid-sprint, no recut lineage). The operator should explicitly
+ *                adopt it into the current Epic or defer it. Surfaced as a
+ *                structured comment so `/epic-deliver` has a single checkpoint.
+ *
+ * Both categories are informational at the wave-completeness gate — they do
+ * not fail closure by themselves. The gate continues to enforce that every
+ * manifest Story is closed; recuts and parked follow-ons are additional
+ * transparency.
+ */
+
+import { parseRecutMarker } from './recut.js';
+
+/**
+ * Partition Stories under an Epic into manifest, recut, and parked buckets.
+ *
+ * @param {number[]} manifestStoryIds  IDs present in the dispatch manifest.
+ * @param {Array<{ id: number, title?: string, body?: string, state?: string, labels?: string[] }>} storiesUnderEpic
+ *   All `type::story` tickets under the Epic.
+ * @returns {{
+ *   manifest: Array<object>,
+ *   recuts: Array<{ storyId: number, parentId: number, title: string, state: string }>,
+ *   parked: Array<{ storyId: number, title: string, state: string }>,
+ * }}
+ */
+export function classifyStoriesAgainstManifest(
+  manifestStoryIds,
+  storiesUnderEpic,
+) {
+  const manifestSet = new Set(manifestStoryIds.map(Number));
+  const manifest = [];
+  const recuts = [];
+  const parked = [];
+
+  for (const story of storiesUnderEpic) {
+    if (manifestSet.has(story.id)) {
+      manifest.push(story);
+      continue;
+    }
+    const marker = parseRecutMarker(story.body);
+    if (marker && manifestSet.has(marker.parentStoryId)) {
+      recuts.push({
+        storyId: story.id,
+        parentId: marker.parentStoryId,
+        title: story.title ?? '',
+        state: story.state ?? 'open',
+      });
+    } else {
+      parked.push({
+        storyId: story.id,
+        title: story.title ?? '',
+        state: story.state ?? 'open',
+      });
+    }
+  }
+
+  return { manifest, recuts, parked };
+}
+
+/**
+ * Render the structured `parked-follow-ons` comment body for an Epic.
+ * Idempotent: the same input produces identical output, so repeated upserts
+ * don't churn comment revisions.
+ *
+ * @param {number} epicId
+ * @param {ReturnType<typeof classifyStoriesAgainstManifest>} classification
+ * @returns {string}
+ */
+export function renderParkedFollowOnsComment(epicId, classification) {
+  const { recuts, parked } = classification;
+
+  const lines = [
+    `## 🪝 Parked Follow-Ons & Recuts — Epic #${epicId}`,
+    '',
+    'Stories created under this Epic that are **not** in the frozen dispatch',
+    'manifest. Surfaced here so `/epic-deliver` can gate on them at the',
+    'completeness check.',
+    '',
+    `- **Recuts** (attributable to a manifest Story): ${recuts.length}`,
+    `- **Parked follow-ons** (no manifest lineage): ${parked.length}`,
+    '',
+  ];
+
+  if (recuts.length > 0) {
+    lines.push('### Recuts');
+    lines.push('');
+    lines.push('| Story | Recut-of | State | Title |');
+    lines.push('| :--- | :--- | :--- | :--- |');
+    for (const r of recuts) {
+      lines.push(
+        `| #${r.storyId} | #${r.parentId} | ${r.state} | ${r.title} |`,
+      );
+    }
+    lines.push('');
+  }
+
+  if (parked.length > 0) {
+    lines.push('### Parked Follow-Ons');
+    lines.push('');
+    lines.push('| Story | State | Title |');
+    lines.push('| :--- | :--- | :--- |');
+    for (const p of parked) {
+      lines.push(`| #${p.storyId} | ${p.state} | ${p.title} |`);
+    }
+    lines.push('');
+    lines.push(
+      '> **Action required**: adopt each Story into the current Epic (by',
+      '> re-running the dispatcher so the manifest is refreshed), or explicitly',
+      '> defer by closing the Story with `state_reason=not_planned`.',
+    );
+    lines.push('');
+  }
+
+  if (recuts.length === 0 && parked.length === 0) {
+    lines.push(
+      '✅ No out-of-manifest Stories detected — every Story under this Epic is in the dispatch manifest.',
+    );
+    lines.push('');
+  }
+
+  lines.push('```json');
+  lines.push(
+    JSON.stringify(
+      {
+        recuts: recuts.map((r) => ({
+          storyId: r.storyId,
+          parentId: r.parentId,
+          state: r.state,
+        })),
+        parked: parked.map((p) => ({ storyId: p.storyId, state: p.state })),
+      },
+      null,
+      2,
+    ),
+  );
+  lines.push('```');
+
+  return lines.join('\n');
+}

package/.agents/scripts/lib/orchestration/phase-runner.js

@@ -0,0 +1,87 @@
+/**
+ * phase-runner.js — Lightweight wrappers for "named phase" error handling.
+ *
+ * Many orchestration entry points (story-init, story-close,
+ * the epic-runner submodules) repeat the same `try { ... } catch (err) {
+ * logger.error('[phase=foo] ' + err.message); ... }` block. These two
+ * helpers consolidate that pattern.
+ *
+ *   - `runPhase(name, fn, opts)`: Run `fn()`. On error, log with a
+ *     `[phase=<name>]` prefix. If `fatal: true`, rethrow; otherwise
+ *     return `opts.fallback` (default `undefined`) so the caller can
+ *     continue.
+ *
+ *   - `runSafely(fn, opts)`: Run `fn()` and swallow any error after
+ *     logging it. Convenience for unnamed best-effort cleanup steps.
+ *
+ * Both helpers handle sync and async `fn`s — the return value is always
+ * a Promise that resolves to the function's value (or `fallback`).
+ */
+
+import { NOOP_LOGGER } from '../Logger.js';
+
+/**
+ * @typedef {object} PhaseLogger
+ * @property {(msg: string) => void} [error]
+ * @property {(msg: string) => void} [warn]
+ */
+
+function pickLogger(logger) {
+  if (!logger) return NOOP_LOGGER;
+  return {
+    error:
+      typeof logger.error === 'function'
+        ? logger.error.bind(logger)
+        : NOOP_LOGGER.error,
+    warn:
+      typeof logger.warn === 'function'
+        ? logger.warn.bind(logger)
+        : NOOP_LOGGER.warn,
+  };
+}
+
+/**
+ * Run `fn` under a named phase. On error:
+ *   - logs `[phase=<name>] <message>` via `logger.error`
+ *   - if `fatal` is true, rethrows the original error
+ *   - otherwise returns `fallback`
+ *
+ * @template T
+ * @param {string} name - Phase name (used in the log prefix).
+ * @param {() => (T | Promise<T>)} fn
+ * @param {{ logger?: PhaseLogger, fallback?: T, fatal?: boolean }} [opts]
+ * @returns {Promise<T | undefined>}
+ */
+export async function runPhase(name, fn, opts = {}) {
+  const logger = pickLogger(opts.logger);
+  const fatal = opts.fatal === true;
+  try {
+    return await fn();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.error(`[phase=${name}] ${message}`);
+    if (fatal) throw err;
+    return opts.fallback;
+  }
+}
+
+/**
+ * Run `fn` and swallow errors after logging. Equivalent to
+ * `runPhase('safe', fn, { logger, fatal: false })` but without requiring
+ * the caller to invent a phase name.
+ *
+ * @template T
+ * @param {() => (T | Promise<T>)} fn
+ * @param {{ logger?: PhaseLogger }} [opts]
+ * @returns {Promise<T | undefined>}
+ */
+export async function runSafely(fn, opts = {}) {
+  const logger = pickLogger(opts.logger);
+  try {
+    return await fn();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.warn(`[phase=safe] ${message}`);
+    return undefined;
+  }
+}

package/.agents/scripts/lib/orchestration/plan-review-routing.js

@@ -0,0 +1,63 @@
+/**
+ * plan-review-routing.js — resolve Phase 7 review-stop vs auto-proceed.
+ *
+ * Pure ESM, no I/O. Consumes the shared planningRisk envelope (derived
+ * from the planner-authored risk verdict via `deriveRiskEnvelope`) and
+ * optional operator overrides to decide whether the plan wrapper should
+ * STOP for human review before Phase 8.
+ */
+
+/**
+ * @typedef {import('./planning-risk.js').PlanningRiskEnvelope} PlanningRiskEnvelope
+ * @typedef {'review-required' | 'auto-proceed' | 'operator-override-review'} ReviewRoutingDecision
+ */
+
+/**
+ * @typedef {Object} ReviewRoutingEnvelope
+ * @property {ReviewRoutingDecision} decision
+ * @property {boolean} requiresStop
+ * @property {boolean} forceReviewApplied
+ * @property {string} operatorMessage
+ */
+
+const AUTO_PROCEED_MESSAGE =
+  'Planning risk is low — auto-proceeding to Phase 8 decomposition after spec validation. Context tickets remain open until Epic delivery finalizes.';
+
+const REVIEW_REQUIRED_MESSAGE =
+  'Planning risk requires operator review — STOP before Phase 8. Review the PRD, Tech Spec, and Acceptance Spec on GitHub and confirm in this session before decomposition.';
+
+const FORCE_REVIEW_MESSAGE =
+  'Operator override — forcing review stop before Phase 8 despite low planning risk.';
+
+/**
+ * Resolve whether Phase 7 should STOP for operator review before Phase 8.
+ *
+ * @param {{ planningRisk: PlanningRiskEnvelope, forceReview?: boolean }} input
+ * @returns {ReviewRoutingEnvelope}
+ */
+export function resolveReviewRouting({ planningRisk, forceReview = false }) {
+  if (forceReview) {
+    return {
+      decision: 'operator-override-review',
+      requiresStop: true,
+      forceReviewApplied: true,
+      operatorMessage: FORCE_REVIEW_MESSAGE,
+    };
+  }
+
+  if (planningRisk.requiresReview) {
+    return {
+      decision: 'review-required',
+      requiresStop: true,
+      forceReviewApplied: false,
+      operatorMessage: REVIEW_REQUIRED_MESSAGE,
+    };
+  }
+
+  return {
+    decision: 'auto-proceed',
+    requiresStop: false,
+    forceReviewApplied: false,
+    operatorMessage: AUTO_PROCEED_MESSAGE,
+  };
+}