mandrel 2.8.0 → 2.10.0

package/.agents/scripts/lib/orchestration/deliver-recover.js

@@ -263,9 +263,96 @@ export function decideRecovery({ storyId, ticket, branch, pr }) {
   };
 }
 
+/**
+ * The shapes a LIVE delivery process actively mutates while it runs. A probe
+ * that lands mid-close can read `executing` + `pr=none` seconds before the
+ * push and PR-open land, and confidently misdirect the operator to re-init a
+ * Story whose close is about to open a PR (observed live on Story #4712: two
+ * probes seconds apart flipped `executing-no-pr` → `executing-with-pr`).
+ * These shapes therefore earn a stability re-probe before the verdict is
+ * trusted; the remaining shapes (`merged-label-stale`, `blocked`,
+ * `done-board-drift`, `ready`) describe settled states no live process is
+ * racing to change.
+ */
+const TRANSIENT_SHAPES = new Set([
+  'executing-no-pr',
+  'executing-with-pr',
+  'closing-no-pr',
+  'closing-pr-pending',
+  'closing-pr-red',
+]);
+
+/**
+ * Default settle window between the two probes of the stability pass. Long
+ * enough for an in-flight push / `gh pr create` / label flip to land (each is
+ * a single network call), short enough that the read-only CLI stays
+ * interactive.
+ */
+const STABILITY_DELAY_MS = 5000;
+
+/**
+ * Build the verdict for a state observed mid-mutation: the two probe rounds
+ * derived DIFFERENT shapes, so neither is safe to act on — acting on the
+ * first misdirects (the #4712 shape), acting on the second may race the same
+ * live process again. The one next command is the probe itself, re-run once
+ * the live process settles.
+ *
+ * @param {{ storyId: number, first: object, second: object, delayMs: number }} args
+ * @returns {{ shape: string, nextCommand: string, detail: string, evidence: string[] }}
+ */
+function buildInTransitionVerdict({ storyId, first, second, delayMs }) {
+  return {
+    shape: 'in-transition',
+    nextCommand: NEXT_COMMANDS.recover(storyId),
+    detail:
+      `Two probes ${Math.round(delayMs / 1000)}s apart derived different shapes ` +
+      `(\`${first.shape}\` → \`${second.shape}\`): a delivery process is actively ` +
+      `mutating this Story's state right now (a push, PR open, or label flip landed ` +
+      `between the probes). Acting on either verdict risks duplicating or misdirecting ` +
+      `the live run. Wait for it to finish, then re-run this probe for a settled verdict.`,
+    evidence: [
+      `probe1.shape=${first.shape}`,
+      `probe2.shape=${second.shape}`,
+      ...second.evidence,
+    ],
+  };
+}
+
+/**
+ * One full probe round: ticket + branch + PR → decision. Throws only when
+ * the ticket itself is unreadable (the probe cannot run without it).
+ */
+async function probeAndDecide({
+  storyId,
+  storyBranch,
+  cwd,
+  provider,
+  config,
+  gh,
+  gitSpawnFn,
+}) {
+  const ticket = await probeTicket({ provider, storyId });
+  if (!ticket.ok) {
+    throw new Error(
+      `deliver-recover: could not read Story #${storyId}: ${ticket.error}`,
+    );
+  }
+  const branch = probeBranch({ cwd, storyBranch, config, gitSpawnFn });
+  const pr = await probePr({ storyBranch, gh });
+  const decision = decideRecovery({ storyId, ticket, branch, pr });
+  return { probes: { ticket, branch, pr }, decision };
+}
+
 /**
  * Probe live state and resolve the single next command. Read-only.
  *
+ * Transient shapes (`executing-*` / `closing-*`) get a **stability re-probe**
+ * (same consecutive-evidence pattern the merge wait's fail-fast uses, Story
+ * #4695): a second probe after a short settle window. Matching shapes return
+ * the fresher verdict; diverging shapes return `in-transition` instead of a
+ * confidently wrong command. Settled shapes skip the second round — their
+ * state has no live process racing to change it.
+ *
  * @param {object} args
  * @param {number} args.storyId
  * @param {string} args.cwd
@@ -273,6 +360,11 @@ export function decideRecovery({ storyId, ticket, branch, pr }) {
  * @param {object} [args.config]
  * @param {object} [args.gh]
  * @param {Function} [args.gitSpawnFn]
+ * @param {boolean} [args.reprobe=true] Disable to skip the stability pass
+ *   (single-probe legacy behavior — for scripted callers that own their own
+ *   settling).
+ * @param {number} [args.stabilityDelayMs] Settle window between the probes.
+ * @param {Function} [args.sleepFn] Test seam for the settle wait.
  * @returns {Promise<object>}
  */
 export async function recoverStory({
@@ -282,22 +374,57 @@ export async function recoverStory({
   config,
   gh = defaultGh,
   gitSpawnFn,
+  reprobe = true,
+  stabilityDelayMs = STABILITY_DELAY_MS,
+  sleepFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 }) {
   const storyBranch = getStoryBranch(storyId);
-  const ticket = await probeTicket({ provider, storyId });
-  if (!ticket.ok) {
-    throw new Error(
-      `deliver-recover: could not read Story #${storyId}: ${ticket.error}`,
-    );
+  const probeArgs = {
+    storyId,
+    storyBranch,
+    cwd,
+    provider,
+    config,
+    gh,
+    gitSpawnFn,
+  };
+
+  const first = await probeAndDecide(probeArgs);
+  if (!reprobe || !TRANSIENT_SHAPES.has(first.decision.shape)) {
+    return {
+      storyId,
+      storyBranch,
+      probes: first.probes,
+      stability: { reprobed: false },
+      ...first.decision,
+    };
   }
-  const branch = probeBranch({ cwd, storyBranch, config, gitSpawnFn });
-  const pr = await probePr({ storyBranch, gh });
-  const decision = decideRecovery({ storyId, ticket, branch, pr });
+
+  await sleepFn(stabilityDelayMs);
+  const second = await probeAndDecide(probeArgs);
+
+  if (second.decision.shape === first.decision.shape) {
+    // Stable across the settle window — trust the fresher evidence.
+    return {
+      storyId,
+      storyBranch,
+      probes: second.probes,
+      stability: { reprobed: true, stable: true, delayMs: stabilityDelayMs },
+      ...second.decision,
+    };
+  }
+
   return {
     storyId,
     storyBranch,
-    probes: { ticket, branch, pr },
-    ...decision,
+    probes: second.probes,
+    stability: { reprobed: true, stable: false, delayMs: stabilityDelayMs },
+    ...buildInTransitionVerdict({
+      storyId,
+      first: first.decision,
+      second: second.decision,
+      delayMs: stabilityDelayMs,
+    }),
   };
 }
 

package/.agents/scripts/lib/orchestration/merge-block-class.js

@@ -71,7 +71,7 @@
  * (`emit-merge-unlanded.js`).
  */
 
-import { failingChecksBlockMerge } from './merge-poll.js';
+import { requiredCheckFailedBlocksMerge } from './merge-poll.js';
 
 /**
  * Every class `classifyMergeBlock` can return. Order is the evaluation
@@ -169,12 +169,21 @@ function describeApiRaceFallback(prProbe, budget) {
  *      rejection surfaced AT arm time still routes to
  *      `branch-protection-human-required` rather than the generic
  *      `arm-failure`.
- *   1b. A red required check — `checks-failed` (Story #4543). Evaluated
- *      before every budget and probe signal because it is *definitive*:
- *      no amount of remaining budget turns a failed check green, and on a
- *      protected branch it also presents as `mergeStateStatus: 'BLOCKED'`,
- *      so leaving it to step 3 would attribute the operator's red test run
- *      to branch protection.
+ *   1b. A genuinely red required check — `checks-failed` (Story #4543,
+ *      head-anchored by Story #4695). Evaluated before every budget and
+ *      probe signal because it is *definitive*: no amount of remaining
+ *      budget turns a failed check green, and on a protected branch it also
+ *      presents as `mergeStateStatus: 'BLOCKED'`, so leaving it to step 3
+ *      would attribute the operator's red test run to branch protection.
+ *      Gated on `requiredCheckFailedBlocksMerge`: a run must have concluded
+ *      failure with none in flight — a red rollup while a required run is
+ *      merely queued is the protected-branch pending state, not this class.
+ *      The predicate also declines the verdict when the probe reports
+ *      `reviewDecision: 'REVIEW_REQUIRED'` (Story #4710): the rollup cannot
+ *      prove the red run is required, and a missing required review already
+ *      explains the BLOCKED merge state, so classification falls through to
+ *      the step-3 human-required verdict instead of misdirecting the
+ *      operator at a possibly-optional red check.
  *   2. Budget exhaustion while checks were still in flight —
  *      `checks-pending-timeout`. Evaluated BEFORE the human-required
  *      probe signals because on a protected branch GitHub reports
@@ -241,23 +250,35 @@ export function classifyMergeBlock(input) {
   // `undefined` (no probe at all) keeps its budget-timeout mapping in
   // step 2 without suppressing the step-3 human-required verdict.
   const checksStatus = prProbe?.checksStatus;
+  // A required run still queued/in-progress on the head is the
+  // protected-branch pending steady state (Story #4695), so it counts as
+  // in-flight evidence exactly like a `pending`/`still-running` aggregate —
+  // keeping a red-rollup-but-required-run-in-flight probe out of the
+  // human-required verdict below and into the timeout branch on budget expiry.
   const checksPendingEvidence =
-    checksStatus === 'pending' || checksStatus === 'still-running';
+    checksStatus === 'pending' ||
+    checksStatus === 'still-running' ||
+    prProbe?.requiredRunEvidence?.requiredRunInFlight === true;
 
   // 1b. A required check is RED. Definitive — no remaining budget makes a
   // failed check pass — so this precedes both the budget branch and the
   // BLOCKED-merge-state heuristic, which would otherwise attribute the red
   // check to branch protection on any protected base.
   //
-  // Gated on `failingChecksBlockMerge` rather than the raw rollup status:
-  // `checksStatus: 'failure'` covers optional checks too, and naming an
-  // optional red check as THE block sends the operator to fix a check that
-  // was never gating the merge. A red-but-not-gating PR that still failed to
-  // land falls through to the fallback, whose reason says exactly that.
-  if (failingChecksBlockMerge(prProbe)) {
+  // Gated on `requiredCheckFailedBlocksMerge` (Story #4695), not the raw
+  // rollup status: `checksStatus: 'failure'` covers optional checks AND the
+  // protected-branch pending state where a required run is merely queued (the
+  // rollup counts a cancelled superseded run as failure). Naming either as THE
+  // block sends the operator to fix a check that was never gating the merge —
+  // on a PR that merges on its own. Only head-anchored evidence of a genuinely
+  // red required run with none in flight classifies here; anything short of
+  // that falls through, keeps polling, and — on budget expiry with checks in
+  // flight — classifies `checks-pending-timeout` as before.
+  if (requiredCheckFailedBlocksMerge(prProbe)) {
+    const evidencePath = prProbe?.evidencePath;
     return {
       blockClass: 'checks-failed',
-      reason: `a required check failed (mergeStateStatus=${prProbe?.mergeStateStatus ?? 'n/a'})`,
+      reason: `a required check failed (mergeStateStatus=${prProbe?.mergeStateStatus ?? 'n/a'}${evidencePath ? `, evidence=${evidencePath}` : ''})`,
     };
   }
 

package/.agents/scripts/lib/orchestration/merge-poll.js

@@ -27,6 +27,20 @@
 export const DEFAULT_INTERVAL_SECONDS = 30;
 export const DEFAULT_MAX_BUDGET_SECONDS = 3600;
 
+/**
+ * Wall-clock bound for every `gh` subprocess the merge wait spawns (Story
+ * #4710). The wait is now routinely unattended (`delivery.mergeWatch.mode:
+ * "async"` runs it in a background invocation with no host tool ceiling), so
+ * a hung `gh pr view` / `gh pr update-branch` used to strand the wait with no
+ * terminal envelope, no label flip, and no friction record. Sixty seconds is
+ * generous for a single API round-trip while staying inside the async probe
+ * window; a timeout maps to the existing probe-error path, so the wait
+ * degrades to conservative-pending / `api-race-other` semantics instead of
+ * hanging. A framework constant by design — not config (Story #4710
+ * Non-Goals).
+ */
+export const MERGE_WAIT_GH_TIMEOUT_MS = 60_000;
+
 /**
  * Pure: derive an aggregate `checksStatus` (`success` | `still-running` |
  * `failure` | `unknown`) from a `statusCheckRollup` array (`gh pr view --json
@@ -57,6 +71,80 @@ export function deriveChecksStatus(statusCheckRollup) {
   return anyPending ? 'still-running' : 'success';
 }
 
+/**
+ * Pure: derive HEAD-ANCHORED per-run evidence from a `statusCheckRollup`
+ * array, distinguishing a genuinely red required run from the pending /
+ * superseded noise the aggregate {@link deriveChecksStatus} folds together.
+ *
+ * {@link deriveChecksStatus} returns `failure` the instant it sees ANY
+ * non-passing conclusion — including a `CANCELLED` superseded-push run or a
+ * sibling-invalidated run — even while the real required check is still
+ * queued. Paired with `mergeStateStatus: BLOCKED` (the protected-branch steady
+ * state while required checks run), that matched a merely *pending* PR and
+ * hard-blocked Stories whose PRs merged untouched. This derivation reads the
+ * two signals the fail-fast decision actually needs:
+ *
+ *   - `requiredRunFailed`   — a run on the head concluded `FAILURE` (or a
+ *                             legacy status context is `FAILURE`/`ERROR`).
+ *                             Deliberately NOT `CANCELLED`/`TIMED_OUT`/
+ *                             `SKIPPED`: those are the superseded-push and
+ *                             sibling-invalidated runs, not a red required
+ *                             check.
+ *   - `requiredRunInFlight` — any run on the head is still QUEUED /
+ *                             IN_PROGRESS (a CheckRun whose status is not
+ *                             `COMPLETED`, or a legacy status context still
+ *                             `PENDING`/`EXPECTED`).
+ *
+ * Returns `null` when the rollup is absent or empty — the evidence is
+ * unavailable and the caller must fall back to the consecutive-probe path
+ * (a single evidence-free failing snapshot must never fail-fast).
+ *
+ * **Contract honesty (Story #4710).** The `requiredRun*` field names describe
+ * what the evidence is USED to establish, not what this function reads: the
+ * `gh pr view` rollup projection carries no `isRequired` discriminator, so
+ * this derivation reads EVERY run on the head, required or not. On its own,
+ * `requiredRunFailed: true` therefore means "a head run genuinely concluded
+ * failure", and required-ness attribution is supplied downstream by
+ * {@link requiredCheckFailedBlocksMerge}, which admits the verdict only when
+ * `mergeStateStatus: BLOCKED` says GitHub itself gates the merge AND no
+ * review-required signal offers a competing explanation for that BLOCKED
+ * state. Do not treat this function's output as a required-only reading.
+ *
+ * @param {Array<{status?: string, conclusion?: string, state?: string}>} statusCheckRollup
+ * @returns {{ requiredRunFailed: boolean, requiredRunInFlight: boolean } | null}
+ */
+export function deriveRequiredRunEvidence(statusCheckRollup) {
+  if (!Array.isArray(statusCheckRollup) || statusCheckRollup.length === 0) {
+    return null;
+  }
+  let requiredRunFailed = false;
+  let requiredRunInFlight = false;
+  for (const check of statusCheckRollup) {
+    const conclusion = String(check?.conclusion ?? '').toUpperCase();
+    const status = String(check?.status ?? '').toUpperCase();
+    const state = String(check?.state ?? '').toUpperCase();
+    // In flight: a CheckRun not yet COMPLETED, or a legacy StatusContext still
+    // PENDING/EXPECTED. `status` is empty on a StatusContext, so it degrades to
+    // the `state` branch rather than counting as in-flight.
+    if (status && status !== 'COMPLETED') {
+      requiredRunInFlight = true;
+    } else if (state === 'PENDING' || state === 'EXPECTED') {
+      requiredRunInFlight = true;
+    }
+    // Genuinely red: FAILURE / ERROR only. CANCELLED / TIMED_OUT / SKIPPED are
+    // the superseded / sibling-invalidated noise a bare rollup miscounts.
+    if (
+      conclusion === 'FAILURE' ||
+      conclusion === 'ERROR' ||
+      state === 'FAILURE' ||
+      state === 'ERROR'
+    ) {
+      requiredRunFailed = true;
+    }
+  }
+  return { requiredRunFailed, requiredRunInFlight };
+}
+
 /**
  * The one `mergeStateStatus` value that means GitHub itself is gating the
  * merge. See {@link failingChecksBlockMerge}.
@@ -102,3 +190,128 @@ export function failingChecksBlockMerge(prProbe) {
     String(prProbe?.mergeStateStatus ?? '').toUpperCase() === MERGE_GATED_STATE
   );
 }
+
+/**
+ * Pure: does HEAD-ANCHORED evidence establish that a REQUIRED check is
+ * genuinely red — enough to fail-fast the merge wait as `checks-failed`?
+ *
+ * This is the single gated decision Story #4695 adds, and the named predicate
+ * a downstream async-confirm Story imports rather than reopening the poll
+ * loop's classification internals. It layers on {@link failingChecksBlockMerge}
+ * (the rollup-`failure` + `mergeStateStatus: BLOCKED` gate) the head-anchored
+ * refinement the raw gate lacked: classify `checks-failed` ONLY when a run
+ * genuinely concluded failure AND none is still in flight. A red rollup while
+ * a required run is queued/in-progress is the protected-branch pending steady
+ * state, not a failure.
+ *
+ * The evidence is read from `prProbe.requiredRunEvidence` (the
+ * {@link deriveRequiredRunEvidence} output threaded through the probe). When it
+ * is absent — older `gh`, an API error, or a probe that never carried a rollup
+ * — this returns `false`: the caller's consecutive-probe fallback owns that
+ * path, because a single evidence-free failing snapshot must never fail-fast.
+ *
+ * **Review-required softening (Story #4710).** The rollup evidence cannot
+ * prove the red run is a REQUIRED check (see
+ * {@link deriveRequiredRunEvidence}), so when the probe carries a competing
+ * explanation for the `BLOCKED` merge state — `reviewDecision:
+ * 'REVIEW_REQUIRED'`, i.e. a required approval is missing — this predicate
+ * declines the `checks-failed` verdict. A red *optional* check beside a
+ * missing required review used to fail-fast as `checks-failed` and send the
+ * operator to fix a check that was never gating the merge; with the review
+ * signal present, classification falls through to the
+ * `branch-protection-human-required` branch, which names the gate GitHub
+ * actually attributes. When a genuinely red required check coexists with a
+ * missing review, both are true blocks and the human-required verdict is
+ * still an honest one — the conservative direction (see
+ * {@link failingChecksBlockMerge} on why failing to fail fast is the cheap
+ * error).
+ *
+ * @param {{ checksStatus?: string, mergeStateStatus?: string,
+ *   reviewDecision?: string,
+ *   requiredRunEvidence?: { requiredRunFailed?: boolean, requiredRunInFlight?: boolean } }} [prProbe]
+ * @returns {boolean}
+ */
+export function requiredCheckFailedBlocksMerge(prProbe) {
+  if (!failingChecksBlockMerge(prProbe)) return false;
+  if (prProbe?.reviewDecision === 'REVIEW_REQUIRED') return false;
+  const evidence = prProbe?.requiredRunEvidence;
+  if (!evidence || typeof evidence.requiredRunFailed !== 'boolean') {
+    return false;
+  }
+  return (
+    evidence.requiredRunFailed === true && evidence.requiredRunInFlight !== true
+  );
+}
+
+/**
+ * Pure: the merge wait's single fail-fast decision (Story #4710 — extracted
+ * from the two near-verbatim inline blocks in `runConfirmMergePhase`'s poll
+ * loop, beside its sibling predicates).
+ *
+ * Encapsulates the Story #4695 evidence policy in one place:
+ *
+ *   - **Per-run evidence available** — decide on this single probe via
+ *     {@link requiredCheckFailedBlocksMerge}; a required run still in flight
+ *     (or only superseded / non-required noise red) resets the counter and
+ *     keeps polling.
+ *   - **Evidence unavailable** (older `gh`, API error, empty rollup) — require
+ *     TWO consecutive failing probes at least one poll interval apart, then
+ *     synthesize the evidence shape the classifier's gate reads so both paths
+ *     classify `checks-failed` through the same predicate.
+ *
+ * Returns the next counter value alongside the verdict; the caller owns the
+ * mutable counter and the terminal side effects. When `failFast` is `true`,
+ * `prProbe` is the evidence-stamped probe to hand to the classifier and
+ * `evidencePath` names which path fired (`per-run` | `consecutive-probe`) for
+ * the `merge.unlanded` telemetry.
+ *
+ * @param {object} args
+ * @param {object} args.probe The current poll's {@code readPrWaitProbe} result.
+ * @param {number} args.consecutiveRequiredFailSnapshots Evidence-free failing
+ *   probes observed so far.
+ * @returns {{ failFast: boolean, consecutiveRequiredFailSnapshots: number,
+ *   prProbe?: object, evidencePath?: 'per-run'|'consecutive-probe' }}
+ */
+export function decideMergeWaitFailFast({
+  probe,
+  consecutiveRequiredFailSnapshots,
+}) {
+  if (!failingChecksBlockMerge(probe)) {
+    return { failFast: false, consecutiveRequiredFailSnapshots: 0 };
+  }
+  if (probe?.requiredRunEvidence) {
+    if (requiredCheckFailedBlocksMerge(probe)) {
+      return {
+        failFast: true,
+        consecutiveRequiredFailSnapshots: 0,
+        evidencePath: 'per-run',
+        prProbe: { ...probe, evidencePath: 'per-run' },
+      };
+    }
+    // A required run is still in flight, only non-required / superseded runs
+    // are red, or a missing required review owns the BLOCKED state: the
+    // protected-branch steady state, not a failure. Keep polling.
+    return { failFast: false, consecutiveRequiredFailSnapshots: 0 };
+  }
+  const next = consecutiveRequiredFailSnapshots + 1;
+  // Synthesize the evidence the classifier's gate reads, so the
+  // consecutive-probe path classifies `checks-failed` through the SAME
+  // predicate as the per-run path (including its review-required softening).
+  const synthesized = {
+    ...probe,
+    requiredRunEvidence: {
+      requiredRunFailed: true,
+      requiredRunInFlight: false,
+    },
+    evidencePath: 'consecutive-probe',
+  };
+  if (next >= 2 && requiredCheckFailedBlocksMerge(synthesized)) {
+    return {
+      failFast: true,
+      consecutiveRequiredFailSnapshots: next,
+      evidencePath: 'consecutive-probe',
+      prProbe: synthesized,
+    };
+  }
+  return { failFast: false, consecutiveRequiredFailSnapshots: next };
+}

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -26,6 +26,7 @@ import {
   renderTechSpecSystemPrompt,
 } from '../templates/spec-author-prompts.js';
 import { concurrentMap } from '../util/concurrent-map.js';
+import { buildComplexityRouteSignal } from './complexity-gate.js';
 import { parseDeliverySlicingTable } from './consolidation-precondition.js';
 import { buildDocsDigest } from './docs-digest.js';
 import { buildAuthoringContext } from './planning/authoring-context.js';
@@ -137,6 +138,63 @@ export const TICKET_SCHEMA_DESCRIPTOR = Object.freeze({
     'validateAndNormalizeTickets (lib/orchestration/ticket-validator.js) at persist time',
 });
 
+/**
+ * Filename of the ready-to-fill Story authoring template `plan-context.js`
+ * writes next to the captured envelope (Story #4707).
+ */
+export const STORIES_TEMPLATE_FILENAME = 'stories.template.json';
+
+/**
+ * Render the ready-to-fill `stories.json` authoring template (Story #4707).
+ *
+ * One-shot authoring: the planner copies this file to `stories.json`, fills
+ * the placeholder values, and runs persist — no step requires reading
+ * `story-body.js` source or re-poking the envelope for format discovery
+ * (bench: ~7 of 17 plan turns were format discovery). The template uses the
+ * **structured-object body** shape, which persist parses and serializes to
+ * the canonical markdown itself (`parse` accepts an object;
+ * `assembleOnePlanStory` re-serializes canonically), so the serializer
+ * contract never has to be reverse-engineered by the author. `acceptance[]`
+ * / `verify[]` live at the ticket's top level — the machine contract persist
+ * syncs into the body.
+ *
+ * Pure and deterministic; the output is valid JSON (parseable as-is), with
+ * instructive placeholder values rather than comments.
+ *
+ * @returns {string} Pretty-printed JSON template content.
+ */
+export function renderStoriesTemplate() {
+  const template = [
+    {
+      slug: 'fill-hyphen-case-slug',
+      type: 'story',
+      title: 'Fill: short descriptive title',
+      body: {
+        goal: 'Fill: one sentence stating why this Story exists.',
+        spec:
+          'Optional — contract and invariants only: interfaces, status ' +
+          'codes, security invariants, and load-bearing constraints with ' +
+          'their why. Implementation choices belong to the deliverer unless ' +
+          'load-bearing. No per-file behavior paragraphs, no current-state ' +
+          'narration. Delete this field when acceptance[] carries the whole ' +
+          'contract.',
+        changes: [
+          { path: 'path/to/file.ext', assumption: 'refactors-existing' },
+        ],
+        non_goals: [],
+        reason_to_exist:
+          'Fill: the single coherent reason this Story exists (one sentence).',
+      },
+      acceptance: [
+        'Fill: a testable, observable criterion (a command exits 0, a file exists, a test matches)',
+      ],
+      verify: ['Fill: exact command or test path (unit|contract|e2e|validate)'],
+      depends_on: [],
+    },
+  ];
+  return `${JSON.stringify(template, null, 2)}\n`;
+}
+
 /**
  * Count top-level enumerated items (`- `, `* `, `1. `) anywhere in a
  * free-form seed text. Unlike {@link countScopeItems} this does not require
@@ -482,6 +540,7 @@ async function buildSeedFileModeEnvelope({
   return {
     mode: modeLabel,
     seed: { path: seedFilePath ?? null, content },
+    complexityRoute: buildComplexityRouteSignal({ seedText: content, config }),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,
@@ -635,6 +694,7 @@ async function buildTicketsModeEnvelope({
     mode: 'tickets',
     sourceTickets,
     seed: { text: seed, path: null },
+    complexityRoute: buildComplexityRouteSignal({ seedText: seed, config }),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,