mandrel 2.60.0 → 2.61.0

package/.agents/scripts/lib/orchestration/ci-rerun-guard.js

@@ -1,48 +1,16 @@
 // .agents/scripts/lib/orchestration/ci-rerun-guard.js
 /**
- * ci-rerun-guard.js — the machine enforcement behind the no-rerun MUST in
- * [`rules/ci-remediation.md`](../../../rules/ci-remediation.md) § Verifier
- * (Story #4865). Owns the CI failure digest (write / read / retire), the
- * head-SHA discriminator, the auto-merge disarm, and the blocked-delivery
- * escalation. `pr-watch-with-update.js` is the enforcement point; this
- * module is the mechanism it drives.
+ * ci-rerun-guard.js — mechanism behind the no-rerun MUST in
+ * `rules/ci-remediation.md` § Verifier, driven by `pr-watch-with-update.js`:
+ * the CI failure digest, the head-SHA discriminator, and the block.
  *
- * **Why the first red, and not the rerun-green.** The obvious design —
- * observe a green that arrives on a re-run of the same commit, then disarm
- * auto-merge and block — cannot enforce anything. GitHub's native
- * auto-merge fires server-side the moment branch protection is satisfied,
- * so it races the watcher's next poll: by the time the rerun-green is
- * observed, the PR may already be merged. The only race-free observation
- * point is the **first red**, which necessarily precedes any green. So the
- * watcher disarms on red and records the PR head SHA; the head SHA is then
- * read at **re-arm** time, not at merge time.
- *
- * **Head SHA is the discriminator.** A green on a *different* head SHA is a
- * fix at source — legal, and it retires the digest. A green on the *same*
- * head SHA is a re-run of a failed job, which the rule forbids: the
- * delivery hard-stops at `agent::blocked` and a CI-gap intake filing
- * (`file-ci-gap.js`, carrying the run link and failure signature the digest
- * already holds) is required before it can proceed.
- *
- * **One rerun after a recorded verdict (Story #5343).** The single exception,
- * and it is evidence-gated rather than discretionary: once `file-ci-gap.js`
- * has filed a `capacity` or `unreproducible-tier` verdict **for the current
- * head SHA**, it stamps a `rerunAllowance` on the digest, and exactly one
- * same-SHA green is then admitted — the digest is retired and the delivery
- * proceeds. This closes the one shape where the rule stranded a correct
- * delivery: a runner that ran out of something has no fix at source to make,
- * so the branch could never move its head SHA and the block needed a human to
- * clear. Every other same-SHA green is still a violation, the allowance is
- * spent the moment it is honoured (it dies with the digest), and a second red
- * after the rerun is real: it writes a fresh digest with no allowance, so it
- * routes to Option 1 like any other red.
- *
- * **Fail closed on an unverifiable green.** A digest whose head SHA is
- * missing, or a current head SHA that `gh` could not resolve, leaves no
- * evidence that the red was fixed at source. An unresolved red plus no
- * evidence of a new commit is treated as a violation rather than waved
- * through — the same unknown-is-blocking posture the arming probe takes on
- * an unrecognized check state.
+ * Enforcement happens at the first red, not the rerun-green: native
+ * auto-merge fires server-side and races the watcher, so only the red is a
+ * race-free observation point. The watcher disarms on red and records the
+ * head SHA. A later green on a different SHA is a fix at source; on the
+ * same SHA it is a forbidden rerun, unless `file-ci-gap.js` recorded a
+ * `capacity`/`unreproducible-tier` allowance for that SHA (one rerun; it
+ * dies with the digest). A missing SHA on either side fails closed.
  */
 
 import {
@@ -57,6 +25,7 @@ import { spawnChild } from '../child-exec.js';
 import { resolveConfig } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
 import { createProvider } from '../provider-factory.js';
+import { isRerunPermitted } from './check-state.js';
 import {
   STATE_LABELS,
   transitionTicketState,
@@ -67,11 +36,8 @@ import {
 const MAX_PRIOR_REDS = 10;
 
 /**
- * The verdicts that earn the one same-SHA rerun (Story #5343). Both mean the
- * failure is a property of the *environment*, proven — so no commit on the
- * branch can move the head SHA to clear it. `pre-existing` is deliberately
- * excluded: it reproduces on `main`, which is a real defect someone owns and
- * a rerun cannot make go away.
+ * Verdicts earning the one same-SHA rerun: proven environment faults no
+ * commit can fix. `pre-existing` is excluded — a real defect on `main`.
  *
  * @type {readonly ['capacity', 'unreproducible-tier']}
  */
@@ -81,13 +47,6 @@ export const RERUN_ALLOWANCE_VERDICTS = Object.freeze([
 ]);
 
 /**
- * Resolve which ticket the digest is keyed to. Story #4539: the digest used
- * to be Epic-scoped by filename and returned `null` without an epic id — so
- * on the v2 Story path (which has no Epic and invokes the watch with `--pr`
- * alone) a red check wrote no digest at all, despite the module header
- * advertising one. v2.0.0 removed the Epic tier; Story scope is the only
- * scope.
- *
  * @param {{ storyId?: number|string|null }} opts
  * @returns {{ kind: 'story', id: number } | null}
  */
@@ -100,9 +59,8 @@ export function resolveDigestScope({ storyId = null } = {}) {
 }
 
 /**
- * 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.
+ * Coarse classification from a check name; steers the next move, not a
+ * root-cause verdict.
  *
  * @param {string} name  failing required-check name.
  * @returns {'test'|'lint'|'baseline'|'build'|'unknown'}
@@ -117,13 +75,7 @@ export function classifyFailure(name) {
 }
 
 /**
- * Resolve the `.json` / `.md` digest paths for a scope. Returns `null` when
- * no scope can be keyed (the digest is scoped by filename and has nothing
- * to key on).
- *
- * Module-private: `writeCiDigest` / `readCiDigest` / `retireCiDigest` are the
- * only callers and are the surface worth pinning, so the keying is asserted
- * through them rather than through an export nothing in production reaches.
+ * Digest paths for a scope; `null` without a Story id to key on.
  *
  * @param {{ storyId?: number|string|null, tempRoot: string, cwd: string }} opts
  * @returns {{ scope: { kind: 'story', id: number }, jsonPath: string, mdPath: string } | null}
@@ -141,10 +93,7 @@ function ciDigestPaths({ storyId = null, tempRoot, cwd }) {
 }
 
 /**
- * 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.
- * Injected into `writeCiDigest` so tests never shell out.
+ * Tail of the failed job log; best-effort, empty on any failure.
  */
 function ghRunLogTail({ runId, cwd, spawnFn, maxLines = 40 }) {
   if (!runId) return '';
@@ -160,11 +109,8 @@ function ghRunLogTail({ runId, cwd, spawnFn, maxLines = 40 }) {
 }
 
 /**
- * Resolve the failing check's run identity — the GitHub Actions run id AND
- * the run URL. Best-effort via `gh pr checks --json name,link`: the `link`
- * field carries the run URL whose trailing path segment is the run id. The
- * URL matters as much as the id, because the intake issue a
- * rerun violation demands must carry a run **link**.
+ * The failing check's run id and URL (the intake filing needs the link).
+ * Best-effort.
  *
  * @returns {{ runId: string|null, url: string|null }}
  */
@@ -188,10 +134,8 @@ function resolveFailingCheckRun({ prRef, checkName, cwd, spawnFn }) {
 }
 
 /**
- * Resolve the PR's current head SHA (`headRefOid`) — the discriminator
- * between a legal fix-at-source green and a forbidden rerun green. Returns
- * `null` when `gh` fails or the payload is unparseable; callers treat an
- * unresolvable head as unverifiable, never as "changed".
+ * The PR's head SHA; `null` on failure, which callers treat as
+ * unverifiable, never as "changed".
  *
  * @param {{ prRef: string, cwd: string, spawnFn?: Function }} opts
  * @returns {string|null}
@@ -216,60 +160,8 @@ export function resolvePrHeadSha({ prRef, cwd, spawnFn }) {
 }
 
 /**
- * A `gh` refusal that means auto-merge was never armed in the first place —
- * there is nothing to disarm, so the PR is already in the un-armed posture
- * the guard wants. Distinguishing this from a genuine disarm failure is
- * load-bearing: an armed PR that could not be disarmed is a blocker, while
- * a never-armed PR is the desired end state.
- */
-const NOT_ARMED = /not enabled|isn't enabled|is not set|no auto-?merge/i;
-
-/**
- * Disarm GitHub native auto-merge for the PR — the race-free response to the
- * first red. Never throws.
- *
- * @param {{ prRef: string, cwd: string, spawnFn?: Function }} opts
- * @returns {{ disarmed: boolean, alreadyUnarmed: boolean, detail: string }}
- *   `disarmed` is true when the PR is (now) un-armed; `alreadyUnarmed`
- *   distinguishes "there was nothing armed" from an executed disarm.
- */
-export function disarmAutoMerge({ prRef, cwd, spawnFn }) {
-  let result;
-  try {
-    result = spawnChild('gh', ['pr', 'merge', prRef, '--disable-auto'], {
-      run: spawnFn,
-      cwd,
-    });
-  } catch (err) {
-    return {
-      disarmed: false,
-      alreadyUnarmed: false,
-      detail: `gh-spawn-error: ${err?.message ?? err}`,
-    };
-  }
-  const status = result?.status ?? 1;
-  const stderr = String(result?.stderr ?? '').trim();
-  if (status === 0) {
-    return { disarmed: true, alreadyUnarmed: false, detail: 'disarmed' };
-  }
-  if (NOT_ARMED.test(stderr)) {
-    return {
-      disarmed: true,
-      alreadyUnarmed: true,
-      detail: `auto-merge was not armed: ${stderr.slice(0, 160)}`,
-    };
-  }
-  return {
-    disarmed: false,
-    alreadyUnarmed: false,
-    detail: `gh-exit-${status}: ${stderr.slice(0, 200)}`,
-  };
-}
-
-/**
- * Read the CI failure digest for a scope, or `null` when none exists (or it
- * is unreadable / malformed — an unparseable digest carries no enforceable
- * evidence, so it is treated as absent).
+ * The digest, or `null`; a malformed one carries no evidence and counts as
+ * absent.
  *
  * @param {{ storyId?: number|string|null, tempRoot: string, cwd: string }} opts
  * @returns {object|null}
@@ -286,8 +178,7 @@ export function readCiDigest({ storyId = null, tempRoot, cwd }) {
 }
 
 /**
- * Retire the digest for a scope — the red it recorded was resolved at
- * source. Best-effort; returns the paths removed (or `null`).
+ * Retire the digest once its red is resolved.
  *
  * @param {{ storyId?: number|string|null, tempRoot: string, cwd: string }} opts
  * @returns {{ jsonPath: string, mdPath: string } | null}
@@ -301,9 +192,7 @@ export function retireCiDigest({ storyId = null, tempRoot, cwd }) {
 }
 
 /**
- * Condense a digest into the record kept in a successor digest's
- * `priorReds`, so a second red on a new head never silently erases the
- * evidence of an unresolved earlier one.
+ * Summary kept in `priorReds` so a new red never erases an unresolved one.
  */
 function summarizeRed(digest) {
   return {
@@ -316,9 +205,7 @@ function summarizeRed(digest) {
 }
 
 /**
- * Carry forward the unresolved reds an incoming digest must not lose. A
- * re-red on the SAME head is the same unresolved red observed again, so it
- * is not duplicated into the history.
+ * A re-red on the same head is not duplicated into history.
  */
 function carryPriorReds(previous, headSha) {
   if (!previous) return [];
@@ -330,10 +217,6 @@ function carryPriorReds(previous, headSha) {
   return history.slice(-MAX_PRIOR_REDS);
 }
 
-/**
- * Render the human-readable digest. Names the head SHA, because that is the
- * field the green path adjudicates on.
- */
 function renderDigestMarkdown(digest, failures) {
   return [
     `# CI failure digest — Story #${digest.storyId} (PR #${digest.prNumber})`,
@@ -373,9 +256,7 @@ function renderDigestMarkdown(digest, failures) {
 }
 
 /**
- * Write the CI failure digest (`.json` + `.md`) for a red watch. Returns
- * the two paths written, or `null` when no story id was supplied (the
- * digest is scoped by filename and has nothing to key on).
+ * Write the digest (`.json` + `.md`); `null` without a Story id.
  *
  * @param {object} opts
  * @param {number|string|null} [opts.storyId] The v2 delivery scope.
@@ -387,9 +268,7 @@ function renderDigestMarkdown(digest, failures) {
  * @param {string} opts.prRef
  * @param {Function} [opts.checkRunFn]
  * @param {Function} [opts.logTailFn]
- * @param {Function} [opts.spawnFn] Child runner handed to the two default
- *   `gh` probes, so their real bodies can be exercised without shelling out.
- *   Ignored when `checkRunFn` / `logTailFn` are replaced outright.
+ * @param {Function} [opts.spawnFn] Child runner for the default `gh` probes.
  * @returns {{ jsonPath: string, mdPath: string } | null}
  */
 export function writeCiDigest({
@@ -438,18 +317,9 @@ export function writeCiDigest({
 }
 
 /**
- * Stamp the one-rerun allowance on the scope's digest (Story #5343).
- *
- * Called by `file-ci-gap.js` after it has filed the intake issue, so the
- * allowance exists only where the evidence the filing carries does. It is
- * keyed on the digest's own head SHA — the head the red was recorded
- * against — so an allowance can never be honoured on a later head it was not
- * earned for.
- *
- * Best-effort and non-throwing: a digest that cannot be re-read or re-written
- * simply records no allowance, and the guard keeps blocking. Returns the
- * recorded allowance, or `null` when none was written (no digest, an
- * ineligible verdict, or an unresolved head SHA).
+ * Stamp the one-rerun allowance, called by `file-ci-gap.js` after filing.
+ * Keyed on the digest's own head SHA so it cannot apply to a later head.
+ * Non-throwing; `null` when nothing was written (the guard keeps blocking).
  *
  * @param {{
  *   storyId?: number|string|null,
@@ -488,10 +358,6 @@ export function recordRerunAllowance({
 }
 
 /**
- * The allowance a digest carries for `headSha`, or `null`. An allowance
- * recorded against a different head is not one: the red it was filed for is
- * not the red being adjudicated.
- *
  * @param {object|null} digest
  * @param {string|null} headSha
  * @returns {{ verdict: string, headSha: string } | null}
@@ -508,18 +374,10 @@ function allowanceFor(digest, headSha) {
 }
 
 /**
- * Adjudicate an all-green watch against any digest recorded for the scope.
+ * Adjudicate an all-green watch against the scope's digest (see header).
  *
  * @param {{ digest: object|null, headSha: string|null }} opts
  * @returns {{ verdict: 'clean'|'fix-at-source'|'rerun-permitted'|'rerun'|'unverifiable', reason: string }}
- *   - `clean`           — no digest: this delivery never went red.
- *   - `fix-at-source`   — the head SHA moved since the red; legal.
- *   - `rerun-permitted` — same head SHA, but `file-ci-gap.js` recorded a
- *                         `capacity` / `unreproducible-tier` verdict for it;
- *                         the one sanctioned rerun (Story #5343).
- *   - `rerun`           — green on the SAME head SHA; forbidden.
- *   - `unverifiable`    — an unresolved red with no head-SHA evidence either
- *                         side; fail closed and treat it as a rerun.
  */
 export function classifyGreenVerdict({ digest, headSha }) {
   if (!digest) return { verdict: 'clean', reason: 'no digest for this scope' };
@@ -531,8 +389,12 @@ export function classifyGreenVerdict({ digest, headSha }) {
     };
   }
   if (recorded === headSha) {
+    // Digests only record required checks.
     const allowance = allowanceFor(digest, headSha);
-    return allowance
+    return isRerunPermitted({
+      required: true,
+      allowanceRecorded: allowance !== null,
+    })
       ? {
           verdict: 'rerun-permitted',
           reason: `one rerun admitted: \`${allowance.verdict}\` verdict recorded for this head SHA (${headSha})`,
@@ -548,11 +410,7 @@ export function classifyGreenVerdict({ digest, headSha }) {
   };
 }
 
-/**
- * The failure signature an intake filing must carry (see `file-ci-gap.js`):
- * the first
- * distinctive line of the captured failed-job log.
- */
+/** First non-blank failed-log line: the signature an intake filing carries. */
 function failureSignature(digest) {
   const tail = String(digest?.logTail ?? '');
   const line = tail
@@ -563,8 +421,7 @@ function failureSignature(digest) {
 }
 
 /**
- * Render the rerun-violation report — used verbatim as the friction comment
- * body and, line by line, as the watcher's stderr report.
+ * The friction comment body, also the watcher's stderr report.
  *
  * @param {{ digest: object, headSha: string|null, prNumber: number, reason: string }} opts
  * @returns {string}
@@ -603,13 +460,9 @@ export function formatRerunViolation({ digest, headSha, prNumber, reason }) {
 }
 
 /**
- * Hard-stop the delivery: post the `friction` comment and flip the Story to
- * `agent::blocked`. Both halves are best-effort — a failure to reach GitHub
- * must not turn the block into a crash, and the watcher's non-zero exit is
- * what actually stops the delivery.
- *
- * Routed through `transitionTicketState` rather than a bare label write so
- * the Projects v2 column sync runs (Story #2548 / #4539).
+ * Post the `friction` comment and flip to `agent::blocked` (via
+ * `transitionTicketState` so the board column syncs). Best-effort: the
+ * watcher's non-zero exit is what actually stops delivery.
  *
  * @param {{
  *   storyId: number|string,

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

@@ -1,42 +1,8 @@
 /**
- * lib/orchestration/code-review.js — In-process Code Review module.
- *
- * Story #1155 (Epic #1142, 5.40.0) — extracted the helper-driven
- * `epic-code-review` invocation into a callable module so the
- * `/mandrel-deliver` runner can run Phase D without spawning a child
- * process or routing through an LLM-driven helper.
- *
- * Story #2831 (Epic #2815, Pluggable Code Review) — refactored to load
- * the review provider through `review-provider-factory`, call the
- * adapter's `runReview()` to collect a `Finding[]`, render the
- * structured-comment body via `findings-renderer`, and post the
- * comment through the GitHub provider here (the adapter is post-free
- * by design).
- *
- * v2.0.0 removed the Epic tier. The Epic-scope envelope and the
- * Epic-scoped `code-review.start` / `.end` lifecycle emits (whose schema
- * requires `epicId`) went with it; Story scope is the only scope. Story #5024
- * deleted those schemas along with the bus that was their only publish path.
- *
- * Public API:
- *   - `runCodeReview({ ticketId, headRef, provider, logger, ... })` →
- *       `{ status, severity, posted, report, halted, blockerReason }`.
- *
- * Behaviour:
- *   - Loads the configured review adapter via the factory; defaults to
- *     a single `native` chain entry when `delivery.codeReview.providers`
- *     is unset or empty.
- *   - Always posts the unified `verification-results` structured comment on
- *     the target issue/PR (the adapter never posts; the orchestrator owns
- *     persistence). Story #4411 (Epic #4405) unified the former
- *     `code-review` and `audit-results` findings contracts into this one
- *     `verification-results` marker.
- *   - Treats severity.critical > 0 as a halting blocker — the merged
- *     `/mandrel-deliver` runner consults `halted` and refuses to advance
- *     to Phase E (retro) when set.
- *
- * Halting on critical findings is the in-process replacement for the
- * helper's "operator must remediate before /mandrel-deliver" gate.
+ * lib/orchestration/code-review.js — in-process Story-scope code review:
+ * load the configured review adapter (default `native`), collect its
+ * `Finding[]`, render and post the `verification-results` comment (adapters
+ * never post), and report `halted` on any surviving critical finding.
  */
 
 import { hasSurvivingCritical } from '../audit-suite/findings.js';
@@ -56,26 +22,16 @@ import { createReviewProvider } from './review-providers/review-provider-factory
 import { upsertStructuredComment } from './ticketing.js';
 
 /**
- * Review depth tiers, ordered light → standard → deep. The depth is resolved
- * by the shared {@link resolveDepth} resolver from two observable properties of
- * the diff under review — whether its changed files touch a registered
- * sensitive path ({@link deriveChangeLevel}) and their mechanical count — then
- * threaded into the review provider's `runReview` input so a sensitive *or*
- * wide-footprint change gets a deeper pass than a small, unremarkable one.
- * Depth is an **input** signal only — it never changes the
- * `{ status, severity, posted, report, halted, blockerReason }` output
- * envelope nor the `verification-results` structured-comment body (Story #3876,
- * extended by Story #3938; re-based off the diff by Story #4542).
+ * Review depth (light → standard → deep), from the diff's sensitivity and
+ * width. An input to `runReview` only; never changes the output envelope or
+ * the posted comment.
  *
  * @typedef {import('./review-depth.js').ReviewDepth} ReviewDepth
  */
 
 /**
- * Resolve the base ref used when a caller omits `baseRef`. Remote-qualified,
- * never the bare branch name — a caller that does not name a base must not
- * silently inherit the local ref's drift (Story #5325). An unfetched remote
- * then yields an unenumerable diff, which every downstream consumer already
- * fails safe on, instead of a confidently-wrong wide one.
+ * Default base is remote-qualified so it cannot inherit local-ref drift; an
+ * unfetched remote yields an unenumerable diff, which consumers fail safe on.
  */
 function resolveConfigBase(config) {
   return remoteBaseRef(config?.project?.baseBranch ?? 'main');
@@ -89,9 +45,6 @@ function resolveCommentTargetId(commentTargetId, fallback) {
 }
 
 /**
- * Resolve the Story-scope envelope from the parameterized
- * `{ scope: 'story', ticketId, baseRef, headRef, commentTargetId }` shape.
- *
  * @returns {{
  *   scope: 'story',
  *   ticketId: number,
@@ -123,40 +76,15 @@ function resolveStoryScope(opts, config) {
   };
 }
 
-/**
- * Resolve the scope envelope
- * (`{ scope, ticketId, baseRef, headRef, commentTargetId }`). v2.0.0
- * removed the Epic tier, so `'story'` is the only scope.
- */
+/** `'story'` is the only scope. */
 function resolveScopeEnvelope(opts, config) {
   return resolveStoryScope(opts, config);
 }
 
 /**
- * In-process wrapper that the `/mandrel-deliver` runner and the
- * `/single-story-deliver` close path consume.
- *
- * Story #2252 — emits `code-review.start` immediately on entry and
- * `code-review.end` immediately before returning the envelope (success
- * or halt). On runner throw, emits `code-review.end` with the canonical
- * structure (`status: 'invalid'`) before re-throwing so the ledger
- * always carries the closing boundary.
- *
- * Story #2831 — the runner loads its adapter through the factory; the
- * `reviewProvider` opt overrides the factory for tests. Severity is
- * derived from the `Finding[]` returned by the adapter (no separate
- * severity field on the runner result).
- *
- * Story #2839 (Epic #2815) — the Story closer requests a Story-scope
- * review against `main`, posts the structured findings comment to the PR
- * (via `commentTargetId`), and surfaces critical findings to the caller
- * as `halted: true`.
- *
- * Argument shape:
- *   `{ ticketId, baseRef, headRef, [commentTargetId], provider }`
- *   `baseRef` defaults to the project base branch; `headRef` is required.
- *   `commentTargetId` overrides the post target (e.g. PR number) while
- *   `ticketId` continues to label the rendered header ("Story #N").
+ * Run a Story-scope review. `headRef` is required; `baseRef` defaults to
+ * the remote base branch; `commentTargetId` (e.g. a PR number) overrides
+ * the post target while `ticketId` still labels the header.
  *
  * @param {{
  *   scope?: 'story',
@@ -188,12 +116,7 @@ function resolveScopeEnvelope(opts, config) {
  *   blockerReason: string|null,
  * }>}
  */
-/**
- * Resolve the human-facing provider name from the resolved code-review
- * config. Multi-entry chains render as `chain[a,b,...]`; a single-entry
- * chain (including the unset/empty default) renders that entry's name;
- * everything else falls back to `'native'`.
- */
+/** Display name: the single entry's name, `chain[a,b]`, or `'native'`. */
 function resolveProviderName(codeReviewConfig) {
   const providers =
     codeReviewConfig && Array.isArray(codeReviewConfig.providers)
@@ -209,17 +132,10 @@ function resolveProviderName(codeReviewConfig) {
 }
 
 /**
- * Resolve the change set the depth derivation reads (Story #4593).
- *
- * `opts.changedFiles` is an injection with three distinct states,
- * and the difference is load-bearing: an **array** is the change set to use
- * verbatim; an explicit **null** is a caller (`runStoryReviewCore`) reporting
- * that it already tried and the diff is unenumerable — re-running git here would
- * only fail again, so it degrades straight to the fail-safe tier; **absent**
- * means no caller enumerated at all, so the shared {@link computeChangeSet}
- * enumerator runs as the fallback (standalone CLI use). On the close path the
- * spine always injects, so the diff is enumerated exactly once per delivery and
- * this pillar can never disagree with the lens pass about what changed.
+ * `opts.changedFiles` has three states: an array is used verbatim; `null`
+ * means the caller already found the diff unenumerable (fail-safe tier, no
+ * retry); absent means enumerate here. The close path always injects, so
+ * review and lens pass agree on what changed.
  */
 function resolveInjectedChangedFiles({ opts, baseRef, headRef }) {
   if (opts.changedFiles === undefined) {
@@ -230,12 +146,8 @@ function resolveInjectedChangedFiles({ opts, baseRef, headRef }) {
 }
 
 /**
- * Build the provider `runReview` input, resolving the review depth from the
- * diff under review: its changed files derive the change level (sensitive path
- * touched or not — Story #4542) and their count supplies the width. The depth
- * is an input-only signal (light → standard → deep) and never touches the
- * output envelope or the posted comment. An unenumerable diff → `standard`.
- * Story #4075 — extracted from `runCodeReview`.
+ * Build the `runReview` input with its depth; an unenumerable diff yields
+ * `standard`.
  */
 function buildReviewInput({ opts, scope, ticketId, baseRef, headRef }) {
   const changedFiles = resolveInjectedChangedFiles({ opts, baseRef, headRef });
@@ -243,9 +155,7 @@ function buildReviewInput({ opts, scope, ticketId, baseRef, headRef }) {
     typeof opts.changedFileCount === 'number'
       ? opts.changedFileCount
       : (changedFiles?.length ?? null);
-  // v2 Stage 2: review depth uses DEFAULT_DIFF_WIDTH (mechanical file count
-  // of the diff under review). It is deliberately decoupled from the
-  // planning model-capacity advisory (`DEFAULT_MODEL_CAPACITY`).
+  // Width is the diff's file count, decoupled from planning model capacity.
   const { level } = deriveChangeLevel({ changedFiles });
   const depth = resolveDepth({
     derivedLevel: level,
@@ -262,10 +172,7 @@ function buildReviewInput({ opts, scope, ticketId, baseRef, headRef }) {
 }
 
 /**
- * Feature-detect manual-prompt providers (Story #2871). Legacy
- * single-adapter providers don't carry `getPromptMessages`, so the
- * empty-array fallback keeps the old snapshot byte-stable; a throw is
- * logged and degraded to empty.
+ * Optional `getPromptMessages`; absent or throwing yields `[]`.
  */
 async function resolvePromptMessages(reviewProvider, reviewInput, logger) {
   if (typeof reviewProvider.getPromptMessages !== 'function') return [];
@@ -283,9 +190,7 @@ async function resolvePromptMessages(reviewProvider, reviewInput, logger) {
 }
 
 /**
- * Upsert the rendered report as a structured comment. Posting failure is
- * non-fatal: it is logged and surfaced via `posted: false`. Story #4075 —
- * extracted from `runCodeReview`.
+ * Posting failure is non-fatal and surfaces as `posted: false`.
  */
 async function postReviewComment({
   upsertCommentFn,
@@ -319,12 +224,6 @@ async function postReviewComment({
   }
 }
 
-/**
- * Run the review pipeline (resolve provider → runReview → prompt messages →
- * render → post comment) and shape the `status: 'ok'` result. Pure of the
- * lifecycle-boundary concern — `runCodeReview` owns the start/end emit pair.
- * Story #4075 — extracted to keep both bodies below the CC must-fix band.
- */
 async function executeReviewPipeline({ opts, config, envelope }) {
   const {
     provider,
@@ -366,7 +265,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
     logger,
   );
 
-  // Story #4839 — degraded gates ride beside the findings, never inside them.
+  // Degraded gates ride beside the findings, never inside them.
   const degradations = await collectProviderDegradations(
     reviewProvider,
     logger,
@@ -413,8 +312,5 @@ export async function runCodeReview(opts = {}) {
   const config = resolveConfigFn();
   const envelope = resolveScopeEnvelope(opts, config);
 
-  // No lifecycle-bus emit: the `code-review.start` / `.end` ledger pair was
-  // Epic-scoped (its schema requires `epicId`), and v2.0.0 removed the Epic
-  // tier. Story-scope review sits outside the lifecycle ledger entirely.
   return executeReviewPipeline({ opts, config, envelope });
 }