mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/retro-perf-heuristics.js

@@ -1,275 +0,0 @@
-/**
- * lib/orchestration/retro-perf-heuristics.js — classify perf signals.
- *
- * Story #3042 / Task #3045 (Epic #3019). Pure functions that turn the
- * `epic-perf-report.waveParallelism` row shape (Story #3025) into a flat
- * list of perf signals. The retro renderer (`./retro/phases/compose-body.js`)
- * consumes the list to surface a `## Performance Signals` section and a
- * `## Recommended Follow-Ons` paste-ready stanza per signal.
- *
- * Signals (kinds):
- *
- *   - `low-utilisation` — any wave whose `utilisation < thresholds.utilisation`.
- *     One signal per offending wave. The signal carries the wave index and
- *     the observed utilisation so the renderer can name the offender.
- *
- *   - `high-bootstrap-share` — emitted when the summed `story-init` /
- *     bootstrap phase time across all waves exceeds
- *     `thresholds.bootstrapShare` of the cumulative `summedStoryMs`. This is
- *     a single signal across the whole report (not one per wave) because the
- *     framework remediation is an Epic-wide bootstrap-cost story, not a
- *     per-wave tweak. The signal payload carries the observed share.
- *
- *   - `cap-binding-run` — emitted when `>= thresholds.capBindingRunLength`
- *     consecutive waves report `capBinding: true`. One signal per maximal
- *     run, carrying the run's first/last wave index and the run length so
- *     the renderer can attribute the run-length back to the deliver-runner
- *     concurrency cap.
- *
- * Threshold contract (`.agentrc.json → delivery.retro.perfThresholds`):
- *
- *   - `utilisation`: number in [0, 1]. Default 0.6.
- *   - `bootstrapShare`: number in [0, 1]. Default 0.4.
- *   - `capBindingRunLength`: positive integer. Default 2.
- *
- * The function is total: it never throws on malformed input. A missing or
- * malformed `report` returns `[]`. A missing `thresholds` falls back to the
- * documented defaults.
- */
-
-/**
- * Defaults mirroring `.agentrc.json → delivery.retro.perfThresholds` so
- * callers (and tests) can omit `thresholds` and get the same behaviour as
- * a resolved config with no overrides. Keep in lockstep with
- * `lib/config/runners.js` (or wherever the resolver default lives) and the
- * `agentrc.schema.json` defaults stanza.
- */
-export const DEFAULT_RETRO_PERF_THRESHOLDS = Object.freeze({
-  utilisation: 0.6,
-  bootstrapShare: 0.4,
-  capBindingRunLength: 2,
-});
-
-function isObject(v) {
-  return v != null && typeof v === 'object' && !Array.isArray(v);
-}
-
-function clampUnit(n, fallback) {
-  if (typeof n !== 'number' || !Number.isFinite(n)) return fallback;
-  // Out-of-range values fall back to the documented default rather than
-  // being clamped — operators wiring nonsensical thresholds should see the
-  // safe default applied, not a silent 0/1 substitute that subtly changes
-  // the heuristic.
-  if (n < 0 || n > 1) return fallback;
-  return n;
-}
-
-function positiveInt(n, fallback) {
-  if (typeof n !== 'number' || !Number.isFinite(n)) return fallback;
-  if (!Number.isInteger(n) || n < 1) return fallback;
-  return n;
-}
-
-/**
- * Resolve the threshold trio against the documented defaults. Exported for
- * the test surface so callers can verify the fallback semantics in
- * isolation.
- *
- * @param {object|null|undefined} thresholds
- * @returns {{ utilisation: number, bootstrapShare: number, capBindingRunLength: number }}
- */
-export function resolvePerfThresholds(thresholds) {
-  const src = isObject(thresholds) ? thresholds : {};
-  return {
-    utilisation: clampUnit(
-      src.utilisation,
-      DEFAULT_RETRO_PERF_THRESHOLDS.utilisation,
-    ),
-    bootstrapShare: clampUnit(
-      src.bootstrapShare,
-      DEFAULT_RETRO_PERF_THRESHOLDS.bootstrapShare,
-    ),
-    capBindingRunLength: positiveInt(
-      src.capBindingRunLength,
-      DEFAULT_RETRO_PERF_THRESHOLDS.capBindingRunLength,
-    ),
-  };
-}
-
-/**
- * Extract the validated `waveParallelism` rows from the report. Rows whose
- * `waveIndex` is not a non-negative integer are dropped (the schema requires
- * one, but the heuristics module must tolerate malformed historical reports).
- *
- * @param {object|null|undefined} report
- * @returns {Array<{ waveIndex: number, wallClockMs: number, summedStoryMs: number, utilisation: number, capBinding: boolean }>}
- */
-function extractRows(report) {
-  if (!isObject(report)) return [];
-  const arr = Array.isArray(report.waveParallelism)
-    ? report.waveParallelism
-    : [];
-  return arr
-    .filter(
-      (r) => isObject(r) && Number.isInteger(r.waveIndex) && r.waveIndex >= 0,
-    )
-    .map((r) => ({
-      waveIndex: r.waveIndex,
-      wallClockMs:
-        typeof r.wallClockMs === 'number' && r.wallClockMs > 0
-          ? r.wallClockMs
-          : 0,
-      summedStoryMs:
-        typeof r.summedStoryMs === 'number' && r.summedStoryMs > 0
-          ? r.summedStoryMs
-          : 0,
-      utilisation:
-        typeof r.utilisation === 'number' && Number.isFinite(r.utilisation)
-          ? r.utilisation
-          : 0,
-      capBinding: Boolean(r.capBinding),
-    }));
-}
-
-/**
- * Build the `low-utilisation` signals — one per wave whose `utilisation` is
- * strictly below the threshold. Returns `[]` when no row crosses the gate.
- *
- * Waves with `summedStoryMs <= 0` are skipped unconditionally: when no
- * per-Story timing windows are present the computed utilisation is 0.0%
- * because the numerator is 0, not because the wave was genuinely idle.
- * Scoring unknown timing as low would flood the retro with non-actionable
- * follow-ons (Story #3850).
- */
-function detectLowUtilisation(rows, threshold) {
-  const out = [];
-  for (const row of rows) {
-    // Skip waves with no timing data — utilisation is unknown, not low.
-    if (row.summedStoryMs <= 0) continue;
-    if (row.utilisation < threshold) {
-      out.push({
-        kind: 'low-utilisation',
-        waveIndex: row.waveIndex,
-        utilisation: row.utilisation,
-        threshold,
-      });
-    }
-  }
-  return out;
-}
-
-/**
- * Sum the bootstrap (story-init) phase time across per-Story summaries on the
- * report. Returns the absolute milliseconds. Falls back to 0 when no Story
- * summary in the report carries a `phaseTimingsMs['story-init']` entry — in
- * that case the share check necessarily returns no signal.
- */
-function sumBootstrapMs(report) {
-  if (!isObject(report)) return 0;
-  const stories = Array.isArray(report.storyPerfSummaries)
-    ? report.storyPerfSummaries
-    : [];
-  let total = 0;
-  for (const s of stories) {
-    if (!isObject(s)) continue;
-    const timings = isObject(s.phaseTimingsMs) ? s.phaseTimingsMs : null;
-    if (!timings) continue;
-    const v = timings['story-init'];
-    if (typeof v === 'number' && Number.isFinite(v) && v > 0) {
-      total += v;
-    }
-  }
-  return total;
-}
-
-/**
- * Build the (at-most-one) `high-bootstrap-share` signal. Returns `[]` when
- * either the cumulative `summedStoryMs` is zero (no wave timing) or the
- * observed bootstrap share is at-or-below the threshold.
- */
-function detectHighBootstrapShare(rows, report, threshold) {
-  const totalStoryMs = rows.reduce((acc, r) => acc + r.summedStoryMs, 0);
-  if (totalStoryMs <= 0) return [];
-  const bootstrapMs = sumBootstrapMs(report);
-  if (bootstrapMs <= 0) return [];
-  const share = bootstrapMs / totalStoryMs;
-  if (share <= threshold) return [];
-  return [
-    {
-      kind: 'high-bootstrap-share',
-      share,
-      bootstrapMs,
-      summedStoryMs: totalStoryMs,
-      threshold,
-    },
-  ];
-}
-
-/**
- * Walk the rows in `waveIndex` order and emit one `cap-binding-run` signal
- * per maximal run of consecutive `capBinding: true` waves whose length is at
- * least `threshold`.
- */
-function detectCapBindingRuns(rows, threshold) {
-  const ordered = [...rows].sort((a, b) => a.waveIndex - b.waveIndex);
-  const out = [];
-  let runStart = null;
-  let runLen = 0;
-  for (let i = 0; i < ordered.length; i += 1) {
-    const row = ordered[i];
-    if (row.capBinding) {
-      if (runStart === null) runStart = row.waveIndex;
-      runLen += 1;
-      // End of array? Flush the run.
-      if (i === ordered.length - 1 && runLen >= threshold) {
-        out.push({
-          kind: 'cap-binding-run',
-          fromWaveIndex: runStart,
-          toWaveIndex: row.waveIndex,
-          runLength: runLen,
-          threshold,
-        });
-      }
-    } else {
-      if (runLen >= threshold && runStart !== null) {
-        out.push({
-          kind: 'cap-binding-run',
-          fromWaveIndex: runStart,
-          toWaveIndex: ordered[i - 1].waveIndex,
-          runLength: runLen,
-          threshold,
-        });
-      }
-      runStart = null;
-      runLen = 0;
-    }
-  }
-  return out;
-}
-
-/**
- * Classify perf signals from an `epic-perf-report` payload.
- *
- * Always returns an array of signal objects. The array is empty when no
- * signal trips. The caller (retro renderer) is responsible for suppressing
- * the entire `## Performance Signals` and `## Recommended Follow-Ons`
- * sections when this returns `[]`.
- *
- * @param {object|null|undefined} report   `epic-perf-report` payload.
- * @param {object|null|undefined} thresholds  Optional override of
- *   `{ utilisation, bootstrapShare, capBindingRunLength }`. Defaults
- *   resolve via `DEFAULT_RETRO_PERF_THRESHOLDS`.
- * @returns {Array<object>} Signal list.
- */
-export function classifyPerfSignals(report, thresholds) {
-  const resolved = resolvePerfThresholds(thresholds);
-  const rows = extractRows(report);
-  if (rows.length === 0) return [];
-  const signals = [];
-  signals.push(...detectLowUtilisation(rows, resolved.utilisation));
-  signals.push(
-    ...detectHighBootstrapShare(rows, report, resolved.bootstrapShare),
-  );
-  signals.push(...detectCapBindingRuns(rows, resolved.capBindingRunLength));
-  return signals;
-}

package/.agents/scripts/lib/orchestration/retro-runner.js

@@ -1,197 +0,0 @@
-/**
- * lib/orchestration/retro-runner.js — In-process Retro module (sequencer).
- *
- * Story #1155 (Epic #1142, 5.40.0) — extracts the helper-driven
- * `epic-retro` invocation into a callable module so the
- * `/deliver` runner can fire Phase E without a separate LLM
- * helper turn. (Story #2259, Epic #2172: the legacy deliver-runner
- * CLI was retired once delivery moved entirely into the slash
- * command.) The retro fires before `/deliver`'s finalize step
- * opens the PR — the operator's PR-merge is the final human gate, not
- * the retro itself.
- *
- * Story #3001 — the runner body was decomposed into `./retro/phases/`
- * (one file per functional unit) following the established pattern at
- * `./git-cleanup/phases/`, `./story-close/phases/`, and
- * `./post-merge/phases/`. This file is now a thin sequencer that owns
- * the `runRetro` entry point and re-exports the phase-level helpers so
- * existing import sites stay unchanged.
- *
- * Public API:
- *   - `runRetro({ epicId, provider, logger })` → `{ posted, compact, scorecard, body, defectClasses }`.
- *   - `composeRetroBody(input)` (pure, exported for tests).
- *   - `gatherRetroSignals({ epicId, provider })` (exported for tests).
- *   - `appendChecksSection(body, findings)` (pure, exported for tests).
- *   - `deriveDefectClasses(routedProposals)` (pure, exported for tests).
- *
- * Story #4135 (Epic #4131, F11) — the runner now derives a
- * **recurring-defect-class signal** from the routed-proposal actionable
- * items (categories that recurred ≥2 times across review/deliver-caught
- * friction, or a force-flagged `agent::blocked` category). The derived
- * classes ride on the `runRetro` envelope as `defectClasses[]` and are
- * stamped onto the proposed `gh issue create` commands as `friction::<class>`
- * labels (the routed-proposals composer already emits that label), which is
- * the durable substrate the `/plan` Phase 0 prior-feedback fetcher reads
- * back to surface recurring classes to the planner. The derivation is
- * **no-op-safe**: absent or empty routed proposals yield an empty array and
- * no behavioural change to the existing retro/post path.
- *
- * Behaviour:
- *   - Reads child Stories' `story-perf-summary` comments to aggregate
- *     `frictionByCategory` totals (Story #1046 unified-summary path).
- *   - Reads child Stories' label sets to count HITL pause events
- *     (`agent::blocked`).
- *   - Reads the Epic's `parked-follow-ons` structured comment for the
- *     parked + recut counts (with a fallback to per-Story body grep on the
- *     `<!-- recut-of: #N -->` marker).
- *   - Selects the compact (clean-manifest) or full retro shape via
- *     `isCleanManifest`.
- *   - Posts the composed markdown as a `retro` structured comment on the
- *     Epic, terminated with the `retro-complete: <ISO>` HTML marker.
- *   - **Never** routes through `notify.js` — GitHub is the sole retro
- *     archive; the webhook must not see the retro body.
- */
-
-import nodeFs from 'node:fs';
-
-import { runChecks } from '../checks/index.js';
-import { assembleState } from '../checks/state.js';
-import { composeRetroBody } from './retro/phases/compose-body.js';
-import { gatherRetroSignals } from './retro/phases/gather-signals.js';
-import { composeAndPostRetro } from './retro/phases/post-and-mirror.js';
-import { upsertStructuredComment } from './ticketing.js';
-
-// Re-export phase-level helpers so existing import sites stay unchanged.
-export { appendChecksSection } from './retro/phases/checks.js';
-export {
-  composeRetroBody,
-  deriveDefectClasses,
-} from './retro/phases/compose-body.js';
-export { gatherRetroSignals } from './retro/phases/gather-signals.js';
-
-/**
- * Public: compose and post the retro structured comment on the Epic.
- *
- * Story #1290 (Epic #1143) — at /deliver Phase 5, the runner invokes
- * the self-healing checks registry with `scope: 'retro'` and
- * `autoFix: false`. The retro is **read-only by construction**: the
- * registry runner enforces the invariant by throwing if any caller flips
- * `autoFix: true` under `scope: 'retro'`. Findings are appended to the
- * retro body via `appendChecksSection`, which suppresses the section when
- * findings are empty so the compact "🟢 Clean sprint" shape is preserved.
- *
- * Story #2252 — when `opts.bus` is supplied the runner emits
- * `retro.start` immediately on entry and `retro.end` immediately before
- * returning the envelope. On throw the helper emits `retro.end` with
- * `posted: false` before re-throwing so the ledger always carries the
- * closing boundary.
- *
- * @param {{
- *   epicId: number,
- *   provider: object,
- *   logger?: { info?: Function, warn?: Function },
- *   forceFull?: boolean,
- *   timestamp?: string,
- *   bus?: object|null,
- *   now?: () => number,
- *   manualInterventions?: number,
- *   frameworkRepo?: string,
- *   consumerRepo?: string,
- *   config?: object|null,
- *   gatherFn?: typeof gatherRetroSignals,
- *   composeFn?: typeof composeRetroBody,
- *   upsertFn?: typeof upsertStructuredComment,
- *   runChecksFn?: typeof runChecks,
- *   assembleStateFn?: typeof assembleState,
- *   cwd?: string,
- * }} opts
- * @returns {Promise<{
- *   posted: boolean,
- *   compact: boolean,
- *   scorecard: object,
- *   body: string,
- *   findings: object[],
- *   defectClasses: Array<{ category: string, occurrences: number, source: 'framework'|'consumer', label: string }>,
- *   commentId?: number,
- * }>}
- */
-export async function runRetro(opts = {}) {
-  const {
-    epicId,
-    provider,
-    logger,
-    forceFull = false,
-    timestamp,
-    bus,
-    now = Date.now,
-    manualInterventions = 0,
-    frameworkRepo,
-    consumerRepo,
-    config = null,
-    gatherFn = gatherRetroSignals,
-    composeFn = composeRetroBody,
-    upsertFn = upsertStructuredComment,
-    runChecksFn = runChecks,
-    assembleStateFn = assembleState,
-    cwd,
-    fsImpl = nodeFs,
-    perfThresholds = null,
-  } = opts;
-
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError('runRetro: epicId is required (positive integer).');
-  }
-  if (!provider) {
-    throw new TypeError('runRetro: provider is required.');
-  }
-  // Epic #2646 Story C (Task #2700) — `bus` is now a hard input. The
-  // previous guarded `emitLifecycleSafe` helper that tolerated a null
-  // bus is gone.
-  if (!bus || typeof bus.emit !== 'function') {
-    throw new TypeError('runRetro: bus is required (object with emit()).');
-  }
-
-  logger?.info?.(`[retro-runner] Composing retro for Epic #${epicId}...`);
-  const startedAt = typeof now === 'function' ? now() : Date.now();
-  await bus.emit('retro.start', { epicId });
-  let retroPathWritten = null;
-  try {
-    return await composeAndPostRetro({
-      epicId,
-      provider,
-      logger,
-      forceFull,
-      timestamp,
-      bus,
-      now,
-      manualInterventions,
-      frameworkRepo,
-      consumerRepo,
-      config,
-      gatherFn,
-      composeFn,
-      upsertFn,
-      runChecksFn,
-      assembleStateFn,
-      cwd,
-      fsImpl,
-      startedAt,
-      perfThresholds,
-      onMirrorWritten: (p) => {
-        retroPathWritten = p;
-      },
-    });
-  } catch (err) {
-    // Surface the closing boundary even on throw — the ledger must
-    // always show a matched start/end pair.
-    const endedAt = typeof now === 'function' ? now() : Date.now();
-    const payload = {
-      epicId,
-      posted: false,
-      durationMs: Math.max(0, Math.floor(endedAt - startedAt)),
-    };
-    if (retroPathWritten) payload.retroPath = retroPathWritten;
-    await bus.emit('retro.end', payload);
-    throw err;
-  }
-}