mandrel 2.64.0 → 2.65.0

package/.agents/scripts/lib/orchestration/review-providers/code-review.js

@@ -0,0 +1,203 @@
+/**
+ * review-providers/code-review.js — a low-effort model bug review of the
+ * Story diff through `claude --print --effort low`. It asks only for
+ * merge-blocking problems, so every parsed finding is `critical` and halts
+ * close before auto-merge. The reviewer is handed the diff range, the Story
+ * id and the diff text — never `acceptance[]` or the self-eval verdict: this
+ * is a bug review, not a second acceptance scoring.
+ *
+ * A missing CLI throws at construction (the default chain entry is
+ * `optional: true`, so hosts without it skip). A review that cannot run or
+ * whose output does not parse degrades to one non-halting `suggestion`.
+ *
+ * @typedef {import('./types.js').Finding}        Finding
+ * @typedef {import('./types.js').ReviewInput}    ReviewInput
+ * @typedef {import('./types.js').ReviewProvider} ReviewProvider
+ */
+
+import { spawnCapture } from '../../child-exec.js';
+import { gitSpawn } from '../../git-utils.js';
+import { PROJECT_ROOT } from '../../project-root.js';
+import { parseProviderFindings } from './parse-findings.js';
+import { renderDepthDirective } from './review-depth.js';
+import { probeClaudeCli } from './security-review.js';
+
+const CLAUDE_ARGS = Object.freeze(['--print', '--effort', 'low']);
+const INVOKE_TIMEOUT_MS = 10 * 60 * 1000;
+/** Larger diffs are truncated; the reviewer is told so. */
+const MAX_DIFF_CHARS = 200_000;
+
+const PROMPT_HEAD =
+  'You are reviewing the diff `{baseRef}...{headRef}` for Story #{ticketId} ' +
+  'before it merges. {depthDirective}\n\n' +
+  'Report ONLY problems you would block this merge for: a bug that makes ' +
+  'the change behave incorrectly, crash, lose data, or break an existing ' +
+  'caller. Do not report style, naming, refactoring ideas, missing tests or ' +
+  'anything you would merge anyway. For each problem give the file, the ' +
+  'line in the new version, why it is wrong, and how to show it fails (an ' +
+  'input, command or test that exposes it).\n\n' +
+  'The diff below is authoritative — files on disk may not reflect it. ' +
+  'Emit ONLY a JSON array on stdout with this exact shape, no prose around ' +
+  'it:\n\n' +
+  '[{"title":"...","body":"Why it is wrong: ... How to show it fails: ...",' +
+  '"file":"...","line":1,"category":"bug"}]\n\n' +
+  'Emit [] if there is nothing you would block the merge for.\n\n';
+
+/**
+ * @param {ReviewInput} input
+ * @param {string} diff
+ * @returns {string}
+ */
+function buildPrompt(input, diff) {
+  const truncated = diff.length > MAX_DIFF_CHARS;
+  const body = truncated ? diff.slice(0, MAX_DIFF_CHARS) : diff;
+  const note = truncated
+    ? `\n[diff truncated at ${MAX_DIFF_CHARS} characters]\n`
+    : '';
+  const head = PROMPT_HEAD.replace('{baseRef}', input.baseRef)
+    .replace('{headRef}', input.headRef)
+    .replace('{ticketId}', String(input.ticketId))
+    .replace('{depthDirective}', renderDepthDirective(input.depth));
+  return `${head}<diff>\n${body}${note}\n</diff>\n`;
+}
+
+/**
+ * The prompt rides stdin so no shell ever quotes it.
+ *
+ * @param {string} prompt
+ * @param {Function} [run] - `spawnSync`-shaped seam for tests.
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+function invokeClaude(prompt, run) {
+  return spawnCapture('claude', [...CLAUDE_ARGS], {
+    cwd: PROJECT_ROOT,
+    input: prompt,
+    shell: process.platform === 'win32',
+    timeout: INVOKE_TIMEOUT_MS,
+    ...(run ? { run } : {}),
+  });
+}
+
+/** A model often fences its JSON; strip one surrounding fence. */
+function stripFence(text) {
+  const match = /^\s*```[a-z]*\s*\n([\s\S]*?)\n\s*```\s*$/i.exec(text ?? '');
+  return match ? match[1] : (text ?? '');
+}
+
+/**
+ * @param {string} title
+ * @param {string} detail
+ * @returns {Finding}
+ */
+function advisory(title, detail) {
+  return {
+    severity: 'suggestion',
+    title,
+    body:
+      `${detail} The model bug review did not produce a verdict — inspect ` +
+      'the diff manually before merging. Advisory only; the chain did not halt.',
+    category: 'bug',
+  };
+}
+
+/**
+ * @param {string} stdout
+ * @returns {Finding[]}
+ */
+function parseFindings(stdout) {
+  try {
+    return parseProviderFindings(stripFence(stdout), {
+      errorPrefix: '[code-review] Failed to parse reviewer stdout as JSON',
+      mapSeverity: () => 'critical',
+      defaultCategory: 'bug',
+    });
+  } catch (err) {
+    return [
+      advisory(
+        'Code review output not parseable as JSON',
+        `The reviewer returned text that did not parse as a JSON findings array (${err.message}).`,
+      ),
+    ];
+  }
+}
+
+/**
+ * @param {ReviewInput} input
+ */
+function assertInput(input) {
+  const { baseRef, headRef, ticketId } = input ?? {};
+  if (!baseRef || !headRef) {
+    throw new TypeError(
+      '[code-review] runReview requires baseRef and headRef.',
+    );
+  }
+  if (!Number.isInteger(ticketId) || ticketId <= 0) {
+    throw new TypeError(
+      '[code-review] runReview requires a positive integer ticketId.',
+    );
+  }
+}
+
+/**
+ * @param {{
+ *   probeFn?: () => boolean,
+ *   gitSpawnFn?: typeof gitSpawn,
+ *   spawnFn?: Function,
+ *   logger?: { info?: Function, warn?: Function },
+ * }} [deps] - `spawnFn` replaces `spawnSync` for the `claude` call.
+ * @returns {ReviewProvider}
+ */
+export function createCodeReviewProviderForRegistry(deps = {}) {
+  const probeFn = deps.probeFn ?? probeClaudeCli;
+  if (!probeFn()) {
+    throw new Error(
+      '[ReviewProviderFactory] codeReview provider "code-review" requires ' +
+        'the `claude` CLI on PATH but it was not detected. Install the ' +
+        'Claude Code CLI, or keep the entry `optional: true` so hosts ' +
+        'without it skip the model bug review.',
+    );
+  }
+  const gitSpawnFn = deps.gitSpawnFn ?? gitSpawn;
+  const { spawnFn, logger } = deps;
+
+  return {
+    async runReview(input) {
+      assertInput(input);
+      const { baseRef, headRef, ticketId } = input;
+      const diff = gitSpawnFn(
+        PROJECT_ROOT,
+        'diff',
+        '--no-color',
+        `${baseRef}...${headRef}`,
+      );
+      if (diff.status !== 0) {
+        return [
+          advisory(
+            'Code review could not read the diff',
+            `\`git diff ${baseRef}...${headRef}\` failed: ${diff.stderr || '<no output>'}.`,
+          ),
+        ];
+      }
+      if (diff.stdout.trim().length === 0) return [];
+
+      logger?.info?.(
+        `[code-review] Invoking claude --print --effort low for Story #${ticketId} (${baseRef}...${headRef})...`,
+      );
+      const result = invokeClaude(buildPrompt(input, diff.stdout), spawnFn);
+      if (result.status !== 0) {
+        logger?.warn?.(
+          `[code-review] claude exited ${result.status}; emitting advisory.`,
+        );
+        return [
+          advisory(
+            'Code review did not complete',
+            `\`claude --print\` exited with status ${result.status}: ${
+              result.stderr || result.stdout || '<no output>'
+            }.`,
+          ),
+        ];
+      }
+      return parseFindings(result.stdout);
+    },
+  };
+}

package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js

@@ -14,6 +14,8 @@
  * @typedef {import('./types.js').ProviderChain}         ProviderChain
  */
 
+import { DEFAULT_REVIEW_PROVIDERS } from '../../config/review-chain-default.js';
+import { createCodeReviewProviderForRegistry } from './code-review.js';
 import { createCodexProviderForRegistry } from './codex.js';
 import { mergeChainDegradations } from './degraded-gates.js';
 import { createNativeProviderForRegistry } from './native.js';
@@ -22,6 +24,7 @@ import { createUltrareviewProviderForRegistry } from './ultrareview.js';
 
 /** @type {Readonly<Record<string, () => ReviewProvider>>} */
 const INLINE_PROVIDERS = Object.freeze({
+  'code-review': createCodeReviewProviderForRegistry,
   codex: createCodexProviderForRegistry,
   native: createNativeProviderForRegistry,
   'security-review': createSecurityReviewProviderForRegistry,
@@ -36,8 +39,6 @@ const PROMPT_PROVIDERS = Object.freeze({
   ultrareview: createUltrareviewProviderForRegistry,
 });
 
-export const DEFAULT_PROVIDER_NAME = 'native';
-
 /**
  * Gate predicate from a `when` clause (`label` / `labelAny`); absent → always true.
  *
@@ -79,7 +80,8 @@ export function isScopeApplicable(declaredScopes, currentScope) {
 }
 
 /**
- * Takes the `codeReview` sub-object; unset/empty `providers` defaults to native.
+ * Takes the `codeReview` sub-object; unset/empty `providers` falls back to
+ * `DEFAULT_REVIEW_PROVIDERS`.
  *
  * @param {{
  *   providers?: Array<object>,
@@ -105,7 +107,7 @@ export function createReviewProvider(codeReviewConfig, opts = {}) {
     Array.isArray(codeReviewConfig.providers) &&
     codeReviewConfig.providers.length > 0
       ? codeReviewConfig.providers
-      : [{ name: DEFAULT_PROVIDER_NAME }];
+      : DEFAULT_REVIEW_PROVIDERS;
 
   const chain = buildProviderChain(entries, {
     inlineRegistry,

package/.agents/scripts/lib/orchestration/review-providers/security-review.js

@@ -24,11 +24,12 @@ export const SECURITY_REVIEW_REMEDIATIONS = Object.freeze({
 
 /**
  * Synchronous so a missing CLI surfaces at construction, not mid-review.
+ * Shared by every `claude --print` provider.
  *
  * @param {{ spawnFn?: typeof spawnSync }} [opts]
  * @returns {boolean}
  */
-function defaultProbeClaudeCli(opts = {}) {
+export function probeClaudeCli(opts = {}) {
   const spawnFn = opts.spawnFn ?? spawnSync;
   try {
     const result = spawnFn('claude', ['--version'], {
@@ -173,7 +174,7 @@ export function buildUnparseableFallbackFinding() {
  * @returns {ReviewProvider}
  */
 export function createSecurityReviewProvider(deps = {}) {
-  const probeFn = deps.probeFn ?? defaultProbeClaudeCli;
+  const probeFn = deps.probeFn ?? probeClaudeCli;
   if (!probeFn()) {
     throw buildSecurityReviewUnavailableError();
   }

package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js

@@ -107,6 +107,7 @@ export function failedTerminalFor(err, args = {}) {
       failure: { reason: String(err?.message ?? err) },
       nextCommand: NEXT_COMMANDS.recover(storyId),
       elapsedSeconds: 0,
+      phaseDurations: err?.closePhaseDurations ?? undefined,
     });
   } catch (buildErr) {
     Logger.error(

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

@@ -56,8 +56,6 @@ async function invokeStoryReviewCore({
   prNumber,
   provider,
   runCodeReviewFn,
-  runLocalLensReviewFn,
-  appendFindingsYieldFn,
   gitSpawnFn,
   progress,
 }) {
@@ -71,8 +69,6 @@ async function invokeStoryReviewCore({
     progressTag: 'REVIEW',
     runCodeReviewFn,
     gitSpawnFn,
-    ...(runLocalLensReviewFn ? { runLocalLensReviewFn } : {}),
-    ...(appendFindingsYieldFn ? { appendFindingsYieldFn } : {}),
   });
 }
 
@@ -131,8 +127,6 @@ async function postStoryReviewCrossRef({
  *   prNumber: number|null,
  *   provider: object,
  *   runCodeReviewFn: Function,
- *   runLocalLensReviewFn?: Function,
- *   appendFindingsYieldFn?: Function,
  *   gitSpawnFn?: Function,
  *   progress: (tag: string, msg: string) => void,
  * }} args
@@ -145,7 +139,6 @@ async function postStoryReviewCrossRef({
  *   degraded?: boolean,
  *   degradations?: Array<object>,
  *   crossRefPosted?: boolean,
- *   localLensReview?: object,
  * }>}
  */
 export async function runStoryScopeReview({
@@ -157,8 +150,6 @@ export async function runStoryScopeReview({
   prNumber,
   provider,
   runCodeReviewFn,
-  runLocalLensReviewFn,
-  appendFindingsYieldFn,
   gitSpawnFn,
   progress,
 }) {
@@ -192,8 +183,6 @@ export async function runStoryScopeReview({
     prNumber,
     provider,
     runCodeReviewFn,
-    runLocalLensReviewFn,
-    appendFindingsYieldFn,
     gitSpawnFn,
     progress,
   });
@@ -229,6 +218,5 @@ export async function runStoryScopeReview({
     postedCommentId: result.postedCommentId ?? null,
     ...degradationEnvelope(result.degradations),
     crossRefPosted,
-    localLensReview: result.localLensReview,
   };
 }

package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js

@@ -44,14 +44,15 @@ import {
   decideMergeWaitFailFast,
   deriveChecksStatus,
   deriveRedHeadRuns,
-  deriveRequiredRunEvidence,
   isPrMerged,
   MERGE_WAIT_GH_TIMEOUT_MS,
   parseWorkflowRunId,
+  pollIntervalMs,
   readRunSummary,
   resolveAdvisoryGateVerdict,
 } from '../../merge-poll.js';
 import { readMergeQueueState } from '../../merge-queue.js';
+import { readProbeRunEvidence } from '../../required-checks.js';
 import { NEXT_COMMANDS } from '../../story-deliver-terminal.js';
 import {
   postStructuredComment,
@@ -155,6 +156,7 @@ export async function readPrWaitProbe({
   gh = defaultGh,
   ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
   readMergeQueueStateFn = readMergeQueueState,
+  readRequiredCheckNamesFn,
 }) {
   try {
     const view = await withGhTimeout(
@@ -188,7 +190,14 @@ export async function readPrWaitProbe({
       }),
       // Head-anchored, so superseded/pending runs don't read as red; `null`
       // when the rollup is empty (the consecutive-probe fallback owns that).
-      requiredRunEvidence: deriveRequiredRunEvidence(view?.statusCheckRollup),
+      requiredRunEvidence: await readProbeRunEvidence({
+        view,
+        checksStatus,
+        prNumber,
+        gh,
+        ghTimeoutMs,
+        readFn: readRequiredCheckNamesFn,
+      }),
       redHeadRuns: deriveRedHeadRuns(view?.statusCheckRollup),
       headSha: readString(view?.headRefOid),
     };
@@ -1105,7 +1114,7 @@ export async function runConfirmMergePhase({
     remaining: rerunAllowance,
     issued: new Set(),
   };
-  const intervalMs = intervalSeconds * 1000;
+  let intervalMs = intervalSeconds * 1000;
   const startedAtMs = nowMsFn();
   let anchorMs = startedAtMs;
   let updatesUsed = 0;
@@ -1129,6 +1138,7 @@ export async function runConfirmMergePhase({
       ghTimeoutMs,
     });
     polls += 1;
+    intervalMs = pollIntervalMs(probe.checksStatus, intervalSeconds);
 
     anchorMs = resolveBudgetAnchorMs({
       createdAt: probe.createdAt,
@@ -1147,12 +1157,7 @@ export async function runConfirmMergePhase({
     // Heartbeat: a backgrounded close's output-file growth is its liveness signal.
     progress?.(
       'CONFIRM',
-      `⏱  poll ${polls}: PR #${prNumber} state=${probe.state ?? 'unknown'} ` +
-        `checks=${probe.checksStatus ?? 'unknown'} ` +
-        `mergeState=${probe.mergeStateStatus ?? 'unknown'} ` +
-        `(${waitBudget.waitedSeconds}s of ${maxWaitSeconds}s this invocation; ` +
-        `${waitBudget.cumulativeSeconds}s of ${maxBudgetSeconds}s cumulative)` +
-        (probe.error ? ` — probe error: ${probe.error}` : ''),
+      pollHeartbeat({ polls, prNumber, probe, waitBudget }),
     );
 
     if (isPrMerged(probe)) {
@@ -1324,13 +1329,24 @@ export async function runConfirmMergePhase({
     },
     predicate: (result) => result?.done === true,
     intervalMs,
-    // No pollUntil timeout: the tick owns both bounds and their classification.
-    sleepFn: (ms) => sleepFn(ms),
+    // No pollUntil timeout: the tick owns both bounds and the cadence.
+    sleepFn: () => sleepFn(intervalMs),
   });
   if (tick.thrown) throw tick.thrown;
   return tick.outcome;
 }
 
+function pollHeartbeat({ polls, prNumber, probe, waitBudget }) {
+  return (
+    `⏱  poll ${polls}: PR #${prNumber} state=${probe.state ?? 'unknown'} ` +
+    `checks=${probe.checksStatus ?? 'unknown'} ` +
+    `mergeState=${probe.mergeStateStatus ?? 'unknown'} ` +
+    `(${waitBudget.waitedSeconds}s of ${waitBudget.maxWaitSeconds}s this invocation; ` +
+    `${waitBudget.cumulativeSeconds}s of ${waitBudget.maxBudgetSeconds}s cumulative)` +
+    (probe.error ? ` — probe error: ${probe.error}` : '')
+  );
+}
+
 function doneWith(outcome) {
   return { done: true, outcome };
 }

package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js

@@ -282,11 +282,61 @@ async function stepPlanRunLabelReap({
 }
 
 /**
- * Run the post-land tail, sequentially. The ref reap and fast-forward (the
- * local-checkout mutations, reap first) run under a cross-process lock on the
- * main checkout, since concurrent closes race on the base ref and worktree
- * registry; GitHub steps stay outside it. The lock is best-effort: on
- * timeout the mutations run anyway.
+ * The local-checkout mutations (ref reap first, then fast-forward) under a
+ * cross-process lock on the main checkout, since concurrent closes race on
+ * the base ref and worktree registry. Best-effort: on timeout they run anyway.
+ */
+async function runLockedLocalSteps({
+  storyId,
+  storyBranch,
+  baseBranch,
+  cwd,
+  config,
+  progress,
+  gitSpawnFn,
+  planFastForwardFn,
+  executeFastForwardFn,
+  acquireLockWithWaitFn,
+}) {
+  const lockCfg = config?.delivery?.postLandLock ?? {};
+  const lock = await acquireLockWithWaitFn({
+    lockPath: postLandLockPath(cwd),
+    waitMs: lockCfg.waitMs,
+    pollMs: lockCfg.pollMs,
+    timeoutMs: lockCfg.timeoutMs,
+    ownerId: `post-land-${storyId}`,
+  });
+  if (!lock.acquired) {
+    progress?.(
+      'POST-LAND',
+      `⚠️ post-land lock not acquired (${lock.reason}); proceeding unserialized.`,
+    );
+  }
+  try {
+    const refCleanup = await step(
+      () => stepRefCleanup({ cwd, storyBranch, progress, gitSpawnFn }),
+      { name: 'local ref cleanup', progress },
+    );
+    const baseFastForward = await step(
+      () =>
+        stepBaseFastForward({
+          cwd,
+          baseBranch,
+          progress,
+          planFastForwardFn,
+          executeFastForwardFn,
+        }),
+      { name: 'base fast-forward', progress },
+    );
+    return { refCleanup, baseFastForward };
+  } finally {
+    if (lock.acquired) lock.release();
+  }
+}
+
+/**
+ * Run the post-land tail: friction markers, then the GitHub steps and the
+ * locked local steps concurrently, then temp purge, then lease release.
  *
  * @param {object} args
  * @param {number} args.storyId
@@ -348,87 +398,67 @@ export async function runPostLandTail({
     config,
   });
 
-  const followUps = await step(
-    () =>
-      stepFollowUps({
-        storyId,
-        provider,
-        config,
-        cwd,
-        progress,
-        captureStoryFollowUpsFn,
-      }),
-    { name: 'follow-up capture', progress },
-  );
-  const statusResync = await step(
-    () =>
-      stepStatusResync({
-        storyId,
-        provider,
-        config,
-        progress,
-        reassertStatusColumnFn,
-      }),
-    { name: 'status-column resync', progress },
-  );
-  await step(
-    () =>
-      stepPlanRunLabelReap({
-        storyId,
-        provider,
-        progress,
-        reapPlanRunLabelsForStoryFn,
-      }),
-    { name: 'plan-run label reap', progress },
-  );
-
-  const epicRollup = await step(
-    () =>
-      stepEpicRollup({
-        storyId,
-        provider,
-        config,
-        progress,
-        rollUpEpicForStoryFn,
-      }),
-    { name: 'epic rollup', progress },
-  );
-
-  const lockCfg = config?.delivery?.postLandLock ?? {};
-  const lock = await acquireLockWithWaitFn({
-    lockPath: postLandLockPath(cwd),
-    waitMs: lockCfg.waitMs,
-    pollMs: lockCfg.pollMs,
-    timeoutMs: lockCfg.timeoutMs,
-    ownerId: `post-land-${storyId}`,
-  });
-  if (!lock.acquired) {
-    progress?.(
-      'POST-LAND',
-      `⚠️ post-land lock not acquired (${lock.reason}); proceeding unserialized.`,
-    );
-  }
-  let refCleanup;
-  let baseFastForward;
-  try {
-    refCleanup = await step(
-      () => stepRefCleanup({ cwd, storyBranch, progress, gitSpawnFn }),
-      { name: 'local ref cleanup', progress },
-    );
-    baseFastForward = await step(
+  // The GitHub steps are independent of each other and of the local
+  // lock-held mutations, so all of them run concurrently.
+  const [followUps, statusResync, , epicRollup, local] = await Promise.all([
+    step(
       () =>
-        stepBaseFastForward({
+        stepFollowUps({
+          storyId,
+          provider,
+          config,
           cwd,
-          baseBranch,
           progress,
-          planFastForwardFn,
-          executeFastForwardFn,
+          captureStoryFollowUpsFn,
         }),
-      { name: 'base fast-forward', progress },
-    );
-  } finally {
-    if (lock.acquired) lock.release();
-  }
+      { name: 'follow-up capture', progress },
+    ),
+    step(
+      () =>
+        stepStatusResync({
+          storyId,
+          provider,
+          config,
+          progress,
+          reassertStatusColumnFn,
+        }),
+      { name: 'status-column resync', progress },
+    ),
+    step(
+      () =>
+        stepPlanRunLabelReap({
+          storyId,
+          provider,
+          progress,
+          reapPlanRunLabelsForStoryFn,
+        }),
+      { name: 'plan-run label reap', progress },
+    ),
+    step(
+      () =>
+        stepEpicRollup({
+          storyId,
+          provider,
+          config,
+          progress,
+          rollUpEpicForStoryFn,
+        }),
+      { name: 'epic rollup', progress },
+    ),
+    runLockedLocalSteps({
+      storyId,
+      storyBranch,
+      baseBranch,
+      cwd,
+      config,
+      progress,
+      gitSpawnFn,
+      planFastForwardFn,
+      executeFastForwardFn,
+      acquireLockWithWaitFn,
+    }),
+  ]);
+  const { refCleanup, baseFastForward } = local;
 
   // After every step that reads the temp artifacts; `signals.ndjson` survives.
   const tempPurge = await step(