mandrel 1.57.0

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

@@ -0,0 +1,217 @@
+/**
+ * progress-reporter/signals.js — parsing and aggregation helpers for the
+ * `story-run-progress` and `phase-timings` structured comments.
+ *
+ * Extracted from the parent `progress-reporter.js` so the aggregator
+ * surface (phase percentile rollups, story-run-progress parsing) is
+ * testable independently of the comment composition (`composition.js`)
+ * and webhook transport (`transport.js`). Pure functions only — no
+ * provider calls, no I/O — which makes this the natural home for the
+ * shared state lookup tables (`PHASE_TO_STATE`, `PHASE_ORDER`,
+ * `STATE_EMOJI`) and the structured-comment kind constants.
+ */
+
+import { parseFencedJsonComment } from '../../structured-comment-parser.js';
+
+/**
+ * Structured-comment kind for the rolled-up Epic-level progress
+ * comment. Persisted via `composition.upsertEpicRunProgress` and read
+ * back by tests + reconcilers.
+ */
+export const EPIC_RUN_PROGRESS_TYPE = 'epic-run-progress';
+
+/**
+ * Structured-comment kind for the per-Story phase-timings summary
+ * posted by `story-close.js`. Read back by the ProgressReporter so the
+ * Epic-level snapshot can aggregate median/p95 across waves.
+ */
+export const PHASE_TIMINGS_TYPE = 'phase-timings';
+
+/**
+ * Structured-comment kind for the per-Story run-progress snapshot that
+ * `/story-deliver` upserts on every Task transition. Read by
+ * ProgressReporter so the Epic-level table reflects sub-agent state in
+ * near-real time instead of label-derived classifications.
+ */
+export const STORY_RUN_PROGRESS_TYPE = 'story-run-progress';
+
+/**
+ * Phase → high-level state classification. Lookup table flattens the
+ * previous switch so cyclomatic complexity stays at 1 (one branch in the
+ * `??` fallback) rather than 6 — keeps the CRAP score floor-bound under
+ * coverage variance.
+ */
+export const PHASE_TO_STATE = {
+  done: 'done',
+  blocked: 'blocked',
+  implementing: 'in-flight',
+  closing: 'in-flight',
+  init: 'queued',
+};
+
+/**
+ * Fixed ordering for the rendered phase-timings table. Matches the enum
+ * in lib/util/phase-timer.js so rows line up with how operators think
+ * about the story lifecycle rather than re-sorting by alphabet or
+ * frequency.
+ */
+export const PHASE_ORDER = [
+  'worktree-create',
+  'bootstrap',
+  'install',
+  'implement',
+  'lint',
+  'test',
+  'close',
+  'api-sync',
+];
+
+/**
+ * Emoji prefix per high-level state. Shared between the per-poll table
+ * (`composition.renderProgressTable`) and the rolled-up Epic table
+ * (`composition.upsertEpicRunProgress`) so operators see the same icon
+ * in both surfaces.
+ */
+export const STATE_EMOJI = {
+  done: '✅',
+  blocked: '🚧',
+  'in-flight': '🔧',
+  queued: '⏳',
+  unknown: '❓',
+};
+
+/**
+ * Map a `story-run-progress` phase to the high-level state label used
+ * by the rendered tables. Returns `'unknown'` for any phase value that
+ * isn't in the lookup table so an unexpected phase surfaces as an
+ * unreadable row rather than a crash.
+ */
+export function phaseToState(phase) {
+  return PHASE_TO_STATE[phase] ?? 'unknown';
+}
+
+/**
+ * Parse a `story-run-progress` structured comment posted by `/story-deliver`.
+ * Returns `null` for any malformed body — the caller falls back to the
+ * ticket-label state derivation in that case.
+ *
+ * Expected payload shape (JSON inside a fenced json codeblock):
+ *   {
+ *     storyId: number,
+ *     branch?: string,
+ *     phase: 'init'|'implementing'|'closing'|'blocked'|'done',
+ *     tasks?: [{ id, title?, state, commitSha? }],
+ *     title?: string,
+ *     updatedAt?: string,
+ *   }
+ */
+export function parseStoryRunProgressComment(comment) {
+  const payload = parseFencedJsonComment(comment);
+  if (!payload || typeof payload !== 'object') return null;
+  const phase = typeof payload.phase === 'string' ? payload.phase : undefined;
+  const tasks = Array.isArray(payload.tasks) ? payload.tasks : [];
+  const tasksTotal = tasks.length;
+  const tasksDone = tasks.filter((t) => t && t.state === 'done').length;
+  return {
+    storyId: Number(payload.storyId),
+    title: typeof payload.title === 'string' ? payload.title : '',
+    phase,
+    state: phaseToState(phase),
+    tasksDone,
+    tasksTotal,
+  };
+}
+
+/**
+ * Extract the `{ phases, ... }` payload from a `phase-timings` structured
+ * comment. Comment body is the fenced-JSON format produced by
+ * `renderPhaseTimingsCommentBody` in story-close. Returns `null`
+ * for any parse failure — the caller treats that as "no summary
+ * available" without erroring out progress rendering.
+ */
+export function parsePhaseTimingsComment(comment) {
+  const payload = parseFencedJsonComment(comment);
+  if (!payload || typeof payload !== 'object') return null;
+  if (!Array.isArray(payload.phases)) return null;
+  return {
+    storyId: Number(payload.storyId),
+    totalMs: Number(payload.totalMs) || 0,
+    phases: payload.phases
+      .filter(
+        (p) =>
+          p &&
+          typeof p.name === 'string' &&
+          Number.isFinite(Number(p.elapsedMs)),
+      )
+      .map((p) => ({ name: p.name, elapsedMs: Number(p.elapsedMs) })),
+  };
+}
+
+/**
+ * Aggregate a list of `phase-timings` summaries into per-phase median,
+ * p95, and sample count. Returns phases ordered by the canonical
+ * `PHASE_ORDER` so the rendered table always has the same row sequence —
+ * operators should never have to hunt for the `install` row.
+ */
+export function aggregatePhaseTimings(summaries) {
+  const buckets = new Map();
+  for (const s of summaries) {
+    if (!s || !Array.isArray(s.phases)) continue;
+    for (const p of s.phases) {
+      if (!buckets.has(p.name)) buckets.set(p.name, []);
+      buckets.get(p.name).push(p.elapsedMs);
+    }
+  }
+  const rows = [];
+  for (const name of PHASE_ORDER) {
+    const samples = buckets.get(name);
+    if (!samples || samples.length === 0) continue;
+    rows.push({
+      name,
+      median: percentile(samples, 0.5),
+      p95: percentile(samples, 0.95),
+      n: samples.length,
+    });
+  }
+  // Include any unexpected phase names at the tail so a future enum
+  // addition surfaces in the table instead of being silently dropped.
+  for (const [name, samples] of buckets.entries()) {
+    if (PHASE_ORDER.includes(name)) continue;
+    rows.push({
+      name,
+      median: percentile(samples, 0.5),
+      p95: percentile(samples, 0.95),
+      n: samples.length,
+    });
+  }
+  return rows;
+}
+
+function percentile(samples, q) {
+  const sorted = [...samples].sort((a, b) => a - b);
+  if (sorted.length === 0) return 0;
+  // Nearest-rank method — clamped so q=1 picks the last element.
+  const idx = Math.min(
+    sorted.length - 1,
+    Math.max(0, Math.ceil(q * sorted.length) - 1),
+  );
+  return sorted[idx];
+}
+
+/**
+ * Render the aggregated phase-timings table. Returns `null` when there
+ * are no summaries to render so the caller can elide the section
+ * entirely rather than emitting an empty stub.
+ */
+export function renderPhaseTimingsSection(summaries) {
+  if (!Array.isArray(summaries) || summaries.length === 0) return null;
+  const rows = aggregatePhaseTimings(summaries);
+  if (rows.length === 0) return null;
+  const header = `### Phase timings (last ${summaries.length} completed stor${summaries.length === 1 ? 'y' : 'ies'})`;
+  const table = [
+    '| Phase | median ms | p95 ms | n |',
+    '| --- | --- | --- | --- |',
+    ...rows.map((r) => `| ${r.name} | ${r.median} | ${r.p95} | ${r.n} |`),
+  ].join('\n');
+  return `${header}\n\n${table}`;
+}

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

@@ -0,0 +1,235 @@
+/**
+ * progress-reporter/transport.js — outbound I/O for the
+ * `/epic-deliver` progress narrative.
+ *
+ * Extracted from the parent `progress-reporter.js` so the
+ * GitHub-comment posting surface (in `composition.js`) and the
+ * progress-signal aggregation (in `signals.js`) can be reasoned about
+ * independently of the webhook fan-out.
+ *
+ * Each `emit*` helper dispatches a curated event-shaped payload through
+ * the caller-supplied `notify` function. The `notify` contract is owned
+ * by `lib/notifications/*` and ultimately reaches the configured webhook
+ * via gh-exec (the retry/backoff loop lives there, not here — this
+ * module's role is the boundary). Failures from `notify` are swallowed
+ * by design: a flaky webhook URL must never crash the runner mid-wave.
+ *
+ * The webhook events emitted from this module are:
+ *
+ *   - `epic-started`  — fired once at /epic-deliver kickoff
+ *   - `epic-progress` — fired at wave boundaries / blocker transitions
+ *   - `epic-blocked`  — wave aggregated to blocked/failed outside halt path
+ *   - `epic-unblocked` — operator flipped back to executing
+ *
+ * Each fire passes `skipComment: true` so the operator-facing GitHub
+ * comments stay owned by `composition.js` (`upsertEpicRunProgress` and
+ * `ProgressReporter.fire()`) — there is exactly one comment writer and
+ * exactly one webhook writer per event.
+ */
+
+/**
+ * Webhook event name for the curated epic-progress rollup. Distinct from
+ * the `epic-run-progress` structured-comment kind in `signals.js` — the
+ * comment is the operator-facing per-poll snapshot on the Epic ticket,
+ * the webhook event is the coarse-grained rollup that fires at wave
+ * boundaries and after blocker transitions.
+ */
+export const EPIC_PROGRESS_EVENT = 'epic-progress';
+
+/**
+ * Fire a curated `epic-progress` webhook event. Event-driven only — called
+ * at wave boundaries and after blocker raise/clear transitions. Carries
+ * the rollup payload `{ pct, done, total, currentWave, totalWaves, phase,
+ * openBlockers }`, which Slack consumers and downstream subscribers use to
+ * track epic progress without subscribing to per-story chatter.
+ *
+ * The dispatch passes `skipComment: true` — the operator-facing GitHub
+ * comment is owned by `ProgressReporter.fire()` and `upsertEpicRunProgress`,
+ * not by this webhook fire.
+ *
+ * Failures are swallowed by design: the runner must keep moving even if
+ * the webhook URL is misconfigured or the network is flaky.
+ *
+ * @param {{
+ *   notify: Function|null,
+ *   epicId: number,
+ *   done: number,
+ *   total: number,
+ *   currentWave: number,
+ *   totalWaves: number,
+ *   phase?: string,
+ *   openBlockers?: Array<{ reason: string, storyId?: number }>,
+ *   logger?: { warn?: Function },
+ * }} args
+ * @returns {Promise<{ payload: object } | null>}
+ */
+export async function emitEpicProgress({
+  notify,
+  epicId,
+  done,
+  total,
+  currentWave,
+  totalWaves,
+  phase,
+  openBlockers = [],
+  logger,
+}) {
+  if (typeof notify !== 'function') return null;
+  const epicIdNum = Number(epicId);
+  if (!Number.isInteger(epicIdNum) || epicIdNum <= 0) return null;
+  const totalN = Math.max(0, Number(total) || 0);
+  const doneN = Math.max(0, Math.min(totalN, Number(done) || 0));
+  const pct = totalN === 0 ? 0 : Math.round((doneN / totalN) * 100);
+  const blockerCount = Array.isArray(openBlockers) ? openBlockers.length : 0;
+  const blockerSuffix =
+    blockerCount > 0
+      ? ` · 🚧 ${blockerCount} blocker${blockerCount === 1 ? '' : 's'}`
+      : '';
+  const message = `Epic #${epicIdNum} progress · Wave ${currentWave}/${totalWaves} · ${doneN}/${totalN} stories done (${pct}%)${blockerSuffix}`;
+
+  const payload = {
+    severity: blockerCount > 0 ? 'high' : 'medium',
+    message,
+    event: EPIC_PROGRESS_EVENT,
+    level: 'epic',
+    epicId: epicIdNum,
+  };
+  if (phase) payload.phase = phase;
+
+  try {
+    await notify(epicIdNum, payload, { skipComment: true });
+  } catch (err) {
+    logger?.warn?.(
+      `[emitEpicProgress] notify dispatch failed (swallowed): ${err?.message ?? err}`,
+    );
+    return null;
+  }
+  return {
+    payload: {
+      pct,
+      done: doneN,
+      total: totalN,
+      currentWave,
+      totalWaves,
+      phase,
+      openBlockers: openBlockers ?? [],
+    },
+  };
+}
+
+/**
+ * Fire a curated `epic-started` webhook event at /epic-deliver kickoff.
+ * The Slack consumer anchors the rest of the epic narrative to this fire.
+ * Failures are swallowed.
+ */
+export async function emitEpicStarted({
+  notify,
+  epicId,
+  totalWaves,
+  totalStories,
+  title,
+  logger,
+}) {
+  if (typeof notify !== 'function') return null;
+  const epicIdNum = Number(epicId);
+  if (!Number.isInteger(epicIdNum) || epicIdNum <= 0) return null;
+  const message = `Epic #${epicIdNum} started · ${totalWaves} wave${totalWaves === 1 ? '' : 's'} · ${totalStories} stor${totalStories === 1 ? 'y' : 'ies'}${title ? ` — ${title}` : ''}`;
+  try {
+    await notify(
+      epicIdNum,
+      {
+        severity: 'medium',
+        message,
+        event: 'epic-started',
+        level: 'epic',
+        epicId: epicIdNum,
+      },
+      { skipComment: true },
+    );
+  } catch (err) {
+    logger?.warn?.(
+      `[emitEpicStarted] notify dispatch failed (swallowed): ${err?.message ?? err}`,
+    );
+  }
+  return null;
+}
+
+/**
+ * Fire a curated `epic-blocked` webhook event when a wave aggregates to
+ * `blocked` or `failed` outside the `BlockerHandler.halt` code path (the
+ * /epic-deliver host-LLM loop has no handler instance — it calls this
+ * helper directly from `epic-execute-record-wave.js`). The payload shape
+ * matches the inline emit in `BlockerHandler.halt` so downstream consumers
+ * see one canonical envelope regardless of which entry point fired.
+ * Failures are swallowed.
+ */
+export async function emitEpicBlocked({
+  notify,
+  epicId,
+  reason,
+  storyId,
+  logger,
+}) {
+  if (typeof notify !== 'function') return null;
+  const epicIdNum = Number(epicId);
+  if (!Number.isInteger(epicIdNum) || epicIdNum <= 0) return null;
+  const storyPart = storyId ? ` (story #${storyId})` : '';
+  const message = `🚨 Action Required: Epic #${epicIdNum}${storyPart} blocked: ${reason}`;
+  try {
+    await notify(
+      epicIdNum,
+      {
+        severity: 'high',
+        message,
+        event: 'epic-blocked',
+        level: 'epic',
+        epicId: epicIdNum,
+      },
+      { skipComment: true },
+    );
+  } catch (err) {
+    logger?.warn?.(
+      `[emitEpicBlocked] notify dispatch failed (swallowed): ${err?.message ?? err}`,
+    );
+  }
+  return null;
+}
+
+/**
+ * Fire a curated `epic-unblocked` webhook event after the operator flips
+ * the Epic label back to `agent::executing`. Paired with `epic-blocked` so
+ * downstream consumers can track open-blocker lifecycle. Failures are
+ * swallowed.
+ */
+export async function emitEpicUnblocked({
+  notify,
+  epicId,
+  resolvedBlocker,
+  logger,
+}) {
+  if (typeof notify !== 'function') return null;
+  const epicIdNum = Number(epicId);
+  if (!Number.isInteger(epicIdNum) || epicIdNum <= 0) return null;
+  const reasonPart = resolvedBlocker?.reason
+    ? ` (${resolvedBlocker.reason})`
+    : '';
+  const message = `Epic #${epicIdNum} unblocked${reasonPart} · resuming.`;
+  try {
+    await notify(
+      epicIdNum,
+      {
+        severity: 'medium',
+        message,
+        event: 'epic-unblocked',
+        level: 'epic',
+        epicId: epicIdNum,
+      },
+      { skipComment: true },
+    );
+  } catch (err) {
+    logger?.warn?.(
+      `[emitEpicUnblocked] notify dispatch failed (swallowed): ${err?.message ?? err}`,
+    );
+  }
+  return null;
+}

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

@@ -0,0 +1,69 @@
+/**
+ * progress-reporter.js — facade module for the /epic-deliver progress
+ * narrative. Story #1847 split the original 1158-LOC monolith into three
+ * sibling sub-modules under `progress-reporter/`:
+ *
+ *   - `composition.js` — structured-comment body builders and the pure
+ *     rendering helpers (the legacy ProgressReporter class used these).
+ *   - `transport.js` — the curated webhook emit surface (epic-started,
+ *     epic-progress, epic-blocked, epic-unblocked).
+ *   - `signals.js` — pure parse/aggregate over `story-run-progress` and
+ *     `phase-timings` structured comments + the shared state lookup
+ *     tables (PHASE_TO_STATE, PHASE_ORDER, STATE_EMOJI).
+ *
+ * Epic #2646 Story C (Task #2699) — the tick-based polling
+ * `ProgressReporter` class that used to live here was deleted in favour
+ * of the bus-driven `lifecycle/listeners/progress-reporter.js` which
+ * already consumes `story.dispatch.end` + `wave.end` to compose the
+ * `epic-run-progress` body. The webhook helpers and parse/aggregate
+ * exports remain at this path so existing importers
+ * (`epic-execute-record-wave.js`, `wave-record-notifications.js`,
+ * `crap-remediation-1641.test.js`) keep resolving — only the periodic
+ * emission shell went away.
+ */
+
+import {
+  deriveState as deriveStateFromComposition,
+  renderProgressBody as renderProgressBodyFromComposition,
+  truncate as truncateFromComposition,
+  upsertEpicRunProgress as upsertEpicRunProgressFromComposition,
+} from './progress-reporter/composition.js';
+import {
+  aggregatePhaseTimings as aggregatePhaseTimingsFromSignals,
+  EPIC_RUN_PROGRESS_TYPE as EPIC_RUN_PROGRESS_TYPE_FROM_SIGNALS,
+  PHASE_TIMINGS_TYPE as PHASE_TIMINGS_TYPE_FROM_SIGNALS,
+  parsePhaseTimingsComment as parsePhaseTimingsCommentFromSignals,
+  parseStoryRunProgressComment as parseStoryRunProgressCommentFromSignals,
+  phaseToState as phaseToStateFromSignals,
+  renderPhaseTimingsSection as renderPhaseTimingsSectionFromSignals,
+  STORY_RUN_PROGRESS_TYPE as STORY_RUN_PROGRESS_TYPE_FROM_SIGNALS,
+} from './progress-reporter/signals.js';
+import {
+  EPIC_PROGRESS_EVENT as EPIC_PROGRESS_EVENT_FROM_TRANSPORT,
+  emitEpicBlocked as emitEpicBlockedFromTransport,
+  emitEpicProgress as emitEpicProgressFromTransport,
+  emitEpicStarted as emitEpicStartedFromTransport,
+  emitEpicUnblocked as emitEpicUnblockedFromTransport,
+} from './progress-reporter/transport.js';
+
+// Re-exports — sub-module surfaces are aliased back to the parent path so
+// existing imports (epic-execute-record-wave.js,
+// wave-record-notifications.js) keep resolving.
+export const EPIC_RUN_PROGRESS_TYPE = EPIC_RUN_PROGRESS_TYPE_FROM_SIGNALS;
+export const PHASE_TIMINGS_TYPE = PHASE_TIMINGS_TYPE_FROM_SIGNALS;
+export const STORY_RUN_PROGRESS_TYPE = STORY_RUN_PROGRESS_TYPE_FROM_SIGNALS;
+export const EPIC_PROGRESS_EVENT = EPIC_PROGRESS_EVENT_FROM_TRANSPORT;
+export const emitEpicProgress = emitEpicProgressFromTransport;
+export const emitEpicStarted = emitEpicStartedFromTransport;
+export const emitEpicBlocked = emitEpicBlockedFromTransport;
+export const emitEpicUnblocked = emitEpicUnblockedFromTransport;
+export const parseStoryRunProgressComment =
+  parseStoryRunProgressCommentFromSignals;
+export const parsePhaseTimingsComment = parsePhaseTimingsCommentFromSignals;
+export const aggregatePhaseTimings = aggregatePhaseTimingsFromSignals;
+export const renderPhaseTimingsSection = renderPhaseTimingsSectionFromSignals;
+export const phaseToState = phaseToStateFromSignals;
+export const upsertEpicRunProgress = upsertEpicRunProgressFromComposition;
+export const deriveState = deriveStateFromComposition;
+export const renderProgressBody = renderProgressBodyFromComposition;
+export const truncate = truncateFromComposition;

package/.agents/scripts/lib/orchestration/epic-runner/progress-signals/_bullet-format.js

@@ -0,0 +1,32 @@
+/**
+ * Shared bullet-formatting helpers for progress-signal detectors.
+ *
+ * Both crap-drift and maintainability-drift produce component-level
+ * regression bullets and need the same two pure utilities — hoisted here
+ * so they are maintained in one place (Story #3631, refs #3631).
+ */
+
+/**
+ * Comparator that sorts the wildcard component `'*'` before all named
+ * components, with named components in locale order.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function componentOrder(a, b) {
+  if (a === '*') return -1;
+  if (b === '*') return 1;
+  return a.localeCompare(b);
+}
+
+/**
+ * Formats a numeric gate value for display: integers render without a
+ * decimal point; non-integers are fixed to two decimal places.
+ *
+ * @param {number} value
+ * @returns {string}
+ */
+export function formatNumber(value) {
+  return Number.isInteger(value) ? String(value) : value.toFixed(2);
+}