mandrel 1.93.0 → 2.0.0

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

@@ -1,227 +0,0 @@
-import nodeFs from 'node:fs';
-import path from 'node:path';
-import { loadCoverage as defaultLoadCoverage } from '../../../coverage-utils.js';
-import { calculateCrapForSource } from '../../../crap-engine.js';
-import { formatNumber } from './_bullet-format.js';
-import {
-  createDriftDetector,
-  walkComponentRegressions,
-} from './component-drift.js';
-
-const DEFAULT_THRESHOLD = 5.0;
-const DEFAULT_CEILING = 30;
-// Distinct from the canonical ratchet baseline at `baselines/crap.json`
-// (Epic #730 Story 5.5) — this 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-crap-snapshot.json';
-
-/**
- * Normalise a repo-relative path for coverage-key lookup. Pure; exported
- * for unit tests so the underlying branches don't have to be exercised
- * through the closure-bound `findCoverageEntry`.
- */
-export function normaliseCoveragePath(relPath) {
-  return String(relPath)
-    .replace(/\\/g, '/')
-    .replace(/^\.\/+/, '');
-}
-
-/**
- * True when a coverage map key matches a (normalised) relative path,
- * either by full equality or by suffix-with-slash. Pure.
- */
-export function coverageKeyMatches(key, suffix) {
-  const norm = String(key).replace(/\\/g, '/');
-  return norm === suffix || norm.endsWith(`/${suffix}`);
-}
-
-/**
- * Detect per-component CRAP regressions from a baseline rollup against the
- * gate's configured floors. Pure — the caller loads the baseline via
- * `lib/baselines/reader.js#load('crap')` and passes the resulting
- * `{ rollup }` plus the gate config block.
- *
- * Bullet shape (Task #1919, Epic #1786):
- *
- *   🧨 crap: <component> <axis> <value> > floor <floor>
- *
- * CRAP is a "lower is better" gate — 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, cap) => value > cap,
-    formatBullet: (name, axis, value, cap) =>
-      `🧨 crap: ${name} ${axis} ${formatNumber(value)} > floor ${formatNumber(cap)}`,
-  });
-}
-
-/**
- * Detects per-method CRAP drift versus a wave-start baseline.
- *
- * Mirrors the `maintainability-drift.js` contract but at per-method
- * granularity: baseline snapshots are `{ "<file>::<method>@<startLine>": crap }`
- * rather than a single score per file. A method surfaces as a Notable bullet
- * when either condition holds:
- *
- *   - **Crossed the ceiling** — current CRAP ≥ `ceiling` and baseline was
- *     either absent or below `ceiling`. Captures newly introduced hotspots
- *     and methods that tipped over the budget.
- *   - **Rose by ≥ threshold** — baseline present and `current - baseline ≥
- *     threshold`. Captures silent regressions that stay under the ceiling
- *     but are trending badly.
- *
- * Bullet shape:
- *
- *   🧨 CRAP drift: <file>::<method> <score> (ceiling <N>)
- *
- * Persistence: baseline is written to `<cwd>/<baselineDir>/wave-crap-snapshot.json`
- * so a resumed epic run can reuse the wave-start anchor rather than lose it.
- *
- * Resilience: read / scoring errors for an individual file are swallowed (and
- * optionally logged) so a single unscorable file cannot take the progress
- * reporter down.
- *
- * @param {{
- *   cwd?: string,
- *   files?: string[],
- *   fs?: { readFileSync: Function, writeFileSync?: Function, mkdirSync?: Function, existsSync?: Function },
- *   calculate?: (source: string, coverageForFile: object|null) => Array<{ method: string, startLine: number, crap: number|null }>,
- *   loadCoverage?: (coveragePath: string) => object|null,
- *   coveragePath?: string | null,
- *   threshold?: number,
- *   ceiling?: number,
- *   baselineDir?: string,
- *   logger?: { warn?: Function },
- * }} [opts]
- */
-export function createCrapDriftDetector(opts = {}) {
-  const fs = opts.fs ?? nodeFs;
-  const cwd = opts.cwd ?? process.cwd();
-  const files = Array.isArray(opts.files) ? [...opts.files] : [];
-  const calculate = opts.calculate ?? calculateCrapForSource;
-  const loadCoverage = opts.loadCoverage ?? defaultLoadCoverage;
-  const coveragePath = opts.coveragePath ?? null;
-  const threshold = Number.isFinite(opts.threshold)
-    ? opts.threshold
-    : DEFAULT_THRESHOLD;
-  const ceiling = Number.isFinite(opts.ceiling)
-    ? opts.ceiling
-    : DEFAULT_CEILING;
-  const logger = opts.logger ?? null;
-
-  function methodKey(method, startLine) {
-    return `${method}@${startLine}`;
-  }
-
-  // Hoisted helpers — exported via `_internal` for unit coverage on each
-  // branch. Keeping them outside the closure keeps the orchestration
-  // method's complexity low.
-  // (see normaliseCoveragePath / coverageKeyMatches at module top.)
-  function findCoverageEntry(coverageMap, relPath) {
-    if (!coverageMap || typeof coverageMap !== 'object') return null;
-    const suffix = normaliseCoveragePath(relPath);
-    if (!suffix) return null;
-    for (const key of Object.keys(coverageMap)) {
-      if (coverageKeyMatches(key, suffix)) {
-        return coverageMap[key] ?? null;
-      }
-    }
-    return null;
-  }
-
-  function scoreFile(relPath, coverageMap) {
-    try {
-      const abs = path.join(cwd, relPath);
-      const src = fs.readFileSync(abs, 'utf-8');
-      const entry = findCoverageEntry(coverageMap, relPath);
-      const rows = calculate(src, entry) ?? [];
-      const methods = {};
-      for (const row of rows) {
-        if (!row || typeof row.method !== 'string') continue;
-        if (typeof row.startLine !== 'number') continue;
-        if (typeof row.crap !== 'number' || !Number.isFinite(row.crap))
-          continue;
-        methods[methodKey(row.method, row.startLine)] = {
-          method: row.method,
-          startLine: row.startLine,
-          crap: row.crap,
-        };
-      }
-      return methods;
-    } catch (err) {
-      logger?.warn?.(
-        `[crap-drift] scoring failed for ${relPath}: ${err?.message ?? err}`,
-      );
-      return null;
-    }
-  }
-
-  function readCoverageMap() {
-    if (!coveragePath) return null;
-    try {
-      return loadCoverage(coveragePath);
-    } catch (err) {
-      logger?.warn?.(
-        `[crap-drift] coverage load failed (${coveragePath}): ${err?.message ?? err}`,
-      );
-      return null;
-    }
-  }
-
-  return createDriftDetector({
-    fs,
-    cwd,
-    files: opts.files,
-    baselineDir: opts.baselineDir,
-    baselineFilename: BASELINE_FILENAME,
-    metadata: { ceiling, threshold },
-    beforeScore: readCoverageMap,
-    scoreFile,
-    captureScore: (methods) => {
-      const persisted = {};
-      for (const [key, row] of Object.entries(methods)) {
-        persisted[key] = row.crap;
-      }
-      return persisted;
-    },
-    async detect({ baseline, scoreFile: score }) {
-      const bullets = [];
-      // Union of files watched and files present in baseline, so methods that
-      // appeared since the snapshot (new files) are still checked, and methods
-      // that disappeared from baseline-only files don't get us stuck iterating
-      // anything spurious.
-      const fileSet = new Set([...files, ...Object.keys(baseline)]);
-      for (const relPath of fileSet) {
-        const currentMethods = score(relPath);
-        if (!currentMethods) continue;
-        const fileBaseline = baseline[relPath] ?? {};
-        for (const [key, row] of Object.entries(currentMethods)) {
-          const prev = fileBaseline[key];
-          const crossed =
-            row.crap >= ceiling &&
-            (prev === undefined || prev === null || prev < ceiling);
-          const rose =
-            typeof prev === 'number' &&
-            Number.isFinite(prev) &&
-            row.crap - prev >= threshold;
-          if (crossed || rose) {
-            bullets.push(
-              `🧨 CRAP drift: ${relPath}::${row.method} ${row.crap.toFixed(2)} (ceiling ${ceiling})`,
-            );
-          }
-        }
-      }
-      return bullets;
-    },
-  });
-}

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',
-      };
-    });
-  }
-}