mandrel 2.30.0 → 2.32.0

package/.agents/scripts/lib/signals/span-tree.js

@@ -1,291 +0,0 @@
-/**
- * Span-tree builder (Epic #1181 / Story #1440 / Task #1461).
- *
- * Pure transform over the `lib/signals/read` async iterator. Materialises
- * a tree of:
- *
- *   epic
- *     story (id)
- *       task (id)
- *         events (chronological)
- *
- * with `startedAt` / `endedAt` / `durationMs` computed from paired
- * lifecycle events when they exist. The Tech Spec (#1433) defines the
- * shape; this module is the canonical implementation.
- *
- * ## Lifecycle pairing
- *
- *   The schema audit in `lib/signals/schema.js` confirms that
- *   `wave-start` / `wave-end` envelopes carry `epicId` + `storyId` and
- *   bracket a Story's lifetime in a wave.
- *   Per-Task lifecycle today comes via `state-transition` events
- *   (`agent::executing` → `agent::done`) — we treat the **first**
- *   timestamp we see for a given (story, task) pair as `startedAt` and
- *   the **last** as `endedAt`. This is intentionally permissive: the
- *   span-tree's contract is "what we have", not "what we wish were
- *   emitted". When a Task has only a start event the `durationMs` stays
- *   `null` per AC#2.
- *
- *   `wave-start` / `wave-end` (or any kind starting with `story.`)
- *   anchor the Story-level start/end when present; absent those, we
- *   fall back to the min/max of every event under that Story.
- *
- * ## Purity
- *
- *   No I/O, no globals, no `Date.now()` reads. The function is a pure
- *   reducer over the iterator — identical input produces identical
- *   output (AC#1). Time references come exclusively from the events'
- *   own `ts` / `timestamp` fields.
- *
- * ## Empty input
- *
- *   `buildSpanTree(emptyIter)` with **no events** returns
- *   `{ epic: null, stories: [] }` — the Epic is unknown when we never
- *   see one (AC#3). When at least one event flows through we pin
- *   `epic` to its `epic` / `epicId` field; mixed-Epic iterators
- *   (uncommon — `read()` is single-Epic) take the first observed Epic
- *   ID and ignore the rest with no warning, since silent permissiveness
- *   is the pure-function contract.
- *
- * @module lib/signals/span-tree
- */
-
-function tsOf(evt) {
-  // Canonical envelope only (Epic #4406) — the legacy `timestamp` alias
-  // was deleted from every writer in the same PR.
-  return evt?.ts ?? null;
-}
-
-function epicOf(evt) {
-  return evt?.epicId ?? null;
-}
-
-function storyOf(evt) {
-  return evt?.storyId ?? null;
-}
-
-function taskOf(evt) {
-  return evt?.taskId ?? null;
-}
-
-/**
- * Lexicographic timestamp comparison. ISO-8601 strings compare correctly
- * with `<` / `>`, so we avoid the Date round-trip and stay pure (no TZ
- * normalisation surprises).
- *
- * @param {string | null} a
- * @param {string | null} b
- * @returns {number} -1 / 0 / 1 (nulls sort last)
- */
-function cmpTs(a, b) {
-  if (a === b) return 0;
-  if (a == null) return 1;
-  if (b == null) return -1;
-  if (a < b) return -1;
-  if (a > b) return 1;
-  return 0;
-}
-
-function diffMs(start, end) {
-  if (start == null || end == null) return null;
-  const s = Date.parse(start);
-  const e = Date.parse(end);
-  if (!Number.isFinite(s) || !Number.isFinite(e)) return null;
-  return e - s;
-}
-
-function isStoryLifecycle(kind) {
-  return (
-    kind === 'wave-start' ||
-    kind === 'wave-end' ||
-    kind === 'story.start' ||
-    kind === 'story.end'
-  );
-}
-
-function isStoryStart(kind) {
-  return kind === 'wave-start' || kind === 'story.start';
-}
-
-function isStoryEnd(kind) {
-  return kind === 'wave-end' || kind === 'story.end';
-}
-
-function emptyTaskNode(id) {
-  return {
-    id,
-    startedAt: null,
-    endedAt: null,
-    durationMs: null,
-    events: [],
-  };
-}
-
-function emptyStoryNode(id) {
-  return {
-    id,
-    startedAt: null,
-    endedAt: null,
-    durationMs: null,
-    tasks: [],
-    events: [],
-  };
-}
-
-function storyKeyOf(sid) {
-  return sid == null ? '__none__' : String(sid);
-}
-
-function getOrCreateStory(state, sid) {
-  const key = storyKeyOf(sid);
-  let node = state.stories.get(key);
-  if (!node) {
-    node = emptyStoryNode(sid);
-    state.stories.set(key, node);
-    state.tasksByStory.set(key, new Map());
-  }
-  return { key, node };
-}
-
-function getOrCreateTask(state, storyKey, tid) {
-  const taskMap = state.tasksByStory.get(storyKey);
-  const tkey = String(tid);
-  let node = taskMap.get(tkey);
-  if (!node) {
-    node = emptyTaskNode(tid);
-    taskMap.set(tkey, node);
-  }
-  return node;
-}
-
-function updateStoryLifecycle(storyNode, kind, ts) {
-  if (!isStoryLifecycle(kind)) return;
-  if (isStoryStart(kind)) {
-    if (storyNode.startedAt == null || cmpTs(ts, storyNode.startedAt) < 0) {
-      storyNode.startedAt = ts;
-    }
-  } else if (isStoryEnd(kind)) {
-    if (storyNode.endedAt == null || cmpTs(ts, storyNode.endedAt) > 0) {
-      storyNode.endedAt = ts;
-    }
-  }
-}
-
-function widenTaskWindow(taskNode, ts) {
-  if (ts == null) return;
-  if (taskNode.startedAt == null || cmpTs(ts, taskNode.startedAt) < 0) {
-    taskNode.startedAt = ts;
-  }
-  if (taskNode.endedAt == null || cmpTs(ts, taskNode.endedAt) > 0) {
-    taskNode.endedAt = ts;
-  }
-}
-
-function bootstrapStoryWindow(storyNode, ts) {
-  if (ts == null) return;
-  if (storyNode.startedAt == null) storyNode.startedAt = ts;
-  if (storyNode.endedAt == null) storyNode.endedAt = ts;
-}
-
-/**
- * Reducer step — fold a single event into the running state. Extracted
- * from `buildSpanTree` so the outer function's CRAP score stays under
- * the new-method ceiling.
- *
- * @param {object} state — mutable accumulator (stories, tasksByStory, run)
- * @param {unknown} evt
- * @returns {void}
- */
-function ingestEvent(state, evt) {
-  if (evt == null || typeof evt !== 'object') return;
-
-  const eRun = epicOf(evt);
-  if (state.run == null && eRun != null) state.run = eRun;
-
-  const ts = tsOf(evt);
-  const sid = storyOf(evt);
-  const tid = taskOf(evt);
-  const kind = typeof evt.kind === 'string' ? evt.kind : null;
-
-  const { key: storyKey, node: storyNode } = getOrCreateStory(state, sid);
-  updateStoryLifecycle(storyNode, kind, ts);
-
-  if (tid != null) {
-    const taskNode = getOrCreateTask(state, storyKey, tid);
-    widenTaskWindow(taskNode, ts);
-    taskNode.events.push(evt);
-  } else {
-    storyNode.events.push(evt);
-  }
-
-  bootstrapStoryWindow(storyNode, ts);
-}
-
-/**
- * Default comparator for sorting Story / Task nodes by id ascending,
- * with `null` ids sorting last and a string fallback for slug-shaped
- * Task ids (the framework allows non-numeric task identifiers).
- *
- * @param {object} a
- * @param {object} b
- * @returns {number}
- */
-function compareNodeIds(a, b) {
-  if (a.id === b.id) return 0;
-  if (a.id == null) return 1;
-  if (b.id == null) return -1;
-  if (typeof a.id === 'number' && typeof b.id === 'number') {
-    return a.id - b.id;
-  }
-  return String(a.id).localeCompare(String(b.id));
-}
-
-function finalizeTask(task) {
-  task.events.sort((ea, eb) => cmpTs(tsOf(ea), tsOf(eb)));
-  task.durationMs = diffMs(task.startedAt, task.endedAt);
-}
-
-function finalizeStory(state, story) {
-  const taskMap = state.tasksByStory.get(storyKeyOf(story.id));
-  const taskEntries = [...taskMap.values()];
-  taskEntries.sort(compareNodeIds);
-  for (const task of taskEntries) finalizeTask(task);
-  story.events.sort((ea, eb) => cmpTs(tsOf(ea), tsOf(eb)));
-  story.durationMs = diffMs(story.startedAt, story.endedAt);
-}
-
-/**
- * Build the span tree from an async iterable of signal events.
- *
- * @param {AsyncIterable<object> | Iterable<object>} iter
- * @returns {Promise<{ run: number | null, stories: Array<object> }>}
- *
- * @example
- *   import { read, buildSpanTree } from './lib/signals/index.js';
- *   const tree = await buildSpanTree(read({ run: 1181 }));
- */
-export async function buildSpanTree(iter) {
-  if (iter == null || typeof iter !== 'object') {
-    throw new TypeError(
-      `signals/span-tree: iter must be an async iterable; got ${iter}`,
-    );
-  }
-
-  // Accumulator state. `stories` keys are `storyKeyOf(sid)` strings;
-  // `tasksByStory` mirrors that and holds per-task sub-maps.
-  const state = {
-    run: null,
-    stories: new Map(),
-    tasksByStory: new Map(),
-  };
-
-  for await (const evt of iter) {
-    ingestEvent(state, evt);
-  }
-
-  const storyEntries = [...state.stories.values()];
-  storyEntries.sort(compareNodeIds);
-  for (const story of storyEntries) finalizeStory(state, story);
-
-  return { run: state.run, stories: storyEntries };
-}

package/.agents/scripts/lib/story-lifecycle.js

@@ -1,194 +0,0 @@
-/**
- * Story lifecycle helpers shared between story-init and story-close.
- *
- * These three pure/IO-helpers capture the overlap previously duplicated across
- * the two CLI scripts — parsing the `Epic: #N` / `parent: #N` references out
- * of a Story body, fetching child sub-tickets, and batch-transitioning
- * tickets to a target state label.
- *
- * The shape is narrow on purpose: init/close still own their own orchestration
- * (branch bootstrap, merge, cascade, notifications). Expanding this module to
- * cover those would over-abstract — they are genuinely different concerns.
- *
- * Under the 2-tier hierarchy (Epic #3078) Stories have no child tickets, so
- * `fetchChildTickets` typically returns `[]` — but the helper remains in
- * place so legacy callers still resolve the Story's direct children cleanly.
- */
-
-import { Logger } from './Logger.js';
-import {
-  STATE_LABELS,
-  transitionTicketState,
-} from './orchestration/ticketing.js';
-/**
- * Parse the `Epic: #N` and `parent: #N` references from a Story body.
- *
- * Story #4300 (defense-in-depth): under the 2-tier hierarchy
- * (Epic → Story) a Story's `parent: #N` marker always IS the parent
- * Epic, so when the `Epic: #N` line is missing — e.g. a Story body
- * refreshed by the reconciler's UPDATE op before Story #4300's
- * single-sourced footer rendering landed — `epicId` falls back to the
- * resolved `parentId` rather than reporting `null` and aborting
- * delivery. A body that carries neither marker still resolves
- * `epicId: null` (no parent to fall back to).
- *
- * @param {string} body  Raw Story body Markdown.
- * @returns {{ epicId: number|null, parentId: number|null }}
- */
-export function resolveStoryHierarchy(body) {
-  const source = body ?? '';
-  const epicMatch = source.match(/(?:^\s*epic:\s*#(\d+))/im);
-  const parentMatch = source.match(/(?:^\s*parent:\s*#(\d+))/im);
-  const parentId = parentMatch ? Number.parseInt(parentMatch[1], 10) : null;
-  const epicId = epicMatch ? Number.parseInt(epicMatch[1], 10) : parentId;
-  return { epicId, parentId };
-}
-
-/**
- * Fetch the Story's direct child tickets via the provider.
- *
- * Under the 2-tier hierarchy (Epic #3078) Stories no longer enumerate
- * child Task tickets — acceptance criteria and verification steps live
- * inline on the Story body, and decomposers emit only Epic / Story
- * issues. For those Stories this helper resolves to an empty
- * array because `provider.getSubTickets(storyId)` itself returns no
- * rows. The helper is retained as a thin pass-through so the three
- * orchestration callers (`story-init` prepare, `task-graph-builder`,
- * and `locked-pipeline`) keep a single, named seam for sub-ticket
- * hydration that is easy to mock in tests and to instrument in the
- * provider layer.
- *
- * Legacy ticket trees that were planned before the 2-tier cutover may
- * still carry sub-tickets (PRD/Tech-Spec links recorded as direct
- * children, for example). The helper deliberately does **not** filter
- * those out — the caller is responsible for classifying anything that
- * comes back. The previous `type::task`-only filter has been removed in
- * Story #3191 because no current call site relies on that narrowing.
- *
- * @param {object} provider  ITicketingProvider instance.
- * @param {number} storyId   Story ticket number to hydrate children for.
- * @returns {Promise<object[]>} Array of child tickets (empty under 2-tier).
- */
-export async function fetchChildTickets(provider, storyId) {
-  return provider.getSubTickets(storyId);
-}
-
-/**
- * Detect transient HTTP errors (rate limits, gateways, server errors) that
- * are worth retrying. Permission/validation errors are not retried — the
- * second attempt would fail the same way.
- *
- * @param {Error} err
- * @returns {boolean}
- */
-function isRetryableError(err) {
-  const status = err?.status ?? err?.statusCode;
-  if (status === 429) return true;
-  if (typeof status === 'number' && status >= 500 && status < 600) return true;
-  const msg = (err?.message ?? '').toLowerCase();
-  return (
-    msg.includes('rate limit') ||
-    msg.includes('timeout') ||
-    msg.includes('econnreset') ||
-    msg.includes('etimedout') ||
-    msg.includes('socket hang up')
-  );
-}
-
-/**
- * Batch-transition a set of tickets to the target state label. Tickets
- * already carrying `STATE_LABELS.DONE` (or the target itself) are skipped.
- * Each transition runs in parallel with a per-ticket retry budget for
- * transient errors (429, 5xx, network). Permanent failures are recorded
- * in `failed` without aborting the batch.
- *
- * @param {object} provider  ITicketingProvider instance.
- * @param {object[]} tickets Array of ticket objects with `id` and `labels`.
- * @param {string} targetLabel  Target `agent::...` label (e.g. STATE_LABELS.EXECUTING).
- * @param {object} [opts]
- * @param {(phase: string, message: string) => void} [opts.progress]  Progress reporter.
- * @param {(ticketId: number, err: Error) => void}  [opts.onError]     Per-failure callback.
- * @param {number} [opts.concurrency=10]    Max parallel ticket transitions.
- * @param {number} [opts.retries=3]         Max attempts per ticket on transient errors.
- * @param {number} [opts.retryBaseMs=500]   Base for exponential backoff (attempt * base).
- * @param {Function} [opts.notify] Optional notify function — forwarded to
- *   each `transitionTicketState` call so successful transitions fire a
- *   state-transition notification.
- * @returns {Promise<{ transitioned: number[], skipped: number[], failed: Array<{ id: number, error: string, attempts: number }> }>}
- */
-export async function batchTransitionTickets(
-  provider,
-  tickets,
-  targetLabel,
-  opts = {},
-) {
-  const { progress, onError, notify } = opts;
-  const transitioned = [];
-  const skipped = [];
-  const failed = [];
-
-  const concurrency = opts.concurrency ?? 10;
-  const maxRetries = opts.retries ?? 3;
-  const retryBaseMs = opts.retryBaseMs ?? 500;
-
-  const processTicket = async (ticket) => {
-    if (ticket.labels.includes(targetLabel)) {
-      progress?.('TICKETS', `  #${ticket.id} already ${targetLabel} — skipped`);
-      skipped.push(ticket.id);
-      return;
-    }
-    if (
-      targetLabel !== STATE_LABELS.DONE &&
-      ticket.labels.includes(STATE_LABELS.DONE)
-    ) {
-      progress?.('TICKETS', `  #${ticket.id} already done — skipped`);
-      skipped.push(ticket.id);
-      return;
-    }
-    let lastErr;
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-      try {
-        // Story #1795 — thread the already-hydrated ticket through
-        // `opts.ticketSnapshot` so `transitionTicketState` skips both
-        // round-trips (notify snapshot + label merge). `batchTransitionTickets`
-        // is the single hot caller of this seam — every wave-close passes
-        // its full task list through here.
-        await transitionTicketState(provider, ticket.id, targetLabel, {
-          notify,
-          ticketSnapshot: ticket,
-        });
-        progress?.(
-          'TICKETS',
-          `  #${ticket.id} → ${targetLabel} ✅${attempt > 1 ? ` (after ${attempt} attempts)` : ''}`,
-        );
-        transitioned.push(ticket.id);
-        return;
-      } catch (err) {
-        lastErr = err;
-        if (attempt >= maxRetries || !isRetryableError(err)) break;
-        const delay = retryBaseMs * 2 ** (attempt - 1);
-        progress?.(
-          'TICKETS',
-          `  #${ticket.id} transient error (${err.message}); retrying in ${delay}ms (${attempt}/${maxRetries - 1})`,
-        );
-        await new Promise((resolve) => setTimeout(resolve, delay));
-      }
-    }
-    failed.push({
-      id: ticket.id,
-      error: lastErr?.message ?? String(lastErr),
-      attempts: maxRetries,
-    });
-    if (onError) onError(ticket.id, lastErr);
-    else
-      Logger.error(`  #${ticket.id} → FAILED: ${lastErr?.message ?? lastErr}`);
-  };
-
-  // Process in batches to avoid overwhelming the API with concurrent requests.
-  for (let i = 0; i < tickets.length; i += concurrency) {
-    const batch = tickets.slice(i, i + concurrency);
-    await Promise.all(batch.map(processTicket));
-  }
-
-  return { transitioned, skipped, failed };
-}