mandrel 1.57.0

package/.agents/scripts/lib/orchestration/epic-deliver-lease-guard.js

@@ -0,0 +1,310 @@
+/**
+ * epic-deliver-lease-guard.js — preflight guards for `/epic-deliver`
+ * (Story #3482, Epic #3457).
+ *
+ * `/epic-deliver`'s prepare phase used to checkout `epic/<id>` over whatever
+ * the operator had checked out, yanking HEAD and resetting baselines under a
+ * live working session (the documented "epic-deliver shares the main checkout"
+ * footgun). This module supplies the two preflight guards the Tech Spec
+ * (#3476) wires into `epic-deliver-prepare.js` *before* any mutating git work:
+ *
+ *   1. **Epic-lease preflight.** Acquire the assignee-as-lease on the Epic
+ *      ticket via `ticket-lease.acquireLease`. On a live foreign claim the
+ *      guard **fails closed** — it throws a clear, operator-facing error that
+ *      names the current owner (the `critical-workflow` risk axis demands
+ *      refuse-and-exit, never warn-and-continue). `--steal` is the only
+ *      override.
+ *   2. **Checkout-safety preflight.** Refuse to start when the working tree is
+ *      dirty or HEAD is on a branch other than the expected one, instead of
+ *      checking `epic/<id>` out over the operator's work.
+ *
+ * Both guards are pure over injected seams (a `git` shim with
+ * `statusPorcelain` / `currentBranch`, and the lease provider) so the unit
+ * suite exercises them without standing up a real repo or hitting GitHub.
+ * Liveness is threaded in via `heartbeatAt` exactly as `ticket-lease.js`
+ * documents — this module does not read the lifecycle ledger itself.
+ *
+ * Per `.agents/rules/orchestration-error-handling.md`, the composed guard
+ * surfaces unrecoverable failures with `throw new Error(...)` (mapped to
+ * `process.exit(1)` by the `runAsCli` boundary), never `Logger.fatal`.
+ */
+
+import { acquireLease, normalizeOperatorHandle } from './ticket-lease.js';
+
+/**
+ * Resolve the acquiring operator's identity. Precedence (Tech Spec #3476):
+ *   1. An explicit `--as <handle>` flag.
+ *   2. `github.operatorHandle` in `.agentrc.json`.
+ *   3. The local `git config user.email`.
+ *
+ * The `@`-prefix some operators carry on `operatorHandle` is stripped so the
+ * value matches the bare login written to a ticket's `assignees`.
+ *
+ * @param {object} args
+ * @param {string} [args.asFlag]        Explicit `--as` value.
+ * @param {object} [args.config]        Resolved config (reads github.operatorHandle).
+ * @param {string} [args.gitUserEmail]  Fallback `git config user.email`.
+ * @returns {string|null} The resolved operator handle, or null when none could
+ *   be determined.
+ */
+export function resolveOperator({ asFlag, config, gitUserEmail } = {}) {
+  const candidates = [asFlag, config?.github?.operatorHandle, gitUserEmail];
+  for (const raw of candidates) {
+    const normalized = normalizeOperatorHandle(raw);
+    if (normalized !== null) return normalized;
+  }
+  return null;
+}
+
+/**
+ * Normalise the expected-branch argument into a non-empty list. `/epic-deliver`
+ * may legitimately start from either the Epic integration branch (`epic/<id>`,
+ * on a resume) or the project base branch (`main`, on a fresh run), so the
+ * guard accepts a set rather than a single name.
+ *
+ * @param {string|string[]} expectedBranch
+ * @returns {string[]}
+ */
+function normaliseExpectedBranches(expectedBranch) {
+  const list = (
+    Array.isArray(expectedBranch) ? expectedBranch : [expectedBranch]
+  ).filter((b) => typeof b === 'string' && b.length > 0);
+  if (list.length === 0) {
+    throw new Error('checkCheckoutSafety: expectedBranch is required');
+  }
+  return list;
+}
+
+/**
+ * Pure checkout-safety classifier. The working tree must be clean and HEAD
+ * must sit on one of `expectedBranch` before prepare moves anything.
+ *
+ * @param {object} args
+ * @param {object} args.git              Injected git shim.
+ * @param {() => { dirty: boolean, entries?: string }} args.git.statusPorcelain
+ *   Returns whether the tree has uncommitted/untracked changes.
+ * @param {() => string|null} args.git.currentBranch  Returns HEAD's branch (or
+ *   null in detached-HEAD state).
+ * @param {string|string[]} args.expectedBranch  The branch (or branches)
+ *   prepare expects HEAD on (typically `epic/<id>` or the project base branch).
+ * @returns {{
+ *   safe: boolean,
+ *   reason: 'clean'|'dirty'|'wrong-branch'|'detached-head',
+ *   currentBranch: string|null,
+ *   expectedBranches: string[],
+ *   dirtyEntries?: string,
+ * }}
+ */
+export function checkCheckoutSafety({ git, expectedBranch }) {
+  if (!git || typeof git.statusPorcelain !== 'function') {
+    throw new Error(
+      'checkCheckoutSafety: git shim with statusPorcelain/currentBranch is required',
+    );
+  }
+  const expectedBranches = normaliseExpectedBranches(expectedBranch);
+
+  const status = git.statusPorcelain();
+  if (status?.dirty) {
+    return {
+      safe: false,
+      reason: 'dirty',
+      currentBranch: git.currentBranch(),
+      expectedBranches,
+      dirtyEntries: status.entries,
+    };
+  }
+
+  const branch = git.currentBranch();
+  if (branch === null || branch === undefined || branch === '') {
+    return {
+      safe: false,
+      reason: 'detached-head',
+      currentBranch: null,
+      expectedBranches,
+    };
+  }
+  if (!expectedBranches.includes(branch)) {
+    return {
+      safe: false,
+      reason: 'wrong-branch',
+      currentBranch: branch,
+      expectedBranches,
+    };
+  }
+  return {
+    safe: true,
+    reason: 'clean',
+    currentBranch: branch,
+    expectedBranches,
+  };
+}
+
+/**
+ * Render the operator-facing message for a failed checkout-safety guard.
+ *
+ * @param {ReturnType<typeof checkCheckoutSafety>} result
+ * @returns {string}
+ */
+export function renderCheckoutRefusal(result) {
+  const expected = result.expectedBranches.map((b) => `'${b}'`).join(' or ');
+  if (result.reason === 'dirty') {
+    return (
+      `[epic-deliver] Refusing to start: the working tree is dirty. ` +
+      `/epic-deliver will not check out ${expected} over uncommitted ` +
+      `or untracked changes — commit, stash, or clean them, then re-run.\n` +
+      `--- dirty entries ---\n${result.dirtyEntries ?? '(unavailable)'}`
+    );
+  }
+  if (result.reason === 'detached-head') {
+    return (
+      `[epic-deliver] Refusing to start: HEAD is detached. /epic-deliver ` +
+      `expects HEAD on ${expected}. Check one out before re-running.`
+    );
+  }
+  return (
+    `[epic-deliver] Refusing to start: HEAD is on '${result.currentBranch}', ` +
+    `not the expected ${expected}. /epic-deliver will not yank HEAD ` +
+    `away from your branch — switch to ${expected} yourself before re-running.`
+  );
+}
+
+/**
+ * Render the operator-facing message for a refused (live foreign) lease.
+ *
+ * @param {{ owner: string|null }} lease
+ * @param {number} epicId
+ * @returns {string}
+ */
+export function renderLeaseRefusal(lease, epicId) {
+  return (
+    `[epic-deliver] Refusing to start: Epic #${epicId} is already claimed by ` +
+    `'${lease.owner}' with a live lease (recent heartbeat within the TTL). ` +
+    `Another /epic-deliver run is driving this Epic. Wait for it to finish, ` +
+    `or pass --steal to forcibly transfer the claim.`
+  );
+}
+
+/**
+ * Acquire the Epic lease for `operator`, failing closed on a live foreign
+ * claim. Returns the `acquireLease` result on success.
+ *
+ * @param {object} args
+ * @param {object} args.provider              Ticketing provider.
+ * @param {number} args.epicId                Epic ticket id.
+ * @param {string} args.operator              Resolved operator handle.
+ * @param {number|null} [args.heartbeatAt]    Current owner's last heartbeat (epoch ms).
+ * @param {boolean} [args.steal=false]        Transfer a live foreign claim.
+ * @param {object} [args.config]              Resolved config (TTL default).
+ * @param {number} [args.now]                 Injectable clock.
+ * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
+ * @throws {Error} when the Epic carries a live foreign claim and `steal` is false.
+ */
+export async function acquireEpicLease({
+  provider,
+  epicId,
+  operator,
+  heartbeatAt = null,
+  steal = false,
+  config,
+  now,
+}) {
+  const result = await acquireLease({
+    provider,
+    ticketId: epicId,
+    operator,
+    heartbeatAt,
+    steal,
+    config,
+    now,
+  });
+  if (!result.acquired) {
+    throw new Error(renderLeaseRefusal(result, epicId));
+  }
+  return result;
+}
+
+/**
+ * Compose the two preflight guards in the order prepare needs them: the
+ * checkout-safety check first (cheap, local, no network), then the Epic-lease
+ * acquisition (a GitHub round-trip). Both fail closed by throwing.
+ *
+ * The checkout-safety guard runs first (cheap, local) and always executes. The
+ * Epic-lease step then **fails closed**: when `operator` cannot be resolved
+ * (null — `--as`, `github.operatorHandle`, and `git user.email` all empty, with
+ * the shipped `@[USERNAME]` placeholder normalised to null), this throws rather
+ * than running an ownerless, unguarded delivery. The lease is the cross-clone
+ * coordination layer; without an identity it cannot serialise concurrent runs,
+ * so silently skipping it would defeat the guard.
+ *
+ * @param {object} args
+ * @param {number} args.epicId
+ * @param {string|string[]} args.expectedBranch  Branch(es) prepare expects HEAD on.
+ * @param {object} args.git                   Injected git shim (statusPorcelain/currentBranch).
+ * @param {object} args.provider              Ticketing provider for the lease.
+ * @param {string|null} args.operator         Resolved operator handle (null fails closed → throw).
+ * @param {number|null} [args.heartbeatAt]    Current owner's last heartbeat (epoch ms).
+ * @param {boolean} [args.steal=false]        Transfer a live foreign claim.
+ * @param {object} [args.config]              Resolved config.
+ * @param {number} [args.now]                 Injectable clock.
+ * @param {object} [args.logger]              Logger with info/warn.
+ * @returns {Promise<{
+ *   checkout: ReturnType<typeof checkCheckoutSafety>,
+ *   lease: { acquired: boolean, owner: string, reason: string },
+ * }>}
+ * @throws {Error} on a dirty/wrong-branch tree, an unresolvable operator
+ *   identity, or a refused live foreign lease.
+ */
+export async function runPrepareGuards({
+  epicId,
+  expectedBranch,
+  git,
+  provider,
+  operator,
+  heartbeatAt = null,
+  steal = false,
+  config,
+  now,
+  logger,
+}) {
+  const log = logger ?? { info: () => {}, warn: () => {} };
+
+  const checkout = checkCheckoutSafety({ git, expectedBranch });
+  if (!checkout.safe) {
+    throw new Error(renderCheckoutRefusal(checkout));
+  }
+  log.info?.(
+    `[epic-deliver] ✅ Checkout-safety guard passed (clean tree on '${checkout.currentBranch}').`,
+  );
+
+  if (!operator) {
+    throw new Error(
+      '[epic-deliver] Refusing to start: no operator identity could be ' +
+        'resolved. --as, github.operatorHandle (unset or still the shipped ' +
+        '`@[USERNAME]` placeholder), and git user.email are all empty, so the ' +
+        'Epic-lease has no owner and concurrent /epic-deliver runs cannot be ' +
+        'serialised. Set your own handle in .agentrc.local.json (e.g. ' +
+        '{ "github": { "operatorHandle": "@your-login" } }), pass --as <handle>, ' +
+        'or configure git user.email, then re-run.',
+    );
+  }
+
+  const lease = await acquireEpicLease({
+    provider,
+    epicId,
+    operator,
+    heartbeatAt,
+    steal,
+    config,
+    now,
+  });
+  if (lease.reason === 'stolen') {
+    log.warn?.(
+      `[epic-deliver] ⚠️  Stole the Epic #${epicId} lease from '${lease.previousOwner}' via --steal (live claim forcibly transferred).`,
+    );
+  } else {
+    log.info?.(
+      `[epic-deliver] ✅ Acquired Epic #${epicId} lease for '${operator}' (reason=${lease.reason}).`,
+    );
+  }
+  return { checkout, lease };
+}

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

@@ -0,0 +1,167 @@
+/**
+ * cli.js — Phase 6 (CLI entry orchestration) of the epic-plan-decompose
+ * pipeline (Story #2466).
+ *
+ * Owns CLI flag parsing, the `--emit-context` JSON envelope path, and
+ * the tickets-file load → `runDecomposePhase` persist path. The
+ * partial-failure diagnostics emitter lives in the sibling
+ * `diagnostics.js` module.
+ *
+ * @module lib/orchestration/epic-plan-decompose/phases/cli
+ */
+
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+
+import { drainPendingCleanupAtBoot } from '../../../../epic-plan-spec.js';
+import {
+  PROJECT_ROOT,
+  resolveConfig,
+  validateOrchestrationConfig,
+} from '../../../config-resolver.js';
+import {
+  Logger,
+  routeAllOutputToStderr,
+  STDERR_LOGGER,
+} from '../../../Logger.js';
+import { createProvider } from '../../../provider-factory.js';
+import { buildDecompositionContext } from './context.js';
+import { reportPartialFailure } from './diagnostics.js';
+import { runDecomposePhase } from './persist.js';
+
+const CLI_OPTIONS = {
+  epic: { type: 'string' },
+  tickets: { type: 'string' },
+  force: { type: 'boolean', default: false },
+  resume: { type: 'boolean', default: false },
+  'allow-over-budget': { type: 'boolean', default: false },
+  'allow-large-fan-out': { type: 'boolean', default: false },
+  'emit-context': { type: 'boolean', default: false },
+  pretty: { type: 'boolean', default: false },
+  'full-context': { type: 'boolean', default: false },
+};
+
+const USAGE =
+  'Usage: epic-plan-decompose.js --epic <EpicId> (--emit-context [--pretty] [--full-context] | --tickets <file>) [--force | --resume] [--allow-over-budget] [--allow-large-fan-out]';
+
+function parseEpicId(rawEpic) {
+  if (!rawEpic) throw new Error(USAGE);
+  const epicId = Number.parseInt(rawEpic, 10);
+  if (Number.isNaN(epicId)) {
+    throw new Error(`Invalid epic ID: "${rawEpic}" — must be a number.`);
+  }
+  return epicId;
+}
+
+function loadResolvedConfig() {
+  let config;
+  try {
+    config = resolveConfig();
+    // Epic #2880 / F14B: pass the canonical resolved config directly.
+    // The legacy `config.orchestration` pointer is gone; the validator
+    // reads `config.github` and `config.delivery.worktreeIsolation`.
+    validateOrchestrationConfig(config);
+  } catch (err) {
+    throw new Error(
+      `Orchestration config schema validation failed:\n${err.message}`,
+    );
+  }
+  return config;
+}
+
+async function driveDrainPendingCleanup({ config, provider, emitContext }) {
+  try {
+    await drainPendingCleanupAtBoot({
+      repoRoot: PROJECT_ROOT,
+      // Epic #2880 / F14B: drainPendingCleanupAtBoot now reads opts.config
+      // (canonical) and resolves the worktree root from
+      // config.delivery.worktreeIsolation.root.
+      config,
+      provider,
+      logger: emitContext ? STDERR_LOGGER : undefined,
+    });
+  } catch (err) {
+    Logger.warn(`[epic-plan-decompose] worktree sweep skipped: ${err.message}`);
+  }
+}
+
+async function runEmitContextPath({ epicId, provider, config, values }) {
+  const ctx = await buildDecompositionContext(epicId, provider, config, {
+    fullContext: values['full-context'],
+  });
+  // Surface the resolved budget on stderr so a misconfigured `.agentrc.json`
+  // (e.g. flat-key `maxTickets` instead of grouped `planning.maxTickets`) is
+  // visible to the operator. The decomposer prompt embeds the same value.
+  // Story #2798 — language changed from "prompt cap" to "reviewability
+  // budget" to match the new prompt/skill contract.
+  Logger.error(
+    `[epic-plan-decompose] Resolved planning.maxTickets = ${ctx.maxTickets} (reviewability budget).`,
+  );
+  const json = values.pretty
+    ? JSON.stringify(ctx, null, 2)
+    : JSON.stringify(ctx);
+  process.stdout.write(`${json}\n`);
+}
+
+async function loadTicketsFile(ticketsPath) {
+  if (!ticketsPath) {
+    throw new Error(
+      'Missing --tickets <file>. (Use --emit-context first to gather authoring context.)',
+    );
+  }
+  const raw = await readFile(ticketsPath, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse tickets file "${ticketsPath}" as JSON: ${err.message}`,
+    );
+  }
+}
+
+async function runPersistPath({ epicId, provider, config, values }) {
+  const tickets = await loadTicketsFile(values.tickets);
+  let result;
+  try {
+    result = await runDecomposePhase(epicId, provider, { tickets }, config, {
+      force: values.force,
+      resume: values.resume,
+      allowOverBudget: values['allow-over-budget'],
+      allowLargeFanOut: values['allow-large-fan-out'],
+    });
+  } catch (err) {
+    await reportPartialFailure({ epicId, provider, err });
+    throw err;
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+/* node:coverage ignore next */
+export async function main() {
+  const { values } = parseArgs({ options: CLI_OPTIONS });
+  const epicId = parseEpicId(values.epic);
+  if (values.force && values.resume) {
+    throw new Error('--force and --resume are mutually exclusive.');
+  }
+
+  const config = loadResolvedConfig();
+  // Epic #2880 / F14B: createProvider takes the canonical resolved config
+  // (it reads config.github). The legacy config.orchestration pointer is
+  // gone; passing it yields undefined and crashes the provider factory's
+  // hard guard.
+  const provider = createProvider(config);
+  const emitContext = values['emit-context'];
+
+  // Story #2278 — in --emit-context mode stdout is reserved for the JSON
+  // envelope. Flip every Logger sink that could land on stdout to stderr
+  // before any orchestration code runs.
+  if (emitContext) routeAllOutputToStderr();
+
+  await driveDrainPendingCleanup({ config, provider, emitContext });
+
+  if (emitContext) {
+    await runEmitContextPath({ epicId, provider, config, values });
+    return;
+  }
+  await runPersistPath({ epicId, provider, config, values });
+}

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

@@ -0,0 +1,151 @@
+/**
+ * context.js — Phase 3 of the epic-plan-decompose pipeline (Story #2466).
+ *
+ * Builds the authoring context (PRD + Tech Spec bodies, heuristics, system
+ * prompt, ticket cap) the host LLM / `epic-plan-decompose-author` Skill
+ * consumes when producing the ticket JSON array.
+ *
+ * Extracted verbatim from `epic-plan-decompose.js`; both
+ * `buildDecomposerSystemPrompt` and `buildDecompositionContext` retain
+ * their public-export contract for the existing unit tests.
+ *
+ * @module lib/orchestration/epic-plan-decompose/phases/context
+ */
+
+import {
+  getLimits,
+  resolvePreflightCeilings,
+} from '../../../config-resolver.js';
+import { renderDecomposerSystemPrompt } from '../../../templates/decomposer-prompts.js';
+import { read as readPlanState } from '../../epic-plan-state-store.js';
+import { applyBudget } from '../../planning-context-budget.js';
+
+export function buildDecomposerSystemPrompt(
+  heuristics = [],
+  { maxTickets } = {},
+) {
+  const base = renderDecomposerSystemPrompt({ maxTickets });
+  const heuristicsStr =
+    heuristics.length > 0
+      ? `### RISK HEURISTICS (planning metadata if any apply):\n- ${heuristics.join('\n- ')}`
+      : '';
+  return `${base}${heuristicsStr ? `\n\n${heuristicsStr}` : ''}`;
+}
+
+function resolveHeuristics(config) {
+  if (Array.isArray(config.planning?.riskHeuristics)) {
+    return config.planning.riskHeuristics;
+  }
+  return config.agentSettings?.planning?.riskHeuristics || [];
+}
+
+function projectBudgetedEntry(item, ticket, mode) {
+  if (mode === 'full') return { id: ticket.id, body: ticket.body };
+  return { id: ticket.id, body: null, bodySummary: item };
+}
+
+/**
+ * Read the persisted planning decision for the Epic so the decomposition
+ * authoring step (Phase 8) can cite the same risk classification the
+ * gate routing used in Phase 7. The decision lives in the `epic-plan-state`
+ * structured comment written by `epic-plan-spec.js`.
+ *
+ * Returns `{ planningRisk: null, reviewRouting: null }` when the comment
+ * is missing (older plans planned before Story #2801 landed) or when the
+ * payload predates the fields. The null sentinels are part of the
+ * decomposition context contract — callers MUST be able to JSON.stringify
+ * the result without losing the keys.
+ *
+ * @param {import('../../../ITicketingProvider.js').ITicketingProvider} provider
+ * @param {number} epicId
+ * @returns {Promise<{ planningRisk: object | null, reviewRouting: object | null }>}
+ */
+async function readPlanningDecision(provider, epicId) {
+  let state = null;
+  try {
+    state = await readPlanState({ provider, epicId });
+  } catch (_err) {
+    // `read` already swallows JSON parse errors; a thrown error here
+    // means the provider couldn't fetch comments. Treat as null state —
+    // the decomposer can still author tickets without the risk envelope.
+    state = null;
+  }
+  if (!state || typeof state !== 'object') {
+    return { planningRisk: null, reviewRouting: null };
+  }
+  return {
+    planningRisk: state.planningRisk ?? null,
+    reviewRouting: state.reviewRouting ?? null,
+  };
+}
+
+async function fetchPlanningTickets(provider, epicId) {
+  const epic = await provider.getEpic(epicId);
+  if (!epic?.linkedIssues?.prd || !epic.linkedIssues.techSpec) {
+    throw new Error(
+      `[Decomposer] Epic #${epicId} is missing linked PRD or Tech Spec. Run the Epic Planner first.`,
+    );
+  }
+  const [prd, techSpec] = await Promise.all([
+    provider.getTicket(epic.linkedIssues.prd),
+    provider.getTicket(epic.linkedIssues.techSpec),
+  ]);
+  return { epic, prd, techSpec };
+}
+
+/**
+ * Build the authoring context the host LLM (or the
+ * `epic-plan-decompose-author` Skill) needs to produce the ticket JSON.
+ *
+ * PRD and Tech Spec bodies are bounded by the planning-context budget
+ * (Epic #817 Story 9). Pass `{ fullContext: true }` (CLI: `--full-context`)
+ * to restore the unbounded full bodies.
+ */
+export async function buildDecompositionContext(
+  epicId,
+  provider,
+  config = {},
+  opts = {},
+) {
+  const { epic, prd, techSpec } = await fetchPlanningTickets(provider, epicId);
+  const { planningRisk, reviewRouting } = await readPlanningDecision(
+    provider,
+    epicId,
+  );
+  const heuristics = resolveHeuristics(config);
+  const limits = getLimits(config);
+  const maxTickets = limits.maxTickets;
+  const planningLimits = limits.planningContext;
+  const { fullContext = false } = opts;
+  const systemPrompt = buildDecomposerSystemPrompt(heuristics, { maxTickets });
+
+  const budgeted = applyBudget(
+    [
+      { path: `prd-${prd.id}.md`, content: prd.body ?? '' },
+      { path: `tech-spec-${techSpec.id}.md`, content: techSpec.body ?? '' },
+    ],
+    planningLimits,
+    { fullContext },
+  );
+  const [prdItem, techSpecItem] = budgeted.items;
+  return {
+    epic: { id: epic.id, title: epic.title },
+    prd: projectBudgetedEntry(prdItem, prd, budgeted.mode),
+    techSpec: projectBudgetedEntry(techSpecItem, techSpec, budgeted.mode),
+    heuristics,
+    systemPrompt,
+    maxTickets,
+    // Story #3875 — surface the real delivery envelope to the decomposer
+    // so Stories are sized against the hydration budget and the
+    // configured preflight ceilings rather than guessed.
+    maxTokenBudget: limits.maxTokenBudget,
+    preflightCeilings: resolvePreflightCeilings(config),
+    contextMode: budgeted.mode,
+    // Story #2801 — surface the Phase 7 planning decision so the
+    // decomposition authoring step can cite the same risk
+    // classification used by gate routing. Both fields are `null`
+    // when the Epic was planned before the decision contract existed.
+    planningRisk,
+    reviewRouting,
+  };
+}

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

@@ -0,0 +1,74 @@
+/**
+ * creation.js — sub-issue link reconciliation, Epic label transitions, and
+ * the advisory ticket-cap warning used by the reconciler-based persist flow
+ * (`persist.js`).
+ *
+ * Exports: `reconcileSubIssueLinks`, `setEpicLabel`,
+ * `warnTicketCapNearLimit`.
+ *
+ * @module lib/orchestration/epic-plan-decompose/phases/creation
+ */
+
+import { Logger } from '../../../Logger.js';
+import { AGENT_LABELS } from '../../../label-constants.js';
+
+export async function reconcileSubIssueLinks(epicId, provider) {
+  if (typeof provider.reconcileSubIssueLinks !== 'function') return;
+  Logger.info(
+    `[Decomposer] Reconciling sub-issue API links for Epic #${epicId}...`,
+  );
+  const result = await provider.reconcileSubIssueLinks(epicId);
+  const { totalExpected, alreadyLinked, reconciled, failed, failures } = result;
+  if (failed === 0) {
+    const reconciledNote = reconciled > 0 ? ` (${reconciled} reconciled)` : '';
+    Logger.info(
+      `[Decomposer] linked ${alreadyLinked + reconciled}/${totalExpected} sub-issues${reconciledNote}`,
+    );
+    return;
+  }
+  for (const failure of failures) {
+    Logger.error(
+      `[Decomposer] sub-issue link gap: parent #${failure.parentId} ← child #${failure.childId}: ${failure.reason}`,
+    );
+  }
+  throw new Error(
+    `[Decomposer] Sub-issue reconciliation incomplete: ${failed}/${totalExpected} links could not be established (linked=${alreadyLinked}, reconciled=${reconciled}). See log for per-child reasons.`,
+  );
+}
+
+export async function setEpicLabel(provider, epicId, targetLabel) {
+  const planningLabels = [AGENT_LABELS.REVIEW_SPEC, AGENT_LABELS.READY];
+  await provider.updateTicket(epicId, {
+    labels: {
+      add: [targetLabel],
+      remove: planningLabels.filter((l) => l !== targetLabel),
+    },
+  });
+}
+
+/**
+ * Advisory-only ticket-count check (Story #2798).
+ *
+ * `maxTickets` is a **reviewability budget**, not a hard authoring cap.
+ * This helper emits a non-destructive warning when a decomposition meets
+ * or exceeds the budget so the operator can spot over-budget plans early
+ * in the persist flow. It never blocks — the hard gate lives in the
+ * `runDecomposePhase` over-budget check, which requires an explicit
+ * `allowOverBudget` (CLI: `--allow-over-budget`) override.
+ *
+ * @param {Array} tickets
+ * @param {number} maxTickets — the reviewability budget
+ * @param {string} [tag] — log prefix
+ * @param {{ logger?: Pick<typeof Logger, 'warn'> }} [opts]
+ */
+export function warnTicketCapNearLimit(
+  tickets,
+  maxTickets,
+  tag = 'epic-plan-decompose',
+  { logger = Logger } = {},
+) {
+  if (tickets.length < maxTickets) return;
+  logger.warn(
+    `[${tag}] ⚠️  Received ${tickets.length} tickets against a reviewability budget of ${maxTickets}. Review the Feature/Story split before persisting; over-budget persistence requires --allow-over-budget.`,
+  );
+}