mandrel 1.57.0

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

@@ -0,0 +1,220 @@
+/**
+ * phases/code-review.js — Story-scope code-review phase
+ * (Story #2840, Epic #2815 — Pluggable Code Review + Story-Level Review).
+ *
+ * Sits between the close-validation gate chain and the merge into
+ * `epic/<id>` inside `runStoryCloseLocked` (locked-pipeline.js). The
+ * configured ReviewProvider runs against the
+ * `epic/<id>`…`story-<id>` diff. The structured `code-review` comment
+ * is posted to the Story issue (default `commentTargetId === ticketId`
+ * inside `runCodeReview`). Outcomes:
+ *
+ *   - clean / non-critical findings → `{ blocked: null }`; the pipeline
+ *     proceeds to merge.
+ *   - critical findings              → `{ blocked: <envelope> }`; the
+ *     pipeline short-circuits, the Story is not merged, and the CLI
+ *     exits non-zero via `exitCode: 1` on the envelope.
+ *   - adapter throw / wiring failure → `{ blocked: null }`; the close
+ *     proceeds because the review surface is advisory for transport
+ *     failures (the same posture refresh.js takes). A warn is logged.
+ *
+ * Bus contract: `runCodeReview` only emits lifecycle events for
+ * `scope: 'epic'` (the `code-review.end` schema requires `epicId`
+ * and the ledger only spans Epic lifecycles — see Story #2839 lock-in
+ * in `code-review.js`). The Story-scope path here therefore does not
+ * forward the bus, and `story.blocked` is emitted separately on the
+ * critical-halt path so the Epic-scoped lifecycle ledger still sees
+ * the Story drop out.
+ *
+ * `runStoryReviewCore` is exported as the shared spine that the
+ * `single-story-close` path imports, so both close paths call `runCodeReview`
+ * through a single implementation rather than each maintaining its own
+ * invocation pattern (Story #3653).
+ */
+
+import { Logger } from '../../../Logger.js';
+import { runCodeReview } from '../../code-review.js';
+import { emitBlockedCloseResult } from '../merge-runner.js';
+
+/**
+ * Collect the extra fields for the code-review-critical blocked envelope.
+ * Pure; used by `runStoryCodeReview` to populate the `extra` argument of
+ * `emitBlockedCloseResult`.
+ */
+function buildCodeReviewBlockedExtra({ storyId, reviewResult }) {
+  const severity = reviewResult?.severity ?? {
+    critical: 0,
+    high: 0,
+    medium: 0,
+    suggestion: 0,
+  };
+  return {
+    storyId: Number(storyId),
+    blockerReason: reviewResult?.blockerReason ?? null,
+    severity,
+    posted: reviewResult?.posted ?? false,
+    exitCode: 1,
+  };
+}
+
+/**
+ * Invoke `runCodeReviewFn` with the canonical Story-scope envelope and return
+ * the raw result. Shared by both the Epic-attached close path
+ * (`runStoryCodeReview`) and the standalone close path
+ * (`single-story-close/phases/code-review.js#runStoryScopeReview`) so the
+ * invocation pattern lives in one place (Story #3653).
+ *
+ * The caller is responsible for error handling and result interpretation —
+ * this function propagates throws rather than swallowing them, because the
+ * two callers have different advisory postures:
+ *
+ *   - Epic-attached close: swallows throws (non-blocking advisory, same as
+ *     `refresh.js`).
+ *   - Standalone close: propagates throws (a review failure stops the close).
+ *
+ * The optional `planningRisk` envelope (Story #3940) is forwarded verbatim to
+ * `runCodeReview`, which folds its `overallLevel` together with the
+ * `baseRef...headRef` changed-file count (which `runCodeReview` enumerates
+ * itself, scoped to the diff under review) into the review depth via the
+ * shared {@link resolveDepth} resolver. It is an **input-only** signal: it
+ * tells the provider how thorough to be and never alters the review's output
+ * envelope or the posted structured-comment body. Absent (`null` / `undefined`,
+ * the standalone close path) → `runCodeReview` resolves the neutral depth from
+ * diff width alone, byte-identical to the pre-#3940 behaviour.
+ *
+ * @param {{
+ *   storyId: number|string,
+ *   baseRef: string,
+ *   headRef: string,
+ *   commentTargetId?: number|null,
+ *   provider: object,
+ *   progress: (tag: string, msg: string) => void,
+ *   progressTag?: string,
+ *   planningRisk?: { overallLevel?: ('low'|'medium'|'high'), axes?: Array<{ axis?: string, level?: string }> }|null,
+ *   runCodeReviewFn?: typeof runCodeReview,
+ * }} args
+ * @returns {Promise<object>} Raw result envelope from `runCodeReview`.
+ */
+export async function runStoryReviewCore({
+  storyId,
+  baseRef,
+  headRef,
+  commentTargetId = null,
+  provider,
+  progress,
+  progressTag = 'CODE-REVIEW',
+  planningRisk = null,
+  runCodeReviewFn = runCodeReview,
+}) {
+  const storyIdNum = Number(storyId);
+  const opts = {
+    scope: 'story',
+    ticketId: storyIdNum,
+    baseRef,
+    headRef,
+    provider,
+    logger: {
+      info: (m) => progress(progressTag, m),
+      warn: (m) => progress(progressTag, `⚠️ ${m}`),
+    },
+  };
+  if (commentTargetId != null) {
+    opts.commentTargetId = commentTargetId;
+  }
+  // Forward the parent Epic's judged risk only on the Epic-attached path; the
+  // standalone caller leaves this null so `runCodeReview` resolves depth from
+  // diff width alone (no plan checkpoint exists for a standalone Story).
+  if (planningRisk != null) {
+    opts.planningRisk = planningRisk;
+  }
+  return runCodeReviewFn(opts);
+}
+
+/**
+ * Run a Story-scope code review against the `epic/<id>`…`story-<id>`
+ * diff and post the structured `code-review` comment to the Story
+ * issue. Returns `{ blocked }` where `blocked` is either `null`
+ * (caller proceeds to merge) or the blocked-envelope (caller returns
+ * it verbatim and the CLI exits 1).
+ *
+ * The optional `planningRisk` envelope (Story #3940) is the parent Epic's
+ * judged risk, read best-effort off the `epic-plan-state` checkpoint by the
+ * locked pipeline. It is forwarded into `runCodeReview` so the review depth is
+ * resolved from BOTH the Epic-judged risk and the Story's own
+ * `epic/<id>...story-<id>` changed-file count — a small Story under a
+ * high-risk Epic still earns `deep`, a small Story under a low-risk Epic gets
+ * `light`, and an absent envelope resolves `standard` (today's behaviour).
+ * Depth is input-only: it never changes `{ blocked }` or the posted comment.
+ *
+ * @param {{
+ *   storyId: number|string,
+ *   epicBranch: string,
+ *   storyBranch: string,
+ *   provider: object,
+ *   bus: { emit: Function }|null,
+ *   progress: (tag: string, msg: string) => void,
+ *   planningRisk?: { overallLevel?: ('low'|'medium'|'high'), axes?: Array<{ axis?: string, level?: string }> }|null,
+ *   runCodeReviewFn?: typeof runCodeReview,
+ * }} args
+ * @returns {Promise<{ blocked: object|null }>}
+ */
+export async function runStoryCodeReview(args) {
+  const {
+    storyId,
+    epicBranch,
+    storyBranch,
+    provider,
+    bus,
+    progress,
+    planningRisk = null,
+    runCodeReviewFn = runCodeReview,
+  } = args;
+
+  const storyIdNum = Number(storyId);
+  progress(
+    'CODE-REVIEW',
+    `Running Story-scope review (${epicBranch}…${storyBranch})...`,
+  );
+
+  let reviewResult;
+  try {
+    reviewResult = await runStoryReviewCore({
+      storyId: storyIdNum,
+      baseRef: epicBranch,
+      headRef: storyBranch,
+      provider,
+      progress,
+      planningRisk,
+      runCodeReviewFn,
+    });
+  } catch (err) {
+    // Adapter / wiring failure — log and proceed. The review is advisory
+    // when the provider cannot complete; the gates already vouched for
+    // the diff at this point.
+    Logger.warn?.(
+      `[story-close] ⚠️ code-review phase failed (continuing without blocker): ${err?.message ?? err}`,
+    );
+    return { blocked: null };
+  }
+
+  if (reviewResult?.halted) {
+    const blocked = await emitBlockedCloseResult({
+      storyId: storyIdNum,
+      phase: 'closing',
+      reason: 'code-review-critical',
+      extra: buildCodeReviewBlockedExtra({ storyId: storyIdNum, reviewResult }),
+      bus,
+      progress,
+      blockedMessage: `Story #${storyIdNum} blocked: code-review reported ${reviewResult.severity.critical} critical blocker(s).`,
+      logger: Logger,
+    });
+    return { blocked };
+  }
+
+  const counts = reviewResult?.severity ?? {};
+  progress(
+    'CODE-REVIEW',
+    `Review complete — high=${counts.high ?? 0} medium=${counts.medium ?? 0} suggestion=${counts.suggestion ?? 0} (posted=${reviewResult?.posted ?? false}).`,
+  );
+  return { blocked: null };
+}

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

@@ -0,0 +1,291 @@
+/**
+ * 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 } from '../format-autofix.js';
+import { runScopedFormatAutofix } from '../format-autofix-scoped.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,
+}) {
+  // 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,
+    useEvidence: !noEvidenceFlag,
+    phaseTimer,
+    provider,
+    bus,
+  });
+  const summary = summarizeGateResults({
+    formatAutofixOutcome,
+    gateOutcome,
+  });
+  return emitGateOutcome(summary, {
+    cwd,
+    epicBranch,
+    storyBranch,
+    config,
+  });
+}