mandrel 2.0.0 → 2.1.0

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,
+  });
+}

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -72,15 +72,65 @@ export async function gatherStoryFrictionSignals(storyId, config) {
   return signals;
 }
 
+/**
+ * Render the empty-roll-up line.
+ *
+ * Story #4578 — an empty roll-up over a multi-Story run must NOT read as
+ * success. The pre-#4578 text ("No friction signals — nothing to follow up")
+ * was *truthful* about the stream and *false* about the run: a 7-Story
+ * delivery containing a mid-run git outage, a parked worker, and a
+ * four-round acceptance critic rendered byte-identically to a genuinely
+ * clean run. An operator cannot tell "nothing went wrong" from "the
+ * telemetry never fired", and the second is likeliest exactly when the run
+ * went worst.
+ *
+ * So the line is a function of `storyCount`:
+ *   - `storyCount <= 1` → the honest, quiet reading is retained. A single
+ *     Story that emitted nothing plausibly *was* clean, and crying wolf on
+ *     every clean Story is how a warning channel gets tuned out.
+ *   - `storyCount > 1`  → zero signals across N Stories is a **claim**, and
+ *     the surrounding text says so and names the two readings, rather than
+ *     asserting the flattering one.
+ *
+ * This mirrors the sibling precedent in `run-epilogue.js`'s
+ * `renderDiffLines`, which refuses to let an unresolvable base diff render
+ * as "0 changed files".
+ *
+ * @param {number} storyCount
+ * @returns {string[]}
+ */
+function renderEmptyRollupLines(storyCount) {
+  if (storyCount <= 1) {
+    return ['_No friction signals — nothing to follow up._'];
+  }
+  return [
+    `> ⚠️ **0 friction signals across ${storyCount} Stories — this is a claim, not a clean bill of health.**`,
+    '> Either the run was genuinely friction-free, or telemetry never fired.',
+    '> An empty stream is indistinguishable from a clean run, and it is least',
+    '> likely to fill exactly when a run is going badly and the agent is busy.',
+    '> The runtime emits friction from its own observables (`agent::blocked`',
+    '> transitions, failed closes, exhausted merge waits) — so zero here also',
+    '> means none of those fired. If the run had friction you can name, that',
+    '> gap is itself the follow-up worth filing.',
+  ];
+}
+
 /**
  * @param {{
  *   storyId: number,
  *   proposals: object,
  *   graduated: object,
- * }} args
+ *   storyCount?: number,
+ * }} args - `storyCount` (default 1) is how many Stories the roll-up spans;
+ *   it decides whether an empty result reads as quiet or as a flagged claim.
  * @returns {string}
  */
-export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
+export function buildFollowUpsCommentBody({
+  storyId,
+  proposals,
+  graduated,
+  storyCount = 1,
+}) {
   const filed = Array.isArray(graduated?.filed) ? graduated.filed : [];
   const framework = proposals?.framework ?? [];
   const consumer = proposals?.consumer ?? [];
@@ -124,7 +174,7 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
     consumer.length === 0 &&
     discarded.length === 0
   ) {
-    lines.push('_No friction signals — nothing to follow up._');
+    lines.push(...renderEmptyRollupLines(storyCount));
     lines.push('');
   }
   lines.push('```json');
@@ -132,6 +182,7 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
     JSON.stringify(
       {
         storyId,
+        storyCount,
         framework: framework.map((i) => i.category),
         consumer: consumer.map((i) => i.category),
         discarded: discarded.map((i) => i.category),
@@ -139,6 +190,15 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
           category: i.category,
           url: i.url ?? null,
         })),
+        // Story #4578 — an empty roll-up over N>1 Stories is a claim worth
+        // flagging, not a success. Machine-readable twin of the warning
+        // prose so a caller need not regex the body.
+        emptyRollupSuspect:
+          storyCount > 1 &&
+          filed.length === 0 &&
+          framework.length === 0 &&
+          consumer.length === 0 &&
+          discarded.length === 0,
       },
       null,
       2,
@@ -149,8 +209,18 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
 }
 
 /**
- * Capture and persist Story follow-ups. Never throws — close must not fail
- * because follow-up filing flaked.
+ * Capture and persist Story follow-ups. Never throws — the land must not
+ * fail because follow-up filing flaked.
+ *
+ * Story #4543 retired the `captureFollowUpsAfterConfirm` action-gate wrapper
+ * (and its `withConfirmFollowUps` sibling) that used to front this function.
+ * Re-deriving "did the merge land?" from a confirmation envelope's `action`
+ * field was the coupling that made close-and-land — the DEFAULT path — skip
+ * capture entirely: the gate only opened on the standalone CLI's `done`, and
+ * a belated manual confirm could not backfill because the Story was already
+ * `agent::done` (confirm returns `noop`, the gate never opens). The shared
+ * land tail (`single-story-close/phases/post-land.js`) now calls this
+ * directly, after the merge is already confirmed.
  *
  * @param {object} args
  * @param {number} args.storyId
@@ -160,15 +230,6 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
  * @param {(tag: string, msg: string) => void} [args.progress]
  * @returns {Promise<object>}
  */
-/**
- * Capture follow-ups only when merge confirm landed (`action === 'done'`).
- * One-liner seam for the confirm-merge CLI.
- */
-export async function captureFollowUpsAfterConfirm(confirmation, ctx) {
-  if (confirmation?.action !== 'done') return null;
-  return captureStoryFollowUps(ctx);
-}
-
 export async function captureStoryFollowUps({
   storyId,
   provider,

package/.agents/scripts/lib/orchestration/story-init-remote.js

@@ -1,6 +1,9 @@
 import { Logger } from '../Logger.js';
-import { AGENT_LABELS } from '../label-constants.js';
-import { upsertStructuredComment } from './ticketing.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+  upsertStructuredComment,
+} from './ticketing.js';
 
 /**
  * Fail closed when the repository remote cannot be verified. The Story is
@@ -30,13 +33,14 @@ export async function handleRemoteVerificationFailure({
         `[single-story-init] failed to post remote-verification friction: ${err?.message ?? err}`,
       );
     }
+    // Story #4539 — the canonical mutator. This is the path where the
+    // skipped Projects v2 column sync (Story #2548) visibly drifts: the
+    // Story is still agent::ready (To Do) when the remote probe fails, so
+    // a direct label write leaves the board reading To Do for a blocked
+    // Story. single-story-init.js's own comment explains exactly why this
+    // must not bypass the mutator.
     try {
-      await provider.updateTicket(storyId, {
-        labels: {
-          add: [AGENT_LABELS.BLOCKED],
-          remove: [AGENT_LABELS.READY, AGENT_LABELS.EXECUTING],
-        },
-      });
+      await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {});
     } catch (err) {
       Logger.warn(
         `[single-story-init] failed to block Story after remote verification: ${err?.message ?? err}`,

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

@@ -1,9 +1,22 @@
+/**
+ * story-plan-state.js — read the v2 Story planning checkpoint.
+ *
+ * `plan-persist.js` upserts one `story-plan-state` structured comment per
+ * created Story carrying the persist receipt (when the plan completed, how many
+ * Stories it created, and their ids). Story #4542 removed the risk fields it
+ * used to carry: the planner-authored verdict, the envelope derived from it,
+ * and the review routing computed from that envelope. Nothing read any of them
+ * back — review depth is now derived from the diff at close time
+ * (`review-depth.js#deriveChangeLevel`), so no checkpoint read sits on the
+ * delivery path at all.
+ */
+
 import { parseFencedJsonComment } from './structured-comment-parser.js';
 import { findStructuredComment } from './ticketing.js';
 
 /**
  * Read the v2 Story planning checkpoint. Missing/malformed comments degrade
- * to null so unplanned Stories still receive the neutral review posture.
+ * to null — an unplanned Story simply has no persist receipt.
  */
 export async function readStoryPlanState({
   provider,
@@ -18,31 +31,3 @@ export async function readStoryPlanState({
   const state = parseFencedJsonComment(comment);
   return state && typeof state === 'object' ? state : null;
 }
-
-export async function readStoryPlanningRisk(args) {
-  const state = await readStoryPlanState(args);
-  return state?.planningRisk ?? null;
-}
-
-export async function readStoryPlanningRiskSafe(args) {
-  try {
-    return await readStoryPlanningRisk(args);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Prefer an explicit `planningRisk` override; otherwise load the Story
- * checkpoint. Callers that omit the field (or pass `undefined`) get the
- * persisted plan risk; callers that pass `null` keep the neutral posture.
- */
-export async function resolveStoryPlanningRisk({
-  provider,
-  storyId,
-  planningRisk,
-  findCommentFn,
-}) {
-  if (planningRisk !== undefined) return planningRisk;
-  return readStoryPlanningRiskSafe({ provider, storyId, findCommentFn });
-}

package/.agents/scripts/lib/orchestration/task-body-validator.js

@@ -24,6 +24,15 @@
  * name at least one path-shaped token so vague verbs ("clean up",
  * "refactor") can't slip through.
  *
+ * `acceptance` / `verify` are the **top-level machine contract** (Story
+ * #4541). The decomposer prompt tells authors to write those lists once at
+ * the ticket's top level and omit the matching body sections; persist syncs
+ * them into the body at assemble time. Validation runs *before* that sync,
+ * so this validator resolves each contract field from the parsed body and
+ * falls back to the ticket's top-level array when the body section is
+ * absent. Without that fallback the validator rejected the very shape its
+ * own prompt prescribes.
+ *
  * `body.changes` items must be object-form `{ path: string, assumption: enum }`
  * entries (Story #2636 shape). Plain string bullets are rejected at parse
  * time and by this validator.
@@ -51,8 +60,8 @@ import { FILE_ASSUMPTION_VALUES } from './file-assumption-enum.js';
 
 /**
  * Canonical testing-tier labels that a `verify[]` entry must name (in
- * parentheses) to pass plan-time validation. Mirrors the skill contract in
- * `core/epic-plan-decompose-author/SKILL.md § verify rules`.
+ * parentheses) to pass plan-time validation. Mirrors the verify-rules contract
+ * in `.agents/scripts/lib/templates/decomposer-prompts.js`.
  *
  * Entries that do not end with `(<tier>)` and are not `manual:<reason>` are
  * rejected by `collectVerifyErrors`.
@@ -164,6 +173,39 @@ function resolveStructuredBody(ticket) {
   }
 }
 
+/**
+ * The two contract fields that live at the ticket's top level and are
+ * synced into the body by `plan-persist` at assemble time.
+ */
+const CONTRACT_FIELDS = Object.freeze(['acceptance', 'verify']);
+
+/**
+ * Resolve the body's contract fields against the ticket's top-level arrays
+ * (Story #4541). The decomposer prompt prescribes authoring `acceptance[]`
+ * / `verify[]` **once** at top level and omitting the matching body
+ * sections; `assemblePlanStories#syncContractFieldFromTopLevel` performs
+ * the sync, but it runs *after* validation. So an absent body section is
+ * not a violation when the ticket carries the list at top level — it is the
+ * preferred shape. A body section that is present and disagrees with the
+ * top level is left alone here: the sync itself fails closed on that
+ * mismatch, and duplicating the check would report it twice.
+ *
+ * @param {object} ticket
+ * @param {object} bodyObject Parsed / structured body.
+ * @returns {object} A copy of `bodyObject` with the contract fields resolved.
+ */
+function resolveContractFieldsFromTopLevel(ticket, bodyObject) {
+  const resolved = { ...bodyObject };
+  for (const field of CONTRACT_FIELDS) {
+    const bodyValue = Array.isArray(resolved[field]) ? resolved[field] : [];
+    if (bodyValue.length > 0) continue;
+    const topLevel = Array.isArray(ticket?.[field]) ? ticket[field] : [];
+    if (topLevel.length === 0) continue;
+    resolved[field] = topLevel.map(String);
+  }
+  return resolved;
+}
+
 /**
  * Validate one Story body and return every violation it exhibits. Empty
  * array means clean. Splits the per-ticket cascade out of
@@ -182,13 +224,14 @@ function resolveStructuredBody(ticket) {
  */
 export function validateTaskBodyShape(ticket) {
   const prefix = `Story "${ticket.title}" (${ticket.slug})`;
-  const { body, error } = resolveStructuredBody(ticket);
+  const { body: parsed, error } = resolveStructuredBody(ticket);
   if (error !== null) {
     return [error];
   }
-  if (body === null || typeof body !== 'object') {
-    return [`${prefix}: body must be an object, got ${typeof body}.`];
+  if (parsed === null || typeof parsed !== 'object') {
+    return [`${prefix}: body must be an object, got ${typeof parsed}.`];
   }
+  const body = resolveContractFieldsFromTopLevel(ticket, parsed);
   const errors = [];
   if (typeof body.goal !== 'string' || body.goal.trim() === '') {
     errors.push(`${prefix}: body.goal must be a non-empty string.`);
@@ -300,7 +343,9 @@ function collectReferencesErrors(prefix, rawReferences) {
 function collectAcceptanceErrors(prefix, rawAcceptance) {
   const acceptance = Array.isArray(rawAcceptance) ? rawAcceptance : [];
   if (acceptance.length === 0) {
-    return [`${prefix}: body.acceptance must list at least one criterion.`];
+    return [
+      `${prefix}: acceptance must list at least one criterion — author it at the ticket's top level (preferred) or in the body's ## Acceptance section.`,
+    ];
   }
   return [];
 }
@@ -323,7 +368,7 @@ function collectVerifyErrors(prefix, rawVerify) {
   const verify = Array.isArray(rawVerify) ? rawVerify : [];
   if (verify.length === 0) {
     return [
-      `${prefix}: body.verify must list at least one entry. Use "manual:<reason>" only when truly unverifiable in isolation.`,
+      `${prefix}: verify must list at least one entry — author it at the ticket's top level (preferred) or in the body's ## Verify section. Use "manual:<reason>" only when truly unverifiable in isolation.`,
     ];
   }
   const errors = [];