mandrel 1.68.0 → 1.70.0

package/.agents/scripts/lib/baselines/refresh-service.js

@@ -90,6 +90,7 @@ import {
 } from '../crap-utils.js';
 import {
   calculateAll as calculateAllMi,
+  isIgnoredByGlobs as isIgnoredByGlobsMi,
   scanDirectory as scanDirectoryMi,
 } from '../maintainability-utils.js';
 import { filterExcludedRows } from './kinds/maintainability.js';
@@ -291,7 +292,18 @@ function buildDefaultMaintainabilityScorer({ cwd, config, quality } = {}) {
         const underTarget = targetAbsDirs.some(
           (root) => abs === root || abs.startsWith(`${root}${path.sep}`),
         );
-        if (underTarget) sourceList.push(abs);
+        // Apply `ignoreGlobs` here too — the full-scope walk drops
+        // ignore-matched files via `scanDirectoryMi`, so the diff-scope path
+        // must do the same or an ignored-but-changed file (e.g. one matched by
+        // `config-settings-schema*.js`) enters `rows` and drags the
+        // `rollup["*"].min` below the maintainability floor. Reuse the same
+        // matcher `scanDirectoryMi` uses so behaviour is identical.
+        if (
+          underTarget &&
+          !isIgnoredByGlobsMi(abs, ignoreGlobs, effectiveCwd)
+        ) {
+          sourceList.push(abs);
+        }
       }
     }
     const scores = await calculateAllMi(sourceList);
@@ -727,7 +739,3 @@ function validateOptions({ kind, scopeFiles, fullScope, writePath }) {
     );
   }
 }
-
-// Exposed for the lint/test invariant (Task #2208) so the guard can list
-// every kind the service is contracted to dispatch without re-deriving it.
-export const REFRESH_SERVICE_SUPPORTED_KINDS = SUPPORTED_KINDS;

package/.agents/scripts/lib/config/baselines.js

@@ -38,23 +38,3 @@ export function getBaselines(config) {
     maintainability: merge('maintainability'),
   };
 }
-
-/**
- * Legacy entry point retained for backward-compatible imports. Story #1737
- * retired the standalone `baselines.*` block; this helper now translates
- * `{ lint: { path }, ... }` input onto synthetic `gates.<tier>.baselinePath`.
- *
- * @param {object|undefined} userBlock
- */
-export function resolveBaselines(userBlock) {
-  const block = userBlock ?? {};
-  return getBaselines({
-    quality: {
-      gates: {
-        lint: { baselinePath: block.lint?.path },
-        crap: { baselinePath: block.crap?.path },
-        maintainability: { baselinePath: block.maintainability?.path },
-      },
-    },
-  });
-}

package/.agents/scripts/lib/config/explain.js

@@ -112,8 +112,6 @@ const KEY_MEANINGS = Object.freeze({
     'Allowlist of events that fire a webhook notification.',
 
   // planning.*
-  'planning.maxTickets':
-    'Upper bound on tickets a single /plan run may create.',
   'planning.context.maxBytes':
     'Byte budget for the planning-context payload before summary mode kicks in.',
   'planning.context.summaryMode':

package/.agents/scripts/lib/config/limits.js

@@ -2,10 +2,9 @@
  * Limits/budgets/signals accessors (Epic #1720 Story #1739 — top-level reshape).
  *
  * Pre-reshape, every runtime ceiling lived under the legacy `agentSettings.limits.*` bag.
- * Post-reshape, the surviving keys are split across `planning.*` and
- * `delivery.*`:
+ * Post-reshape, the surviving operator-configurable keys are split across
+ * `planning.*` and `delivery.*`:
  *
- *   - `planning.maxTickets` (decomposer ceiling)
  *   - `planning.context.{maxBytes, summaryMode}` (planning-context budget)
  *   - `delivery.maxTokenBudget` (task-prompt hydration cap)
  *   - `delivery.execution.timeoutMs` (per-process execution timeout)
@@ -13,6 +12,14 @@
  *   - `delivery.signals.{hotspot, rework, retry}` (performance-signal
  *     detector thresholds — `churn` and `idle` dropped)
  *
+ * `maxTickets` (the decomposer reviewability budget) is a **framework
+ * constant** — Story #4163 collapsed the never-overridden
+ * `planning.maxTickets` operator knob to `LIMITS_DEFAULTS.maxTickets` and
+ * removed it from the AJV schema, the published mirror, and the explain
+ * map. The persist-time over-budget gate (ADR-20260610) still reads the
+ * constant via `getLimits(config).maxTickets`; `resolveLimits` no longer
+ * reads `planning.maxTickets`, so setting it in a config is inert.
+ *
  * Dropped entirely: `maxInstructionSteps`, `friction.*` (the LLM
  * self-pacing thresholds rewritten as qualitative prose in
  * `.agents/instructions.md`), `executionMaxBuffer` (now a framework-internal
@@ -55,7 +62,7 @@ export const LEASE_TTL_MS_DEFAULT = 900000;
  * per-complexity budget branch anywhere in the resolver.
  */
 export const LIMITS_DEFAULTS = Object.freeze({
-  maxTickets: 60,
+  maxTickets: 80,
   maxTokenBudget: 300000,
   executionTimeoutMs: 600000,
   leaseTtlMs: LEASE_TTL_MS_DEFAULT,
@@ -91,9 +98,10 @@ function mergeSignals(userSignals) {
 /**
  * Resolve the surviving limits surface against a `.agentrc.json` shape
  * (post-reshape). Accepts the resolved-config wrapper or a partial bag —
- * pulls `maxTickets` and `planningContext` from `planning.*`, pulls
- * `maxTokenBudget` and `executionTimeoutMs` from `delivery.*`, pulls
- * signals from `delivery.signals.*`.
+ * `maxTickets` is the framework constant `LIMITS_DEFAULTS.maxTickets`
+ * (no longer operator-configurable; Story #4163), pulls `planningContext`
+ * from `planning.*`, pulls `maxTokenBudget` and `executionTimeoutMs` from
+ * `delivery.*`, pulls signals from `delivery.signals.*`.
  *
  * @param {object|undefined} config
  * @returns {{
@@ -125,7 +133,10 @@ export function resolveLimits(config) {
   const lease =
     delivery.lease && typeof delivery.lease === 'object' ? delivery.lease : {};
   return {
-    maxTickets: planning.maxTickets ?? LIMITS_DEFAULTS.maxTickets,
+    // `maxTickets` is a framework constant (Story #4163) — never read from
+    // `planning.maxTickets`. The persist-time over-budget gate still reads
+    // this value via getLimits().maxTickets.
+    maxTickets: LIMITS_DEFAULTS.maxTickets,
     maxTokenBudget: delivery.maxTokenBudget ?? LIMITS_DEFAULTS.maxTokenBudget,
     executionTimeoutMs:
       execution.timeoutMs ?? LIMITS_DEFAULTS.executionTimeoutMs,

package/.agents/scripts/lib/config/temp-paths.js

@@ -56,8 +56,6 @@
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 
-let _resolveConfig;
-
 /**
  * Cache the resolved main-checkout root per spawn cwd so the
  * `git rev-parse` shell-out runs at most once per distinct working
@@ -136,20 +134,6 @@ function anchorTempRoot(tempRoot) {
   return root ? path.join(root, tempRoot) : tempRoot;
 }
 
-/**
- * Lazy import of `resolveConfig` to side-step a circular module graph
- * (`config-resolver.js` re-exports from this directory and importing it
- * eagerly would resolve `temp-paths.js` before `lib/config/limits.js` is
- * ready). The resolver itself caches per-root, so the inner call is cheap.
- */
-async function getResolveConfig() {
-  if (!_resolveConfig) {
-    const mod = await import('../config-resolver.js');
-    _resolveConfig = mod.resolveConfig;
-  }
-  return _resolveConfig;
-}
-
 /**
  * Synchronous tempRoot extraction. Accepts the canonical full resolved
  * config (`{ project, ... }`) and reads `project.paths.tempRoot`.
@@ -172,21 +156,6 @@ export function tempRootFrom(config) {
     : 'temp';
 }
 
-/**
- * Async tempRoot resolver. When the caller cannot pass a config bag, this
- * loads the project's `.agentrc.json` via `resolveConfig` (cached per
- * root). Most `.agents/scripts` consumers should prefer the synchronous
- * variant by threading their already-resolved config through.
- *
- * @param {{ cwd?: string }} [opts]
- * @returns {Promise<string>}
- */
-export async function tempRootAsync(opts) {
-  const resolveConfig = await getResolveConfig();
-  const resolved = resolveConfig({ cwd: opts?.cwd });
-  return tempRootFrom(resolved);
-}
-
 const epicId = (id) => {
   if (!Number.isInteger(id) || id <= 0) {
     throw new Error(

package/.agents/scripts/lib/config-settings-schema.js

@@ -249,7 +249,7 @@ const CODEBASE_SNAPSHOT_SCHEMA = {
 /**
  * `planning.taskSizing` — Story-sizing thresholds consumed by
  * `ticket-validator-sizing.js`. Operator overrides shallow-merge with
- * `DEFAULT_TASK_SIZING` defaults (softFiles 8, hardFiles 30,
+ * `DEFAULT_TASK_SIZING` defaults (softFiles 15, hardFiles 30,
  * maxAcceptance 14, softAcceptanceCount 10 — the uniform relaxed profile
  * from Story #3874). Story #3760 collapsed the per-profile matrix and the
  * parallel `testSurface` axis into a flat set of knobs; the `sizingProfile`
@@ -271,7 +271,6 @@ const PLANNING_SCHEMA = {
   type: 'object',
   properties: {
     riskHeuristics: LIST_OR_EXTENDER_OF_STRINGS,
-    maxTickets: { type: 'integer', minimum: 1 },
     context: PLANNING_CONTEXT_SCHEMA,
     codebaseSnapshot: CODEBASE_SNAPSHOT_SCHEMA,
     taskSizing: TASK_SIZING_SCHEMA,

package/.agents/scripts/lib/crap-utils.js

@@ -13,6 +13,10 @@ import { scanDirectory } from './maintainability-utils.js';
 import { resolveTsTranspilerVersion, transpileIfNeeded } from './transpile.js';
 
 const CRAP_WORKER_URL = new URL('./workers/crap-worker.js', import.meta.url);
+const COMBINED_MI_CRAP_WORKER_URL = new URL(
+  './workers/combined-mi-crap-worker.js',
+  import.meta.url,
+);
 
 // Pool-vs-serial cutover — single-sourced in cpu-pool.js (see the
 // POOL_SERIAL_THRESHOLD docstring for the tuning rationale).
@@ -472,3 +476,280 @@ async function scoreFilesViaPool(queue, coverage) {
     return { item, result: r };
   });
 }
+
+/**
+ * In-process combined scorer: parse `abs` exactly once via `analyzeOnce` and
+ * derive BOTH the module MI score and the per-method CRAP rows. The reference
+ * implementation for the combined worker, used directly below
+ * `SERIAL_THRESHOLD` (matching the serial fast paths of `calculateAll` and
+ * `scanAndScore`).
+ *
+ * Return shape mirrors `combined-mi-crap-worker.js`:
+ *   - `miScore` — `null` on read failure (MI dropped by the host), `0` on
+ *     transpile-null / parse-error (parity with `calculateForFile` /
+ *     `calculateForSource`), otherwise the module maintainability index.
+ *   - `crapRows` — `null` on read/transpile/parse failure (CRAP drops the
+ *     file), `[]` when coverage-skipped, otherwise the scored method rows.
+ *   - `skippedFileNoCoverage` / `skippedMethodsNoCoverage` — CRAP counters.
+ */
+function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
+  const entry = findCoverageEntry(coverage, relPath);
+  let source;
+  try {
+    source = fs.readFileSync(abs, 'utf-8');
+  } catch {
+    return {
+      relPath,
+      miScore: null,
+      skippedFileNoCoverage: false,
+      crapRows: null,
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  const prepared = transpileIfNeeded(abs, source);
+  if (prepared === null) {
+    return {
+      relPath,
+      miScore: 0,
+      skippedFileNoCoverage: false,
+      crapRows: null,
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  const {
+    miScore,
+    crapRows: rawCrapRows,
+    parseError,
+  } = analyzeOnce(prepared, entry);
+  if (parseError) {
+    return {
+      relPath,
+      miScore: 0,
+      skippedFileNoCoverage: false,
+      crapRows: null,
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  if (requireCoverage && entry === null) {
+    return {
+      relPath,
+      miScore,
+      skippedFileNoCoverage: true,
+      crapRows: [],
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  const crapRows = [];
+  let skippedMethodsNoCoverage = 0;
+  for (const mr of rawCrapRows) {
+    if (mr.crap === null || mr.coverage === null) {
+      skippedMethodsNoCoverage += 1;
+      continue;
+    }
+    crapRows.push({
+      method: mr.method,
+      startLine: mr.startLine,
+      cyclomatic: mr.cyclomatic,
+      coverage: mr.coverage,
+      crap: mr.crap,
+    });
+  }
+  return {
+    relPath,
+    miScore,
+    skippedFileNoCoverage: false,
+    crapRows,
+    skippedMethodsNoCoverage,
+  };
+}
+
+async function scoreFilesCombinedViaPool(queue, coverage) {
+  const enrichedQueue = queue.map((item) => ({
+    ...item,
+    coverageEntry: findCoverageEntry(coverage, item.relPath),
+  }));
+  const results = await runOnPool(COMBINED_MI_CRAP_WORKER_URL, enrichedQueue, {
+    workerData: {},
+  });
+  return results.map((r, i) => {
+    const item = queue[i];
+    if (!r || r.__cpuPoolError) {
+      Logger.warn(
+        `[crap-utils] combined worker pool error for ${item.relPath}: ${r?.message ?? 'unknown'}`,
+      );
+      return { item, result: null };
+    }
+    return { item, result: r };
+  });
+}
+
+/**
+ * Combined MI + CRAP single-pass scan. Walks the shared `targetDirs` once (or
+ * reuses `preScannedFiles`), dispatches every file through ONE worker that
+ * calls `analyzeOnce` a single time, and returns BOTH the maintainability
+ * score map and the CRAP scan result.
+ *
+ * This collapses the two independent escomplex passes the full-tree baseline
+ * regenerator used to run (`calculateAll` → maintainability worker, then
+ * `scanAndScore` → CRAP worker) into one parse per file. The outputs are
+ * shaped to be drop-in equivalents of the two passes they replace, so the
+ * downstream envelope projection + writer logic stays byte-identical:
+ *
+ *   - `miScores` — `Record<relPath, number>` keyed exactly as `calculateAll`
+ *     keys its result (`path.relative(cwd, abs)`, POSIX-normalised), with
+ *     read-failure files (`miScore === null`) dropped. Parity target:
+ *     `calculateAll(files)`.
+ *   - `crap` — `{ rows, scannedFiles, skippedFilesNoCoverage,
+ *     skippedMethodsNoCoverage }`, identical in shape and content to
+ *     `scanAndScore({ targetDirs, coverage, ... })`. The rows are
+ *     CRAP-sorted (file → startLine → method) so the result matches
+ *     `scanAndScore` even before the writer re-sorts.
+ *
+ * The `requireCoverage`, `scopeFiles`, `ignoreGlobs`, and `preScannedFiles`
+ * semantics match `scanAndScore` exactly — coverage gating, scope filtering,
+ * and the single-walk reuse path behave the same. Files dropped from CRAP by
+ * the coverage gate STILL contribute their MI score (the MI pass never
+ * required coverage), preserving the two-pass behaviour where MI scores every
+ * file in the target dirs.
+ *
+ * @param {{
+ *   targetDirs: string[],
+ *   coverage: object|null,
+ *   requireCoverage?: boolean,
+ *   cwd?: string,
+ *   scopeFiles?: Set<string>|string[]|null,
+ *   ignoreGlobs?: string[],
+ *   preScannedFiles?: string[]|null,
+ * }} params
+ * @returns {Promise<{
+ *   miScores: Record<string, number>,
+ *   crap: {
+ *     rows: Array<{
+ *       file: string, method: string, startLine: number,
+ *       cyclomatic: number, coverage: number, crap: number,
+ *     }>,
+ *     scannedFiles: number,
+ *     skippedFilesNoCoverage: number,
+ *     skippedMethodsNoCoverage: number,
+ *   },
+ * }>}
+ */
+export async function scanAndScoreCombined({
+  targetDirs,
+  coverage,
+  requireCoverage = true,
+  cwd = process.cwd(),
+  scopeFiles = null,
+  ignoreGlobs = [],
+  preScannedFiles = null,
+}) {
+  if (!Array.isArray(targetDirs)) {
+    throw new TypeError('scanAndScoreCombined: targetDirs must be an array');
+  }
+  const scopeSet =
+    scopeFiles == null
+      ? null
+      : scopeFiles instanceof Set
+        ? scopeFiles
+        : new Set(scopeFiles);
+
+  // Single directory walk (or reuse the caller's pre-walked list), mirroring
+  // scanAndScore so the file discovery is byte-identical between paths.
+  const files = preScannedFiles != null ? [...preScannedFiles] : [];
+  if (preScannedFiles == null) {
+    for (const dir of targetDirs) {
+      const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+      scanDirectory(abs, files, { cwd, ignoreGlobs });
+    }
+  }
+  files.sort();
+
+  // Build the work queue. Each item carries both the canonicalised relPath
+  // (CRAP's key + scope filter, matching scanAndScore) and the raw relPath
+  // (MI's key, matching calculateAll's `path.relative(cwd, p)` shape).
+  const queue = [];
+  for (const abs of files) {
+    const rawRel = path.relative(cwd, abs).replace(/\\/g, '/');
+    const relPath = canonicalisePath(rawRel);
+    if (scopeSet && !scopeSet.has(relPath)) continue;
+    queue.push({ abs, relPath, miRel: rawRel, requireCoverage });
+  }
+  const scannedFiles = queue.length;
+
+  const perFile =
+    queue.length < SERIAL_THRESHOLD
+      ? queue.map((item) => ({
+          item,
+          result: scoreFileCombinedSerial(item, coverage),
+        }))
+      : await scoreFilesCombinedViaPool(queue, coverage);
+
+  // MI assembly — mirror calculateAll: drop read-failure files (miScore
+  // null), key by the raw relative path, then sort ascending so the returned
+  // object is insertion-order-stable.
+  const miEntries = [];
+  // CRAP assembly — mirror scanAndScore: file-level skip counter, drop
+  // read/transpile/parse failures, accumulate method rows.
+  const crapRows = [];
+  let skippedFilesNoCoverage = 0;
+  let skippedMethodsNoCoverage = 0;
+
+  for (const { item, result } of perFile) {
+    if (!result) continue; // unrecoverable per-file failure: drop silently
+
+    // MI side.
+    if (result.miScore !== null) {
+      miEntries.push({ relPath: item.miRel, score: result.miScore });
+    }
+
+    // CRAP side.
+    if (result.skippedFileNoCoverage) {
+      skippedFilesNoCoverage += 1;
+      continue;
+    }
+    if (result.crapRows === null) {
+      if (result.error) {
+        Logger.warn(
+          `[crap-utils] failed to score ${item.relPath}: ${result.error}`,
+        );
+      }
+      continue;
+    }
+    skippedMethodsNoCoverage += result.skippedMethodsNoCoverage ?? 0;
+    for (const mr of result.crapRows) {
+      crapRows.push({
+        file: item.relPath,
+        method: mr.method,
+        startLine: mr.startLine,
+        cyclomatic: mr.cyclomatic,
+        coverage: mr.coverage,
+        crap: mr.crap,
+      });
+    }
+  }
+
+  miEntries.sort((a, b) =>
+    a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0,
+  );
+  const miScores = {};
+  for (const { relPath, score } of miEntries) {
+    miScores[relPath] = score;
+  }
+
+  crapRows.sort((a, b) => {
+    if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+    if (a.startLine !== b.startLine) return a.startLine - b.startLine;
+    if (a.method !== b.method) return a.method < b.method ? -1 : 1;
+    return 0;
+  });
+
+  return {
+    miScores,
+    crap: {
+      rows: crapRows,
+      scannedFiles,
+      skippedFilesNoCoverage,
+      skippedMethodsNoCoverage,
+    },
+  };
+}

package/.agents/scripts/lib/maintainability-utils.js

@@ -36,6 +36,36 @@ const IGNORED_DIRS = new Set([
   '.next',
 ]);
 
+/**
+ * Test whether an absolute (or repo-relative) file path matches any of the
+ * configured `ignoreGlobs`. This is the single source of truth for how the
+ * maintainability scorer decides a file is ignored: both the full-scope
+ * directory walk (`scanDirectory` below) and the diff-scope file-list path
+ * in `refresh-service.js` MUST funnel through it so an `ignoreGlobs`-listed
+ * file is excluded identically in both scopes (a diff-scope refresh that
+ * skipped this check would let an ignored file poison the `rollup["*"].min`
+ * floor — see `buildDefaultMaintainabilityScorer`).
+ *
+ * Matching mirrors `scanDirectory`: the path is reduced to a canonicalised,
+ * POSIX, repo-relative form and tested against each glob with minimatch's
+ * `{ dot: true }` so dot-prefixed roots like `.agents/` match.
+ *
+ * @param {string} filePath absolute or relative path to the source file
+ * @param {string[]} ignoreGlobs minimatch patterns; empty/absent is a no-op
+ * @param {string} [cwd] root for repo-relative resolution; defaults to cwd
+ * @returns {boolean} true when the file matches at least one ignore glob
+ */
+export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
+  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return false;
+  const matchCwd = cwd ?? process.cwd();
+  const absFilePath = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(matchCwd, filePath);
+  const rawRel = path.relative(matchCwd, absFilePath).replace(/\\/g, '/');
+  const relPath = canonicalisePath(rawRel);
+  return ignoreGlobs.some((g) => minimatch(relPath, g, { dot: true }));
+}
+
 /**
  * Recursively scans a directory for JS/TS source files. Accepts `.js`,
  * `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, and `.cts`. Directories listed
@@ -71,15 +101,8 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
         scanDirectory(filePath, fileList, opts);
       }
     } else if (entry.isFile() && isSupportedSourceFile(entry.name)) {
-      if (ignoreGlobs.length > 0) {
-        const absFilePath = path.isAbsolute(filePath)
-          ? filePath
-          : path.resolve(filePath);
-        const rawRel = path.relative(matchCwd, absFilePath).replace(/\\/g, '/');
-        const relPath = canonicalisePath(rawRel);
-        if (ignoreGlobs.some((g) => minimatch(relPath, g, { dot: true }))) {
-          continue;
-        }
+      if (isIgnoredByGlobs(filePath, ignoreGlobs, matchCwd)) {
+        continue;
       }
       fileList.push(filePath);
     }

package/.agents/scripts/lib/orchestration/dispatch-engine.js

@@ -27,8 +27,6 @@ import { buildManifest } from './manifest-builder.js';
 import { STATE_LABELS } from './ticketing.js';
 
 export const AGENT_DONE_LABEL = STATE_LABELS.DONE;
-export const AGENT_EXECUTING_LABEL = STATE_LABELS.EXECUTING;
-export const AGENT_READY_LABEL = STATE_LABELS.READY;
 
 /* node:coverage ignore next */
 export function ensureBranch(branchName, baseBranch) {

package/.agents/scripts/lib/orchestration/epic-cleanup.js

@@ -105,7 +105,12 @@ export function epicBranchHasOpenPr(opts) {
 /**
  * Build the list of branches owned by the Epic from the checkpoint.
  *
- * @param {{ epicId: number, waves?: Array<{ stories?: Array<{ id: number }> }> } | null} state
+ * Story #4155 — the ready-set runtime records a flat per-Story status map
+ * (`stories: { [storyId]: { status, ... } }`) on the checkpoint instead of a
+ * per-wave `waves[]` history. The owned Story branches are the keys of that
+ * map.
+ *
+ * @param {{ epicId: number, stories?: Record<string, object> } | null} state
  * @returns {{ epicBranch: string, storyBranches: string[] }}
  */
 export function listEpicBranchesFromState(state) {
@@ -113,13 +118,12 @@ export function listEpicBranchesFromState(state) {
   if (!Number.isInteger(epicId) || epicId <= 0) {
     return { epicBranch: null, storyBranches: [] };
   }
+  const storyMap =
+    state?.stories && typeof state.stories === 'object' ? state.stories : {};
   const storyIds = new Set();
-  for (const wave of state.waves ?? []) {
-    for (const story of wave?.stories ?? []) {
-      if (story && Number.isInteger(story.id) && story.id > 0) {
-        storyIds.add(story.id);
-      }
-    }
+  for (const key of Object.keys(storyMap)) {
+    const id = Number(key);
+    if (Number.isInteger(id) && id > 0) storyIds.add(id);
   }
   return {
     epicBranch: `epic/${epicId}`,

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/cli.js

@@ -89,13 +89,13 @@ async function runEmitContextPath({ epicId, provider, config, values }) {
   const ctx = await buildDecompositionContext(epicId, provider, config, {
     fullContext: values['full-context'],
   });
-  // Surface the resolved budget on stderr so a misconfigured `.agentrc.json`
-  // (e.g. flat-key `maxTickets` instead of grouped `planning.maxTickets`) is
-  // visible to the operator. The decomposer prompt embeds the same value.
-  // Story #2798 — language changed from "prompt cap" to "reviewability
-  // budget" to match the new prompt/skill contract.
+  // Surface the resolved reviewability budget on stderr so the operator
+  // sees the same value the decomposer prompt embeds. `maxTickets` is a
+  // framework constant (LIMITS_DEFAULTS.maxTickets), no longer an
+  // operator-configurable key. Story #2798 — language is "reviewability
+  // budget", not "prompt cap".
   Logger.error(
-    `[epic-plan-decompose] Resolved planning.maxTickets = ${ctx.maxTickets} (reviewability budget).`,
+    `[epic-plan-decompose] Resolved maxTickets reviewability budget = ${ctx.maxTickets} (framework constant).`,
   );
   const json = values.pretty
     ? JSON.stringify(ctx, null, 2)

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/context.js

@@ -22,9 +22,9 @@ import { applyBudget } from '../../planning-context-budget.js';
 
 export function buildDecomposerSystemPrompt(
   heuristics = [],
-  { maxTickets } = {},
+  { maxTickets, maxTokenBudget } = {},
 ) {
-  const base = renderDecomposerSystemPrompt({ maxTickets });
+  const base = renderDecomposerSystemPrompt({ maxTickets, maxTokenBudget });
   const heuristicsStr =
     heuristics.length > 0
       ? `### RISK HEURISTICS (planning metadata if any apply):\n- ${heuristics.join('\n- ')}`
@@ -115,9 +115,13 @@ export async function buildDecompositionContext(
   const heuristics = resolveHeuristics(config);
   const limits = getLimits(config);
   const maxTickets = limits.maxTickets;
+  const maxTokenBudget = limits.maxTokenBudget;
   const planningLimits = limits.planningContext;
   const { fullContext = false } = opts;
-  const systemPrompt = buildDecomposerSystemPrompt(heuristics, { maxTickets });
+  const systemPrompt = buildDecomposerSystemPrompt(heuristics, {
+    maxTickets,
+    maxTokenBudget,
+  });
 
   const budgeted = applyBudget(
     [
@@ -137,8 +141,10 @@ export async function buildDecompositionContext(
     maxTickets,
     // Story #3875 — surface the real delivery envelope to the decomposer
     // so Stories are sized against the hydration budget and the
-    // configured preflight ceilings rather than guessed.
-    maxTokenBudget: limits.maxTokenBudget,
+    // configured preflight ceilings rather than guessed. Story #4162 also
+    // threads this value into the rendered systemPrompt above as a sizing
+    // input so the prompt itself names the budget.
+    maxTokenBudget,
     preflightCeilings: resolvePreflightCeilings(config),
     contextMode: budgeted.mode,
     // Story #2801 — surface the Phase 7 planning decision so the