mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/orchestration/epic-runner/deliver-phases.js

@@ -1,50 +0,0 @@
-/**
- * deliver-phases.js — phase enum and ordering utility for `/deliver`.
- *
- * Story #1155 (Epic #1142, 5.40.0). Originally extracted from the
- * legacy class-based checkpoint module so the phase enum and close-tail
- * semantics live in a dedicated module that downstream tooling (the
- * contract test) can import without dragging the provider-coupled
- * checkpoint surface along. Story #2409 routes the runtime checkpoint
- * read/write surface through `../epic-run-state-store.js`; this file
- * remains the canonical home for the phase enum + validator.
- */
-
-/**
- * Ordered list of `/deliver` phases. The checkpoint's `phase` field
- * stores the **next phase to run**, so a mid-flight crash during
- * `code-review` resumes by reading `phase === 'code-review'` and re-
- * entering Phase D from the start.
- */
-export const DELIVER_PHASES = Object.freeze([
-  'prepare',
-  'wave-loop',
-  'close-validation',
-  'code-review',
-  'retro',
-  'finalize',
-]);
-
-/**
- * Pure: index of `phase` in `DELIVER_PHASES`. Returns `-1` for unknown
- * values (callers treat that as "start fresh"); `+Infinity` for the
- * terminal `'done'` sentinel.
- */
-export function phaseIndex(phase) {
-  if (phase === 'done') return Number.POSITIVE_INFINITY;
-  return DELIVER_PHASES.indexOf(phase);
-}
-
-/**
- * Pure: validate that `nextPhase` is a known phase tag (or the terminal
- * `'done'` sentinel). Throws on invalid input — exported so the
- * `setPhase` store function and downstream callers share one failure mode.
- */
-export function assertValidDeliverPhase(nextPhase) {
-  if (nextPhase === 'done') return;
-  if (phaseIndex(nextPhase) >= 0) return;
-  throw new Error(
-    `Invalid /deliver phase ${JSON.stringify(nextPhase)}. ` +
-      `Expected one of ${DELIVER_PHASES.join(', ')} or 'done'.`,
-  );
-}

package/.agents/scripts/lib/orchestration/epic-runner/phases/build-wave-dag.js

@@ -1,129 +0,0 @@
-/**
- * Build the wave DAG from the Epic's open child Stories.
- *
- * `getSubTickets` returns the **direct** children of a parent ticket via
- * native sub-issues + checklist links + body reverse-lookup. The
- * canonical 2-tier hierarchy is Epic → Story, so the Epic's direct
- * `type::story` children are the complete Story set.
- *
- * We additionally filter out closed Stories — `getSubTickets`'s reverse-
- * reference search can surface closed-as-obsolete tickets whose body
- * still names the Epic (e.g. a Story replaced during a planning
- * iteration). Dispatching against those would silently fan a sub-agent
- * out at pre-replan work.
- *
- * Throws if no open Stories are found.
- */
-
-import { computeWaves } from '../../../Graph.js';
-import { TYPE_LABELS } from '../../../label-constants.js';
-import { buildStoryAdjacency } from '../../../story-adjacency.js';
-import { WaveScheduler } from '../wave-scheduler.js';
-
-/**
- * Collect the Epic's direct `type::story` children and return the open
- * ones, deduped by id.
- *
- * Exported so `snapshot.js#discoverStoryIds` and `epic-deliver-preflight`
- * can share the same enumeration contract — the snapshot.end payload,
- * preflight Story count, and wave DAG input set must never disagree.
- */
-export async function discoverOpenStories({ epicId, provider }) {
-  const descendants = (await provider.getSubTickets(epicId)) ?? [];
-  const seen = new Set();
-  const stories = [];
-  for (const t of descendants) {
-    const labels = t.labels ?? [];
-    if (!labels.includes(TYPE_LABELS.STORY)) continue;
-    // Defense-in-depth: never enumerate a context spec ticket (Tech
-    // Spec / Acceptance Spec) as a deliverable Story even if it carries
-    // `type::story`. The `createTicket` factory no longer stamps context
-    // tickets that way, but a context ticket mislabelled out-of-band must
-    // still never reach a delivery wave (it has no `story-<id>` branch or
-    // acceptance contract to deliver against).
-    if (
-      labels.some((l) => typeof l === 'string' && l.startsWith('context::'))
-    ) {
-      continue;
-    }
-    const rawState = t.state ?? 'open';
-    const norm = typeof rawState === 'string' ? rawState.toLowerCase() : 'open';
-    if (norm !== 'open') continue;
-    const id = t.id ?? t.number;
-    if (id == null || seen.has(id)) continue;
-    seen.add(id);
-    stories.push(t);
-  }
-  return stories;
-}
-
-export async function runBuildWaveDagPhase(ctx, collaborators, state) {
-  const { epicId, provider } = ctx;
-  const bus = collaborators?.bus ?? null;
-  if (bus) {
-    await bus.emit('epic.plan.start', { epicId });
-  }
-  const stories = await discoverOpenStories({ epicId, provider });
-  if (!stories.length) {
-    throw new Error(`Epic #${epicId} has no child stories to dispatch.`);
-  }
-  const { adjacency, taskMap } = buildStoryDag(stories);
-  const waves = computeWaves(adjacency, taskMap);
-  const scheduler = new WaveScheduler(waves);
-  if (bus) {
-    // epic.plan.end carries the computed waves as the array-of-arrays
-    // shape declared by the schema. Each inner array is the storyIds
-    // dispatched together in that wave. `computeWaves` may return
-    // entries that are objects (when fed `taskMap`); we normalize to a
-    // simple numeric matrix here so the payload validates and replays
-    // off the ledger without coupling readers to internal types.
-    await bus.emit('epic.plan.end', {
-      waves: normalizeWavesForEmit(waves),
-    });
-  }
-  return { ...state, stories, waves, scheduler };
-}
-
-/**
- * Normalize the runner's wave representation into the
- * `Array<Array<integer>>` shape declared by
- * `.agents/schemas/lifecycle/epic.plan.end.schema.json`. `computeWaves`
- * returns waves of `taskMap` entries (objects with `id`); the ledger
- * needs only the IDs. Defensive number coercion mirrors the same id
- * extraction used in `buildStoryDag` above so emit and DAG stay
- * structurally aligned.
- */
-function normalizeWavesForEmit(waves) {
-  if (!Array.isArray(waves)) return [];
-  return waves.map((wave) => {
-    if (!Array.isArray(wave)) return [];
-    return wave
-      .map((entry) => {
-        if (entry == null) return null;
-        if (typeof entry === 'number') return entry;
-        const id = entry.id ?? entry.number ?? entry.storyId;
-        return id == null ? null : Number(id);
-      })
-      .filter((n) => Number.isInteger(n) && n > 0);
-  });
-}
-
-/**
- * Convert an ordered list of story tickets into the adjacency/taskMap shape
- * that `Graph.computeWaves()` expects.
- *
- * The adjacency comes from the shared story-level builder
- * (`lib/story-adjacency.js#buildStoryAdjacency`), which owns the
- * dependency-source ordering contract (body `blocked by` references via
- * `parseBlockedBy`, then explicit `dependencies[]`) and drops foreign
- * edges so the DAG stays closed over the scheduled set.
- */
-function buildStoryDag(stories) {
-  const adjacency = buildStoryAdjacency(stories);
-  const taskMap = new Map();
-  for (const s of stories) {
-    const id = Number(s.id ?? s.number);
-    taskMap.set(id, { ...s, id });
-  }
-  return { adjacency, taskMap };
-}

package/.agents/scripts/lib/orchestration/epic-runner/phases/snapshot.js

@@ -1,103 +0,0 @@
-/**
- * Epic snapshot phase — fetch Epic ticket and enforce the acceptance-spec
- * start gate.
- *
- * Auto-close is now the default for `/deliver` (the human PR-merge is
- * the gate); no per-Epic label snapshot is required.
- *
- * Acceptance-spec start gate (Story #4324): an Epic may be delivered when
- * *either* the operator has explicitly waived the acceptance requirement
- * via the `acceptance::n-a` label, *or* the Epic body carries the
- * `## Acceptance Table` managed section (the folded home of the retired
- * `context::acceptance-spec` ticket's AC-ID table). Presence is
- * sufficient — the reviewer's OK during /plan Phase 7 is the approval
- * signal. This still refuses to launch Epics that skipped the /plan
- * Phase 7 acceptance authoring step (or didn't waive), surfacing the gap
- * at delivery time rather than letting Story dispatch race ahead without
- * a spec at all.
- */
-
-import { hasEpicSection } from '../../../epic-body-sections.js';
-import { ACCEPTANCE_NA } from '../../../label-constants.js';
-import { discoverOpenStories } from './build-wave-dag.js';
-
-/**
- * Run the snapshot phase.
- *
- * Fetch the Epic ticket, assert the acceptance-spec start gate, and emit
- * `epic.snapshot.start` at entry and `epic.snapshot.end` at exit via the
- * lifecycle bus. After the Epic #2880 / Story #2898 hard cutover the bus
- * is the sole mutator of phase state — production wiring (see
- * `createEpicRunnerCollaborators`) always supplies a bus, and named
- * listeners on the bus (LabelTransitioner, StructuredCommentPoster, …)
- * own every state side effect. The phase return shape (`{ ...state, epic }`)
- * is the function's contract with the runner pipeline; it is not a parallel
- * state write.
- *
- * The `bus` parameter is still defensively typed as optional because unit
- * fixtures occasionally pass `{}` as the collaborator bag (e.g. the
- * acceptance-spec gate tests under `tests/epic-runner/`); those callers
- * skip the emit but still exercise the gate logic. Production cannot
- * reach the `!bus` branch.
- *
- * `epic.snapshot.end` carries the enumerated story IDs the Epic owns
- * (matching the schema at `.agents/schemas/lifecycle/epic.snapshot.end.schema.json`).
- * This makes the snapshot record self-describing on disk: a reader of
- * `temp/epic-<id>/lifecycle.ndjson` can recover the dispatch set without
- * re-querying the provider.
- */
-export async function runSnapshotPhase(ctx, collaborators, state) {
-  const { epicId, provider } = ctx;
-  const bus = collaborators?.bus ?? null;
-  if (bus) {
-    await bus.emit('epic.snapshot.start', { epicId });
-  }
-  const epic = await provider.getTicket(epicId);
-  assertAcceptanceSpecGate({ epic, epicId });
-  let storyIds = [];
-  if (bus) {
-    storyIds = await discoverStoryIds({ epicId, provider });
-    await bus.emit('epic.snapshot.end', { epicId, storyIds });
-  }
-  return { ...state, epic };
-}
-
-/**
- * Enumerate the Story IDs owned by an Epic. Delegates to
- * `discoverOpenStories` so the snapshot.end payload and the wave DAG
- * input set never disagree — both enumerate the Epic's direct Story
- * children and exclude closed reverse-referenced tickets.
- *
- * Returns a sorted array of positive integers (sort order makes the
- * ledger record deterministic across runs and platform iteration
- * quirks, which is what AC-3 / resume determinism depends on).
- */
-async function discoverStoryIds({ epicId, provider }) {
-  const stories = await discoverOpenStories({ epicId, provider });
-  const ids = stories
-    .map((t) => Number(t.id ?? t.number))
-    .filter((id) => Number.isInteger(id) && id > 0);
-  return [...new Set(ids)].sort((a, b) => a - b);
-}
-
-/**
- * Refuse to launch /deliver when the acceptance precondition has not been
- * satisfied. Throws a clear `Error` (per orchestration-error-handling
- * rule) so the `runAsCli` boundary maps it to `process.exit(1)` with the
- * operator-visible message intact.
- *
- * The gate checks section presence (or the waiver label) only.
- *
- * @param {{ epic: { labels?: string[], body?: string }, epicId: number }} args
- */
-function assertAcceptanceSpecGate({ epic, epicId }) {
-  const labels = epic?.labels ?? [];
-  if (labels.includes(ACCEPTANCE_NA)) return;
-
-  if (!hasEpicSection(epic?.body ?? '', 'acceptanceTable')) {
-    throw new Error(
-      `[epic-deliver] Epic #${epicId} cannot launch: the Epic body has no ## Acceptance Table section and the acceptance::n-a waiver label is absent. ` +
-        'Run /plan Phase 7 to author the acceptance table, or apply the acceptance::n-a label to the Epic to opt out.',
-    );
-  }
-}

package/.agents/scripts/lib/orchestration/epic-runner/progress-reporter/composition.js

@@ -1,267 +0,0 @@
-/**
- * progress-reporter/composition.js — body builders for the
- * `epic-run-progress` structured comment and the periodic ProgressReporter
- * snapshot.
- *
- * Extracted from the parent `progress-reporter.js` so the
- * structured-comment rendering surface is testable independently of the
- * orchestration shell (`ProgressReporter`) and the I/O webhook posters in
- * `transport.js`. Pure functions only — no provider calls, no clock reads
- * beyond the caller-supplied `now()`.
- *
- * `upsertEpicRunProgress` is the canonical body builder + persistence
- * surface for the rolled-up Epic-level table that lands on the Epic
- * ticket after every wave; the ProgressReporter class delegates its
- * per-poll `#render` / `#renderNotable` to the pure renderers below so
- * the same shape is generated either side of the boundary.
- */
-
-import { upsertStructuredComment } from '../../ticketing.js';
-import { EPIC_RUN_PROGRESS_TYPE, STATE_EMOJI } from './signals.js';
-
-/**
- * Truncate `s` to at most `n` characters, suffixing with a single ellipsis
- * (`…`) when the string was longer. Returns the empty string for any
- * falsy input so table cells never render `undefined`/`null`.
- */
-function truncate(s, n) {
-  if (!s) return '';
-  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
-}
-
-/**
- * Escape pipe characters so a value can be inlined into a markdown table
- * cell without breaking the column separators.
- */
-export function escapePipes(s) {
-  return String(s).replace(/\|/g, '\\|');
-}
-
-/**
- * Derive the high-level state classification for a single ticket. Reads
- * the canonical `agent::*` label set first, then falls back to the GitHub
- * `state` string for the closed-without-done case. Returns `'unknown'`
- * for any unrecognized shape so the renderer can flag unreadable rows in
- * the Notable section.
- */
-export function deriveState(ticket, AGENT_LABELS) {
-  if (!ticket) return 'unknown';
-  const labels = ticket.labels ?? [];
-  const state = (ticket.state ?? '').toString().toUpperCase();
-  if (state === 'CLOSED' || labels.includes(AGENT_LABELS.DONE)) return 'done';
-  if (labels.includes(AGENT_LABELS.BLOCKED)) return 'blocked';
-  if (labels.includes(AGENT_LABELS.EXECUTING)) return 'in-flight';
-  if (labels.includes(AGENT_LABELS.READY)) return 'queued';
-  return 'unknown';
-}
-
-/**
- * Declarative descriptor table that drives the Notable bullet block. Each
- * descriptor names a row state, the emoji prefix to render, and the
- * `label(count)` function that produces the count-aware human phrase (e.g.
- * "1 story blocked" vs "2 stories blocked"). Iteration order is the
- * canonical render order: blocked → in-flight → unknown, matching the
- * pre-refactor sequential filter walks so output stays byte-identical.
- */
-const STATE_NOTABLE_DESCRIPTORS = [
-  {
-    state: 'blocked',
-    emoji: STATE_EMOJI.blocked,
-    label: (n) => `${n} stor${n === 1 ? 'y' : 'ies'} blocked`,
-  },
-  {
-    state: 'in-flight',
-    emoji: STATE_EMOJI['in-flight'],
-    label: (n) => `${n} in flight`,
-  },
-  {
-    state: 'unknown',
-    emoji: STATE_EMOJI.unknown,
-    label: (n) => `${n} unreadable (token scope / network?)`,
-  },
-];
-
-/**
- * Single-pass grouping of `rows` keyed by the descriptor states. Returns a
- * Map<state, row[]> so callers can iterate descriptors and look up the
- * matching slice in O(1); states absent from `rows` get an empty array so
- * the renderer can skip them with a single `length` check.
- */
-function groupRowsByNotableState(rows) {
-  const groups = new Map(STATE_NOTABLE_DESCRIPTORS.map((d) => [d.state, []]));
-  for (const r of rows) {
-    const bucket = groups.get(r.state);
-    if (bucket) bucket.push(r);
-  }
-  return groups;
-}
-
-/**
- * Run a single detector against `rows`/`ctx`, swallowing any thrown or
- * rejected error so one misbehaving detector cannot kill the whole render
- * path. Failures are surfaced via `logger.warn` so operators still see the
- * signal; the bullet array is treated as empty on failure.
- */
-async function runDetector(detector, rows, ctx, logger) {
-  try {
-    const fn = typeof detector === 'function' ? detector : detector?.detect;
-    if (typeof fn !== 'function') return [];
-    const out = await fn.call(detector, rows, ctx);
-    return Array.isArray(out) ? out : [];
-  } catch (err) {
-    logger?.warn?.(`[ProgressReporter] detector failed: ${err.message}`);
-    return [];
-  }
-}
-
-/**
- * Render the **Notable** bullet block: blocked-story summary, in-flight
- * counts, unreadable rows, plus any detector bullets that were collected
- * from the caller. Detectors receive `(rows, ctx)` and may return either
- * an array of strings or a thenable resolving to one — the caller is
- * responsible for awaiting and trapping detector failures (we trap them
- * here to keep the render path non-fatal).
- *
- * The state-driven bullets are emitted from `STATE_NOTABLE_DESCRIPTORS`
- * via a single grouping pass, which keeps the cyclomatic surface flat as
- * new notable states are added.
- *
- * Returns the rendered block (without the leading `**Notable**` header so
- * the caller can place it inside a larger composition).
- */
-export async function renderNotable({ rows, detectors = [], wave, logger }) {
-  const items = [];
-  const groups = groupRowsByNotableState(rows);
-  for (const { state, emoji, label } of STATE_NOTABLE_DESCRIPTORS) {
-    const matched = groups.get(state);
-    if (!matched.length) continue;
-    const ids = matched.map((r) => `#${r.id}`).join(', ');
-    items.push(`- ${emoji} ${label(matched.length)}: ${ids}`);
-  }
-
-  const ctx = { wave };
-  const detectorResults = await Promise.all(
-    (detectors ?? []).map((detector) =>
-      runDetector(detector, rows, ctx, logger),
-    ),
-  );
-  for (const bullets of detectorResults) {
-    for (const b of bullets) items.push(b.startsWith('- ') ? b : `- ${b}`);
-  }
-
-  if (!items.length) items.push('- (none)');
-  return items.join('\n');
-}
-
-/**
- * Render and upsert the rolled-up `epic-run-progress` comment on the Epic.
- *
- * Called by `/deliver`'s per-Story status recorder
- * (`epic-execute-record-wave.js`) after each recorder beat. Story #4155
- * (Epic #4151) — the Epic `/deliver` runtime cut over from the wave-batch
- * scheduler to the continuous ready-set core, so the rollup is a **flat
- * per-Story table** keyed by the checkpoint's `stories` status map, not a
- * wave-grouped table. There is no `currentWave` / `totalWaves` / `waves[]`
- * in the payload any more.
- *
- * The payload schema:
- *
- *   {
- *     "kind": "epic-run-progress",
- *     "epicId": <number>,
- *     "stories": [ { id, title?, state, blockerCommentId? } ],
- *     "startedAt"?: "<iso8601>",
- *     "updatedAt": "<iso8601>"
- *   }
- *
- * The function does not re-derive Story state from labels — it trusts the
- * `stories` map supplied by the caller (the checkpoint's recorded per-Story
- * statuses).
- *
- * @param {{
- *   provider: import('../../../ITicketingProvider.js').ITicketingProvider,
- *   epicId: number,
- *   stories: Record<string, { status?: string, title?: string,
- *                             blockerCommentId?: string }>,
- *   startedAt?: string,
- *   now?: () => Date,
- * }} args
- * @returns {Promise<{ body: string, payload: object }>} the rendered body
- *   and payload that were upserted onto the Epic.
- */
-export async function upsertEpicRunProgress({
-  provider,
-  epicId,
-  stories,
-  startedAt,
-  now = () => new Date(),
-} = {}) {
-  if (!provider || typeof provider.postComment !== 'function') {
-    throw new TypeError(
-      'upsertEpicRunProgress requires a provider with postComment',
-    );
-  }
-  const epicIdNum = Number(epicId);
-  if (!Number.isInteger(epicIdNum) || epicIdNum <= 0) {
-    throw new TypeError('upsertEpicRunProgress requires a numeric epicId');
-  }
-  const statusMap = stories && typeof stories === 'object' ? stories : {};
-
-  const updatedAt = now().toISOString();
-  const rows = Object.entries(statusMap)
-    .map(([key, rec]) => {
-      const id = Number(key);
-      const state = String(rec?.status ?? 'pending');
-      const row = { id, title: String(rec?.title ?? ''), state };
-      if (rec?.blockerCommentId != null) {
-        row.blockerCommentId = String(rec.blockerCommentId);
-      }
-      return row;
-    })
-    .filter((r) => Number.isInteger(r.id) && r.id > 0)
-    .sort((a, b) => a.id - b.id);
-
-  const payload = {
-    kind: EPIC_RUN_PROGRESS_TYPE,
-    epicId: epicIdNum,
-    stories: rows,
-    updatedAt,
-  };
-  if (typeof startedAt === 'string' && startedAt) {
-    payload.startedAt = startedAt;
-  }
-
-  const totalStories = rows.length;
-  const doneStories = rows.filter((s) => s.state === 'done').length;
-  const header = `### 📊 Epic Progress — ${doneStories}/${totalStories} stories done`;
-
-  const tableLines = ['| ID | State | Title |', '|---|---|---|'];
-  if (rows.length === 0) {
-    tableLines.push('| — | _(no stories yet)_ | — |');
-  } else {
-    for (const s of rows) {
-      const emoji = STATE_EMOJI[s.state] ?? '';
-      const title = escapePipes(truncate(s.title, 60));
-      tableLines.push(`| #${s.id} | ${emoji} ${s.state} | ${title} |`);
-    }
-  }
-
-  const body = [
-    header,
-    '',
-    tableLines.join('\n'),
-    '',
-    '```json',
-    JSON.stringify(payload, null, 2),
-    '```',
-  ].join('\n');
-
-  await upsertStructuredComment(
-    provider,
-    epicIdNum,
-    EPIC_RUN_PROGRESS_TYPE,
-    body,
-  );
-
-  return { body, payload };
-}