mandrel 1.94.0 → 2.1.0

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

@@ -2,10 +2,12 @@
  * 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 unified `verification-results`
+ * Sits between the close-validation gate chain and merge in the deleted
+ * pre-v2 Epic close path (`runStoryCloseLocked` / `locked-pipeline.js`,
+ * merge target `epic/<id>`). The v2 `/deliver` path
+ * (`single-story-close.js`) reviews `main`…`story-<id>` instead. The
+ * configured ReviewProvider runs against the supplied base…head diff. The
+ * unified `verification-results`
  * structured comment is posted to the Story issue (default
  * `commentTargetId === ticketId` inside `runCodeReview`). Outcomes:
  *
@@ -39,7 +41,7 @@ import {
 import { gitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
 import { runCodeReview } from '../../code-review.js';
-import { emitBlockedCloseResult } from '../merge-runner.js';
+import { emitBlockedCloseResult } from '../emit-blocked.js';
 
 /**
  * The review depth the Story-scope local-lens pass runs at. Shift-left
@@ -203,15 +205,12 @@ function buildCodeReviewBlockedExtra({ storyId, reviewResult }) {
  *     `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.
+ * Review depth is not passed in: `runCodeReview` derives it entirely from the
+ * `baseRef...headRef` diff it enumerates itself — the changed files' sensitive-
+ * path intersection plus their count (Story #4542, which retired the
+ * planner-authored risk envelope this spine used to forward). Depth remains 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.
  *
  * @param {{
  *   storyId: number|string,
@@ -221,7 +220,6 @@ function buildCodeReviewBlockedExtra({ storyId, reviewResult }) {
  *   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,
  *   runLocalLensReviewFn?: typeof runLocalLensReview,
  * }} args
@@ -239,7 +237,6 @@ export async function runStoryReviewCore({
   provider,
   progress,
   progressTag = 'CODE-REVIEW',
-  planningRisk = null,
   runCodeReviewFn = runCodeReview,
   runLocalLensReviewFn = runLocalLensReview,
 }) {
@@ -258,12 +255,6 @@ export async function runStoryReviewCore({
   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;
-  }
 
   // Shift-left local-lens pass (Epic #4405). Runs matched local lenses at
   // `light` depth against the actual Story diff, inside this close-subprocess
@@ -282,29 +273,26 @@ export async function runStoryReviewCore({
 }
 
 /**
- * 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).
+ * Run a Story-scope code review against the supplied base…head diff
+ * (v2: `main`…`story-<id>` via `single-story-close.js`; pre-v2 Epic
+ * close: `epic/<id>`…`story-<id>`) and post the structured
+ * `code-review` comment to the Story issue. Returns `{ blocked }` where
+ * `blocked` is either `null` (caller proceeds to open/merge the PR) 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.
+ * Review depth is derived inside `runCodeReview` from this Story's own base…head
+ * diff — a narrow change touching a registered sensitive path earns `deep`, a
+ * small change touching none gets `light`, a wide diff earns `deep` on size, and
+ * an unenumerable diff resolves `standard` (Story #4542). Depth is input-only:
+ * it never changes `{ blocked }` or the posted comment.
  *
  * @param {{
  *   storyId: number|string,
- *   epicBranch: string,
+ *   baseBranch: 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,
  *   runLocalLensReviewFn?: typeof runLocalLensReview,
  * }} args
@@ -316,12 +304,11 @@ export async function runStoryReviewCore({
 export async function runStoryCodeReview(args) {
   const {
     storyId,
-    epicBranch,
+    baseBranch,
     storyBranch,
     provider,
     bus,
     progress,
-    planningRisk = null,
     runCodeReviewFn = runCodeReview,
     runLocalLensReviewFn = runLocalLensReview,
   } = args;
@@ -329,18 +316,17 @@ export async function runStoryCodeReview(args) {
   const storyIdNum = Number(storyId);
   progress(
     'CODE-REVIEW',
-    `Running Story-scope review (${epicBranch}…${storyBranch})...`,
+    `Running Story-scope review (${baseBranch}…${storyBranch})...`,
   );
 
   let reviewResult;
   try {
     reviewResult = await runStoryReviewCore({
       storyId: storyIdNum,
-      baseRef: epicBranch,
+      baseRef: baseBranch,
       headRef: storyBranch,
       provider,
       progress,
-      planningRisk,
       runCodeReviewFn,
       runLocalLensReviewFn,
     });

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -0,0 +1,360 @@
+/**
+ * story-deliver-terminal.js — the one terminal envelope every Story
+ * close-and-land invocation emits, and the shared next-command vocabulary
+ * (Story #4543).
+ *
+ * Before this module the delivery tail had **two** divergent return
+ * contracts, both prose and neither validated:
+ * `.agents/workflows/helpers/deliver-story.md` defined one shape and
+ * `.agents/agents/story-worker.md` a different one, so a caller could not
+ * distinguish a landed Story from a parked one without re-probing GitHub.
+ * `story-deliver-terminal.schema.json` is now the SSOT both docs reference
+ * rather than restate, and this module is its only writer.
+ *
+ * Two exports carry the contract:
+ *
+ *   - {@link buildTerminalEnvelope} assembles and **validates** the envelope.
+ *     It throws on a schema violation rather than emitting a malformed
+ *     terminal: a silently-wrong terminal is exactly the failure this Story
+ *     exists to eliminate, so failing loudly at the writer is the point.
+ *   - {@link NEXT_COMMANDS} is the next-command vocabulary shared with
+ *     `deliver-recover.js`, so a `pending` envelope and a recovery probe
+ *     name the same command for the same state instead of inventing two
+ *     dialects for one condition.
+ *
+ * `TERMINAL_EXIT_CODES` maps status → process exit code. `pending` gets its
+ * **own** code (3) precisely so a caller can tell "slow CI, resume me" from
+ * "hard block, come look" without parsing stdout — the distinction the
+ * pre-#4543 pipeline collapsed by treating budget exhaustion as a block.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'story-deliver-terminal.schema.json',
+);
+
+export const TERMINAL_ENVELOPE_KIND = 'story-deliver-terminal';
+
+/**
+ * status → process exit code.
+ *
+ * `pending` is **3**, not 0 and not 1. Zero would tell a headless caller the
+ * Story landed when it did not; one would conflate a resumable slow-CI wait
+ * with a hard block and send the operator to diagnose branch protection that
+ * is working fine. A distinct code is what lets `/deliver` resume without
+ * classifying.
+ */
+export const TERMINAL_EXIT_CODES = Object.freeze({
+  landed: 0,
+  pending: 3,
+  blocked: 1,
+  failed: 1,
+});
+
+export const TERMINAL_STATUSES = Object.freeze([
+  'landed',
+  'pending',
+  'blocked',
+  'failed',
+]);
+
+/**
+ * The shared next-command vocabulary. Every producer of a "what now?"
+ * answer — the `pending` terminal envelope and `deliver-recover.js` —
+ * builds its command from here, so the two surfaces never drift into
+ * naming different commands for the same observed state.
+ */
+export const NEXT_COMMANDS = Object.freeze({
+  /**
+   * Resume a bounded merge wait that expired with the PR still in flight.
+   *
+   * `--wait` is load-bearing: without it the confirm CLI probes once and
+   * answers `pending` again, so the cumulative-budget give-up never fires and
+   * a wedged PR is never escalated to anyone.
+   */
+  resumeLand: (storyId) =>
+    `node .agents/scripts/single-story-confirm-merge.js --story ${storyId} --wait`,
+  /** Confirm a merged-but-mislabelled Story (the idempotent flip + tail). */
+  confirmMerge: (storyId) =>
+    `node .agents/scripts/single-story-confirm-merge.js --story ${storyId}`,
+  /** Enter the red-CI fix loop against the failing PR. */
+  watchCi: (storyId, prNumber) =>
+    `node .agents/scripts/pr-watch-with-update.js --pr ${prNumber} --story ${storyId}`,
+  /** Re-run close for a Story whose PR was never opened. */
+  close: (storyId) =>
+    `node .agents/scripts/single-story-close.js --story ${storyId}`,
+  /** Resume implementation in the Story worktree. */
+  implement: (storyId) =>
+    `node .agents/scripts/single-story-init.js --story ${storyId}`,
+  /** Re-assert a drifted Projects v2 Status column. */
+  resync: (storyId) =>
+    `node .agents/scripts/resync-status-column.js --story ${storyId}`,
+  /** Probe a stranded Story and print its single next command. */
+  recover: (storyId) =>
+    `node .agents/scripts/deliver-recover.js --story ${storyId}`,
+});
+
+/** @type {Function|null} */
+let _validator = null;
+
+/**
+ * Compile (once) and return the terminal-envelope validator.
+ *
+ * @returns {Function}
+ */
+function getValidator() {
+  if (_validator) return _validator;
+  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  _validator = ajv.compile(schema);
+  return _validator;
+}
+
+/**
+ * Validate a candidate envelope against the shipped schema.
+ *
+ * @param {object} envelope
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateTerminalEnvelope(envelope) {
+  const validate = getValidator();
+  const valid = validate(envelope);
+  if (valid) return { valid: true, errors: [] };
+  const errors = (validate.errors ?? []).map(
+    (e) => `${e.instancePath || '/'} ${e.message}`,
+  );
+  return { valid: false, errors };
+}
+
+/**
+ * Drop `undefined`-valued keys so the schema's `additionalProperties: false`
+ * and its nullable unions both stay satisfiable from one optional-argument
+ * builder signature.
+ *
+ * @param {object} obj
+ * @returns {object}
+ */
+function compact(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Assemble the terminal envelope and validate it before returning.
+ *
+ * Throws a `TypeError` naming the schema violations when the assembled
+ * object does not validate. That is deliberate: the whole point of the
+ * envelope is that a caller can trust its status without re-probing
+ * GitHub, so emitting an unvalidated one would reintroduce the ambiguity
+ * this replaces.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {'landed'|'pending'|'blocked'|'failed'} args.status
+ * @param {string} args.phase
+ * @param {string} [args.storyBranch]
+ * @param {string} [args.baseBranch]
+ * @param {object|null} [args.pr]
+ * @param {object} [args.gates]
+ * @param {object|null} [args.tail]
+ * @param {object|null} [args.blocked]
+ * @param {object|null} [args.failure]
+ * @param {string|null} [args.nextCommand]
+ * @param {number} args.elapsedSeconds
+ * @param {object|null} [args.waitBudget]
+ * @param {string} [args.timestamp]
+ * @returns {object} The validated envelope.
+ */
+export function buildTerminalEnvelope({
+  storyId,
+  status,
+  phase,
+  storyBranch,
+  baseBranch,
+  pr,
+  gates,
+  tail,
+  blocked,
+  failure,
+  nextCommand,
+  elapsedSeconds = 0,
+  waitBudget,
+  timestamp = new Date().toISOString(),
+}) {
+  const envelope = compact({
+    kind: TERMINAL_ENVELOPE_KIND,
+    storyId: Number(storyId),
+    status,
+    phase,
+    storyBranch: storyBranch ?? null,
+    baseBranch: baseBranch ?? null,
+    pr: pr ?? null,
+    gates,
+    tail: tail ?? null,
+    blocked: blocked ?? null,
+    failure: failure ?? null,
+    nextCommand: nextCommand ?? null,
+    elapsedSeconds: Math.max(0, Number(elapsedSeconds) || 0),
+    waitBudget: waitBudget ?? null,
+    timestamp,
+  });
+
+  const { valid, errors } = validateTerminalEnvelope(envelope);
+  if (!valid) {
+    throw new TypeError(
+      `buildTerminalEnvelope: assembled envelope violates story-deliver-terminal.schema.json:\n` +
+        errors.map((e) => `  - ${e}`).join('\n'),
+    );
+  }
+  return envelope;
+}
+
+/**
+ * Resolve the process exit code for a terminal envelope.
+ *
+ * @param {object} envelope
+ * @returns {number}
+ */
+export function exitCodeForTerminal(envelope) {
+  return TERMINAL_EXIT_CODES[envelope?.status] ?? 1;
+}
+
+/** The markers a caller scans stdout for to recover the envelope. */
+export const TERMINAL_BEGIN_MARKER = '--- STORY DELIVER TERMINAL ---';
+export const TERMINAL_END_MARKER = '--- END TERMINAL ---';
+
+/**
+ * Write a terminal envelope to stdout, between its markers.
+ *
+ * **Deliberately not `Logger.info`.** The envelope is this CLI's
+ * machine-readable contract — every invocation emits exactly ONE, and a
+ * headless caller parses it out of stdout to decide what happened.
+ * `Logger.info` is level-gated, so under the documented
+ * `AGENT_LOG_LEVEL=silent` (§ 1.H) the envelope silently vanished and the
+ * caller got a bare exit code: precisely the "no envelope at all" outcome
+ * Story #4543 exists to remove. A contract payload must not be suppressible
+ * by a verbosity knob.
+ *
+ * Single home for the marker format so the four emit sites (the runner's
+ * terminal, the close CLI's failed-terminal catch, and both confirm-CLI
+ * paths) cannot drift apart.
+ *
+ * @param {object} envelope
+ * @param {{ write?: (s: string) => void }} [opts] `write` is a test seam.
+ * @returns {void}
+ */
+export function emitTerminalEnvelope(
+  envelope,
+  { write = (s) => process.stdout.write(s) } = {},
+) {
+  write(
+    `\n${TERMINAL_BEGIN_MARKER}\n${JSON.stringify(envelope, null, 2)}\n${TERMINAL_END_MARKER}\n`,
+  );
+}
+
+/**
+ * Map a `runConfirmMergePhase` outcome onto the schema-validated terminal
+ * envelope (Story #4543). One writer, one shape — the two prose contracts
+ * this replaces disagreed with each other precisely because each surface
+ * assembled its own.
+ *
+ * @returns {object} A validated `story-deliver-terminal` envelope.
+ */
+export function terminalFromWaitOutcome({
+  waitOutcome,
+  storyId,
+  storyBranch,
+  baseBranch,
+  prNumber,
+  prUrl,
+  autoMergeEnabled,
+  gates,
+  elapsedSeconds,
+}) {
+  const prBase = {
+    number: prNumber,
+    url: prUrl ?? null,
+    autoMergeEnabled: Boolean(autoMergeEnabled),
+  };
+  const common = {
+    storyId,
+    storyBranch,
+    baseBranch,
+    gates,
+    elapsedSeconds,
+  };
+
+  if (waitOutcome.terminal === 'landed') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'landed',
+      phase: 'post-land',
+      pr: {
+        ...prBase,
+        state: 'MERGED',
+        // The observed rollup, not an assumed 'success' — a merge can land by
+        // admin override or with non-required checks red.
+        checksStatus: waitOutcome.prProbe?.checksStatus ?? null,
+      },
+      tail: waitOutcome.tail,
+      nextCommand: null,
+    });
+  }
+
+  if (waitOutcome.terminal === 'pending') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'pending',
+      phase: 'confirm-merge',
+      pr: {
+        ...prBase,
+        state: waitOutcome.prProbe?.state ?? 'OPEN',
+        checksStatus: waitOutcome.prProbe?.checksStatus ?? null,
+      },
+      waitBudget: waitOutcome.waitBudget,
+      nextCommand: NEXT_COMMANDS.resumeLand(storyId),
+    });
+  }
+
+  // blocked — the classifier already named the class and the friction
+  // comment already carries the class-specific remediation, so the next
+  // command mirrors it rather than inventing a second opinion.
+  const nextCommand =
+    waitOutcome.blockClass === 'checks-failed'
+      ? NEXT_COMMANDS.watchCi(storyId, prNumber)
+      : waitOutcome.blockClass === 'merged-flip-failed'
+        ? NEXT_COMMANDS.confirmMerge(storyId)
+        : NEXT_COMMANDS.recover(storyId);
+  return buildTerminalEnvelope({
+    ...common,
+    status: 'blocked',
+    phase: 'confirm-merge',
+    pr: {
+      ...prBase,
+      state: waitOutcome.prProbe?.state ?? null,
+      checksStatus: waitOutcome.prProbe?.checksStatus ?? null,
+    },
+    blocked: {
+      blockClass: waitOutcome.blockClass,
+      reason: waitOutcome.reason,
+      frictionCommentId: waitOutcome.frictionCommentId ?? null,
+    },
+    nextCommand,
+  });
+}