mandrel 1.94.0 → 2.1.0

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

@@ -1,310 +0,0 @@
-/**
- * epic-deliver-lease-guard.js — preflight guards for `/deliver`
- * (Story #3482, Epic #3457).
- *
- * `/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 {
-  acquireLeaseFailClosed,
-  resolveOperatorFromCandidates,
-} from './lease-guard-shared.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 (via
- * the shared lease-guard kernel) so the value matches the bare login written
- * to a ticket's `assignees`. This surface's missing-handle policy is `'null'`
- * — `runPrepareGuards` fails closed on a null operator with deliver-specific
- * wording after the (cheap, local) checkout-safety guard has run.
- *
- * @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 } = {}) {
-  return resolveOperatorFromCandidates({
-    candidates: [asFlag, config?.github?.operatorHandle, gitUserEmail],
-  });
-}
-
-/**
- * Normalise the expected-branch argument into a non-empty list. `/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. ` +
-      `/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. /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}. /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 /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,
-}) {
-  return acquireLeaseFailClosed({
-    provider,
-    ticketId: epicId,
-    operator,
-    heartbeatAt,
-    steal,
-    config,
-    now,
-    renderRefusal: renderLeaseRefusal,
-  });
-}
-
-/**
- * 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 /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/context.js

@@ -1,163 +0,0 @@
-/**
- * context.js — Phase 3 of the epic-plan-decompose pipeline (Story #2466).
- *
- * Builds the authoring context (the Epic body — which carries the folded
- * Tech Spec sections and Acceptance Table per Story #4324 — plus
- * 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 { hasTechSpecContent } from '../../../epic-body-sections.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, maxTokenBudget, epicId } = {},
-) {
-  const base = renderDecomposerSystemPrompt({
-    maxTickets,
-    maxTokenBudget,
-    epicId,
-  });
-  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 fetchPlanningEpic(provider, epicId) {
-  const epic = await provider.getEpic(epicId);
-  if (!epic || !hasTechSpecContent(epic.body ?? '')) {
-    throw new Error(
-      `[Decomposer] Epic #${epicId} body carries no Tech Spec sections (no ## Delivery Slicing). Run the Epic Planner (Phase 7) first.`,
-    );
-  }
-  return { epic };
-}
-
-/**
- * Build the authoring context the host LLM (or the
- * `epic-plan-decompose-author` Skill) needs to produce the ticket JSON.
- *
- * The Epic body (ideation sections + folded Tech Spec sections +
- * Acceptance Table — the AC-ID source for wave-0 BDD scaffold tags) is
- * bounded by the planning-context budget (Epic #817 Story 9). Pass
- * `{ fullContext: true }` (CLI: `--full-context`) to restore the
- * unbounded full body.
- */
-export async function buildDecompositionContext(
-  epicId,
-  provider,
-  config = {},
-  opts = {},
-) {
-  const { epic } = await fetchPlanningEpic(provider, epicId);
-  const { planningRisk, reviewRouting } = await readPlanningDecision(
-    provider,
-    epicId,
-  );
-  const heuristics = resolveHeuristics(config);
-  const limits = getLimits(config);
-  const maxTickets = limits.maxTickets;
-  const maxTokenBudget = limits.maxTokenBudget;
-  const planningLimits = limits.planningContext;
-  const { fullContext = false } = opts;
-  const systemPrompt = buildDecomposerSystemPrompt(heuristics, {
-    maxTickets,
-    maxTokenBudget,
-    epicId,
-  });
-
-  const budgeted = applyBudget(
-    [{ path: `epic-${epic.id}.md`, content: epic.body ?? '' }],
-    planningLimits,
-    { fullContext },
-  );
-  const [epicItem] = budgeted.items;
-  return {
-    epic: { id: epic.id, title: epic.title },
-    // Story #4324 — the Epic body is the single planning document: it
-    // carries the ideation sections, the folded Tech Spec sections
-    // (## Delivery Slicing first), and the ## Acceptance Table the wave-0
-    // BDD scaffold reads its AC IDs from.
-    epicBody: projectBudgetedEntry(epicItem, epic, 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. Story #4162 also
-    // threads this value into the rendered systemPrompt above as a sizing
-    // input so the prompt itself names the budget.
-    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

@@ -1,140 +0,0 @@
-/**
- * creation.js — sub-issue link reconciliation, Epic label transitions,
- * the advisory ticket-cap warning, and the blocked-by dependency wiring
- * used by the reconciler-based persist flow (`persist.js`).
- *
- * Exports: `reconcileSubIssueLinks`, `setBlockedByDependencies`,
- * `setEpicLabel`, `warnTicketCapNearLimit`.
- *
- * @module lib/orchestration/epic-plan-decompose/phases/creation
- */
-
-import { applyBlockedByDependencies } from '../../../../providers/github/blocked-by-add.js';
-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.`,
-  );
-}
-
-/**
- * Translate each Story's `dependsOn` slug list into native GitHub "blocked
- * by" dependency edges. Best-effort and non-fatal: individual edge failures
- * are logged as warnings and do not abort the decompose phase.
- *
- * Requires the provider to expose `owner`, `repo`, `_gh`, and `getTicket`.
- * No-ops silently when any required surface is absent so callers remain
- * safe across provider stubs.
- *
- * @param {number} epicId
- * @param {import('../../../ITicketingProvider.js').ITicketingProvider} provider
- * @param {object} spec — the parsed YAML spec (has `.stories[*].dependsOn`).
- * @param {object} stateMapping — slug → `{ issueNumber }` from the reconciler state.
- */
-export async function setBlockedByDependencies(
-  epicId,
-  provider,
-  spec,
-  stateMapping,
-) {
-  const stories = Array.isArray(spec?.stories) ? spec.stories : [];
-  const hasDeps = stories.some(
-    (s) => Array.isArray(s.dependsOn) && s.dependsOn.length > 0,
-  );
-  if (!hasDeps) return;
-
-  if (
-    !provider?.owner ||
-    !provider?.repo ||
-    !provider?._gh ||
-    typeof provider.getTicket !== 'function'
-  ) {
-    Logger.warn(
-      `[Decomposer] setBlockedByDependencies: provider missing required surface (owner/repo/_gh/getTicket); skipping.`,
-    );
-    return;
-  }
-
-  Logger.info(
-    `[Decomposer] Setting native blocked-by dependency edges for Epic #${epicId}...`,
-  );
-
-  // Build a slug → issueNumber map from the reconciler state mapping.
-  const slugToIssueNumber = {};
-  for (const [slug, entry] of Object.entries(stateMapping ?? {})) {
-    if (typeof entry?.issueNumber === 'number') {
-      slugToIssueNumber[slug] = entry.issueNumber;
-    }
-  }
-
-  const result = await applyBlockedByDependencies({
-    stories,
-    slugToIssueNumber,
-    getTicket: (n) => provider.getTicket(n),
-    owner: provider.owner,
-    repo: provider.repo,
-    gh: provider._gh,
-  });
-
-  const { edgesAdded, edgesSkipped, edgesFailed, storiesProcessed } = result;
-  Logger.info(
-    `[Decomposer] blocked-by edges: ${edgesAdded} added, ${edgesSkipped} already present, ${edgesFailed} failed (${storiesProcessed} stories with deps processed).`,
-  );
-}
-
-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 Story decomposition before persisting; over-budget persistence requires --allow-over-budget.`,
-  );
-}

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

@@ -1,64 +0,0 @@
-/**
- * dag.js — Phase 2 of the epic-plan-decompose pipeline (Story #2466).
- *
- * Owns the deterministic DAG helpers used by the reconciler pipeline:
- *   - `resolveDependencies(ticket, slugMap)`
- *   - `orderTicketsForCreation(validated)` (topological sort of the
- *     Story set so dependency producers are created before consumers)
- *
- * Extracted verbatim from `epic-plan-decompose.js` so the named exports
- * (`resolveDependencies`, `orderTicketsForCreation`) that the
- * `tests/ticket-decomposer.test.js` suite imports keep their contract.
- *
- * @module lib/orchestration/epic-plan-decompose/phases/dag
- */
-
-export function resolveDependencies(ticket, slugMap) {
-  const resolved = [];
-  for (const dep of ticket.depends_on || []) {
-    const depId = slugMap.get(dep);
-    if (depId === undefined) {
-      // Unreachable through normal flow: validateAndNormalizeTickets
-      // already rejects unknown slugs and the topological sort guarantees
-      // creation order. A throw here turns a future regression (e.g.
-      // someone bypassing the validator) into a loud failure instead of a
-      // silently-dropped DAG edge.
-      throw new Error(
-        `[Decomposer] ${ticket.type.toUpperCase()} "${ticket.title}" (${ticket.slug}) depends on unresolved slug "${dep}". This indicates a planner bug or out-of-order ticket creation.`,
-      );
-    }
-    resolved.push(depId);
-  }
-  return resolved;
-}
-
-function topoSortGroup(group) {
-  const slugToTicket = new Map(group.map((t) => [t.slug, t]));
-  const visited = new Set();
-  const sorted = [];
-
-  function visit(t) {
-    if (visited.has(t.slug)) return;
-    visited.add(t.slug);
-    for (const dep of t.depends_on ?? []) {
-      const depTicket = slugToTicket.get(dep);
-      if (depTicket) visit(depTicket);
-    }
-    sorted.push(t);
-  }
-
-  for (const t of group) visit(t);
-  return sorted;
-}
-
-/**
- * Topologically sort the Story set so intra-set dep chains resolve
- * before their dependents are created. The 2-tier hierarchy has a
- * single ticket type (story) attached directly to the Epic, so there
- * is no parent-type ordering to interleave.
- */
-export function orderTicketsForCreation(validated) {
-  const result = [];
-  for (const t of topoSortGroup([...validated])) result.push(t);
-  return result;
-}