mandrel 2.30.0 → 2.32.0

package/.agents/scripts/lib/orchestration/{lifecycle/listeners/watcher.js → pr-watch.js}

@@ -1,13 +1,18 @@
-// .agents/scripts/lib/orchestration/lifecycle/listeners/watcher.js
+// .agents/scripts/lib/orchestration/pr-watch.js
 /**
- * Watcher — lifecycle listener that owns the required-check poll loop
- * for an open Epic PR. Story #2256 / Task #2261 (Epic #2172).
+ * pr-watch.js — the required-check poll loop for an open PR.
+ * Story #2256 (Epic #2172).
  *
- * Subscribes to:
- *   - `pr.created` → resolve the required-check names from GitHub at
- *     runtime via `gh pr checks <pr> --required`, then poll until every
- *     check reaches a terminal state (or a per-listener wall-clock
- *     deadline expires), recording the outcome in `classifications`.
+ * **Not a listener, and no longer shelved among them.** This shipped as the
+ * `Watcher` lifecycle listener subscribing to `pr.created`. Story #5006
+ * deleted the class but left the plain primitive at
+ * `lifecycle/listeners/watcher.js` so its CLI consumer's import stayed
+ * stable. Story #5024 then retired the bus itself, which took the listener
+ * concept — and the `listeners/` directory — with it, so the primitive moved
+ * here beside [`merge-poll.js`](./merge-poll.js), the home Story #4545 chose
+ * for `MergeWatcher`'s surviving parts. The only production consumer,
+ * `pr-watch-with-update.js`, has always driven {@link watchPrToTerminal}
+ * directly, with no bus.
  *
  * Critical contract:
  *   - Required-check **names** are resolved from `gh pr checks` at
@@ -16,29 +21,18 @@
  *     branch-protection ruleset on GitHub is the source of truth at
  *     watch time. This guards against config drift (a config file that
  *     hasn't been updated after a protection rule changed on GitHub
- *     would otherwise cause the watcher to either skip a required check
+ *     would otherwise cause the watch to either skip a required check
  *     or wait for a removed one indefinitely).
  *
- * Idempotency contract (AC-10): per-instance `Set<string>` of
- * `${event}:${seqId}` keys. A repeat `(event, seqId)` short-circuits
- * without re-polling and emits nothing. Combined with the bus-level
- * replay defence, this is sufficient — re-running `/deliver` after
- * a crash will produce a NEW seqId and the listener legitimately
- * re-runs the poll loop (which is itself idempotent: the outcome map
- * always reflects the live GitHub state).
- *
- * Side-effect firewall: the listener shells out to `gh` and records
- * its outcome in the in-memory `classifications` log. It does NOT
- * mutate ticket labels, post comments, call `notify`, or emit on the
- * bus — the production consumer (`pr-watch-with-update.js`) drives
- * `watchPrToTerminal` directly without a bus, and the retired
- * `epic.watch.start` / `epic.watch.end` bus events went with the
- * Epic-orchestration stratum.
+ * Side-effect firewall: the loop shells out to `gh` through injectable
+ * ports and returns a verdict. It does NOT mutate ticket labels, post
+ * comments, call `notify`, or write any ledger.
  */
 
 import { spawnSync } from 'node:child_process';
 
-import { parsePrNumberFromUrl } from '../../../github-url.js';
+import { parsePrNumberFromUrl } from '../github-url.js';
+import { applyBehindUpdate } from './behind-recovery.js';
 
 /**
  * Map `gh pr checks` `state` values to the canonical lowercase outcome
@@ -121,8 +115,8 @@ export function normalizeCheckState(raw) {
 }
 
 /**
- * Parse a PR number out of a PR URL. The bus contract gives us
- * `pr.created.prUrl`; `gh pr checks` accepts either the URL or the
+ * Parse a PR number out of a PR URL. Callers hand in the URL `gh pr
+ * create` returned; `gh pr checks` accepts either the URL or the
  * number — we pass the URL through verbatim, but the helper still
  * exists for tests asserting we never silently coerce a malformed URL.
  *
@@ -184,9 +178,9 @@ function ghPrChecks({ prUrl, cwd, repo, spawnFn = spawnSync }) {
 }
 
 /**
- * Default `gh pr view` spawn — probes `mergeStateStatus` so the Watcher
+ * Default `gh pr view` spawn — probes `mergeStateStatus` so the watch loop
  * can detect the BEHIND condition (PR head is behind its base branch)
- * AFTER every required check is green. Exported so tests can stub.
+ * AFTER every required check is green. Injectable so tests can stub.
  */
 function ghPrView({ prUrl, cwd, repo, spawnFn = spawnSync }) {
   const result = spawnFn(
@@ -377,8 +371,8 @@ function defaultSleep(ms) {
  * an empty stdout) are logged and skipped — the outer cap eventually
  * short-circuits if `gh` is unrecoverably broken.
  *
- * Exported so the BEHIND-recovery outer loop in `Watcher.handle()` can
- * call this for each CI cycle without duplicating the inner logic.
+ * Exported so {@link watchPrToTerminal}'s BEHIND-recovery outer loop can
+ * call it once per CI cycle without duplicating the inner logic.
  *
  * @param {object} opts
  * @param {string} opts.prUrl
@@ -434,9 +428,10 @@ export async function pollUntilTerminal({
  * commit after each. Plain async function with NO bus coupling: it
  * shells out to `gh` (via injectable spawns) and returns the verdict.
  *
- * This is the load-bearing primitive shared by the `Watcher` lifecycle
- * listener (`handle()`) and the `pr-watch-with-update.js` CLI, so both
- * paths perform identical polling and BEHIND-recovery. Story #3902.
+ * The load-bearing primitive the `pr-watch-with-update.js` CLI drives.
+ * Story #3902 introduced it so the (since-retired) `Watcher` listener and
+ * the CLI could not drift apart on polling or BEHIND-recovery; the CLI is
+ * now its only caller.
  *
  * @param {object} opts
  * @param {string} opts.prUrl              PR URL or number (passed to `gh` verbatim).
@@ -463,11 +458,10 @@ export async function pollUntilTerminal({
  *   real `setTimeout`-backed sleep; tests override with a no-op.
  * @param {{ info?: Function, warn?: Function, debug?: Function }} opts.logger
  * @param {{status:number,stdout:string,stderr:string}} [opts.firstProbe]
- *   Optional already-issued `gh pr checks` result. When the caller (the
- *   `Watcher` listener) has already probed once to resolve the required
- *   check names, it threads that result here so the loop does not
- *   double-spend the first `gh pr checks` call. Omit it (the CLI path)
- *   and the loop issues the first probe itself.
+ *   Optional already-issued `gh pr checks` result. A caller that has
+ *   already probed once to resolve the required-check names threads it
+ *   here so the loop does not double-spend the first `gh pr checks` call.
+ *   Omit it (the CLI path) and the loop issues the first probe itself.
  * @returns {Promise<{
  *   outcomes: object,
  *   requiredChecks: string[],
@@ -502,8 +496,8 @@ export async function watchPrToTerminal({
   firstProbe,
 }) {
   // First probe: resolve the required-check name set at runtime. Reuse a
-  // caller-supplied probe (the listener already issued one to resolve the
-  // required check names) so we never double-spend the first `gh` call.
+  // caller-supplied probe (issued to resolve the required-check names) so
+  // we never double-spend the first `gh` call.
   const first = firstProbe ?? ghPrChecksFn({ prUrl, cwd, repo });
   // `gh` exits 8 when checks are still pending; this is expected and
   // does not indicate failure. Any other non-zero status with no
@@ -579,6 +573,9 @@ export async function watchPrToTerminal({
       // Bounded by `maxUpdates` so a racing base branch can't ping-pong
       // indefinitely.
       if (!allTerminal(outcomes) || !allGreen(outcomes)) break;
+      // Budget is checked before the `gh pr view` spawn so an exhausted arm
+      // costs no extra round-trip; the shared helper re-checks it as a
+      // fail-safe, and its callback therefore never fires on this path.
       if (updatesApplied >= maxUpdates) break;
       const view = ghPrViewFn({ prUrl, cwd, repo });
       if (view.status !== 0) {
@@ -587,15 +584,26 @@ export async function watchPrToTerminal({
         );
         break;
       }
-      const mergeStateStatus = parseMergeStateStatus(view.stdout);
-      if (mergeStateStatus !== 'BEHIND') break;
-      const update = ghPrUpdateBranchFn({ prUrl, cwd, repo });
-      if (update.status !== 0) {
-        logger.warn?.(
-          `[Watcher] gh pr update-branch failed (status=${update.status}): ${update.stderr}`,
-        );
-        break;
-      }
+      const recovery = await applyBehindUpdate({
+        mergeStateStatus: parseMergeStateStatus(view.stdout),
+        updatesUsed: updatesApplied,
+        maxUpdates,
+        updateBranch: async () => {
+          const update = ghPrUpdateBranchFn({ prUrl, cwd, repo });
+          return update.status === 0
+            ? { ok: true }
+            : {
+                ok: false,
+                detail: `status=${update.status}: ${update.stderr}`,
+              };
+        },
+        onUpdateFailed: (detail) =>
+          logger.warn?.(`[Watcher] gh pr update-branch failed (${detail})`),
+      });
+      // Anything but a landed fast-forward ends the arm: not BEHIND means
+      // there is nothing to recover, and a failed update must not silently
+      // re-poll as though the head moved.
+      if (!recovery.updated) break;
       updatesApplied += 1;
       logger.info?.(
         `[Watcher] PR BEHIND base — issued gh pr update-branch (#${updatesApplied}/${maxUpdates}); re-polling required checks.`,
@@ -643,161 +651,3 @@ export async function watchPrToTerminal({
     stillRunning,
   };
 }
-
-/**
- * Watcher listener.
- */
-export class Watcher {
-  /**
-   * @param {object} opts
-   * @param {object} opts.bus
-   * @param {string} [opts.cwd]
-   * @param {number} [opts.pollIntervalMs] default 10_000.
-   * @param {number} [opts.maxPolls] safety cap on iterations; default
-   *   180 (≈30 min @ 10s).
-   * @param {number} [opts.maxUpdates] cap on `gh pr update-branch`
-   *   recovery calls per `pr.created` event; default 3. Mirrors the
-   *   legacy `pr-watch-with-update` cap so a racing base branch
-   *   can't induce an infinite update-branch ping-pong.
-   * @param {number} [opts.maxResumes] Story #4358: how many times to
-   *   re-arm the poll loop after the cap fires with checks still pending
-   *   (and none failed) before declaring `still-running`; default 0.
-   * @param {Function} [opts.ghPrChecksFn] override for tests.
-   * @param {Function} [opts.ghPrViewFn] override for tests; resolves
-   *   `mergeStateStatus` for the BEHIND-recovery gate.
-   * @param {Function} [opts.ghPrUpdateBranchFn] override for tests;
-   *   issues the fast-forward update on the PR.
-   * @param {Function} [opts.sleepFn] override for tests.
-   * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
-   */
-  constructor(opts = {}) {
-    if (!opts.bus || typeof opts.bus.on !== 'function') {
-      throw new TypeError('Watcher requires a bus with on()');
-    }
-    this.bus = opts.bus;
-    this.cwd = opts.cwd ?? process.cwd();
-    this.pollIntervalMs = Number.isInteger(opts.pollIntervalMs)
-      ? opts.pollIntervalMs
-      : 10_000;
-    this.maxPolls = Number.isInteger(opts.maxPolls) ? opts.maxPolls : 180;
-    this.maxUpdates =
-      Number.isInteger(opts.maxUpdates) && opts.maxUpdates >= 0
-        ? opts.maxUpdates
-        : 3;
-    this.maxResumes =
-      Number.isInteger(opts.maxResumes) && opts.maxResumes >= 0
-        ? opts.maxResumes
-        : 0;
-    this.ghPrChecksFn = opts.ghPrChecksFn ?? ghPrChecks;
-    this.ghPrViewFn = opts.ghPrViewFn ?? ghPrView;
-    this.ghPrUpdateBranchFn = opts.ghPrUpdateBranchFn ?? ghPrUpdateBranch;
-    this.sleepFn = opts.sleepFn ?? defaultSleep;
-    this.logger = opts.logger ?? console;
-    /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
-    this._seen = new Set();
-    /**
-     * Classification log — every `pr.created` we observe lands here
-     * with the outcome (`watched`, `failed`, `skipped-duplicate`,
-     * `still-running`, `timed-out`). Mirrors the Finalizer / Reconciler
-     * "no silent skip" surface.
-     */
-    this.classifications = [];
-    this.events = Object.freeze(['pr.created']);
-  }
-
-  register() {
-    return this.events.map((event) =>
-      this.bus.on(event, async (ctx) => this.handle(ctx)),
-    );
-  }
-
-  async handle({ event, seqId, payload }) {
-    const key = `${event}:${seqId}`;
-    if (this._seen.has(key)) {
-      this.classifications.push({
-        event,
-        seqId,
-        outcome: 'skipped',
-        reason: 'duplicate-seqId',
-      });
-      this.logger.debug?.(`[Watcher] skip duplicate ${key} (idempotent)`);
-      return;
-    }
-    this._seen.add(key);
-
-    const prUrl = payload?.prUrl;
-    if (typeof prUrl !== 'string' || prUrl.length === 0) {
-      this.classifications.push({
-        event,
-        seqId,
-        outcome: 'failed',
-        reason: 'no-pr-url',
-      });
-      return;
-    }
-
-    // First probe: resolve the required-check name set at runtime BEFORE
-    // the (potentially long) poll loop runs. We thread this probe into
-    // `watchPrToTerminal` (via `firstProbe`) so the shared loop reuses it
-    // instead of double-spending the first `gh pr checks` call.
-    const first = this.ghPrChecksFn({ prUrl, cwd: this.cwd });
-    const firstEntries = parseGhPrChecks(first.stdout);
-    if (firstEntries.length === 0 && first.status !== 0 && first.status !== 8) {
-      this.classifications.push({
-        event,
-        seqId,
-        outcome: 'failed',
-        reason: `gh-checks-failed:status=${first.status}`,
-      });
-      this.logger.warn?.(
-        `[Watcher] gh pr checks failed (status=${first.status}): ${first.stderr}`,
-      );
-      return;
-    }
-
-    const requiredChecks = firstEntries.map((e) => e.name);
-
-    // Delegate the poll + BEHIND-recovery loop to the shared plain
-    // primitive so the CLI (`pr-watch-with-update.js`) and this listener
-    // run identical logic.
-    const { polls, updatesApplied, resumesApplied, terminal, stillRunning } =
-      await watchPrToTerminal({
-        prUrl,
-        cwd: this.cwd,
-        maxPolls: this.maxPolls,
-        maxUpdates: this.maxUpdates,
-        maxResumes: this.maxResumes,
-        pollIntervalMs: this.pollIntervalMs,
-        ghPrChecksFn: this.ghPrChecksFn,
-        ghPrViewFn: this.ghPrViewFn,
-        ghPrUpdateBranchFn: this.ghPrUpdateBranchFn,
-        sleepFn: this.sleepFn,
-        logger: this.logger,
-        firstProbe: first,
-      });
-
-    // `still-running` (slow CI, not red) is a distinct classification from
-    // a genuine `timed-out` — reserved for a check that never went
-    // terminal within the poll cap AND the resume budget while none
-    // failed. `watched` covers every terminal arm (green or red).
-    const outcome = terminal
-      ? 'watched'
-      : stillRunning
-        ? 'still-running'
-        : 'timed-out';
-    this.classifications.push({
-      event,
-      seqId,
-      outcome,
-      polls,
-      updatesApplied,
-      resumesApplied,
-      requiredChecks: requiredChecks.length,
-    });
-  }
-
-  reset() {
-    this._seen.clear();
-    this.classifications = [];
-  }
-}

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -301,9 +301,6 @@ export async function readNativeBlockedBy({
  * @param {Map<number, number[]>} nativeEdges
  * @param {number[]} foreignDone Ids outside the set already satisfied.
  * @param {(msg: string) => void} [warn]
- * @param {object} [injectedRules] Test seam forwarded to the shape
- *   derivation — skips the `audit-rules.json` disk read. Production callers
- *   omit it (the real manifest, memoized per process, is the default).
  * @returns {{ kind: string, stories: object[], dag: object[], done: number[] }}
  */
 export function buildStoriesEnvelope({
@@ -311,8 +308,6 @@ export function buildStoriesEnvelope({
   nativeEdges = new Map(),
   foreignDone = [],
   warn,
-  config,
-  injectedRules,
 }) {
   const sorted = [...stories].sort((a, b) => a.id - b.id);
   const inSetDone = sorted.filter(isSatisfiedBlocker).map((s) => s.id);
@@ -324,8 +319,8 @@ export function buildStoriesEnvelope({
     // acceptance-critic sub-agent boots) or `subagent` (the conservative
     // default). Model-side fan-out only; close gates are untouched.
     //
-    // `storyCount` is the premise that decides it, and it is this call site's
-    // load-bearing argument: `inline` names the router's ONE session, so it is
+    // `storyCount` is the ONLY premise that decides it, and it is this call
+    // site's whole argument: `inline` names the router's ONE session, so it is
     // granted only to a run resolving exactly ONE Story, which has no
     // concurrent sibling to share that session with. Passing the resolved set
     // size here is therefore what makes the envelope self-consistent with the
@@ -336,19 +331,14 @@ export function buildStoriesEnvelope({
     // a caller reads for a given `--ids` list never changes as siblings land
     // mid-run. The `route::lite` label is a human-visible hint only, never the
     // control signal.
-    stories: sorted.map(({ id, title, body, url, labels, state }) => ({
+    stories: sorted.map(({ id, title, url, labels, state }) => ({
       id,
       title,
       url,
       labels,
       state,
-      dispatchMode: resolveStoryDispatchMode({
-        body,
-        labels,
-        config,
-        storyCount: sorted.length,
-        injectedRules,
-      }).mode,
+      dispatchMode: resolveStoryDispatchMode({ storyCount: sorted.length })
+        .mode,
     })),
     dag: storiesToDag(sorted, nativeEdges, warn),
     done: [...new Set([...inSetDone, ...foreignDone])].sort((a, b) => a - b),

package/.agents/scripts/lib/orchestration/review-providers/codex.js

@@ -19,7 +19,7 @@
  * `provider: native` explicitly; the probe is the only thing that
  * routes between "configured backend present" and "configured backend
  * missing". The adapter never consults a GitHub provider — the
- * orchestrator owns posting/upserting and the lifecycle bus.
+ * orchestrator owns posting and upserting.
  *
  * @typedef {import('./types.js').Finding} Finding
  * @typedef {import('./types.js').ReviewInput} ReviewInput

package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js

@@ -0,0 +1,130 @@
+/**
+ * review-providers/mi-exemptions.js — the maintainability gate's exemption list,
+ * as the native review provider reads it.
+ *
+ * `delivery.quality.gates.maintainability.ignoreGlobs` is the one declared
+ * answer to "which files is the maintainability index meaningless for" —
+ * declarative schema blobs, generated code, vendored trees. Every other MI
+ * consumer already honours it: the baseline writer excludes those files
+ * (`update-maintainability-baseline.js`), so the `check-baselines.js` ratchet
+ * and the pre-merge MI advisory never see them either.
+ *
+ * `review-providers/native.js` did not, and the split produced a live
+ * contradiction on Story #5007 / PR #5022: the ratchet PASSED while the review
+ * lens raised a **critical blocker** on three exempted
+ * `config-settings-schema*.js` modules in the same close run. Because a critical
+ * finding halts `single-story-close.js` before auto-merge, the only way to land
+ * legitimate work was to merge the PR by hand. A gate that must be
+ * hand-bypassed to ship is not a gate.
+ *
+ * This module is that reconciliation, kept separate from the provider so the
+ * exemption concern has one home and the provider keeps one reason to change.
+ */
+
+import { getQuality } from '../../config/quality.js';
+import { resolveConfig } from '../../config-resolver.js';
+import { isIgnoredByGlobs } from '../../maintainability-utils.js';
+
+/**
+ * Read `delivery.quality.gates.maintainability.ignoreGlobs` so a review's
+ * maintainability dimension scores the same file set the ratchet does.
+ *
+ * Best-effort and total. A config that cannot be resolved yields `[]`, which
+ * scores every changed JS file. That direction is deliberate: degrading to
+ * "score everything" can only produce an advisory the operator must read,
+ * whereas degrading to "score nothing" would silently retire the dimension.
+ *
+ * @param {{ resolveConfigFn?: typeof resolveConfig, getQualityFn?: typeof getQuality }} [deps]
+ * @returns {string[]} minimatch patterns; `[]` when unset or unresolvable.
+ */
+export function resolveMaintainabilityIgnoreGlobs({
+  resolveConfigFn = resolveConfig,
+  getQualityFn = getQuality,
+} = {}) {
+  try {
+    const globs = getQualityFn(resolveConfigFn())?.maintainability?.ignoreGlobs;
+    return Array.isArray(globs) ? globs.slice() : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Pure: split a changed-file list into the set to score and the set the
+ * maintainability gate exempts.
+ *
+ * Matching funnels through `maintainability-utils.js#isIgnoredByGlobs` — the
+ * declared single source of truth for how the MI scorer decides a file is
+ * ignored — so an exempted file is excluded here by exactly the same rule that
+ * kept it out of the baseline. Re-implementing the match with a local
+ * `minimatch` call is what let the two surfaces disagree in the first place.
+ *
+ * Module-local: {@link scopeMaintainabilityFiles} is the single door, and its
+ * `scored` / `ignored` split is where this behaviour is observable.
+ *
+ * @param {string[]} files
+ * @param {string[]} ignoreGlobs
+ * @param {string} cwd root for repo-relative glob resolution
+ * @returns {{ scored: string[], ignored: string[] }}
+ */
+function partitionByIgnoreGlobs(files, ignoreGlobs, cwd) {
+  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) {
+    return { scored: files, ignored: [] };
+  }
+  const scored = [];
+  const ignored = [];
+  for (const relPath of files) {
+    if (isIgnoredByGlobs(relPath, ignoreGlobs, cwd)) ignored.push(relPath);
+    else scored.push(relPath);
+  }
+  return { scored, ignored };
+}
+
+/**
+ * Render the operator-facing notice naming the files the gate exempted, or
+ * `null` when nothing was exempted so the caller can `if` past the log call.
+ *
+ * The notice exists because silence is ambiguous: an operator reading a review
+ * that says nothing about three changed schema modules cannot tell "scored and
+ * healthy" from "never scored".
+ *
+ * Module-local: reached through {@link scopeMaintainabilityFiles}'s `notice`.
+ *
+ * @param {string[]|undefined} ignoredFiles
+ * @returns {string|null}
+ */
+function formatExemptionNotice(ignoredFiles) {
+  const files = Array.isArray(ignoredFiles) ? ignoredFiles : [];
+  if (files.length === 0) return null;
+  return (
+    `[native-review] Maintainability: ${files.length} changed file(s) exempt via ` +
+    `delivery.quality.gates.maintainability.ignoreGlobs — not scored: ${files.join(', ')}.`
+  );
+}
+
+/**
+ * Resolve the exemption list and split a review's changed-file set into the
+ * paths whose maintainability should be scored and the paths the gate exempts.
+ *
+ * This is the one door the native provider uses: it keeps the resolve → match →
+ * report sequence here rather than spread across the provider, so the provider
+ * carries no knowledge of how an exemption is decided.
+ *
+ * @param {string[]} changedFiles
+ * @param {{
+ *   cwd: string,
+ *   resolveIgnoreGlobsFn?: typeof resolveMaintainabilityIgnoreGlobs,
+ * }} opts
+ * @returns {{ scored: string[], ignored: string[], notice: string|null }}
+ */
+export function scopeMaintainabilityFiles(
+  changedFiles,
+  { cwd, resolveIgnoreGlobsFn = resolveMaintainabilityIgnoreGlobs } = {},
+) {
+  const { scored, ignored } = partitionByIgnoreGlobs(
+    changedFiles,
+    resolveIgnoreGlobsFn(),
+    cwd,
+  );
+  return { scored, ignored, notice: formatExemptionNotice(ignored) };
+}

package/.agents/scripts/lib/orchestration/review-providers/native.js

@@ -7,14 +7,24 @@
  *
  *   1. Diffs `headRef` against `baseRef` to enumerate changed files.
  *   2. Runs scoped lint (biome + markdownlint) over the changed surface.
- *   3. Computes per-file maintainability reports for changed JS files.
+ *   3. Computes per-file maintainability reports for changed JS files, minus
+ *      the files the maintainability gate exempts (see below).
  *   4. Maps each signal to a `Finding` with a `severity` ∈ {critical, high,
  *      medium, suggestion}.
  *
- * The adapter does NOT post to GitHub, does NOT render a markdown body,
- * and does NOT consult the lifecycle bus. Those concerns belong to
- * `runCodeReview()` (which calls the renderer + the structured-comment
- * upserter) and the listener chain.
+ * **The maintainability dimension honours the gate's exemption list**, read via
+ * [`mi-exemptions.js`](mi-exemptions.js) — see that module for why this
+ * provider disagreeing with the ratchet was a live delivery blocker. Exempted
+ * files are named on the log rather than silently dropped.
+ *
+ * The lint dimension is deliberately NOT filtered through the same list:
+ * lint carries its own exclusion surface (biome's `files.includes`,
+ * `.markdownlintignore`), and a quality-gate ignore glob makes no claim about
+ * whether a file should parse or format cleanly.
+ *
+ * The adapter does NOT post to GitHub and does NOT render a markdown body.
+ * Those concerns belong to `runCodeReview()`, which calls the renderer + the
+ * structured-comment upserter.
  *
  * Construction is intentionally zero-arg so the factory can instantiate
  * it without threading config through every call. Per-invocation config
@@ -53,6 +63,10 @@ import {
 } from '../../observability/runtime-friction.js';
 import { PROJECT_ROOT } from '../../project-root.js';
 import { transpileIfNeeded } from '../../transpile.js';
+import {
+  resolveMaintainabilityIgnoreGlobs,
+  scopeMaintainabilityFiles,
+} from './mi-exemptions.js';
 import {
   parseLintOutput,
   partitionFilesForLint,
@@ -389,16 +403,6 @@ export function buildLintFindings(lintSummary) {
   return findings;
 }
 
-function _emptyResults() {
-  return {
-    totalFiles: 0,
-    jsFiles: 0,
-    maintainability: [],
-    criticalFindings: [],
-    mediumFindings: [],
-  };
-}
-
 async function runLintPhase({
   scopeLint,
   changedFiles,
@@ -467,6 +471,7 @@ function buildLintDegradations(lintSummary) {
  *   analyzeChangedFilesFn?: typeof analyzeChangedFiles,
  *   buildLintFindingsFn?: typeof buildLintFindings,
  *   emitToolDegradationFn?: typeof emitRuntimeFriction,
+ *   resolveIgnoreGlobsFn?: typeof resolveMaintainabilityIgnoreGlobs,
  *   logger?: { info?: Function, warn?: Function, error?: Function },
  *   scopeLint?: 'changed-only'|'off',
  * }} [deps]
@@ -479,6 +484,10 @@ export function createNativeProvider(deps = {}) {
     analyzeChangedFilesFn = analyzeChangedFiles,
     buildLintFindingsFn = buildLintFindings,
     emitToolDegradationFn = emitRuntimeFriction,
+    // The maintainability-gate exemption seam. The resolution itself — gate-key
+    // read and fail-open — is unit-tested in `mi-exemptions.js`; this dep is
+    // here so a provider test can pin the WIRING without a config on disk.
+    resolveIgnoreGlobsFn = resolveMaintainabilityIgnoreGlobs,
     logger,
     scopeLint = 'changed-only',
   } = deps;
@@ -551,7 +560,12 @@ export function createNativeProvider(deps = {}) {
       logger?.info?.(
         `[native-review] Analyzing ${changedFiles.length} changed file(s)...`,
       );
-      const results = await analyzeChangedFilesFn(changedFiles, {
+      const mi = scopeMaintainabilityFiles(changedFiles, {
+        cwd: PROJECT_ROOT,
+        resolveIgnoreGlobsFn,
+      });
+      if (mi.notice) logger?.info?.(mi.notice);
+      const results = await analyzeChangedFilesFn(mi.scored, {
         headRef,
         gitSpawnFn,
       });

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

@@ -21,7 +21,7 @@
  * the caller raises that to a thrown error so auto-merge is not enabled.
  *
  * Delegates the `runCodeReview` invocation to `runStoryReviewCore`
- * (exported from `story-close/phases/code-review.js`) so the close path
+ * (exported from `story-close/phases/review-core.js`) so the close path
  * shares a single invocation pattern (Story #3653). Review depth needs no
  * input here: it is derived from this Story's own diff inside `runCodeReview`
  * (Story #4542).