mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/README.md

@@ -5,7 +5,7 @@ events and performs a single side effect. The canonical close-tail roster
 — in registration order — is wired by
 [`index.js`](./index.js) (`buildDefaultListenerChain`), the production
 entrypoint the standalone `lifecycle-emit.js` CLI shells in for
-`/epic-deliver`'s Phase 6 / 7.5 / 8 / 8.5 markdown invocations:
+`/deliver`'s Phase 6 / 7.5 / 8 / 8.5 markdown invocations:
 
 - `ledger-writer.js` — privileged `onEmitted` hook that lands every
   `emitted` record on disk before any listener body runs (MUST be first).

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-armer.js

@@ -41,7 +41,7 @@
  *      This is the bus-level replay defence.
  *   2. The `gh pr view` probe — short-circuits across process
  *      boundaries when a prior run already armed auto-merge. This is
- *      the recovery defence: `/epic-deliver` restarted on the same PR
+ *      the recovery defence: `/deliver` restarted on the same PR
  *      will see the existing arm and emit `epic.merge.armed` exactly
  *      once.
  *

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-predicate.js

@@ -7,7 +7,7 @@
  *
  * Subscribes to:
  *   - `epic.automerge.start` (production path, Story #3901) → the
- *     `/epic-deliver` Phase 8.5 boundary that the `lifecycle-emit.js`
+ *     `/deliver` Phase 8.5 boundary that the `lifecycle-emit.js`
  *     CLI actually fires. This event carries `prUrl` but NO
  *     `checkOutcomes` (Phase 8's `pr-watch-with-update.js` has already
  *     polled every required check to green before Phase 8.5 runs), so

package/.agents/scripts/lib/orchestration/lifecycle/listeners/branch-cleaner.js

@@ -1,7 +1,7 @@
 // .agents/scripts/lib/orchestration/lifecycle/listeners/branch-cleaner.js
 /**
  * BranchCleaner — lifecycle listener that owns post-merge **branch** reap
- * for `/epic-deliver`. Story #2398 (companion to Cleaner, which owns the
+ * for `/deliver`. Story #2398 (companion to Cleaner, which owns the
  * temp-tree archival half of end-of-Epic cleanup).
  *
  * Subscribes to:

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

@@ -49,7 +49,7 @@
  *      level replays short-circuit.
  *   2. The `gh pr list --head` probe + `openOrLocatePr`'s internal
  *      locate path — both defend against cross-process re-runs
- *      (`/epic-deliver` restarted on the same branch after a crash).
+ *      (`/deliver` restarted on the same branch after a crash).
  *
  * Side-effect firewall: the listener emits on the bus, shells out to
  * `gh`/`git` (via the helpers), and upserts the `epic-handoff`

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

@@ -8,7 +8,7 @@
  * mirrored this roster for an in-session runner was deleted with the
  * dead epic-runner stratum in Story #3908; the host-LLM-drives-CLIs
  * model reaches every close-tail listener through the `lifecycle-emit.js`
- * CLI shells in `/epic-deliver`'s Phase 6 / 7.5 / 8 markdown invocations,
+ * CLI shells in `/deliver`'s Phase 6 / 7.5 / 8 markdown invocations,
  * which call this builder.)
  *
  * Canonical roster (registration order):

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

@@ -20,7 +20,7 @@
  *      `{ epicId, prNumber, mergeCommitSha, mergedAt, pollAttempts }`.
  *   4. If the budget is exceeded without observing a merge, return
  *      a `failed` classification with reason `budget-exceeded` and
- *      do NOT emit `epic.merge.confirmed`. The /epic-deliver
+ *      do NOT emit `epic.merge.confirmed`. The /deliver
  *      blocker-handler flow surfaces this via `agent::blocked`.
  *
  * Resume contract (AC of Task #2907): the ledger is the source of

package/.agents/scripts/lib/orchestration/lifecycle/listeners/notify-dispatcher.js

@@ -14,7 +14,7 @@
  *
  *   webhookEvents entry    lifecycle event
  *   --------------------   ---------------------
- *   `epic-started`         (emitted at /epic-deliver kickoff;
+ *   `epic-started`         (emitted at /deliver kickoff;
  *                          this listener handles `epic.snapshot.start`)
  *   `epic-blocked`         `epic.blocked`
  *   `epic-complete`        `epic.complete`

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

@@ -23,7 +23,7 @@
  * Idempotency contract (AC-10): per-instance `Set<string>` of
  * `${event}:${seqId}` keys. A repeat `(event, seqId)` short-circuits
  * without re-polling and emits nothing. Combined with the bus-level
- * replay defence, this is sufficient — re-running `/epic-deliver` after
+ * replay defence, this is sufficient — re-running `/deliver` after
  * a crash will produce a NEW seqId and the listener legitimately
  * re-runs the poll loop (which is itself idempotent: the outcome map
  * always reflects the live GitHub state).
@@ -109,7 +109,7 @@ export const extractPrNumber = parsePrNumberFromUrl;
  *
  * Exported so tests can stub.
  */
-export function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
     [
@@ -134,7 +134,7 @@ export function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
  * can detect the BEHIND condition (PR head is behind its base branch)
  * AFTER every required check is green. Exported so tests can stub.
  */
-export function ghPrView({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrView({ prUrl, cwd, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
     ['pr', 'view', prUrl, '--json', 'mergeStateStatus'],
@@ -154,7 +154,7 @@ export function ghPrView({ prUrl, cwd, spawnFn = spawnSync }) {
  * BEHIND" (the conservative recovery branch). Pure — exported for
  * tests.
  */
-export function parseMergeStateStatus(stdout) {
+function parseMergeStateStatus(stdout) {
   const trimmed = String(stdout ?? '').trim();
   if (trimmed.length === 0) return '';
   try {
@@ -172,7 +172,7 @@ export function parseMergeStateStatus(stdout) {
  * loop to fast-forward the PR head with its base branch. Exported so
  * tests can stub and assert call counts.
  */
-export function ghPrUpdateBranch({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrUpdateBranch({ prUrl, cwd, spawnFn = spawnSync }) {
   const result = spawnFn('gh', ['pr', 'update-branch', prUrl], {
     cwd,
     encoding: 'utf-8',
@@ -192,7 +192,7 @@ export function ghPrUpdateBranch({ prUrl, cwd, spawnFn = spawnSync }) {
  * the same definition as the downstream predicate. Pure — exported
  * for tests.
  */
-export const GREEN_CHECK_OUTCOMES = Object.freeze(
+const GREEN_CHECK_OUTCOMES = Object.freeze(
   new Set(['success', 'neutral', 'skipped']),
 );
 
@@ -202,7 +202,7 @@ export const GREEN_CHECK_OUTCOMES = Object.freeze(
  * regardless of mergeStateStatus, so we never auto-recover into a
  * failing PR.
  */
-export function allGreen(outcomes) {
+function allGreen(outcomes) {
   const values = Object.values(outcomes);
   if (values.length === 0) return false;
   for (const v of values) {
@@ -271,7 +271,7 @@ export function allTerminal(outcomes) {
  * behaviour is reviewable. Called only when the poll loop exits via
  * the iteration cap.
  */
-export function promotePendingToTimedOut(outcomes) {
+function promotePendingToTimedOut(outcomes) {
   const out = {};
   for (const [k, v] of Object.entries(outcomes)) {
     out[k] = v === 'pending' ? 'timed_out' : v;

package/.agents/scripts/lib/orchestration/manifest-builder.js

@@ -1,7 +1,7 @@
 /**
  * lib/orchestration/manifest-builder.js — Manifest Building Logic
  *
- * 3-tier-only producer. Reads Story tickets from `allTickets` directly,
+ * 2-tier-only producer. Reads Story tickets from `allTickets` directly,
  * computes Story-scoped waves, and emits the `waves[].stories[]` /
  * Story-only `storyManifest` shape. The pre-Epic-#3163 Task-tier branch
  * has been removed; the framework no longer carries a Task-tier
@@ -48,7 +48,7 @@ function extractSectionList(body, heading) {
 
 /**
  * Project a Story ticket into the inline-acceptance/verify shape required by
- * the 3-tier waves[].stories[] schema. Reads `## Acceptance` /
+ * the 2-tier waves[].stories[] schema. Reads `## Acceptance` /
  * `## Acceptance Criteria` and `## Verify` sections from the body.
  *
  * @param {object} story
@@ -95,7 +95,7 @@ function projectStoryForWave(story, epicId) {
 const AGENT_DONE_LABEL = STATE_LABELS.DONE;
 
 /**
- * Build the Story-only manifest array used by the 3-tier hierarchy path.
+ * Build the Story-only manifest array used by the 2-tier hierarchy path.
  * Reads Story tickets directly from `allTickets`; there is no Task tier
  * to walk. Each entry exposes an empty `tasks: []` to keep downstream
  * consumers (renderers, dispatch helpers) on a single per-Story shape
@@ -145,7 +145,7 @@ function buildStoryOnlyManifest(stories, epicId) {
 }
 
 /**
- * Build the wave records for a 3-tier manifest. Each wave entry exposes a
+ * Build the wave records for a 2-tier manifest. Each wave entry exposes a
  * `stories[]` projection (instead of the legacy `tasks[]`) so dispatch
  * consumers can fan Story execution out wave-by-wave without ever seeing
  * a `type::task` ticket.
@@ -200,7 +200,7 @@ export function buildManifest({
     epicTitle: epic?.title ?? '',
     executor: 'claude-code',
     dryRun,
-    hierarchy: '3-tier',
+    hierarchy: '2-tier',
     summary: {
       totalStories,
       doneStories,

package/.agents/scripts/lib/orchestration/parked-follow-ons.js

@@ -9,7 +9,7 @@
  *   - "parked" — the Story is genuinely outside the manifest (carved off
  *                mid-sprint, no recut lineage). The operator should explicitly
  *                adopt it into the current Epic or defer it. Surfaced as a
- *                structured comment so `/epic-deliver` has a single checkpoint.
+ *                structured comment so `/deliver` has a single checkpoint.
  *
  * Both categories are informational at the wave-completeness gate — they do
  * not fail closure by themselves. The gate continues to enforce that every
@@ -81,7 +81,7 @@ export function renderParkedFollowOnsComment(epicId, classification) {
     `## 🪝 Parked Follow-Ons & Recuts — Epic #${epicId}`,
     '',
     'Stories created under this Epic that are **not** in the frozen dispatch',
-    'manifest. Surfaced here so `/epic-deliver` can gate on them at the',
+    'manifest. Surfaced here so `/deliver` can gate on them at the',
     'completeness check.',
     '',
     `- **Recuts** (attributable to a manifest Story): ${recuts.length}`,

package/.agents/scripts/lib/orchestration/plan-runner/plan-router.js

@@ -2,7 +2,7 @@
  * plan-router — given an Epic's current labels, decide which plan-phase CLI
  * should run next.
  *
- * Used by the local `/epic-plan` wrapper (chains spec → decompose).
+ * Used by the local `/plan` wrapper (chains spec → decompose).
  *
  * The router is intentionally stateless. Callers feed the current label set
  * (a string array, usually from `provider.getEpic(id).labels`) and receive a
@@ -21,7 +21,7 @@ export const PLAN_PHASE_NAMES = Object.freeze({
  * path used by the local wrapper; `command` is the slash-command invocation
  * operators fire.
  *
- * Spec and Decompose are served by the unified `/epic-plan` wrapper with a
+ * Spec and Decompose are served by the unified `/plan` wrapper with a
  * `--phase` flag — the phase workflows themselves live at
  * `.agents/workflows/helpers/epic-plan-{spec,decompose}.md` and are not
  * directly invokable slash commands.
@@ -33,20 +33,20 @@ export const PLAN_PHASE_DESCRIPTORS = Object.freeze({
   [PLAN_PHASE_NAMES.SPEC]: {
     phase: PLAN_PHASE_NAMES.SPEC,
     script: '.agents/scripts/epic-plan-spec.js',
-    command: '/epic-plan --phase spec',
+    command: '/plan --phase spec',
     parkingLabel: AGENT_LABELS.REVIEW_SPEC,
   },
   [PLAN_PHASE_NAMES.DECOMPOSE]: {
     phase: PLAN_PHASE_NAMES.DECOMPOSE,
     script: '.agents/scripts/epic-plan-decompose.js',
-    command: '/epic-plan --phase decompose',
+    command: '/plan --phase decompose',
     parkingLabel: AGENT_LABELS.READY,
   },
 });
 
 /**
  * Given the Epic's current labels, pick the next plan phase to run in the
- * local `/epic-plan` wrapper.
+ * local `/plan` wrapper.
  *
  * Precedence:
  *   1. If the Epic already carries `agent::ready`, there is nothing left to

package/.agents/scripts/lib/orchestration/post-merge/phases/notification.js

@@ -21,7 +21,7 @@ export async function notificationPhase(ctx, state) {
     storyId,
     story,
     epicBranch,
-    orchestration,
+    config,
     progress,
     provider,
     notifyFn = notify,
@@ -39,7 +39,7 @@ export async function notificationPhase(ctx, state) {
       level: 'story',
       epicId,
     },
-    { orchestration },
+    { config },
   );
   // Fire a rolled-up `epic-progress` webhook so operators see the Epic's
   // overall stories-done count tick up at each story-close, without
@@ -66,7 +66,7 @@ export async function notificationPhase(ctx, state) {
           level: 'epic',
           epicId,
         },
-        { orchestration, skipComment: true },
+        { config, skipComment: true },
       );
     } catch (err) {
       logger?.warn?.(

package/.agents/scripts/lib/orchestration/post-merge/phases/ticket-closure.js

@@ -2,14 +2,14 @@
  * phases/ticket-closure.js — post-merge ticket transition + cascade phase.
  *
  * Transitions the Story to `agent::done`, then runs cascade completion
- * so any parent Feature/Epic that is now fully resolved closes too.
+ * so any parent Epic-side rollup that is now fully resolved closes too.
  *
- * **3-tier closure (Story #3127).** Under the 3-tier hierarchy a Story
+ * **2-tier closure (Story #3127).** Under the 2-tier hierarchy a Story
  * is the leaf unit of execution and has no child tickets — `tasks`
  * arrives as an empty array. `batchTransitionTickets` handles the empty
  * input cleanly (the loop trivially completes), the Story is
  * transitioned alone, and cascade completion walks upward to
- * Feature/Epic. No branch on hierarchy mode is required here.
+ * parent. No branch on hierarchy mode is required here.
  *
  * Notifications are intentionally
  * NOT routed through the per-ticket transitions here — `notificationPhase`

package/.agents/scripts/lib/orchestration/post-merge/phases/worktree-reap.js

@@ -54,9 +54,9 @@ function findStillRegisteredEntry(entries, storyId) {
   });
 }
 
-function resolveWorktreeRoot(repoRoot, orchestration) {
+function resolveWorktreeRoot(repoRoot, delivery) {
   if (!repoRoot) return null;
-  const configuredRoot = orchestration?.worktreeIsolation?.root ?? '.worktrees';
+  const configuredRoot = delivery?.worktreeIsolation?.root ?? '.worktrees';
   return path.join(repoRoot, configuredRoot);
 }
 
@@ -263,7 +263,7 @@ function logStaleRegistryEntry({ state, stillRegistered, logger }) {
 
 export async function worktreeReapPhase(ctx) {
   const {
-    orchestration,
+    delivery,
     storyId,
     epicId,
     epicBranch,
@@ -276,7 +276,7 @@ export async function worktreeReapPhase(ctx) {
     recordPendingCleanupFn = recordPendingCleanup,
     pathExistsFn = fs.existsSync,
   } = ctx;
-  const wtConfig = orchestration?.worktreeIsolation;
+  const wtConfig = delivery?.worktreeIsolation;
   const log = reapPhaseLogger(progress);
   const skipState = resolveSkipState(wtConfig, log);
   if (skipState) return skipState;
@@ -309,7 +309,7 @@ export async function worktreeReapPhase(ctx) {
     stillRegistered,
     reapResult,
     storyId,
-    orchestration,
+    delivery,
     repoRoot,
     logger,
     recordPendingCleanupFn,
@@ -352,7 +352,7 @@ function applyStillRegisteredState({
   stillRegistered,
   reapResult,
   storyId,
-  orchestration,
+  delivery,
   repoRoot,
   logger,
   recordPendingCleanupFn,
@@ -370,7 +370,7 @@ function applyStillRegisteredState({
       reason: 'still-registered-after-reap',
     };
   }
-  const worktreeRoot = resolveWorktreeRoot(repoRoot, orchestration);
+  const worktreeRoot = resolveWorktreeRoot(repoRoot, delivery);
   let manifestEntry = null;
   if (worktreeRoot) {
     try {

package/.agents/scripts/lib/orchestration/preflight-cache.js

@@ -3,7 +3,7 @@
  *
  * Cache adapter for the snapshot/DAG envelope produced by
  * `epic-deliver-preflight.js` so `epic-deliver-prepare.js` can skip the
- * second walk of Epic → Feature → Story when the underlying Epic ticket
+ * second walk of Epic → Story when the underlying Epic ticket
  * has not drifted between the two operator invocations.
  *
  * Contract:
@@ -53,28 +53,51 @@ export function preflightCachePath({ epicId, cwd }) {
 }
 
 /**
- * Stable string fingerprint of an Epic snapshot. The hash is keyed on the
- * exact fields `runSnapshotPhase` reads (`getTicket(epicId)` return value)
- * so that any drift the snapshot phase would observe forces a cache miss.
+ * Per-ticket fingerprint fields shared by the Epic and each Story in the
+ * cache key: id, body, sorted labels, and updatedAt. Story bodies carry
+ * the dependency edges, so hashing them means a Story-dependency edit
+ * forces a cache miss (Story #4019 — the previous Epic-only key let
+ * dependency edits slip through unnoticed).
+ *
+ * @param {{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }} ticket
+ * @returns {{ id: number|string|null, body: string, labels: string[], updatedAt: string|null }}
+ */
+function ticketFingerprint(ticket) {
+  const t = ticket && typeof ticket === 'object' ? ticket : {};
+  return {
+    id: t.id ?? t.number ?? null,
+    body: typeof t.body === 'string' ? t.body : '',
+    labels: Array.isArray(t.labels) ? [...t.labels].map(String).sort() : [],
+    updatedAt: typeof t.updatedAt === 'string' ? t.updatedAt : null,
+  };
+}
+
+/**
+ * Stable string fingerprint of an Epic snapshot **plus its Story
+ * dependency state**. The hash is keyed on the exact fields
+ * `runSnapshotPhase` reads (`getTicket(epicId)` return value) and on each
+ * Story's id/body/labels/updatedAt, so that any drift the snapshot or
+ * wave-DAG phases would observe — including a Story-dependency edit —
+ * forces a cache miss (Story #4019).
  *
  * Labels are sorted to absorb GitHub's non-deterministic label order
- * across responses. The hash is sha256; we return the full hex digest so
+ * across responses; stories are sorted by id so enumeration order never
+ * perturbs the key. The hash is sha256; we return the full hex digest so
  * the cache key is collision-resistant for the lifetime of a delivery.
  *
  * @param {{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }} epic
+ * @param {Array<{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }>} [stories]
  * @returns {string}
  */
-export function computeBaseSha(epic) {
+export function computeBaseSha(epic, stories = []) {
   if (!epic || typeof epic !== 'object') {
     throw new TypeError('computeBaseSha: epic snapshot must be an object');
   }
-  const id = epic.id ?? epic.number ?? null;
-  const body = typeof epic.body === 'string' ? epic.body : '';
-  const labels = Array.isArray(epic.labels)
-    ? [...epic.labels].map(String).sort()
-    : [];
-  const updatedAt = typeof epic.updatedAt === 'string' ? epic.updatedAt : null;
-  const payload = JSON.stringify({ id, body, labels, updatedAt });
+  const epicPrint = ticketFingerprint(epic);
+  const storyPrints = (Array.isArray(stories) ? stories : [])
+    .map(ticketFingerprint)
+    .sort((a, b) => Number(a.id ?? 0) - Number(b.id ?? 0));
+  const payload = JSON.stringify({ ...epicPrint, stories: storyPrints });
   return createHash('sha256').update(payload).digest('hex');
 }
 

package/.agents/scripts/lib/orchestration/recurring-failure-detector.js

@@ -6,7 +6,7 @@
  * `close-validate.end` `emitted` records and groups them by `failedGate`.
  * Returns one finding per gate that appears in **two or more distinct
  * Stories** within the same Epic. Findings are the substrate
- * `/epic-deliver` consumes when upserting the cross-Story
+ * `/deliver` consumes when upserting the cross-Story
  * `recurring-failure-class` structured comment on the Epic ticket.
  *
  * The helper is intentionally pure: no GitHub I/O, no global state. It

package/.agents/scripts/lib/orchestration/retro/phases/compose-body.js

@@ -328,7 +328,7 @@ function followOnBody(s) {
     ``,
     `Trigger: ${trigger}.`,
     ``,
-    `Apply the meta::framework-gap label so /epic-plan Phase 0 surfaces it on the next planning pass.`,
+    `Apply the meta::framework-gap label so /plan Phase 0 surfaces it on the next planning pass.`,
   ].join('\n');
 }
 

package/.agents/scripts/lib/orchestration/retro/phases/gather-signals.js

@@ -130,8 +130,8 @@ async function warnIfEpicLooksPopulated({ epicId, provider, logger }) {
  * `logger` so the silent failure becomes visible. Probe failure degrades
  * gracefully — the function never throws on the guard alone.
  *
- * **3-tier ledgers (Story #3151, Story #3200).** Under the 3-tier
- * hierarchy (Epic → Feature → Story; no Task-tier children), `friction`
+ * **2-tier ledgers (Story #3151, Story #3200).** Under the 2-tier
+ * hierarchy (Epic → Story; no Task-tier children), `friction`
  * / `parked` / `recuts` / `storyPerfSummaries` are all Story-scoped, so
  * the function continues to produce a non-empty signals report. The
  * empty-walk guard above is **not** triggered for this shape because

package/.agents/scripts/lib/orchestration/retro-runner.js

@@ -3,10 +3,10 @@
  *
  * Story #1155 (Epic #1142, 5.40.0) — extracts the helper-driven
  * `epic-retro` invocation into a callable module so the
- * `/epic-deliver` runner can fire Phase E without a separate LLM
+ * `/deliver` runner can fire Phase E without a separate LLM
  * helper turn. (Story #2259, Epic #2172: the legacy deliver-runner
  * CLI was retired once delivery moved entirely into the slash
- * command.) The retro fires before `/epic-deliver`'s finalize step
+ * command.) The retro fires before `/deliver`'s finalize step
  * opens the PR — the operator's PR-merge is the final human gate, not
  * the retro itself.
  *
@@ -56,7 +56,7 @@ export { gatherRetroSignals } from './retro/phases/gather-signals.js';
 /**
  * Public: compose and post the retro structured comment on the Epic.
  *
- * Story #1290 (Epic #1143) — at /epic-deliver Phase 5, the runner invokes
+ * Story #1290 (Epic #1143) — at /deliver Phase 5, the runner invokes
  * the self-healing checks registry with `scope: 'retro'` and
  * `autoFix: false`. The retro is **read-only by construction**: the
  * registry runner enforces the invariant by throwing if any caller flips

package/.agents/scripts/lib/orchestration/review-depth.js

@@ -22,7 +22,7 @@
  *                  is enumerated).
  *   - `standard` — everything else, including absent/malformed risk envelopes
  *                  and a `medium` level. Fail toward the middle, never toward
- *                  `light`: an Epic that skipped `/epic-plan` has no risk
+ *                  `light`: an Epic that skipped `/plan` has no risk
  *                  verdict, and treating it as `light` would under-review
  *                  unjudged work while `standard` preserves today's behaviour.
  *

package/.agents/scripts/lib/orchestration/review-providers/codex.js

@@ -31,6 +31,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { parseProviderFindings } from './parse-findings.js';
 import { renderDepthDirective } from './review-depth.js';
 
 /**
@@ -173,66 +174,10 @@ export function mapCodexSeverity(raw) {
  * @throws {Error} when stdout is not parseable JSON.
  */
 export function parseCodexFindings(rawStdout) {
-  const text = (rawStdout ?? '').trim();
-  if (text.length === 0) return [];
-
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch (err) {
-    throw new Error(
-      `[codex-review] Failed to parse /codex:review stdout as JSON: ${
-        err?.message ?? err
-      }`,
-    );
-  }
-
-  // Unwrap a single layer of envelope when present.
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-    else if (parsed.result !== undefined) parsed = parsed.result;
-    else if (parsed.data !== undefined) parsed = parsed.data;
-  }
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-  }
-
-  if (!Array.isArray(parsed)) return [];
-
-  /** @type {Finding[]} */
-  const findings = [];
-  for (const entry of parsed) {
-    if (!entry || typeof entry !== 'object') continue;
-    const title =
-      typeof entry.title === 'string' && entry.title.trim().length > 0
-        ? entry.title.trim()
-        : null;
-    const body =
-      typeof entry.body === 'string' && entry.body.trim().length > 0
-        ? entry.body
-        : typeof entry.message === 'string' && entry.message.trim().length > 0
-          ? entry.message
-          : null;
-    if (!title || !body) continue;
-
-    /** @type {Finding} */
-    const finding = {
-      severity: mapCodexSeverity(entry.severity),
-      title,
-      body,
-    };
-    if (typeof entry.file === 'string' && entry.file.length > 0) {
-      finding.file = entry.file;
-    }
-    if (Number.isInteger(entry.line) && entry.line > 0) {
-      finding.line = entry.line;
-    }
-    if (typeof entry.category === 'string' && entry.category.length > 0) {
-      finding.category = entry.category;
-    }
-    findings.push(finding);
-  }
-  return findings;
+  return parseProviderFindings(rawStdout, {
+    errorPrefix: '[codex-review] Failed to parse /codex:review stdout as JSON',
+    mapSeverity: mapCodexSeverity,
+  });
 }
 
 /**

package/.agents/scripts/lib/orchestration/review-providers/native.js

@@ -42,14 +42,14 @@
 
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-import { PROJECT_ROOT } from '../../config-resolver.js';
-import { runOnPool } from '../../cpu-pool.js';
+import { POOL_SERIAL_THRESHOLD, runOnPool } from '../../cpu-pool.js';
 import { gitSpawn } from '../../git-utils.js';
 import {
   calculateReport,
   classifyReport,
 } from '../../maintainability-engine.js';
-import { transpileIfNeeded } from '../../maintainability-utils.js';
+import { PROJECT_ROOT } from '../../project-root.js';
+import { transpileIfNeeded } from '../../transpile.js';
 import {
   hashCommandConfig,
   recordPass,
@@ -67,10 +67,11 @@ const MAINTAINABILITY_REPORT_WORKER_URL = new URL(
  * `analyzeChangedFiles` scores in-process (the pre-pool serial path). At or
  * above it, per-file `calculateReportForFile` scoring is offloaded to the
  * shared worker pool so the event loop is not blocked during epic-scoped
- * reviews (f-performance). Tuned to match the `SERIAL_THRESHOLD` used by the
- * maintainability baseline scan in `maintainability-utils.js`.
+ * reviews (f-performance). Single-sourced in `cpu-pool.js` (see the
+ * `POOL_SERIAL_THRESHOLD` docstring for the tuning rationale); the
+ * `SERIAL_THRESHOLD` export name is preserved as this module's public API.
  */
-export const SERIAL_THRESHOLD = 8;
+export const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
 
 const JS_MAINTAINABILITY_EXTS = new Set(['.js', '.mjs', '.cjs']);