mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/orchestration/preflight-cache.js

@@ -1,187 +0,0 @@
-/**
- * preflight-cache.js — Epic #3019 / Story #3027.
- *
- * Legacy cache adapter for the snapshot/DAG envelope the deleted
- * `epic-deliver-preflight.js` / `epic-deliver-prepare.js` pair produced
- * (pre-v2 Epic `/deliver`). Retained so fingerprint helpers and tests stay
- * stable; no live v2 entry seam reads or writes this cache.
- *
- * Contract:
- *   - Cache file lives at `<cwd>/temp/epic-<epicId>/preflight-snapshot.json`.
- *   - Envelope shape:
- *       {
- *         epicId: number,
- *         baseSha: string,        // deterministic fingerprint of the Epic
- *                                 // snapshot returned by provider.getTicket
- *         capturedAt: string,     // ISO-8601 timestamp
- *         epic: object,           // the snapshot from runSnapshotPhase
- *         stories: object[],      // the open Story tickets from runBuildWaveDagPhase
- *         waves: Array<Array<object>>, // wave DAG (ids + labels preserved)
- *       }
- *   - `computeBaseSha(epic)` derives the cache key from the same provider
- *     call (`getTicket(epicId)`) used to walk the hierarchy. The hash
- *     covers the Epic's id, body, labels (sorted), and (when present)
- *     `updatedAt` — the same fields that drive Story discovery and the
- *     acceptance start gate (the Epic body's ## Acceptance Table).
- *   - Cache miss is signalled by `readCache` returning `null`. Callers
- *     MUST fall back to a fresh snapshot/DAG pass.
- *   - `writeCache` creates the parent directory recursively and writes
- *     atomically (write to `<path>.tmp` then rename).
- *
- * The module is pure JS / node:fs — no provider dependency — so tests
- * can exercise it without spinning up a GitHub mock.
- */
-
-import { createHash } from 'node:crypto';
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-
-/**
- * Resolve the on-disk path for an Epic's preflight cache.
- *
- * @param {{ epicId: number, cwd?: string }} args
- * @returns {string}
- */
-export function preflightCachePath({ epicId, cwd }) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError(
-      'preflightCachePath: epicId must be a positive integer',
-    );
-  }
-  const root = cwd ?? process.cwd();
-  return path.join(root, 'temp', `epic-${epicId}`, 'preflight-snapshot.json');
-}
-
-/**
- * Per-ticket fingerprint fields shared by the Epic and each Story in the
- * cache key: id, body, sorted labels, and updatedAt. Story bodies carry
- * the dependency edges, so hashing them means a Story-dependency edit
- * forces a cache miss (Story #4019 — the previous Epic-only key let
- * dependency edits slip through unnoticed).
- *
- * @param {{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }} ticket
- * @returns {{ id: number|string|null, body: string, labels: string[], updatedAt: string|null }}
- */
-function ticketFingerprint(ticket) {
-  const t = ticket && typeof ticket === 'object' ? ticket : {};
-  return {
-    id: t.id ?? t.number ?? null,
-    body: typeof t.body === 'string' ? t.body : '',
-    labels: Array.isArray(t.labels) ? [...t.labels].map(String).sort() : [],
-    updatedAt: typeof t.updatedAt === 'string' ? t.updatedAt : null,
-  };
-}
-
-/**
- * Stable string fingerprint of an Epic snapshot **plus its Story
- * dependency state**. The hash is keyed on the exact fields
- * `runSnapshotPhase` reads (`getTicket(epicId)` return value) and on each
- * Story's id/body/labels/updatedAt, so that any drift the snapshot or
- * wave-DAG phases would observe — including a Story-dependency edit —
- * forces a cache miss (Story #4019).
- *
- * Labels are sorted to absorb GitHub's non-deterministic label order
- * across responses; stories are sorted by id so enumeration order never
- * perturbs the key. The hash is sha256; we return the full hex digest so
- * the cache key is collision-resistant for the lifetime of a delivery.
- *
- * @param {{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }} epic
- * @param {Array<{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }>} [stories]
- * @returns {string}
- */
-export function computeBaseSha(epic, stories = []) {
-  if (!epic || typeof epic !== 'object') {
-    throw new TypeError('computeBaseSha: epic snapshot must be an object');
-  }
-  const epicPrint = ticketFingerprint(epic);
-  const storyPrints = (Array.isArray(stories) ? stories : [])
-    .map(ticketFingerprint)
-    .sort((a, b) => Number(a.id ?? 0) - Number(b.id ?? 0));
-  const payload = JSON.stringify({ ...epicPrint, stories: storyPrints });
-  return createHash('sha256').update(payload).digest('hex');
-}
-
-/**
- * Read the cached preflight envelope from disk. Returns `null` when the
- * file is missing or unreadable — callers MUST treat that as a cache
- * miss and fall back to a fresh snapshot/DAG pass.
- *
- * The function intentionally swallows `ENOENT` and JSON-parse errors so
- * a stale or partially-written file does not poison legacy Epic prepare callers.
- *
- * @param {{ epicId: number, cwd?: string }} args
- * @returns {Promise<object | null>}
- */
-export async function readPreflightCache({ epicId, cwd }) {
-  const cachePath = preflightCachePath({ epicId, cwd });
-  let raw;
-  try {
-    raw = await readFile(cachePath, 'utf8');
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    throw err;
-  }
-  try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    if (parsed.epicId !== epicId) return null;
-    if (typeof parsed.baseSha !== 'string' || !parsed.baseSha) return null;
-    if (!parsed.epic || typeof parsed.epic !== 'object') return null;
-    if (!Array.isArray(parsed.stories)) return null;
-    if (!Array.isArray(parsed.waves)) return null;
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Persist the preflight envelope to disk. Writes atomically via tmp +
- * rename so concurrent readers never observe a partial file.
- *
- * @param {{ epicId: number, baseSha: string, epic: object, stories: object[], waves: Array<Array<object>>, cwd?: string, capturedAt?: string }} args
- * @returns {Promise<{ cachePath: string, baseSha: string }>}
- */
-export async function writePreflightCache({
-  epicId,
-  baseSha,
-  epic,
-  stories,
-  waves,
-  cwd,
-  capturedAt,
-}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError(
-      'writePreflightCache: epicId must be a positive integer',
-    );
-  }
-  if (typeof baseSha !== 'string' || !baseSha) {
-    throw new TypeError(
-      'writePreflightCache: baseSha must be a non-empty string',
-    );
-  }
-  if (!epic || typeof epic !== 'object') {
-    throw new TypeError('writePreflightCache: epic must be an object');
-  }
-  if (!Array.isArray(stories)) {
-    throw new TypeError('writePreflightCache: stories must be an array');
-  }
-  if (!Array.isArray(waves)) {
-    throw new TypeError('writePreflightCache: waves must be an array');
-  }
-  const cachePath = preflightCachePath({ epicId, cwd });
-  await mkdir(path.dirname(cachePath), { recursive: true });
-  const envelope = {
-    epicId,
-    baseSha,
-    capturedAt: capturedAt ?? new Date().toISOString(),
-    epic,
-    stories,
-    waves,
-  };
-  const tmp = `${cachePath}.tmp`;
-  await writeFile(tmp, `${JSON.stringify(envelope, null, 2)}\n`, 'utf8');
-  await rename(tmp, cachePath);
-  return { cachePath, baseSha };
-}

package/.agents/scripts/lib/orchestration/resolve-plan-run.js

@@ -1,155 +0,0 @@
-/**
- * Pure helpers for resolve-plan-run.js — keep the CLI entry thin so new-file
- * CRAP stays under the quality-preview ceiling.
- *
- * @module lib/orchestration/resolve-plan-run
- */
-
-import { TYPE_LABELS } from '../label-constants.js';
-import { buildStoryAdjacency } from '../story-adjacency.js';
-import {
-  normalizePlanRunId,
-  PLAN_RUN_LABEL_PREFIX,
-} from './plan-persist/story-ops.js';
-
-/**
- * Normalize a plan-run id into the canonical label `plan-run::<token>`.
- *
- * @param {string} raw
- * @returns {string}
- */
-export function normalizePlanRunLabel(raw) {
-  const token = normalizePlanRunId(raw);
-  return `${PLAN_RUN_LABEL_PREFIX}${token}`;
-}
-
-/**
- * Extract a bare plan-run id from a label or raw token.
- *
- * @param {string} label
- * @returns {string}
- */
-export function planRunIdFromLabel(label) {
-  return String(label ?? '')
-    .trim()
-    .replace(new RegExp(`^${PLAN_RUN_LABEL_PREFIX}`), '');
-}
-
-/**
- * @param {object} issue
- * @returns {string[]}
- */
-export function normalizeIssueLabels(issue) {
-  const raw = issue?.labels;
-  if (!Array.isArray(raw)) return [];
-  return raw
-    .map((l) => (typeof l === 'string' ? l : l?.name))
-    .filter((n) => typeof n === 'string' && n.length > 0);
-}
-
-/**
- * @param {object} issue
- * @returns {{ id: number, title: string, body: string, url: string|null, labels: string[], state: string }|null}
- */
-export function toStoryRecord(issue) {
-  const id = Number(issue?.number ?? issue?.id);
-  if (!Number.isInteger(id) || id <= 0) return null;
-  const labels = normalizeIssueLabels(issue);
-  if (!labels.includes(TYPE_LABELS.STORY)) return null;
-  return {
-    id,
-    title: String(issue?.title ?? ''),
-    body: String(issue?.body ?? ''),
-    url: issue?.html_url ?? issue?.url ?? null,
-    labels,
-    state: String(issue?.state ?? 'open').toLowerCase(),
-  };
-}
-
-/**
- * @param {object[]} stories
- * @returns {{ id: number, dependsOn: number[] }[]}
- */
-export function storiesToDag(stories) {
-  const adjacency = buildStoryAdjacency(stories, { dropForeign: false });
-  return stories.map((s) => ({
-    id: s.id,
-    dependsOn: adjacency.get(s.id) ?? [],
-  }));
-}
-
-/**
- * Map provider issues into the deliver-router story list + DAG nodes.
- *
- * @param {object[]} issues
- * @param {{ planRunId: string, planRunLabel: string }} meta
- * @returns {{ kind: string, planRunId: string, planRunLabel: string, stories: object[], dag: object[] }}
- */
-export function buildPlanRunEnvelope(issues, { planRunId, planRunLabel }) {
-  const stories = (Array.isArray(issues) ? issues : [])
-    .map(toStoryRecord)
-    .filter(Boolean)
-    .sort((a, b) => a.id - b.id);
-
-  return {
-    kind: 'plan-run',
-    planRunId,
-    planRunLabel,
-    stories: stories.map(({ id, title, url, labels, state }) => ({
-      id,
-      title,
-      url,
-      labels,
-      state,
-    })),
-    dag: storiesToDag(stories),
-    done: stories
-      .filter(
-        (story) =>
-          story.state === 'closed' || story.labels.includes('agent::done'),
-      )
-      .map((story) => story.id),
-  };
-}
-
-/**
- * Pure core used by tests: given issues + meta, build the envelope.
- *
- * @param {{ run: string, issues: object[] }} args
- * @returns {ReturnType<typeof buildPlanRunEnvelope>}
- */
-export function resolvePlanRunFromIssues({ run, issues }) {
-  const planRunLabel = normalizePlanRunLabel(run);
-  const planRunId = planRunIdFromLabel(planRunLabel);
-  return buildPlanRunEnvelope(issues, { planRunId, planRunLabel });
-}
-
-/**
- * Fetch issues for a plan-run label via the ticketing provider.
- *
- * @param {object} provider
- * @param {{ planRunLabel: string, state: string }} args
- * @returns {Promise<object[]>}
- */
-export async function fetchPlanRunIssues(provider, { planRunLabel, state }) {
-  if (typeof provider?.listIssuesByLabel !== 'function') {
-    throw new Error('resolve-plan-run: provider.listIssuesByLabel is required');
-  }
-  const labels = `${planRunLabel},${TYPE_LABELS.STORY}`;
-  const issues = await provider.listIssuesByLabel({ state, labels });
-  return Array.isArray(issues) ? issues : [];
-}
-
-/**
- * @param {string|undefined} state
- * @returns {string}
- */
-export function assertIssueState(state) {
-  const value = state ?? 'open';
-  if (!['open', 'closed', 'all'].includes(value)) {
-    throw new Error(
-      `resolve-plan-run: --state must be open|closed|all (got ${value})`,
-    );
-  }
-  return value;
-}

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 (code constants only — not operator-tunable via
- * `.agentrc.json`; the former `delivery.retro.perfThresholds` key was
- * retired):
- *
- *   - `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
- * `DEFAULT_RETRO_PERF_THRESHOLDS` below.
- */
-
-/**
- * Framework-fixed defaults for `classifyPerfSignals`. Callers (and tests)
- * can omit `thresholds` and get these values. Not sourced from agentrc —
- * edit this constant (and keep tests in lockstep) to change the gates.
- */
-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;
-}