mandrel 1.84.0 → 1.85.0

package/.agents/scripts/pr-watch-with-update.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 /**
- * pr-watch-with-update.js — Phase 8 "watch until green" CLI.
+ * pr-watch-with-update.js — the single CI-watch mechanism for BOTH the
+ * Epic Phase 8 path (`deliver-epic.md`) and the standalone single-Story
+ * Step 4 path (`single-story-deliver.md`). Story #4358 retired the bare
+ * `gh pr checks --watch` from the single-Story path so both drive this
+ * one CLI.
  *
  * Polls the PR's required checks to a terminal state and auto-recovers
  * from `mergeStateStatus: BEHIND` (via bounded `gh pr update-branch`
@@ -9,24 +13,53 @@
  * and the bus path are byte-for-byte equivalent. No lifecycle bus is
  * created; this is a direct, synchronous watch with a real exit code.
  *
- * Contract (Story #3902):
- *   - Blocks until every required check is terminal (or the poll cap
- *     fires).
- *   - Prints the final `{ checkName: outcome }` map to stdout as JSON.
- *   - Exits 0 only when every required check is green
- *     (success / neutral / skipped); exits non-zero otherwise (red
- *     check, timed-out poll cap, or an unresolvable `gh pr checks`
- *     failure) so the calling workflow can gate on the exit code.
+ * Slow-vs-failed semantics (Story #4358):
+ *   - GREEN — every required check terminal + green → exit 0.
+ *   - RED   — one or more required checks genuinely failed → exit 1
+ *             IMMEDIATELY, consuming no resume budget. On red the CLI
+ *             writes `temp/epic-<id>-ci-digest.{json,md}` (failing check
+ *             name, run id, a `gh run view --log-failed` tail, and a
+ *             coarse classification) and prints the `/loop
+ *             /loops:fix-failing-tests` handoff.
+ *   - STILL-RUNNING — the poll cap fired with checks still pending and
+ *             none failed; the watcher re-armed up to
+ *             `delivery.ci.watch.maxResumes` times, then returned a
+ *             `still-running` verdict → exit 2 (NEVER 1, NEVER
+ *             `timed_out`). The CLI prints the `/loop 5m /loops:watch-ci`
+ *             handoff so the host can keep polling on its own cadence.
+ *
+ * Config (Story #4356 namespace, read via `getCiDelivery`):
+ *   - `delivery.ci.watch.pollIntervalMs`
+ *   - `delivery.ci.watch.maxPolls`
+ *   - `delivery.ci.watch.maxResumes`
+ *   CLI flags override config; config overrides the framework fallback.
  *
  * Usage:
  *   node .agents/scripts/pr-watch-with-update.js --pr <n> [--repo owner/repo]
- *     [--max-updates N] [--poll-interval-ms MS] [--max-polls N]
+ *     [--epic <id>] [--max-updates N] [--poll-interval-ms MS]
+ *     [--max-polls N] [--max-resumes N]
  */
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
+import { getCiDelivery } from './lib/config/ci.js';
+import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { watchPrToTerminal } from './lib/orchestration/lifecycle/listeners/watcher.js';
 
+/** Framework fallbacks when neither a CLI flag nor config supplies a value. */
+export const WATCH_DEFAULTS = Object.freeze({
+  pollIntervalMs: 10_000,
+  maxPolls: 180,
+  maxUpdates: 3,
+  maxResumes: 3,
+});
+
+/** Exit code reserved for the slow-but-not-red `still-running` verdict. */
+export const STILL_RUNNING_EXIT_CODE = 2;
+
 function parsePositiveInt(raw, fallback) {
   if (raw == null) return fallback;
   const n = Number.parseInt(raw, 10);
@@ -34,41 +67,232 @@ function parsePositiveInt(raw, fallback) {
 }
 
 /**
- * Run the watch loop and resolve to the exit code (0 = all green,
- * 1 = not green / failed). Exported for tests so the green / red /
- * BEHIND paths can be exercised with injected `gh` spawns and no
- * `process.exit`.
+ * Resolve the effective poll knobs: CLI flag → `delivery.ci.watch.*` →
+ * framework fallback. Pure (given a config bag) — exported for tests so
+ * the precedence ladder is reviewable. `flags` are the raw string values
+ * from `parseArgs` (or numbers, in tests); a nullish flag falls through
+ * to config, and a nullish config field falls through to the default.
+ *
+ * @param {object} opts
+ * @param {object|null} [opts.config]  resolved config (or a bare bag).
+ * @param {object} [opts.flags]        `{ pollIntervalMs, maxPolls, maxResumes, maxUpdates }`.
+ * @returns {{ pollIntervalMs: number, maxPolls: number, maxResumes: number, maxUpdates: number }}
+ */
+export function resolveWatchKnobs({ config, flags = {} } = {}) {
+  const watch = getCiDelivery(config).watch ?? {};
+  const pick = (flag, cfg, dflt) =>
+    parsePositiveInt(flag, Number.isInteger(cfg) && cfg >= 0 ? cfg : dflt);
+  return {
+    pollIntervalMs: pick(
+      flags.pollIntervalMs,
+      watch.pollIntervalMs,
+      WATCH_DEFAULTS.pollIntervalMs,
+    ),
+    maxPolls: pick(flags.maxPolls, watch.maxPolls, WATCH_DEFAULTS.maxPolls),
+    maxResumes: pick(
+      flags.maxResumes,
+      watch.maxResumes,
+      WATCH_DEFAULTS.maxResumes,
+    ),
+    maxUpdates: pick(flags.maxUpdates, undefined, WATCH_DEFAULTS.maxUpdates),
+  };
+}
+
+/**
+ * Coarse failure classification from a failing-check name. Pure —
+ * exported for tests. Deliberately shallow: it steers the operator's
+ * next move (which `/loop` unit to reach for), not a root-cause verdict.
+ *
+ * @param {string} name  failing required-check name.
+ * @returns {'test'|'lint'|'baseline'|'build'|'unknown'}
+ */
+export function classifyFailure(name) {
+  const n = String(name ?? '').toLowerCase();
+  if (/lint|format|biome|markdownlint/.test(n)) return 'lint';
+  if (/baseline|coverage|crap|maintainab|duplicat/.test(n)) return 'baseline';
+  if (/build|compile|typecheck|bundle/.test(n)) return 'build';
+  if (/test|spec|validate|ci|check/.test(n)) return 'test';
+  return 'unknown';
+}
+
+/**
+ * Default `gh run view --log-failed` spawn — pulls the tail of the failed
+ * job log so the digest carries an actionable excerpt. Best-effort:
+ * returns an empty tail when the run id is unknown or `gh` errors.
+ * Exported indirectly via `writeCiDigest` injection so tests can stub
+ * without shelling out.
+ */
+function ghRunLogTail({ runId, cwd, spawnFn = spawnSync, maxLines = 40 }) {
+  if (!runId) return '';
+  const result = spawnFn('gh', ['run', 'view', String(runId), '--log-failed'], {
+    cwd,
+    encoding: 'utf-8',
+    shell: false,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  const out = (result.stdout ?? '').trim();
+  if (out.length === 0) return '';
+  const lines = out.split('\n');
+  return lines.slice(-maxLines).join('\n');
+}
+
+/**
+ * Resolve the GitHub Actions run id for a failing check. Best-effort via
+ * `gh pr checks --json name,link` — the `link` field carries the run URL
+ * whose trailing path segment is the run id. Returns `null` when
+ * unresolvable.
+ */
+function resolveRunId({ prRef, checkName, cwd, spawnFn = spawnSync }) {
+  const result = spawnFn('gh', ['pr', 'checks', prRef, '--json', 'name,link'], {
+    cwd,
+    encoding: 'utf-8',
+    shell: false,
+  });
+  try {
+    const parsed = JSON.parse((result.stdout ?? '').trim() || '[]');
+    const entry = Array.isArray(parsed)
+      ? parsed.find((e) => e?.name === checkName)
+      : null;
+    const link = entry?.link ?? '';
+    const m = /\/runs\/(\d+)/.exec(String(link));
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the CI failure digest (`.json` + `.md`) for a red watch. Returns
+ * the two paths written (or `null` when no epic id was supplied — the
+ * digest is Epic-scoped by filename). Exported for tests.
+ *
+ * @param {object} opts
+ * @param {number|string|null} opts.epicId
+ * @param {number} opts.prNumber
+ * @param {Array<{name:string, outcome:string}>} opts.failures
+ * @param {string} opts.tempRoot
+ * @param {string} opts.cwd
+ * @param {string} opts.prRef
+ * @param {Function} [opts.runIdFn]
+ * @param {Function} [opts.logTailFn]
+ * @returns {{ jsonPath: string, mdPath: string } | null}
+ */
+export function writeCiDigest({
+  epicId,
+  prNumber,
+  failures,
+  tempRoot,
+  cwd,
+  prRef,
+  runIdFn = resolveRunId,
+  logTailFn = ghRunLogTail,
+}) {
+  if (epicId == null || String(epicId).length === 0) return null;
+  const primary = failures[0] ?? { name: 'unknown', outcome: 'failure' };
+  const runId = runIdFn({ prRef, checkName: primary.name, cwd });
+  const logTail = logTailFn({ runId, cwd });
+  const classification = classifyFailure(primary.name);
+  const digest = {
+    epicId: Number.parseInt(String(epicId), 10),
+    prNumber,
+    failingCheck: primary.name,
+    failingOutcome: primary.outcome,
+    runId,
+    classification,
+    allFailures: failures,
+    logTail,
+    generatedAt: new Date().toISOString(),
+  };
+  const dir = path.isAbsolute(tempRoot) ? tempRoot : path.join(cwd, tempRoot);
+  mkdirSync(dir, { recursive: true });
+  const base = `epic-${digest.epicId}-ci-digest`;
+  const jsonPath = path.join(dir, `${base}.json`);
+  const mdPath = path.join(dir, `${base}.md`);
+  writeFileSync(jsonPath, `${JSON.stringify(digest, null, 2)}\n`);
+  const md = [
+    `# CI failure digest — Epic #${digest.epicId} (PR #${prNumber})`,
+    '',
+    `- **Failing check:** \`${digest.failingCheck}\` (${digest.failingOutcome})`,
+    `- **Run id:** ${runId ?? 'unresolved'}`,
+    `- **Classification:** ${classification}`,
+    `- **Generated:** ${digest.generatedAt}`,
+    '',
+    failures.length > 1
+      ? `Other non-green checks: ${failures
+          .slice(1)
+          .map((f) => `\`${f.name}\`=${f.outcome}`)
+          .join(', ')}`
+      : '',
+    '',
+    '## `gh run view --log-failed` tail',
+    '',
+    '```text',
+    logTail || '(no failed-log output available)',
+    '```',
+    '',
+  ].join('\n');
+  writeFileSync(mdPath, md);
+  return { jsonPath, mdPath };
+}
+
+/**
+ * Run the watch loop and resolve to the exit code. Exported for tests so
+ * the green / red / still-running / BEHIND paths can be exercised with
+ * injected `gh` spawns and no `process.exit`.
+ *
+ *   0 → all required checks green.
+ *   1 → a required check genuinely failed (red).
+ *   2 → still-running (slow CI): cap + resume budget exhausted, none red.
  *
  * @param {object} opts
  * @param {number} opts.prNumber
  * @param {string|null} [opts.repo]
- * @param {number} [opts.maxUpdates]
- * @param {number} [opts.pollIntervalMs]
- * @param {number} [opts.maxPolls]
- * @param {Function} [opts.ghPrChecksFn]   inject for tests
- * @param {Function} [opts.ghPrViewFn]     inject for tests
+ * @param {number|string|null} [opts.epicId]  Epic id for the red-path digest.
+ * @param {number|string} [opts.maxUpdates]
+ * @param {number|string} [opts.pollIntervalMs]
+ * @param {number|string} [opts.maxPolls]
+ * @param {number|string} [opts.maxResumes]
+ * @param {object|null} [opts.config]         resolved config (defaults to resolveConfig()).
+ * @param {string} [opts.tempRoot]            digest output dir (default `temp`).
+ * @param {Function} [opts.ghPrChecksFn]      inject for tests
+ * @param {Function} [opts.ghPrViewFn]        inject for tests
  * @param {Function} [opts.ghPrUpdateBranchFn] inject for tests
- * @param {Function} [opts.sleepFn]        inject for tests
+ * @param {Function} [opts.sleepFn]           inject for tests
+ * @param {Function} [opts.writeDigestFn]     inject for tests (default writeCiDigest)
  * @param {object} [opts.logger]
- * @param {(line: string) => void} [opts.print] stdout sink (default console.log)
+ * @param {(line: string) => void} [opts.print] stdout sink (default process.stdout)
  * @returns {Promise<number>} process exit code.
  */
 export async function runPrWatch({
   prNumber,
   repo = null,
+  epicId = null,
   maxUpdates,
   pollIntervalMs,
   maxPolls,
+  maxResumes,
+  config,
+  tempRoot,
   ghPrChecksFn,
   ghPrViewFn,
   ghPrUpdateBranchFn,
   sleepFn,
+  writeDigestFn = writeCiDigest,
   logger = Logger,
   print = (line) => process.stdout.write(`${line}\n`),
 } = {}) {
   if (!Number.isInteger(prNumber) || prNumber < 1)
     throw new TypeError('runPrWatch: --pr requires a positive integer');
 
+  const resolvedConfig =
+    config !== undefined ? config : safeResolveConfig(logger);
+  const knobs = resolveWatchKnobs({
+    config: resolvedConfig,
+    flags: { pollIntervalMs, maxPolls, maxResumes, maxUpdates },
+  });
+  const effectiveTempRoot =
+    tempRoot ?? resolvedConfig?.project?.paths?.tempRoot ?? 'temp';
+
   // `gh` accepts a bare PR number or a URL; passing `<repo>#<n>` lets
   // `gh` resolve the right repository without a URL. When `--repo` is
   // omitted, `gh` infers the repo from the cwd's remote.
@@ -77,9 +301,10 @@ export async function runPrWatch({
   const result = await watchPrToTerminal({
     prUrl: prRef,
     cwd: process.cwd(),
-    maxPolls: parsePositiveInt(maxPolls, 180),
-    maxUpdates: parsePositiveInt(maxUpdates, 3),
-    pollIntervalMs: parsePositiveInt(pollIntervalMs, 10_000),
+    maxPolls: knobs.maxPolls,
+    maxUpdates: knobs.maxUpdates,
+    maxResumes: knobs.maxResumes,
+    pollIntervalMs: knobs.pollIntervalMs,
     ...(ghPrChecksFn ? { ghPrChecksFn } : {}),
     ...(ghPrViewFn ? { ghPrViewFn } : {}),
     ...(ghPrUpdateBranchFn ? { ghPrUpdateBranchFn } : {}),
@@ -96,8 +321,10 @@ export async function runPrWatch({
       requiredChecks: result.requiredChecks,
       polls: result.polls,
       updatesApplied: result.updatesApplied,
+      resumesApplied: result.resumesApplied,
       terminal: result.terminal,
       green: result.green,
+      stillRunning: result.stillRunning,
       ...(result.error ? { error: result.error } : {}),
     }),
   );
@@ -108,22 +335,78 @@ export async function runPrWatch({
     );
     return 1;
   }
-  if (!result.terminal) {
-    logger.error?.(
-      `[pr-watch] poll cap reached before every required check went terminal (polls=${result.polls}).`,
-    );
-    return 1;
+
+  if (result.green) {
+    logger.info?.('[pr-watch] all required checks green.');
+    return 0;
   }
-  if (!result.green) {
-    const red = Object.entries(result.outcomes)
-      .filter(([, v]) => v !== 'success' && v !== 'neutral' && v !== 'skipped')
-      .map(([k, v]) => `${k}=${v}`)
+
+  // Slow-but-not-red: the cap AND resume budget are exhausted with checks
+  // still pending and none failed. Never exit 1, never `timed_out` — hand
+  // off to the host's interval loop and exit 2.
+  if (result.stillRunning) {
+    const stillPending = Object.entries(result.outcomes)
+      .filter(([, v]) => v === 'still-running')
+      .map(([k]) => k)
       .join(', ');
-    logger.error?.(`[pr-watch] required check(s) not green: ${red}`);
-    return 1;
+    logger.warn?.(
+      `[pr-watch] required check(s) still running after ${result.polls} polls + ${result.resumesApplied} resumes: ${stillPending}. Hand off to the interval watch loop:`,
+    );
+    logger.warn?.('[pr-watch]   /loop 5m /loops:watch-ci');
+    return STILL_RUNNING_EXIT_CODE;
+  }
+
+  // Genuine red check — exit 1 immediately, write the digest, and surface
+  // the fix-loop handoff.
+  // Exclude 'still-running' as well as the non-failing states: when the cap
+  // fires with a mixed failed+pending map, promotePendingToStillRunning has
+  // rewritten the pending entries, and a still-running check is slow, not
+  // red — including it here would let it become the digest's "primary"
+  // failing check and mispoint the diagnosis at a slow check.
+  const failures = Object.entries(result.outcomes)
+    .filter(
+      ([, v]) =>
+        v !== 'success' &&
+        v !== 'neutral' &&
+        v !== 'skipped' &&
+        v !== 'still-running',
+    )
+    .map(([name, outcome]) => ({ name, outcome }));
+  const red = failures.map((f) => `${f.name}=${f.outcome}`).join(', ');
+  logger.error?.(`[pr-watch] required check(s) not green: ${red}`);
+  let digestPaths = null;
+  try {
+    digestPaths = writeDigestFn({
+      epicId,
+      prNumber,
+      failures,
+      tempRoot: effectiveTempRoot,
+      cwd: process.cwd(),
+      prRef,
+    });
+  } catch (err) {
+    logger.warn?.(
+      `[pr-watch] failed to write CI digest (non-fatal): ${err?.message ?? err}`,
+    );
+  }
+  if (digestPaths) {
+    logger.error?.(`[pr-watch] CI failure digest → ${digestPaths.jsonPath}`);
+  }
+  logger.error?.('[pr-watch] a required check failed. Drive it to green with:');
+  logger.error?.('[pr-watch]   /loop /loops:fix-failing-tests');
+  return 1;
+}
+
+/** Resolve config without letting a config error abort the watch. */
+function safeResolveConfig(logger) {
+  try {
+    return resolveConfig();
+  } catch (err) {
+    logger?.warn?.(
+      `[pr-watch] config resolve failed; using framework watch defaults: ${err?.message ?? err}`,
+    );
+    return null;
   }
-  logger.info?.('[pr-watch] all required checks green.');
-  return 0;
 }
 
 async function main() {
@@ -131,18 +414,22 @@ async function main() {
     options: {
       pr: { type: 'string' },
       repo: { type: 'string' },
+      epic: { type: 'string' },
       'max-updates': { type: 'string' },
       'poll-interval-ms': { type: 'string' },
       'max-polls': { type: 'string' },
+      'max-resumes': { type: 'string' },
     },
     strict: false,
   });
   return runPrWatch({
     prNumber: Number.parseInt(values.pr ?? '', 10),
     repo: values.repo ?? null,
+    epicId: values.epic ?? null,
     maxUpdates: values['max-updates'],
     pollIntervalMs: values['poll-interval-ms'],
     maxPolls: values['max-polls'],
+    maxResumes: values['max-resumes'],
   });
 }
 

package/.agents/scripts/run-verify.js

@@ -2,16 +2,31 @@
 /* node:coverage ignore file */
 
 /**
- * Local full verification — mirrors the intent of close-validation without
- * epic-scoped MI projection or push semantics.
+ * Local full verification — a true CI mirror for the gates that CAN be proven
+ * locally, without epic-scoped MI projection or push semantics.
  *
- * Order: lint (includes docs:check) → full test suite → unified baselines.
+ * Order: audit (SCA) → lint (includes docs:check) → full test suite →
+ * unified baselines.
+ *
+ * The `audit` step runs `npm audit --audit-level=high`, matching CI's
+ * "Dependency Vulnerability Audit (SCA)" gate so a local green no longer hides
+ * a high-severity advisory that CI would fail on. It is independent of the
+ * pre-push `PREPUSH_AUDIT` opt-in, which stays unchanged.
+ *
+ * A handful of CI gates cannot be reproduced by this command (action pinning,
+ * TruffleHog secret scan, the BASELINE_SCOPE=full push-scoped maintainability
+ * run) — those are catalogued in docs/ci-contract.md.
  */
 
 import { spawnSync } from 'node:child_process';
 import { runAsCli } from './lib/cli-utils.js';
 
 const STEPS = [
+  {
+    label: 'audit',
+    cmd: 'npm',
+    args: ['audit', '--audit-level=high'],
+  },
   { label: 'lint', cmd: 'npm', args: ['run', 'lint'] },
   { label: 'test', cmd: 'npm', args: ['test'] },
   {

package/.agents/scripts/single-story-confirm-merge.js

@@ -10,7 +10,7 @@
  * auto-merge completes *asynchronously* after the close script exits, so
  * the `agent::done` flip (which closes the issue) is deferred to this
  * confirmation step, invoked by the CI-watch loop in
- * `single-story-deliver.md` Step 5 once `gh pr checks --watch` exits.
+ * `single-story-deliver.md` Step 5 once `pr-watch-with-update.js` exits.
  *
  * The script:
  *   1. Resolves the PR number (`--pr <n>`, or probes

package/.agents/skills/core/epic-plan-decompose-author/SKILL.md

@@ -238,7 +238,38 @@ The envelope also has a **floor**, not just a ceiling: a Story that would plausi
 
 - A Story touching more than **`softFiles` (15)** files emits an advisory width finding — a nudge to check cohesion or declare `wide`.
 - A Story touching more than **`hardFiles` (30)** files is **rejected** unless it declares `wide` with a reason.
-- A Story with more than **`maxAcceptance` (14)** acceptance items is **rejected**; more than **`softAcceptanceCount` (10)** emits an advisory warning.
+- Acceptance mass is **advisory only**: more than **`softAcceptanceCount` (10)** acceptance items 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 the plan implies and judge the
+plan by its schedule, not by how tidy the taxonomy looks. The canonical rules
+live in the rendered decomposer prompt (`decomposer-prompts.js`) — in brief:
+
+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.
+3. **Every Story must earn its slot** by at least one of **(a) parallelism**
+   (it runs concurrently with a sibling in the schedule just built — not
+   merely "logically independent"), **(b) risk isolation** (it isolates a
+   consumer-facing behavior change or high-risk cutover into its own
+   reviewable, revertable unit), or **(c) envelope pressure** (merged into its
+   neighbor it would exceed the one-pass delivery envelope).
+4. **A dependent link with none of those justifications merges into its
+   consumer** — the single-consumer merge rule generalized from pairs to
+   chains.
+5. **Hot-file rule.** When one file appears in the `changes[]` of more than a
+   third of the Stories, the slicing axis cuts across a shared seam — merge
+   the Stories that co-edit it, or re-slice along the seam.
+
+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.
 
 #### DELIVERY SLICING (consume the Tech Spec target grouping when present)
 

package/.agents/skills/core/scope-triage/SKILL.md

@@ -50,10 +50,11 @@ The work is a single shippable capability. Signals:
 - **One capability, one reason to exist.** The artifact describes one coherent
   change a reviewer would accept as a single PR — the
   `DELIVERABLE_GRANULARITY_GUIDANCE.definition` notion of a Story.
-- **Acceptance fits one Story.** The acceptance-criteria list plausibly fits a
-  single Story's inline `acceptance[]` — i.e. it sits under the
-  `maxAcceptance` ceiling in `DEFAULT_TASK_SIZING` rather than spanning many
-  independent outcomes.
+- **Acceptance fits one Story.** The acceptance-criteria list reads as the
+  binding contract of one coherent capability rather than spanning many
+  independent outcomes. Acceptance mass is advisory-only (the
+  `softAcceptanceCount` nudge in `DEFAULT_TASK_SIZING` — there is no hard
+  ceiling), so the question is cohesion, not count.
 - **Footprint fits Story sizing.** The plausible file footprint fits the Story
   width described by `DEFAULT_TASK_SIZING` (the `softFiles` / `hardFiles`
   knobs); a legitimately broad-but-cohesive change would declare `wide` rather

package/.agents/workflows/helpers/deliver-epic-reference.md

@@ -342,14 +342,28 @@ just fires the emit and reads the resulting ledger.
    refusing to run when the body has no `## Acceptance Table` section
    and no waiver is set (the
    start gate in Phase 1 would normally catch that first).
-2. **PR open — bus-driven (Story #2894).** On
-   `acceptance.reconcile.ok` the `Finalizer` listener invokes
-   [`openOrLocatePr`](../../scripts/lib/orchestration/finalize/open-or-locate-pr.js)
-   with `{ epicId, headBranch: 'epic/<id>', baseBranch: 'main' }`.
-   The helper probes for an existing open PR on the head branch
-   first (idempotent locate path — a re-run of `/deliver`
-   on the same branch short-circuits without opening a duplicate)
-   and only opens a new PR when none exists. The listener then
+2. **PR open / ready — bus-driven (Story #2894; earlyPr split Story
+   #4359).** On `acceptance.reconcile.ok` the `Finalizer` listener
+   resolves `delivery.ci.earlyPr` via
+   [`getCiDelivery`](../../scripts/lib/config/ci.js) (default `true`) and
+   branches:
+   - **`earlyPr` on (default)** — the Epic PR already exists as a draft
+     (Phase 2 opened it at wave 1 with
+     [`openOrLocatePr`](../../scripts/lib/orchestration/finalize/open-or-locate-pr.js)
+     `{ draft: true }`). Finalize locates it and flips it ready-for-review
+     via
+     [`markPrReady`](../../scripts/lib/orchestration/finalize/open-or-locate-pr.js)
+     rather than creating a PR. `gh pr ready` on an already-ready PR is a
+     no-op, so replay is idempotent.
+   - **`earlyPr` off** — finalize invokes `openOrLocatePr` with
+     `{ epicId, headBranch: 'epic/<id>', baseBranch: 'main' }` (no
+     `draft`). The helper probes for an existing open PR on the head branch
+     first (idempotent locate path — a re-run of `/deliver` on the same
+     branch short-circuits without opening a duplicate) and only opens a
+     new PR when none exists.
+
+   In both modes the PR title/body contract (`feat: Epic #<id>` /
+   `Closes #<id>`) is identical. The listener then
    emits `pr.created` → `epic.finalize.end` and **stops** (Story
    #3367). It does **not** emit `epic.merge.ready`: that event is
    the sole `AutomergeArmer` trigger, and emitting it from finalize