mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/label-taxonomy.js

@@ -4,59 +4,30 @@
  *
  * All label names are sourced from `label-constants.js` so renames only need
  * to happen in one place. Colors come from `LABEL_COLORS` in the same module.
+ *
+ * v2 deleted the behavioral persona concept (`.agents/personas/` +
+ * `persona::*` labels). Role framing for spawns lives in `.agents/agents/`
+ * via `delivery.routing.roleScopedAgents`; QA auth identities live in
+ * `qa.personas` — neither is a GitHub label axis.
  */
 
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import {
   ACCEPTANCE_LABELS,
   AGENT_LABELS,
   DELIVERY_LABELS,
   LABEL_COLORS,
-  PERSONA_LABEL_PREFIX,
   PLANNING_LABELS,
   STATUS_LABELS,
   TYPE_LABELS,
 } from './label-constants.js';
 
-const PERSONAS_DIR = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  '..',
-  '..',
-  'personas',
-);
-
-/**
- * Discover persona labels from `.agents/personas/*.md`. The filename
- * (without extension) is the label suffix — this is the same value the
- * context hydrator uses to resolve `persona::<name>` to its markdown file.
- */
-function buildPersonaLabels() {
-  return fs
-    .readdirSync(PERSONAS_DIR)
-    .filter((f) => f.endsWith('.md'))
-    .map((f) => f.slice(0, -3))
-    .sort()
-    .map((name) => ({
-      name: `${PERSONA_LABEL_PREFIX}${name}`,
-      color: LABEL_COLORS.PERSONA,
-      description: `${name} persona`,
-    }));
-}
-
 /** @type {Array<{ name: string, color: string, description: string }>} */
 export const LABEL_TAXONOMY = [
   // Type
-  {
-    name: TYPE_LABELS.EPIC,
-    color: LABEL_COLORS.TYPE,
-    description: 'Epic-level work item',
-  },
   {
     name: TYPE_LABELS.STORY,
     color: LABEL_COLORS.TYPE,
-    description: 'User story under an Epic',
+    description: 'Story work item',
   },
 
   // Agent State
@@ -95,9 +66,6 @@ export const LABEL_TAXONOMY = [
     description: 'Blocked by a dependency',
   },
 
-  // Persona — dynamically derived from .agents/personas/*.md
-  ...buildPersonaLabels(),
-
   // Acceptance axis — explicit opt-out signal for Epics that
   // intentionally have no acceptance-table coverage (waives the Epic
   // body's ## Acceptance Table section — Story #4324).
@@ -108,15 +76,13 @@ export const LABEL_TAXONOMY = [
   },
 
   // Planning axis — operator-applied waivers for the planning → delivery
-  // handoff gates. Currently the sole entry is the `healthcheck-waived`
-  // override consumed by `plan-persist.js` when the inline healthcheck
-  // (`runPlanHealthcheck`) returned `ok: false` for a reason the
-  // operator has triaged and accepted.
+  // handoff gates. `healthcheck-waived` remains for tickets that still
+  // carry the historical label; the healthcheck CLI was retired.
   {
     name: PLANNING_LABELS.HEALTHCHECK_WAIVED,
     color: LABEL_COLORS.PLANNING,
     description:
-      'Operator override — allows agent::ready handoff despite a failing post-plan healthcheck',
+      'Historical operator override for the retired post-plan healthcheck',
   },
 
   // Delivery routing — applied by `plan-persist.js` when the risk verdict

package/.agents/scripts/lib/observability/active-story-env.js

@@ -7,7 +7,7 @@
  * This module is the single writer/clearer of those vars:
  *
  *   - `setActiveStoryEnv({ epicId, storyId, workCwd })` is called from
- *     `story-init.js` after the worktree is materialised. It sets the
+ *     `single-story-init.js` after the worktree is materialised. It sets the
  *     vars on the current `process.env` (so any child commands the
  *     orchestrator spawns inherit them) and exports them to a sibling
  *     `.env.local` inside the worktree. The harness re-spawns the
@@ -37,9 +37,21 @@ const ENV_LOCAL_BASENAME = '.env.local';
 /**
  * Names of the env vars we own. Keeping the list central makes the
  * round-trip (set on init, clear on close) trivially auditable —
- * grep `CC_EPIC_ID` / `CC_STORY_ID` to find every read site.
+ * grep `CC_EPIC_ID` / `CC_STORY_ID` / `CC_SLICE_ID` to find every read site.
+ *
+ * Epic #4476 (M5) added `CC_SLICE_ID` (the single-delivery analogue of
+ * `CC_STORY_ID` — set on the ONE long guarded session so the PostToolUse
+ * hook can emit `slice.heartbeat` off the token stream) and `CC_OPERATOR`
+ * (the resolved lease-owner handle, stamped onto hook-emitted heartbeats so
+ * `latestHeartbeatForOwner` keeps resolving a live claim). The clear path
+ * wipes all four so no stale context leaks past close.
  */
-export const ACTIVE_STORY_ENV_KEYS = ['CC_EPIC_ID', 'CC_STORY_ID'];
+export const ACTIVE_STORY_ENV_KEYS = [
+  'CC_EPIC_ID',
+  'CC_STORY_ID',
+  'CC_SLICE_ID',
+  'CC_OPERATOR',
+];
 
 /**
  * Render the `.env.local` body. One `KEY=value` line per var, LF
@@ -180,3 +192,100 @@ export function clearActiveStoryEnv({
   }
   return { envCleared: true, fileRemoved, filePath };
 }
+
+/**
+ * Render the single-delivery `.env.local` body. The single-delivery executor
+ * (`deliver-epic-single.md`) walks the Delivery Slicing table inside ONE long
+ * session; there is no Story fan-out and thus no `CC_STORY_ID`. Instead the
+ * "current slice" is exported as `CC_SLICE_ID` so the PostToolUse hook emits
+ * `slice.heartbeat` — the watchdog's forward-progress signal for the single
+ * session — as a free byproduct of tool activity.
+ *
+ * `CC_STORY_ID` MUST be absent (its presence would make the hook emit
+ * `story.heartbeat` and the trace path key off a non-existent Story). The
+ * optional `operator` handle is emitted as `CC_OPERATOR` only when supplied.
+ *
+ * Exported for testing.
+ *
+ * @param {{ epicId: number, sliceId: string, operator?: string }} input
+ * @returns {string}
+ */
+export function renderActiveSliceEnvFile({ epicId, sliceId, operator }) {
+  const lines = [
+    '# Auto-managed by .agents/scripts/lib/observability/active-story-env.js',
+    '# Re-generated on every slice-start; deleted on epic-close.',
+    `CC_EPIC_ID=${epicId}`,
+    `CC_SLICE_ID=${sliceId}`,
+  ];
+  if (typeof operator === 'string' && operator.length > 0) {
+    lines.push(`CC_OPERATOR=${operator}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Set `CC_EPIC_ID` / `CC_SLICE_ID` (+ optional `CC_OPERATOR`) on the current
+ * process and, when `workCwd` is provided, export them to
+ * `<workCwd>/.env.local` for the harness to reload on the next tool call. The
+ * single-delivery analogue of {@link setActiveStoryEnv}; called at each
+ * `slice.start` boundary so the hook's throttled `slice.heartbeat` is keyed to
+ * the slice currently being implemented.
+ *
+ * `CC_STORY_ID` is explicitly removed so a prior Story context (if any ever
+ * leaked in) cannot make the hook emit the wrong heartbeat shape.
+ *
+ * @param {{ epicId: number, sliceId: string, operator?: string|null,
+ *           workCwd?: string, env?: NodeJS.ProcessEnv, fs?: typeof nodeFs,
+ *           logger?: { warn?: (m: string) => void } }} args
+ * @returns {{ envSet: boolean, fileWritten: boolean, filePath: string|null }}
+ */
+export function setActiveSliceEnv({
+  epicId,
+  sliceId,
+  operator,
+  workCwd,
+  env = process.env,
+  fs = nodeFs,
+  logger,
+} = {}) {
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    throw new Error(
+      `[active-story-env] epicId must be a positive integer; got ${epicId}`,
+    );
+  }
+  if (typeof sliceId !== 'string' || sliceId.length === 0) {
+    throw new Error(
+      `[active-story-env] sliceId must be a non-empty string; got ${sliceId}`,
+    );
+  }
+  const normOperator =
+    typeof operator === 'string' && operator.length > 0 ? operator : undefined;
+
+  if ('CC_STORY_ID' in env) delete env.CC_STORY_ID;
+  env.CC_EPIC_ID = String(epicId);
+  env.CC_SLICE_ID = sliceId;
+  if (normOperator) env.CC_OPERATOR = normOperator;
+  else if ('CC_OPERATOR' in env) delete env.CC_OPERATOR;
+
+  let fileWritten = false;
+  let filePath = null;
+  if (typeof workCwd === 'string' && workCwd.length > 0) {
+    filePath = nodePath.join(workCwd, ENV_LOCAL_BASENAME);
+    try {
+      fs.writeFileSync(
+        filePath,
+        renderActiveSliceEnvFile({ epicId, sliceId, operator: normOperator }),
+        { encoding: 'utf8' },
+      );
+      fileWritten = true;
+    } catch (err) {
+      logger?.warn?.(
+        `[active-story-env] Failed to write ${filePath}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  }
+  return { envSet: true, fileWritten, filePath };
+}

package/.agents/scripts/lib/observability/hook-heartbeat.js

@@ -0,0 +1,187 @@
+/**
+ * hook-heartbeat.js — Epic #4476 (M5): heartbeats OFF the token stream.
+ *
+ * Before M5, the `story.heartbeat` / `slice.heartbeat` forward-progress
+ * signal that idle-watchdog consumers read from the lifecycle ledger was an
+ * **LLM obligation**: the delivery workflow instructed the agent to run
+ * `story-phase.js` / `slice-phase.js --event heartbeat` at least once per
+ * meaningful step, and every such call was a full-priced LLM turn re-reading
+ * ~100k of cached context just to append one NDJSON line.
+ *
+ * This module makes that liveness signal a **free byproduct of the agent
+ * doing any work**. It is invoked from the existing PostToolUse trace hook
+ * (`tool-trace-hook.js`), so every tool call the agent makes refreshes the
+ * heartbeat — no dedicated bookkeeping turn required. The record it appends is
+ * byte-for-byte the same `story.heartbeat` / `slice.heartbeat` shape the
+ * watchdog already consumes (emitted through the same
+ * `emit-story-heartbeat.js` / `emit-slice-lifecycle.js` emitters), so the
+ * watchdog needs no change: the signal is preserved, only its emission
+ * mechanism moves off the token stream.
+ *
+ * ## Robustness contract (mirrors `tool-trace-hook.js`)
+ *   - **No-op outside an active Story with an Epic-scoped ledger.** When a
+ *     valid `{ CC_EPIC_ID, CC_STORY_ID }` pair is not present in the
+ *     environment (v2 standalone Stories omit `CC_EPIC_ID`), `emitHeartbeatFromHook`
+ *     returns without touching the filesystem.
+ *   - **Best-effort.** Every failure is swallowed. A heartbeat is
+ *     observability, not state; a hook must never block tool execution.
+ *   - **Throttled across processes.** Command hooks are spawned as fresh
+ *     `node` processes per tool call, so in-process state cannot throttle. The
+ *     throttle is anchored to the **mtime of a sidecar marker file** under the
+ *     Epic temp dir: at most one heartbeat per `HEARTBEAT_MIN_INTERVAL_MS`
+ *     lands, regardless of how many tool calls fire in that window. This keeps
+ *     the ledger from ballooning while still refreshing liveness faster than
+ *     the watchdog's threshold.
+ */
+
+import { statSync, utimesSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { epicTempDir } from '../config/temp-paths.js';
+import { emitStoryHeartbeat } from '../orchestration/lifecycle/emit-story-heartbeat.js';
+
+/**
+ * Default minimum wall-clock gap between two hook-emitted heartbeats for the
+ * same target. Comfortably below the watchdog's default 30-minute staleness
+ * threshold, so an actively-working agent never trips a false stall, while
+ * still bounding ledger growth to ~1 line/minute of activity.
+ */
+const HEARTBEAT_MIN_INTERVAL_MS = 60_000;
+
+/**
+ * Resolve the heartbeat target from the active-Story / active-slice env vars.
+ *
+ * A `story.heartbeat` requires a parent `epicId` (its schema pins
+ * `epicId >= 1`), so a **standalone** Story (`CC_STORY_ID` set, `CC_EPIC_ID`
+ * absent) yields `null` — there is no Epic-scoped ledger to write to and the
+ * standalone path is not watched by the Epic idle watchdog. The trace hook
+ * still records that context's traces; only the heartbeat is skipped.
+ *
+ * Inert `slice.*` lifecycle (and `CC_SLICE_ID` heartbeats) were removed in
+ * the v2 ceremony lock-in — `## Slicing` is prose-only.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ kind: 'story', epicId: number, storyId: number, operator?: string }
+ *          | null}
+ */
+export function resolveHeartbeatTarget(env = process.env) {
+  const epicRaw = env.CC_EPIC_ID;
+  const storyRaw = env.CC_STORY_ID;
+  const operator =
+    typeof env.CC_OPERATOR === 'string' && env.CC_OPERATOR.length > 0
+      ? env.CC_OPERATOR
+      : undefined;
+
+  const epicId = epicRaw ? Number.parseInt(epicRaw, 10) : Number.NaN;
+  const epicOk = Number.isInteger(epicId) && epicId > 0;
+
+  if (storyRaw) {
+    const storyId = Number.parseInt(storyRaw, 10);
+    if (!Number.isInteger(storyId) || storyId <= 0) return null;
+    // story.heartbeat has no meaning without a parent Epic ledger.
+    if (!epicOk) return null;
+    return {
+      kind: 'story',
+      epicId,
+      storyId,
+      ...(operator ? { operator } : {}),
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Stable, filesystem-safe marker basename for a target. The marker's mtime is
+ * the throttle anchor; its contents are irrelevant.
+ *
+ * @param {{ kind: string, storyId?: number, sliceId?: string }} target
+ * @returns {string}
+ */
+export function heartbeatMarkerName(target) {
+  return `.heartbeat-story-${target.storyId}`;
+}
+
+/**
+ * Throttle predicate. Returns `true` when no marker exists yet, or the marker
+ * is older than `intervalMs`. Any stat error (missing file / unreadable) is
+ * treated as "emit" — the safe direction for a liveness signal.
+ *
+ * @param {{ markerPath: string, now: Date, intervalMs: number, statFn?: typeof statSync }} args
+ * @returns {boolean}
+ */
+export function shouldEmitHeartbeat({
+  markerPath,
+  now,
+  intervalMs,
+  statFn = statSync,
+}) {
+  try {
+    const st = statFn(markerPath);
+    return now.getTime() - st.mtimeMs >= intervalMs;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Update (or create) the throttle marker so its mtime is `now`. Best-effort:
+ * a failure here at worst lets the next tool call emit a second heartbeat.
+ *
+ * @param {string} markerPath
+ * @param {Date} now
+ */
+function touchMarker(markerPath, now) {
+  try {
+    writeFileSync(markerPath, '', { flag: 'a' });
+    utimesSync(markerPath, now, now);
+  } catch {
+    // swallow — throttle degrades to "emit again next call", never fatal.
+  }
+}
+
+/**
+ * Emit one throttled heartbeat for the active target, if any. The whole body
+ * is best-effort: any failure returns a `{ emitted: false }` envelope rather
+ * than throwing, so the calling PostToolUse hook never blocks the tool.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env]        Defaults to `process.env`.
+ * @param {Date} [opts.now]                     Injected clock (tests).
+ * @param {number} [opts.intervalMs]            Throttle window.
+ * @param {object} [opts.config]                Resolved config (tempRoot).
+ * @returns {{ emitted: boolean, reason?: string, kind?: string, ledgerPath?: string }}
+ */
+export function emitHeartbeatFromHook({
+  env = process.env,
+  now = new Date(),
+  intervalMs = HEARTBEAT_MIN_INTERVAL_MS,
+  config,
+} = {}) {
+  try {
+    const target = resolveHeartbeatTarget(env);
+    if (!target) return { emitted: false, reason: 'no-target' };
+
+    const markerPath = path.join(
+      epicTempDir(target.epicId, config),
+      heartbeatMarkerName(target),
+    );
+    if (!shouldEmitHeartbeat({ markerPath, now, intervalMs })) {
+      return { emitted: false, reason: 'throttled', kind: target.kind };
+    }
+
+    const timestamp = now.toISOString();
+    const res = emitStoryHeartbeat({
+      epicId: target.epicId,
+      storyId: target.storyId,
+      phase: 'implementing',
+      timestamp,
+      ...(target.operator ? { operator: target.operator } : {}),
+      config: config ?? undefined,
+    });
+    touchMarker(markerPath, now);
+    return { emitted: true, kind: target.kind, ledgerPath: res?.ledgerPath };
+  } catch {
+    return { emitted: false, reason: 'error' };
+  }
+}

package/.agents/scripts/lib/observability/source-classifier.js

@@ -57,7 +57,7 @@ function toScanString(value) {
 /**
  * Return true when `haystack` contains any framework prefix as a
  * substring. We use `includes` (not `startsWith`) because a command line
- * like `node .agents/scripts/story-init.js` carries the prefix in the
+ * like `node .agents/scripts/single-story-init.js` carries the prefix in the
  * middle, and a failing-path like `repo/.agents/foo.js` may carry an
  * absolute prefix.
  *
@@ -83,13 +83,13 @@ function containsFrameworkPrefix(haystack) {
  * Framework-wins: if either input matches a framework prefix, the result
  * is `"framework"` even when the other input looks consumer-shaped. This
  * matters for mixed cases like a consumer test invoking
- * `node .agents/scripts/story-init.js` — that's framework friction even
+ * `node .agents/scripts/single-story-init.js` — that's framework friction even
  * though the failing test path lives under the consumer.
  *
  * @param {unknown} failingPath  The path of the file or directory the
  *                               signal blames (e.g. `"tests/foo.test.js"`).
  * @param {unknown} command       The command line the signal blames
- *                                (e.g. `"node .agents/scripts/story-init.js"`).
+ *                                (e.g. `"node .agents/scripts/single-story-init.js"`).
  * @returns {"framework"|"consumer"}
  */
 export function classifyPathSource(failingPath, command) {

package/.agents/scripts/lib/observability/tool-trace-hook.js

@@ -48,6 +48,7 @@
 
 import { createHash } from 'node:crypto';
 
+import { emitHeartbeatFromHook } from './hook-heartbeat.js';
 import { appendTrace } from './signals-writer.js';
 
 /**
@@ -381,15 +382,25 @@ export async function handlePost(event, active) {
  */
 export async function main(event) {
   try {
-    const active = resolveActiveStory();
-    if (!active) return; // No active Story => zero filesystem calls.
     if (!event || typeof event !== 'object') return;
+    const active = resolveActiveStory();
 
     const phase = event.hook_event_name;
     if (phase === 'PreToolUse') {
-      handlePre(event);
+      // Pre-pairing only matters for the trace-line duration, which only
+      // the Story-scoped trace path records; slice-only context (single
+      // delivery) needs no Pre.
+      if (active) handlePre(event);
     } else if (phase === 'PostToolUse') {
-      await handlePost(event, active);
+      if (active) await handlePost(event, active);
+      // Heartbeat OFF the token stream (Epic #4476 M5). A throttled
+      // story.heartbeat / slice.heartbeat, keyed off the same active-Story /
+      // active-slice env vars, so the §2e Idle Watchdog's forward-progress
+      // signal is a free byproduct of ANY tool call — no dedicated
+      // bookkeeping LLM turn. Best-effort and self-guarded; resolves its own
+      // target (fires for slice context even when `active` is null because
+      // there is no CC_STORY_ID under single delivery).
+      emitHeartbeatFromHook();
     }
     // Any other phase is silently ignored — the hook is registered for
     // Pre/Post only; receiving anything else is a configuration error

package/.agents/scripts/lib/onboard/init-tail.js

@@ -37,9 +37,7 @@ import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
  */
 export const PLAN_HANDOFF_TEXT =
   '\n✅  Mandrel is ready. Start your first project:\n\n' +
-  '    /plan --idea "<one-line description of what you want to build>"\n\n' +
-  'Or, if you already have a `type::epic` Issue open:\n\n' +
-  '    /plan <epicId>\n';
+  '    /plan --seed "<one-line description of what you want to build>"\n';
 
 // ---------------------------------------------------------------------------
 // Internal helpers

package/.agents/scripts/lib/orchestration/acceptance-clusters.js

@@ -0,0 +1,111 @@
+/**
+ * acceptance-clusters.js — Epic #4475 (M4-B), design §S2a.
+ *
+ * The **acceptance-dilution guard** for single delivery. In the fan-out
+ * shape, each Story ran its own fresh-context acceptance self-eval critic, so
+ * a 14-AC Epic decomposed into 4 Stories got ~4 independent critic passes for
+ * free. Single delivery collapses the whole Epic into ONE guarded session — if
+ * we ran a single critic over all 14 ACs it would degrade to two redraft
+ * rounds scoring everything at once (the exact "acceptance dilution" risk the
+ * adopted design calls out as blocking).
+ *
+ * This module restores the distributed coverage: the Epic's
+ * `## Acceptance Table` AC ids are split into clusters of at most
+ * `clusterCeiling` (config `delivery.acceptanceEval.clusterCeiling`, default 4,
+ * hard-clamped to `[1, 8]`), and the executor spawns ONE maker-blind
+ * fresh-context `Agent` critic per cluster. The cluster count is therefore
+ * `ceil(totalACs / clusterCeiling)` — a deterministic fan-out width the
+ * `deliver-epic-single.md` executor and its isolation test both key off.
+ *
+ * Pure and total — inputs in, clusters out. No I/O, no throws on malformed
+ * input (a non-array / empty AC set yields zero clusters — the executor then
+ * has nothing to critique, which the front gate already forecloses by refusing
+ * `acceptance::n-a`).
+ */
+
+import { getAcceptanceEval } from '../config/acceptance-eval.js';
+
+/**
+ * @typedef {object} AcceptanceCluster
+ * @property {number} clusterIndex  Zero-based position in the fan-out.
+ * @property {string} clusterId     Stable id (`ac-cluster-<n>`, 1-based).
+ * @property {string[]} acIds       The AC ids this critic scores (≤ ceiling).
+ */
+
+/**
+ * Split an ordered list of AC ids into fresh-context critic clusters of at
+ * most `ceiling` ids each. The count is exactly `ceil(acIds.length / ceiling)`
+ * — the load-bearing fan-out-width invariant the isolation test pins.
+ *
+ * The input order is preserved (the executor orders ACs by their associated
+ * Delivery-Slicing slice before calling this, so same-slice ACs land adjacent
+ * and tend to share a cluster), but ordering is a nicety — the count guarantee
+ * is what forecloses dilution.
+ *
+ * @param {string[]} acIds       Ordered AC ids (e.g. `['AC-1', 'AC-2', …]`).
+ * @param {number} [ceiling=4]   Max ACs per cluster. A non-positive / non-
+ *                               integer ceiling degrades to 1 (one AC per
+ *                               cluster — the maximally-distributed, never-
+ *                               collapsed fan-out).
+ * @returns {AcceptanceCluster[]} `ceil(n / ceiling)` clusters; `[]` when there
+ *   are no AC ids.
+ */
+export function clusterAcceptanceCriteria(acIds, ceiling = 4) {
+  const ids = Array.isArray(acIds)
+    ? acIds.filter((id) => typeof id === 'string' && id.length > 0)
+    : [];
+  if (ids.length === 0) return [];
+
+  const size =
+    typeof ceiling === 'number' && Number.isInteger(ceiling) && ceiling >= 1
+      ? ceiling
+      : 1;
+
+  const clusters = [];
+  for (let start = 0; start < ids.length; start += size) {
+    const clusterIndex = clusters.length;
+    clusters.push({
+      clusterIndex,
+      clusterId: `ac-cluster-${clusterIndex + 1}`,
+      acIds: ids.slice(start, start + size),
+    });
+  }
+  return clusters;
+}
+
+/**
+ * The expected fan-out width for `total` ACs at `ceiling` — the number of
+ * independent maker-blind critic passes the single-delivery executor spawns.
+ * Exported so the executor (and its isolation test) can assert the number of
+ * `Agent` critic spawns equals this without re-deriving the ceil math.
+ *
+ * @param {number} total    Total AC count.
+ * @param {number} ceiling  Max ACs per cluster (≥ 1; degrades to 1 otherwise).
+ * @returns {number} `ceil(total / ceiling)`; `0` when `total <= 0`.
+ */
+export function expectedClusterCount(total, ceiling) {
+  const n = Number.isInteger(total) && total > 0 ? total : 0;
+  if (n === 0) return 0;
+  const size =
+    typeof ceiling === 'number' && Number.isInteger(ceiling) && ceiling >= 1
+      ? ceiling
+      : 1;
+  return Math.ceil(n / size);
+}
+
+/**
+ * Convenience wrapper: resolve the effective `clusterCeiling` from config
+ * (applying the framework default + the undisableable `[1, 8]` clamp) and
+ * cluster `acIds` with it. The single home the executor's `slice-phase`
+ * substrate and any future CLI use so the clamp is applied once.
+ *
+ * @param {string[]} acIds
+ * @param {object | null | undefined} config  Resolved `.agentrc.json`.
+ * @returns {{ clusters: AcceptanceCluster[], clusterCeiling: number, totalAcs: number }}
+ */
+export function clusterAcceptanceForConfig(acIds, config) {
+  const { clusterCeiling } = getAcceptanceEval(config);
+  const clusters = clusterAcceptanceCriteria(acIds, clusterCeiling);
+  const ids = Array.isArray(acIds) ? acIds.filter(Boolean) : [];
+  return { clusters, clusterCeiling, totalAcs: ids.length };
+}

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -41,7 +41,10 @@
 
 import { readFileSync } from 'node:fs';
 
-import { signalsFile } from '../config/temp-paths.js';
+import { epicArtifactPath, signalsFile } from '../config/temp-paths.js';
+
+/** Epic-level signals stream basename (mirrors signals-writer). */
+const EPIC_SIGNALS_BASENAME = 'signals.ndjson';
 
 /**
  * Verdicts that clear a criterion. Anything else (`partial`, `unmet`, or
@@ -168,11 +171,18 @@ export function buildAcceptanceEvalSignal({
   epicId,
   outcome,
   phase = 'implement',
+  clusterId = null,
 }) {
   return {
     kind: 'acceptance-eval',
     epicId: epicId ?? null,
-    storyId,
+    storyId: storyId ?? null,
+    // Epic #4475 (M4-B): single-delivery acceptance critics score an AC
+    // *cluster*, not a Story. `clusterId` scopes the per-cluster round count
+    // on the epic-level signals stream; omitted (null) for the per-Story path.
+    ...(typeof clusterId === 'string' && clusterId.length > 0
+      ? { clusterId }
+      : {}),
     phase,
     emitter: { tool: 'acceptance-eval.js' },
     details: {
@@ -216,13 +226,27 @@ export function buildAcceptanceEvalSignal({
 export function deriveAcceptanceEvalRound({
   epicId,
   storyId,
+  clusterId = null,
   config,
   readFile = (p) => readFileSync(p, 'utf8'),
   signalsPathResolver = signalsFile,
+  epicSignalsPathResolver = (eid, cfg) =>
+    epicArtifactPath(eid, EPIC_SIGNALS_BASENAME, cfg),
 }) {
+  // Epic #4475 (M4-B): single-delivery critics score AC clusters, not
+  // Stories. When `clusterId` is supplied the round is counted per cluster
+  // off the epic-level signals stream; otherwise the per-Story path
+  // (unchanged) counts by `storyId` off the Story's stream.
+  const clusterMode =
+    typeof clusterId === 'string' &&
+    clusterId.length > 0 &&
+    Number.isInteger(epicId);
+
   let text;
   try {
-    text = readFile(signalsPathResolver(epicId ?? null, storyId, config));
+    text = clusterMode
+      ? readFile(epicSignalsPathResolver(epicId, config))
+      : readFile(signalsPathResolver(epicId ?? null, storyId, config));
   } catch (_err) {
     // No ledger yet → no prior rounds.
     return 1;
@@ -240,7 +264,11 @@ export function deriveAcceptanceEvalRound({
     }
     if (!record || typeof record !== 'object') continue;
     if (record.kind !== 'acceptance-eval') continue;
-    if (record.storyId !== storyId) continue;
+    if (clusterMode) {
+      if (record.clusterId !== clusterId) continue;
+    } else if (record.storyId !== storyId) {
+      continue;
+    }
     priorRounds += 1;
   }
   return priorRounds + 1;