mandrel 2.0.0 → 2.2.0

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

@@ -28,259 +28,111 @@
  * critical-halt path so the Epic-scoped lifecycle ledger still sees
  * the Story drop out.
  *
- * `runStoryReviewCore` is exported as the shared spine that the
- * `single-story-close` path imports, so both close paths call `runCodeReview`
- * through a single implementation rather than each maintaining its own
- * invocation pattern (Story #3653).
+ * 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 {
-  runAuditSuite,
-  selectLocalLenses,
-} from '../../../audit-suite/index.js';
-import { gitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
 import { runCodeReview } from '../../code-review.js';
 import { emitBlockedCloseResult } from '../emit-blocked.js';
+import { runLocalLensReview } from './local-lens-review.js';
+import { runStoryReviewCore } from './review-core.js';
 
 /**
- * The review depth the Story-scope local-lens pass runs at. Shift-left
- * (Epic #4405): local concerns are cheap to decide on a single Story's diff, so
- * the maker-blind Story-scope review runs its matched local lenses at `light`
- * depth here rather than paying a deeper pass at Epic close. Fixed for this
- * tier — it is not risk-scaled like the code-review pillar depth.
- */
-export const STORY_SCOPE_LENS_DEPTH = 'light';
-
-/**
- * Enumerate the files changed in the `baseRef...headRef` diff via
- * `git diff --name-only`. Best-effort: returns `[]` when the diff cannot be
- * enumerated (git failure, missing ref) and never throws, mirroring the
- * advisory posture of the surrounding review phase. Synchronous `gitSpawn`
- * (returns `{ status, stdout }`) is the same seam `code-review.js#countChangedFiles`
- * uses.
+ * Read a review envelope's severity counts, tolerating the partial envelope a
+ * misbehaving provider adapter can return. Pure.
  *
- * @param {{ baseRef: string, headRef: string, gitSpawnFn?: typeof gitSpawn }} args
- * @returns {string[]} Changed file paths, or `[]` on any failure.
+ * @param {object|null|undefined} reviewResult
+ * @returns {{ critical: number, high: number, medium: number, suggestion: number }}
  */
-export function enumerateChangedFiles({
-  baseRef,
-  headRef,
-  gitSpawnFn = gitSpawn,
-}) {
-  try {
-    const result = gitSpawnFn(
-      process.cwd(),
-      'diff',
-      '--name-only',
-      `${baseRef}...${headRef}`,
-    );
-    if (!result || result.status !== 0 || typeof result.stdout !== 'string') {
-      return [];
+function resolveSeverity(reviewResult) {
+  return (
+    reviewResult?.severity ?? {
+      critical: 0,
+      high: 0,
+      medium: 0,
+      suggestion: 0,
     }
-    return result.stdout
-      .split('\n')
-      .map((f) => f.trim())
-      .filter(Boolean);
-  } catch {
-    return [];
-  }
+  );
 }
 
 /**
- * Run the Story-scope local-lens pass: select the LOCAL-tier lenses whose
- * `filePatterns` match the actual Story diff (`baseRef...headRef`) and
- * materialize their lens-prompt bodies at `light` depth. This is the
- * shift-left tier from Epic #4405 — it runs **inside** the story-close
- * subprocess spine (called only from {@link runStoryReviewCore}), never in the
- * delivering child's (maker's) context, so a maker never grades its own work.
- *
- * A diff that matches no local lens adds **no** lens work: the roster is empty
- * and `runAuditSuite` is never invoked. Best-effort and total — a git or
- * materialization failure degrades to `{ skipped: true, lenses: [] }` and is
- * logged via `progress`, matching the advisory posture the review phase already
- * takes for provider/transport failures.
+ * Collect the extra fields for the code-review-critical blocked envelope. Pure.
  *
- * @param {{
- *   baseRef: string,
- *   headRef: string,
- *   progress: (tag: string, msg: string) => void,
- *   progressTag?: string,
- *   gitSpawnFn?: typeof gitSpawn,
- *   selectLocalLensesFn?: typeof selectLocalLenses,
- *   runAuditSuiteFn?: typeof runAuditSuite,
- * }} args
- * @returns {Promise<{
- *   depth: 'light',
- *   lenses: string[],
- *   skipped: boolean,
- *   materialized: object|null,
- * }>}
- */
-export async function runLocalLensReview({
-  baseRef,
-  headRef,
-  progress,
-  progressTag = 'CODE-REVIEW',
-  gitSpawnFn = gitSpawn,
-  selectLocalLensesFn = selectLocalLenses,
-  runAuditSuiteFn = runAuditSuite,
-}) {
-  const empty = {
-    depth: STORY_SCOPE_LENS_DEPTH,
-    lenses: [],
-    skipped: true,
-    materialized: null,
-  };
-  let lenses;
-  try {
-    const changedFiles = enumerateChangedFiles({
-      baseRef,
-      headRef,
-      gitSpawnFn,
-    });
-    lenses = selectLocalLensesFn({ changedFiles });
-    if (lenses.length === 0) {
-      progress(
-        progressTag,
-        'No local lens matched the Story diff — skipping the lens pass.',
-      );
-      return empty;
-    }
-    const materialized = await runAuditSuiteFn({ auditWorkflows: lenses });
-    progress(
-      progressTag,
-      `Ran ${lenses.length} local lens(es) at ${STORY_SCOPE_LENS_DEPTH} depth: ${lenses.join(', ')}.`,
-    );
-    return {
-      depth: STORY_SCOPE_LENS_DEPTH,
-      lenses,
-      skipped: false,
-      materialized,
-    };
-  } catch (err) {
-    // The lens pass is advisory: a git or materialization failure must not
-    // fail the close. Log and degrade to a skipped envelope.
-    progress(
-      progressTag,
-      `⚠️ local lens pass failed (continuing without it): ${err?.message ?? err}`,
-    );
-    return empty;
-  }
-}
-
-/**
- * Collect the extra fields for the code-review-critical blocked envelope.
- * Pure; used by `runStoryCodeReview` to populate the `extra` argument of
- * `emitBlockedCloseResult`.
+ * @param {{ storyId: number, reviewResult: object }} args
+ * @returns {object}
  */
 function buildCodeReviewBlockedExtra({ storyId, reviewResult }) {
-  const severity = reviewResult?.severity ?? {
-    critical: 0,
-    high: 0,
-    medium: 0,
-    suggestion: 0,
-  };
   return {
-    storyId: Number(storyId),
+    storyId,
     blockerReason: reviewResult?.blockerReason ?? null,
-    severity,
+    severity: resolveSeverity(reviewResult),
     posted: reviewResult?.posted ?? false,
     exitCode: 1,
   };
 }
 
 /**
- * Invoke `runCodeReviewFn` with the canonical Story-scope envelope and return
- * the raw result. Shared by both the Epic-attached close path
- * (`runStoryCodeReview`) and the standalone close path
- * (`single-story-close/phases/code-review.js#runStoryScopeReview`) so the
- * invocation pattern lives in one place (Story #3653).
- *
- * The caller is responsible for error handling and result interpretation —
- * this function propagates throws rather than swallowing them, because the
- * two callers have different advisory postures:
+ * Render the operator-facing one-line summary of a completed (non-halting)
+ * review. Pure.
  *
- *   - Epic-attached close: swallows throws (non-blocking advisory, same as
- *     `refresh.js`).
- *   - Standalone close: propagates throws (a review failure stops the close).
+ * @param {object} reviewResult
+ * @returns {string}
+ */
+function formatReviewSummary(reviewResult) {
+  const { high, medium, suggestion } = resolveSeverity(reviewResult);
+  const posted = reviewResult?.posted ?? false;
+  return `Review complete — high=${high} medium=${medium} suggestion=${suggestion} (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.
  *
- * The optional `planningRisk` envelope (Story #3940) is forwarded verbatim to
- * `runCodeReview`, which folds its `overallLevel` together with the
- * `baseRef...headRef` changed-file count (which `runCodeReview` enumerates
- * itself, scoped to the diff under review) into the review depth via the
- * shared {@link resolveDepth} resolver. It is an **input-only** signal: it
- * tells the provider how thorough to be and never alters the review's output
- * envelope or the posted structured-comment body. Absent (`null` / `undefined`,
- * the standalone close path) → `runCodeReview` resolves the neutral depth from
- * diff width alone, byte-identical to the pre-#3940 behaviour.
+ * @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|string,
- *   baseRef: string,
- *   headRef: string,
- *   commentTargetId?: number|null,
- *   provider: object,
+ *   storyId: number,
+ *   reviewResult: object,
+ *   bus: { emit: Function }|null,
  *   progress: (tag: string, msg: string) => void,
- *   progressTag?: string,
- *   planningRisk?: { overallLevel?: ('low'|'medium'|'high'), axes?: Array<{ axis?: string, level?: string }> }|null,
- *   runCodeReviewFn?: typeof runCodeReview,
- *   runLocalLensReviewFn?: typeof runLocalLensReview,
  * }} args
- * @returns {Promise<object>} Raw result envelope from `runCodeReview`, augmented
- *   with a `localLensReview` field carrying the Story-scope local-lens pass
- *   outcome (Epic #4405, Story #4409). Both close entry points reach the lens
- *   pass through this single spine, so it runs on the Epic-attached and
- *   standalone paths alike and always inside the close subprocess.
+ * @returns {Promise<object>} The blocked envelope.
  */
-export async function runStoryReviewCore({
-  storyId,
-  baseRef,
-  headRef,
-  commentTargetId = null,
-  provider,
-  progress,
-  progressTag = 'CODE-REVIEW',
-  planningRisk = null,
-  runCodeReviewFn = runCodeReview,
-  runLocalLensReviewFn = runLocalLensReview,
-}) {
-  const storyIdNum = Number(storyId);
-  const opts = {
-    scope: 'story',
-    ticketId: storyIdNum,
-    baseRef,
-    headRef,
-    provider,
-    logger: {
-      info: (m) => progress(progressTag, m),
-      warn: (m) => progress(progressTag, `⚠️ ${m}`),
-    },
-  };
-  if (commentTargetId != null) {
-    opts.commentTargetId = commentTargetId;
-  }
-  // Forward the parent Epic's judged risk only on the Epic-attached path; the
-  // standalone caller leaves this null so `runCodeReview` resolves depth from
-  // diff width alone (no plan checkpoint exists for a standalone Story).
-  if (planningRisk != null) {
-    opts.planningRisk = planningRisk;
-  }
-
-  // Shift-left local-lens pass (Epic #4405). Runs matched local lenses at
-  // `light` depth against the actual Story diff, inside this close-subprocess
-  // spine so the maker never grades its own work. Advisory — it never blocks
-  // the close and its outcome rides on the returned envelope for downstream
-  // consumers.
-  const localLensReview = await runLocalLensReviewFn({
-    baseRef,
-    headRef,
+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,
-    progressTag,
+    blockedMessage: `Story #${storyId} blocked: code-review reported ${critical} critical blocker(s).`,
+    logger: Logger,
   });
-
-  const result = await runCodeReviewFn(opts);
-  return { ...result, localLensReview };
 }
 
 /**
@@ -291,23 +143,19 @@ export async function runStoryReviewCore({
  * `blocked` is either `null` (caller proceeds to open/merge the PR) or the
  * blocked-envelope (caller returns it verbatim and the CLI exits 1).
  *
- * The optional `planningRisk` envelope (Story #3940) is the parent Epic's
- * judged risk, read best-effort off the `epic-plan-state` checkpoint by the
- * locked pipeline. It is forwarded into `runCodeReview` so the review depth is
- * resolved from BOTH the parent Epic's judged risk (pre-v2) and the Story's own
- * base…head changed-file count — a small Story under a
- * high-risk Epic still earns `deep`, a small Story under a low-risk Epic gets
- * `light`, and an absent envelope resolves `standard` (today's behaviour).
- * Depth is input-only: it never changes `{ blocked }` or the posted comment.
+ * 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,
- *   epicBranch: string,
+ *   baseBranch: string,
  *   storyBranch: string,
  *   provider: object,
  *   bus: { emit: Function }|null,
  *   progress: (tag: string, msg: string) => void,
- *   planningRisk?: { overallLevel?: ('low'|'medium'|'high'), axes?: Array<{ axis?: string, level?: string }> }|null,
  *   runCodeReviewFn?: typeof runCodeReview,
  *   runLocalLensReviewFn?: typeof runLocalLensReview,
  * }} args
@@ -316,67 +164,44 @@ export async function runStoryReviewCore({
  *   (Epic #4405, Story #4409) when the review completed; it is absent only when
  *   the whole review phase threw (advisory failure).
  */
-export async function runStoryCodeReview(args) {
-  const {
-    storyId,
-    epicBranch,
-    storyBranch,
-    provider,
-    bus,
-    progress,
-    planningRisk = null,
-    runCodeReviewFn = runCodeReview,
-    runLocalLensReviewFn = runLocalLensReview,
-  } = args;
-
+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 (${epicBranch}…${storyBranch})...`,
+    `Running Story-scope review (${baseBranch}…${storyBranch})...`,
   );
 
-  let reviewResult;
-  try {
-    reviewResult = await runStoryReviewCore({
-      storyId: storyIdNum,
-      baseRef: epicBranch,
-      headRef: storyBranch,
-      provider,
-      progress,
-      planningRisk,
-      runCodeReviewFn,
-      runLocalLensReviewFn,
-    });
-  } catch (err) {
-    // Adapter / wiring failure — log and proceed. The review is advisory
-    // when the provider cannot complete; the gates already vouched for
-    // the diff at this point.
-    Logger.warn?.(
-      `[story-close] ⚠️ code-review phase failed (continuing without blocker): ${err?.message ?? err}`,
-    );
-    return { blocked: null };
-  }
-
-  const localLensReview = reviewResult?.localLensReview;
+  const reviewResult = await invokeReviewCore({
+    storyId: storyIdNum,
+    baseRef: baseBranch,
+    headRef: storyBranch,
+    provider,
+    progress,
+    runCodeReviewFn,
+    runLocalLensReviewFn,
+  });
+  if (reviewResult === null) return { blocked: null };
 
-  if (reviewResult?.halted) {
-    const blocked = await emitBlockedCloseResult({
+  const localLensReview = reviewResult.localLensReview;
+  if (reviewResult.halted) {
+    const blocked = await emitCriticalBlock({
       storyId: storyIdNum,
-      phase: 'closing',
-      reason: 'code-review-critical',
-      extra: buildCodeReviewBlockedExtra({ storyId: storyIdNum, reviewResult }),
+      reviewResult,
       bus,
       progress,
-      blockedMessage: `Story #${storyIdNum} blocked: code-review reported ${reviewResult.severity.critical} critical blocker(s).`,
-      logger: Logger,
     });
     return { blocked, localLensReview };
   }
 
-  const counts = reviewResult?.severity ?? {};
-  progress(
-    'CODE-REVIEW',
-    `Review complete — high=${counts.high ?? 0} medium=${counts.medium ?? 0} suggestion=${counts.suggestion ?? 0} (posted=${reviewResult?.posted ?? false}).`,
-  );
+  progress('CODE-REVIEW', formatReviewSummary(reviewResult));
   return { blocked: null, localLensReview };
 }

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

@@ -0,0 +1,191 @@
+/**
+ * phases/local-lens-review.js — the Story-scope local-lens pass.
+ *
+ * Extracted from `phases/code-review.js` (Story #4603) so the review spine and
+ * the lens pass each carry one reason to change. The spine
+ * (`runStoryReviewCore`) owns the single per-close-run diff enumeration and the
+ * `runCodeReview` invocation; this module owns lens selection + materialization.
+ *
+ * Shift-left tier (Epic #4405): local concerns are cheap to decide on a single
+ * Story's diff, so the maker-blind Story-scope review runs its matched local
+ * lenses here, inside the story-close subprocess, rather than paying a deeper
+ * pass at Epic close.
+ */
+
+import {
+  runAuditSuite,
+  selectLocalLenses,
+} from '../../../audit-suite/index.js';
+import { gitSpawn } from '../../../git-utils.js';
+import { computeChangeSet } from '../../change-set.js';
+
+/**
+ * The review depth the Story-scope local-lens pass runs at. Fixed for this
+ * tier — it is not risk-scaled like the code-review pillar depth.
+ *
+ * Module-local: it is an implementation detail of {@link runLocalLensReview}
+ * (it rides out on the returned envelope's `depth` field), not a public seam.
+ * Tests assert the observable `'light'` on that envelope rather than importing
+ * the constant, so it stays off the public surface (Story #4603).
+ */
+const STORY_SCOPE_LENS_DEPTH = 'light';
+
+/**
+ * Enumerate the files changed in the `baseRef...headRef` diff. Thin adapter over
+ * the shared {@link computeChangeSet} enumerator (Story #4593) that flattens its
+ * `files: string[]|null` envelope to this phase's historical `[]`-on-failure
+ * contract: the lens roster treats "nothing changed" and "diff unknown"
+ * identically, because an unknown diff matches no `filePatterns` and therefore
+ * adds no lens work either way.
+ *
+ * Best-effort and total — never throws, mirroring the advisory posture of the
+ * surrounding review phase. Retained as the self-enumeration fallback for
+ * {@link runLocalLensReview} when no change set is injected.
+ *
+ * @param {{
+ *   baseRef: string,
+ *   headRef: string,
+ *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
+ * }} args
+ * Module-local (Story #4603): a private fallback of {@link runLocalLensReview},
+ * exercised through that public entry point rather than imported directly, so it
+ * adds no public export a production path fails to reach.
+ *
+ * @returns {string[]} Changed file paths, or `[]` on any failure.
+ */
+function enumerateChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
+  return computeChangeSet({ baseRef, headRef, gitSpawnFn }).files ?? [];
+}
+
+/**
+ * Resolve the change set the lens roster reads, honouring all THREE injection
+ * states (Story #4603 — the fix for #4593's single-enumeration leak).
+ *
+ * The distinction between `null` and `undefined` is load-bearing and mirrors
+ * the sibling contract in `orchestration/code-review.js#resolveInjectedChangedFiles`:
+ *
+ *   - **array**     — the caller's change set; use it verbatim.
+ *   - **`null`**    — the caller (`runStoryReviewCore`) already tried and the
+ *                     diff is unenumerable. Re-running git here would only fail
+ *                     again, so degrade straight to the fail-safe empty roster.
+ *   - **`undefined`** — nobody enumerated (standalone callers), so the shared
+ *                     enumerator runs as the fallback.
+ *
+ * The prior `Array.isArray()` discriminator collapsed `null` and `undefined`
+ * into one branch and re-spawned git on the unenumerable path, contradicting the
+ * spine's documented "the one enumeration per close run" invariant.
+ *
+ * Module-local (Story #4603): a private detail of {@link runLocalLensReview}.
+ * The three-state contract is asserted through that public entry point (does an
+ * injected `null` re-spawn git? does `undefined` self-enumerate?), so it needs
+ * no public export — keeping the fix from re-introducing the very kind of
+ * production-dead public symbol this Story's ratchet root-cause is about.
+ *
+ * @param {{
+ *   changedFiles: string[]|null|undefined,
+ *   baseRef: string,
+ *   headRef: string,
+ *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
+ * }} args
+ * @returns {string[]}
+ */
+function resolveLensChangeSet({
+  changedFiles,
+  baseRef,
+  headRef,
+  gitSpawnFn = gitSpawn,
+}) {
+  if (changedFiles === undefined) {
+    return enumerateChangedFiles({ baseRef, headRef, gitSpawnFn });
+  }
+  return changedFiles ?? [];
+}
+
+/**
+ * Run the Story-scope local-lens pass: select the LOCAL-tier lenses whose
+ * `filePatterns` match the actual Story diff (`baseRef...headRef`) and
+ * materialize their lens-prompt bodies at `light` depth. Called only from
+ * `runStoryReviewCore`, never in the delivering child's (maker's) context, so a
+ * maker never grades its own work.
+ *
+ * A diff that matches no local lens adds **no** lens work: the roster is empty
+ * and `runAuditSuite` is never invoked. Best-effort and total — a git or
+ * materialization failure degrades to `{ skipped: true, lenses: [] }` and is
+ * logged via `progress`, matching the advisory posture the review phase already
+ * takes for provider/transport failures.
+ *
+ * Story #4593 — `changedFiles` is injected by `runStoryReviewCore`, which
+ * computes the change set once per close run and hands the same list to this
+ * pass and to `runCodeReview`. Self-enumeration is the **fallback only**, kept
+ * for standalone callers that supply no list; see {@link resolveLensChangeSet}
+ * for the three-state contract.
+ *
+ * @param {{
+ *   baseRef: string,
+ *   headRef: string,
+ *   changedFiles?: string[]|null,
+ *   progress: (tag: string, msg: string) => void,
+ *   progressTag?: string,
+ *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
+ *   selectLocalLensesFn?: typeof selectLocalLenses,
+ *   runAuditSuiteFn?: typeof runAuditSuite,
+ * }} args
+ * @returns {Promise<{
+ *   depth: 'light',
+ *   lenses: string[],
+ *   skipped: boolean,
+ *   materialized: object|null,
+ * }>}
+ */
+export async function runLocalLensReview({
+  baseRef,
+  headRef,
+  changedFiles: injectedChangedFiles,
+  progress,
+  progressTag = 'CODE-REVIEW',
+  gitSpawnFn = gitSpawn,
+  selectLocalLensesFn = selectLocalLenses,
+  runAuditSuiteFn = runAuditSuite,
+}) {
+  const empty = {
+    depth: STORY_SCOPE_LENS_DEPTH,
+    lenses: [],
+    skipped: true,
+    materialized: null,
+  };
+  try {
+    const changedFiles = resolveLensChangeSet({
+      changedFiles: injectedChangedFiles,
+      baseRef,
+      headRef,
+      gitSpawnFn,
+    });
+    const lenses = selectLocalLensesFn({ changedFiles });
+    if (lenses.length === 0) {
+      progress(
+        progressTag,
+        'No local lens matched the Story diff — skipping the lens pass.',
+      );
+      return empty;
+    }
+    const materialized = await runAuditSuiteFn({ auditWorkflows: lenses });
+    progress(
+      progressTag,
+      `Ran ${lenses.length} local lens(es) at ${STORY_SCOPE_LENS_DEPTH} depth: ${lenses.join(', ')}.`,
+    );
+    return {
+      depth: STORY_SCOPE_LENS_DEPTH,
+      lenses,
+      skipped: false,
+      materialized,
+    };
+  } catch (err) {
+    // The lens pass is advisory: a git or materialization failure must not
+    // fail the close. Log and degrade to a skipped envelope.
+    progress(
+      progressTag,
+      `⚠️ local lens pass failed (continuing without it): ${err?.message ?? err}`,
+    );
+    return empty;
+  }
+}