mandrel 1.94.0 → 2.1.0

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

@@ -1,292 +0,0 @@
-/**
- * phases/gates.js — pre-merge gates phase (Story #2460, Epic #2453 —
- * CLI thinning pilot).
- *
- * Runs the close-validation chain (format-autofix → attribution-aware
- * baseline gates → maintainability projection) against the Story
- * worktree before the merge. Outcomes:
- *
- *   - `{ status: 'ok' }`              — gates passed; caller continues.
- *   - `{ status: 'blocked' }`         — baseline drift not attributable
- *     to the Story; caller emits `emitBaselineBlockedResult`.
- *   - `{ status: 'blocked-timeout' }` — one of the bounded-timeout
- *     spawns tripped its watchdog; caller routes through
- *     `emitSpawnTimeoutBlockedResult`.
- *
- * Story #2995 split the pre-merge body into a pure summarizer
- * (`summarizeGateResults`) plus a side-effecting emitter
- * (`emitGateOutcome`). `runPreMergeValidation` is now a thin sequencer:
- * it runs the format-autofix and attribution gate side effects, hands
- * the raw outcomes to the summarizer, and then routes through the
- * emitter. Output is byte-identical to the pre-refactor function.
- *
- * Public surface:
- *   - shouldSkipValidation(input)
- *   - summarizeGateResults(results)
- *   - emitGateOutcome(summary, ctx)
- *   - runPreMergeValidation(input)
- *   - emitBaselineBlockedResult(input)
- */
-
-import { Logger } from '../../../Logger.js';
-import { runPreMergeGatesWithAttribution } from '../baseline-attribution-wiring.js';
-import { runFormatAutofix, runScopedFormatAutofix } from '../format-autofix.js';
-import { emitBlockedCloseResult } from '../merge-runner.js';
-import { emitMaintainabilityProjection } from '../pre-merge-validation.js';
-
-/**
- * Format the `{ status: 'blocked' }` result returned by
- * `runPreMergeGatesWithAttribution` into the canonical close-result
- * envelope + console marker (Story #1124 — non-attributable baseline
- * drift).
- */
-export async function emitBaselineBlockedResult({
-  storyId,
-  gateOutcome,
-  progress: log,
-  bus = null,
-}) {
-  const nonAttributable = gateOutcome.nonAttributable ?? [];
-  return emitBlockedCloseResult({
-    storyId,
-    phase: 'closing',
-    reason: 'baseline-drift-not-attributable',
-    extra: {
-      nonAttributable,
-      commentId: gateOutcome.commentId ?? null,
-    },
-    bus,
-    progress: log,
-    blockedMessage: `Story #${storyId} blocked: baseline drift on ${nonAttributable.length} path(s) not attributable to this Story.`,
-    logger: Logger,
-  });
-}
-
-/**
- * Compute whether the pre-merge gate chain should be skipped on this
- * close. Resume-from-anywhere paths skip; an explicit `--skip-validation`
- * also skips.
- */
-export function shouldSkipValidation({
-  skipValidationParam,
-  resumeFromConflict,
-  resumeFromMerge,
-  resumeFromPostMerge,
-}) {
-  return (
-    !!skipValidationParam ||
-    resumeFromConflict ||
-    resumeFromMerge ||
-    resumeFromPostMerge
-  );
-}
-
-/**
- * Pure aggregator over the raw outcomes produced by the close-validation
- * side effects (Story #2995 split). Consumes the format-autofix outcome
- * and the attribution-aware gate outcome, then classifies the combined
- * result into a verdict + blocker/advisory lists.
- *
- * Verdicts:
- *   - `'blocked-timeout'` — format-autofix spawn watchdog tripped, or the
- *     attribution gate chain itself returned `blocked-timeout`. The
- *     originating outcome is carried on the blocker entry so the emitter
- *     can return the canonical envelope verbatim.
- *   - `'blocked'`         — attribution gate chain reported baseline
- *     drift not attributable to the Story.
- *   - `'ok'`              — gates passed; the maintainability projection
- *     should be emitted and the gate envelope returned to the caller.
- *
- * Inputs are tolerated as `null`/`undefined` so callers that only ran a
- * subset of the chain (resume paths, partial mocks) get a deterministic
- * `'ok'` verdict instead of a thrown error.
- *
- * NO I/O. NO logger calls. NO label transitions. This function is the
- * unit-testable shape of the pre-merge decision.
- */
-export function summarizeGateResults({
-  formatAutofixOutcome = null,
-  gateOutcome = null,
-} = {}) {
-  if (formatAutofixOutcome?.timedOut) {
-    return {
-      verdict: 'blocked-timeout',
-      blockers: [
-        {
-          kind: 'format-autofix-timeout',
-          formatAutofixOutcome,
-        },
-      ],
-      advisories: [],
-    };
-  }
-  if (gateOutcome?.status === 'blocked') {
-    return {
-      verdict: 'blocked',
-      blockers: [
-        {
-          kind: 'baseline-drift',
-          gateOutcome,
-        },
-      ],
-      advisories: [],
-    };
-  }
-  if (gateOutcome?.status === 'blocked-timeout') {
-    return {
-      verdict: 'blocked-timeout',
-      blockers: [
-        {
-          kind: 'gate-timeout',
-          gateOutcome,
-        },
-      ],
-      advisories: [],
-    };
-  }
-  return {
-    verdict: 'ok',
-    blockers: [],
-    advisories: [],
-    gateOutcome,
-  };
-}
-
-/**
- * Side-effecting emitter: consumes a `summarizeGateResults` summary plus
- * the orchestration context and performs the actions implied by the
- * verdict (Story #2995 split).
- *
- * - `blocked-timeout` from format-autofix → return the canonical
- *   timeout envelope built from `formatAutofixOutcome`.
- * - `blocked` / `blocked-timeout` from the attribution gate chain →
- *   return the gate outcome verbatim (caller routes through
- *   `emitBaselineBlockedResult` / spawn-timeout handler).
- * - `ok` → emit the maintainability projection (Logger side effect) and
- *   return the gate outcome verbatim.
- *
- * Maintaining output byte-equivalence with the pre-refactor function is
- * the contract: the gate-outcome objects flow through unchanged.
- */
-export function emitGateOutcome(summary, ctx) {
-  if (summary.verdict === 'blocked-timeout') {
-    const blocker = summary.blockers[0];
-    if (blocker?.kind === 'format-autofix-timeout') {
-      const fao = blocker.formatAutofixOutcome;
-      return {
-        status: 'blocked-timeout',
-        gateName: 'format-autofix',
-        exitCode: fao.exitCode ?? 124,
-        spawnCmd: fao.writeCmdString ?? null,
-        timeoutMs: fao.timeoutMs ?? null,
-      };
-    }
-    return blocker?.gateOutcome ?? null;
-  }
-  if (summary.verdict === 'blocked') {
-    return summary.blockers[0]?.gateOutcome ?? null;
-  }
-  // verdict === 'ok'
-  emitMaintainabilityProjection({
-    cwd: ctx.cwd,
-    epicBranch: ctx.epicBranch,
-    storyBranch: ctx.storyBranch,
-    config: ctx.config,
-    logger: Logger,
-  });
-  return summary.gateOutcome;
-}
-
-/**
- * Run the close-validation gate chain against the Story worktree. The
- * format-autofix self-heal step runs first (Story #2165 — bounded
- * timeout) and short-circuits the chain when the formatter spawn is
- * SIGKILLed. Otherwise the attribution-aware gate chain runs.
- *
- * Story #2995 split this body into a pure summarizer
- * (`summarizeGateResults`) + a side-effecting emitter
- * (`emitGateOutcome`). This function is now a thin sequencer.
- *
- * Returns the gate envelope verbatim so the caller can route by
- * `status` (`blocked` vs `blocked-timeout` vs `ok`).
- */
-export async function runPreMergeValidation({
-  cwd,
-  worktreePath,
-  epicBranch,
-  storyBranch,
-  config,
-  storyId,
-  epicId,
-  noEvidenceFlag,
-  phaseTimer,
-  provider,
-  bus = null,
-  cycleState = null,
-}) {
-  // Story #2533: scope-narrowed biome-format auto-apply on the Epic→Story
-  // diff. The scoped step folds format drift introduced by Story commits
-  // into a dedicated `fix(story-close):` commit on the Story branch and
-  // emits Logger.warn naming the auto-fixed files.
-  //
-  // Story #3407: when branch refs are available, this scoped step is the
-  // formatter autofix path. Falling through to the whole-tree `.` formatter
-  // from inside `.worktrees/story-*` is fragile against consumer ignore
-  // globs that exclude `.worktrees`, so the broad autofix is retained only
-  // for resume/legacy callers that cannot supply a diff anchor.
-  let formatAutofixOutcome = null;
-  if (epicBranch && storyBranch) {
-    // Story #3907 — pass `worktreePath` so the formatter writes + the scoped
-    // `fix(story-close):` commit land in the Story worktree (where
-    // `story-<id>` is checked out), never the main checkout's current branch.
-    formatAutofixOutcome = runScopedFormatAutofix({
-      cwd,
-      worktreePath,
-      storyId,
-      epicBranch,
-      storyBranch,
-      config,
-      logger: Logger,
-    });
-  } else {
-    formatAutofixOutcome = runFormatAutofix({
-      cwd,
-      storyId,
-      config,
-      logger: Logger,
-    });
-  }
-  if (formatAutofixOutcome?.timedOut) {
-    const summary = summarizeGateResults({ formatAutofixOutcome });
-    return emitGateOutcome(summary, {
-      cwd,
-      epicBranch,
-      storyBranch,
-      config,
-    });
-  }
-  const gateOutcome = await runPreMergeGatesWithAttribution({
-    cwd,
-    worktreePath,
-    epicBranch,
-    storyBranch,
-    config,
-    storyId,
-    epicId,
-    cycleState,
-    useEvidence: !noEvidenceFlag,
-    phaseTimer,
-    provider,
-    bus,
-  });
-  const summary = summarizeGateResults({
-    formatAutofixOutcome,
-    gateOutcome,
-  });
-  return emitGateOutcome(summary, {
-    cwd,
-    epicBranch,
-    storyBranch,
-    config,
-  });
-}

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

@@ -1,270 +0,0 @@
-/**
- * phases/locked-pipeline.js — the per-Epic-merge-lock-protected body of
- * `runStoryClose` (Story #2460, Epic #2453 — CLI thinning pilot).
- *
- * Sits behind `withEpicMergeLock` in story-close.js. Owns:
- *
- *   1. dispatchRecovery     — prior-state detection + --resume / --restart
- *      dispatch
- *   2. fetchChildTickets      — hydrate the cascade target set
- *   3. phase-timer restore  — pick up the snapshot story-init wrote
- *   4. gates                — pre-merge validation (skipped on resume)
- *   5. refresh              — bounded baseline auto-refresh (gates ok path)
- *   6. close                — merge + post-merge close pipeline
- *
- * The split out of story-close.js keeps the CLI shell at ≤ 300 LOC and
- * means a future test can drive the locked pipeline with the lock
- * mocked out — without re-acquiring the per-Epic lock or re-entering
- * the preflight gate.
- */
-
-import { Logger } from '../../../Logger.js';
-import { hasInlineAcceptance } from '../../../story-init/task-graph-builder.js';
-import { fetchChildTickets } from '../../../story-lifecycle.js';
-import { createPhaseTimer } from '../../../util/phase-timer.js';
-import {
-  clearPhaseTimerState,
-  loadPhaseTimerState,
-} from '../../../util/phase-timer-state.js';
-import { read as readPlanState } from '../../epic-plan-state-store.js';
-import { dispatchRecovery } from '../../story-close-recovery.js';
-import { runClosePhase } from './close.js';
-import { runStoryCodeReview } from './code-review.js';
-import {
-  emitBaselineBlockedResult,
-  runPreMergeValidation,
-  shouldSkipValidation,
-} from './gates.js';
-import { runAutoRefreshSafely } from './refresh.js';
-import { emitSpawnTimeoutBlockedResult } from './timeout-blocked-emitter.js';
-
-/**
- * Run pre-merge gates and, on a clean outcome, the bounded baseline
- * auto-refresh. Returns `{ blocked }` so the locked pipeline can
- * short-circuit on a `blocked` / `blocked-timeout` gate outcome.
- *
- * `runPreMergeValidation` is an injectable seam (Story #3973): the
- * forwarding of `config: ctx.config` into the gate builder is load-bearing
- * — without it the typecheck gate ignores `project.commands.typecheck` and
- * falls back to the hardcoded `npm run typecheck`, blocking every close for
- * any consumer with a non-default typecheck command. The default is the
- * module-level `runPreMergeValidation`; tests inject a spy to pin that
- * `config` reaches the gate builder through this call site.
- *
- * @param {object} ctx - The locked-pipeline context bundle.
- * @param {object} [deps] - Injectable collaborators.
- * @param {typeof runPreMergeValidation} [deps.runPreMergeValidationFn]
- * @param {typeof runAutoRefreshSafely} [deps.runAutoRefreshSafelyFn]
- */
-export async function runGatesAndRefresh(
-  ctx,
-  {
-    runPreMergeValidationFn = runPreMergeValidation,
-    runAutoRefreshSafelyFn = runAutoRefreshSafely,
-  } = {},
-) {
-  // Story #4017 — one shared cycle-state object per close cycle. The
-  // gate-failure attribution retry and the post-gates auto-refresh both
-  // funnel through `runRefreshCommit`, which keys its idempotency token
-  // off this object so each baseline kind is refreshed (scored +
-  // committed) at most once per close.
-  const cycleState = { refreshedKinds: new Set(), lastRefreshSha: null };
-  const gateOutcome = await runPreMergeValidationFn({
-    cwd: ctx.cwd,
-    worktreePath: ctx.worktreePath,
-    epicBranch: ctx.epicBranch,
-    storyBranch: ctx.storyBranch,
-    config: ctx.config,
-    storyId: ctx.storyId,
-    epicId: ctx.epicId,
-    noEvidenceFlag: ctx.noEvidenceFlag,
-    phaseTimer: ctx.phaseTimer,
-    provider: ctx.provider,
-    bus: ctx.bus,
-    cycleState,
-  });
-  if (gateOutcome?.status === 'blocked') {
-    return {
-      blocked: await emitBaselineBlockedResult({
-        storyId: ctx.storyId,
-        gateOutcome,
-        progress: ctx.progress,
-        bus: ctx.bus,
-      }),
-    };
-  }
-  if (gateOutcome?.status === 'blocked-timeout') {
-    return {
-      blocked: await emitSpawnTimeoutBlockedResult({
-        storyId: ctx.storyId,
-        epicId: ctx.epicId,
-        spawnName: gateOutcome.gateName ?? 'coverage-capture',
-        spawnCmd: gateOutcome.spawnCmd ?? null,
-        timeoutMs: gateOutcome.timeoutMs ?? null,
-        exitCode: gateOutcome.exitCode ?? 124,
-        config: ctx.config,
-        provider: ctx.provider,
-        progress: ctx.progress,
-        bus: ctx.bus,
-      }),
-    };
-  }
-  await runAutoRefreshSafelyFn(
-    {
-      storyId: ctx.storyId,
-      epicId: ctx.epicId,
-      cwd: ctx.worktreePath || ctx.cwd,
-      epicBranch: ctx.epicBranch,
-      storyBranch: ctx.storyBranch,
-      config: ctx.config,
-      cycleState,
-    },
-    { progress: ctx.progress },
-  );
-  return { blocked: null };
-}
-
-/**
- * Read the parent Epic's judged `planningRisk` envelope off its
- * `epic-plan-state` checkpoint so the Story-scope review can inherit the
- * Epic's review depth (Story #3940). Best-effort and total — it reuses the
- * shared `read` from `epic-plan-state-store.js` (the same reader `/plan
- * --resume` and `epic-audit-prepare.js`'s `resolveRiskRoutedLenses` use, no
- * third bespoke reader) and never fails the close:
- *
- *   - absent/non-integer `epicId` (a Story that is not Epic-attached) → `null`
- *   - missing/unparseable checkpoint, no `planningRisk` field → `null`
- *   - any read throw (provider error, malformed comment) → `null`
- *
- * A `null` result threads through `runStoryCodeReview` → `runCodeReview`
- * unchanged, so depth resolves from diff width alone (`standard`), preserving
- * today's behaviour for an Epic that skipped `/plan`.
- *
- * @param {{ provider: object, epicId: number|null|undefined, readPlanStateFn?: typeof readPlanState }} args
- * @returns {Promise<{ overallLevel?: string, axes?: Array<object> }|null>}
- */
-export async function resolveParentEpicPlanningRisk({
-  provider,
-  epicId,
-  readPlanStateFn = readPlanState,
-}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) return null;
-  try {
-    const state = await readPlanStateFn({ provider, epicId });
-    return state?.planningRisk ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Body of `withEpicMergeLock(epicId, ..., () => …)` from story-close.js.
- *
- * @param {object} args - resolved-close-input bundle from
- *   `resolveCloseInputs` plus the orchestrator-injected `progress` /
- *   `progressLog` callbacks and the lifecycle bus.
- * @returns {Promise<{ success: boolean, result?: object } | object>}
- */
-export async function runStoryCloseLocked(args) {
-  const {
-    cwd,
-    storyId,
-    epicId,
-    epicBranch,
-    storyBranch,
-    config,
-    skipValidationParam,
-    resumeFlag,
-    restartFlag,
-    provider,
-    story,
-    progress,
-  } = args;
-
-  // Prior-state detection + --resume / --restart dispatch.
-  // `dispatchRecovery` only reads `orchestration.worktreeIsolation`; surface
-  // it from the canonical `delivery.worktreeIsolation` view directly.
-  const { resumeFromConflict, resumeFromMerge, resumeFromPostMerge } =
-    dispatchRecovery({
-      cwd,
-      storyId,
-      epicId,
-      epicBranch,
-      storyBranch,
-      orchestration: { worktreeIsolation: config.delivery?.worktreeIsolation },
-      resume: resumeFlag,
-      restart: restartFlag,
-      progress,
-      logger: Logger,
-    });
-
-  // Story #4251 — mirror the init-side short-circuit: a 2-tier Story (inline
-  // acceptance on its body) has no children, so skip the `fetchChildTickets`
-  // probe (empty sub-issues GraphQL query + never-matching `/search/issues`
-  // scan) entirely. The cascade target is just the Story itself. A body
-  // lacking inline acceptance still enumerates children for legacy / Epic
-  // callers.
-  const tasks = hasInlineAcceptance(story?.body)
-    ? []
-    : await fetchChildTickets(provider, storyId);
-  provider.primeTicketCache([story, ...tasks]);
-  progress('TICKETS', `Found ${tasks.length} child ticket(s)`);
-
-  const prior = loadPhaseTimerState({ mainCwd: cwd, storyId });
-  const phaseTimer = createPhaseTimer(storyId, prior ? { restore: prior } : {});
-
-  const skipValidation = shouldSkipValidation({
-    skipValidationParam,
-    resumeFromConflict,
-    resumeFromMerge,
-    resumeFromPostMerge,
-  });
-
-  const ctx = {
-    ...args,
-    tasks,
-    phaseTimer,
-    resumeFromConflict,
-    resumeFromMerge,
-    resumeFromPostMerge,
-    clearPhaseTimerState,
-  };
-
-  if (!skipValidation) {
-    const { blocked } = await runGatesAndRefresh(ctx);
-    if (blocked) return blocked;
-
-    // Story #2840 — Story-scope code review runs after the gate chain
-    // passes (so we know the diff is build-clean) but before the merge
-    // into `epic/<id>`. Critical findings short-circuit the close and
-    // exit non-zero; non-critical findings post a structured comment
-    // and let close proceed.
-    //
-    // Story #3940 — the review inherits the parent Epic's judged review
-    // depth: read the Epic's `planningRisk` envelope best-effort off its
-    // `epic-plan-state` checkpoint and forward it so `runCodeReview`
-    // resolves depth from BOTH that risk and the Story-scope
-    // (`epic/<id>...story-<id>`) changed-file count. A missing/unreadable
-    // checkpoint degrades to `null` (→ `standard`) without failing close.
-    const planningRisk = await resolveParentEpicPlanningRisk({
-      provider: ctx.provider,
-      epicId: ctx.epicId,
-    });
-    const review = await runStoryCodeReview({
-      storyId: ctx.storyId,
-      epicBranch: ctx.epicBranch,
-      storyBranch: ctx.storyBranch,
-      provider: ctx.provider,
-      bus: ctx.bus,
-      progress: ctx.progress,
-      planningRisk,
-    });
-    if (review.blocked) return review.blocked;
-  }
-
-  // Everything past validation is the `close` phase; the post-merge
-  // pipeline marks `api-sync` once the merge lands.
-  phaseTimer.mark('close');
-
-  return runClosePhase(ctx);
-}

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

@@ -1,110 +0,0 @@
-/**
- * phases/preflight.js — story-close preflight phase (Story #2460, Epic
- * #2453 — CLI thinning pilot).
- *
- * Wraps the registry-driven preflight scan + the canonical "preflight
- * refused" close-result envelope. Runs BEFORE `withEpicMergeLock` so the
- * per-Epic lock is not acquired just to release it on a refused
- * preflight (the project-wide exit-code 2 reservation).
- *
- * Public surface:
- *   - runStoryClosePreflight(opts)         ← exported (story-close.js re-export)
- *   - emitPreflightBlockedResult(opts)
- *   - runPreflightPhase(ctx)               ← pipeline entry
- */
-
-import { Logger } from '../../../Logger.js';
-import {
-  PREFLIGHT_REFUSED_EXIT_CODE,
-  runPreflight,
-} from '../../../preflight-runner.js';
-import { emitBlockedCloseResult } from '../merge-runner.js';
-
-/**
- * Run the story-close preflight gate. Exported so tests can drive it
- * with an inline registry / probe spies without re-entering the full
- * close orchestrator.
- *
- * @param {object} opts
- * @param {string|number} opts.storyId
- * @param {string} [opts.cwd=process.cwd()]
- * @param {object} [opts.probes]
- * @param {object} [opts.registry]
- * @param {string} [opts.dir]
- * @param {object} [opts.logger]
- * @returns {Promise<{ ok: boolean, findings: Array, fixed: Array }>}
- */
-export async function runStoryClosePreflight({
-  storyId,
-  cwd = process.cwd(),
-  probes,
-  registry,
-  dir,
-  logger,
-} = {}) {
-  Logger.info(
-    `[story-close] Running preflight checks (scope=story-close) for Story #${storyId ?? '?'}...`,
-  );
-  const preflight = await runPreflight({
-    scope: 'story-close',
-    autoFix: true,
-    cwd,
-    probes,
-    registry,
-    dir,
-    logger,
-  });
-  return {
-    ok: !preflight.blocked,
-    findings: preflight.findings,
-    fixed: preflight.fixed,
-  };
-}
-
-/**
- * Emit the canonical close-result envelope for the "preflight refused"
- * exit. Shape mirrors `emitBaselineBlockedResult` so the wave aggregator's
- * label-derivation fallback sees a consistent envelope.
- */
-export async function emitPreflightBlockedResult({
-  storyId,
-  preflight,
-  progress,
-}) {
-  return emitBlockedCloseResult({
-    storyId,
-    phase: 'preflight',
-    reason: 'preflight-refused',
-    extra: { findings: preflight.findings },
-    progress,
-    blockedMessage: `Story #${storyId} blocked: preflight refused — ${preflight.findings.length} blocker finding(s).`,
-    logger: Logger,
-  });
-}
-
-/**
- * Phase pipeline entry. Returns one of:
- *   - { ok: true } when preflight passed (caller continues)
- *   - { ok: false, exitEnvelope } when preflight refused (caller short-circuits
- *     with `{ success: false, result: exitEnvelope, exitCode: PREFLIGHT_REFUSED_EXIT_CODE }`)
- */
-export async function runPreflightPhase({ ctx }) {
-  const outcome = await runStoryClosePreflight({
-    storyId: ctx.storyId,
-    cwd: ctx.cwd,
-  });
-  if (outcome.ok) return { ok: true };
-  const exitEnvelope = await emitPreflightBlockedResult({
-    storyId: ctx.storyId,
-    preflight: outcome,
-    progress: ctx.progress,
-  });
-  return {
-    ok: false,
-    exitEnvelope: {
-      success: false,
-      result: exitEnvelope,
-      exitCode: PREFLIGHT_REFUSED_EXIT_CODE,
-    },
-  };
-}