mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -0,0 +1,426 @@
+/**
+ * run-epilogue.js — real per-run closeout for `/deliver --run`.
+ *
+ * After the last Story in a multi-Story plan-run lands, this module:
+ *   1. Selects the cross-Story audit lens roster over the combined landed
+ *      tip vs base (deterministic `selectAudits` — host walks lenses).
+ *   2. Rolls up friction follow-ups across every Story in the run and
+ *      files/posts them on the primary Story.
+ *   3. Checks sibling Spec/acceptance coherence across Story bodies.
+ *
+ * There is no inert planner-only path: `planRunEpilogue` enumerates steps
+ * and `runPlanRunEpilogue` executes them. Single-Story runs skip the
+ * epilogue (`applicable: false`).
+ *
+ * @module lib/orchestration/run-epilogue
+ */
+
+import { selectAudits } from '../audit-suite/index.js';
+import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
+import { gitSpawn } from '../git-utils.js';
+import { Logger } from '../Logger.js';
+import { forEachLine } from '../observability/signals-writer.js';
+import { composeRoutedProposals } from './retro-proposals.js';
+import {
+  buildFollowUpsCommentBody,
+  resolveFollowUpRepos,
+} from './story-follow-ups.js';
+import { upsertStructuredComment } from './ticketing.js';
+
+/**
+ * Canonical epilogue step kinds, in execution order.
+ * @type {readonly ['audit-roster', 'follow-up-rollup', 'sibling-coherence']}
+ */
+export const RUN_EPILOGUE_STEP_KINDS = Object.freeze([
+  'audit-roster',
+  'follow-up-rollup',
+  'sibling-coherence',
+]);
+
+/**
+ * @param {string|number|{ id?: string|number, slug?: string }} entry
+ * @returns {string|null}
+ */
+function normalizeStoryId(entry) {
+  if (typeof entry === 'string') return entry.trim() || null;
+  if (typeof entry === 'number' && Number.isInteger(entry)) {
+    return String(entry);
+  }
+  if (!entry || typeof entry !== 'object') return null;
+  if (typeof entry.id === 'string' || Number.isInteger(entry.id)) {
+    return String(entry.id).trim() || null;
+  }
+  return typeof entry.slug === 'string' ? entry.slug.trim() || null : null;
+}
+
+/**
+ * @param {Array<string|number|{ id?: string|number, slug?: string }>} stories
+ * @returns {string[]}
+ */
+function normalizeStoryIds(stories) {
+  const list = Array.isArray(stories) ? stories : [];
+  const seen = new Set();
+  const ids = [];
+  for (const entry of list) {
+    const id = normalizeStoryId(entry);
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    ids.push(id);
+  }
+  return ids;
+}
+
+/**
+ * Enumerate the ordered epilogue steps for a completed run.
+ *
+ * @param {object} args
+ * @param {string} args.planRunId
+ * @param {Array<string|number|{ id?: string|number, slug?: string }>} args.stories
+ * @returns {object}
+ */
+export function planRunEpilogue({ planRunId, stories } = {}) {
+  const ids = normalizeStoryIds(stories);
+  const runId =
+    typeof planRunId === 'string' && planRunId.trim() !== ''
+      ? planRunId.trim()
+      : null;
+
+  if (ids.length <= 1) {
+    return {
+      applicable: false,
+      planRunId: runId,
+      stories: ids,
+      steps: [],
+      reason:
+        ids.length === 0
+          ? 'no Stories in run'
+          : 'single-Story run — per-Story close is the end; no run-scoped epilogue',
+    };
+  }
+
+  // Positional `/deliver 101 102` has no plan-run label. Synthesize a
+  // stable adhoc id from the sorted Story set so the epilogue still
+  // anchors comments / audit roster without requiring `--run`.
+  const effectiveRunId =
+    runId ??
+    `adhoc-${[...ids].sort((a, b) => Number(a) - Number(b)).join('-')}`;
+
+  const steps = [
+    {
+      kind: 'audit-roster',
+      description: `Select cross-Story audit lenses for run ${effectiveRunId}`,
+      stories: ids,
+    },
+    {
+      kind: 'follow-up-rollup',
+      description: `Friction follow-up roll-up for run ${effectiveRunId}`,
+      stories: ids,
+    },
+    {
+      kind: 'sibling-coherence',
+      description: `Sibling-coherence check across the ${ids.length} Story specs of run ${effectiveRunId}`,
+      stories: ids,
+    },
+  ];
+
+  return {
+    applicable: true,
+    planRunId: effectiveRunId,
+    stories: ids,
+    steps,
+  };
+}
+
+async function listChangedFiles(cwd, baseRef = 'origin/main') {
+  try {
+    const result = gitSpawn(cwd, 'diff', '--name-only', `${baseRef}...HEAD`);
+    if (result.status !== 0) return [];
+    return String(result.stdout ?? '')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+async function executeAuditRoster({ planRunId, stories, cwd, provider }) {
+  const primaryId = Number(stories[0]);
+  const changedFiles = await listChangedFiles(cwd);
+  let selectedAudits = [];
+  if (Number.isInteger(primaryId) && primaryId > 0) {
+    const selected = await selectAudits({
+      ticketId: primaryId,
+      gate: 'gate3',
+      provider,
+      baseBranch: 'main',
+      headRef: 'HEAD',
+    });
+    selectedAudits = Array.isArray(selected?.selectedAudits)
+      ? selected.selectedAudits
+      : Array.isArray(selected)
+        ? selected
+        : [];
+  }
+  const body = [
+    '### plan-run-audit-roster',
+    '',
+    `Cross-Story audit roster for plan-run \`${planRunId}\`.`,
+    '',
+    `Changed files considered: ${changedFiles.length}.`,
+    '',
+    '**Selected lenses** (host MUST walk each against the combined landed diff):',
+    ...(selectedAudits.length > 0
+      ? selectedAudits.map((lens) => `- \`${lens}\``)
+      : ['- _(none — docs-only or no matching change-set lenses)_']),
+    '',
+    '```json',
+    JSON.stringify(
+      {
+        planRunId,
+        stories: stories.map(Number),
+        changedFiles,
+        selectedAudits,
+      },
+      null,
+      2,
+    ),
+    '```',
+  ].join('\n');
+  if (Number.isInteger(primaryId) && primaryId > 0) {
+    await upsertStructuredComment(
+      provider,
+      primaryId,
+      'plan-run-audit-roster',
+      body,
+    );
+  }
+  return {
+    kind: 'audit-roster',
+    selectedAudits,
+    changedFileCount: changedFiles.length,
+  };
+}
+
+async function executeFollowUpRollup({
+  planRunId,
+  stories,
+  provider,
+  config,
+  cwd,
+}) {
+  const signals = [];
+  for (const raw of stories) {
+    const sid = Number(raw);
+    if (!Number.isInteger(sid) || sid <= 0) continue;
+    await forEachLine(
+      null,
+      sid,
+      (parsed) => {
+        if (!parsed || typeof parsed !== 'object') return;
+        const category =
+          typeof parsed.category === 'string' ? parsed.category.trim() : '';
+        if (!category) return;
+        const source = parsed.source === 'framework' ? 'framework' : 'consumer';
+        signals.push({ category, source });
+      },
+      config,
+    );
+  }
+  const repos = resolveFollowUpRepos(config);
+  const primaryId = Number(stories[0]);
+  const proposals = composeRoutedProposals({
+    anchorId: Number.isInteger(primaryId) ? primaryId : 1,
+    anchorKind: 'run',
+    frameworkRepo: repos.frameworkRepo,
+    consumerRepo: repos.consumerRepo,
+    signals,
+    unresolvedBlockedEvents: [],
+  });
+  // Patch titles to mention the plan-run token (anchorKind run uses numeric id).
+  for (const item of [...proposals.framework, ...proposals.consumer]) {
+    item.title = item.title.replace(/plan-run \d+/, `plan-run ${planRunId}`);
+    item.body = item.body.replace(/plan-run \d+/g, `plan-run ${planRunId}`);
+  }
+  const graduated = await graduateRetroProposals({
+    epicId: primaryId,
+    provider,
+    config,
+    currentRepo: repos.currentRepo,
+    frameworkRepo: (() => {
+      const [owner, repo] = repos.frameworkRepo.split('/');
+      return { owner, repo };
+    })(),
+    routedProposals: proposals,
+    cwd,
+  });
+  if (Number.isInteger(primaryId) && primaryId > 0) {
+    const body = buildFollowUpsCommentBody({
+      storyId: primaryId,
+      proposals,
+      graduated,
+    }).replace(
+      `from Story #${primaryId}`,
+      `from plan-run \`${planRunId}\` (primary Story #${primaryId})`,
+    );
+    await upsertStructuredComment(provider, primaryId, 'follow-ups', body);
+  }
+  return {
+    kind: 'follow-up-rollup',
+    signalCount: signals.length,
+    filed: graduated.filed?.length ?? 0,
+  };
+}
+
+function extractSection(body, heading) {
+  if (typeof body !== 'string') return '';
+  const re = new RegExp(
+    `(?:^|\\n)## ${heading}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`,
+    'i',
+  );
+  const match = body.match(re);
+  return match ? match[1].trim() : '';
+}
+
+async function executeSiblingCoherence({ planRunId, stories, provider }) {
+  const findings = [];
+  const bodies = [];
+  for (const raw of stories) {
+    const sid = Number(raw);
+    if (!Number.isInteger(sid) || sid <= 0) continue;
+    const ticket = await provider.getTicket(sid);
+    bodies.push({
+      id: sid,
+      title: ticket?.title ?? '',
+      acceptance: extractSection(ticket?.body ?? '', 'Acceptance'),
+      spec: extractSection(ticket?.body ?? '', 'Spec'),
+    });
+  }
+  const withAcceptance = bodies.filter((b) => b.acceptance.length > 0);
+  if (withAcceptance.length > 0 && withAcceptance.length < bodies.length) {
+    const missing = bodies
+      .filter((b) => b.acceptance.length === 0)
+      .map((b) => `#${b.id}`);
+    findings.push(
+      `Stories missing ## Acceptance while siblings declare ACs: ${missing.join(', ')}`,
+    );
+  }
+  // Detect identical non-empty Spec blobs (likely copy-paste drift).
+  const specMap = new Map();
+  for (const b of bodies) {
+    if (!b.spec) continue;
+    const key = b.spec.replace(/\s+/g, ' ').slice(0, 400);
+    if (!specMap.has(key)) specMap.set(key, []);
+    specMap.get(key).push(b.id);
+  }
+  for (const ids of specMap.values()) {
+    if (ids.length > 1) {
+      findings.push(
+        `Duplicate ## Spec prose across Stories ${ids.map((id) => `#${id}`).join(', ')} — split or dedupe.`,
+      );
+    }
+  }
+  const primaryId = Number(stories[0]);
+  const body = [
+    '### plan-run-sibling-coherence',
+    '',
+    `Sibling-coherence check for plan-run \`${planRunId}\`.`,
+    '',
+    findings.length === 0
+      ? '_No coherence findings._'
+      : findings.map((f) => `- ${f}`).join('\n'),
+    '',
+    '```json',
+    JSON.stringify(
+      { planRunId, stories: stories.map(Number), findings },
+      null,
+      2,
+    ),
+    '```',
+  ].join('\n');
+  if (Number.isInteger(primaryId) && primaryId > 0) {
+    await upsertStructuredComment(
+      provider,
+      primaryId,
+      'plan-run-sibling-coherence',
+      body,
+    );
+  }
+  return { kind: 'sibling-coherence', findings };
+}
+
+/**
+ * Execute the per-run epilogue. Throws only on programmer misuse; step
+ * failures are collected into `errors[]`.
+ *
+ * @param {object} args
+ * @param {string} args.planRunId
+ * @param {Array<string|number>} args.stories
+ * @param {object} args.provider
+ * @param {object} [args.config]
+ * @param {string} [args.cwd]
+ * @returns {Promise<object>}
+ */
+export async function runPlanRunEpilogue({
+  planRunId,
+  stories,
+  provider,
+  config,
+  cwd = process.cwd(),
+} = {}) {
+  const plan = planRunEpilogue({ planRunId, stories });
+  if (!plan.applicable) {
+    return { ...plan, results: [], errors: [] };
+  }
+  if (!provider || typeof provider.getTicket !== 'function') {
+    throw new TypeError('runPlanRunEpilogue requires a ticketing provider');
+  }
+
+  const results = [];
+  const errors = [];
+  for (const step of plan.steps) {
+    try {
+      if (step.kind === 'audit-roster') {
+        results.push(
+          await executeAuditRoster({
+            planRunId: plan.planRunId,
+            stories: plan.stories,
+            cwd,
+            provider,
+          }),
+        );
+      } else if (step.kind === 'follow-up-rollup') {
+        results.push(
+          await executeFollowUpRollup({
+            planRunId: plan.planRunId,
+            stories: plan.stories,
+            provider,
+            config,
+            cwd,
+          }),
+        );
+      } else if (step.kind === 'sibling-coherence') {
+        results.push(
+          await executeSiblingCoherence({
+            planRunId: plan.planRunId,
+            stories: plan.stories,
+            provider,
+          }),
+        );
+      }
+    } catch (err) {
+      const message = err?.message ?? String(err);
+      Logger.warn(`[run-epilogue] step ${step.kind} failed: ${message}`);
+      errors.push({ kind: step.kind, message });
+    }
+  }
+
+  return {
+    applicable: true,
+    planRunId: plan.planRunId,
+    stories: plan.stories,
+    steps: plan.steps,
+    results,
+    errors,
+  };
+}

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

@@ -1,7 +1,7 @@
 /**
  * phases/auto-merge.js — enable GitHub native auto-merge on the PR.
  *
- * Mirrors the epic-deliver finalize call shape: squash strategy, delete
+ * Mirrors the v2 `single-story-close.js` finalize call shape: squash strategy, delete
  * the branch on merge. Non-fatal — returns `{ enabled: false, reason }`
  * on any failure so the caller can fall back to the operator-merges-button
  * path.

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

@@ -129,6 +129,7 @@ export async function runCloseValidationPhase({
       config,
       epicBranch: baseBranch,
       cwd: worktreePath || cwd,
+      log: (m) => Logger.info(m),
     }),
     log: (m) => Logger.info(m),
     storyId,

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

@@ -21,13 +21,14 @@
  * the caller raises that to a thrown error so auto-merge is not enabled.
  *
  * Delegates the `runCodeReview` invocation to `runStoryReviewCore`
- * (exported from `story-close/phases/code-review.js`) so both the
- * Epic-attached and standalone close paths share a single invocation
- * pattern (Story #3653).
+ * (exported from `story-close/phases/code-review.js`) so the close path
+ * shares a single invocation pattern (Story #3653). When `planningRisk`
+ * is omitted, loads it from the Story's `story-plan-state` checkpoint.
  */
 
 import { parsePrNumberFromUrl } from '../../../github-url.js';
 import { runStoryReviewCore } from '../../story-close/phases/code-review.js';
+import { resolveStoryPlanningRisk } from '../../story-plan-state.js';
 import { postStructuredComment } from '../../ticketing/state.js';
 
 /**
@@ -71,6 +72,79 @@ export function buildStoryReviewCrossRefBody({
   );
 }
 
+async function invokeStoryReviewCore({
+  storyId,
+  storyBranch,
+  baseBranch,
+  prNumber,
+  provider,
+  planningRisk,
+  runCodeReviewFn,
+  runLocalLensReviewFn,
+  progress,
+}) {
+  return runStoryReviewCore({
+    storyId,
+    baseRef: baseBranch,
+    headRef: storyBranch,
+    commentTargetId: prNumber,
+    provider,
+    planningRisk: await resolveStoryPlanningRisk({
+      provider,
+      storyId,
+      planningRisk,
+    }),
+    progress,
+    progressTag: 'REVIEW',
+    runCodeReviewFn,
+    // Forward the seam only when the caller injects it; otherwise
+    // `runStoryReviewCore` uses its default local-lens pass. `undefined`
+    // deep-merges to the default via the destructuring default there.
+    ...(runLocalLensReviewFn ? { runLocalLensReviewFn } : {}),
+  });
+}
+
+async function postStoryReviewCrossRef({
+  provider,
+  storyId,
+  prUrl,
+  prNumber,
+  result,
+  severity,
+  progress,
+}) {
+  if (result.posted && Number.isInteger(result.postedCommentId)) {
+    const commentUrl = `${prUrl}#issuecomment-${result.postedCommentId}`;
+    const body = buildStoryReviewCrossRefBody({
+      prUrl,
+      prNumber,
+      commentUrl,
+      severity,
+    });
+    try {
+      await postStructuredComment(provider, storyId, 'notification', body);
+      progress(
+        'REVIEW',
+        `📝 Cross-reference comment posted on Story #${storyId} → ${commentUrl}`,
+      );
+      return true;
+    } catch (err) {
+      progress(
+        'REVIEW',
+        `⚠️ Failed to post Story cross-reference comment: ${err?.message ?? err}`,
+      );
+      return false;
+    }
+  }
+  if (!result.posted) {
+    progress(
+      'REVIEW',
+      '⚠️ Skipping Story cross-reference comment: PR-side review comment did not post.',
+    );
+  }
+  return false;
+}
+
 /**
  * Run the Story-scope code review against `main`, post the structured
  * findings comment to the PR, and add a one-line cross-reference comment
@@ -93,6 +167,7 @@ export function buildStoryReviewCrossRefBody({
  *   prUrl: string,
  *   prNumber: number|null,
  *   provider: object,
+ *   planningRisk?: object|null, // omit to load from story-plan-state
  *   runCodeReviewFn: Function,
  *   runLocalLensReviewFn?: Function,
  *   progress: (tag: string, msg: string) => void,
@@ -115,6 +190,7 @@ export async function runStoryScopeReview({
   prUrl,
   prNumber,
   provider,
+  planningRisk,
   runCodeReviewFn,
   runLocalLensReviewFn,
   progress,
@@ -132,19 +208,16 @@ export async function runStoryScopeReview({
     `Running Story-scope code review for Story #${storyId} (${baseBranch}...${storyBranch}) → PR #${prNumber}...`,
   );
 
-  const result = await runStoryReviewCore({
+  const result = await invokeStoryReviewCore({
     storyId,
-    baseRef: baseBranch,
-    headRef: storyBranch,
-    commentTargetId: prNumber,
+    storyBranch,
+    baseBranch,
+    prNumber,
     provider,
-    progress,
-    progressTag: 'REVIEW',
+    planningRisk,
     runCodeReviewFn,
-    // Forward the seam only when the caller injects it; otherwise
-    // `runStoryReviewCore` uses its default local-lens pass. `undefined`
-    // deep-merges to the default via the destructuring default there.
-    ...(runLocalLensReviewFn ? { runLocalLensReviewFn } : {}),
+    runLocalLensReviewFn,
+    progress,
   });
 
   const sev = result.severity ?? {
@@ -158,34 +231,15 @@ export async function runStoryScopeReview({
     `Findings — critical:${sev.critical} high:${sev.high} medium:${sev.medium} suggestion:${sev.suggestion}. Posted to PR #${prNumber}: ${result.posted}.`,
   );
 
-  let crossRefPosted = false;
-  if (result.posted && Number.isInteger(result.postedCommentId)) {
-    const commentUrl = `${prUrl}#issuecomment-${result.postedCommentId}`;
-    const body = buildStoryReviewCrossRefBody({
-      prUrl,
-      prNumber,
-      commentUrl,
-      severity: sev,
-    });
-    try {
-      await postStructuredComment(provider, storyId, 'notification', body);
-      crossRefPosted = true;
-      progress(
-        'REVIEW',
-        `📝 Cross-reference comment posted on Story #${storyId} → ${commentUrl}`,
-      );
-    } catch (err) {
-      progress(
-        'REVIEW',
-        `⚠️ Failed to post Story cross-reference comment: ${err?.message ?? err}`,
-      );
-    }
-  } else if (!result.posted) {
-    progress(
-      'REVIEW',
-      '⚠️ Skipping Story cross-reference comment: PR-side review comment did not post.',
-    );
-  }
+  const crossRefPosted = await postStoryReviewCrossRef({
+    provider,
+    storyId,
+    prUrl,
+    prNumber,
+    result,
+    severity: sev,
+    progress,
+  });
 
   return {
     halted: !!result.halted,

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

@@ -10,6 +10,7 @@
 
 import path from 'node:path';
 import { parseSprintArgs } from '../../../cli-args.js';
+import { getDeliveryRouting } from '../../../config/delivery-routing.js';
 import { PROJECT_ROOT } from '../../../project-root.js';
 
 /**
@@ -27,11 +28,12 @@ function resolveFlag(paramValue, parsedValue, defaultValue) {
 }
 
 /**
- * Resolve the `waitForMerge` option: an explicit `--no-wait-merge` opt-out
- * always wins (preserves the pre-Story-#4428 exit shape even if a future
- * headless wrapper defaults to waiting); otherwise the explicit
- * `--wait-merge` / injected value governs, defaulting to `false` so
- * attended (non-headless) invocations are byte-identical to before.
+ * Resolve the `waitForMerge` option:
+ *   1. `--no-wait-merge` / injected opt-out always wins (stop at
+ *      `agent::closing`).
+ *   2. Explicit `--wait-merge` / injected true forces land-in-close.
+ *   3. Otherwise default from `delivery.routing.closeAndLand` (true) so
+ *      attended and headless delivers share the close-and-land happy path.
  *
  * @param {{ waitForMergeParam, noWaitForMergeParam, parsed }} raw
  * @returns {boolean}
@@ -41,13 +43,12 @@ function resolveWaitForMerge({
   noWaitForMergeParam,
   parsed,
 }) {
-  const optedOut = resolveFlag(
-    noWaitForMergeParam,
-    parsed.noWaitForMerge,
-    false,
-  );
-  if (optedOut) return false;
-  return resolveFlag(waitForMergeParam, parsed.waitForMerge, false);
+  if (resolveFlag(noWaitForMergeParam, parsed.noWaitForMerge, false)) {
+    return false;
+  }
+  const explicit = waitForMergeParam ?? parsed.waitForMerge;
+  if (typeof explicit === 'boolean') return explicit;
+  return getDeliveryRouting().closeAndLand;
 }
 
 /**
@@ -75,7 +76,9 @@ export function parseCloseOptions({
           skipSync: !!skipSyncParam,
           noAutoMerge: !!noAutoMergeParam,
           noFullScopeCrap: !!noFullScopeCrapParam,
-          waitForMerge: !!waitForMergeParam,
+          // Preserve undefined so resolveWaitForMerge can apply the
+          // closeAndLand config default when neither flag was injected.
+          waitForMerge: waitForMergeParam,
           noWaitForMerge: !!noWaitForMergeParam,
         }
       : parseSprintArgs();