mandrel 2.31.0 → 2.32.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js

@@ -19,7 +19,7 @@
  * module mechanizes it.
  *
  * Contract (pure where possible — the only side effect is an injectable
- * `git log` read used to derive the type):
+ * `git log` read):
  *
  *   - If `storyTitle` is **already** a parseable Conventional Commit
  *     subject, it is preserved verbatim and suffixed with `(#<storyId>)`.
@@ -28,116 +28,48 @@
  *     `<type>: <descriptive text> (#<storyId>)`. The `type` is derived
  *     from the branch's own (already-conventional) commit subjects when
  *     available, falling back to a safe configured default (`chore`).
+ *   - Either way, a branch (or Story) that declares a breaking change gets
+ *     the `!` marker and a `BREAKING CHANGE:` footer on the PR body.
  *
- * Mirrors the already-normalized Epic-finalize default in
- * `lib/orchestration/finalize/open-or-locate-pr.js` (`feat: Epic #<id>`),
- * bringing the standalone path to the same guarantee.
+ * The rules that decide *what* the subject says now live in
+ * `conventional-subject.js` — type precedence, acronym-safe casing, and
+ * breaking-change collection are pure and unit-tested there. What is left
+ * here is the git read those rules consume and the assembly of the two
+ * strings `gh pr create` needs.
  */
 
 import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
 import { Logger as DefaultLogger } from '../../../Logger.js';
+import {
+  collectBreakingNotes,
+  isConventionalSubject,
+  markBreaking,
+  pickDominantType,
+  shapeDescription,
+} from './conventional-subject.js';
 
 /** Safe default Conventional-Commit type when none can be derived. */
 const DEFAULT_CONVENTIONAL_TYPE = 'chore';
 
 /**
- * The Conventional-Commit types Mandrel accepts. Mirrors
- * `commitlint.config.js` → `type-enum` and `release-please-config.json` →
- * `changelog-sections`. Kept in sync by hand (single hard-cutover, no
- * shim) — adding a type means touching all three.
+ * Record separator between whole commit messages in the `git log` read. A NUL
+ * cannot occur inside a commit message, so splitting on it is unambiguous —
+ * unlike a blank-line or subject-prefix heuristic, which a commit body can
+ * forge.
  */
-const CONVENTIONAL_TYPES = Object.freeze([
-  'feat',
-  'fix',
-  'perf',
-  'refactor',
-  'revert',
-  'docs',
-  'style',
-  'chore',
-  'test',
-  'build',
-  'ci',
-]);
-
-// Precedence used when a branch carries a mix of conventional types: pick
-// the most release-significant one so the squash subject communicates the
-// branch's headline impact (and release-please bumps appropriately).
-const TYPE_PRECEDENCE = Object.freeze([
-  'feat',
-  'fix',
-  'perf',
-  'refactor',
-  'revert',
-  'docs',
-  'style',
-  'test',
-  'build',
-  'ci',
-  'chore',
-]);
-
-const TYPE_GROUP = CONVENTIONAL_TYPES.join('|');
-// Anchored Conventional-Commit header matcher:
-//   <type>(<optional scope>)<optional !>: <non-empty description>
-// Mirrors the shape `@commitlint/config-conventional` enforces (a known
-// type, an optional parenthesised scope, an optional breaking `!`, a
-// colon-space separator, and a non-empty subject). Used for the pure
-// "is this already conventional?" check and to pull the type off a branch
-// commit subject without spawning commitlint per call.
-const CONVENTIONAL_HEADER_RE = new RegExp(
-  `^(?:${TYPE_GROUP})(?:\\([^()\\r\\n]+\\))?!?: \\S.*$`,
-);
-const LEADING_TYPE_RE = new RegExp(
-  `^(${TYPE_GROUP})(?:\\([^()\\r\\n]+\\))?!?:`,
-);
-
-/**
- * True iff `subject` is a parseable Conventional Commit subject under the
- * repo's type vocabulary. Pure.
- *
- * @param {string} subject
- * @returns {boolean}
- */
-function isConventionalSubject(subject) {
-  if (typeof subject !== 'string') return false;
-  return CONVENTIONAL_HEADER_RE.test(subject.trim());
-}
+const RECORD_SEP = '\u0000';
 
 /**
- * Extract the Conventional-Commit `type` from a single commit subject, or
- * `null` when the subject is not conventional. Pure.
+ * Read the branch's own commits (those unique to the Story branch relative to
+ * the base branch) as whole messages — subject AND body, because the body is
+ * where a `BREAKING CHANGE:` footer lives.
  *
- * @param {string} subject
- * @returns {string|null}
- */
-function parseConventionalType(subject) {
-  if (typeof subject !== 'string') return null;
-  const match = subject.trim().match(LEADING_TYPE_RE);
-  return match ? match[1] : null;
-}
-
-/**
- * Pick the most release-significant type from a list of conventional
- * types, honouring `TYPE_PRECEDENCE`. Returns `null` for an empty list.
- * Pure.
+ * Returns `[]` when the read fails, which degrades every downstream rule to
+ * its safe default (type `chore`, no breaking marker) rather than throwing a
+ * close that is otherwise healthy.
  *
- * @param {string[]} types
- * @returns {string|null}
- */
-function pickDominantType(types) {
-  const present = new Set(types.filter(Boolean));
-  for (const candidate of TYPE_PRECEDENCE) {
-    if (present.has(candidate)) return candidate;
-  }
-  return null;
-}
-
-/**
- * Read the branch's own commit subjects (commits unique to the Story
- * branch relative to the base branch) and derive the dominant
- * Conventional-Commit type. Returns `DEFAULT_CONVENTIONAL_TYPE` when no
- * conventional subject is found or the git read fails.
+ * Oldest-first (`--reverse`) is load-bearing: `pickDominantType` breaks a tie
+ * on the Story's primary commit, which is the first one authored.
  *
  * @param {{
  *   storyBranch: string,
@@ -146,96 +78,174 @@ function pickDominantType(types) {
  *   gitSpawn?: typeof defaultGitSpawn,
  *   logger?: { warn?: Function },
  * }} args
- * @returns {string}
+ * @returns {string[]} Whole commit messages, oldest first.
  */
-function deriveTypeFromBranchCommits({
+function readBranchCommits({
   storyBranch,
   baseBranch,
   cwd = process.cwd(),
   gitSpawn = defaultGitSpawn,
   logger = DefaultLogger,
 }) {
+  if (!storyBranch || !baseBranch) return [];
+  const range = `${baseBranch}..${storyBranch}`;
   try {
-    const range = `${baseBranch}..${storyBranch}`;
-    const result = gitSpawn(cwd, 'log', '--no-merges', '--format=%s', range);
-    if (!result || result.status !== 0) {
+    const result = gitSpawn(
+      cwd,
+      'log',
+      '--no-merges',
+      '--reverse',
+      '--format=%B%x00',
+      range,
+    );
+    if (result?.status !== 0) {
       logger?.warn?.(
         `[normalize-pr-title] git log ${range} failed (status=${result?.status ?? 'n/a'}); ` +
-          `defaulting type to "${DEFAULT_CONVENTIONAL_TYPE}".`,
+          `defaulting type to "${DEFAULT_CONVENTIONAL_TYPE}" and assuming no breaking change.`,
       );
-      return DEFAULT_CONVENTIONAL_TYPE;
+      return [];
     }
-    const types = String(result.stdout ?? '')
-      .split('\n')
-      .map((line) => parseConventionalType(line))
-      .filter(Boolean);
-    return pickDominantType(types) ?? DEFAULT_CONVENTIONAL_TYPE;
+    return String(result.stdout ?? '')
+      .split(RECORD_SEP)
+      .map((message) => message.trim())
+      .filter((message) => message.length > 0);
   } catch (err) {
     logger?.warn?.(
-      `[normalize-pr-title] could not derive type from branch commits ` +
-        `(defaulting to "${DEFAULT_CONVENTIONAL_TYPE}"): ${err?.message ?? err}`,
+      `[normalize-pr-title] could not read branch commits ` +
+        `(defaulting to "${DEFAULT_CONVENTIONAL_TYPE}", no breaking change): ${err?.message ?? err}`,
     );
-    return DEFAULT_CONVENTIONAL_TYPE;
+    return [];
   }
 }
 
 /**
- * Produce a PR title that parses as a Conventional Commit.
+ * Produce the PR title and the breaking-change notes that belong with it.
  *
  *   - Already-conventional `storyTitle` → preserved verbatim + `(#<id>)`.
- *   - Otherwise → `<derivedType>: <storyTitle> (#<id>)`.
- *   - Empty / missing `storyTitle` → `<derivedType>: Story #<id>`.
+ *   - Otherwise → `<derivedType>: <shaped storyTitle> (#<id>)`.
+ *   - Empty / missing `storyTitle` → `<derivedType>: story #<id>`.
+ *   - Breaking → `!` inserted before the colon in either shape.
  *
- * The type derivation (`deriveTypeFromBranchCommits`) is the only side
- * effect, and is skipped entirely when the title is already conventional.
+ * `commitMessages` is the branch read (`readBranchCommits`); passing `[]`
+ * yields the safe default type and no breaking marker. `storyBody` is the
+ * Story issue's body, scanned for a declared `BREAKING CHANGE:` footer.
  *
  * @param {{
  *   storyTitle: string,
  *   storyId: number|string,
- *   storyBranch?: string,
- *   baseBranch?: string,
- *   cwd?: string,
- *   gitSpawn?: typeof defaultGitSpawn,
- *   logger?: { warn?: Function },
+ *   commitMessages?: string[],
+ *   storyBody?: string,
  * }} args
+ * @returns {{ title: string, breaking: boolean, breakingNotes: string[] }}
+ */
+function normalizePrTitle({
+  storyTitle,
+  storyId,
+  commitMessages = [],
+  storyBody = '',
+}) {
+  const idSuffix = `(#${storyId})`;
+  const trimmed = typeof storyTitle === 'string' ? storyTitle.trim() : '';
+  const { breaking, notes } = collectBreakingNotes({
+    commitMessages,
+    storyBody,
+  });
+
+  // Already conventional → preserve verbatim (the maker's own casing and
+  // scope survive), append the id reference. Only the breaking marker may be
+  // added, and only when it is not already there.
+  const subject = isConventionalSubject(trimmed)
+    ? trimmed
+    : synthesizeSubject({ description: trimmed, storyId, commitMessages });
+
+  const marked = breaking ? markBreaking(subject) : subject;
+  return { title: `${marked} ${idSuffix}`, breaking, breakingNotes: notes };
+}
+
+/**
+ * Build a conventional subject for a Story whose title is plain prose.
+ *
+ * @param {{ description: string, storyId: number|string, commitMessages: string[] }} args
+ * @returns {string}
+ */
+function synthesizeSubject({ description, storyId, commitMessages }) {
+  const subjects = commitMessages.map((message) => message.split('\n')[0]);
+  const type = pickDominantType(subjects) ?? DEFAULT_CONVENTIONAL_TYPE;
+  const raw = description.length > 0 ? description : `Story #${storyId}`;
+  return `${type}: ${shapeDescription(raw)}`;
+}
+
+/**
+ * Build the PR body.
+ *
+ * The `Closes #<id>` footer is what auto-closes the Story on merge. A
+ * `BREAKING CHANGE:` footer goes LAST, as the spec requires, so that a repo
+ * configured to use the PR body as the squash-commit message hands
+ * release-please a parseable note rather than prose. When the squash body is
+ * built from the constituent commit messages instead (GitHub's default, and
+ * this repo's setting), the note still reaches `main` through whichever
+ * commit carried the footer — and the `!` in the subject carries the signal
+ * either way.
+ *
+ * @param {{ storyId: number|string, breakingNotes?: string[] }} args
  * @returns {string}
  */
-export function normalizePrTitle({
+function buildPrBody({ storyId, breakingNotes }) {
+  const lines = [`Closes #${storyId}`, '', '_Auto-opened by `/deliver`._'];
+  if (breakingNotes.length > 0) {
+    lines.push('', `BREAKING CHANGE: ${breakingNotes.join(' ')}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Derive the two strings `gh pr create` needs. One `git log` read serves both
+ * halves: the commit SUBJECTS decide the type, and the commit BODIES — plus
+ * the Story body — decide whether this is a breaking change.
+ *
+ * A declared break is announced on the progress channel, because a `!` the
+ * operator did not expect in the squash subject should be visible while the
+ * close is running rather than discovered in the release notes.
+ *
+ * @param {{ storyTitle: string, storyId: number|string, storyBody?: string,
+ *   storyBranch: string, baseBranch: string, cwd?: string,
+ *   gitSpawn?: typeof defaultGitSpawn,
+ *   progress?: (tag: string, msg: string) => void }} args
+ * @returns {{ title: string, body: string, breaking: boolean, breakingNotes: string[] }}
+ */
+export function buildPullRequestFields({
   storyTitle,
   storyId,
+  storyBody = '',
   storyBranch,
   baseBranch,
   cwd = process.cwd(),
   gitSpawn = defaultGitSpawn,
-  logger = DefaultLogger,
+  progress = () => {},
 }) {
-  const idSuffix = `(#${storyId})`;
-  const trimmed = typeof storyTitle === 'string' ? storyTitle.trim() : '';
-
-  // Already conventional → preserve verbatim, append the id reference.
-  if (isConventionalSubject(trimmed)) {
-    return `${trimmed} ${idSuffix}`;
+  const commitMessages = readBranchCommits({
+    storyBranch,
+    baseBranch,
+    cwd,
+    gitSpawn,
+  });
+  const { title, breaking, breakingNotes } = normalizePrTitle({
+    storyTitle,
+    storyId,
+    commitMessages,
+    storyBody,
+  });
+  if (breaking) {
+    progress(
+      'PR',
+      '⚠️  Breaking change declared — the PR title carries `!` and the body a ' +
+        `BREAKING CHANGE footer: ${breakingNotes.join(' ') || '(no note text)'}`,
+    );
   }
-
-  // Not conventional → derive a type and synthesize.
-  const type =
-    storyBranch && baseBranch
-      ? deriveTypeFromBranchCommits({
-          storyBranch,
-          baseBranch,
-          cwd,
-          gitSpawn,
-          logger,
-        })
-      : DEFAULT_CONVENTIONAL_TYPE;
-
-  // Lowercase the leading character of a synthesized description so the
-  // subject satisfies commitlint's `subject-case` rule (matching the
-  // `shapeMergeSubject` behaviour). An already-conventional title is left
-  // untouched (it was preserved verbatim above). The empty-title fallback
-  // uses a lowercased `story #<id>` for the same reason.
-  const rawDescription = trimmed.length > 0 ? trimmed : `Story #${storyId}`;
-  const description =
-    rawDescription.charAt(0).toLowerCase() + rawDescription.slice(1);
-  return `${type}: ${description} ${idSuffix}`;
+  return {
+    title,
+    body: buildPrBody({ storyId, breakingNotes }),
+    breaking,
+    breakingNotes,
+  };
 }

package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js

@@ -9,7 +9,11 @@
  */
 
 import path from 'node:path';
-import { parseMergeWatchMode, parseSprintArgs } from '../../../cli-args.js';
+import {
+  parseMergeWatchMode,
+  parseOverrideReviewBlock,
+  parseSprintArgs,
+} from '../../../cli-args.js';
 import { getDeliveryRouting } from '../../../config/delivery-routing.js';
 import { PROJECT_ROOT } from '../../../project-root.js';
 import { isOperatorMergeReason } from './auto-merge.js';
@@ -91,8 +95,8 @@ export function resolveWaitForMerge({
  * (`waitForMergeExplicit` / `noWaitForMerge`) for the runner to resolve once
  * the config and the arm outcome exist.
  *
- * @param {{ storyIdParam, cwdParam, skipValidationParam, skipSyncParam, noAutoMergeParam, waitForMergeParam, noWaitForMergeParam, maxWaitSecondsParam, mergeWatchModeParam }} raw
- * @returns {{ storyId, cwd, skipValidation, skipSync, noAutoMerge, waitForMergeExplicit, noWaitForMerge, maxWaitSeconds, mergeWatchMode }}
+ * @param {{ storyIdParam, cwdParam, skipValidationParam, skipSyncParam, noAutoMergeParam, waitForMergeParam, noWaitForMergeParam, maxWaitSecondsParam, mergeWatchModeParam, overrideReviewBlockParam }} raw
+ * @returns {{ storyId, cwd, skipValidation, skipSync, noAutoMerge, waitForMergeExplicit, noWaitForMerge, maxWaitSeconds, mergeWatchMode, overrideReviewBlock }}
  */
 export function parseCloseOptions({
   storyIdParam,
@@ -104,6 +108,7 @@ export function parseCloseOptions({
   noWaitForMergeParam,
   maxWaitSecondsParam,
   mergeWatchModeParam,
+  overrideReviewBlockParam,
 }) {
   // An injecting caller (`storyIdParam` supplied) is not reading argv at all,
   // so there is nothing to parse and `parsed` stays empty. This used to build a
@@ -148,5 +153,12 @@ export function parseCloseOptions({
         ? waitForMergeExplicit
         : undefined,
     noWaitForMerge: !!resolveFlag(noWaitForMergeParam, parsed.noWaitForMerge),
+    // `undefined` when unsupplied, which is what keeps a review
+    // critical blocker blocking. An injecting caller passes the reason string
+    // directly; both doors run the same validating parser, so neither can arm
+    // a reasonless override.
+    overrideReviewBlock: parseOverrideReviewBlock(
+      resolveFlag(overrideReviewBlockParam, parsed.overrideReviewBlock),
+    ),
   };
 }

package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js

@@ -44,7 +44,7 @@
 import { gh as defaultGh } from '../../../gh-exec.js';
 import { Logger } from '../../../Logger.js';
 import { computeChangeSet as defaultComputeChangeSet } from '../../change-set.js';
-import { normalizePrTitle } from './normalize-pr-title.js';
+import { buildPullRequestFields } from './normalize-pr-title.js';
 
 /**
  * Pick the PR this head branch should resolve to from a `gh pr list
@@ -112,6 +112,7 @@ function probeEmptyDiff({ cwd, baseBranch, storyBranch, computeChangeSet }) {
  *   cwd: string,
  *   storyId: number,
  *   storyTitle: string,
+ *   storyBody?: string,
  *   storyBranch: string,
  *   baseBranch: string,
  *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
@@ -124,6 +125,7 @@ export async function ensurePullRequestWith({
   cwd: _cwd,
   storyId,
   storyTitle,
+  storyBody = '',
   storyBranch,
   baseBranch,
   gh = defaultGh,
@@ -185,26 +187,19 @@ export async function ensurePullRequestWith({
   }
 
   progress('PR', `Opening PR for ${storyBranch} → ${baseBranch}...`);
-  // The repo squash-merges and GitHub uses the PR title as the squash
-  // subject on `main`. A raw human issue title is not a Conventional
-  // Commit, so release-please silently counts it as 0 releasable commits
-  // (Story #3969). Normalize the title to conventional form: preserve an
-  // already-conventional `storyTitle` verbatim, otherwise synthesize a
-  // type derived from the branch's own commit subjects (default `chore`).
-  // `gh-exec` spawns `gh` against the current process cwd (the worktree),
-  // so the branch-commit read uses the same cwd.
-  const title = normalizePrTitle({
+  // The repo squash-merges and GitHub uses the PR title as the squash subject
+  // on `main`, so both fields are derived rather than typed — see
+  // `normalize-pr-title.js`. `gh-exec` spawns `gh` against the current process
+  // cwd (the worktree), so the branch read uses the same cwd.
+  const { title, body } = buildPullRequestFields({
     storyTitle,
     storyId,
+    storyBody,
     storyBranch,
     baseBranch,
     cwd: _cwd ?? process.cwd(),
+    progress,
   });
-  const body = [
-    `Closes #${storyId}`,
-    '',
-    `_Auto-opened by \`/deliver\`._`,
-  ].join('\n');
   try {
     const createResult = await gh.pr.create([
       '--base',

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

@@ -20,6 +20,11 @@ export async function handleCriticalReviewBlock({
     '',
     `The Story-scope review reported **${criticalCount} critical blocker(s)** on ${prUrl}.`,
     'Remediate the posted findings, then re-run `/deliver`.',
+    '',
+    'If you have reviewed a finding and judged it wrong, re-run close with',
+    '`--override-review-block "<reason>"` rather than merging by hand — see',
+    '`phases/review-override.js`. The override is recorded on the Story, on the',
+    'PR, and as friction telemetry.',
   ].join('\n');
   try {
     await upsertStructuredComment(provider, storyId, 'friction', body);

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

@@ -0,0 +1,157 @@
+/**
+ * phases/review-override.js — the sanctioned, logged override of a Story-scope
+ * code-review critical blocker.
+ *
+ * Split out of `phases/review-block.js`, which owns the opposite outcome: the
+ * blocker that *holds*. Keeping the two in one module meant one file owning
+ * both "park this Story" and "ship it anyway", and the override's audit trail is
+ * substantial enough — three write surfaces, each independently best-effort —
+ * to be its own reason to change.
+ *
+ * **Why an override exists at all.** A critical review finding halts
+ * `single-story-close.js` before auto-merge, and no flag overrode a review
+ * verdict: `--skip-validation` bypasses the gate chain and `--no-auto-merge`
+ * declines to arm, but neither touches the review. So an operator who had read a
+ * finding and judged it wrong could only land by merging the PR by hand, which
+ * bypasses the gate with no record anywhere of what was overridden or why. This
+ * module does not weaken the gate; it relocates that escape hatch out of an
+ * untraceable hand-merge and into a mandatory-reason audit trail.
+ *
+ * Live provenance: Story #5007 / PR #5022, where a FALSE critical blocker — an
+ * MI finding on files `delivery.quality.gates.maintainability.ignoreGlobs`
+ * exempts, which the `check-baselines.js` ratchet correctly ignored in the same
+ * run — halted a legitimate delivery with a hand-merge as the only way out.
+ */
+
+import { Logger } from '../../../Logger.js';
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../../../observability/runtime-friction.js';
+import {
+  postStructuredComment,
+  upsertStructuredComment,
+} from '../../ticketing.js';
+
+/** Cap on the reason text copied into the friction signal's `details`. */
+const REASON_SIGNAL_LIMIT = 500;
+
+/**
+ * Build the audit record posted when an operator overrides a review blocker.
+ * Pure.
+ *
+ * The body restates the count, the reason, and the fact that auto-merge was
+ * armed anyway — an override whose trail says only "overridden" is no better
+ * than the hand-merge it replaces.
+ *
+ * Module-local: an implementation detail of
+ * {@link handleOverriddenReviewBlock}, whose posted body is observable through
+ * that public entry point. Exporting it would add a public symbol no production
+ * path reaches — the exact dead-export shape this repo ratchets against.
+ *
+ * @param {{ prUrl: string, criticalCount: number, reason: string }} args
+ * @returns {string}
+ */
+function buildReviewOverrideBody({ prUrl, criticalCount, reason }) {
+  return [
+    '### Code-review blocker overridden by operator',
+    '',
+    `The Story-scope review reported **${criticalCount} critical blocker(s)** on ${prUrl}.`,
+    'The operator reviewed and rejected the finding(s) and authorized delivery',
+    'with `--override-review-block`; auto-merge was armed.',
+    '',
+    '**Recorded reason:**',
+    '',
+    `> ${reason.split('\n').join('\n> ')}`,
+    '',
+    'The findings comment on the PR is left in place unchanged — this record',
+    'sits beside it rather than resolving it.',
+  ].join('\n');
+}
+
+/**
+ * Post one audit record, swallowing the failure into a warning.
+ *
+ * Every write here is best-effort by design: an override whose audit trail
+ * partly failed must still land the delivery the operator authorized, because
+ * the close would otherwise fail for a reason the operator cannot act on. The
+ * friction signal is the durable record — it is what makes a rising override
+ * count visible to the retro.
+ *
+ * Module-local: the two call sites below are its only callers.
+ *
+ * @param {{ post: () => Promise<unknown>, surface: string }} args
+ * @returns {Promise<boolean>} true when the record landed.
+ */
+async function postAuditRecord({ post, surface }) {
+  try {
+    await post();
+    return true;
+  } catch (err) {
+    Logger.warn(
+      `[single-story-close] failed to post review-override record on ${surface}: ${err?.message ?? err}`,
+    );
+    return false;
+  }
+}
+
+/**
+ * Record an operator-authorized override of a critical code-review blocker,
+ * then let close continue to the auto-merge phase.
+ *
+ * Writes to three surfaces: the Story issue via `upsert` so a re-run does not
+ * stack duplicates; the PR via `post` so the trail is append-only on the surface
+ * a human reviews, and so a reviewer reading the PR need not open the Story to
+ * learn the blocker was overridden; and the friction stream.
+ *
+ * @param {{
+ *   provider: object,
+ *   storyId: number,
+ *   prUrl: string,
+ *   prNumber: number|null,
+ *   criticalCount: number,
+ *   reason: string,
+ *   config?: object,
+ *   emitFrictionFn?: typeof emitRuntimeFriction,
+ * }} args
+ * @returns {Promise<{ overridden: true, reason: string, criticalCount: number }>}
+ */
+export async function handleOverriddenReviewBlock({
+  provider,
+  storyId,
+  prUrl,
+  prNumber,
+  criticalCount,
+  reason,
+  config,
+  emitFrictionFn = emitRuntimeFriction,
+}) {
+  const body = buildReviewOverrideBody({ prUrl, criticalCount, reason });
+  Logger.warn(
+    `[single-story-close] ⚠️ Story-scope review reported ${criticalCount} critical blocker(s) on ` +
+      `PR ${prUrl} — OVERRIDDEN by operator: ${reason}`,
+  );
+  await postAuditRecord({
+    post: () => upsertStructuredComment(provider, storyId, 'friction', body),
+    surface: `Story #${storyId}`,
+  });
+  if (Number.isInteger(prNumber)) {
+    await postAuditRecord({
+      post: () =>
+        postStructuredComment(provider, prNumber, 'notification', body),
+      surface: `PR #${prNumber}`,
+    });
+  }
+  await emitFrictionFn({
+    storyId,
+    category: RUNTIME_FRICTION_CATEGORIES.REVIEW_BLOCK_OVERRIDDEN,
+    tool: 'single-story-close',
+    details: {
+      prUrl,
+      criticalCount,
+      reason: reason.slice(0, REASON_SIGNAL_LIMIT),
+    },
+    config,
+  });
+  return { overridden: true, reason, criticalCount };
+}