mandrel 1.77.0 → 1.78.0

package/.agents/docs/workflows.md

@@ -20,6 +20,13 @@ slash command (e.g. `/deliver`). The projection writes only
 `.claude/commands/<name>.md` — there is no plugin manifest and no
 marketplace listing. The commands load in every Claude Code environment.
 
+Loop units are the one namespaced exception: files under
+`.agents/workflows/loops/<name>.md` project to
+`.claude/commands/loops/<name>.md` and are invoked as the namespaced
+`/loops:<name>` command. On hosts that flatten subdirectory commands the
+same unit surfaces under the flat fallback `/loops-<name>`. They are
+listed separately in the **Loops namespace** section below.
+
 This index is regenerated from each workflow’s front-matter `description:`
 by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
@@ -54,3 +61,15 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /plan. |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |
 | `/qa-run` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |
+
+## Loops namespace (3)
+
+Loop units project to `.claude/commands/loops/<name>.md` and are invoked
+as `/loops:<name>` (flat fallback `/loops-<name>` on hosts that flatten
+subdirectory commands).
+
+| Command | Description |
+| --- | --- |
+| `/loops:fix-failing-tests` | Self-paced convergence loop that drives a red test suite to green. Each round reads the latest failure, applies the smallest fix, and re-runs the verify oracle (`npm test`); the loop terminates when the oracle exits 0. The host (`/loop`) owns iteration and pacing — mandrel supplies the action, the goal, and the terminating oracle. |
+| `/loops:nightly-audit` | Cron maintenance loop that runs a nightly audit sweep over the repository and files actionable findings. Each run executes the audit workflows and routes the results; the host (`/schedule` or a cron-driven `/loop`) owns the cadence. verify is optional for a cron loop — the scheduler owns iteration, so this unit ships the action and goal, not a terminating oracle. |
+| `/loops:watch-ci` | Interval watch loop that polls a pull request's CI checks until they settle. Each round runs `gh pr checks` and reports the delta; the host (`/loop 5m`) owns the cadence and re-invokes the unit on its schedule. verify is optional for an interval loop — the externally-scheduled host owns iteration, so this unit ships the action and goal, not a terminating oracle. |

package/.agents/schemas/lifecycle/loop.tick.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/loop.tick.schema.json",
+  "title": "loop.tick",
+  "description": "Emitted once per pass of a host-driven loop (e.g. a recurring loop command or a long-running poll) so each round lands an inspectable ledger record. Surfaces the loop as forward-progress evidence the /deliver idle watchdog already scans — distinct from story.heartbeat, which carries Story-phase info for a single in-flight Story. A loop is not tied to a Story tier: loop.tick carries a free-form loopName, a monotonic round counter, the configured cadence, and a status so a host loop never runs silently. cadence is the loop's configured interval label (e.g. '5m', 'self-paced'); status is the per-round verdict (running while the loop continues, done when it terminates normally, blocked when it stalls).",
+  "type": "object",
+  "required": ["event", "loopName", "round", "cadence", "status", "timestamp"],
+  "properties": {
+    "event": { "type": "string", "const": "loop.tick" },
+    "loopName": { "type": "string", "minLength": 1 },
+    "round": { "type": "integer", "minimum": 0 },
+    "cadence": { "type": "string", "minLength": 1 },
+    "status": {
+      "type": "string",
+      "enum": ["running", "done", "blocked"]
+    },
+    "timestamp": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/loop-unit.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/loop-unit.schema.json",
+  "version": "1.0.0",
+  "title": "Loop Unit (recurring-work definition)",
+  "description": "Schema for the YAML frontmatter of a loop unit — a markdown file under .agents/workflows/loops/ that defines a recurring/iterative unit of work with a checkable definition of done. The loop block carries the cadence (how the loop is paced), the goal (what the loop is trying to achieve), an optional verify command/array (the at-keyboard checks proving a round is complete — required for self-paced cadence, optional for interval/cron), a maxRounds backstop, and an onExhaust policy describing what happens when the round cap is hit without the goal being met.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["loop"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional reference to this schema file so YAML editors with $schema-aware autocomplete can resolve it from the unit file itself."
+    },
+    "description": {
+      "type": "string",
+      "description": "Optional human-readable summary of what this loop unit does."
+    },
+    "loop": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["cadence", "goal"],
+      "description": "The loop definition block. Carries the cadence, goal, conditional verify, round cap, and exhaustion policy.",
+      "properties": {
+        "cadence": {
+          "type": "string",
+          "enum": ["self-paced", "interval", "cron"],
+          "description": "How the loop is paced. 'self-paced' lets the agent decide when to run the next round and therefore MUST carry a verify[] so each round has a checkable definition of done. 'interval' and 'cron' are externally scheduled, so verify is optional."
+        },
+        "goal": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Required. What the loop is trying to achieve — the standing objective each round works toward."
+        },
+        "verify": {
+          "description": "Command(s) that prove a round is complete. A single command string or an array of command strings. Required when cadence is 'self-paced'; optional for 'interval' / 'cron'.",
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "minItems": 1
+            }
+          ]
+        },
+        "maxRounds": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Optional positive-integer backstop on the number of loop rounds before the onExhaust policy fires."
+        },
+        "onExhaust": {
+          "type": "string",
+          "enum": ["block", "report", "hand-back"],
+          "description": "What happens when maxRounds is hit without the goal met. 'block' transitions to a HITL gate; 'report' emits a summary and stops; 'hand-back' returns control to the caller."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "cadence": { "const": "self-paced" } },
+            "required": ["cadence"]
+          },
+          "then": {
+            "required": ["verify"]
+          }
+        }
+      ]
+    }
+  }
+}

package/.agents/scripts/check-doc-links.js

@@ -258,7 +258,14 @@ function stripAnchorAndQuery(target) {
 //     `temp/epic-[ID]/tickets.json` (preceded by `]`).
 //   - the following char is NOT a word char, `-`, or `.`, so file
 //     extensions like `/tickets.json` and identifier suffixes don't match.
-const SLASH_TOKEN_RE = /(?<![\w/:.>\])])\/([a-z][a-z0-9-]*)(?![\w.-])/g;
+// The optional `(?::[a-z][a-z0-9-]*)?` tail captures the namespaced
+// `/loops:<name>` command form (Story #4289). Without it the matcher would
+// stop at `loops` and try to resolve `.agents/workflows/loops.md`, which does
+// not exist — loop units live under `loops/<name>.md`. The resolver below
+// splits the captured `loops:<name>` token on the `:` to resolve the
+// namespaced path.
+const SLASH_TOKEN_RE =
+  /(?<![\w/:.>\])])\/([a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)?)(?![\w.-])/g;
 
 export function extractSlashTokens(masked) {
   const out = [];
@@ -334,6 +341,22 @@ export function checkFile(absPath, repoRoot) {
   for (const { token, line } of slashTokens) {
     if (RETIRED_COMMANDS.has(token)) continue;
     if (SLASH_ALLOWLIST.has(token)) continue;
+    // Namespaced loop commands (`/loops:<name>`, Story #4289) resolve to a
+    // loop unit under `.agents/workflows/loops/<name>.md`. Split on the `:`
+    // and resolve the namespaced path rather than a flat `loops:<name>.md`.
+    if (token.includes(':')) {
+      const [ns, name] = token.split(':');
+      const nsFile = path.join(workflowsDir, ns, `${name}.md`);
+      if (!fs.existsSync(nsFile)) {
+        violations.push({
+          file: relFile,
+          line,
+          kind: 'unknown-command',
+          message: `slash command /${token} does not resolve to .agents/workflows/${ns}/${name}.md`,
+        });
+      }
+      continue;
+    }
     const workflowFile = path.join(workflowsDir, `${token}.md`);
     const helperFile = path.join(workflowsDir, 'helpers', `${token}.md`);
     if (!fs.existsSync(workflowFile) && !fs.existsSync(helperFile)) {

package/.agents/scripts/check-loop-units.js

@@ -0,0 +1,204 @@
+/**
+ * CLI: loop-unit lint gate (Story #4288, Epic #4284).
+ *
+ * Validates every loop-unit markdown file under `.agents/workflows/loops/`
+ * against `.agents/schemas/loop-unit.schema.json` via
+ * `lib/loop-units/validate-loop-unit.js`. An absent or empty loops
+ * directory is a **clean pass** (exit 0) — the gate only fails when a unit
+ * file is present and invalid.
+ *
+ * On any invalid (or structurally unparseable) unit the CLI prints a
+ * message naming the offending file and the missing/invalid field, then
+ * exits non-zero. This is wired into `npm run lint` so a malformed loop
+ * unit fails the lint gate.
+ *
+ * Flags:
+ *   --dir <path>  override the loops directory (default
+ *                 `.agents/workflows/loops`, resolved from cwd)
+ *   --json        write a structured envelope to stdout instead of the
+ *                 human-readable preview
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  LoopUnitParseError,
+  validateLoopUnit,
+} from './lib/loop-units/validate-loop-unit.js';
+
+export const DEFAULT_LOOPS_DIR = path.join('.agents', 'workflows', 'loops');
+
+/**
+ * Parse argv for `--dir <path>` and `--json`. Exported so tests can pin
+ * the parser.
+ *
+ * @param {string[]} argv
+ * @returns {{ dir: string | null, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let dir = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--dir') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        dir = next;
+        i += 1;
+      }
+    } else if (a === '--json') {
+      json = true;
+    }
+  }
+  return { dir, json };
+}
+
+/**
+ * `README.md` (any case) under the loops directory is namespace
+ * documentation, not a loop unit — it carries no `loop:` frontmatter and is
+ * not projected as a `/loops:` command (see `sync-claude-commands.js`). It is
+ * excluded from the loop-unit collector so the lint gate never flags the
+ * directory's own README as a malformed unit.
+ *
+ * @param {string} name a directory-entry basename
+ * @returns {boolean}
+ */
+export function isLoopUnitFile(name) {
+  return name.endsWith('.md') && name.toLowerCase() !== 'readme.md';
+}
+
+/**
+ * Collect `*.md` loop-unit files directly under `dir`, sorted. Returns an
+ * empty array when the directory is absent (the clean-pass case). The
+ * directory's `README.md` is excluded — it is namespace documentation, not a
+ * unit (see `isLoopUnitFile`).
+ *
+ * @param {string} dir absolute path
+ * @returns {string[]} absolute paths
+ */
+export function collectLoopUnitFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && isLoopUnitFile(e.name))
+    .map((e) => path.join(dir, e.name))
+    .sort();
+}
+
+/**
+ * Validate every loop unit under `dir`. Returns the per-file results and a
+ * roll-up `failures` array carrying `{ file, issues }` for each invalid or
+ * unparseable unit.
+ *
+ * @param {string} dir absolute path
+ * @param {{ schemaPath?: string }} [opts]
+ * @returns {{ files: string[], failures: Array<{ file: string, issues: Array<{path:string,message:string}> }> }}
+ */
+export function checkLoopUnits(dir, opts = {}) {
+  const files = collectLoopUnitFiles(dir);
+  const failures = [];
+  for (const file of files) {
+    try {
+      const { valid, issues } = validateLoopUnit(file, opts);
+      if (!valid) failures.push({ file, issues });
+    } catch (err) {
+      if (err instanceof LoopUnitParseError) {
+        failures.push({ file, issues: [{ path: '/', message: err.reason }] });
+      } else {
+        throw err;
+      }
+    }
+  }
+  return { files, failures };
+}
+
+/**
+ * Render the human-readable report. Each failure lists the offending file
+ * and one line per issue naming the field path and message.
+ *
+ * @param {{ files: string[], failures: Array<{ file: string, issues: Array<{path:string,message:string}> }> }} result
+ * @returns {string}
+ */
+export function renderReport({ files, failures }) {
+  const lines = [];
+  if (files.length === 0) {
+    lines.push('[check-loop-units] no loop units found (ok)');
+    return lines.join('\n');
+  }
+  for (const { file, issues } of failures) {
+    lines.push(`✖ ${file}`);
+    for (const issue of issues) {
+      lines.push(`    ${issue.path}: ${issue.message}`);
+    }
+  }
+  const tag = failures.length > 0 ? '(gate fail)' : '(ok)';
+  lines.push(
+    `[check-loop-units] checked=${files.length} invalid=${failures.length} ${tag}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the full pipeline
+ * against a tmpdir fixture directory.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} 0 = clean; 1 = at least one invalid unit
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const { dir, json } = parseArgv(argv);
+  const loopsDir = path.resolve(cwd, dir ?? DEFAULT_LOOPS_DIR);
+  const result = checkLoopUnits(loopsDir);
+  const exitCode = result.failures.length > 0 ? 1 : 0;
+
+  if (json) {
+    stdout.write(
+      `${JSON.stringify(
+        {
+          kind: 'loop-units-report',
+          dir: loopsDir,
+          checked: result.files.length,
+          failures: result.failures,
+          exitCode,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    const report = renderReport(result);
+    if (exitCode === 0) {
+      stdout.write(`${report}\n`);
+    } else {
+      stderr.write(`${report}\n`);
+    }
+  }
+
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'check-loop-units',
+  propagateExitCode: true,
+  errorPrefix: '[check-loop-units] ❌ Fatal error',
+});

package/.agents/scripts/generate-workflows-doc.js

@@ -34,7 +34,7 @@ import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { Logger } from './lib/Logger.js';
-import { buildCatalog } from './lib/mandrel-catalog.js';
+import { buildCatalog, buildLoopCatalog } from './lib/mandrel-catalog.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -66,12 +66,14 @@ function cellEscape(description) {
 }
 
 /**
- * Render the full generated `workflows.md` content from a catalog.
+ * Render the full generated `workflows.md` content from the flat command
+ * catalog and the loop-unit catalog.
  *
  * @param {Array<{ name: string, description: string | null, vague: boolean }>} catalog
+ * @param {Array<{ name: string, description: string | null, vague: boolean }>} [loopCatalog]
  * @returns {string}
  */
-export function renderWorkflowsDoc(catalog) {
+export function renderWorkflowsDoc(catalog, loopCatalog = []) {
   const lines = [
     '<!--',
     '  GENERATED FILE — do not edit by hand.',
@@ -95,6 +97,13 @@ export function renderWorkflowsDoc(catalog) {
     '`.claude/commands/<name>.md` — there is no plugin manifest and no',
     'marketplace listing. The commands load in every Claude Code environment.',
     '',
+    'Loop units are the one namespaced exception: files under',
+    '`.agents/workflows/loops/<name>.md` project to',
+    '`.claude/commands/loops/<name>.md` and are invoked as the namespaced',
+    '`/loops:<name>` command. On hosts that flatten subdirectory commands the',
+    'same unit surfaces under the flat fallback `/loops-<name>`. They are',
+    'listed separately in the **Loops namespace** section below.',
+    '',
     'This index is regenerated from each workflow’s front-matter `description:`',
     'by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`',
     'fails when it drifts from the on-disk workflow set. To change a command’s',
@@ -110,6 +119,29 @@ export function renderWorkflowsDoc(catalog) {
     lines.push(`| \`/${entry.name}\` | ${cellEscape(entry.description)} |`);
   }
 
+  lines.push('');
+  lines.push(`## Loops namespace (${loopCatalog.length})`);
+  lines.push('');
+  lines.push(
+    'Loop units project to `.claude/commands/loops/<name>.md` and are invoked',
+  );
+  lines.push(
+    'as `/loops:<name>` (flat fallback `/loops-<name>` on hosts that flatten',
+  );
+  lines.push('subdirectory commands).');
+  lines.push('');
+  if (loopCatalog.length === 0) {
+    lines.push('> No loop units are shipped yet.');
+  } else {
+    lines.push('| Command | Description |');
+    lines.push('| --- | --- |');
+    for (const entry of loopCatalog) {
+      lines.push(
+        `| \`/loops:${entry.name}\` | ${cellEscape(entry.description)} |`,
+      );
+    }
+  }
+
   lines.push('');
   return lines.join('\n');
 }
@@ -121,7 +153,8 @@ export function renderWorkflowsDoc(catalog) {
  */
 export function buildExpected() {
   const catalog = buildCatalog(WORKFLOWS_DIR);
-  const generated = renderWorkflowsDoc(catalog);
+  const loopCatalog = buildLoopCatalog(WORKFLOWS_DIR);
+  const generated = renderWorkflowsDoc(catalog, loopCatalog);
   const original = fs.existsSync(DOC_PATH)
     ? fs.readFileSync(DOC_PATH, 'utf8')
     : null;

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

@@ -53,6 +53,34 @@ export function gateExitCode(code, sig) {
   return sig ? 143 : 1;
 }
 
+/**
+ * Biome's marker for "you handed me a path set, but every one of them is
+ * excluded by my own config (`files.includes` allowlist / `files.ignore` /
+ * `overrides`), so I processed nothing" — biome exits 1 in that case.
+ *
+ * The format gate scopes biome to the changed-file subset (Story #3410). When
+ * that subset is non-empty by extension but every path is biome-config-ignored,
+ * the scoped invocation reports this message and exits 1 even though
+ * `biome format .` over the whole tree is clean — a false negative for the
+ * gate (Story #4292). Detecting the marker lets the runner treat that exit as
+ * a clean skip rather than a formatting failure.
+ */
+const BIOME_NO_FILES_PROCESSED =
+  'No files were processed in the specified paths';
+
+/**
+ * Whether biome's combined gate output carries the "No files were processed"
+ * marker. Pure function — no I/O. Exported for unit coverage (Story #4292).
+ *
+ * @param {string} output - Combined stdout/stderr captured from the gate child.
+ * @returns {boolean}
+ */
+export function isBiomeNoFilesProcessed(output) {
+  return (
+    typeof output === 'string' && output.includes(BIOME_NO_FILES_PROCESSED)
+  );
+}
+
 /**
  * Default async gate runner — used by `runCloseValidation` when no `runner`
  * is injected. Spawns the gate via `child_process.spawn`, prefixes every
@@ -66,13 +94,19 @@ export function gateExitCode(code, sig) {
  * `runCloseValidation` sees a non-zero status and folds it into the
  * already-recorded first-failure.
  *
+ * When `opts.tolerateNoFilesProcessed` is set (the biome-scoped format gate —
+ * Story #4292), a non-zero exit whose combined output carries biome's
+ * "No files were processed" marker is downgraded to a clean `status: 0`,
+ * because that exit means every config-included path was already excluded,
+ * not that formatting drifted.
+ *
  * @param {string} cmd
  * @param {string[]} args
- * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string> }} opts
+ * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean }} opts
  * @returns {Promise<{ status: number }>}
  */
 export function defaultGateRunner(cmd, args, opts = {}) {
-  const { cwd, signal, gateName, log, env } = opts;
+  const { cwd, signal, gateName, log, env, tolerateNoFilesProcessed } = opts;
   const child = spawn(cmd, args, {
     cwd,
     shell: process.platform === 'win32',
@@ -85,13 +119,35 @@ export function defaultGateRunner(cmd, args, opts = {}) {
   const prefix = gateName ? `[${gateName}] ` : '';
   const emit =
     typeof log === 'function' ? log : (m) => process.stdout.write(`${m}\n`);
-  pipePrefixed(child.stdout, prefix, emit);
-  pipePrefixed(child.stderr, prefix, emit);
+  // Capture the combined output only when we may need to inspect it for the
+  // biome "No files were processed" marker — otherwise the stream is purely
+  // piped through to the operator (no retained buffer).
+  let captured = '';
+  const tap = tolerateNoFilesProcessed
+    ? (line) => {
+        captured += `${line}\n`;
+        emit(line);
+      }
+    : emit;
+  pipePrefixed(child.stdout, prefix, tap);
+  pipePrefixed(child.stderr, prefix, tap);
   const detach = attachGateAbortHandler(child, signal);
   return new Promise((resolve) => {
     child.on('exit', (code, sig) => {
       detach();
-      resolve({ status: gateExitCode(code, sig) });
+      const status = gateExitCode(code, sig);
+      if (
+        status !== 0 &&
+        tolerateNoFilesProcessed &&
+        isBiomeNoFilesProcessed(captured)
+      ) {
+        emit(
+          `${prefix}↳ biome processed zero files (all changed paths are config-ignored); treating as a clean skip`,
+        );
+        resolve({ status: 0 });
+        return;
+      }
+      resolve({ status });
     });
     child.on('error', () => {
       detach();

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

@@ -50,11 +50,18 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
   log(
     `[close-validation] ↳ ${gate.name} scoped to ${eligibleFiles.length} formatter-eligible changed file(s) from ${gate.changedFileScope.baseRef}...HEAD`,
   );
+  // The extension filter cannot see biome's own config-ignore axis
+  // (`files.includes` allowlist / `files.ignore` / `overrides`). When every
+  // eligible-by-extension path is also config-ignored, the scoped biome
+  // invocation exits 1 with "No files were processed" — a false negative for
+  // the gate (Story #4292). Flag the scoped run so the runner downgrades that
+  // specific exit to a clean skip instead of a formatting failure.
   return {
     gate,
     cmd: gate.cmd,
     args: [...args, ...eligibleFiles],
     skip: false,
+    tolerateNoFilesProcessed: true,
   };
 }
 
@@ -209,6 +216,9 @@ export async function runCloseValidation({
       log,
       signal,
       ...(gate.env ? { env: gate.env } : {}),
+      ...(gate.tolerateNoFilesProcessed
+        ? { tolerateNoFilesProcessed: true }
+        : {}),
     });
     return { status: result?.status ?? 1 };
   };
@@ -255,7 +265,12 @@ export async function runCloseValidation({
     let result;
     try {
       result = await dispatchGate(
-        { ...gate, cmd: execution.cmd, args: execution.args },
+        {
+          ...gate,
+          cmd: execution.cmd,
+          args: execution.args,
+          tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
+        },
         ac.signal,
       );
     } catch (err) {
@@ -321,6 +336,7 @@ export async function runCloseValidation({
       ...gate,
       cmd: execution.cmd,
       args: execution.args,
+      tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
     });
     if (result.status !== 0) {
       failed.push({ gate, status: result.status, cwd: spawnCwd });