mandrel 1.94.0 → 2.1.0

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 };
-}

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

@@ -1,210 +0,0 @@
-/**
- * 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
- * `/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. Consumed by the rolled-up Epic table
- * (`composition.upsertEpicRunProgress`) so operators see a consistent icon
- * per state across the progress surface.
- */
-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 `/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',
- *     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;
-  return {
-    storyId: Number(payload.storyId),
-    title: typeof payload.title === 'string' ? payload.title : '',
-    phase,
-    state: phaseToState(phase),
-  };
-}
-
-/**
- * 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}`;
-}