mandrel 1.84.0 → 1.85.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/finalizer.js

@@ -24,7 +24,11 @@
  *   4. Otherwise, invoke `runFinalizeFn`. The production default
  *      (`composeBusOwnedFinalize`) chains
  *        a. `openOrLocatePr({ epicId, headBranch, baseBranch })`
- *        b. `postHandoffComment({ epicId, prNumber, prUrl, provider })`
+ *        b. `markPrReady({ pr })` when `delivery.ci.earlyPr` is on
+ *           (Story #4359) — the wave-1 draft is flipped ready-for-review;
+ *           skipped when `earlyPr` is off (the PR was opened here, never a
+ *           draft).
+ *        c. `postHandoffComment({ epicId, prNumber, prUrl, provider })`
  *      and returns `{ prNumber, prUrl, handoff }`. (Story #4324 retired
  *      the `closePlanningTickets` sweep with the context-ticket classes —
  *      there are no planning tickets to close.)
@@ -60,13 +64,17 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { getCiDelivery } from '../../../config/ci.js';
 import {
   graduateAuditResults as defaultGraduateAuditResults,
   isAutoFileEnabled as isAuditResultsAutoFileEnabled,
 } from '../../../feedback-loop/audit-results-graduator.js';
 import { graduateFindings as defaultGraduateFindings } from '../../../feedback-loop/code-review-graduator.js';
 import { parsePrNumberFromUrl } from '../../../github-url.js';
-import { openOrLocatePr as defaultOpenOrLocatePr } from '../../finalize/open-or-locate-pr.js';
+import {
+  markPrReady as defaultMarkPrReady,
+  openOrLocatePr as defaultOpenOrLocatePr,
+} from '../../finalize/open-or-locate-pr.js';
 import { postHandoffComment as defaultPostHandoffComment } from '../../finalize/post-handoff-comment.js';
 
 /**
@@ -79,17 +87,31 @@ import { postHandoffComment as defaultPostHandoffComment } from '../../finalize/
  * `{ blocker: { reason, detail } }` when a step fails with an
  * unrecoverable error that should keep the Epic at `agent::blocked`.
  *
+ * Story #4359 (Epic #4355) — early-PR draft mode. When `earlyPr` is on
+ * (the default resolved via `getCiDelivery`), the Epic PR already exists
+ * as a draft (opened at wave 1). Finalize then **locates** it (the
+ * `openOrLocatePr` probe short-circuits to `created: false`) and flips it
+ * ready-for-review via `markPrReady` rather than opening the draft as a
+ * `--draft`. When `earlyPr` is off, finalize opens the PR here with no
+ * draft — the pre-Story close-time timing. In both modes the title/body
+ * contract is identical and `markPrReady` is a no-op on an already-ready
+ * PR, so replay stays idempotent.
+ *
  * @param {{
  *   provider?: object|null,
+ *   earlyPr?: boolean,
  *   openOrLocatePrFn?: typeof defaultOpenOrLocatePr,
+ *   markPrReadyFn?: typeof defaultMarkPrReady,
  *   postHandoffCommentFn?: typeof defaultPostHandoffComment,
  * }} deps
  */
 export function composeBusOwnedFinalize(deps = {}) {
   const openOrLocatePrFn = deps.openOrLocatePrFn ?? defaultOpenOrLocatePr;
+  const markPrReadyFn = deps.markPrReadyFn ?? defaultMarkPrReady;
   const postHandoffCommentFn =
     deps.postHandoffCommentFn ?? defaultPostHandoffComment;
   const provider = deps.provider ?? null;
+  const earlyPr = deps.earlyPr !== false;
 
   return async function runBusOwnedFinalize({ epicId, cwd } = {}) {
     if (!Number.isInteger(epicId) || epicId < 1) {
@@ -129,6 +151,24 @@ export function composeBusOwnedFinalize(deps = {}) {
       };
     }
 
+    // Story #4359: when earlyPr is on, the located PR is the wave-1 draft —
+    // flip it ready-for-review. `gh pr ready` on an already-ready PR is a
+    // no-op, so a replay (or an earlyPr-off PR that was never a draft) is
+    // safe. A failure here is a hard blocker: leaving the PR a draft would
+    // silently park the merge gate.
+    if (earlyPr) {
+      try {
+        await markPrReadyFn({ pr: openResult.url, cwd });
+      } catch (err) {
+        return {
+          blocker: {
+            reason: 'mark-pr-ready-failed',
+            detail: err?.message ?? String(err),
+          },
+        };
+      }
+    }
+
     // The handoff comment requires a provider. The lifecycle-emit CLI
     // may construct the Finalizer without one; in that case the step
     // short-circuits (the run itself still succeeds — the PR is open and
@@ -256,9 +296,14 @@ export class Finalizer {
     this.cwd = opts.cwd ?? process.cwd();
     this.fullScope = opts.fullScope === true;
     this.provider = opts.provider ?? null;
+    // Story #4359: gate the finalize PR-open/ready branch on
+    // `delivery.ci.earlyPr` (default true) resolved via getCiDelivery.
+    // On → the wave-1 draft is located and marked ready; off → the PR is
+    // opened here at close time (pre-Story timing).
+    const earlyPr = getCiDelivery(opts.config ?? null).earlyPr;
     this.runFinalizeFn =
       opts.runFinalizeFn ??
-      composeBusOwnedFinalize({ provider: this.provider });
+      composeBusOwnedFinalize({ provider: this.provider, earlyPr });
     this.ghPrListHeadFn = opts.ghPrListHeadFn ?? ghPrListHead;
     // ultrareview bug_007: the existing-PR short-circuit must run the
     // handoff-comment upsert (idempotent) so crash-recovery replays

package/.agents/scripts/lib/orchestration/lifecycle/listeners/index.js

@@ -229,13 +229,18 @@ export async function buildDefaultListenerChain(opts = {}) {
   // 5. AutomergePredicate — emits epic.merge.{ready,blocked} based on
   //    the runtime predicate evaluation. Requires a truthy `provider`;
   //    skip cleanly when the caller omitted one (lifecycle-emit CLI
-  //    has no provider wired in by default).
+  //    has no provider wired in by default). `config` selects the
+  //    `delivery.ci.autoMerge` posture (trust-ci default vs strict) and
+  //    `cwd` (repoRoot) is where the live `gh pr checks --required`
+  //    probe shells out (Story #4361).
   let automergePredicate = null;
   if (provider) {
     automergePredicate = new AutomergePredicate({
       bus,
       epicId,
       provider,
+      config,
+      cwd: repoRoot,
       logger,
     });
     automergePredicate.register();

package/.agents/scripts/lib/orchestration/lifecycle/listeners/watcher.js

@@ -55,6 +55,35 @@ import { parsePrNumberFromUrl } from '../../../github-url.js';
  * Unknown / non-pending unrecognized values collapse to `'skipped'`
  * so any future GitHub state we haven't enumerated still validates.
  */
+/**
+ * The raw check-state tokens `normalizeCheckState` recognizes (lowercased).
+ * A token absent from this set is one we have NOT enumerated — the watch
+ * path collapses it to `'skipped'` (validate-anything), but a fail-closed
+ * consumer (the auto-merge arming probe) must treat it as unknown-therefore-
+ * blocking rather than trust the `'skipped'` collapse. Exported so that
+ * stricter consumer lives here as the single vocabulary owner.
+ */
+export const RECOGNIZED_CHECK_STATES = Object.freeze(
+  new Set([
+    '',
+    'pending',
+    'queued',
+    'in_progress',
+    'requested',
+    'waiting',
+    'success',
+    'completed',
+    'failure',
+    'startup_failure',
+    'neutral',
+    'cancelled',
+    'timed_out',
+    'action_required',
+    'stale',
+    'skipped',
+  ]),
+);
+
 export function normalizeCheckState(raw) {
   const v = String(raw ?? '')
     .trim()
@@ -266,19 +295,45 @@ export function allTerminal(outcomes) {
 }
 
 /**
- * Promote any `'pending'` outcomes to the schema-valid `'timed_out'`
- * sentinel before emit. Pure — exported for tests so the cap-fire
- * behaviour is reviewable. Called only when the poll loop exits via
- * the iteration cap.
+ * Sentinel outcome for a required check that never went terminal within
+ * the poll cap AND the resume budget — the CI job is genuinely slow, not
+ * red. Story #4358 made this a first-class outcome distinct from
+ * `'timed_out'` (a GitHub-reported terminal timeout) and `'failure'` (a
+ * red check): a `'still-running'` map means "re-arm the watch / hand off
+ * to `/loop`," never "the change is broken."
  */
-function promotePendingToTimedOut(outcomes) {
+export const STILL_RUNNING = 'still-running';
+
+/**
+ * Promote any leftover `'pending'` outcomes to the schema-valid
+ * `'still-running'` sentinel before emit. Pure — exported for tests so
+ * the cap-fire behaviour is reviewable. Called only when the poll loop
+ * (and its resume budget) exits with checks still pending and none
+ * failed — the slow-but-not-red terminal state.
+ */
+export function promotePendingToStillRunning(outcomes) {
   const out = {};
   for (const [k, v] of Object.entries(outcomes)) {
-    out[k] = v === 'pending' ? 'timed_out' : v;
+    out[k] = v === 'pending' ? STILL_RUNNING : v;
   }
   return out;
 }
 
+/**
+ * True when at least one required check has genuinely failed — the hard
+ * stop that consumes NO resume budget and exits 1 immediately. A
+ * `'pending'` check is not a failure (it is still running); anything
+ * outside the non-failing set AND outside `'pending'` is a red block.
+ * Pure — exported for tests.
+ */
+export function hasFailingCheck(outcomes) {
+  for (const v of Object.values(outcomes)) {
+    if (v === 'pending') continue;
+    if (!GREEN_CHECK_OUTCOMES.has(v)) return true;
+  }
+  return false;
+}
+
 /**
  * Default sleeper. Hoisted so tests can stub without faking timers.
  */
@@ -355,8 +410,13 @@ export async function pollUntilTerminal({
  * @param {object} opts
  * @param {string} opts.prUrl              PR URL or number (passed to `gh` verbatim).
  * @param {string} opts.cwd
- * @param {number} opts.maxPolls           Hard cap on total poll iterations.
+ * @param {number} opts.maxPolls           Hard cap on total poll iterations per arm.
  * @param {number} opts.maxUpdates         Cap on `gh pr update-branch` recovery calls.
+ * @param {number} [opts.maxResumes]       Story #4358: after the poll cap fires with
+ *   one or more required checks still pending (and NONE failed), re-arm the poll
+ *   loop up to this many times before giving up with a `still-running` verdict.
+ *   A genuinely red check short-circuits immediately and consumes no resume
+ *   budget. Defaults to 0 (no resume) so existing callers are unchanged.
  * @param {number} opts.pollIntervalMs     Delay between poll ticks.
  * @param {Function} [opts.ghPrChecksFn]   `gh pr checks` invoker. Defaults
  *   to the real `gh pr checks` spawn so the CLI path (which injects no
@@ -379,19 +439,24 @@ export async function pollUntilTerminal({
  *   requiredChecks: string[],
  *   polls: number,
  *   updatesApplied: number,
+ *   resumesApplied: number,
  *   terminal: boolean,
  *   green: boolean,
+ *   stillRunning: boolean,
  *   error?: string,
  * }>}
  *   `outcomes` is schema-valid (no `'pending'` — leftover pending is
- *   promoted to `'timed_out'` when the cap fires). `error` is set only
- *   when the first probe could not resolve the required-check set.
+ *   promoted to `'still-running'` when the cap and resume budget are both
+ *   exhausted with no failed check). `stillRunning` is true in exactly
+ *   that case (slow CI, not red). `error` is set only when the first
+ *   probe could not resolve the required-check set.
  */
 export async function watchPrToTerminal({
   prUrl,
   cwd,
   maxPolls,
   maxUpdates,
+  maxResumes = 0,
   pollIntervalMs,
   ghPrChecksFn = ghPrChecks,
   ghPrViewFn = ghPrView,
@@ -417,8 +482,10 @@ export async function watchPrToTerminal({
       requiredChecks: [],
       polls: 0,
       updatesApplied: 0,
+      resumesApplied: 0,
       terminal: false,
       green: false,
+      stillRunning: false,
       error: `gh-checks-failed:status=${first.status}`,
     };
   }
@@ -433,68 +500,95 @@ export async function watchPrToTerminal({
   let outcomes = reduceOutcomes(firstEntries);
   let polls = 0;
   let updatesApplied = 0;
-  while (polls < maxPolls) {
-    ({ outcomes, polls } = await pollUntilTerminal({
-      prUrl,
-      cwd,
-      outcomes,
-      polls,
-      maxPolls,
-      ghPrChecksFn,
-      pollIntervalMs,
-      sleepFn,
-      logger,
-    }));
-    // Checks have either all gone terminal or we hit the iteration cap.
-    // BEHIND-recovery (Story #2327): when every required check is green
-    // AND the PR is BEHIND its base, issue ONE `gh pr update-branch`
-    // call and re-poll the checks against the freshly-rebased commit. A
-    // red check is a hard block — stop here regardless of merge state.
-    // Bounded by `maxUpdates` so a racing base branch can't ping-pong
-    // indefinitely.
-    if (!allTerminal(outcomes) || !allGreen(outcomes)) break;
-    if (updatesApplied >= maxUpdates) break;
-    const view = ghPrViewFn({ prUrl, cwd });
-    if (view.status !== 0) {
-      logger.warn?.(
-        `[Watcher] gh pr view failed (status=${view.status}): ${view.stderr}`,
-      );
-      break;
-    }
-    const mergeStateStatus = parseMergeStateStatus(view.stdout);
-    if (mergeStateStatus !== 'BEHIND') break;
-    const update = ghPrUpdateBranchFn({ prUrl, cwd });
-    if (update.status !== 0) {
-      logger.warn?.(
-        `[Watcher] gh pr update-branch failed (status=${update.status}): ${update.stderr}`,
+  let resumesApplied = 0;
+  // Outer resume loop (Story #4358). Each iteration runs one full
+  // poll-to-cap + BEHIND-recovery arm. When the arm ends with checks
+  // still pending but NONE failed, we re-arm (reset the poll counter)
+  // up to `maxResumes` times before declaring `still-running`. A red
+  // check breaks out immediately without consuming resume budget.
+  for (;;) {
+    while (polls < maxPolls) {
+      ({ outcomes, polls } = await pollUntilTerminal({
+        prUrl,
+        cwd,
+        outcomes,
+        polls,
+        maxPolls,
+        ghPrChecksFn,
+        pollIntervalMs,
+        sleepFn,
+        logger,
+      }));
+      // Checks have either all gone terminal or we hit the iteration cap.
+      // BEHIND-recovery (Story #2327): when every required check is green
+      // AND the PR is BEHIND its base, issue ONE `gh pr update-branch`
+      // call and re-poll the checks against the freshly-rebased commit. A
+      // red check is a hard block — stop here regardless of merge state.
+      // Bounded by `maxUpdates` so a racing base branch can't ping-pong
+      // indefinitely.
+      if (!allTerminal(outcomes) || !allGreen(outcomes)) break;
+      if (updatesApplied >= maxUpdates) break;
+      const view = ghPrViewFn({ prUrl, cwd });
+      if (view.status !== 0) {
+        logger.warn?.(
+          `[Watcher] gh pr view failed (status=${view.status}): ${view.stderr}`,
+        );
+        break;
+      }
+      const mergeStateStatus = parseMergeStateStatus(view.stdout);
+      if (mergeStateStatus !== 'BEHIND') break;
+      const update = ghPrUpdateBranchFn({ prUrl, cwd });
+      if (update.status !== 0) {
+        logger.warn?.(
+          `[Watcher] gh pr update-branch failed (status=${update.status}): ${update.stderr}`,
+        );
+        break;
+      }
+      updatesApplied += 1;
+      logger.info?.(
+        `[Watcher] PR BEHIND base — issued gh pr update-branch (#${updatesApplied}/${maxUpdates}); re-polling required checks.`,
       );
-      break;
+      await sleepFn(pollIntervalMs);
+      // After update-branch, the freshly-rebased commit invalidates the
+      // previous terminal outcomes. Reset to force the inner poll loop to
+      // re-evaluate the new CI cycle.
+      outcomes = {};
+      for (const name of requiredChecks) outcomes[name] = 'pending';
     }
-    updatesApplied += 1;
+
+    // Arm complete. Decide whether to re-arm. A genuinely red check is a
+    // hard stop that consumes NO resume budget — the change is broken,
+    // resuming would only burn wall-clock. Only re-arm when the arm timed
+    // out with pending-but-not-failed checks and resume budget remains.
+    if (allTerminal(outcomes) || hasFailingCheck(outcomes)) break;
+    if (resumesApplied >= maxResumes) break;
+    resumesApplied += 1;
+    polls = 0;
     logger.info?.(
-      `[Watcher] PR BEHIND base — issued gh pr update-branch (#${updatesApplied}/${maxUpdates}); re-polling required checks.`,
+      `[Watcher] poll cap reached with checks still pending; re-arming watch (resume #${resumesApplied}/${maxResumes}).`,
     );
-    await sleepFn(pollIntervalMs);
-    // After update-branch, the freshly-rebased commit invalidates the
-    // previous terminal outcomes. Reset to force the inner poll loop to
-    // re-evaluate the new CI cycle.
-    outcomes = {};
-    for (const name of requiredChecks) outcomes[name] = 'pending';
   }
 
   const terminal = allTerminal(outcomes);
-  // The schema enum forbids `'pending'`; promote any leftover pending
-  // entries (cap-fire path) to `'timed_out'` for the returned map.
+  const failing = hasFailingCheck(outcomes);
+  // Slow-but-not-red: the poll cap AND resume budget are exhausted with
+  // one or more checks still pending and NONE failed. The schema enum
+  // forbids `'pending'`; promote leftover pending entries to the
+  // `'still-running'` sentinel (never `'timed_out'` — that would read as
+  // a genuine terminal failure to the auto-merge predicate).
+  const stillRunning = !terminal && !failing;
   const finalOutcomes = terminal
     ? outcomes
-    : promotePendingToTimedOut(outcomes);
+    : promotePendingToStillRunning(outcomes);
   return {
     outcomes: finalOutcomes,
     requiredChecks,
     polls,
     updatesApplied,
+    resumesApplied,
     terminal,
     green: terminal && allGreen(finalOutcomes),
+    stillRunning,
   };
 }
 
@@ -513,6 +607,9 @@ export class Watcher {
    *   recovery calls per `pr.created` event; default 3. Mirrors the
    *   legacy `pr-watch-with-update` cap so a racing base branch
    *   can't induce an infinite update-branch ping-pong.
+   * @param {number} [opts.maxResumes] Story #4358: how many times to
+   *   re-arm the poll loop after the cap fires with checks still pending
+   *   (and none failed) before declaring `still-running`; default 0.
    * @param {Function} [opts.ghPrChecksFn] override for tests.
    * @param {Function} [opts.ghPrViewFn] override for tests; resolves
    *   `mergeStateStatus` for the BEHIND-recovery gate.
@@ -539,6 +636,10 @@ export class Watcher {
       Number.isInteger(opts.maxUpdates) && opts.maxUpdates >= 0
         ? opts.maxUpdates
         : 3;
+    this.maxResumes =
+      Number.isInteger(opts.maxResumes) && opts.maxResumes >= 0
+        ? opts.maxResumes
+        : 0;
     this.ghPrChecksFn = opts.ghPrChecksFn ?? ghPrChecks;
     this.ghPrViewFn = opts.ghPrViewFn ?? ghPrView;
     this.ghPrUpdateBranchFn = opts.ghPrUpdateBranchFn ?? ghPrUpdateBranch;
@@ -549,8 +650,8 @@ export class Watcher {
     /**
      * Classification log — every `pr.created` we observe lands here
      * with the outcome (`watched`, `failed`, `skipped-duplicate`,
-     * `timed-out`). Mirrors the Finalizer / Reconciler "no silent skip"
-     * surface.
+     * `still-running`, `timed-out`). Mirrors the Finalizer / Reconciler
+     * "no silent skip" surface.
      */
     this.classifications = [];
     this.events = Object.freeze(['pr.created']);
@@ -631,12 +732,15 @@ export class Watcher {
       outcomes: emitOutcomes,
       polls,
       updatesApplied,
+      resumesApplied,
       terminal,
+      stillRunning,
     } = await watchPrToTerminal({
       prUrl,
       cwd: this.cwd,
       maxPolls: this.maxPolls,
       maxUpdates: this.maxUpdates,
+      maxResumes: this.maxResumes,
       pollIntervalMs: this.pollIntervalMs,
       ghPrChecksFn: this.ghPrChecksFn,
       ghPrViewFn: this.ghPrViewFn,
@@ -646,12 +750,22 @@ export class Watcher {
       firstProbe: first,
     });
 
+    // `still-running` (slow CI, not red) is a distinct classification from
+    // a genuine `timed-out` — reserved for a check that never went
+    // terminal within the poll cap AND the resume budget while none
+    // failed. `watched` covers every terminal arm (green or red).
+    const outcome = terminal
+      ? 'watched'
+      : stillRunning
+        ? 'still-running'
+        : 'timed-out';
     this.classifications.push({
       event,
       seqId,
-      outcome: terminal ? 'watched' : 'timed-out',
+      outcome,
       polls,
       updatesApplied,
+      resumesApplied,
       requiredChecks: requiredChecks.length,
     });
     try {

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

@@ -139,6 +139,7 @@ function makeDefaultGhAutoMergeRunner(gh) {
  *   prNumber: number|null,
  *   prUrl: string,
  *   noAutoMerge: boolean,
+ *   autoMergePolicy?: 'trust-ci'|'strict',
  *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
  *   progress: (tag: string, msg: string) => void,
  * }} args
@@ -149,6 +150,7 @@ export async function runAutoMergePhase({
   prNumber,
   prUrl,
   noAutoMerge,
+  autoMergePolicy = 'trust-ci',
   gh,
   progress,
 }) {
@@ -156,6 +158,23 @@ export async function runAutoMergePhase({
     progress('PR', '⏭  Auto-merge disabled (--no-auto-merge).');
     return { autoMergeEnabled: false, autoMergeReason: 'disabled-by-flag' };
   }
+  // `delivery.ci.autoMerge: "strict"` opts standalone Stories out of
+  // auto-merge (parallel to the Epic path's strict predicate): the PR opens
+  // and waits for an operator merge instead of arming native auto-merge.
+  // The default `"trust-ci"` keeps arming on green required CI — GitHub's
+  // native `--auto` is the required-check gate, so no client-side predicate
+  // is needed here (unlike the Epic path, which gates on local
+  // audit/review/retro signals a standalone Story does not produce).
+  if (autoMergePolicy === 'strict') {
+    progress(
+      'PR',
+      '⏭  Auto-merge skipped (delivery.ci.autoMerge="strict") — operator merges.',
+    );
+    return {
+      autoMergeEnabled: false,
+      autoMergeReason: 'disabled-by-policy-strict',
+    };
+  }
   if (prNumber == null) {
     progress(
       'PR',

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

@@ -2,6 +2,7 @@ import nodeFs from 'node:fs';
 import path from 'node:path';
 import { buildDefaultGates } from '../../close-validation/gates.js';
 import { runCloseValidation } from '../../close-validation/runner.js';
+import { getCiDelivery } from '../../config/ci.js';
 import { resolveConfig } from '../../config-resolver.js';
 import { getStoryBranch, gitSync } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
@@ -316,6 +317,7 @@ export async function runSingleStoryClose({
     prNumber,
     prUrl,
     noAutoMerge: options.noAutoMerge,
+    autoMergePolicy: getCiDelivery(config).autoMerge,
     gh: injectedGh,
     progress,
   });

package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js

@@ -17,10 +17,12 @@
  * `.agents/scripts/lib/config-settings-schema.js`.
  *
  * Sizing model (Story #3760 — profile-matrix collapse; Story #3874 — one
- * uniform relaxed profile):
- *   - Flat knobs: `softFiles` (~15), `hardFiles` (~30), `maxAcceptance` (~14),
+ * uniform relaxed profile; the hard acceptance ceiling was removed after the
+ * Epic #4355 decomposition experiment showed it forced fragmentation):
+ *   - Flat knobs: `softFiles` (~15), `hardFiles` (~30),
  *     `softAcceptanceCount` (~10). No per-profile ceiling map, no parallel
- *     `testSurface` axis, no selector and no second profile.
+ *     `testSurface` axis, no selector and no second profile. Acceptance
+ *     mass is advisory-only.
  *   - The four-profile `sizingProfile` enum is replaced by a single optional
  *     `wide` declaration carrying a one-line human-readable reason. Declaring
  *     `wide` with a reason lifts the `hardFiles` rejection; no Story is
@@ -119,9 +121,12 @@ export const DEFAULT_TASK_SIZING = Object.freeze({
   // The hard `hardFiles` rejection (30) is unchanged.
   softFiles: 15,
   softAcceptanceCount: 10,
-  // Hard ceilings (rejection unless lifted).
+  // Hard ceiling (rejection unless lifted via `wide`). Acceptance mass has
+  // no hard ceiling: the former `maxAcceptance` rejection forced careful,
+  // fine-grained specs to fragment one coherent capability into dependent
+  // slices (observed on Epic #4355), so it was removed — the delivery-
+  // schedule simulation in the decomposer prompt owns that judgment now.
   hardFiles: 30,
-  maxAcceptance: 14,
   // Under-size (merge-candidate) thresholds (Story #4312). A Story with a
   // footprint at or below BOTH ceilings that also carries at least one
   // `depends_on` edge to a sibling looks like a dependent fragment rather than
@@ -528,17 +533,13 @@ function computeStorySizingFindings(story, sizing) {
     ),
   );
 
-  // Acceptance ceiling + soft warn.
-  if (acceptance.length > sizing.maxAcceptance) {
-    out.push(
-      makeOversized(
-        story.slug,
-        'acceptance',
-        acceptance.length,
-        sizing.maxAcceptance,
-      ),
-    );
-  } else if (acceptance.length > sizing.softAcceptanceCount) {
+  // Acceptance mass is advisory-only (Story #4312's under-size heuristic is
+  // the merge signal; the former hard `maxAcceptance` rejection is removed).
+  // A long binding contract is a re-check-cohesion nudge, never by itself a
+  // decomposition error — cohesion and the delivery envelope govern Story
+  // size, and the delivery-schedule simulation in the decomposer prompt owns
+  // the fragmentation/consolidation judgment.
+  if (acceptance.length > sizing.softAcceptanceCount) {
     out.push(
       makeSoftWidth(
         story.slug,

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -50,8 +50,7 @@ export function renderDecomposerSystemPrompt({
 function render2TierPrompt({ maxTickets, maxTokenBudget, epicId = null }) {
   // Sizing thresholds are sourced from the single DEFAULT_TASK_SIZING constant
   // (ticket-validator-sizing.js) so the prompt and the validator cannot drift.
-  const { softFiles, hardFiles, maxAcceptance, softAcceptanceCount } =
-    DEFAULT_TASK_SIZING;
+  const { softFiles, hardFiles, softAcceptanceCount } = DEFAULT_TASK_SIZING;
   // Deliverable-granularity definition + single-consumer merge rule + the
   // soft envelope-floor heuristic are sourced from the single
   // DELIVERABLE_GRANULARITY_GUIDANCE constant (ticket-validator-sizing.js) so
@@ -177,7 +176,22 @@ ${envelopeFloor}
 
 - A Story touching more than **${softFiles} files** (\`softFiles\`) emits an advisory width finding — a nudge to check cohesion or declare \`wide\`.
 - A Story touching more than **${hardFiles} files** (\`hardFiles\`) is **rejected** unless it declares \`wide\` with a reason.
-- A Story with more than **${maxAcceptance} acceptance items** (\`maxAcceptance\`) is **rejected**; more than ${softAcceptanceCount} (\`softAcceptanceCount\`) emits an advisory warning.
+- Acceptance mass is **advisory only**: more than **${softAcceptanceCount} acceptance items** (\`softAcceptanceCount\`) emits an advisory warning. There is NO hard acceptance ceiling — a long binding contract is a signal to re-check cohesion, never a reason to fragment one coherent capability into dependent slices.
+
+#### DELIVERY-SCHEDULE SIMULATION — the story count must earn itself:
+
+Before emitting, simulate the delivery schedule your plan implies, and judge the plan by its schedule — not by how tidy the taxonomy looks:
+
+1. **Build the wave schedule.** A Story runs only after every \`depends_on\` completes, and two Stories that name the same file in \`changes[]\` cannot run in the same wave (the scheduler serializes file-overlapping Stories even when no \`depends_on\` edge links them).
+2. **Compute the parallelism yield**: story count ÷ critical-path length in waves. A yield near 1.0 means the plan is a serial chain — N Stories that deliver no faster than one Story while paying N delivery sessions (hydration, branch, PR, review, CI).
+3. **Every Story must earn its slot** by at least one of:
+   - **(a) parallelism** — it actually runs concurrently with a sibling in the schedule you just built ("logically independent" does not count; *schedule*-independent does);
+   - **(b) risk isolation** — it isolates a consumer-facing behavior change or high-risk cutover into its own reviewable, revertable unit;
+   - **(c) envelope pressure** — merged into its neighbor it would exceed the one-pass delivery envelope (\`maxTokenBudget\`).
+4. **A dependent link with none of those justifications merges into its consumer.** This generalizes the single-consumer merge rule from pairs to chains.
+5. **Hot-file rule.** When one file appears in the \`changes[]\` of more than a third of your Stories, the slicing axis cuts across a shared seam — merge the Stories that co-edit it, or re-slice along the seam so each Story owns its files.
+
+End each Story's \`reason_to_exist\` with its justification letter and one clause, e.g. "… (a: runs in wave 1 alongside <slug>)" or "(b: isolates the auto-merge default change)". A reason that names only a topic ("config work", "docs") with no justification is a merge signal.
 
 #### \`wide\` DECLARATION (optional — for legitimately broad changes):