mandrel 2.30.0 → 2.32.0

package/.agents/scripts/lib/orchestration/lint-baseline-service.js

@@ -1,114 +0,0 @@
-/**
- * lib/orchestration/lint-baseline-service.js
- *
- * Captures the lint baseline (see `lint-baseline.js capture`). Extracted
- * from the inline implementation that used to live in the deleted
- * `dispatch-engine.js` entry seam so the coordinator no longer reaches into
- * `node:child_process` or `node:fs` directly. Tests can exercise the service with a stubbed exec
- * adapter and no filesystem interaction.
- */
-
-import defaultFs from 'node:fs';
-import path from 'node:path';
-import { getBaselines, getPaths, PROJECT_ROOT } from '../config-resolver.js';
-
-/**
- * Shape of the exec adapter passed into {@link LintBaselineService}.
- *
- * Implementations may be sync (e.g. `execFileSync`) or async; the service
- * always `await`s the return value so either works.
- *
- * @typedef {(file: string, args: string[], options?: object) => (void | Promise<void>)} LintBaselineExec
- */
-
-/**
- * Minimal logger shape consumed by {@link LintBaselineService}. Matches the
- * surviving `lib/Logger.js` surface (single-argument message form).
- *
- * @typedef {object} LintBaselineLogger
- * @property {(msg: string) => void} info
- * @property {(msg: string) => void} warn
- */
-
-/**
- * Outcome of {@link LintBaselineService#capture}.
- *
- * @typedef {object} LintBaselineCaptureResult
- * @property {boolean} skipped                   True when the baseline file already existed on disk.
- * @property {boolean} [captured]                True when the exec adapter ran and succeeded.
- * @property {string} [error]                    Error message when the exec adapter threw (still non-fatal).
- */
-
-export class LintBaselineService {
-  /**
-   * @param {object} deps
-   * @param {LintBaselineExec} deps.exec           Injected exec adapter — invoked with `(file, args, options)`.
-   * @param {LintBaselineLogger} deps.logger       Logger for skip / capture / failure messages.
-   * @param {object} deps.settings                 `.agentrc.json` `settings` block.
-   *   The baseline artifact path is resolved via
-   *   `getBaselines(settings).lint.path` (default
-   *   `baselines/lint.json`); operators override under
-   *   `delivery.quality.gates.lint.baselinePath`.
-   *   `scriptsRoot` is resolved via `getPaths(settings)`
-   *   (lives at `project.paths.scriptsRoot` post-Epic #773 Story 9).
-   * @param {typeof import('node:fs')} [deps.fs]   Optional `fs` module (defaults to `node:fs`). Kept injectable so unit tests can assert no real-disk access.
-   */
-  constructor({ exec, logger, settings, fs = defaultFs }) {
-    this.exec = exec;
-    this.logger = logger;
-    this.settings = settings;
-    this.fs = fs;
-  }
-
-  /**
-   * Capture (or skip) the lint baseline for the given Epic branch.
-   *
-   * Behaviour:
-   * - If the baseline artifact already exists, log a skip and return
-   *   `{ skipped: true }` — **no exec call is made**.
-   * - Otherwise invoke the injected exec adapter to run
-   *   `node <scriptsRoot>/lint-baseline.js capture`.
-   * - Exec failures are logged at `warn` and swallowed — baseline capture
-   *   is advisory and must never break the dispatch cycle.
-   *
-   * @param {string} epicBranch  Epic branch name (used for logging only).
-   * @returns {Promise<LintBaselineCaptureResult>}  Resolution of the capture attempt.
-   */
-  async capture(epicBranch) {
-    const { settings, logger, exec, fs } = this;
-    // `settings` is the legacy-shim view (`{ paths, quality, ... }`). The
-    // post-reshape accessors read `project.paths` and `delivery.quality`;
-    // the shim's pointers are reference-equal to the canonical blocks, so
-    // re-wrap here.
-    const canonical = {
-      project: { paths: settings?.paths },
-      delivery: { quality: settings?.quality },
-    };
-    const lintBaselinePath = getBaselines(canonical).lint.path;
-    const absPath = path.resolve(PROJECT_ROOT, lintBaselinePath);
-
-    if (fs.existsSync(absPath)) {
-      logger.info('Lint baseline already exists, skipping capture.');
-      return { skipped: true };
-    }
-
-    logger.info(`Capturing lint baseline on ${epicBranch}...`);
-    const scriptsRoot = getPaths(canonical).scriptsRoot;
-    try {
-      await exec(
-        'node',
-        [path.join(PROJECT_ROOT, scriptsRoot, 'lint-baseline.js'), 'capture'],
-        {
-          cwd: PROJECT_ROOT,
-          encoding: 'utf8',
-          stdio: 'inherit',
-          shell: false,
-        },
-      );
-      return { skipped: false, captured: true };
-    } catch (err) {
-      logger.warn(`Lint baseline capture failed (non-fatal): ${err.message}`);
-      return { skipped: false, captured: false, error: err.message };
-    }
-  }
-}

package/.agents/scripts/lib/orchestration/pr-base-guard.js

@@ -1,37 +0,0 @@
-// .agents/scripts/lib/orchestration/pr-base-guard.js
-/**
- * pr-base-guard.js — refuse to open a pull request for a Story that still
- * carries an Epic/parent footer (pre-v2 hierarchy). v2 Stories are
- * standalone; Epic-attached bodies are a forward-cutover refusal, not a
- * redirect onto `epic/<N>`.
- */
-
-import { resolveStoryHierarchy } from '../story-lifecycle.js';
-
-/**
- * Inspect a Story's body for an Epic/parent reference and refuse any PR
- * when one is present. Callers must re-plan Epic-attached tickets as v2
- * Stories before delivering.
- *
- * @param {object} args
- * @param {number} args.storyId — Story ticket id (used in the error
- *   message so the operator can grep the failing surface).
- * @param {string|null|undefined} args.storyBody — raw Story body markdown.
- *   When falsy, the guard short-circuits (no body → nothing to enforce).
- * @param {string} args.baseBranch — retained for call-site compatibility;
- *   unused once an Epic/parent footer is detected (any base is refused).
- * @throws {Error} when the Story body declares an Epic or Parent footer.
- */
-export function assertStoryPrBaseAllowed({
-  storyId,
-  storyBody,
-  baseBranch: _baseBranch,
-}) {
-  if (!storyBody) return;
-  const { epicId } = resolveStoryHierarchy(storyBody);
-  if (epicId == null) return;
-  throw new Error(
-    `Story #${storyId} still declares Epic/Parent #${epicId}. ` +
-      'v2 delivery is Story-only — re-plan as a standalone Story (no Epic footer) before opening a PR.',
-  );
-}

package/.agents/scripts/lib/orchestration/resolves-token.js

@@ -1,127 +0,0 @@
-/**
- * resolves-token.js — single source of truth for the `(resolves #N)`
- * Story-merge integration marker.
- *
- * Background. The deleted `story-close.js` integrated each Story branch into its
- * parent Epic branch with `git merge --no-ff` and a Conventional-Commit
- * subject that carries a ` (resolves #<storyId>)` trailer. That trailer is
- * the *durable* proof a Story landed on `epic/<id>`: the local/remote
- * Story branch is deleted right after the merge, and a later rebase or
- * force-push can drop the Story tip off the merged history, so several
- * recovery and telemetry paths grep the Epic log for the trailer rather
- * than relying on a branch ref.
- *
- * Before this module, six call sites each re-derived the marker inline —
- * three subtly different regexes (`/\(resolves #(\d+)\)/i`,
- * `/\(resolves\s+#\d+\)/i`) and three subtly different `git log --grep`
- * argument shapes (plain `resolves #N`, and the boundary-safe
- * `-E --grep=resolves #N( |\)|$)`). This module collapses them into one
- * token vocabulary with no change to the *emitted* text, so in-flight
- * peer closes that already wrote ` (resolves #N)` keep matching.
- *
- * Exports:
- *   - `resolvesToken(storyId)`       — the ` (resolves #<id>)` suffix that
- *                                      merge-subject.js appends to the
- *                                      merge-commit subject.
- *   - `RESOLVES_TRAILER_RE`          — anchored, capturing regex matching
- *                                      `(resolves #<digits>)` in a subject.
- *   - `parseResolvesStoryId(subject)`— parse the Story id out of a subject,
- *                                      or `null` when no trailer is present.
- *   - `resolvesGrepArgs(storyId)`    — the boundary-safe `git log` argument
- *                                      list (`['-E', '--grep=...']`) that
- *                                      matches the trailer for exactly this
- *                                      Story id and not a longer id that
- *                                      shares the prefix.
- *   - `resolvesOrRefsGrepArgs(storyId)` — like `resolvesGrepArgs` but matches
- *                                      the fully-parenthesized `(resolves #N)`
- *                                      *or* `(refs #N)` integration marker, for
- *                                      the ref-independent already-merged scan
- *                                      in `story-close-recovery.js`.
- *
- * Pure module — no I/O, no git spawns. Callers own the spawn.
- */
-
-/**
- * Build the durable Story-merge marker suffix.
- *
- * The leading space is intentional: the marker is appended to a
- * Conventional-Commit subject (`<type>(<scope>): <title>`) and the space
- * separates the title from the trailer. This is the exact text peer
- * closes already emit — do not change it without a coordinated cutover of
- * every grep below.
- *
- * @param {number|string} storyId
- * @returns {string} ` (resolves #<storyId>)`
- */
-export function resolvesToken(storyId) {
-  return ` (resolves #${storyId})`;
-}
-
-/**
- * Match `(resolves #<digits>)` in a commit subject. Anchored to the
- * parenthesized form because that is the canonical Story-merge trailer
- * shape — a bare `resolves #N` mentioned in prose elsewhere in the
- * message must not win over the trailer. Capturing group 1 is the
- * Story id digits.
- *
- * Case-insensitive to tolerate a hand-authored `(Resolves #N)`; the
- * runtime always emits lower-case.
- *
- * @type {RegExp}
- */
-export const RESOLVES_TRAILER_RE = /\(resolves #(\d+)\)/i;
-
-/**
- * Parse the Story id out of a commit subject's `(resolves #N)` trailer.
- * Returns the integer id, or `null` when the subject carries no trailer.
- *
- * @param {string} subject
- * @returns {number|null}
- */
-export function parseResolvesStoryId(subject) {
-  if (typeof subject !== 'string' || subject.length === 0) return null;
-  const m = RESOLVES_TRAILER_RE.exec(subject);
-  return m ? Number.parseInt(m[1], 10) : null;
-}
-
-/**
- * Build the boundary-safe `git log --grep` argument list that matches the
- * `(resolves #<storyId>)` trailer for *exactly* this Story id.
- *
- * The trailing `( |\)|$)` alternation is what makes the match boundary
- * safe: `resolves #12` must not match a subject that names `#1234`. The
- * canonical merge subject closes the trailer with `)`, so the `\)` branch
- * is the common hit; the ` ` and `$` branches tolerate non-canonical
- * placements (trailer mid-subject, or unterminated at end-of-line).
- *
- * Returned as an argument array (not a string) so callers splat it
- * straight into a `git log` spawn alongside their own ref / format flags.
- * `-E` enables the POSIX-extended alternation.
- *
- * @param {number|string} storyId
- * @returns {string[]} `['-E', '--grep=resolves #<storyId>( |\\)|$)']`
- */
-export function resolvesGrepArgs(storyId) {
-  return ['-E', `--grep=resolves #${storyId}( |\\)|$)`];
-}
-
-/**
- * Build the boundary-safe `git log --grep` argument list that matches the
- * fully-parenthesized `(resolves #<storyId>)` *or* `(refs #<storyId>)`
- * integration marker for *exactly* this Story id.
- *
- * Unlike {@link resolvesGrepArgs} (which keys off a trailing space / paren /
- * end boundary), this matcher requires the canonical parenthesized form on
- * both sides — `\(...\)` — because it is the ref-independent already-merged
- * signal: when both Story refs are reaped, `story-close-recovery.js` scans
- * the Epic history for the integration commit whose subject carries the
- * trailer. The closing `\)` is the boundary that prevents `#3327` matching
- * `(resolves #33270)`. `refs` is accepted alongside `resolves` because an
- * agent-authored implementation commit references the Story via `(refs #N)`.
- *
- * @param {number|string} storyId
- * @returns {string[]} `['-E', '--grep=\\((resolves|refs) #<storyId>\\)']`
- */
-export function resolvesOrRefsGrepArgs(storyId) {
-  return ['-E', `--grep=\\((resolves|refs) #${storyId}\\)`];
-}

package/.agents/scripts/lib/orchestration/spec-section-validator.js

@@ -1,130 +0,0 @@
-/**
- * spec-section-validator.js — Tech Spec post-authoring section gate.
- *
- * `/plan` Phase 7 authors a Tech Spec from documentation and the Epic body.
- * Phase 8.3 (Holistic Consolidation) then reconciles the draft ticket array
- * against the Tech Spec's `## Delivery Slicing` section, which the
- * decompose-author skill uses as the capability-boundary anchor. When the
- * authored Tech Spec omits that section, the consolidation pass runs against
- * a void and produces groupings that reflect technical shape (cron jobs
- * together) rather than capability boundaries — observed on Epic #18 in
- * `dsj1984/athportal` (planned with v1.54.0).
- *
- * `validateSpecSections` parses a Tech Spec body for the required
- * `## Delivery Slicing` heading (accepting the casing/wording variants
- * below) and returns a deterministic `{ ok, missing[] }` envelope.
- *
- * Story #4403 (Finding 3): this gate used to be run by a standalone
- * `epic-plan-spec-validate.js` CLI as a separate Phase 7.5 workflow step —
- * but by the time the documented ordering ran it, the Phase 7 persist path's
- * `cleanupPhaseTempFiles` had already deleted the temp `techspec.md` file the
- * gate read, so the "blocking gate" could never actually block. The CLI is
- * retired; `runSpecPhase` (`phases/run-spec-phase.js`) now calls
- * `validateSpecSections` directly against the in-memory authored content as
- * part of its input validation, before any GitHub mutation. This is the
- * Phase 8-side counterpart to the retired Phase 6 Epic Clarity Gate —
- * same detect-then-prompt pattern, one phase later, but a hard gate
- * (fail closed) rather than an advisory rubric.
- *
- * `validateSpecSections` and `formatMissingSectionMessage` are pure, I/O-free
- * helpers. `validateSpecFile` is a thin disk-reading convenience for callers
- * (tests, ad-hoc tooling) that hold a path rather than in-memory content.
- */
-
-import { readFile } from 'node:fs/promises';
-import { DELIVERY_SLICING_RE } from '../ticket-body-sections.js';
-
-/**
- * The single required Tech Spec section, with the heading variants the
- * Architect persona may emit. Matched case-insensitively against any
- * level-2 (`## `) heading.
- *
- *   - `## Delivery Slicing`   (canonical)
- *   - `## Delivery slicing`   (variant casing)
- *   - `## DELIVERY SLICING`   (variant casing)
- *   - `## Slicing`            (shorthand)
- */
-const REQUIRED_SECTIONS = Object.freeze([
-  {
-    name: 'Delivery Slicing',
-    /** Level-2 heading, allowing the `Delivery ` qualifier to be optional. */
-    re: DELIVERY_SLICING_RE,
-  },
-]);
-
-/**
- * Canonical names of the required sections, in document order. Exported so
- * callers (CLI, tests, downstream tooling) can iterate without re-deriving
- * the list.
- *
- * @type {readonly string[]}
- */
-export const REQUIRED_SECTION_NAMES = Object.freeze(
-  REQUIRED_SECTIONS.map((s) => s.name),
-);
-
-/**
- * Validate a Tech Spec body for the required post-authoring sections.
- *
- * @param {{ body: string }} [args]
- * @returns {{ ok: boolean, missing: string[], present: string[] }}
- *   `ok` is true when every required section heading is present. `missing`
- *   lists the canonical names of absent sections (empty when `ok`).
- *   `present` lists the canonical names that were found.
- */
-export function validateSpecSections({ body } = {}) {
-  const source = typeof body === 'string' ? body : '';
-
-  const present = [];
-  const missing = [];
-  for (const section of REQUIRED_SECTIONS) {
-    if (section.re.test(source)) {
-      present.push(section.name);
-    } else {
-      missing.push(section.name);
-    }
-  }
-
-  return { ok: missing.length === 0, missing, present };
-}
-
-/**
- * Validate an authored Tech Spec file for the required post-authoring
- * sections. Thin wrapper around `validateSpecSections` that owns the file
- * read so callers holding a path (rather than in-memory content) do not each
- * re-implement the read-then-validate sequence.
- *
- * @param {{ techspecPath: string }} args
- * @returns {Promise<{ ok: boolean, missing: string[], present: string[] }>}
- */
-export async function validateSpecFile({ techspecPath }) {
-  const body = await readFile(techspecPath, 'utf8');
-  return validateSpecSections({ body });
-}
-
-/**
- * Build the operator-facing failure message for a missing-section result.
- * Names each missing section and tells the operator whether to re-author the
- * spec or add the section by hand before continuing.
- *
- * @param {{ techspecPath: string, missing: string[] }} args
- * @returns {string}
- */
-export function formatMissingSectionMessage({ techspecPath, missing }) {
-  const list = missing.map((name) => `## ${name}`).join(', ');
-  return [
-    `[spec-section-validator] Tech Spec is missing required section(s): ${list}`,
-    `  Spec source: ${techspecPath}`,
-    '',
-    `  Phase 8 (decomposition) reconciles the draft ticket array against the`,
-    `  Tech Spec's "## Delivery Slicing" section — without it, the Phase 8.3`,
-    `  consolidation pass has no capability-boundary anchor and groups by`,
-    `  technical shape instead.`,
-    '',
-    '  To continue, do ONE of the following and re-run the Phase 7 persist step:',
-    `    1. Re-author the Tech Spec (re-run the Phase 7 spec-author step) so it`,
-    `       emits a "## Delivery Slicing" section, OR`,
-    `    2. Add a "## Delivery Slicing" section to the Tech Spec by hand,`,
-    `       describing the capability boundaries the work should be sliced along.`,
-  ].join('\n');
-}

package/.agents/scripts/lib/orchestration/story-close/emit-blocked.js

@@ -1,55 +0,0 @@
-/**
- * Best-effort blocked-close result helper shared by Story-scope review.
- *
- * @module lib/orchestration/story-close/emit-blocked
- */
-
-import { Logger } from '../../Logger.js';
-import { emitTerseResult } from '../../observability/terse-result.js';
-
-/**
- * Best-effort `story.blocked` lifecycle emit. The bus is optional and emit
- * failures are swallowed so the blocked result remains the caller-visible
- * outcome.
- */
-async function emitStoryBlockedSafe({ bus, storyId, reason, logger }) {
-  if (!bus) return;
-  try {
-    await bus.emit('story.blocked', {
-      storyId: Number(storyId),
-      reason: String(reason),
-    });
-  } catch (err) {
-    logger?.warn?.(
-      `[story-close] story.blocked emit failed for #${storyId} (swallowed): ${err?.message ?? err}`,
-    );
-  }
-}
-
-/**
- * @param {object} args
- * @returns {Promise<object>}
- */
-export async function emitBlockedCloseResult({
-  storyId,
-  phase,
-  reason,
-  extra = {},
-  bus = null,
-  progress,
-  blockedMessage,
-  logger = Logger,
-}) {
-  const result = { success: false, status: 'blocked', phase, reason, ...extra };
-  await emitStoryBlockedSafe({ bus, storyId, reason, logger });
-  // Story #4685 — full detail to a temp log; single summary line in its place.
-  emitTerseResult({
-    label: 'STORY CLOSE RESULT',
-    result,
-    scope: storyId,
-    summary: { storyId, status: 'blocked', phase, reason },
-    log: logger,
-  });
-  progress('BLOCKED', blockedMessage);
-  return result;
-}

package/.agents/scripts/lib/orchestration/story-close/phases/code-review.js

@@ -1,211 +0,0 @@
-/**
- * phases/code-review.js — Story-scope code-review phase
- * (Story #2840, Epic #2815 — Pluggable Code Review + Story-Level Review).
- *
- * Sits between the close-validation gate chain and merge in the deleted
- * pre-v2 Epic close path (`runStoryCloseLocked` / `locked-pipeline.js`,
- * merge target `epic/<id>`). The v2 `/deliver` path
- * (`single-story-close.js`) reviews `main`…`story-<id>` instead. The
- * configured ReviewProvider runs against the supplied base…head diff. The
- * unified `verification-results`
- * structured comment is posted to the Story issue (default
- * `commentTargetId === ticketId` inside `runCodeReview`). Outcomes:
- *
- *   - clean / non-critical findings → `{ blocked: null }`; the pipeline
- *     proceeds to merge.
- *   - critical findings              → `{ blocked: <envelope> }`; the
- *     pipeline short-circuits, the Story is not merged, and the CLI
- *     exits non-zero via `exitCode: 1` on the envelope.
- *   - adapter throw / wiring failure → `{ blocked: null }`; the close
- *     proceeds because the review surface is advisory for transport
- *     failures (the same posture refresh.js takes). A warn is logged.
- *
- * Bus contract: `runCodeReview` only emits lifecycle events for
- * `scope: 'epic'` (the `code-review.end` schema requires `epicId`
- * and the ledger only spans Epic lifecycles — see Story #2839 lock-in
- * in `code-review.js`). The Story-scope path here therefore does not
- * forward the bus, and `story.blocked` is emitted separately on the
- * critical-halt path so the Epic-scoped lifecycle ledger still sees
- * the Story drop out.
- *
- * The shared spine both close paths call `runCodeReview` through
- * (`runStoryReviewCore`, Story #3653) and the shift-left local-lens pass
- * (Epic #4405) live in `review-core.js` and `local-lens-review.js`
- * respectively (extracted by Story #4603). This module is the Epic-attached
- * phase entry point: it owns the advisory error posture and the
- * critical-halt → blocked-envelope translation, and nothing else.
- */
-
-import { Logger } from '../../../Logger.js';
-import { runCodeReview } from '../../code-review.js';
-import { summarizeDegradations } from '../../review-providers/degraded-gates.js';
-import { emitBlockedCloseResult } from '../emit-blocked.js';
-import { runLocalLensReview } from './local-lens-review.js';
-import { runStoryReviewCore } from './review-core.js';
-
-/**
- * Read a review envelope's severity counts, tolerating the partial envelope a
- * misbehaving provider adapter can return. Pure.
- *
- * @param {object|null|undefined} reviewResult
- * @returns {{ critical: number, high: number, medium: number, suggestion: number }}
- */
-function resolveSeverity(reviewResult) {
-  return (
-    reviewResult?.severity ?? {
-      critical: 0,
-      high: 0,
-      medium: 0,
-      suggestion: 0,
-    }
-  );
-}
-
-/**
- * Collect the extra fields for the code-review-critical blocked envelope. Pure.
- *
- * @param {{ storyId: number, reviewResult: object }} args
- * @returns {object}
- */
-function buildCodeReviewBlockedExtra({ storyId, reviewResult }) {
-  return {
-    storyId,
-    blockerReason: reviewResult?.blockerReason ?? null,
-    severity: resolveSeverity(reviewResult),
-    posted: reviewResult?.posted ?? false,
-    exitCode: 1,
-  };
-}
-
-/**
- * Render the operator-facing one-line summary of a completed (non-halting)
- * review. Pure.
- *
- * @param {object} reviewResult
- * @returns {string}
- */
-function formatReviewSummary(reviewResult) {
-  const { high, medium, suggestion } = resolveSeverity(reviewResult);
-  const posted = reviewResult?.posted ?? false;
-  // Story #4839 — `degraded` is always stated: an absent degradation line must
-  // never be the way an operator concludes that every gate ran.
-  const degraded = summarizeDegradations(reviewResult?.degradations);
-  return `Review complete — high=${high} medium=${medium} suggestion=${suggestion} degraded=${degraded} (posted=${posted}).`;
-}
-
-/**
- * Run the shared review spine, absorbing an adapter / wiring failure into this
- * phase's advisory posture: the review is best-effort when the provider cannot
- * complete, and the gates already vouched for the diff at this point.
- *
- * @param {object} args Spine arguments (see {@link runStoryReviewCore}).
- * @returns {Promise<object|null>} The review envelope, or `null` when the
- *   review threw and the close should proceed unblocked.
- */
-async function invokeReviewCore(args) {
-  try {
-    return await runStoryReviewCore(args);
-  } catch (err) {
-    Logger.warn?.(
-      `[story-close] ⚠️ code-review phase failed (continuing without blocker): ${err?.message ?? err}`,
-    );
-    return null;
-  }
-}
-
-/**
- * Translate a halting (critical-findings) review into the blocked envelope the
- * caller returns verbatim, emitting `story.blocked` onto the bus on the way.
- *
- * @param {{
- *   storyId: number,
- *   reviewResult: object,
- *   bus: { emit: Function }|null,
- *   progress: (tag: string, msg: string) => void,
- * }} args
- * @returns {Promise<object>} The blocked envelope.
- */
-async function emitCriticalBlock({ storyId, reviewResult, bus, progress }) {
-  const { critical } = resolveSeverity(reviewResult);
-  return emitBlockedCloseResult({
-    storyId,
-    phase: 'closing',
-    reason: 'code-review-critical',
-    extra: buildCodeReviewBlockedExtra({ storyId, reviewResult }),
-    bus,
-    progress,
-    blockedMessage: `Story #${storyId} blocked: code-review reported ${critical} critical blocker(s).`,
-    logger: Logger,
-  });
-}
-
-/**
- * Run a Story-scope code review against the supplied base…head diff
- * (v2: `main`…`story-<id>` via `single-story-close.js`; pre-v2 Epic
- * close: `epic/<id>`…`story-<id>`) and post the structured
- * `code-review` comment to the Story issue. Returns `{ blocked }` where
- * `blocked` is either `null` (caller proceeds to open/merge the PR) or the
- * blocked-envelope (caller returns it verbatim and the CLI exits 1).
- *
- * Review depth is derived inside `runCodeReview` from this Story's own base…head
- * diff — a narrow change touching a registered sensitive path earns `deep`, a
- * small change touching none gets `light`, a wide diff earns `deep` on size, and
- * an unenumerable diff resolves `standard` (Story #4542). Depth is input-only:
- * it never changes `{ blocked }` or the posted comment.
- *
- * @param {{
- *   storyId: number|string,
- *   baseBranch: string,
- *   storyBranch: string,
- *   provider: object,
- *   bus: { emit: Function }|null,
- *   progress: (tag: string, msg: string) => void,
- *   runCodeReviewFn?: typeof runCodeReview,
- *   runLocalLensReviewFn?: typeof runLocalLensReview,
- * }} args
- * @returns {Promise<{ blocked: object|null, localLensReview?: object }>}
- *   `localLensReview` carries the Story-scope local-lens pass outcome
- *   (Epic #4405, Story #4409) when the review completed; it is absent only when
- *   the whole review phase threw (advisory failure).
- */
-export async function runStoryCodeReview({
-  storyId,
-  baseBranch,
-  storyBranch,
-  provider,
-  bus,
-  progress,
-  runCodeReviewFn = runCodeReview,
-  runLocalLensReviewFn = runLocalLensReview,
-}) {
-  const storyIdNum = Number(storyId);
-  progress(
-    'CODE-REVIEW',
-    `Running Story-scope review (${baseBranch}…${storyBranch})...`,
-  );
-
-  const reviewResult = await invokeReviewCore({
-    storyId: storyIdNum,
-    baseRef: baseBranch,
-    headRef: storyBranch,
-    provider,
-    progress,
-    runCodeReviewFn,
-    runLocalLensReviewFn,
-  });
-  if (reviewResult === null) return { blocked: null };
-
-  const localLensReview = reviewResult.localLensReview;
-  if (reviewResult.halted) {
-    const blocked = await emitCriticalBlock({
-      storyId: storyIdNum,
-      reviewResult,
-      bus,
-      progress,
-    });
-    return { blocked, localLensReview };
-  }
-
-  progress('CODE-REVIEW', formatReviewSummary(reviewResult));
-  return { blocked: null, localLensReview };
-}