mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/story-close/phases/refresh.js

@@ -1,86 +0,0 @@
-/**
- * phases/refresh.js — bounded baseline auto-refresh phase (Story #2460,
- * Epic #2453 — CLI thinning pilot).
- *
- * Pre-merge gates have passed; this phase regenerates baseline rows
- * scoped to the Story diff and folds them into HEAD via one canonical
- * `chore(baselines): refresh <kind> for story-<id>` commit per kind that
- * actually drifted. Failure modes are advisory: a regen / amend /
- * signal-write failure is logged but does not block the close.
- *
- * Public surface:
- *   - describeAutoRefreshOutcome(refreshResult)   ← exported (story-close.js re-export)
- *   - reportAutoRefreshOutcome(refreshResult, deps?)
- *   - runAutoRefreshSafely(args, deps?)
- */
-
-import { Logger } from '../../../Logger.js';
-import { runAutoRefresh } from '../auto-refresh-runner.js';
-
-/**
- * Pure: render the AUTO-REFRESH status into a `{channel, message}` log
- * envelope, or `null` for statuses we don't surface. Extracted so the
- * branching lives behind a tested boundary.
- */
-export function describeAutoRefreshOutcome(refreshResult) {
-  if (
-    refreshResult?.status === 'committed' ||
-    refreshResult?.status === 'amended'
-  ) {
-    return {
-      channel: 'progress',
-      label: 'AUTO-REFRESH',
-      message: `Committed bounded baseline drift on Story branch (${refreshResult.sha}).`,
-    };
-  }
-  if (refreshResult?.status === 'refused') {
-    const sig = refreshResult.dedup
-      ? 'already present'
-      : refreshResult.signalAppended
-        ? 'appended'
-        : 'not written';
-    return {
-      channel: 'progress',
-      label: 'AUTO-REFRESH',
-      message: `Refused — ${refreshResult.refusalReasons.length} cap breach(es); friction signal ${sig}.`,
-    };
-  }
-  if (refreshResult?.status === 'failed') {
-    return {
-      channel: 'warn',
-      message: `[auto-refresh] ${refreshResult.reason}: ${refreshResult.detail ?? ''}`,
-    };
-  }
-  return null;
-}
-
-/**
- * Translate the structured outcome into a single log line via the
- * provided `progress` callback (so production wires `progressLog` and
- * tests can pin the channel + label).
- */
-export function reportAutoRefreshOutcome(refreshResult, deps = {}) {
-  const envelope = describeAutoRefreshOutcome(refreshResult);
-  if (!envelope) return;
-  const progress = deps.progress;
-  const logger = deps.logger ?? Logger;
-  if (envelope.channel === 'warn') logger.warn(envelope.message);
-  else if (progress) progress(envelope.label, envelope.message);
-}
-
-/**
- * Story #1398 (Epic #1386) — bounded baseline auto-refresh. Pre-merge
- * gates have passed; regenerate baseline rows scoped to the Story diff
- * and amend them into HEAD if every row's delta is at or below the
- * configured caps. Failure modes are advisory.
- */
-export async function runAutoRefreshSafely(args, deps = {}) {
-  try {
-    const refreshResult = await runAutoRefresh(args);
-    reportAutoRefreshOutcome(refreshResult, deps);
-  } catch (err) {
-    Logger.warn(
-      `[auto-refresh] runner threw: ${err?.stack || err?.message || err}`,
-    );
-  }
-}

package/.agents/scripts/lib/orchestration/story-close/phases/timeout-blocked-emitter.js

@@ -1,112 +0,0 @@
-/**
- * phases/timeout-blocked-emitter.js — side-effecting half of the timeout
- * dispatch phase (Story #2460, Epic #2453 — CLI thinning pilot).
- *
- * Applies the `agent::blocked` transition + the friction comment + the
- * lifecycle-bus emit when one of the close-time bounded-timeout spawns
- * exits 124. All three side-effects are best-effort: a failure here
- * logs and falls through so the close-result envelope reaches the
- * operator regardless.
- *
- * Sibling: `timeout-blocked.js` (pure helpers — the descriptor table,
- * reason-token map, and body renderer). Split out so the side-effects
- * stay isolated and the pure half is trivially testable.
- */
-
-import { Logger } from '../../../Logger.js';
-import {
-  STATE_LABELS,
-  transitionTicketState,
-  upsertStructuredComment,
-} from '../../ticketing.js';
-import { emitBlockedCloseResult } from '../merge-runner.js';
-import {
-  renderSpawnTimeoutFrictionBody,
-  resolveSpawnTimeoutDescriptor,
-  resolveSpawnTimeoutMs,
-} from './timeout-blocked.js';
-
-/**
- * Apply the `agent::blocked` transition + friction comment when one of
- * the close-time spawns exits 124.
- *
- * @param {{
- *   storyId: number|string,
- *   epicId?: number|string|null,
- *   spawnName: string,
- *   spawnCmd?: string|null,
- *   timeoutMs?: number|null,
- *   exitCode?: number|null,
- *   config?: object,
- *   provider: object,
- *   progress: (tag: string, msg: string) => void,
- *   reason?: string,
- *   bus?: object|null,
- * }} input
- */
-export async function emitSpawnTimeoutBlockedResult({
-  storyId,
-  epicId,
-  spawnName,
-  spawnCmd = null,
-  timeoutMs: providedTimeoutMs = null,
-  exitCode = 124,
-  config,
-  provider,
-  progress: log,
-  reason,
-  bus = null,
-}) {
-  const timeoutMs =
-    providedTimeoutMs ?? resolveSpawnTimeoutMs(spawnName, config);
-
-  const body = renderSpawnTimeoutFrictionBody({
-    storyId,
-    epicId,
-    timeoutMs,
-    spawnName,
-    spawnCmd,
-  });
-
-  let commentId = null;
-  try {
-    const res = await upsertStructuredComment(
-      provider,
-      storyId,
-      'friction',
-      body,
-    );
-    commentId = res?.commentId ?? null;
-  } catch (err) {
-    Logger.warn?.(
-      `[story-close] failed to upsert ${spawnName}-timeout friction comment on #${storyId}: ${err?.message ?? err}`,
-    );
-  }
-
-  try {
-    await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {
-      cascade: false,
-    });
-  } catch (err) {
-    Logger.warn?.(
-      `[story-close] failed to transition Story #${storyId} → ${STATE_LABELS.BLOCKED}: ${err?.message ?? err}`,
-    );
-  }
-
-  const descriptor = resolveSpawnTimeoutDescriptor(spawnName);
-  return emitBlockedCloseResult({
-    storyId,
-    phase: 'closing',
-    reason: reason ?? `${spawnName}-timeout`,
-    extra: {
-      gateName: spawnName,
-      exitCode: exitCode ?? 124,
-      timeoutMs,
-      commentId,
-    },
-    bus,
-    progress: log,
-    blockedMessage: `Story #${storyId} blocked: \`${spawnCmd || descriptor.defaultCmd}\` exceeded ${timeoutMs ?? 'configured'}ms — flipped to ${STATE_LABELS.BLOCKED}.`,
-    logger: Logger,
-  });
-}

package/.agents/scripts/lib/orchestration/story-close/phases/timeout-blocked.js

@@ -1,157 +0,0 @@
-/**
- * phases/timeout-blocked.js — pure timeout-classification helpers for
- * the story-close phase pipeline (Story #2460, Epic #2453).
- *
- * Holds the spawn-timeout descriptor table, the reason-token map, the
- * config → timeout-ms resolver, and the friction-comment body renderers.
- * The side-effecting emit (label transition + comment upsert + bus emit)
- * lives in the sibling `timeout-blocked-emitter.js` so this file stays
- * pure and easy to test.
- *
- * Public surface (all exported; re-exported by story-close.js for
- * historical test imports):
- *   - SPAWN_TIMEOUT_DESCRIPTORS
- *   - resolveSpawnTimeoutDescriptor(name)
- *   - resolveSpawnTimeoutReason(name)
- *   - resolveSpawnTimeoutMs(name, config)
- *   - renderSpawnTimeoutFrictionBody(input)
- *   - renderCoverageTimeoutFrictionBody(input)
- */
-
-import { getQuality } from '../../../config-resolver.js';
-
-/**
- * Story #2165 — known spawn-timeout dispatch table. Each entry names the
- * spawn whose bounded-timeout watchdog tripped and the `.agentrc.json`
- * config key the operator tunes to raise the budget.
- */
-export const SPAWN_TIMEOUT_DESCRIPTORS = Object.freeze({
-  'coverage-capture': Object.freeze({
-    displayName: 'Coverage capture',
-    defaultCmd: 'npm run test:coverage',
-    configKey: 'delivery.quality.gates.coverage.timeoutMs',
-    summary: 'The `coverage-capture` pre-merge gate',
-  }),
-  'check-maintainability': Object.freeze({
-    displayName: 'Maintainability baseline refresh',
-    defaultCmd: 'npm run maintainability:update',
-    configKey: 'delivery.quality.gates.maintainability.refreshTimeoutMs',
-    summary: 'The `check-maintainability` baseline-refresh path',
-  }),
-  'check-crap': Object.freeze({
-    displayName: 'CRAP baseline refresh',
-    defaultCmd: 'npm run crap:update',
-    configKey: 'delivery.quality.gates.crap.refreshTimeoutMs',
-    summary: 'The `check-crap` baseline-refresh path',
-  }),
-  'format-autofix': Object.freeze({
-    displayName: 'Format autofix',
-    defaultCmd: 'npx biome format --write .',
-    configKey: 'delivery.quality.formatAutofix.timeoutMs',
-    summary: 'The pre-gate `format-autofix` step',
-  }),
-});
-
-const DEFAULT_TIMEOUT_DESCRIPTOR = Object.freeze({
-  displayName: 'Close-time spawn',
-  defaultCmd: '<unknown>',
-  configKey: 'delivery.quality.<gate>.timeoutMs',
-  summary: 'A close-time spawn',
-});
-
-export function resolveSpawnTimeoutDescriptor(spawnName) {
-  return SPAWN_TIMEOUT_DESCRIPTORS[spawnName] ?? DEFAULT_TIMEOUT_DESCRIPTOR;
-}
-
-/**
- * Story #2241 / Task #2247 — map a spawn-timeout name to the canonical
- * `story.blocked.reason` token the lifecycle bus emits.
- */
-const SPAWN_TIMEOUT_REASONS = Object.freeze({
-  'coverage-capture': 'timeout:coverage-capture',
-  'check-maintainability': 'timeout:baseline-refresh',
-  'check-crap': 'timeout:baseline-refresh',
-  'format-autofix': 'timeout:biome-format',
-});
-
-export function resolveSpawnTimeoutReason(spawnName) {
-  return (
-    SPAWN_TIMEOUT_REASONS[spawnName] ?? `timeout:${spawnName ?? 'unknown'}`
-  );
-}
-
-/**
- * Story #2165 — resolve the timeout (ms) the upstream watchdog enforced
- * for the named spawn. Best-effort: a missing/invalid resolver returns
- * `null`.
- */
-export function resolveSpawnTimeoutMs(spawnName, config) {
-  try {
-    const quality = getQuality(config);
-    switch (spawnName) {
-      case 'coverage-capture':
-        return quality?.coverage?.timeoutMs ?? null;
-      case 'check-maintainability':
-        return quality?.maintainability?.refreshTimeoutMs ?? null;
-      case 'check-crap':
-        return quality?.crap?.refreshTimeoutMs ?? null;
-      case 'format-autofix':
-        return quality?.formatAutofix?.timeoutMs ?? null;
-      default:
-        return null;
-    }
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Render the friction-comment body posted on the Story ticket when one of
- * the close-time spawns trips the bounded-timeout watchdog (exit 124).
- */
-export function renderSpawnTimeoutFrictionBody({
-  storyId,
-  epicId,
-  timeoutMs,
-  spawnName = 'coverage-capture',
-  spawnCmd,
-}) {
-  const descriptor = resolveSpawnTimeoutDescriptor(spawnName);
-  const cmd = spawnCmd || descriptor.defaultCmd;
-  const seconds = Math.round((timeoutMs ?? 0) / 1000);
-  const minutes = Math.round((seconds / 60) * 10) / 10;
-  const budget = timeoutMs
-    ? `${timeoutMs}ms (~${minutes} min)`
-    : 'configured budget';
-  return [
-    `### ${descriptor.displayName} timed out`,
-    '',
-    `${descriptor.summary} spawned \`${cmd}\` for Story #${storyId} (Epic #${epicId ?? 'unknown'}) and the bounded watchdog killed the child after ${budget}.`,
-    '',
-    `**Exit code:** 124 (GNU \`timeout(1)\` convention — surfaced when \`spawnSync\` returns with \`signal: 'SIGKILL'\`).`,
-    '',
-    `**Next actions:**`,
-    `- Re-run \`${cmd}\` locally inside the Story worktree to confirm the hang.`,
-    `- If the command is honestly slow, raise \`${descriptor.configKey}\` in \`.agentrc.json\` and re-close.`,
-    `- If a deadlock or runaway loop is the cause, isolate the offending input and fix the underlying hang.`,
-    '',
-    `Story label has been flipped to \`agent::blocked\`. Resume by transitioning back to \`agent::executing\` after the underlying issue is fixed.`,
-  ].join('\n');
-}
-
-/**
- * Backwards-compatible wrapper for the coverage-capture timeout body
- * (Story #2136 / Task #2143).
- */
-export function renderCoverageTimeoutFrictionBody({
-  storyId,
-  epicId,
-  timeoutMs,
-}) {
-  return renderSpawnTimeoutFrictionBody({
-    storyId,
-    epicId,
-    timeoutMs,
-    spawnName: 'coverage-capture',
-  });
-}