mandrel 1.84.0 → 1.86.0

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution/phases/regression-projection.js

@@ -244,6 +244,24 @@ export const PROJECTORS = {
   'check-crap': projectCrapForGate,
 };
 
+/**
+ * Composite gates fan out to per-kind projectors. The baseline pipeline was
+ * unified behind a single `check-baselines` gate (per-kind pipeline: schema →
+ * floor → tolerance), but the attribution layer still keys on the original
+ * per-kind gate names. Without this map a `check-baselines` failure projects
+ * zero regressions, the gate-failure handler sees an empty list, and the
+ * auto-refresh path silently no-ops — so a legitimate MI/CRAP regression
+ * hard-fails the close instead of self-healing (framework-gap #4377).
+ */
+export const COMPOSITE_SUBGATES = {
+  'check-baselines': ['check-maintainability', 'check-crap'],
+};
+
+/** `check-maintainability` → `maintainability`. */
+function gateKind(gateName) {
+  return gateName.replace(/^check-/, '');
+}
+
 export function projectRegressionsForGate({
   gateName,
   cwd,
@@ -253,14 +271,27 @@ export function projectRegressionsForGate({
   projectMaintainability = defaultProjectMaintainabilityRegressions,
   getBaselines = defaultGetBaselines,
 }) {
-  const project = PROJECTORS[gateName];
-  if (!project) return [];
-  return project({
+  const ctx = {
     cwd,
     epicBranch,
     storyBranch,
     config,
     projectMaintainability,
     getBaselines,
-  });
+  };
+  const subGates = COMPOSITE_SUBGATES[gateName];
+  if (subGates) {
+    // Union the per-kind regressions, tagging each row with its baseline
+    // kind so the gate-failure handler can refresh the right baseline (one
+    // kind per attribution cycle; the retry loop converges the rest).
+    return subGates.flatMap((sub) => {
+      const project = PROJECTORS[sub];
+      if (!project) return [];
+      const kind = gateKind(sub);
+      return project(ctx).map((row) => ({ _gateKind: kind, ...row }));
+    });
+  }
+  const project = PROJECTORS[gateName];
+  if (!project) return [];
+  return project(ctx);
 }

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/single-story-sweep/protection-ctx.js

@@ -0,0 +1,75 @@
+/**
+ * single-story-sweep/protection-ctx.js
+ *
+ * Shared builder for the `evaluateProtection` context the boot-sweep
+ * engine ([`sweepMergedBranches`](../single-story-sweep.js)) threads into
+ * every candidate protection check. Single-homed here so the three boot
+ * callers — `single-story-init.js`, `epic-deliver-prepare.js`, and the
+ * `boot-sweep.js` CLI — build an identical ctx instead of each re-wiring
+ * the git/gh/ticket ports.
+ *
+ * Story #2990: the sweep protection-ctx `ghRunner` stays on raw
+ * `spawnSync('gh', …)` (not the `lib/gh-exec.js` async facade) because
+ * `executeCleanup` invokes the protection checks inside a synchronous
+ * candidate-filter loop. The runner contract is the legacy
+ * `(args, opts) => stdout string` shape.
+ */
+
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+import { gitSpawn } from '../git-utils.js';
+
+/**
+ * Build the synchronous `gh` runner the sweep uses for its
+ * candidate-protection checks.
+ *
+ * Story #4073: the `spawnImpl` seam injects the `spawnSync` boundary so
+ * the runner's success/error handling can be unit-tested without a live
+ * `gh` binary. It defaults to `child_process.spawnSync`, so the
+ * production CLI path is unchanged.
+ *
+ * @param {string} cwd Repo root used as the default spawn cwd.
+ * @param {typeof defaultSpawnSync} [spawnImpl] Injectable spawn boundary —
+ *   defaults to `child_process.spawnSync`.
+ * @returns {(args: string[], opts?: { cwd?: string }) => string}
+ */
+export function makeGhRunner(cwd, spawnImpl = defaultSpawnSync) {
+  return (args, opts) => {
+    const result = spawnImpl('gh', args, {
+      cwd: opts?.cwd ?? cwd,
+      encoding: 'utf-8',
+      shell: false,
+    });
+    if (result.status !== 0) {
+      throw new Error(
+        `gh ${args.join(' ')} exit ${result.status}: ${result.stderr ?? ''}`,
+      );
+    }
+    return result.stdout ?? '';
+  };
+}
+
+/**
+ * Build the `evaluateProtection` ctx bag: the repo root, the `gitSpawn`
+ * port, the synchronous `gh` runner, and a `getTicket` port bound to the
+ * supplied provider.
+ *
+ * @param {{
+ *   cwd: string,
+ *   provider: { getTicket: (id: number) => Promise<object> },
+ *   spawnImpl?: typeof defaultSpawnSync,
+ * }} args
+ * @returns {{
+ *   repoRoot: string,
+ *   gitSpawn: typeof gitSpawn,
+ *   ghRunner: (args: string[], opts?: { cwd?: string }) => string,
+ *   getTicket: (id: number) => Promise<object>,
+ * }}
+ */
+export function buildProtectionCtx({ cwd, provider, spawnImpl }) {
+  return {
+    repoRoot: cwd,
+    gitSpawn,
+    ghRunner: makeGhRunner(cwd, spawnImpl),
+    getTicket: (id) => provider.getTicket(id),
+  };
+}

package/.agents/scripts/lib/single-story-sweep.js

@@ -1,27 +1,41 @@
 /**
- * single-story-sweep.js — Sweep merged `story-*` branches at init.
+ * single-story-sweep.js — the scope-agnostic merged-branch sweep engine
+ * plus the `story-*` boot-sweep preset.
  *
- * Wraps `git-cleanup-branches.js` with a fixed policy tuned for the
- * `/single-story-deliver` boot path:
+ * `sweepMergedBranches` is the single reap engine every boot cleanup
+ * path routes through. It sits directly over the `git-cleanup` phase
+ * library (`planCleanup` / `executeCleanup` / `executeFastForward` /
+ * `buildGlobFilter`) and the shared `evaluateProtection` guard set, so
+ * no reap path re-implements the `git branch -D` / `git merge --ff-only`
+ * primitives:
  *
- *   - Scope: `story-*` only (never touches `epic/*`, `story/<id>/*`, etc.).
- *   - Mode:  --execute --remote (delete local + origin + prune trackers).
- *   - Skip:  the current run's `storyBranch` is always excluded, even if a
- *            stale PR for the same id were already merged.
+ *   - Scope: caller-supplied `include` / `exclude` globs (via
+ *            `buildGlobFilter`). The story preset pins `story-*`.
+ *   - Reap:  merged local branches whose PR HEAD SHA equals the merged
+ *            `headRefOid`, deleted local + origin with tracking-ref
+ *            prune (`executeCleanup` in `--remote` mode).
  *   - Protection (Story #2011): each candidate is filtered through
  *            `evaluateProtection` before reaching `executeCleanup`. A
  *            candidate is protected (not reaped) when its branch HEAD
  *            differs from the PR's `headRefOid` (unpushed work), when
  *            its worktree has uncommitted edits, or when the parent
  *            Story ticket is not in a terminal state. Protected
- *            candidates surface in the result envelope under
- *            `protected` so the operator can see what was skipped.
+ *            candidates surface under `protected`.
+ *   - Fast-forward (opt-in via `fastForward: true`): fast-forward the
+ *            base branch through `executeFastForward` after the reap.
+ *            Best-effort — a failed fast-forward never fails the sweep.
  *   - Concurrency (Story #2011): the sweep acquires a process-scoped
  *            lockfile around plan + execute. On lock contention the
- *            sweep is skipped (init continues — same contract as a
+ *            sweep is skipped (the host continues — same contract as a
  *            plan failure).
- *   - Errors are caught and surfaced in the envelope. The caller MUST NOT
- *            propagate sweep failures — story init proceeds either way.
+ *   - Never touches the stash stack.
+ *   - Errors are caught and surfaced in the envelope. Callers MUST NOT
+ *            propagate sweep failures — the host proceeds either way.
+ *
+ * `sweepMergedStoryBranches` is a thin preset over the engine tuned for
+ * the boot path (`include: story-*`, `exclude: <current story branch>`,
+ * `fastForward: false`). Its exported name, signature, and result
+ * envelope are unchanged from the pre-engine implementation.
  *
  * Re-exports the same `planCleanup` / `executeCleanup` injection seams so
  * tests can stub git/`gh` without touching the CLI.
@@ -30,7 +44,9 @@
 import {
   buildGlobFilter,
   executeCleanup as defaultExecuteCleanup,
+  executeFastForward as defaultExecuteFastForward,
   planCleanup as defaultPlanCleanup,
+  planFastForward as defaultPlanFastForward,
 } from '../git-cleanup.js';
 import { evaluateProtection as defaultEvaluateProtection } from './single-story-sweep/protection.js';
 import { acquireSweepLock as defaultAcquireSweepLock } from './single-story-sweep/sweep-lock.js';
@@ -38,15 +54,20 @@ import { acquireSweepLock as defaultAcquireSweepLock } from './single-story-swee
 const STORY_BRANCH_INCLUDE = 'story-*';
 
 /**
- * Sweep merged `story-*` branches in `cwd`.
+ * Scope-agnostic merged-branch sweep engine.
  *
  * @param {{
  *   cwd: string,
  *   baseBranch: string,
- *   currentStoryBranch: string,
+ *   include?: string[],
+ *   exclude?: string[],
+ *   fastForward?: boolean,
  *   logger?: { info?: (m: string) => void, warn?: (m: string) => void },
+ *   logTag?: string,
  *   planCleanupFn?: typeof defaultPlanCleanup,
  *   executeCleanupFn?: typeof defaultExecuteCleanup,
+ *   planFastForwardFn?: typeof defaultPlanFastForward,
+ *   executeFastForwardFn?: typeof defaultExecuteFastForward,
  *   protectionFn?: typeof defaultEvaluateProtection,
  *   protectionCtx?: object,
  *   acquireLockFn?: typeof defaultAcquireSweepLock,
@@ -61,17 +82,23 @@ const STORY_BRANCH_INCLUDE = 'story-*';
  *   remoteDeleted: number,
  *   protected: Array<{ branch: string, reason: string, worktreePath?: string|null }>,
  *   failures: Array<{ branch: string|null, scope: string, stderr?: string }>,
+ *   fastForward?: object,
  *   error?: string,
  *   reason?: string,
  * }>}
  */
-export async function sweepMergedStoryBranches({
+export async function sweepMergedBranches({
   cwd,
   baseBranch,
-  currentStoryBranch,
+  include = ['*'],
+  exclude = [],
+  fastForward = false,
   logger = {},
+  logTag = '[sweep]',
   planCleanupFn = defaultPlanCleanup,
   executeCleanupFn = defaultExecuteCleanup,
+  planFastForwardFn = defaultPlanFastForward,
+  executeFastForwardFn = defaultExecuteFastForward,
   protectionFn = defaultEvaluateProtection,
   protectionCtx = null,
   acquireLockFn = defaultAcquireSweepLock,
@@ -92,16 +119,13 @@ export async function sweepMergedStoryBranches({
 
   // Optional lock acquisition. Skip silently when no lockPath is
   // supplied (e.g. unit tests, callers that opt out). Contention is
-  // non-fatal — return a skipped result and let init continue.
+  // non-fatal — return a skipped result and let the host continue.
   let releaseLock = () => {};
   if (lockPath) {
-    const lockResult = acquireLockFn({
-      lockPath,
-      timeoutMs: lockTimeoutMs,
-    });
+    const lockResult = acquireLockFn({ lockPath, timeoutMs: lockTimeoutMs });
     if (!lockResult.acquired) {
       log.warn(
-        `[single-story-sweep] lock not acquired (${lockResult.reason}${
+        `${logTag} lock not acquired (${lockResult.reason}${
           lockResult.detail ? `: ${lockResult.detail}` : ''
         }); skipping sweep.`,
       );
@@ -120,16 +144,28 @@ export async function sweepMergedStoryBranches({
   }
 
   try {
-    return await runSweepUnderLock({
+    const reap = await runSweepUnderLock({
       cwd,
       baseBranch,
-      currentStoryBranch,
+      include,
+      exclude,
       log,
+      logTag,
       planCleanupFn,
       executeCleanupFn,
       protectionFn,
       protectionCtx,
     });
+    if (!fastForward) return reap;
+    const ff = runFastForwardStep({
+      cwd,
+      baseBranch,
+      log,
+      logTag,
+      planFastForwardFn,
+      executeFastForwardFn,
+    });
+    return { ...reap, fastForward: ff };
   } finally {
     try {
       releaseLock();
@@ -139,41 +175,73 @@ export async function sweepMergedStoryBranches({
   }
 }
 
+/**
+ * Sweep merged `story-*` branches in `cwd`. Preset over
+ * {@link sweepMergedBranches} for the boot path: it pins the `story-*`
+ * include glob, excludes the current run's `currentStoryBranch`, and
+ * keeps `fastForward` off (the boot caller fast-forwards the base branch
+ * separately). Exported name, signature, and result-envelope shape are
+ * unchanged from the pre-engine implementation.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch: string,
+ *   currentStoryBranch: string,
+ *   logger?: { info?: (m: string) => void, warn?: (m: string) => void },
+ *   planCleanupFn?: typeof defaultPlanCleanup,
+ *   executeCleanupFn?: typeof defaultExecuteCleanup,
+ *   protectionFn?: typeof defaultEvaluateProtection,
+ *   protectionCtx?: object,
+ *   acquireLockFn?: typeof defaultAcquireSweepLock,
+ *   lockPath?: string|null,
+ *   lockTimeoutMs?: number,
+ * }} args
+ * @returns {Promise<object>} the {@link sweepMergedBranches} envelope.
+ */
+export function sweepMergedStoryBranches(args = {}) {
+  const { currentStoryBranch } = args;
+  const exclude =
+    typeof currentStoryBranch === 'string' && currentStoryBranch.length > 0
+      ? [currentStoryBranch]
+      : [];
+  return sweepMergedBranches({
+    ...args,
+    include: [STORY_BRANCH_INCLUDE],
+    exclude,
+    fastForward: false,
+    logTag: '[single-story-sweep]',
+  });
+}
+
 /**
  * Inner: the plan + protect + execute pipeline. Kept separate so the
- * outer `sweepMergedStoryBranches` can stay focused on the lock
- * acquire/release wrapper.
+ * outer engine can stay focused on the lock and fast-forward wrappers.
  */
 async function runSweepUnderLock({
   cwd,
   baseBranch,
-  currentStoryBranch,
+  include,
+  exclude,
   log,
+  logTag,
   planCleanupFn,
   executeCleanupFn,
   protectionFn,
   protectionCtx,
 }) {
-  const exclude =
-    typeof currentStoryBranch === 'string' && currentStoryBranch.length > 0
-      ? [currentStoryBranch]
-      : [];
-  const filter = buildGlobFilter({
-    include: [STORY_BRANCH_INCLUDE],
-    exclude,
-  });
+  const filter = buildGlobFilter({ include, exclude });
 
   let plan;
   try {
     plan = planCleanupFn({ cwd, baseBranch, filter });
   } catch (err) {
     const msg = err?.message ?? String(err);
-    log.warn(`[single-story-sweep] plan failed: ${msg}`);
+    log.warn(`${logTag} plan failed: ${msg}`);
     return zeroResult({ error: `plan: ${msg}` });
   }
 
   if (plan.candidates.length === 0) {
-    log.info('[single-story-sweep] no merged story branches to reap.');
+    log.info(`${logTag} no merged branches to reap.`);
     return {
       ok: true,
       skipped: false,
@@ -190,11 +258,12 @@ async function runSweepUnderLock({
     protectionFn,
     protectionCtx,
     log,
+    logTag,
   });
 
   if (reapable.length === 0) {
     log.info(
-      `[single-story-sweep] all ${plan.candidates.length} candidate(s) protected; no reap.`,
+      `${logTag} all ${plan.candidates.length} candidate(s) protected; no reap.`,
     );
     return {
       ok: true,
@@ -207,20 +276,41 @@ async function runSweepUnderLock({
     };
   }
 
+  return executeReap({
+    reapable,
+    protectedList,
+    candidateCount: plan.candidates.length,
+    cwd,
+    executeCleanupFn,
+    log,
+    logTag,
+  });
+}
+
+/**
+ * Execute the reap plan for the reapable candidates and shape the result
+ * envelope. Split out of {@link runSweepUnderLock} so each function keeps
+ * a single responsibility.
+ */
+function executeReap({
+  reapable,
+  protectedList,
+  candidateCount,
+  cwd,
+  executeCleanupFn,
+  log,
+  logTag,
+}) {
   let result;
   try {
-    result = executeCleanupFn({
-      candidates: reapable,
-      cwd,
-      remote: true,
-    });
+    result = executeCleanupFn({ candidates: reapable, cwd, remote: true });
   } catch (err) {
     const msg = err?.message ?? String(err);
-    log.warn(`[single-story-sweep] execute failed: ${msg}`);
+    log.warn(`${logTag} execute failed: ${msg}`);
     return {
       ok: false,
       skipped: false,
-      candidates: plan.candidates.length,
+      candidates: candidateCount,
       localDeleted: 0,
       remoteDeleted: 0,
       protected: protectedList,
@@ -241,18 +331,18 @@ async function runSweepUnderLock({
   const summary = `${localDeleted} local + ${remoteDeleted} remote${protectedSummary}`;
   if (result.ok) {
     log.info(
-      `[single-story-sweep] reaped ${summary}${reapedBranches ? ` [${reapedBranches}]` : ''}.`,
+      `${logTag} reaped ${summary}${reapedBranches ? ` [${reapedBranches}]` : ''}.`,
     );
   } else {
     log.warn(
-      `[single-story-sweep] reaped ${summary} with ${result.failures.length} failure(s) — init continues.`,
+      `${logTag} reaped ${summary} with ${result.failures.length} failure(s) — host continues.`,
     );
   }
 
   return {
     ok: result.ok,
     skipped: false,
-    candidates: plan.candidates.length,
+    candidates: candidateCount,
     localDeleted,
     remoteDeleted,
     protected: protectedList,
@@ -260,6 +350,44 @@ async function runSweepUnderLock({
   };
 }
 
+/**
+ * Best-effort fast-forward of the base branch through the git-cleanup
+ * fast-forward phase. Never throws — a failed fast-forward is logged and
+ * returned as `{ ok: false, error }` but must never fail the sweep.
+ */
+function runFastForwardStep({
+  cwd,
+  baseBranch,
+  log,
+  logTag,
+  planFastForwardFn,
+  executeFastForwardFn,
+}) {
+  try {
+    const plan = planFastForwardFn({ cwd, baseBranch });
+    const ff = executeFastForwardFn({
+      cwd,
+      baseBranch,
+      plan,
+      logger: {
+        info: (m) => log.info(m.replace(/^\[git-cleanup\]\s*/, `${logTag} `)),
+        warn: (m) => log.warn(m.replace(/^\[git-cleanup\]\s*/, `${logTag} `)),
+      },
+    });
+    return {
+      ok: ff.ok !== false,
+      applied: !!ff.applied,
+      skipped: !!ff.skipped,
+      behind: ff.behind ?? null,
+      reason: ff.reason ?? null,
+    };
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    log.warn(`${logTag} fast-forward failed: ${msg}`);
+    return { ok: false, applied: false, skipped: false, error: msg };
+  }
+}
+
 /**
  * Iterate plan candidates and split them into `reapable` (safe to pass
  * to executeCleanup) and `protectedList` (skipped, with a reason).
@@ -270,14 +398,15 @@ async function runSweepUnderLock({
  *
  * When no `protectionCtx` is supplied (legacy callers, unit tests),
  * the protection check is bypassed entirely and every candidate is
- * reapable. The CLI surface in `single-story-init.js` always supplies
- * a ctx, so this fallback never fires in production.
+ * reapable. The boot-path CLI surfaces always supply a ctx, so this
+ * fallback never fires in production.
  */
 async function partitionCandidates({
   candidates,
   protectionFn,
   protectionCtx,
   log,
+  logTag,
 }) {
   const reapable = [];
   const protectedList = [];
@@ -291,7 +420,7 @@ async function partitionCandidates({
       verdict = await protectionFn({ candidate, ctx: protectionCtx });
     } catch (err) {
       const reason = `protection-eval-error: ${err?.message ?? err}`;
-      log.warn(`[single-story-sweep] protected ${candidate.branch}: ${reason}`);
+      log.warn(`${logTag} protected ${candidate.branch}: ${reason}`);
       protectedList.push({
         branch: candidate.branch,
         reason,
@@ -300,9 +429,7 @@ async function partitionCandidates({
       continue;
     }
     if (verdict?.protected) {
-      log.info(
-        `[single-story-sweep] protected ${candidate.branch}: ${verdict.reason}`,
-      );
+      log.info(`${logTag} protected ${candidate.branch}: ${verdict.reason}`);
       protectedList.push({
         branch: candidate.branch,
         reason: verdict.reason ?? 'unknown',

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):