mandrel 2.59.0 → 2.61.0

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

@@ -1,52 +1,14 @@
 /**
- * conventional-subject.js — the pure Conventional-Commit rules behind the
- * squash-merge subject a standalone Story lands on `main`.
- *
- * Split out of `normalize-pr-title.js` so the rules that decide
- * what the release notes say are testable without a git read. The three rules
- * here each closed a defect observed live on `main`:
- *
- *   1. **Type precedence follows release impact.** A multi-commit Story used
- *      to resolve its type off a hand-ordered list in which `docs` outranked
- *      `chore` for no stated reason. Story #5004 (`chore(gates)`, `docs(ci)`,
- *      `chore(baselines)`) therefore landed as
- *      `docs: check/CI gate sweep …` — a change that deleted five
- *      `lib/checks` modules, two CLIs and a dependency, filed under
- *      documentation. `TYPE_RANK` now mirrors `changelog-sections` in
- *      `release-please-config.json`: rank IS how visible the type is in the
- *      release notes. Types that render identically (the six `hidden: true`
- *      ones) share a rank, because there is no honest ordering between them —
- *      those ties break on how much of the branch carries the type, then on
- *      the Story's primary (oldest) commit.
- *
- *   2. **Casing leaves acronyms alone.** The old synthesizer lowercased the
- *      first character unconditionally to satisfy commitlint's `subject-case`
- *      rule, which turned Story #5002's "CRAP surface diet" into
- *      `refactor: cRAP surface diet`. `shapeDescription` lowercases only when
- *      the leading word is not an all-caps token, so CRAP / CI / QA / API
- *      survive. That is a deliberate, narrow trade: commitlint's
- *      `subject-case` treats ANY leading capital as sentence-case and would
- *      flag `CRAP surface diet` — but commitlint never runs on a PR title or
- *      a GitHub squash subject (see `rules/git-conventions.md` §
- *      Conventional Commits), so the rule it would fail is not a gate this
- *      subject passes through, while a mangled acronym is permanent in the
- *      changelog.
- *
- *   3. **A breaking change survives the squash.** release-please only sees a
- *      breaking change through a `!` in the subject or a `BREAKING CHANGE:`
- *      footer. Story #5004 removed `project.commands.lintBaseline` from a
- *      schema block that is `additionalProperties: false` — a hard consumer
- *      break — described in prose in the commit body and therefore invisible
- *      to the parser. `collectBreakingNotes` reads the footer out of any
- *      constituent commit (or a Story-body declaration) and `markBreaking`
- *      puts the `!` where the parser looks.
+ * conventional-subject.js — pure Conventional-Commit rules for the squash
+ * subject a Story lands on `main`: type precedence by release impact,
+ * acronym-safe casing (commitlint never sees a squash subject, but a mangled
+ * acronym is permanent in the changelog), and a breaking change that
+ * survives the squash as a `!`.
  */
 
 /**
- * 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.
+ * Mirrors commitlint `type-enum` and release-please `changelog-sections`;
+ * kept in sync by hand.
  */
 const CONVENTIONAL_TYPES = Object.freeze([
   'feat',
@@ -63,11 +25,8 @@ const CONVENTIONAL_TYPES = Object.freeze([
 ]);
 
 /**
- * Release-impact rank per type — LOWER wins. Derived from
- * `changelog-sections` in `release-please-config.json`: the five types that
- * render a visible section are ordered by how much a reader needs to see
- * them, and the six `hidden: true` types share the bottom rank because the
- * release notes draw no distinction between them.
+ * Release-impact rank, LOWER wins, from `changelog-sections`; the hidden
+ * types tie because the release notes don't distinguish them.
  *
  * @type {Readonly<Record<string, number>>}
  */
@@ -85,48 +44,28 @@ const TYPE_RANK = Object.freeze({
   ci: 5, // hidden
 });
 
-/** Rank for a type absent from `TYPE_RANK` — always loses. */
 const UNRANKED = Number.MAX_SAFE_INTEGER;
 
 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.
+// <type>(<scope>)?!?: <description> — the shape config-conventional enforces.
 const CONVENTIONAL_HEADER_RE = new RegExp(
   `^(?:${TYPE_GROUP})(?:\\([^()\\r\\n]+\\))?!?: \\S.*$`,
 );
 const LEADING_TYPE_RE = new RegExp(
   `^(${TYPE_GROUP})(?:\\([^()\\r\\n]+\\))?(!?):`,
 );
-// Splits a conventional header into `<type><scope?>`, `<!?>`, `<description>`
-// so the breaking marker can be inserted at the one position the parser reads.
 const HEADER_PARTS_RE = new RegExp(
   `^((?:${TYPE_GROUP})(?:\\([^()\\r\\n]+\\))?)(!?): (.*)$`,
 );
 
-/**
- * The Conventional-Commits breaking footer, in both spellings the spec
- * defines (`BREAKING CHANGE:` and the hyphenated `BREAKING-CHANGE:`). Case is
- * significant — the spec requires uppercase, and so does
- * `conventional-commits-parser`'s default `noteKeywords`, so matching
- * case-insensitively here would announce breaks release-please will not.
- */
+/** Case-sensitive, as the parser's `noteKeywords` are. */
 const BREAKING_FOOTER_RE = /^BREAKING[ -]CHANGE:[ \t]*(.*)$/;
 
-/** A git-trailer-shaped line (`Some-Token: value`) — ends a footer's text. */
 const TRAILER_RE = /^[A-Za-z][A-Za-z-]*:[ \t]/;
-/** An opening or closing markdown code fence: ``` or ~~~, optionally indented. */
 const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})/;
 
 /**
- * True iff `subject` is a parseable Conventional Commit subject under the
- * repo's type vocabulary. Pure.
- *
  * @param {string} subject
  * @returns {boolean}
  */
@@ -136,9 +75,6 @@ export function isConventionalSubject(subject) {
 }
 
 /**
- * Extract the Conventional-Commit `type` from a single commit subject, or
- * `null` when the subject is not conventional. Pure.
- *
  * @param {string} subject
  * @returns {string|null}
  */
@@ -149,10 +85,8 @@ function parseConventionalType(subject) {
 }
 
 /**
- * Order two type candidates: release impact first, then how much of the
- * branch carries the type, then the earliest commit that used it. The second
- * and third keys only ever decide a tie inside the hidden tier — every
- * visible type holds its rank alone.
+ * Rank, then commit count, then earliest use (the tie-breaks only matter in
+ * the hidden tier).
  *
  * @param {{rank: number, count: number, firstIndex: number}} a
  * @param {{rank: number, count: number, firstIndex: number}} b
@@ -165,12 +99,8 @@ function compareTypeCandidates(a, b) {
 }
 
 /**
- * Pick the type the squash subject should carry from the branch's own commit
- * subjects. Returns `null` when no subject is conventional.
- *
- * `subjects` MUST be oldest-first: the final tie-break reads index 0 as the
- * Story's primary commit, the one whose type the operator chose before any
- * fixup or baseline-refresh commit piled on.
+ * `subjects` MUST be oldest-first: the last tie-break treats index 0 as the
+ * Story's primary commit.
  *
  * @param {string[]} subjects Commit subjects, oldest first.
  * @returns {string|null}
@@ -199,11 +129,8 @@ export function pickDominantType(subjects) {
 }
 
 /**
- * True when the leading word of `text` is an all-caps token — an acronym the
- * synthesizer must not touch. Requires two or more letters so a stray leading
- * "A" or "I" still lowercases; punctuation and digits are ignored so
- * `CRAP:`, `CI/CD` and `API-surface` all read as acronyms while `A11y` does
- * not.
+ * Leading all-caps word of 2+ letters (non-letters ignored), so `CI/CD` is an
+ * acronym but a lone "A" or `A11y` is not.
  *
  * @param {string} text
  * @returns {boolean}
@@ -215,10 +142,7 @@ function leadsWithAcronym(text) {
 }
 
 /**
- * Shape a human Story title into the description half of a synthesized
- * Conventional-Commit subject: lowercase the first character so the subject
- * reads as a sentence fragment, EXCEPT when the leading word is an acronym.
- * Pure.
+ * Lowercase the first character unless the leading word is an acronym.
  *
  * @param {string} text
  * @returns {string}
@@ -231,10 +155,7 @@ export function shapeDescription(text) {
 }
 
 /**
- * Insert the breaking-change `!` into a conventional subject, at the one
- * position `conventional-commits-parser` reads it: immediately before the
- * colon, after any scope. A subject that already carries `!`, or that is not
- * conventional, is returned unchanged. Pure.
+ * Insert `!` before the colon (after any scope); otherwise unchanged.
  *
  * @param {string} subject
  * @returns {string}
@@ -248,9 +169,7 @@ export function markBreaking(subject) {
 }
 
 /**
- * Pull the text of one `BREAKING CHANGE:` footer out of `lines`, starting at
- * the footer line itself. The note runs to the end of its paragraph: a blank
- * line, another trailer, or the end of the message closes it.
+ * A footer note runs until a blank line, another trailer, or the end.
  *
  * @param {string[]} lines
  * @param {number} start Index of the matched footer line.
@@ -271,22 +190,8 @@ function readFooterNote(lines, start, head) {
 }
 
 /**
- * Scan one commit message (or the Story body) for breaking-change evidence.
- *
- * @param {string} text
- * @param {boolean} readHeaderBang Whether line 0 is a commit header whose `!`
- *   counts. False for the Story body, which has no header.
- * @returns {{ breaking: boolean, notes: string[], subject: string|null }}
- */
-/**
- * Blank every line inside a markdown code fence, keeping line indices intact.
- *
- * A Story `## Spec` that documents this very contract quotes the footer in a
- * fence; reading that as a declaration ships a `<type>!:` subject and a release
- * note for a break nobody made. Fenced spans are the only place the anchored
- * footer regex can fire on non-footer text — an indented block or a blockquote
- * already fails the `^` anchor. Blanking rather than dropping means a fence
- * also closes an open footer note, which is what a paragraph break would do.
+ * Blank lines inside code fences, so a quoted footer is not a declaration;
+ * blanking (not dropping) keeps indices and closes an open note.
  *
  * @param {string[]} lines
  * @returns {string[]}
@@ -302,6 +207,11 @@ function blankFencedLines(lines) {
   });
 }
 
+/**
+ * @param {string} text
+ * @param {boolean} readHeaderBang False for the Story body, which has no header.
+ * @returns {{ breaking: boolean, notes: string[], subject: string|null }}
+ */
 function scanForBreaking(text, readHeaderBang) {
   const lines = blankFencedLines(String(text ?? '').split('\n'));
   const notes = [];
@@ -334,23 +244,9 @@ function scanForBreaking(text, readHeaderBang) {
 }
 
 /**
- * Collect the branch's breaking-change declarations.
- *
- * Two sources, both honoured:
- *
- *   - **Any constituent commit** — a `BREAKING CHANGE:` / `BREAKING-CHANGE:`
- *     footer, or a `!` in the header. This is the path a maker takes while
- *     writing the commit that does the breaking.
- *   - **The Story body** — the same footer, written as its own line anywhere
- *     in the Story issue (the `## Spec` block is the natural home). This is
- *     the declarative path: `/mandrel-plan` can state the break up front and close
- *     propagates it even when no individual commit remembered the footer.
- *     Only the footer form counts; prose describing a break does not, because
- *     a keyword-free sentence is exactly what release-please cannot parse.
- *
- * When something is breaking but no footer supplied text, the `!` commit's
- * own description becomes the note — the fallback Conventional Commits
- * itself prescribes for a `!` header with no footer.
+ * Breaking declarations from any commit (footer or header `!`) or a footer
+ * line in the Story body; prose never counts. With no footer text, the `!`
+ * commit's description is the note, per the spec.
  *
  * @param {{ commitMessages?: string[], storyBody?: string }} args
  * @returns {{ breaking: boolean, notes: string[] }}

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

@@ -0,0 +1,96 @@
+/**
+ * phases/graphql-preflight.js — refuse the close during `init` when GitHub
+ * GraphQL (which all of `gh pr` needs) is unreachable, before any gate runs
+ * or anything is pushed. It must never fail a healthy close: ambiguous or
+ * throwing probes are fail-open.
+ */
+
+import {
+  describeGraphqlPreflight,
+  probeGraphqlAvailability,
+} from '../../../gh-exec.js';
+import { Logger } from '../../../Logger.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+  upsertStructuredComment,
+} from '../../ticketing.js';
+
+/**
+ * Best-effort: a notification failure must not replace the real blocker.
+ * Canonical mutators only, so the Projects v2 column syncs.
+ *
+ * @param {{ provider: object, storyId: number, reason: string,
+ *   progress: (tag: string, msg: string) => void }} args
+ * @returns {Promise<void>}
+ */
+async function announcePreflightBlock({ provider, storyId, reason, progress }) {
+  const body = [
+    '### Close refused during `init`: GitHub GraphQL preflight',
+    '',
+    reason,
+    '',
+    'Nothing was validated, committed, or pushed — the preflight runs before the',
+    'gate chain, so re-running close from a session that can reach GraphQL starts',
+    'from exactly where this Story stands now:',
+    '',
+    '```bash',
+    `node .agents/scripts/single-story-close.js --story ${storyId}`,
+    '```',
+  ].join('\n');
+  try {
+    await upsertStructuredComment(provider, storyId, 'friction', body);
+    progress('PREFLIGHT', `📝 Posted friction comment on #${storyId}.`);
+  } catch (err) {
+    Logger.warn?.(
+      `[single-story-close] ⚠️ Failed to post preflight friction comment on #${storyId}: ${err?.message ?? err}`,
+    );
+  }
+  try {
+    await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {});
+    progress('PREFLIGHT', `🚧 Flipped Story #${storyId} → agent::blocked.`);
+  } catch (err) {
+    Logger.warn?.(
+      `[single-story-close] ⚠️ Failed to flip Story #${storyId} to agent::blocked: ${err?.message ?? err}`,
+    );
+  }
+}
+
+/**
+ * A throwing (injected) probe is treated as available.
+ *
+ * @param {{
+ *   storyId: number,
+ *   provider: object,
+ *   progress: (tag: string, msg: string) => void,
+ *   ghFacade?: { api: Function },
+ *   probe?: typeof probeGraphqlAvailability,
+ * }} args `ghFacade` is the run's own, so it asks the same boundary the PR phase will.
+ * @returns {Promise<{ verdict: string, reason: string }|null>} null to proceed.
+ */
+export async function runGraphqlPreflight({
+  storyId,
+  provider,
+  progress,
+  ghFacade,
+  probe = probeGraphqlAvailability,
+}) {
+  let verdict;
+  try {
+    verdict = await probe(ghFacade ? { ghFacade } : undefined);
+  } catch (err) {
+    progress(
+      'PREFLIGHT',
+      `⚠️ GraphQL preflight could not run (close continues): ${err?.message ?? err}`,
+    );
+    return null;
+  }
+  if (verdict?.available !== false) {
+    progress('PREFLIGHT', `✅ GitHub GraphQL reachable (${verdict?.reason}).`);
+    return null;
+  }
+  const reason = describeGraphqlPreflight(verdict);
+  progress('PREFLIGHT', `🛑 ${reason}`);
+  await announcePreflightBlock({ provider, storyId, reason, progress });
+  return { verdict: verdict.verdict, reason };
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/lock-wait-pending.js

@@ -0,0 +1,49 @@
+/**
+ * phases/lock-wait-pending.js — a close whose full-suite lock wait expired
+ * ends `pending`, not `failed`: nothing was spawned, pushed or labelled, so
+ * the next command is the same close.
+ */
+import {
+  buildTerminalEnvelope,
+  NEXT_COMMANDS,
+} from '../../story-deliver-terminal.js';
+
+/**
+ * @param {{
+ *   storyId: number,
+ *   storyBranch: string,
+ *   baseBranch: string,
+ *   lockWait: { waitedSeconds: number, expired: boolean }|null,
+ *   elapsedSeconds: number,
+ * }} args
+ * @returns {{ result: object, terminal: object, note: string }} The close
+ *   result, the validated `pending` envelope, and the operator line.
+ */
+export function lockWaitPending({
+  storyId,
+  storyBranch,
+  baseBranch,
+  lockWait,
+  elapsedSeconds,
+}) {
+  const nextCommand = NEXT_COMMANDS.close(storyId);
+  return {
+    result: {
+      storyId,
+      standalone: true,
+      action: 'deferred',
+      reason: 'full-suite-lock-wait-expired',
+    },
+    terminal: buildTerminalEnvelope({
+      storyId,
+      status: 'pending',
+      phase: 'close-validation',
+      storyBranch,
+      baseBranch,
+      lockWait,
+      nextCommand,
+      elapsedSeconds,
+    }),
+    note: `⏸  Story #${storyId}: another full suite held the host lock past the wait budget — resume with: ${nextCommand}`,
+  };
+}

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

@@ -1,41 +1,8 @@
 /**
- * normalize-pr-title.js — guarantee the standalone-Story PR title is a
- * valid Conventional Commit subject so the squash-merge subject on `main`
- * parses for release-please.
- *
- * Story #3969 (framework gap). The repo squash-merges, and GitHub uses the
- * PR title as the squash-commit subject. `buildPullRequest` previously
- * emitted the raw human issue title (`<storyTitle> (#<id>)`), which is a
- * plain description ("Rename the published npm package…") that
- * release-please's Conventional-Commit parser rejects:
- *
- *   ❯ commit could not be parsed: … Rename the published npm package …
- *   ❯ error: unexpected token ' ' at 1:7, valid tokens [(, !, :]
- *   ❯ commits: 0  → no release cut
- *
- * The `commit-msg` commitlint Husky hook only validates *local* commits and
- * never runs on a GitHub-UI squash-merge title, so nothing mechanized the
- * documented "author the PR title in conventional form" contract. This
- * module mechanizes it.
- *
- * Contract (pure where possible — the only side effect is an injectable
- * `git log` read):
- *
- *   - If `storyTitle` is **already** a parseable Conventional Commit
- *     subject, it is preserved verbatim and suffixed with `(#<storyId>)`.
- *     No re-prefixing, no double type.
- *   - Otherwise the title is **synthesized** into conventional form:
- *     `<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.
- *
- * 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.
+ * normalize-pr-title.js — make the PR title (GitHub's squash subject) a
+ * Conventional Commit so release-please can parse it; commitlint never sees
+ * a squash title. The subject rules live in `conventional-subject.js`; this
+ * module does the git read and assembles the `gh pr create` strings.
  */
 
 import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
@@ -48,28 +15,14 @@ import {
   shapeDescription,
 } from './conventional-subject.js';
 
-/** Safe default Conventional-Commit type when none can be derived. */
 const DEFAULT_CONVENTIONAL_TYPE = 'chore';
 
-/**
- * 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.
- */
+/** NUL cannot occur in a commit message, so a body cannot forge a split. */
 const RECORD_SEP = '\u0000';
 
 /**
- * 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.
- *
- * 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.
- *
- * Oldest-first (`--reverse`) is load-bearing: `pickDominantType` breaks a tie
- * on the Story's primary commit, which is the first one authored.
+ * Whole messages (bodies carry the breaking footer), oldest-first for the
+ * type tie-break. A failed read returns `[]`, degrading to safe defaults.
  *
  * @param {{
  *   storyBranch: string,
@@ -119,16 +72,8 @@ function readBranchCommits({
 }
 
 /**
- * Produce the PR title and the breaking-change notes that belong with it.
- *
- *   - Already-conventional `storyTitle` → preserved verbatim + `(#<id>)`.
- *   - Otherwise → `<derivedType>: <shaped storyTitle> (#<id>)`.
- *   - Empty / missing `storyTitle` → `<derivedType>: story #<id>`.
- *   - Breaking → `!` inserted before the colon in either shape.
- *
- * `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.
+ * A conventional title is kept verbatim; prose is synthesized as
+ * `<derivedType>: <shaped title>`. Either gets `(#<id>)` and, if breaking, `!`.
  *
  * @param {{
  *   storyTitle: string,
@@ -151,9 +96,6 @@ function normalizePrTitle({
     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 });
@@ -163,8 +105,6 @@ function normalizePrTitle({
 }
 
 /**
- * Build a conventional subject for a Story whose title is plain prose.
- *
  * @param {{ description: string, storyId: number|string, commitMessages: string[] }} args
  * @returns {string}
  */
@@ -176,16 +116,8 @@ function synthesizeSubject({ description, storyId, commitMessages }) {
 }
 
 /**
- * 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.
+ * `Closes #<id>` auto-closes the Story; a breaking footer goes LAST, per the
+ * spec, for repos that squash with the PR body.
  *
  * @param {{ storyId: number|string, breakingNotes?: string[] }} args
  * @returns {string}
@@ -203,13 +135,8 @@ function buildPrBody({ storyId, breakingNotes }) {
 }
 
 /**
- * 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.
+ * A declared break is announced on progress so an unexpected `!` is seen
+ * during the close, not in the release notes.
  *
  * @param {{ storyTitle: string, storyId: number|string, storyBody?: string,
  *   storyBranch: string, baseBranch: string, cwd?: string,