mandrel 1.94.0 → 2.0.0

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

@@ -1,117 +0,0 @@
-import nodeFs from 'node:fs';
-import path from 'node:path';
-
-import { calculateForSource } from '../../../maintainability-engine.js';
-import { formatNumber } from './_bullet-format.js';
-import {
-  createDriftDetector,
-  walkComponentRegressions,
-} from './component-drift.js';
-
-const DEFAULT_THRESHOLD = 2.0;
-// Distinct from the canonical ratchet baseline at `baselines/maintainability.json`
-// (Epic #730 Story 5.5) — this file is a per-wave drift SNAPSHOT, not the
-// committed score baseline. Filename intentionally differs so a repo-wide
-// grep for the canonical baseline no longer hits the snapshot.
-const BASELINE_FILENAME = 'wave-mi-snapshot.json';
-
-/**
- * Detect per-component maintainability regressions from a baseline rollup
- * against the gate's configured floors. Pure — the caller loads the
- * baseline via `lib/baselines/reader.js#load('maintainability')` and passes
- * the resulting `{ rollup }` plus the gate config block.
- *
- * Bullet shape (Task #1919, Epic #1786):
- *
- *   📉 maintainability: <component> <axis> <value> < floor <floor>
- *
- * Maintainability is "higher is better" — every axis breach reports when
- * `value < floor`. Component-scoped breaches do NOT trigger a `*` bullet
- * unless `*` itself breaches. The walk itself is the shared
- * `component-drift.js` helper (Story #3984).
- *
- * @param {{
- *   rollup?: Record<string, Record<string, number>>,
- *   gateConfig?: { floors?: Record<string, Record<string, number>> } & object,
- * }} params
- * @returns {string[]}
- */
-export function detectComponentRegressions(params = {}) {
-  return walkComponentRegressions(params, {
-    isBreach: (value, target) => value < target,
-    formatBullet: (name, axis, value, target) =>
-      `📉 maintainability: ${name} ${axis} ${formatNumber(value)} < floor ${formatNumber(target)}`,
-  });
-}
-
-/**
- * Detects per-file maintainability drop versus a wave-start baseline.
- *
- * Usage:
- *   const detector = createMaintainabilityDriftDetector({ cwd, files });
- *   detector.captureBaseline();   // call once at wave-start
- *   await detector.detect(rows);  // call each progress fire
- *
- * A baseline is a map of file -> score, persisted to
- * `<cwd>/<baselineDir>/wave-mi-snapshot.json` so that a resumed epic
- * run can re-read the snapshot from the previous wave rather than lose the
- * anchor. Any file whose score has dropped by >= `threshold` since baseline
- * is surfaced as a bullet:
- *
- *   📉 Maintainability drift: <file> -<n.nn> vs wave-start baseline
- *
- * Errors while reading/scoring individual files are swallowed — a single
- * bad file must not take the progress reporter down.
- *
- * @param {{
- *   cwd?: string,
- *   files?: string[],               // files to watch; repo-relative paths
- *   fs?: { readFileSync: Function, writeFileSync?: Function, mkdirSync?: Function, existsSync?: Function },
- *   calculate?: (source: string) => number,
- *   threshold?: number,             // drop (baseline - current) that trips a bullet
- *   baselineDir?: string,           // directory (under cwd) to persist snapshot
- * }} [opts]
- */
-export function createMaintainabilityDriftDetector(opts = {}) {
-  const fs = opts.fs ?? nodeFs;
-  const cwd = opts.cwd ?? process.cwd();
-  const calculate = opts.calculate ?? calculateForSource;
-  const threshold = Number.isFinite(opts.threshold)
-    ? opts.threshold
-    : DEFAULT_THRESHOLD;
-
-  function scoreFile(relPath) {
-    try {
-      const abs = path.join(cwd, relPath);
-      const src = fs.readFileSync(abs, 'utf-8');
-      const score = calculate(src);
-      return Number.isFinite(score) ? score : null;
-    } catch {
-      return null;
-    }
-  }
-
-  return createDriftDetector({
-    fs,
-    cwd,
-    files: opts.files,
-    baselineDir: opts.baselineDir,
-    baselineFilename: BASELINE_FILENAME,
-    scoreFile,
-    captureScore: (score) => score,
-    async detect({ baseline, scoreFile: score }) {
-      const bullets = [];
-      for (const [relPath, baseScore] of Object.entries(baseline)) {
-        const current = score(relPath);
-        if (current == null) continue;
-        const drop = baseScore - current;
-        if (drop >= threshold) {
-          bullets.push(
-            `📉 Maintainability drift: ${relPath} -${drop.toFixed(2)} vs wave-start baseline`,
-          );
-        }
-      }
-      return bullets;
-    },
-  });
-}

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

@@ -1,37 +0,0 @@
-import nodeFs from 'node:fs';
-import path from 'node:path';
-
-/**
- * Detects "worktree residue" — stories that the ticket graph reports as done,
- * but whose `.worktrees/story-<id>/` directory is still on disk. This usually
- * means story-close failed to reap the worktree (see the Windows
- * partial-reap failure mode in friction memory), and a future run of the
- * same story id would collide with the stale directory.
- *
- * The detector is pure (aside from fs reads) and accepts an fs adapter so the
- * unit test can drive present/absent cases without touching disk.
- *
- * @param {{
- *   fs?: { existsSync: (p: string) => boolean },
- *   cwd?: string,
- * }} [opts]
- * @returns {(rows: Array<{id:number|string, state:string}>) => Promise<string[]>}
- */
-export function createStalledWorktreeDetector(opts = {}) {
-  const fs = opts.fs ?? nodeFs;
-  const cwd = opts.cwd ?? process.cwd();
-  return async function detect(rows = []) {
-    const bullets = [];
-    for (const row of rows) {
-      if (row?.state !== 'done') continue;
-      const relPath = `.worktrees/story-${row.id}`;
-      const absPath = path.join(cwd, relPath);
-      if (fs.existsSync(absPath)) {
-        bullets.push(
-          `⚠️ Worktree residue: #${row.id} marked done but .worktrees/story-${row.id}/ still present`,
-        );
-      }
-    }
-    return bullets;
-  };
-}

package/.agents/scripts/lib/orchestration/epic-runner/story-launcher.js

@@ -1,127 +0,0 @@
-/**
- * StoryLauncher — produces the per-wave dispatch plan and (optionally)
- * delegates execution to an injected `dispatch` adapter.
- *
- * After Story #908, in-session Agent-tool fan-out replaces the subprocess
- * spawn pipeline. The launcher's primary responsibility is `planWave(stories)`:
- * given a wave's Story tickets it returns a stable list of
- * `{ storyId, worktree }` entries. The `/deliver` skill consumes that
- * list (one wave at a time) to format one assistant turn containing N
- * parallel `Agent` tool calls (subagent_type `general-purpose`), each of
- * which drives `/deliver <storyId>` for one Story.
- *
- * `launchWave(stories)` is a convenience for callers that already hold a
- * concrete dispatch adapter (tests, future programmatic harnesses). It calls
- * `planWave` and forwards the plan to `dispatch({ plan, concurrencyCap, signal })`,
- * returning the adapter's result list. The CLI does not provide a default
- * dispatch adapter — invoking the engine without one is an explicit error.
- */
-
-const DEFAULT_TIMEOUT_MS = 6 * 60 * 60 * 1000;
-
-export class StoryLauncher {
-  /**
-   * @param {{
-   *   ctx?: { dispatch?: Function, concurrencyCap?: number, worktreeResolver?: (storyId: number) => string, logger?: object },
-   *   concurrencyCap?: number,
-   *   dispatch?: (args: { plan: Array<{ storyId: number, worktree?: string }>, concurrencyCap: number, signal?: AbortSignal }) => Promise<Array<{ storyId: number, status: string, detail?: string }>>,
-   *   worktreeResolver?: (storyId: number) => string,
-   *   timeoutMs?: number,
-   *   logger?: { info: Function, warn: Function, error: Function }
-   * }} opts
-   */
-  constructor(opts = {}) {
-    const ctx = opts?.ctx;
-    const dispatch = opts?.dispatch ?? ctx?.dispatch ?? null;
-    const concurrencyCap = opts?.concurrencyCap ?? ctx?.concurrencyCap;
-    if (!Number.isInteger(concurrencyCap) || concurrencyCap < 1) {
-      throw new RangeError('concurrencyCap must be a positive integer');
-    }
-    this.concurrencyCap = concurrencyCap;
-    this.dispatch = dispatch;
-    this.worktreeResolver = opts?.worktreeResolver ?? ctx?.worktreeResolver;
-    this.timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    this.logger = opts?.logger ?? ctx?.logger ?? console;
-  }
-
-  /**
-   * Produce the dispatch plan for a wave. Pure: no side effects, no IO. The
-   * caller (the `/deliver` skill's wave loop, or `launchWave` below)
-   * decides what to do with the plan.
-   *
-   * @param {Array<number|{id?:number,storyId?:number,number?:number}>} stories
-   * @returns {Array<{ storyId: number, worktree?: string }>}
-   */
-  planWave(stories) {
-    return (stories ?? []).map((s) => {
-      const storyId =
-        typeof s === 'object' && s !== null
-          ? (s.id ?? s.storyId ?? s.number)
-          : s;
-      const id = Number(storyId);
-      return {
-        storyId: id,
-        worktree: this.worktreeResolver?.(id),
-      };
-    });
-  }
-
-  /**
-   * Plan + dispatch the wave through the injected adapter. Returns one result
-   * entry per input Story preserving input order. Throws when no dispatch
-   * adapter was injected — the engine is no longer callable without one.
-   *
-   * @param {object[]} stories
-   * @param {AbortSignal} [signal]
-   * @returns {Promise<Array<{ storyId: number, status: string, detail?: string }>>}
-   */
-  async launchWave(stories, signal) {
-    if (typeof this.dispatch !== 'function') {
-      throw new TypeError(
-        'StoryLauncher.launchWave requires a dispatch adapter (in-session Agent-tool fan-out is the responsibility of the /deliver skill).',
-      );
-    }
-    const plan = this.planWave(stories);
-    if (plan.length === 0) return [];
-
-    const controller = new AbortController();
-    const timer = setTimeout(
-      () =>
-        controller.abort(new Error(`wave timed out after ${this.timeoutMs}ms`)),
-      this.timeoutMs,
-    );
-    const onParentAbort = () => controller.abort(signal?.reason);
-    signal?.addEventListener?.('abort', onParentAbort, { once: true });
-    try {
-      const results = await this.dispatch({
-        plan,
-        concurrencyCap: this.concurrencyCap,
-        signal: controller.signal,
-      });
-      return this.#alignResults(plan, results);
-    } catch (err) {
-      return plan.map((p) => ({
-        storyId: p.storyId,
-        status: 'failed',
-        detail: err?.message ?? String(err),
-      }));
-    } finally {
-      clearTimeout(timer);
-      signal?.removeEventListener?.('abort', onParentAbort);
-    }
-  }
-
-  #alignResults(plan, results) {
-    const list = Array.isArray(results) ? results : [];
-    const byId = new Map(list.map((r) => [Number(r.storyId), r]));
-    return plan.map((p) => {
-      const r = byId.get(p.storyId);
-      if (r) return { storyId: p.storyId, ...r };
-      return {
-        storyId: p.storyId,
-        status: 'failed',
-        detail: 'dispatch returned no result for this story',
-      };
-    });
-  }
-}

package/.agents/scripts/lib/orchestration/epic-runner/sub-agent-return.js

@@ -1,276 +0,0 @@
-/**
- * sub-agent-return.js — parse and reconcile per-Story sub-agent return text.
- *
- * `/deliver` Step 2 dispatches one `Agent` tool call per Story per
- * wave. Each sub-agent owes its parent the JSON return contract documented
- * in `.agents/workflows/helpers/deliver-epic.md`:
- *
- *   {
- *     "storyId": <number>,
- *     "status": "done" | "blocked" | "failed",
- *     "phase": "init|implementing|closing|blocked|done",
- *     "branchDeleted": <boolean>,
- *     "blockerCommentId": <string|null>,
- *     "detail": <string|undefined>,
- *     "renderedBody": <string|undefined>
- *   }
- *
- * On the current model tier a sub-agent that does real work returns the
- * envelope verbatim; a return that fails to parse is a rare protocol error,
- * not a normal recovery path. Parsing is therefore strict — an already-parsed
- * object or a return string that is pure JSON — with **no free-form
- * extraction heuristics**: the prose-wrapped extraction candidates
- * (fenced ```json``` blocks, balanced-`{...}`-substring scans, chat-prelude
- * tolerance) were measured to never fire in practice (Story #3864:
- * zero malformed terminal returns across the sampled delivered Epics) and
- * were deleted in a hard cutover. A return that does not parse routes
- * directly to GitHub-state reconciliation plus a friction record — the
- * stronger backstop that already caught everything the heuristics caught.
- *
- * This module provides the two helpers `/deliver`'s wave dispatcher
- * now uses:
- *
- *   - `parseStoryAgentReturn(raw)` — accept an already-parsed object or a
- *     return string that is pure JSON, then schema-validate it. Returns
- *     `{ ok: true, value }` on success, `{ ok: false, error }` otherwise.
- *
- *   - `reconcileStoryFromGitHub({ provider, storyId })` — reads the Story
- *     ticket's labels and `story-run-progress` structured comment to derive
- *     an authoritative result row. Used as a fallback whenever the
- *     sub-agent's return text fails to parse. Status is downgraded to
- *     `failed` unless the live ticket actually carries `agent::done`
- *     (in which case the operator may have manually closed the Story).
- */
-
-import { parseFencedJsonComment } from '../structured-comment-parser.js';
-import { findStructuredComment } from '../ticketing.js';
-import { STORY_RUN_PROGRESS_TYPE } from './story-run-progress-writer.js';
-
-const VALID_STATUS = new Set(['done', 'blocked', 'failed']);
-
-/**
- * Strict parse of a per-Story sub-agent return. Accepts:
- *   1. an object that already looks parsed, or
- *   2. a return string that is pure JSON.
- *
- * There is no free-form extraction: a string that is not pure JSON (prose,
- * a fenced block, a chat-prelude + envelope) yields `ok: false` and the
- * caller MUST reconcile from GitHub. Parsing is strict on both sides —
- * callers always get a fully-validated object or `ok: false`.
- *
- * @param {unknown} raw
- * @returns {{ ok: true, value: object } | { ok: false, error: string }}
- */
-export function parseStoryAgentReturn(raw) {
-  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
-    return validateStoryReturnShape(raw);
-  }
-  if (typeof raw !== 'string') {
-    return {
-      ok: false,
-      error: `expected string or object, got ${raw === null ? 'null' : typeof raw}`,
-    };
-  }
-  const trimmed = raw.trim();
-  if (trimmed.length === 0) {
-    return { ok: false, error: 'empty return text' };
-  }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch {
-    return {
-      ok: false,
-      error: `return text is not a JSON envelope (${quote(trimmed)})`,
-    };
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    return {
-      ok: false,
-      error: `return text parsed to a non-object (${quote(trimmed)})`,
-    };
-  }
-  return validateStoryReturnShape(parsed);
-}
-
-/**
- * Validate the per-Story return contract. Pure helper — no IO.
- *
- * @param {object} obj
- * @returns {{ ok: true, value: object } | { ok: false, error: string }}
- */
-function validateStoryReturnShape(obj) {
-  const storyId = Number(obj.storyId ?? obj.id);
-  if (!Number.isInteger(storyId) || storyId <= 0) {
-    return {
-      ok: false,
-      error: `storyId must be a positive integer; got ${JSON.stringify(obj.storyId ?? obj.id)}`,
-    };
-  }
-  const status = String(obj.status ?? '');
-  if (!VALID_STATUS.has(status)) {
-    return {
-      ok: false,
-      error: `status "${status}" must be one of: ${[...VALID_STATUS].join(', ')}`,
-    };
-  }
-  const value = { storyId, status };
-  if (typeof obj.phase === 'string') value.phase = obj.phase;
-  if (typeof obj.branchDeleted === 'boolean') {
-    value.branchDeleted = obj.branchDeleted;
-  }
-  if (obj.blockerCommentId != null) {
-    value.blockerCommentId = String(obj.blockerCommentId);
-  }
-  if (typeof obj.detail === 'string') value.detail = obj.detail;
-  if (typeof obj.renderedBody === 'string')
-    value.renderedBody = obj.renderedBody;
-  return { ok: true, value };
-}
-
-function quote(text) {
-  const oneline = text.replace(/\s+/g, ' ').trim();
-  return oneline.length > 120 ? `${oneline.slice(0, 117)}...` : oneline;
-}
-
-/**
- * Authoritative reconciliation: rebuild a per-Story result row from the
- * Story ticket's live state when the sub-agent return cannot be trusted.
- *
- * The result is always conservative — `status: 'failed'` unless the live
- * ticket carries `agent::done` (or `state: 'closed'`). The phase is
- * best-effort, sourced from the Story's `story-run-progress` comment;
- * absence of the comment is non-fatal.
- *
- * Story #3907 — a Story carrying `agent::blocked` reconciles to
- * `status: 'blocked'`, not `failed`. A garbled / unparseable return from a
- * genuinely blocked child previously collapsed to `failed`, which erased the
- * `blockerCommentId` and steered the operator toward the wrong remediation
- * (re-run vs. resolve-the-blocker). The blocked arm recovers the blocker
- * comment id from the Story's latest `friction` structured comment so the
- * wave row carries it through to `epic-run-progress`.
- *
- * @param {{
- *   provider: { getTicket: Function, getTicketComments: Function },
- *   storyId: number,
- * }} args
- * @returns {Promise<{
- *   storyId: number,
- *   status: 'done' | 'blocked' | 'failed',
- *   phase?: string,
- *   blockerCommentId?: string,
- *   reconciledFromGitHub: true,
- *   reconcileError?: string,
- * }>}
- */
-export async function reconcileStoryFromGitHub({ provider, storyId } = {}) {
-  if (!Number.isInteger(storyId) || storyId <= 0) {
-    throw new TypeError(
-      'reconcileStoryFromGitHub: storyId must be a positive integer',
-    );
-  }
-  if (!provider || typeof provider.getTicket !== 'function') {
-    throw new TypeError(
-      'reconcileStoryFromGitHub: provider.getTicket is required',
-    );
-  }
-
-  let ticket;
-  try {
-    ticket = await provider.getTicket(storyId, { fresh: true });
-  } catch (err) {
-    return {
-      storyId,
-      status: 'failed',
-      reconciledFromGitHub: true,
-      reconcileError: err?.message ?? String(err),
-    };
-  }
-
-  const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
-  const isDone = labels.includes('agent::done') || ticket?.state === 'closed';
-  const isBlocked = !isDone && labels.includes('agent::blocked');
-  let status = 'failed';
-  if (isDone) status = 'done';
-  else if (isBlocked) status = 'blocked';
-
-  const out = { storyId, status, reconciledFromGitHub: true };
-
-  // Story #3907 — for a blocked Story, recover the blocker comment id from
-  // the latest `friction` structured comment so the operator is routed to the
-  // blocker (and its evidence), not a blind re-run. Best-effort: a missing
-  // friction comment leaves `status: 'blocked'` with no id, which is still
-  // strictly more accurate than the old `failed` downgrade.
-  if (isBlocked) {
-    try {
-      const friction = await findStructuredComment(
-        provider,
-        storyId,
-        'friction',
-      );
-      if (friction && friction.id != null) {
-        out.blockerCommentId = String(friction.id);
-      }
-    } catch (err) {
-      out.reconcileError = err?.message ?? String(err);
-    }
-  }
-
-  // Cross-look the story-run-progress comment for the phase when present.
-  // Story #3909 retired the per-Story story-run-progress *comment*
-  // (the redundant mid-flight surface), so this read now usually finds nothing
-  // and the reconciled row degrades to label-only — which is fine: the labels
-  // are the authoritative state. Failure here is non-fatal.
-  try {
-    const comment = await findStructuredComment(
-      provider,
-      storyId,
-      STORY_RUN_PROGRESS_TYPE,
-    );
-    const payload = comment ? parseFencedJsonComment(comment) : null;
-    if (payload && typeof payload === 'object') {
-      if (typeof payload.phase === 'string') out.phase = payload.phase;
-    }
-  } catch (err) {
-    out.reconcileError = err?.message ?? String(err);
-  }
-
-  return out;
-}
-
-/**
- * Render a single friction-comment body listing every malformed sub-agent
- * return for a recorder beat. Pure helper — no provider call. Exposed so
- * tests can pin the body shape.
- *
- * Story #4155 — under the ready-set runtime there is no wave index; the
- * recorder records the Stories it was handed, so the body is keyed by Epic
- * only.
- *
- * @param {{
- *   epicId: number,
- *   failures: Array<{ storyId: number, error: string, returnText: string }>,
- * }} args
- * @returns {string}
- */
-export function renderMalformedReturnsFriction({ epicId, failures }) {
-  const lines = [
-    `### 🚧 epic-execute friction — Epic #${epicId}`,
-    '',
-    `**Reason:** \`malformed-subagent-return\``,
-    '',
-    `${failures.length} sub-agent return(s) did not match the /deliver return contract.`,
-    'Each Story below was reconciled from GitHub (labels + `story-run-progress`)',
-    'and its recorded status downgraded to `failed` unless the live ticket',
-    'already carried `agent::done`.',
-    '',
-  ];
-  for (const f of failures) {
-    lines.push(`- **Story #${f.storyId}** — ${f.error}`);
-    if (f.returnText) {
-      lines.push(`  Original return: \`${quote(f.returnText)}\``);
-    }
-  }
-  return lines.join('\n');
-}

package/.agents/scripts/lib/orchestration/epic-runner/wave-scheduler.js

@@ -1,66 +0,0 @@
-/**
- * WaveScheduler — iterates the wave DAG returned by `Graph.computeWaves()`.
- *
- * Tracks progress (current wave index, waves completed) but never spawns
- * workers. The `story-launcher` consumes the stories it yields.
- */
-
-export class WaveScheduler {
-  /**
-   * @param {object[][]} waves - Array of waves, each a list of story objects.
-   */
-  constructor(waves) {
-    if (!Array.isArray(waves)) {
-      throw new TypeError('WaveScheduler expects a waves array');
-    }
-    this.waves = waves;
-    this.currentIndex = 0;
-    this.completed = new Set();
-  }
-
-  get totalWaves() {
-    return this.waves.length;
-  }
-
-  get currentWave() {
-    return this.currentIndex;
-  }
-
-  hasMoreWaves() {
-    return this.currentIndex < this.waves.length;
-  }
-
-  /**
-   * Returns the next wave to dispatch and advances the pointer. Returns null
-   * if no waves remain.
-   *
-   * @returns {{ index: number, stories: object[] } | null}
-   */
-  nextWave() {
-    if (!this.hasMoreWaves()) return null;
-    const index = this.currentIndex;
-    const stories = this.waves[index];
-    this.currentIndex += 1;
-    return { index, stories };
-  }
-
-  /**
-   * Marks a previously-yielded wave as complete. Idempotent. Throws if the
-   * index is out of range or refers to a wave not yet yielded.
-   *
-   * @param {number} index
-   */
-  markWaveComplete(index) {
-    if (!Number.isInteger(index) || index < 0 || index >= this.waves.length) {
-      throw new RangeError(`Wave index ${index} is out of range`);
-    }
-    if (index >= this.currentIndex) {
-      throw new Error(`Wave ${index} has not been yielded yet`);
-    }
-    this.completed.add(index);
-  }
-
-  completedWaves() {
-    return [...this.completed].sort((a, b) => a - b);
-  }
-}