mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/deliver-route.js

@@ -1,173 +0,0 @@
-/**
- * lib/orchestration/deliver-route.js — the deliver-side reader for the
- * plan-time single-delivery seam (Epic #4475, M4-A).
- *
- * The plan path already ships the seam inert (Epic #4474): the risk verdict's
- * `deliveryShape`, the `delivery::single` label, and the
- * `epic-plan-state.decompose = { ticketCount: 0, shape: "single" }`
- * checkpoint. Nothing on the deliver side read them — until this module. It
- * folds those two markers (plus the global kill-switch) into a single
- * delivery-route verdict for `/deliver`.
- *
- * Pure and total — inputs in, verdict out. No GitHub calls, no I/O, no
- * throws. It mirrors how `review-depth.js#resolveDepth` and
- * `epic-audit-prepare.js` read `planningRisk` / `decompose` off the
- * `epic-plan-state` checkpoint: the caller fetches the Epic labels + the
- * checkpoint, then hands both here.
- *
- * ── Routing precedence (highest wins) ──────────────────────────────────
- *   1. Kill-switch. `delivery.routing.singleDelivery === false` forces
- *      `fan-out` for EVERY Epic, even a single-labelled one — the instant
- *      global revert (`lib/config/delivery-routing.js`). Overrides all.
- *   2. Single marker. The `delivery::single` label (primary) OR
- *      `checkpoint.decompose.shape === "single"` (secondary) → `single`.
- *   3. Wide-DAG advisory. A fan-out-shaped Epic whose ready-width > 1 is
- *      genuine parallelism → `fan-out`. Deliver-time width only ADVISES —
- *      it never reroutes a single-marked Epic (that would orphan a Story
- *      tree that does not exist; re-route = re-plan).
- *   4. Legacy / no marker → `fan-out` (safe backward-compat: a legacy Epic
- *      has an authored Story tree the fan-out engine consumes).
- *
- * BEHAVIOR-PRESERVING in M4-A: the router consumes a `single` verdict via a
- * stub that continues at `deliver-epic.md` (fan-out), so no `/deliver`
- * observably changes until M4-B lands `deliver-epic-single.md`.
- *
- * @typedef {'single'|'fan-out'} DeliveryRoute
- */
-
-import { getDeliveryRouting } from '../config/delivery-routing.js';
-
-/** The canonical single-delivery routing marker label. */
-export const DELIVERY_SINGLE_LABEL = 'delivery::single';
-
-/**
- * True when the Epic carries the `delivery::single` routing label. Tolerant
- * of the two label shapes callers hold: an array of label-name strings, or an
- * array of `{ name }` objects (the GitHub REST label shape).
- *
- * @param {{ labels?: Array<string | { name?: string }> } | null | undefined} epic
- * @returns {boolean}
- */
-function hasSingleLabel(epic) {
-  const labels = Array.isArray(epic?.labels) ? epic.labels : [];
-  return labels.some((l) => {
-    const name = typeof l === 'string' ? l : l?.name;
-    return name === DELIVERY_SINGLE_LABEL;
-  });
-}
-
-/**
- * True when the plan-state checkpoint's `decompose.shape` is the deliberate
- * single shape. `plan-persist.js` writes `decompose = { ticketCount: 0,
- * shape: "single" }` for a spec-only plan; every other value (including a
- * legacy checkpoint with no `shape` field) is not-single.
- *
- * @param {{ decompose?: { shape?: string } } | null | undefined} checkpoint
- * @returns {boolean}
- */
-function hasSingleDecomposeShape(checkpoint) {
-  return checkpoint?.decompose?.shape === 'single';
-}
-
-/**
- * Resolve the delivery route for one Epic from its labels, its plan-state
- * checkpoint, and the resolved config. See the module header for the full
- * precedence. Pure — never throws; malformed / absent inputs degrade to the
- * safe `fan-out` default.
- *
- * @param {{ labels?: Array<string | { name?: string }> } | null | undefined} epic
- *   The Epic ticket snapshot (only `labels` is read here).
- * @param {{ decompose?: { shape?: string } } | null | undefined} checkpoint
- *   The `epic-plan-state` structured comment, parsed (or `null` on a legacy
- *   Epic that predates the checkpoint — treated as no marker).
- * @param {object | null | undefined} config
- *   The resolved config; `delivery.routing.singleDelivery` is the kill-switch.
- * @returns {{ route: DeliveryRoute, reason: string, singleDeliveryEnabled: boolean }}
- */
-export function resolveEpicDeliveryRoute(epic, checkpoint, config) {
-  const { singleDelivery } = getDeliveryRouting(config);
-
-  // 1. Kill-switch — overrides all. A `false` value forces fan-out even for
-  //    an Epic the planner marked single (the instant global revert).
-  if (singleDelivery === false) {
-    return {
-      route: 'fan-out',
-      reason:
-        'kill-switch: delivery.routing.singleDelivery=false forces fan-out for every Epic',
-      singleDeliveryEnabled: false,
-    };
-  }
-
-  // 2. Single marker — label (primary) OR checkpoint decompose shape
-  //    (secondary). Either alone routes single.
-  const labelled = hasSingleLabel(epic);
-  const shaped = hasSingleDecomposeShape(checkpoint);
-  if (labelled || shaped) {
-    const via =
-      labelled && shaped
-        ? `${DELIVERY_SINGLE_LABEL} label + decompose.shape="single"`
-        : labelled
-          ? `${DELIVERY_SINGLE_LABEL} label`
-          : 'decompose.shape="single"';
-    return {
-      route: 'single',
-      reason: `single marker present (${via})`,
-      singleDeliveryEnabled: true,
-    };
-  }
-
-  // 3/4. No single marker → fan-out (a wide DAG or a legacy Story tree; the
-  //      deliver-time width only advises and never reroutes here).
-  return {
-    route: 'fan-out',
-    reason: 'no single marker — fan-out (legacy Story tree or wide DAG)',
-    singleDeliveryEnabled: true,
-  };
-}
-
-/**
- * Compute the ready-width of a delivery plan — the count of work units that
- * could dispatch on the first beat. It is the mechanical parallelism signal
- * the planner uses at plan time to mark a genuinely-wide Epic `fan-out`, and
- * that `/deliver` may surface as an advisory at deliver time (it never
- * reroutes — see the module header).
- *
- * Accepts either input shape the framework already produces:
- *   - Delivery-Slicing rows — `[{ independent: boolean }, …]` from
- *     `parseDeliverySlicingTable`. A serial chain (every row
- *     `Independent: No`, or a lone independent slice) has width 1; two or
- *     more independent slices yield a width equal to that independent count
- *     (> 1) — genuine parallelism.
- *   - A wave DAG — `[[…], […], …]` (the array-of-waves `state.waves` shape
- *     `runBuildWaveDagPhase` produces). The width is the largest wave — the
- *     most Stories ready to dispatch on a single beat.
- *
- * Pure and total: an empty / malformed / unrecognized input degrades to
- * width 1 (the safe "not wide" signal). Never throws.
- *
- * @param {Array<{ independent?: boolean }> | Array<Array<unknown>> | null | undefined} deliverySlicingRowsOrDag
- * @returns {number} an integer ≥ 1.
- */
-export function computeReadyWidth(deliverySlicingRowsOrDag) {
-  const input = deliverySlicingRowsOrDag;
-  if (!Array.isArray(input) || input.length === 0) return 1;
-
-  // Wave-DAG shape: an array whose entries are themselves arrays.
-  if (input.every((entry) => Array.isArray(entry))) {
-    let widest = 1;
-    for (const wave of input) {
-      if (wave.length > widest) widest = wave.length;
-    }
-    return widest;
-  }
-
-  // Delivery-Slicing rows: entries are `{ independent }` records.
-  const independentCount = input.reduce(
-    (acc, row) =>
-      row && typeof row === 'object' && row.independent === true
-        ? acc + 1
-        : acc,
-    0,
-  );
-  return independentCount >= 2 ? independentCount : 1;
-}

package/.agents/scripts/lib/orchestration/dispatch-engine.js

@@ -1,134 +0,0 @@
-/**
- * lib/orchestration/dispatch-engine.js — Core Dispatch Engine (SDK coordinator)
- *
- * Thin facade composing:
- *   - `dispatch-pipeline.js` — internal resolve/fetch/reconcile/graph helpers
- *
- * Every Epic is 2-tier (Epic → Story); `dispatch()` computes a
- * Story-level wave plan and emits a 2-tier manifest. The legacy Task-tier
- * dispatch runtime (Task fetcher, single-Story executor, the per-Task
- * wave fan-out, and the Epic-completion detector) was removed in Epic
- * #3163.
- */
-
-import { PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
-import { ConflictingTypeLabelsError } from '../errors/index.js';
-import { ensureLocalBranch } from '../git-branch-lifecycle.js';
-import { Logger } from '../Logger.js';
-import { TYPE_LABELS } from '../label-constants.js';
-import { createProvider } from '../provider-factory.js';
-import {
-  buildStoryDispatchGraph,
-  fetchEpicContext,
-  isTwoTierDispatch,
-  resolveDispatchContext,
-} from './dispatch-pipeline.js';
-import { buildManifest } from './manifest-builder.js';
-import { STATE_LABELS } from './ticketing.js';
-
-export const AGENT_DONE_LABEL = STATE_LABELS.DONE;
-
-/* node:coverage ignore next */
-export function ensureBranch(branchName, baseBranch) {
-  ensureLocalBranch(branchName, baseBranch, PROJECT_ROOT, {
-    log: (msg) => Logger.info(msg),
-  });
-}
-
-/**
- * Resolve a single ticket ID, detect its type, and delegate to the
- * appropriate execution pipeline. Single entry point shared by the CLI
- * wrapper and the MCP `dispatch_wave` tool.
- */
-export async function resolveAndDispatch(options) {
-  const { ticketId, dryRun = false } = options;
-  const config = resolveConfig();
-  const provider = options.provider ?? createProvider(config);
-
-  const ticket = await provider.getTicket(ticketId);
-  const labels = ticket.labels || [];
-
-  const typeLabels = labels.filter((l) => l.startsWith('type::'));
-  if (typeLabels.length > 1) {
-    throw new ConflictingTypeLabelsError(
-      `Ticket #${ticketId} has conflicting type labels: ${typeLabels.join(', ')}. Exactly one type::* label is required.`,
-    );
-  }
-
-  const isStory = labels.includes(TYPE_LABELS.STORY);
-  const isEpic = labels.includes(TYPE_LABELS.EPIC);
-
-  if (isStory) {
-    throw new Error(
-      `[Dispatcher] Ticket #${ticketId} is a **Story**. Stories are dispatched ` +
-        'through the Story delivery path, not directly via the dispatcher. ' +
-        `Run \`/deliver ${ticketId}\` to execute this Story, ` +
-        `or dispatch its parent Epic with \`/deliver #<epicId>\`.`,
-    );
-  }
-
-  if (isEpic) {
-    return dispatch({ epicId: ticketId, dryRun, provider });
-  }
-
-  const typeLabel = labels.find((l) => l.startsWith('type::')) || 'unknown';
-  throw new Error(
-    `[Dispatcher] Ticket #${ticketId} has type "${typeLabel.replace('type::', '')}". ` +
-      `Only "epic" or "story" tickets can be dispatched. ` +
-      `Please ensure the ticket is correctly categorized before execution.`,
-  );
-}
-
-/**
- * Main dispatcher. Orchestrates one dispatch cycle for an Epic.
- * Primary public export of the orchestration SDK.
- */
-export async function dispatch(options) {
-  const ctx = resolveDispatchContext(options, ensureBranch);
-  const { epicId, dryRun } = ctx;
-
-  const fetched = await fetchEpicContext(ctx);
-
-  // Every Epic is 2-tier (Epic → Story). Compute Story-level
-  // waves directly from the Story tickets and emit a 2-tier-shaped
-  // manifest with `waves[].stories[]` so downstream consumers (manifest
-  // renderer, /deliver wave planner) see the correct execution plan.
-  // Per-Story execution is owned by `/deliver` (story-init →
-  // story-close), not by this dispatcher.
-  if (isTwoTierDispatch(fetched.allTickets)) {
-    Logger.info(
-      'Detected 2-tier hierarchy — computing Story-level execution waves.',
-    );
-    const { allWaves: storyWaves } = buildStoryDispatchGraph(
-      fetched.allTickets,
-    );
-    return buildManifest({
-      epicId,
-      epic: fetched.epic,
-      tasks: [],
-      allTickets: fetched.allTickets,
-      waves: storyWaves,
-      dispatched: [],
-      dryRun,
-      hierarchy: '2-tier',
-    });
-  }
-
-  // No Story tickets under the Epic — throw loudly rather than emit an
-  // empty manifest, matching the wave-loop's behavior (build-wave-dag.js
-  // throws the same message shape on this input). A silently-empty
-  // manifest masks a pre-cutover Epic whose children are legacy Features.
-  const typedChildren = (fetched.allTickets ?? [])
-    .map((t) => (t.labels ?? []).find((l) => l.startsWith('type::')))
-    .filter(Boolean);
-  const legacyHint =
-    typedChildren.length > 0
-      ? ` Found ${typedChildren.length} non-Story child ticket(s) ` +
-        `(${[...new Set(typedChildren)].join(', ')}) — this Epic looks ` +
-        `pre-cutover (legacy Feature children) and needs migration to the ` +
-        `2-tier (Epic → Story) hierarchy before dispatch.`
-      : '';
-  throw new Error(
-    `Epic #${epicId} has no child stories to dispatch.${legacyHint}`,
-  );
-}

package/.agents/scripts/lib/orchestration/dispatch-pipeline.js

@@ -1,183 +0,0 @@
-/**
- * dispatch-pipeline.js
- *
- * Internal pipeline helpers composed by `dispatch-engine.js::dispatch()`.
- * Keeping these out of the coordinator keeps the public entry point compact
- * and focused on the 2-tier flow: resolve → fetch → Story-graph.
- */
-
-import { PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
-import { getEpicBranch } from '../git-utils.js';
-import { Logger } from '../Logger.js';
-import { TYPE_LABELS } from '../label-constants.js';
-import { createProvider } from '../provider-factory.js';
-import { buildStoryAdjacency } from '../story-adjacency.js';
-import { WorktreeManager } from '../worktree-manager.js';
-import { computeStoryWaves } from './dependency-analyzer.js';
-
-/**
- * Runtime context for a single dispatch cycle.
- *
- * Produced by {@link resolveDispatchContext} and consumed by every pipeline
- * stage (fetch → graph → scaffold → GC → dispatch). All fields
- * are resolved once up-front so downstream helpers can stay free of
- * configuration look-ups.
- *
- * @typedef {object} DispatchContext
- * @property {number} epicId                                  Epic ticket number under dispatch.
- * @property {boolean} dryRun                                 When true, mutating side-effects are skipped.
- * @property {object} config                                  Resolved canonical `.agentrc.json` (with `project`, `github`, `planning`, `delivery` blocks).
- * @property {import('../ITicketingProvider.js').ITicketingProvider} provider  Ticketing provider (may come from cache).
- * @property {import('../worktree-manager.js').WorktreeManager | undefined} worktreeManager  Optional worktree manager (only when isolation is enabled and not dry-run).
- * @property {string} baseBranch                              Trunk branch the Epic branches from (default `main`).
- * @property {string} epicBranch                              Epic branch name (`epic/<epicId>`).
- * @property {(branchName: string, baseBranch: string) => void} ensureBranch  Caller-supplied branch-creation helper.
- */
-
-/**
- * The output of {@link fetchEpicContext}.
- *
- * @typedef {object} FetchedEpic
- * @property {object} epic                 The Epic ticket record.
- * @property {object[]} allTickets         Every ticket under the Epic (stories + health).
- * @property {Map<number, object>} allTicketsById  Index of `allTickets` by ticket id.
- */
-
-/**
- * Resolve the runtime context for a dispatch: canonical config, provider, adapter,
- * worktree manager, base/epic branch names, and the `ensureBranch` bound
- * helper supplied by the caller.
- *
- * @param {object} options                                    Dispatch entry options.
- * @param {number} options.epicId                             Epic ticket number.
- * @param {boolean} [options.dryRun=false]                    When true, skip branch creation and worktree setup.
- * @param {import('../ITicketingProvider.js').ITicketingProvider} [options.provider]  Pre-constructed provider (overrides factory).
- * @param {import('../worktree-manager.js').WorktreeManager} [options.worktreeManager]  Pre-constructed worktree manager.
- * @param {(branchName: string, baseBranch: string) => void} ensureBranch  Branch-creation helper bound by caller (keeps engine ↔ git-lifecycle coupling at the edge).
- * @returns {DispatchContext}                                 Fully resolved dispatch context.
- */
-export function resolveDispatchContext(options, ensureBranch) {
-  const { epicId, dryRun = false } = options;
-
-  const config = resolveConfig();
-  const provider = options.provider ?? createProvider(config);
-
-  const wtConfig = config?.delivery?.worktreeIsolation;
-  let worktreeManager = options.worktreeManager;
-  if (!worktreeManager && wtConfig?.enabled && !dryRun) {
-    worktreeManager = new WorktreeManager({
-      repoRoot: PROJECT_ROOT,
-      config: wtConfig,
-    });
-  }
-
-  return {
-    epicId,
-    dryRun,
-    config,
-    provider,
-    worktreeManager,
-    baseBranch: config?.project?.baseBranch ?? 'main',
-    epicBranch: getEpicBranch(epicId),
-    ensureBranch,
-  };
-}
-
-/**
- * Fetch Epic + all tickets and prime the provider cache.
- *
- * @param {DispatchContext} ctx  Dispatch context.
- * @returns {Promise<FetchedEpic>}  Epic + ticket graph.
- */
-export async function fetchEpicContext(ctx) {
-  const { provider, epicId } = ctx;
-
-  Logger.info(`\nFetching Epic #${epicId}...`);
-  const epic = await provider.getEpic(epicId);
-
-  Logger.info(`Fetching all tickets under Epic #${epicId}...`);
-  const allTickets = await provider.getTickets(epicId);
-  const allTicketsById = new Map(allTickets.map((t) => [t.id, t]));
-
-  provider.primeTicketCache(allTickets);
-
-  return { epic, allTickets, allTicketsById };
-}
-
-/**
- * Detect 2-tier hierarchy from the fetched ticket graph. After Epic #3163's
- * hard cutover deleted the `type::task` ticket layer, shape selection is
- * purely structural: any Epic carrying at least one `type::story` ticket
- * resolves to 2-tier.
- *
- * @param {object[]} allTickets
- * @returns {boolean}
- */
-export function isTwoTierDispatch(allTickets) {
-  if (!Array.isArray(allTickets) || allTickets.length === 0) return false;
-  return allTickets.some((t) =>
-    (t.labelSet ?? new Set(t.labels ?? [])).has(TYPE_LABELS.STORY),
-  );
-}
-
-/**
- * Build the Story-level dispatch graph for a 2-tier Epic. Reads story
- * tickets from `allTickets`, parses cross-Story `blocked by` references
- * from each Story body (also honoring an optional `dependencies[]`
- * field set by fixture providers), and computes wave indices via
- * {@link computeStoryWaves}.
- *
- * The returned `allWaves` is an array of Story-ticket arrays, ordered by
- * wave index. `storyMap` indexes the same Story tickets by id for downstream
- * lookups (mirrors the `taskMap` returned by {@link buildDispatchGraph}).
- *
- * Stories with no resolvable wave (cycle pre-filter, missing in groups)
- * are placed in their own trailing wave so they remain visible in the
- * manifest output.
- *
- * @param {object[]} allTickets  Fetched ticket graph (Epic + Stories).
- * @returns {{ allWaves: object[][], storyMap: Map<number, object> }}
- * @throws {Error} When the Story dependency graph contains a cycle.
- */
-export function buildStoryDispatchGraph(allTickets) {
-  const stories = (allTickets ?? []).filter((t) =>
-    (t.labelSet ?? new Set(t.labels ?? [])).has(TYPE_LABELS.STORY),
-  );
-  const storyMap = new Map(stories.map((s) => [s.id, s]));
-
-  // Shared story-level adjacency builder (lib/story-adjacency.js) owns the
-  // dependency-source ordering contract: body `blocked by` references via
-  // `parseBlockedBy`, then explicit `dependencies[]`, foreign edges dropped.
-  const explicitDeps = buildStoryAdjacency(stories);
-
-  // computeStoryWaves expects a Map<storyId, { tasks: [] }>; with no Tasks
-  // present, only explicitDeps + focus-area rollup (no-op for empty
-  // task lists) drive wave assignment.
-  const storyGroups = new Map(
-    stories.map((s) => [s.id, { storyId: s.id, tasks: [] }]),
-  );
-  const waveAssignment = computeStoryWaves(storyGroups, explicitDeps);
-
-  // Bucket stories by wave index. `computeStoryWaves` returns -1 for any
-  // story it could not place; route those into a trailing bucket so they
-  // still surface in the manifest.
-  const byWave = new Map();
-  let maxWave = -1;
-  for (const story of stories) {
-    const wave = waveAssignment.get(story.id) ?? -1;
-    if (wave > maxWave) maxWave = wave;
-    if (!byWave.has(wave)) byWave.set(wave, []);
-    byWave.get(wave).push(story);
-  }
-
-  const allWaves = [];
-  for (let i = 0; i <= maxWave; i++) {
-    if (byWave.has(i)) allWaves.push(byWave.get(i));
-  }
-  if (byWave.has(-1)) allWaves.push(byWave.get(-1));
-
-  Logger.info(
-    `Computed ${allWaves.length} Story-level execution wave(s) (2-tier).`,
-  );
-  return { allWaves, storyMap };
-}