mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/orchestration/cascade-grouping.js

@@ -1,275 +0,0 @@
-/**
- * lib/orchestration/cascade-grouping.js — Cascade dispatch helpers.
- *
- * Pure helpers used by `cascadeCompletion` (see `./ticketing.js`) to
- * partition a list of parent tickets into disjoint shared-ancestor groups
- * and to buffer per-parent log output so parallel dispatch produces a
- * byte-identical log stream to the serial baseline.
- *
- * Pulled out of `ticketing.js` so the cascade orchestrator stays under the
- * project's per-file maintainability ceiling. No state is held at module
- * scope — every helper takes its dependencies as arguments.
- */
-
-/**
- * Walks `parent: #N` references upward from the given ticket id until no new
- * ancestors are discovered. Returns the set of every ticket id reachable
- * along the chain, including the starting id. Cycle-safe by construction —
- * the visited set acts as the seen guard, so a cyclic `parent: #N` graph
- * terminates in finite steps without revisiting nodes.
- *
- * Pure of side effects beyond the provider reads it issues. Provider
- * failures on a single hop fall back to "no further ancestors discovered"
- * for that branch (the chain truncates rather than throwing); this matches
- * `cascadeCompletion`'s tolerant posture toward transient reads.
- *
- * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
- * @param {number} startId
- * @param {Map<number, Set<number>>} [cache] - Optional per-call cache of
- *   already-walked chains keyed by intermediate id. Reused across parents
- *   in {@link groupByAncestor} to amortise repeat walks.
- * @returns {Promise<Set<number>>} ancestor set including `startId`.
- */
-export async function walkAncestorChain(provider, startId, cache) {
-  // Inner DFS with memoisation. `inProgress` guards cycles so a cyclic
-  // `parent: #N` graph terminates without recursion depth issues. Each
-  // visited node gets its own cache entry holding the set of ids reachable
-  // from it (inclusive), so a sibling walk that re-enters this subgraph
-  // can splice the cached set wholesale instead of re-reading the provider.
-  async function visit(id, inProgress) {
-    if (cache?.has(id)) return cache.get(id);
-    if (inProgress.has(id)) {
-      // Cycle: return a singleton so the caller still includes `id` in its
-      // ancestor set without recursing further through this loop. Do NOT
-      // memoise — the partial result is incomplete for `id`'s true chain.
-      return new Set([id]);
-    }
-    inProgress.add(id);
-
-    const set = new Set([id]);
-    let ticket = null;
-    try {
-      ticket = await provider.getTicket(id);
-    } catch {
-      // Provider read failure: truncate the chain branch. Memoise as the
-      // singleton so subsequent walks don't retry an already-failed read.
-      inProgress.delete(id);
-      cache?.set(id, set);
-      return set;
-    }
-
-    if (ticket?.body) {
-      const matches = [...ticket.body.matchAll(/parent:\s*#(\d+)/gi)];
-      for (const m of matches) {
-        const next = Number.parseInt(m[1], 10);
-        if (!Number.isFinite(next)) continue;
-        const subset = await visit(next, inProgress);
-        for (const v of subset) set.add(v);
-      }
-    }
-
-    inProgress.delete(id);
-    cache?.set(id, set);
-    return set;
-  }
-
-  return visit(startId, new Set());
-}
-
-/**
- * Partitions a list of parent ids into disjoint groups whose members share
- * at least one ancestor (transitively, via `parent: #N` references walked
- * to fixpoint).
- *
- * Two parents end up in the same group if and only if their ancestor sets
- * overlap on at least one ticket id. Parents with no shared ancestors end
- * up in singleton groups. The union of the returned groups equals the
- * input set; the order of `parents[]` is preserved within each group, and
- * groups are returned in the order their first member appears in the
- * input.
- *
- * Pure of side effects beyond the provider reads needed to walk chains.
- * Walked ancestor sets are cached per call so a parent that contributes
- * to multiple groups is not re-walked. Cycle-safe — see
- * {@link walkAncestorChain}.
- *
- * Used by `cascadeCompletion` to dispatch disjoint groups in parallel
- * while keeping shared-ancestor groups strictly sequential (concurrent
- * transitions on the same ancestor would race the "all children done?"
- * check).
- *
- * @param {Array<number>} parents
- * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
- * @returns {Promise<Array<Array<number>>>} disjoint groups of parent ids.
- */
-export async function groupByAncestor(parents, provider) {
-  if (!Array.isArray(parents) || parents.length === 0) return [];
-
-  // Walk each parent's ancestor chain once, sharing a cache so a parent
-  // that re-enters an already-walked subgraph reuses the cached set.
-  const cache = new Map();
-  const ancestorsByParent = new Map();
-  for (const parentId of parents) {
-    const chain = await walkAncestorChain(provider, parentId, cache);
-    ancestorsByParent.set(parentId, chain);
-  }
-
-  return unionFindByAncestor(parents, ancestorsByParent);
-}
-
-/**
- * Union-Find over `parents`, joined whenever any two parents' ancestor
- * chains overlap on at least one id. Returns the parents bucketed by
- * representative, in input order both for the groups themselves and for
- * members within each group.
- *
- * Pulled out of {@link groupByAncestor} to keep that function's CRAP
- * under the v6 ceiling.
- *
- * @param {Array<number>} parents
- * @param {Map<number, Set<number>>} ancestorsByParent
- * @returns {Array<Array<number>>}
- */
-function unionFindByAncestor(parents, ancestorsByParent) {
-  const parentIndex = new Map();
-  parents.forEach((p, i) => {
-    parentIndex.set(p, i);
-  });
-  const uf = parents.map((_, i) => i);
-  const find = (i) => {
-    while (uf[i] !== i) {
-      uf[i] = uf[uf[i]];
-      i = uf[i];
-    }
-    return i;
-  };
-  const union = (a, b) => {
-    const ra = find(a);
-    const rb = find(b);
-    if (ra !== rb) uf[ra] = rb;
-  };
-
-  // For each ancestor id, collect parents whose chain hits it; union them.
-  const ancestorToParents = new Map();
-  for (const [parentId, chain] of ancestorsByParent) {
-    for (const ancestorId of chain) {
-      if (!ancestorToParents.has(ancestorId)) {
-        ancestorToParents.set(ancestorId, []);
-      }
-      ancestorToParents.get(ancestorId).push(parentId);
-    }
-  }
-  for (const sharing of ancestorToParents.values()) {
-    if (sharing.length < 2) continue;
-    const first = parentIndex.get(sharing[0]);
-    for (let i = 1; i < sharing.length; i++) {
-      union(first, parentIndex.get(sharing[i]));
-    }
-  }
-
-  // Bucket parents by representative, preserving first-seen order for
-  // both groups and within-group ordering.
-  const repToGroup = new Map();
-  const groupOrder = [];
-  for (const parentId of parents) {
-    const rep = find(parentIndex.get(parentId));
-    if (!repToGroup.has(rep)) {
-      repToGroup.set(rep, []);
-      groupOrder.push(rep);
-    }
-    repToGroup.get(rep).push(parentId);
-  }
-
-  return groupOrder.map((rep) => repToGroup.get(rep));
-}
-
-/**
- * Dispatches cascade work across disjoint shared-ancestor groups in
- * parallel while running each within-group parent sequentially in input
- * order. Per-parent output is captured into a buffered logger so the
- * visible log stream is byte-identical to a serial baseline; the buffer
- * is flushed to `flushLogger` in the original `parsedParents` order
- * after every group resolves.
- *
- * The actual per-parent work is supplied by `processParent` so this
- * helper stays free of cascade-specific dependencies — its only job is
- * the parallel-dispatch + ordered-flush scaffolding.
- *
- * @template R
- * @param {Object} args
- * @param {Array<number>} args.parsedParents - Parent ids in their
- *   original input order. Drives both the group-membership lookup and
- *   the post-dispatch log flush order.
- * @param {Array<Array<number>>} args.groups - Disjoint groups returned
- *   by {@link groupByAncestor}.
- * @param {(parentId: number, bufferedLogger: object) => Promise<R>} args.processParent
- *   Per-parent worker. Receives the parent id and a buffered logger.
- *   Its resolved value is collected into `args.parsedParents`-ordered
- *   results.
- * @param {{ debug: Function, info: Function, warn: Function, error: Function }} args.flushLogger
- *   Real logger that receives the buffered output after dispatch.
- * @returns {Promise<Array<R>>} per-parent results in `parsedParents`
- *   order.
- */
-export async function dispatchCascadeGroups({
-  parsedParents,
-  groups,
-  processParent,
-  flushLogger,
-}) {
-  const parentLoggers = new Map();
-  const parentResults = new Map();
-  for (const parentId of parsedParents) {
-    parentLoggers.set(parentId, createBufferedLogger());
-  }
-
-  await Promise.all(
-    groups.map(async (group) => {
-      for (const parentId of group) {
-        const logger = parentLoggers.get(parentId);
-        const result = await processParent(parentId, logger);
-        parentResults.set(parentId, result);
-      }
-    }),
-  );
-
-  const results = [];
-  for (const parentId of parsedParents) {
-    const lg = parentLoggers.get(parentId);
-    if (lg) {
-      for (const entry of lg.buffer) {
-        flushLogger[entry.level](entry.message);
-      }
-    }
-    const result = parentResults.get(parentId);
-    if (result !== undefined) results.push(result);
-  }
-  return results;
-}
-
-/**
- * Buffered logger shaped like the public `Logger` surface. Stores every
- * emitted line in `buffer[]` instead of writing to the console. Callers
- * flush the buffer to a real logger after the buffered region completes
- * so the visible log output is byte-identical to a serial run.
- *
- * @returns {{ buffer: Array<{ level: 'debug'|'info'|'warn'|'error', message: string }>, debug: Function, info: Function, warn: Function, error: Function }}
- */
-export function createBufferedLogger() {
-  const buffer = [];
-  return {
-    buffer,
-    debug(message) {
-      buffer.push({ level: 'debug', message });
-    },
-    info(message) {
-      buffer.push({ level: 'info', message });
-    },
-    warn(message) {
-      buffer.push({ level: 'warn', message });
-    },
-    error(message) {
-      buffer.push({ level: 'error', message });
-    },
-  };
-}

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

@@ -1,69 +0,0 @@
-/**
- * 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/reconciler.js

@@ -1,137 +0,0 @@
-/**
- * lib/orchestration/reconciler.js — Ticket Hierarchy Reconciliation
- */
-
-import { Logger } from '../Logger.js';
-import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
-import { concurrentMap } from '../util/concurrent-map.js';
-import { STATE_LABELS } from './ticketing.js';
-
-const AGENT_DONE_LABEL = STATE_LABELS.DONE;
-
-// Inlined parent-id parser. The reconciler only needs the direct parent
-// reference scraped from a ticket body's `parent: #N` trailer; pulling the
-// helper inline keeps reconciler.js self-contained for the 3-tier
-// hierarchy walk (Stories → Features).
-const PARENT_ID_PATTERN = /^parent:\s*#(\d+)/m;
-
-function parseParentIdFromBody(body) {
-  const match = (body ?? '').match(PARENT_ID_PATTERN);
-  return match ? Number.parseInt(match[1], 10) : null;
-}
-
-// Cap=4 — bounded parallelism for ticket-update fan-outs. Reconciliation
-// iterates an Epic-sized set of independent GitHub mutations; cap matches
-// the established pattern across the orchestration layer (wave-gate,
-// progress-reporter, sub-issue link reconcile) and stays well under the
-// secondary rate-limit ceiling observed for issue PATCHes.
-const RECONCILE_CONCURRENCY = 4;
-
-/**
- * Reconcile the ticket hierarchy bottom-up (Stories → Features).
- *
- * Walks every Story and Feature under the Epic; if all children of a
- * container are done, closes the container and applies `agent::done`.
- *
- * Epic auto-closure is intentionally excluded — Epics close only through
- * the formal `/epic-deliver` workflow.
- *
- * Per-ticket provider failures are logged and swallowed so a single bad
- * ticket cannot halt reconciliation across the rest of the graph.
- *
- * @param {import('../ITicketingProvider.js').ITicketingProvider} provider  Ticketing provider.
- * @param {number} _epicId                                               Epic id (reserved — currently unused; kept for call-site stability).
- * @param {object} _epic                                                 Epic ticket record (reserved — currently unused).
- * @param {object[]} allTickets                                          Every ticket under the Epic.
- * @param {boolean} dryRun                                               When true, mutate nothing.
- * @returns {Promise<void>}
- */
-export async function reconcileHierarchy(
-  provider,
-  _epicId,
-  _epic,
-  allTickets,
-  dryRun,
-) {
-  const ticketMap = new Map(allTickets.map((t) => [t.id, t]));
-
-  const childrenOf = new Map();
-  for (const ticket of allTickets) {
-    const parentId = parseParentIdFromBody(ticket.body);
-    if (parentId != null) {
-      if (!childrenOf.has(parentId)) childrenOf.set(parentId, []);
-      childrenOf.get(parentId).push(ticket.id);
-    }
-  }
-
-  function isDone(ticketId) {
-    const t = ticketMap.get(ticketId);
-    if (!t) return false;
-    return (
-      t.state === 'closed' ||
-      (t.labelSet ?? new Set(t.labels)).has(AGENT_DONE_LABEL)
-    );
-  }
-
-  function shouldClose(id) {
-    const ticket = ticketMap.get(id);
-    if (!ticket || ticket.state === 'closed') return null;
-    const children = childrenOf.get(id) ?? [];
-    if (children.length === 0) return null;
-    if (!children.every((cid) => isDone(cid))) return null;
-    return ticket;
-  }
-
-  async function applyClose(id, typeName, ticket) {
-    try {
-      await provider.updateTicket(id, {
-        labels: {
-          add: [AGENT_DONE_LABEL],
-          remove: [AGENT_LABELS.READY, AGENT_LABELS.EXECUTING],
-        },
-        state: 'closed',
-        state_reason: 'completed',
-      });
-      ticket.state = 'closed';
-      Logger.info(`✅ ${typeName} #${id} closed and marked agent::done.`);
-    } catch (err) {
-      Logger.warn(`Failed to close ${typeName} #${id}: ${err.message}`);
-    }
-  }
-
-  async function maybeClose(id, typeName) {
-    const ticket = shouldClose(id);
-    if (!ticket) return;
-    Logger.info(
-      `All children of ${typeName} #${id} "${ticket.title}" are done. Closing...`,
-    );
-    if (dryRun) {
-      Logger.info(
-        `[DRY-RUN] Would close ${typeName} #${id} and set agent::done.`,
-      );
-      ticket.state = 'closed';
-      return;
-    }
-    await applyClose(id, typeName, ticket);
-  }
-
-  const storyIds = allTickets
-    .filter((t) => (t.labelSet ?? new Set(t.labels)).has(TYPE_LABELS.STORY))
-    .map((t) => t.id);
-  const featureIds = allTickets
-    .filter((t) => (t.labelSet ?? new Set(t.labels)).has(TYPE_LABELS.FEATURE))
-    .map((t) => t.id);
-
-  // cap=4 — Stories are container leaves of this reconcile (their children
-  // are Tasks already settled by reconcileClosedTasks); independent close
-  // mutations can fan out without ordering. Features stay sequential because
-  // a Feature may parent another Feature, and bottom-up close depends on
-  // child-Feature state already being mutated in the same pass.
-  await concurrentMap(storyIds, (id) => maybeClose(id, 'Story'), {
-    concurrency: RECONCILE_CONCURRENCY,
-  });
-  for (const id of featureIds) await maybeClose(id, 'Feature');
-
-  // EXCLUSION: Epic auto-closure removed.
-  // The Epic ticket now stays open until the formal /epic-deliver workflow is executed.
-}