mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/cli-args.js

@@ -1,12 +1,7 @@
 import { parseArgs } from 'node:util';
 
 /**
- * Parse a single ticket-ID-style value. Strips an optional leading `#`,
- * coerces to a positive integer, and returns `null` for anything invalid.
- *
- * Shared by every CLI that accepts `--epic`, `--story`, `--task`, `--recut-of`,
- * or a ticket positional, so the `Number.parseInt(..., 10)` + `# ` prefix dance lives
- * in exactly one place.
+ * Positive integer with an optional leading `#`; `null` when invalid.
  *
  * @param {string|number|null|undefined} value
  * @returns {number|null}
@@ -21,10 +16,7 @@ export function parseTicketId(value) {
 }
 
 /**
- * Coerce a value returned by `node:util`'s `parseArgs` for a boolean flag into
- * a real boolean. Under `strict: false`, `--flag=true` / `--flag=false` arrive
- * here as the literal strings `'true'` / `'false'`, while bare `--flag` lands
- * as `true`. Absence yields `undefined`, which collapses to `false`.
+ * Under `strict: false`, `--flag=false` arrives as the string `'false'`.
  *
  * @param {boolean|string|null|undefined} value
  * @returns {boolean}
@@ -47,11 +39,8 @@ function optionalBooleanFlag(value) {
 }
 
 /**
- * Parse a positive-integer flag, preserving `undefined` when the flag is
- * absent so a caller can distinguish "not supplied" (fall back to config)
- * from an explicit value. A non-numeric or non-positive value is treated as
- * absent rather than coerced to 0 — a `--max-wait-seconds=abc` typo must not
- * silently become a zero-second wait.
+ * `undefined` when absent (caller falls back to config). Junk is treated as
+ * absent, never coerced to 0.
  *
  * @param {unknown} value
  * @returns {number|undefined}
@@ -63,11 +52,7 @@ function parsePositiveInt(value) {
 }
 
 /**
- * The same contract for a flag whose ZERO is meaningful (Story #5266):
- * `--rerun-advisory 0` is an explicit "spend nothing", not an absent flag.
- * A negative or non-numeric value is still treated as absent rather than
- * coerced, so a typo falls back to the config default instead of inventing an
- * allowance that spends the consumer's CI minutes.
+ * As {@link parsePositiveInt}, for a flag whose zero is meaningful.
  *
  * @param {unknown} value
  * @returns {number|undefined}
@@ -78,22 +63,11 @@ function parseNonNegativeInt(value) {
   return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
 }
 
-/** The only two merge-watch postures `--merge-watch-mode` accepts. */
 const MERGE_WATCH_MODES = ['sync', 'async'];
 
 /**
- * Parse `--merge-watch-mode` (Story #4949), the per-invocation override of
- * `delivery.mergeWatch.mode`. Absence is preserved as `undefined` so the
- * caller can distinguish "not supplied" (fall back to config) from an explicit
- * posture — the same contract {@link parsePositiveInt} gives
- * `--max-wait-seconds`.
- *
- * Unlike that sibling, an unrecognized value **throws** rather than degrading
- * to absent. A `--max-wait-seconds` typo falls back to a sane bound; a
- * `--merge-watch-mode` typo would fall back to `sync` and silently return a
- * multi-Story run to a serialized foreground wait per close, with the wall
- * clock as the only evidence. Parsing runs before the first close phase, so
- * failing here costs no mutation.
+ * `undefined` when absent. An unrecognized value throws: degrading to `sync`
+ * would silently serialize a multi-Story run. Runs before any mutation.
  *
  * @param {unknown} value
  * @returns {'sync'|'async'|undefined}
@@ -108,11 +82,7 @@ export function parseMergeWatchMode(value) {
 }
 
 /**
- * {@link parseMergeWatchMode} degraded to the "absent" value instead of
- * throwing — how the tolerant parse below treats a flag that failed
- * validation. Reporting `undefined` is safe there and only there, because a
- * tolerant parse never drives a pipeline: its caller surfaces the rejection
- * as the run's failure and runs no phase at all.
+ * Non-throwing variant; safe only because a tolerant parse runs no phase.
  *
  * @param {unknown} value
  * @returns {'sync'|'async'|undefined}
@@ -125,25 +95,13 @@ function tolerantMergeWatchMode(value) {
   }
 }
 
-/**
- * Shortest override reason that can plausibly name a rejected finding. Below
- * this, the flag is being used to silence the gate rather than to record a
- * judgement, which is the failure mode the reason requirement exists to stop.
- */
+/** Shorter than this, the reason silences the gate rather than records why. */
 const MIN_OVERRIDE_REASON_LENGTH = 12;
 
 /**
- * Parse `--override-review-block <reason>` — the sanctioned,
- * logged override of a Story-scope code-review critical blocker.
- *
- * The reason is **mandatory and validated**, because the alternative it
- * replaces is not "no override" but `gh pr merge` run by hand: before this
- * flag, a review blocker the operator had reviewed and rejected left bypassing
- * the gate entirely as the only way to land, and that bypass wrote nothing
- * down anywhere. An override that records why is strictly more auditable than
- * the hand-merge it displaces; an override that records nothing is not, so a
- * bare or blank `--override-review-block` fails closed here — before any phase
- * runs, at no mutation cost — rather than arming a silent one.
+ * The logged override of a code-review critical blocker. The reason is
+ * mandatory: a bare flag throws before any phase rather than arming a silent
+ * override.
  *
  * @param {unknown} value
  * @returns {string|undefined} the trimmed reason, or `undefined` when absent.
@@ -162,10 +120,7 @@ export function parseOverrideReviewBlock(value) {
 }
 
 /**
- * {@link parseOverrideReviewBlock} degraded to absent instead of throwing, for
- * the tolerant reporting parse. Same contract as
- * {@link tolerantMergeWatchMode}: safe only because a tolerant parse runs no
- * phase.
+ * Non-throwing variant, as {@link tolerantMergeWatchMode}.
  *
  * @param {unknown} value
  * @returns {string|undefined}
@@ -179,13 +134,8 @@ function tolerantOverrideReviewBlock(value) {
 }
 
 /**
- * Standardized CLI argument parser for sprint scripts.
- * Supports options like --epic, --story, --dry-run, --skip-dashboard.
- *
- * Throws when a *validating* parser rejects a flag value (currently only
- * `--merge-watch-mode`). Callers that must not throw — an error handler
- * needing `storyId` to report an envelope — use {@link parseSprintArgsTolerant}
- * rather than calling this a second time inside their own catch.
+ * Throws when a validating flag parser rejects a value; error handlers use
+ * {@link parseSprintArgsTolerant} instead of re-calling this.
  *
  * @param {string[]} args Array of arguments (defaults to process.argv)
  * @param {{ tolerant?: boolean }} [options] `tolerant` degrades a rejected
@@ -209,21 +159,10 @@ export function parseSprintArgs(
       // No default — absent means "use delivery.routing.closeAndLand".
       'wait-merge': { type: 'boolean' },
       'no-wait-merge': { type: 'boolean', default: false },
-      // Story #4543 — per-run override of `delivery.mergeWatch.maxWaitSeconds`
-      // (the merge wait's per-invocation bound). Absent means "use the config".
+      // The next three override `delivery.*` config when present.
       'max-wait-seconds': { type: 'string' },
-      // Story #4949 — per-invocation override of `delivery.mergeWatch.mode`.
-      // Absent means "use the config"; see `parseMergeWatchMode` for why an
-      // unrecognized value fails closed instead of degrading to absent.
       'merge-watch-mode': { type: 'string' },
-      // Story #5266 — per-invocation override of `delivery.ci.rerunAdvisory`.
-      // Absent means "use the config", whose default is 0: close re-runs
-      // nothing and mutates no GitHub state on an advisory red unless asked.
       'rerun-advisory': { type: 'string' },
-      // Sanctioned override of a code-review critical blocker.
-      // Absent means "the blocker blocks"; see `parseOverrideReviewBlock` for
-      // why a bare or too-short reason fails closed instead of arming a silent
-      // override.
       'override-review-block': { type: 'string' },
       executor: { type: 'string' },
       cwd: { type: 'string' },
@@ -244,45 +183,23 @@ export function parseSprintArgs(
     skipValidation: coerceBooleanFlag(values['skip-validation']),
     skipSync: coerceBooleanFlag(values['skip-sync']),
     noAutoMerge: coerceBooleanFlag(values['no-auto-merge']),
-    // Close-and-land: `--wait-merge` forces land-in-close; `--no-wait-merge`
-    // opts out. When neither flag is present (`undefined`),
-    // `parseCloseOptions` applies `delivery.routing.closeAndLand` (default
-    // true) so attended and headless delivers share the same happy path.
+    // `undefined` when neither flag is present: config `closeAndLand` decides.
     waitForMerge: optionalBooleanFlag(values['wait-merge']),
     noWaitForMerge: coerceBooleanFlag(values['no-wait-merge']),
-    // Story #4543 — raise the merge wait's per-invocation bound for a
-    // headless caller with no host tool-invocation ceiling, so it lands in
-    // one block instead of returning `pending` at the default 300s.
     maxWaitSeconds: parsePositiveInt(values['max-wait-seconds']),
-    // Story #4949 — per-invocation override of `delivery.mergeWatch.mode`.
-    // `undefined` when the flag is absent, which is what lets the merge wait
-    // fall back to the config; anything unrecognized throws here.
     mergeWatchMode: tolerant
       ? tolerantMergeWatchMode(values['merge-watch-mode'])
       : parseMergeWatchMode(values['merge-watch-mode']),
-    // Story #5266 — how many times close may re-run a failed ADVISORY run
-    // before blocking on it. `undefined` when absent, which is what lets the
-    // merge wait fall back to `delivery.ci.rerunAdvisory` (default 0).
-    // `parseNonNegativeInt` degrades a junk value to undefined rather than
-    // guessing an allowance that would spend the consumer's CI minutes.
     rerunAdvisory: parseNonNegativeInt(values['rerun-advisory']),
-    // The operator's recorded reason for overriding a review
-    // blocker. `undefined` when the flag is absent, which is what keeps the
-    // blocker blocking by default.
     overrideReviewBlock: tolerant
       ? tolerantOverrideReviewBlock(values['override-review-block'])
       : parseOverrideReviewBlock(values['override-review-block']),
     executor: values.executor ?? null,
-    // Resolve worktree cwd from flag or env. Empty string/whitespace → null.
     cwd:
       (typeof values.cwd === 'string' && values.cwd.trim()) ||
       process.env.AGENT_WORKTREE_ROOT ||
       null,
     recutOf: parseTicketId(values['recut-of']),
-    // Story #4253: pre-resolved Epic linkage threaded by the /mandrel-deliver
-    // fan-out so `single-story-init.js` can skip redundant Epic lookups when
-    // the parent already threaded Epic context (pre-v2; field retained for
-    // CLI compatibility).
     resume: values.resume ?? false,
     restart: values.restart ?? false,
   };
@@ -294,9 +211,6 @@ export function parseSprintArgs(
 }
 
 /**
- * Last-resort tolerant parse: the fields, or an empty bag if even the
- * tolerant pass cannot produce one.
- *
  * @param {string[]} args
  * @returns {object}
  */
@@ -309,24 +223,9 @@ function parseSprintArgsOrEmpty(args) {
 }
 
 /**
- * Parse argv **without ever throwing**, returning the fields alongside the
- * rejection rather than in place of it.
- *
- * `parseSprintArgs` gained its first *validating* parser in
- * {@link parseMergeWatchMode} (Story #4949), which made a latent shape in the
- * CLI entries fatal: their catch blocks called
- * `failedTerminalFor(err, parseSprintArgs())` — re-invoking the very parser
- * that had just thrown. The second throw escaped the catch, so an
- * unparseable argv produced a bare stack trace with **no terminal envelope
- * and no friction signal**, on the two surfaces whose whole contract is that
- * they always emit one. An error handler must not depend on an operation
- * already known to fail.
- *
- * So the entries parse **once**, up front, through this wrapper: `args`
- * carries the `storyId` and skip flags the envelope is built from, and
- * `error` is the failure to report. The tolerant re-parse degrades **only**
- * the flag that failed validation; every other field parses normally. Use
- * the result to *report*, never to run a pipeline.
+ * Never throws: returns the fields alongside the rejection, so an entry's
+ * error handler can still build its terminal envelope. Only the failing flag
+ * degrades. Use the result to report, never to run a pipeline.
  *
  * @param {string[]} [args] Array of arguments (defaults to `process.argv`)
  * @returns {{ args: object, error: Error|null }}
@@ -365,31 +264,6 @@ function coerceValue(type, raw) {
   return raw;
 }
 
-/**
- * Declarative argv parser used by every top-level script under
- * `.agents/scripts/`. Replaces the hand-rolled `parseCliArgs` walkers that
- * the `tests/enforcement/parse-cli-args.test.js` enforcement gate forbids.
- *
- * Spec entry shape:
- *   { type, alias?, default?, envKey?, optionalValue?, short? }
- *
- *   - `type`: 'boolean' | 'ticket' | 'integer' | 'string' | 'string-multi'.
- *     'ticket' coerces via `parseTicketId` (positive int, leading `#` stripped,
- *     `null` for invalid). 'integer' coerces via `Number()` (NaN on garbage).
- *   - `alias`: output key on `values`. Defaults to camel-cased flag name.
- *   - `default`: applied when no value was provided AND no envKey produced
- *     one. For 'ticket' the default fires when the parsed value is null.
- *   - `envKey`: env-var fallback, used only when the flag is absent and the
- *     env value is a non-empty string.
- *   - `optionalValue`: value to assign when the flag is present without a
- *     value (i.e. EOF or the next token is another `--flag`).
- *   - `short`: single-char short flag (e.g. `-h`).
- *
- * @param {Record<string, object>} spec
- * @param {string[]} args  argv slice (no `process` / script entries)
- * @param {{ env?: NodeJS.ProcessEnv }} [opts]
- * @returns {{ values: Record<string, any>, positionals: string[] }}
- */
 function validateSpec(spec) {
   for (const [name, def] of Object.entries(spec)) {
     if (!SUPPORTED_FLAG_TYPES.has(def.type)) {
@@ -517,6 +391,17 @@ function applyDefaults(spec, state) {
   }
 }
 
+/**
+ * Declarative argv parser for every top-level script. Spec entry:
+ * `{ type, alias?, default?, envKey?, optionalValue?, short? }` — `alias`
+ * defaults to the camel-cased flag; `envKey` applies only when the flag is
+ * absent; `default` after that; `optionalValue` when the flag has no value.
+ *
+ * @param {Record<string, object>} spec
+ * @param {string[]} args  argv slice (no `process` / script entries)
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ values: Record<string, any>, positionals: string[] }}
+ */
 export function defineFlags(spec, args = [], opts = {}) {
   validateSpec(spec);
   const env = opts.env ?? process.env;

package/.agents/scripts/lib/cli-usage.js

@@ -1,32 +1,10 @@
 /**
- * `.agents/scripts/lib/cli-usage.js` — the one implementation of `--help` for
- * every top-level script under `.agents/scripts/`.
+ * The one `--help` implementation for top-level scripts, so a flag contract
+ * lives with its code, not in workflow prose.
  *
- * ## Why
- *
- * A script's flag contract used to live in the workflow prose that invoked it
- * (`deliver-story.md` Step 0 restating `single-story-init.js`'s `--dry-run` /
- * `--steal`, and so on). Two homes for one contract is a drift class: the
- * script changes, the prose does not, and the next agent runs a flag that no
- * longer exists. Moving the enumeration into the script's own `--help` gives
- * the contract a single home that ships with the code that implements it.
- *
- * ## Contract
- *
- * `--help` (or `-h`) is a **query**, never an error path:
- *
- *   - writes non-empty text to **stdout** and exits **0**;
- *   - performs no GitHub write, acquires no lease, mutates no working tree.
- *
- * stdout — not `Logger.info` — because help output must survive
- * `AGENT_LOG_LEVEL=silent` and carry no `[Orchestrator]` decoration; this is
- * the same `process.stdout.write` carve-out that machine-parsable envelopes
- * use (see `tests/enforcement/no-console.test.js`).
- *
- * The short-circuit itself lives in `runAsCli` (`lib/cli-utils.js`), which
- * fires this module **before** the script's `main` runs — so the "no side
- * effects" half of the contract holds structurally rather than by each
- * script remembering to check first.
+ * `--help`/`-h` is a query: non-empty stdout, exit 0, no side effects.
+ * stdout (not `Logger`) so it survives `AGENT_LOG_LEVEL=silent`. `runAsCli`
+ * short-circuits before `main`, so "no side effects" holds structurally.
  *
  * ## Usage
  *

package/.agents/scripts/lib/cli-utils.js

@@ -34,18 +34,8 @@ export function isDirectInvocation(importMetaUrl) {
 }
 
 /**
- * Settle one CLI run: await `main`, translate its outcome into an exit code,
- * then flush stdio.
- *
- * **The exit is never eager** (Story #4783). This helper assigns
- * `process.exitCode` and returns, letting Node terminate once the event loop
- * is empty — which is *after* the pending stdout writes drain. The previous
- * `process.exit()` call terminated first, discarding anything still queued
- * behind a full pipe buffer, so any CLI emitting more than 64 KiB into a pipe
- * truncated silently while still reporting success. The resulting exit code is
- * identical for every caller: `code ?? 0` on the `propagateExitCode` path,
- * `options.exitCode` (default 1) on the fatal-error path, and an untouched 0
- * everywhere else.
+ * Await `main` and set `process.exitCode` — never `process.exit()`, which
+ * truncates stdout still queued behind a full pipe buffer.
  *
  * @param {() => Promise<unknown>} main
  * @param {{ source: string, exitCode: number, onError?: (err: Error) => void,

package/.agents/scripts/lib/close-validation/commands.js

@@ -1,41 +1,23 @@
-/**
- * close-validation/commands.js — Command resolution + formatter file policy.
- *
- * Owns the `project.commands.*` resolution helpers used by the close-
- * validation gates (typecheck / lint / formatCheck / formatWrite), the Story-diff
- * changed-file listing for the format gate, and the formatter
- * file-eligibility policy (Story #3410).
- */
+/** Close-validation `project.commands.*` resolution and formatter file policy. */
 
 import { execFileSync } from 'node:child_process';
 import { diffNameOnly } from '../changed-files.js';
 import { getCommands } from '../config/commands.js';
 
-/**
- * Fallback typecheck command — the gate is mandatory by design (Epic-branch
- * type regressions surface in the next Story's pre-push otherwise).
- */
+/** The typecheck and lint gates are mandatory, so they carry their own fallbacks. */
 const TYPECHECK_FALLBACK = 'npm run typecheck';
 
 /**
- * Fallback lint command. The gate is mandatory, and this string is the exact
- * command the gate spawned before `project.commands.lint` existed — an
- * unconfigured consumer must keep getting byte-identical argv, because the
- * gate's `commandConfigHash` is computed over it and any drift would silently
- * invalidate every previously recorded lint evidence record.
+ * Must stay byte-identical: `commandConfigHash` covers it, and drift would
+ * invalidate every recorded lint evidence record.
  */
 const LINT_FALLBACK = 'npm run lint';
 
-/** Default formatter command when `project.commands.formatCheck` is unset. */
 export const FORMAT_CHECK_FALLBACK = 'npx biome format .';
 
-/** Default formatter command in write mode. */
 const FORMAT_WRITE_FALLBACK = 'npx biome format --write .';
 
-/**
- * Build the format-gate hint dynamically from the resolved write command so
- * a Prettier-only repo gets `prettier --write` in its hint, not biome.
- */
+/** Derived from the write command so a Prettier repo is not told to run biome. */
 export function buildFormatHint(writeCmd) {
   const cmd =
     writeCmd && writeCmd.trim().length > 0 ? writeCmd : FORMAT_WRITE_FALLBACK;
@@ -43,37 +25,27 @@ export function buildFormatHint(writeCmd) {
 }
 
 /**
- * Resolve a string `project.commands.<key>` with a fallback when the
- * value is missing, empty, or the resolver throws on malformed config.
- * Shared engine behind the three resolveX command helpers.
+ * Falls back on a missing/empty value or malformed config.
  *
  * @param {{ project?: { commands?: object } } | null | undefined} config
- *   Canonical resolved config (or a bare `{ project: { commands } }` bag).
  * @param {string} key
  * @param {string} fallback
  * @returns {string}
  */
 function resolveCommandWithFallback(config, key, fallback) {
   try {
-    // `getCommands` reads `config.project.commands` from the canonical
-    // resolved config.
     const cmds = getCommands(config);
     const value = cmds[key];
     if (typeof value === 'string' && value.trim().length > 0) {
       return value.trim();
     }
   } catch {
-    // Malformed config — fall through to the framework default.
+    // Malformed config — use the fallback.
   }
   return fallback;
 }
 
 /**
- * Resolve the typecheck command. Reads `project.commands.typecheck`;
- * falls back to `npm run typecheck`. The framework-wide
- * `COMMANDS_DEFAULTS.typecheck` is `null` but this gate is mandatory, so
- * we apply the fallback here. Exported for testing.
- *
  * @param {{ project?: { commands?: object } } | null | undefined} config
  * @returns {string}
  */
@@ -82,14 +54,7 @@ export function resolveTypecheckCommand(config) {
 }
 
 /**
- * Resolve the lint command. Reads `project.commands.lint`; falls back to
- * `npm run lint`. The framework-wide `COMMANDS_DEFAULTS.lint` is `null` — as
- * for typecheck — because the fallback belongs to this mandatory gate rather
- * than to the shared accessor.
- *
- * A consumer sets this to point the gate at the scoped pair its hooks already
- * run: the close-time gate stays real (the diff is still linted) while CI
- * keeps owning whole-repo drift. Exported for testing.
+ * A consumer may point this at its hooks' scoped lint; CI keeps whole-repo drift.
  *
  * @param {{ project?: { commands?: object } } | null | undefined} config
  * @returns {string}
@@ -99,10 +64,6 @@ export function resolveLintCommand(config) {
 }
 
 /**
- * Resolve the format-check command. Reads `project.commands.formatCheck`;
- * falls back to `npx biome format .` so existing repos keep working byte-
- * for-byte. Exported for testing.
- *
  * @param {{ project?: { commands?: object } } | null | undefined} config
  * @returns {string}
  */
@@ -115,10 +76,6 @@ export function resolveFormatCheckCommand(config) {
 }
 
 /**
- * Resolve the format-write command used by story-close format-autofix (and
- * surfaced in the format-gate hint). Reads `project.commands.formatWrite`;
- * falls back to `npx biome format --write .`. Exported for testing.
- *
  * @param {{ project?: { commands?: object } } | null | undefined} config
  * @returns {string}
  */
@@ -131,11 +88,8 @@ export function resolveFormatWriteCommand(config) {
 }
 
 /**
- * Compute the Story-diff file scope for formatter gates. The default Biome
- * formatter used to run against `.` from inside `.worktrees/story-*`, which
- * lets consumer ignore globs that exclude `.worktrees` self-exclude the whole
- * run. Scoping to changed paths keeps verification real without depending on
- * how consumers spell root ignore patterns.
+ * Story-diff scope for the format gate: run against `.` inside
+ * `.worktrees/story-*`, a consumer's `.worktrees` ignore glob excludes everything.
  *
  * @param {{ cwd: string, baseRef: string }} opts
  * @returns {string[]}
@@ -144,8 +98,6 @@ export function listChangedFilesForFormatGate({ cwd, baseRef }) {
   if (!cwd) throw new Error('listChangedFilesForFormatGate: cwd is required');
   if (!baseRef)
     throw new Error('listChangedFilesForFormatGate: baseRef is required');
-  // Bridge execFileSync into the gitSpawn(cwd, ...args) contract so
-  // diffNameOnly owns the stdout → path-list conversion.
   const gitSpawn = (_cwd, ...args) => {
     try {
       const stdout = execFileSync('git', args, {
@@ -166,18 +118,8 @@ export function listChangedFilesForFormatGate({ cwd, baseRef }) {
 }
 
 /**
- * File extensions Biome's formatter can process. Used to filter the
- * changed-file scope down to the formatter-eligible subset (Story #3410):
- * passing only ineligible paths (e.g. a docs-only Story whose diff is all
- * markdown) makes `biome format <files>` report "No files were processed"
- * and exit 1, failing the gate for a Story that has nothing to format.
- *
- * The set mirrors Biome's handled languages (JS/TS family + JSON + CSS).
- * Markdown, YAML, and other unhandled types are intentionally absent — the
- * default formatter is biome, so the scope is keyed to what biome formats.
- * Consumers who swap the formatter via `project.commands.formatCheck`
- * do not get `changedFileScope` at all (see `buildDefaultGates`), so this
- * filter only ever runs against the default biome command.
+ * What biome formats. Handing biome only ineligible paths exits 1 ("No files
+ * were processed"). Only the default biome command gets a changed-file scope.
  */
 const FORMATTER_ELIGIBLE_EXTENSIONS = new Set([
   'ts',
@@ -192,11 +134,7 @@ const FORMATTER_ELIGIBLE_EXTENSIONS = new Set([
 ]);
 
 /**
- * Whether a changed path is eligible for the default (biome) formatter,
- * decided purely by file extension. Pure function — no I/O. Exported for
- * unit coverage (Story #3410).
- *
- * @param {string} filePath - A repo-relative path (forward-slash normalized).
+ * @param {string} filePath - Repo-relative.
  * @returns {boolean}
  */
 export function isFormatterEligible(filePath) {
@@ -207,7 +145,6 @@ export function isFormatterEligible(filePath) {
   );
   const base = filePath.slice(lastSlash + 1);
   const dot = base.lastIndexOf('.');
-  // No extension (dotfile-only or extensionless) → not formatter-eligible.
   if (dot <= 0) return false;
   const ext = base.slice(dot + 1).toLowerCase();
   return FORMATTER_ELIGIBLE_EXTENSIONS.has(ext);