mandrel 2.30.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/push.js

@@ -15,6 +15,18 @@
  * added because it would re-ask a question the push exit code already
  * answered authoritatively.
  *
+ * Issue #4990 — the push runs in the Story worktree, not the main
+ * checkout. `core.hooksPath` is the relative `.husky/_`, so the
+ * invocation directory is what selects which tree `pre-push` resolves
+ * and measures. Pushing from the main checkout therefore validated a
+ * tree other than the one being sent — false red when that checkout sat
+ * on unrelated work, and worse, false green whenever it happened to be
+ * clean. `worktreePath` falls back to `cwd` because single-tree mode and
+ * a disabled `delivery.worktreeIsolation` both legitimately have no
+ * worktree, and there the main checkout IS the tree being pushed. The
+ * two sibling phases resolve their tree the same way
+ * (`base-sync.js`, `close-validation.js`).
+ *
  * `gitSync` is accepted as an injected dependency rather than statically
  * imported so the caller's (cache-busted) binding wins. The
  * `single-story-close.js` orchestrator owns the static import; test
@@ -29,6 +41,7 @@ import { gitSync as defaultGitSync } from '../../../git-utils.js';
  *
  * @param {{
  *   cwd: string,
+ *   worktreePath?: string|null,
  *   storyBranch: string,
  *   gitSync?: typeof defaultGitSync,
  *   progress: (tag: string, msg: string) => void,
@@ -36,6 +49,7 @@ import { gitSync as defaultGitSync } from '../../../git-utils.js';
  */
 export function pushStoryBranch({
   cwd,
+  worktreePath = null,
   storyBranch,
   gitSync = defaultGitSync,
   progress,
@@ -46,8 +60,9 @@ export function pushStoryBranch({
     // before this point, but `--skip-validation` skips that chain, and the
     // bypass then left nothing running at all. `pre-push` is the backstop,
     // and it only became reachable once hooks were materialized into
-    // worktrees — which is where every Story branch is built.
-    gitSync(cwd, 'push', '-u', 'origin', storyBranch);
+    // worktrees — which is where every Story branch is built, and where the
+    // cwd below now resolves so the hook reads that tree.
+    gitSync(worktreePath ?? cwd, 'push', '-u', 'origin', storyBranch);
     progress('GIT', `✅ Pushed ${storyBranch}.`);
   } catch (err) {
     throw new Error(

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);