mandrel 2.24.0 → 2.25.0

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

@@ -1,8 +1,9 @@
 /**
- * phases/pull-request.js — open or reuse the PR for a standalone Story.
+ * phases/pull-request.js — open, reuse, or decline to open the PR for a
+ * standalone Story.
  *
- * Probes for an existing open PR with `head = storyBranch`; creates one if
- * none exists. Returns the PR URL.
+ * Probes for an existing PR with `head = storyBranch`; creates one if none
+ * exists. Returns `{ url, alreadyMerged, created }`.
  *
  * `gh pr view --head` is not available on all `gh` versions, so we probe
  * with `gh pr list --head <branch>` and fall back to `gh pr create`.
@@ -13,17 +14,99 @@
  * error classification, timeout handling, and JSON parsing surface
  * instead of carrying its own `execFileSync('gh', …)` plumbing.
  *
+ * ## An already-merged PR is not an absent PR (Story #4873)
+ *
+ * The probe used to ask for `--state open` only. On the recovery path that is
+ * a false negative with teeth: a resumed close pushes the branch, the push
+ * turns the checks green, armed auto-merge lands the ORIGINAL PR server-side,
+ * and the resumed close then sees no OPEN PR on the head — so it opened a
+ * SECOND PR against a branch that is now byte-identical to base and
+ * squash-merged a zero-file commit onto `main`. Both halves of that are now
+ * closed:
+ *
+ *   1. The probe reads `--state all` and reports a MERGED PR on this head as
+ *      the outcome (`alreadyMerged: true`), so the caller lands on the merge
+ *      that already happened instead of manufacturing a new one. An OPEN PR
+ *      still wins over a merged one — a re-opened head is a live PR.
+ *   2. Creation is REFUSED outright when the head-versus-base diff contains no
+ *      files. An empty diff means there is nothing to merge, so a PR opened on
+ *      it can only ever produce an empty commit.
+ *
+ * The empty-diff guard fails **open**, not closed: `computeChangeSet` returns
+ * `files: null` when it cannot enumerate the diff at all, and absence of
+ * evidence must never block a legitimate PR — only a positively-observed empty
+ * file list refuses.
+ *
  * The function still accepts an injected `gh` facade so tests can wire
  * a fake without spawning real children.
  */
 
 import { gh as defaultGh } from '../../../gh-exec.js';
 import { Logger } from '../../../Logger.js';
+import { computeChangeSet as defaultComputeChangeSet } from '../../change-set.js';
 import { normalizePrTitle } from './normalize-pr-title.js';
 
 /**
- * Probe for an existing open PR with `head = storyBranch`; create one if
- * none exists. Returns the PR URL. Exported for testing.
+ * Pick the PR this head branch should resolve to from a `gh pr list
+ * --state all` projection. A live PR always wins; otherwise the first MERGED
+ * PR is the outcome to report. A head whose only PRs were CLOSED without
+ * merging resolves to nothing — there is a new PR to open.
+ *
+ * A row carrying a url but no recognizable `state` reads as live, not as
+ * nothing: the projection this phase asks for always includes `state`, so an
+ * absent one means an older/other `gh`, and the old `--state open` probe
+ * treated every returned row as a reusable open PR. Guessing "no PR" there is
+ * the failure mode with teeth — it opens a duplicate.
+ *
+ * Pure, and module-private on purpose: `ensurePullRequestWith` is the only
+ * caller and the only surface worth pinning, so the precedence is asserted
+ * through it rather than through a test-only export the production
+ * dead-export ratchet would then flag.
+ *
+ * @param {Array<{url?: string, state?: string, mergedAt?: string}>} rows
+ * @returns {{ url: string, state: 'OPEN'|'MERGED' }|null}
+ */
+function pickHeadPullRequest(rows) {
+  if (!Array.isArray(rows)) return null;
+  let merged = null;
+  for (const row of rows) {
+    const url = String(row?.url ?? '').trim();
+    if (!url) continue;
+    const state = String(row?.state ?? '').toUpperCase();
+    if (state === 'MERGED' || (state !== 'OPEN' && row?.mergedAt)) {
+      merged ??= { url, state: 'MERGED' };
+      continue;
+    }
+    if (state === 'CLOSED') continue;
+    return { url, state: 'OPEN' };
+  }
+  return merged;
+}
+
+/**
+ * Enumerate the head-versus-base diff and report whether it is positively
+ * empty. `null` (diff unenumerable) is NOT empty — see the module header.
+ *
+ * The diff is taken against `origin/<baseBranch>` when that ref resolves,
+ * because the local base ref can trail the remote by exactly the merge that
+ * makes this diff empty — the very state the guard exists to catch. It falls
+ * back to the local ref, and finally to "unknown", when the remote ref cannot
+ * be enumerated.
+ *
+ * @returns {{ empty: boolean, baseRef: string|null }}
+ */
+function probeEmptyDiff({ cwd, baseBranch, storyBranch, computeChangeSet }) {
+  for (const baseRef of [`origin/${baseBranch}`, baseBranch]) {
+    const set = computeChangeSet({ baseRef, headRef: storyBranch, cwd });
+    if (!set.enumerated) continue;
+    return { empty: (set.files ?? []).length === 0, baseRef };
+  }
+  return { empty: false, baseRef: null };
+}
+
+/**
+ * Probe for an existing PR with `head = storyBranch`; create one if none
+ * exists. Exported for testing.
  *
  * @param {{
  *   cwd: string,
@@ -32,9 +115,10 @@ import { normalizePrTitle } from './normalize-pr-title.js';
  *   storyBranch: string,
  *   baseBranch: string,
  *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
+ *   computeChangeSetFn?: typeof defaultComputeChangeSet,
  *   progress?: (tag: string, msg: string) => void,
  * }} args
- * @returns {Promise<string>}
+ * @returns {Promise<{ url: string, alreadyMerged: boolean, created: boolean }>}
  */
 export async function ensurePullRequestWith({
   cwd: _cwd,
@@ -43,6 +127,7 @@ export async function ensurePullRequestWith({
   storyBranch,
   baseBranch,
   gh = defaultGh,
+  computeChangeSetFn = defaultComputeChangeSet,
   progress = () => {},
 }) {
   // `cwd` is preserved on the call signature for backwards compatibility
@@ -51,22 +136,26 @@ export async function ensurePullRequestWith({
   // before invoking the phase, so the effective cwd matches the legacy
   // `execFileSync('gh', …, { cwd })` shape.
   try {
-    // `gh pr list --head <branch> --state open --json url` returns a
-    // JSON array of `{ url }` rows; an empty array means no open PR on
-    // this head. We pick the first entry's URL (matching the legacy
-    // `-q '.[0].url // empty'` projection on our side) so the typed
-    // `gh.pr.list` facade can stay generic.
+    // `gh pr list --head <branch> --state all --json url,state,mergedAt`
+    // returns a JSON array of rows; an empty array means this head has never
+    // had a PR. `--state all` (not `open`) is load-bearing — see the module
+    // header's duplicate-empty-PR note.
     const rows = await gh.pr.list(
-      ['--head', storyBranch, '--state', 'open'],
-      ['url'],
+      ['--head', storyBranch, '--state', 'all'],
+      ['url', 'state', 'mergedAt'],
     );
-    const existing =
-      Array.isArray(rows) && rows.length > 0
-        ? String(rows[0]?.url ?? '').trim()
-        : '';
-    if (existing) {
-      progress('PR', `Reusing existing PR: ${existing}`);
-      return existing;
+    const existing = pickHeadPullRequest(rows);
+    if (existing?.state === 'OPEN') {
+      progress('PR', `Reusing existing PR: ${existing.url}`);
+      return { url: existing.url, alreadyMerged: false, created: false };
+    }
+    if (existing?.state === 'MERGED') {
+      progress(
+        'PR',
+        `✅ PR for ${storyBranch} is already MERGED: ${existing.url} — ` +
+          'reporting that outcome instead of opening a second PR.',
+      );
+      return { url: existing.url, alreadyMerged: true, created: false };
     }
   } catch (err) {
     // `gh pr list` failure is recoverable — fall through to create. Log
@@ -76,6 +165,25 @@ export async function ensurePullRequestWith({
     );
   }
 
+  // Nothing to merge → nothing to open. Refused before `gh pr create` so the
+  // failure names the empty diff rather than surfacing later as a zero-file
+  // squash commit on the base branch.
+  const emptyDiff = probeEmptyDiff({
+    cwd: _cwd ?? process.cwd(),
+    baseBranch,
+    storyBranch,
+    computeChangeSet: computeChangeSetFn,
+  });
+  if (emptyDiff.empty) {
+    throw new Error(
+      `[single-story-close] refusing to open a pull request for ${storyBranch}: ` +
+        `the head-versus-base diff (${emptyDiff.baseRef}...${storyBranch}) contains no files. ` +
+        'An empty diff has nothing to merge, and a PR opened on it can only squash an empty ' +
+        'commit onto the base branch. If the work already landed, confirm the merge instead: ' +
+        `node .agents/scripts/single-story-confirm-merge.js --story ${storyId}`,
+    );
+  }
+
   progress('PR', `Opening PR for ${storyBranch} → ${baseBranch}...`);
   // The repo squash-merges and GitHub uses the PR title as the squash
   // subject on `main`. A raw human issue title is not a Conventional
@@ -110,7 +218,7 @@ export async function ensurePullRequestWith({
     ]);
     const url = (createResult?.stdout ?? '').trim();
     progress('PR', `✅ Opened: ${url}`);
-    return url;
+    return { url, alreadyMerged: false, created: true };
   } catch (err) {
     throw new Error(
       `[single-story-close] \`gh pr create\` failed: ${err?.message ?? err}`,

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

@@ -12,6 +12,7 @@ import { createProvider } from '../../provider-factory.js';
 import { flipLabelAndNotify } from '../../single-story/story-merged-notify.js';
 import { WorktreeManager } from '../../worktree-manager.js';
 import { runCodeReview as runCodeReviewDefault } from '../code-review.js';
+import { resolveRunScopedConfig } from '../run-scoped-config.js';
 import { releaseStoryLease } from '../single-story-lease-guard.js';
 import {
   buildTerminalEnvelope,
@@ -144,6 +145,7 @@ async function runPrePushPhases({
   worktreePath,
   config,
   baseBranch,
+  baseConfirmed,
   storyBranch,
   storyId,
   provider,
@@ -185,6 +187,7 @@ async function runPrePushPhases({
       cwd,
       worktreePath,
       baseBranch,
+      baseConfirmed,
       storyBranch,
       storyId,
       provider,
@@ -210,7 +213,7 @@ async function openAndReviewPr({
   setPhase('push');
   pushStoryBranch({ cwd, storyBranch, gitSync, progress });
   setPhase('pull-request');
-  const prUrl = await ensurePullRequestWith({
+  const { url: prUrl, alreadyMerged } = await ensurePullRequestWith({
     cwd,
     storyId,
     storyTitle: story.title,
@@ -220,6 +223,13 @@ async function openAndReviewPr({
     progress,
   });
   const prNumber = parsePrNumber(prUrl);
+  // Story #4873 — the head's PR already merged (an armed PR that landed while
+  // a previous close invocation was between phases). There is nothing left to
+  // review and nothing left to arm; the confirm phase probes the PR, observes
+  // MERGED, and lands the Story on the merge that actually happened.
+  if (alreadyMerged) {
+    return { prUrl, prNumber, alreadyMerged: true };
+  }
   setPhase('code-review');
   const reviewOutcome = await runStoryScopeReview({
     cwd,
@@ -245,7 +255,7 @@ async function openAndReviewPr({
         'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/deliver`.',
     );
   }
-  return { prUrl, prNumber };
+  return { prUrl, prNumber, alreadyMerged: false };
 }
 
 async function releaseLease({
@@ -443,7 +453,6 @@ async function runClosePipeline({
   const startedAtMs = Date.now();
   const config = injectedConfig || resolveConfig({ cwd: options.cwd });
   const provider = injectedProvider || createProvider(config);
-  const baseBranch = config.project?.baseBranch ?? 'main';
   const storyBranch = getStoryBranch(options.storyId);
 
   progress('INIT', `Closing standalone Story #${options.storyId}...`);
@@ -462,6 +471,22 @@ async function runClosePipeline({
     );
   }
 
+  // Story #4891 — the base branch this run was SEEDED from, read back off the
+  // run's `story-init` receipt rather than re-resolved from a config file that
+  // may have changed during the whole implementation window. Throws (fail
+  // closed, naming both values) when the pin and current config disagree —
+  // deliberately here, before the gate chain, format-autofix and base-sync,
+  // so a wrong base is never merged into the Story branch. `baseConfirmed`
+  // gates the base-merge remediation advice further down.
+  const { values: runScoped, confirmed: baseConfirmed } =
+    await resolveRunScopedConfig({
+      provider,
+      storyId: options.storyId,
+      config,
+      progress,
+    });
+  const baseBranch = runScoped.baseBranch;
+
   const worktreePath = resolveWorktreePath({
     cwd: options.cwd,
     config,
@@ -483,6 +508,7 @@ async function runClosePipeline({
         ...options,
         config,
         baseBranch,
+        baseConfirmed,
         storyBranch,
         provider,
         worktreePath,
@@ -493,7 +519,7 @@ async function runClosePipeline({
     leaseArgs,
   );
 
-  const { prUrl, prNumber } = await releaseLeaseOnBlock(
+  const { prUrl, prNumber, alreadyMerged } = await releaseLeaseOnBlock(
     () =>
       openAndReviewPr({
         cwd: options.cwd,
@@ -527,20 +553,31 @@ async function runClosePipeline({
     WorktreeManager,
   });
   setPhase('auto-merge');
+  // An already-merged head PR (Story #4873) has nothing to arm — `gh pr merge`
+  // against it fails, which would report the arm as a fault and block a Story
+  // whose work is already on the base branch. Skip the arm and let the confirm
+  // phase observe the merge that happened.
   const {
     autoMergeEnabled,
     autoMergeReason,
     localCleanupDeferred,
     directMerged,
-  } = await runAutoMergePhase({
-    cwd: options.cwd,
-    prNumber,
-    prUrl,
-    noAutoMerge: options.noAutoMerge,
-    autoMergePolicy: getCiDelivery(config).autoMerge,
-    gh: injectedGh,
-    progress,
-  });
+  } = alreadyMerged
+    ? {
+        autoMergeEnabled: true,
+        autoMergeReason: null,
+        localCleanupDeferred: false,
+        directMerged: false,
+      }
+    : await runAutoMergePhase({
+        cwd: options.cwd,
+        prNumber,
+        prUrl,
+        noAutoMerge: options.noAutoMerge,
+        autoMergePolicy: getCiDelivery(config).autoMerge,
+        gh: injectedGh,
+        progress,
+      });
   await flipLabelAndNotify({
     provider,
     notifyFn: injectedNotify,

package/.agents/scripts/lib/reserved-test-ids.js

@@ -0,0 +1,77 @@
+/**
+ * lib/reserved-test-ids.js — the framework's one declaration of which
+ * Epic / Story ids are **synthetic** (Story #4892).
+ *
+ * The band `999000–999999` has been reserved for test fixtures since the
+ * post-test temp reaper shipped, but it lived as a private regexp inside
+ * `cleanup-repo-test-temp.js` (`/^epic-999\d{3}$/`) and nothing else could
+ * consult it. Two independent surfaces need the same rule, and spelling it
+ * twice is how they would drift:
+ *
+ *   1. **Write side.** A test that spawns a real CLI at the repository root
+ *      inherits the real state directory, so its fixture telemetry can land
+ *      in the operator's live `temp/` signals tree. The post-run guard in
+ *      `check-test-temp-hygiene.js` fails the run when a stream file owned by
+ *      a reserved id survives there.
+ *   2. **Read side.** The retro composer renders the distinct Stories a
+ *      friction bucket spans as recurrence evidence in a body that is filed
+ *      as a real GitHub issue. A reserved id is synthetic by construction, so
+ *      it can never be resolved to a real issue and must never be published
+ *      as evidence (issue #4870 named `#999999` as a contributing Story).
+ *
+ * Deliberately dependency-free: the write side is a CLI guard and the read
+ * side is a pure composer, so the shared rule must not drag config, fs, or
+ * git resolution into either.
+ */
+
+/** First id in the reserved test-fixture band. */
+const RESERVED_TEST_ID_MIN = 999000;
+
+/** Last id in the reserved test-fixture band. */
+const RESERVED_TEST_ID_MAX = 999999;
+
+/**
+ * Human-readable band, for guard failure messages that have to tell an
+ * operator which ids they may not use for real work.
+ */
+export const RESERVED_TEST_ID_BAND = `${RESERVED_TEST_ID_MIN}–${RESERVED_TEST_ID_MAX}`;
+
+/**
+ * Is `id` inside the reserved test-fixture band?
+ *
+ * Exact-band membership, because this is the predicate the temp reaper and
+ * the pollution guard share: both classify an on-disk directory that a test
+ * created, and over-reaching (treating every large id as reserved) would let
+ * one of them delete or condemn a directory the band never claimed.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isReservedTestId(id) {
+  return (
+    Number.isInteger(id) &&
+    id >= RESERVED_TEST_ID_MIN &&
+    id <= RESERVED_TEST_ID_MAX
+  );
+}
+
+/**
+ * May `id` be published as ticket evidence in operator-visible output?
+ *
+ * The floor is the reserved band, not the band itself: an id at or above
+ * `RESERVED_TEST_ID_MIN` is synthetic by construction (the framework reserves
+ * that space for fixtures, and no repository has minted that many issues), so
+ * nothing at or beyond the floor can be resolved to a real issue. A
+ * non-integer or non-positive id is not a ticket reference at all.
+ *
+ * This is a plausibility bound, not an existence probe: it is the strongest
+ * statement a caller with no ticket-provider access can make, and it is what
+ * keeps the invariant true at every call site instead of only where somebody
+ * remembered to wire a probe.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isPublishableTicketId(id) {
+  return Number.isInteger(id) && id > 0 && id < RESERVED_TEST_ID_MIN;
+}

package/.agents/scripts/lib/story-plan.js

@@ -9,16 +9,24 @@
  *   - DEFAULT_REFINE_THRESHOLD     — seed length below which refinement
  *                                    is auto-suggested.
  *   - REQUIRED_SECTIONS            — canonical section headings the body
- *                                    must carry to be accepted by
- *                                    /single-story-deliver.
+ *                                    must carry itself. Story #4874: the
+ *                                    `## Acceptance` / `## Verify` sections
+ *                                    are deliberately NOT among them —
+ *                                    those lists are the ticket's top-level
+ *                                    machine contract and persist
+ *                                    synthesizes their sections, exactly as
+ *                                    the story-author prompt instructs.
  *   - rankDuplicateCandidates({ seed, openStories, maxResults })
  *                                  — Jaccard-overlap ranking of open
  *                                    Stories whose titles fuzzy-match
  *                                    the seed.
- *   - validateStoryBody(body)      — schema-light shape check:
- *                                    required sections present, no
- *                                    `Epic:` reference, AC checklist
- *                                    non-empty.
+ *   - validateStoryBody(body, contract)
+ *                                  — schema-light shape check against the
+ *                                    canonical Story-body contract: `##
+ *                                    Goal` / `## Changes` present, no
+ *                                    `Epic:` reference, and an
+ *                                    acceptance/verify contract resolvable
+ *                                    from the top-level arrays or the body.
  *   - buildContextEnvelope(opts)   — assemble the context envelope the
  *                                    host LLM consumes.
  */
@@ -26,21 +34,25 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { overlapScore, tokenize } from './duplicate-search.js';
+import { parse as parseStoryBody } from './story-body/story-body.js';
 
 export const DEFAULT_REFINE_THRESHOLD = 200;
 export const DEFAULT_DUPLICATE_MAX_RESULTS = 5;
 export const DEFAULT_DUPLICATE_MIN_SCORE = 0.15;
 
-export const REQUIRED_SECTIONS = [
-  'Context',
-  'Acceptance Criteria',
-  'Out of Scope',
-  'Notes',
-];
+/**
+ * The sections the authored body must carry itself. Story #4874 reconciled
+ * this list with the story-author prompt: the prompt tells the author to
+ * write `acceptance[]` / `verify[]` **once** at the ticket's top level and
+ * omit the matching body sections, so demanding those sections here made a
+ * prompt-faithful body unpersistable and cost a re-author round.
+ */
+export const REQUIRED_SECTIONS = ['Goal', 'Changes'];
+
+/** The contract lists persist synthesizes into the body from the top level. */
+const CONTRACT_FIELDS = /** @type {const} */ (['acceptance', 'verify']);
 
 const EPIC_REF_PATTERN = /^\s*Epic:\s*#\d+/m;
-const AC_HEADING_PATTERN = /^##\s+Acceptance Criteria\s*$/m;
-const CHECKLIST_PATTERN = /^\s*-\s*\[\s?\]/m;
 
 /**
  * Rank open Stories by title-overlap with the seed. Reuses the same
@@ -115,54 +127,137 @@ export function shouldRefine({
 }
 
 /**
- * Schema-light validator for a standalone-Story body. Used by the persist
- * path *and* by tests asserting `--dry-run` output stability. The check
- * is deliberately tolerant of authoring whitespace: it asserts the
- * canonical headings are present, that no `Epic: #N` reference leaks
- * (the standalone contract), and that the Acceptance Criteria section
- * carries at least one unchecked checklist item.
+ * Collect the violations for one contract list (`acceptance` / `verify`).
+ *
+ * The list may be authored at the ticket's top level (the shape the
+ * story-author prompt prescribes) or written into the body as a section —
+ * either satisfies the contract, and the top level is preferred because
+ * persist synthesizes the section from it. Only two shapes are violations:
+ * the list is nowhere, or it is in both places and the two disagree (fail
+ * closed rather than guess which is authoritative, mirroring
+ * `plan-persist`'s `syncContractFieldFromTopLevel`).
+ *
+ * @param {'acceptance'|'verify'} field
+ * @param {unknown} bodyList  The parsed body's section entries.
+ * @param {unknown} topLevel  The ticket's top-level array.
+ * @returns {string[]}
+ */
+function collectContractErrors(field, bodyList, topLevel) {
+  const inBody = (Array.isArray(bodyList) ? bodyList : []).map(String);
+  const inTicket = (Array.isArray(topLevel) ? topLevel : []).map(String);
+  if (inBody.length === 0 && inTicket.length === 0) {
+    return [
+      `${field} must list at least one entry — author it as the ticket's top-level ${field}[] array; persist synthesizes the "## ${field[0].toUpperCase()}${field.slice(1)}" section from it`,
+    ];
+  }
+  if (
+    inBody.length > 0 &&
+    inTicket.length > 0 &&
+    (inBody.length !== inTicket.length ||
+      inBody.some((v, i) => v !== inTicket[i]))
+  ) {
+    return [
+      `${field} disagrees between the body section and the top-level ${field}[] array — author it once, at the top level`,
+    ];
+  }
+  return [];
+}
+
+/**
+ * Schema-light validator for a standalone-Story body, stated against the
+ * same authoring shape the story-author prompt prescribes (Story #4874).
+ *
+ * It parses the body with the canonical Story-body parser and asserts:
+ * a non-empty `## Goal`, at least one `## Changes` entry, no leaking
+ * `Epic: #N` reference (the standalone contract), and an acceptance +
+ * verify contract resolvable from the ticket's top-level arrays **or** the
+ * body's own sections. It deliberately does not demand the `## Acceptance`
+ * / `## Verify` sections of the author — persist synthesizes them.
  *
  * @param {string} body
+ * @param {{ acceptance?: string[], verify?: string[] }} [contract]
+ *   The ticket's top-level contract arrays, when the caller has them.
  * @returns {{ ok:boolean, errors:string[] }}
  */
-export function validateStoryBody(body) {
-  const errors = [];
+export function validateStoryBody(body, contract = {}) {
   if (typeof body !== 'string' || body.trim().length === 0) {
     return { ok: false, errors: ['body is empty'] };
   }
 
-  for (const section of REQUIRED_SECTIONS) {
-    const pattern = new RegExp(`^##\\s+${escapeRegex(section)}\\s*$`, 'm');
-    if (!pattern.test(body)) {
-      errors.push(`missing required section: "## ${section}"`);
-    }
+  let parsed;
+  try {
+    parsed = parseStoryBody(body).body;
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [`body is not a parseable Story body: ${err.message}`],
+    };
   }
 
+  const errors = [];
+  if (typeof parsed.goal !== 'string' || parsed.goal.trim() === '') {
+    errors.push('missing required section: "## Goal"');
+  }
+  if (!Array.isArray(parsed.changes) || parsed.changes.length === 0) {
+    errors.push('missing required section: "## Changes"');
+  }
   if (EPIC_REF_PATTERN.test(body)) {
     errors.push(
       'body contains an "Epic: #N" reference — standalone Stories must not link to an Epic',
     );
   }
-
-  // AC checklist non-empty: extract from "## Acceptance Criteria" to the
-  // next "## " heading (or EOF) and assert at least one checklist item.
-  const acStart = body.search(AC_HEADING_PATTERN);
-  if (acStart !== -1) {
-    const rest = body.slice(acStart);
-    const nextHeading = rest.slice(1).search(/^##\s+/m);
-    const acBlock = nextHeading === -1 ? rest : rest.slice(0, nextHeading + 1);
-    if (!CHECKLIST_PATTERN.test(acBlock)) {
-      errors.push(
-        'Acceptance Criteria section has no unchecked checklist items (`- [ ] ...`)',
-      );
-    }
+  for (const field of CONTRACT_FIELDS) {
+    errors.push(
+      ...collectContractErrors(field, parsed[field], contract?.[field]),
+    );
   }
 
   return { ok: errors.length === 0, errors };
 }
 
-function escapeRegex(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Render the canonical `## Acceptance` / `## Verify` sections into a body
+ * that omits them, from the ticket's top-level arrays (Story #4874).
+ *
+ * This is the synthesis the story-author prompt promises: the author writes
+ * each list once at top level, and the persisted GitHub issue still reads as
+ * a complete executable document. A body that already carries a section is
+ * returned untouched — `validateStoryBody` has already refused the case
+ * where the two disagree.
+ *
+ * @param {string} body
+ * @param {{ acceptance?: string[], verify?: string[] }} [contract]
+ * @returns {string}
+ */
+export function synthesizeContractSections(body, contract = {}) {
+  let parsed;
+  try {
+    parsed = parseStoryBody(body).body;
+  } catch {
+    return body;
+  }
+  const blocks = [];
+  if (
+    (parsed.acceptance ?? []).length === 0 &&
+    Array.isArray(contract.acceptance) &&
+    contract.acceptance.length > 0
+  ) {
+    const items = contract.acceptance
+      .map((a, i) => `- [ ] AC-${i + 1}: ${a}`)
+      .join('\n');
+    blocks.push(`## Acceptance\n${items}`);
+  }
+  if (
+    (parsed.verify ?? []).length === 0 &&
+    Array.isArray(contract.verify) &&
+    contract.verify.length > 0
+  ) {
+    blocks.push(
+      `## Verify\n${contract.verify.map((v) => `- ${v}`).join('\n')}`,
+    );
+  }
+  if (blocks.length === 0) return body;
+  return `${body.trimEnd()}\n\n${blocks.join('\n\n')}\n`;
 }
 
 /**