mandrel 2.60.0 → 2.61.0

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

@@ -1,10 +1,4 @@
-/**
- * close-validation/gates.js — Gate construction and partitioning.
- *
- * Owns the canonical close-validation gate list (`buildDefaultGates` /
- * `DEFAULT_GATES`) and the parallel-vs-serial partitioning used by the
- * runner (`INDEPENDENT_GATE_NAMES` / `partitionGates`).
- */
+/** Close-validation gate list construction and parallel/serial partitioning. */
 
 import { existsSync } from 'node:fs';
 
@@ -26,26 +20,15 @@ import {
 
 /**
  * @typedef {Object} Gate
- * @property {string}   name  - Short label used in progress logs.
- * @property {string}   cmd   - Executable to run.
- * @property {string[]} args  - Arguments passed to `cmd`.
+ * @property {string}   name
+ * @property {string}   cmd
+ * @property {string[]} args
  * @property {string}   [hint] - Remediation hint shown on failure.
- * @property {{ baseRef: string }} [changedFileScope] - Optional Story-diff scope.
- * @property {{ reason: string }} [skip] - Pre-decided skip (Story #5278). The
- *   runner records the gate as skipped with this reason and never spawns it.
- *   Used for the `coverage-capture` gate when the incremental-coverage skip
- *   is already known to fire, so the gate list can register a real `npm test`
- *   gate in its place instead of the close silently running no test gate.
- * @property {Record<string, string>} [env] - Optional per-gate environment
- *   overlay. Merged over `process.env` for this gate's spawned child only.
- *   Used to thread the epic baseRef into the `check-baselines` gate via
- *   `BASELINE_REF` (Story #3890) so baseline regressions compare against the
- *   epic integration branch rather than `origin/main`.
+ * @property {{ baseRef: string }} [changedFileScope]
+ * @property {{ reason: string }} [skip] - Pre-decided skip: recorded, never spawned.
+ * @property {Record<string, string>} [env] - Overlay merged over `process.env` for this gate's child only.
  * @property {(cmd: string, args: string[], opts: { cwd: string, gateName?: string, log?: (m: string) => void, signal?: AbortSignal, env?: Record<string, string> }) => Promise<{ status: number }> | { status: number }} [run]
- *   - Optional in-process runner. Story #1973: when present, the gate
- *     executes via this callable instead of spawning `cmd`/`args` through
- *     the default runner — used for per-kind baseline gates that import
- *     `compare(head, base)` directly.
+ *   - In-process runner used instead of spawning `cmd`/`args`.
  */
 
 const TYPECHECK_HINT =
@@ -57,21 +40,10 @@ function buildChangedFileScope(baseRef) {
 }
 
 /**
- * Derive the per-gate `env` overlay that pins the `check-baselines`
- * regression-compare base to the close run's integration branch
- * (Story #3890).
- *
- * The baselines gate resolves its compare ref through `resolveScope`,
- * whose environment layer reads `BASELINE_REF`. Threading
- * `origin/<baseBranch>` here makes the gate diff head against the epic
- * integration branch instead of the framework-default `origin/main`, so
- * drift that already landed on `main` but is outside the Story's own diff
- * does not surface as a phantom regression. The same convention
- * (`origin/<baseBranch>`) is used by the baseline-attribution and
- * auto-refresh paths, keeping read/compare bases aligned.
- *
- * Returns `null` when no integration branch is supplied (the gate then
- * keeps its existing default-ref / consumer-config behaviour untouched).
+ * Pin the `check-baselines` compare base to `origin/<baseBranch>` via
+ * `BASELINE_REF`, so drift outside the Story's diff is not a phantom
+ * regression; matches the attribution and auto-refresh bases. `null` keeps
+ * the gate's default ref.
  *
  * @param {string|undefined|null} baseBranch
  * @returns {{ BASELINE_REF: string } | null}
@@ -82,15 +54,8 @@ function buildBaselinesGateEnv(baseBranch) {
 }
 
 /**
- * Resolve whether the CRAP gate is enabled. When enabled, the close-
- * validation graph drops the standalone `test` gate because coverage-
- * capture already runs the suite under c8 instrumentation (Story #1798).
- *
- * Reads the single canonical shape `delivery.quality.gates.crap.enabled`
- * from the resolved config. Defaults to `true` so an omitted setting
- * matches `CRAP_GATE_DEFAULTS.enabled`. We deliberately do NOT round-trip
- * through `getQuality()` here because that resolver expects the unresolved
- * `gates.crap.*` shape.
+ * Defaults to `true` (matches `CRAP_GATE_DEFAULTS.enabled`). Not routed
+ * through `getQuality()`, which expects the unresolved `gates.crap.*` shape.
  *
  * @param {object|undefined|null} config - Canonical resolved config.
  * @returns {boolean}
@@ -102,41 +67,16 @@ function isCrapGateEnabled(config) {
 }
 
 /**
- * The gates run in the Story worktree, whose `package.json` is the committed
- * one the consumer ships — the presence of a `test:coverage` script is a
- * committed fact, so probing at the gate cwd is authoritative. See
- * `lib/npm-scripts.js` for the shared reader.
- */
-
-/**
- * Conditionally produce the standalone `test` gate entry.
- *
- * The plain `test` gate is the canonical test runner UNLESS the
- * coverage-capture gate is taking that role — which happens only when the
- * CRAP gate is enabled (Story #1798) AND the consumer actually ships a
- * `test:coverage` script for coverage-capture to run (#4473). When CRAP is
- * enabled but `test:coverage` is absent, coverage-capture is dropped from
- * the gate list, so the `test` gate MUST come back — otherwise the consumer
- * has NO working test gate at all. Splitting this out keeps
- * `buildDefaultGates` flat for the CRAP-cyclomatic gate.
+ * The plain `test` gate, unless coverage-capture will run the suite — every
+ * close must keep exactly one working test gate.
  *
- * Story #5278 adds a third way for coverage-capture to stop being the test
- * runner: it is registered, but its own incremental-coverage skip is already
- * known to fire (nothing changed under `crap.targetDirs`), so it will exit 0
- * without running anything. A tests-only Story hits that on every close, and
- * before #5278 the close then recorded a suite it never ran as `passed`.
- *
- * @param {boolean} coverageCaptureRunsSuite - Whether the coverage-capture
- *   gate will actually run the suite for this build.
+ * @param {boolean} coverageCaptureRunsSuite
  * @returns {Gate[]}
  */
 function buildTestGateEntry(coverageCaptureRunsSuite) {
   if (coverageCaptureRunsSuite) return [];
-  // Story #5173 — `fullSuiteLock` marks the one gate here that spawns a whole
-  // suite, so `defaultGateRunner` serializes it behind the host lock. It is
-  // set on this entry alone precisely because the two full-suite gates are
-  // mutually exclusive: when `coverage-capture` is registered instead, the
-  // lock is taken one level down, inside `runCapture`.
+  // `fullSuiteLock` serializes this suite behind the host lock; when
+  // coverage-capture runs instead, `runCapture` takes the lock itself.
   return [{ name: 'test', cmd: 'npm', args: ['test'], fullSuiteLock: true }];
 }
 
@@ -144,19 +84,10 @@ const CHECK_BASELINES_HINT =
   'Unified baselines gate breached. Inspect the JSON report (`node .agents/scripts/check-baselines.js`) to see which kind/component/axis fell below floor; remediate the underlying file(s) or — when the regression is intentional — refresh the relevant baseline through its per-kind update script and commit with a `baseline-refresh:` tagged subject.';
 
 /**
- * The names the unified baselines gate can register under (Story #5172).
- *
- * `single` is the unsplit entry — the historical name, and the fail-closed
- * fallback used whenever the enabled-kind set cannot be resolved into two
- * buckets. `independent` and `coverage` are the split pair: the first reads no
- * coverage artifact and therefore fails alongside `lint` / `format` /
- * `typecheck` in the parallel partition, the second consumes the artifact
- * `coverage-capture` writes and therefore stays serial behind it.
- *
- * Every name here MUST also be a member of the `gateName` enum in
- * `.agents/schemas/validation-evidence.schema.json` — the close pipeline keys
- * per-gate evidence on it. `tests/close-validation-gates-enum.test.js` pins
- * that ⊆ invariant.
+ * Baselines gate names. `single` is the unsplit fail-closed fallback;
+ * `independent` runs in the parallel partition, `coverage` stays serial
+ * behind coverage-capture. Every name MUST be in the `gateName` enum of
+ * `validation-evidence.schema.json`.
  */
 export const BASELINES_GATE_NAMES = Object.freeze({
   single: 'check-baselines',
@@ -164,28 +95,12 @@ export const BASELINES_GATE_NAMES = Object.freeze({
   coverage: 'check-baselines-coverage',
 });
 
-/**
- * The baseline kinds whose evaluation reads the coverage artifact written by
- * the `coverage-capture` gate (`coverage` scores it directly; `crap` divides
- * complexity by it). They are the only kinds that have to wait for the
- * capture — every other kind scores the source tree and can run as early as
- * the cheapest gates do.
- */
+/** Kinds that read the coverage-capture artifact and so must wait for it. */
 const COVERAGE_CONSUMING_KINDS = new Set(['coverage', 'crap']);
 
 /**
- * Baseline kinds the resolved config enables for the unified
- * `check-baselines` gate. Mirrors `selectEnabledGates` in the check-baselines
- * pipeline (a kind runs when its `gates.<kind>` block is present and not
- * explicitly disabled) so the registration probe's view of "what will run"
- * matches the gate's own view exactly — and so the Story #5172 partition is
- * derived from the pipeline's own view of what runs rather than a hardcoded
- * kind list that a consumer's config could silently contradict.
- *
- * Returns `null` when that view cannot be resolved at all (a config object
- * whose `delivery.quality` access throws). Callers MUST read `null` as
- * "unknown" and fall back to the single unsplit gate: a partition that cannot
- * be computed must never silently drop enforcement.
+ * Enabled baseline kinds, mirroring `selectEnabledGates` in check-baselines.
+ * `null` means unresolvable; callers MUST fall back to the single unsplit gate.
  *
  * @param {object|undefined|null} config canonical resolved config
  * @returns {string[]|null}
@@ -203,11 +118,7 @@ function enabledBaselineKinds(config) {
 }
 
 /**
- * Whether the consumer opted into fail-closed baseline enforcement via
- * `delivery.quality.requireBaselines: true`. Default false — a consumer that
- * enables baseline gates but has not committed baseline artifacts gets a
- * clean skip (see `probeBaselinesGate`) rather than a deterministic first-try
- * close failure. Fail-closed baseline posture (#4495).
+ * `delivery.quality.requireBaselines: true` opts into fail-closed enforcement.
  *
  * @param {object|undefined|null} config
  * @returns {boolean}
@@ -223,33 +134,14 @@ function toKindSet(presentBaselines) {
 }
 
 /**
- * Probe whether the `check-baselines` consumer contract is satisfied before
- * registering the gate (#4495 — mirrors the #4473/#4480 coverage-capture
- * remedy). The contract: every enabled baseline kind carries a committed
- * baseline artifact on disk (the same path the gate's reader resolves).
- *
- * Decision shape:
- *   - `{ register: false, reason }` — skip (caller logs the reason). Baseline
- *     gates ARE enabled but none of the enabled kinds carry a committed
- *     baseline artifact and the consumer has not set `requireBaselines`. This
- *     is the bench/greenfield case: the gate would otherwise fail
- *     deterministically on first try reading a non-existent
- *     `baselines/<kind>.json`.
- *   - `{ register: true }` — at least one committed baseline artifact is
- *     present, OR no baseline kinds are enabled at all (the gate then self-
- *     skips every kind and exits a clean empty PASS — no failure to avoid, so
- *     the gate stays registered exactly as pre-#4495); run the gate.
- *   - `{ register: true, hint }` — baselines are required-by-config
- *     (`requireBaselines: true`) but absent; keep the gate registered so it
- *     fails, with a preflight hint naming the fix.
+ * Decide whether to register `check-baselines`. Skip (with `reason`) only when
+ * kinds are enabled, none has a committed `baselines/<kind>.json`, and
+ * baselines are not required — the gate would otherwise fail deterministically.
+ * Required-but-absent stays registered with a fix `hint`; no enabled kinds
+ * registers (the gate exits a clean empty PASS).
  *
  * @param {{ config?: object, cwd?: string, enabledKinds?: string[]|null, presentBaselines?: string[]|Set<string> }} opts
- *   `enabledKinds` is `enabledBaselineKinds(config)` computed once by the
- *   caller (so the probe and the partition below read the same view).
- *   A `null` — the unresolvable set — reads as "no enabled kinds", which is
- *   the fail-closed path: the gate stays registered under its single
- *   historical name. `presentBaselines` injects the set of kinds whose
- *   baseline artifact exists (tests), short-circuiting the on-disk probe.
+ *   `enabledKinds: null` (unresolvable) reads as none — the fail-closed path.
  * @returns {{ register: boolean, reason?: string, hint?: string }}
  */
 function probeBaselinesGate({
@@ -260,10 +152,6 @@ function probeBaselinesGate({
 } = {}) {
   const enabled = enabledKinds ?? [];
   if (enabled.length === 0) {
-    // No enabled baseline kinds → `check-baselines.js` self-skips every kind
-    // and exits clean (an empty PASS). There is no deterministic-failure risk
-    // to avoid, so keep the gate registered exactly as it was pre-#4495; the
-    // #4495 skip is confined strictly to the read-miss-would-fail case below.
     return { register: true };
   }
   const injected =
@@ -291,30 +179,10 @@ function probeBaselinesGate({
 }
 
 /**
- * Build the `check-baselines` gate entries for this run (Story #5172).
- *
- * One registration decision, one `BASELINE_REF` overlay, one remediation
- * hint — fanned out across however many entries the enabled-kind set splits
- * into. Keeping the fan-out here is what makes the #3890 (`BASELINE_REF`)
- * and #4495 (`probeBaselinesGate`) invariants structurally impossible to
- * apply to one entry and forget on the other.
- *
- * Three shapes:
- *   - decision says skip → no entries at all (#4495's greenfield skip).
- *   - `kinds` is null (unresolvable) or empty → ONE entry under the single
- *     historical name with no `--gate` filter, in its historical serial
- *     position. Fail closed: a partition that cannot be computed must never
- *     silently drop enforcement, and an empty set means the gate self-skips
- *     every kind and exits a clean empty PASS exactly as it did pre-split.
- *   - otherwise → the split pair, each pinned to its own `--gate` list.
- *     Neither bucket is ever registered with an empty kind set, so a consumer
- *     running only coverage-consuming kinds gets no parallel entry and one
- *     running none of them gets no serial entry.
- *
- * The independent entry is emitted first so a reader of the gate list sees
- * the order the runner actually walks; `partitionGates` is what routes it
- * into the parallel phase, and the coverage entry keeps its declared
- * position after `coverage-capture`.
+ * Fan one registration decision, `BASELINE_REF` overlay and hint out across
+ * the baselines entries, so no entry can miss one. Null/empty `kinds` yields
+ * ONE unfiltered `single` entry (fail closed); otherwise the non-empty
+ * buckets of the split pair, each pinned to its own `--gate` list.
  *
  * @param {{ decision: { register: boolean, hint?: string }, kinds: string[]|null, env: { BASELINE_REF: string }|null }} args
  * @returns {Gate[]}
@@ -351,10 +219,7 @@ function buildBaselinesGateEntries({ decision, kinds, env }) {
 }
 
 /**
- * Split a resolved command string into the `{ cmd, args }` pair a gate entry
- * carries. Whitespace-separated, so `npm run lint` yields the argv the gate
- * spawned before any of these commands were configurable — which is what
- * keeps an unconfigured consumer's `commandConfigHash` unchanged.
+ * Whitespace split; keeps an unconfigured consumer's `commandConfigHash` stable.
  *
  * @param {string} commandString
  * @returns {{ cmd: string, args: string[] }}
@@ -365,23 +230,10 @@ function splitCommand(commandString) {
 }
 
 /**
- * Will the `coverage-capture` gate skip its own capture before running
- * anything? (Story #5278.)
- *
- * `coverage-capture-incremental.js` exits 0 without a suite when no changed
- * file lives under `crap.targetDirs` — the saving that makes incremental mode
- * worth having. The gate list has to know that in advance, because the
- * consequence is not "coverage-capture is cheap today" but "there is no test
- * gate in this close at all": the plain `test` gate is dropped precisely
- * because coverage-capture was going to carry test-failure signalling. A
- * tests-only Story therefore closed green over a red suite.
- *
- * Predicting the skip is safe in one direction only, so every uncertainty
- * resolves to `false` (coverage-capture runs, no extra `test` gate — the
- * pre-#5278 shape): an unresolvable ref, a missing cwd, a git error, or the
- * mode being off. A wrong `false` costs one redundant capture; a wrong `true`
- * would register a `test` gate beside a coverage-capture that also runs the
- * suite, which is the double-spend the credit economy exists to prevent.
+ * Will coverage-capture take its incremental skip (no changed file under
+ * `crap.targetDirs`)? If so the close would otherwise have no test gate at all.
+ * Every uncertainty resolves to `false`: a wrong `false` costs one redundant
+ * capture, a wrong `true` runs the suite twice.
  *
  * @param {{
  *   config?: object,
@@ -397,8 +249,7 @@ function predictsIncrementalCaptureSkip({
   baseBranch,
   getChangedFilesImpl = getChangedFiles,
 }) {
-  // No cwd is the module-load `DEFAULT_GATES` case: never spawn git at import
-  // time just to answer a question that caller cannot act on.
+  // No cwd is the module-load `DEFAULT_GATES` case: never spawn git at import.
   if (typeof cwd !== 'string' || cwd.length === 0) return false;
   const { crap } = getQuality(config);
   if (crap?.incrementalCoverage?.skipWhenUnchanged !== true) return false;
@@ -406,9 +257,8 @@ function predictsIncrementalCaptureSkip({
   if (typeof ref !== 'string' || ref.length === 0) return false;
   try {
     const changed = getChangedFilesImpl({ ref, cwd });
-    // Not an array is "the change set is unknown", not "the change set is
-    // empty" — and `filterFilesUnderTargets` flattens both to `[]`, so the
-    // shape has to be checked here or an unknown diff reads as a skip.
+    // Non-array is "unknown", which `filterFilesUnderTargets` would flatten to
+    // `[]` and misread as a skip.
     if (!Array.isArray(changed)) return false;
     return filterFilesUnderTargets(changed, crap.targetDirs).length === 0;
   } catch {
@@ -417,9 +267,7 @@ function predictsIncrementalCaptureSkip({
 }
 
 /**
- * Is the `test` gate already credited for this build? Only consulted when
- * coverage-capture is the active runner; a consumer without one gets the
- * plain `test` gate regardless (Story #5313).
+ * Is the `test` gate already credited? Only consulted when coverage-capture is active.
  *
  * @param {{ coverageCaptureActive: boolean } & Parameters<typeof predictsTestEvidenceCredit>[0]} opts
  * @returns {boolean}
@@ -429,10 +277,7 @@ function resolveTestCredited({ coverageCaptureActive, ...probe }) {
 }
 
 /**
- * Will the `coverage-capture` gate be the one that runs the suite for this
- * build — so the plain `test` gate is dropped? It is not when it is inactive,
- * when its incremental skip is pre-decided (Story #5278), or when a green
- * bare `npm test` already deposited the test credit (Story #5313).
+ * Does coverage-capture run the suite (so the plain `test` gate is dropped)?
  *
  * @param {{ coverageCaptureActive: boolean, captureSkipPredicted: boolean, testCredited: boolean }} opts
  * @returns {boolean}
@@ -445,91 +290,47 @@ function coverageCaptureRunsSuite({
   return coverageCaptureActive && !captureSkipPredicted && !testCredited;
 }
 
+const COVERAGE_CAPTURE_ARGS = Object.freeze([
+  '.agents/scripts/coverage-capture.js',
+]);
+
+/** The close gate that replays the `pre-push` hook's CRAP-scope preview. */
+const QUALITY_PREVIEW_GATE_NAME = 'quality-preview';
+
+const QUALITY_PREVIEW_HINT =
+  "Quality preview failed — the same per-file maintainability / CRAP check the `pre-push` hook runs, scored against the base branch. Reduce the flagged methods' complexity or cover them, then re-run close; a close that skipped this gate would have died at push instead.";
+
 /**
- * The `coverage-capture` gate's argv.
- *
- * Story #5278 — `--require-credited` is passed here, and only here, when the
- * consumer has set `delivery.execution.requireCreditedCapture`. The CLI no
- * longer reads that key, so the worker's pre-push deposit invocation always
- * runs while the close gate refuses to pay for a suite the worker should
- * already have banked.
+ * Replays the `pre-push` CRAP-scope preview so its breach fails close, not
+ * the push. Registered exactly when coverage-capture is, and after it, so it
+ * scores a fresh artifact.
  *
- * @param {object} [config]
- * @returns {string[]}
+ * @param {{ coverageCaptureActive: boolean, baseBranch?: string }} opts
+ * @returns {Gate[]}
  */
-function buildCoverageCaptureArgs(config) {
-  const args = ['.agents/scripts/coverage-capture.js'];
-  if (config?.delivery?.execution?.requireCreditedCapture === true) {
-    args.push('--require-credited');
-  }
-  return args;
+function buildQualityPreviewGateEntry({ coverageCaptureActive, baseBranch }) {
+  if (!coverageCaptureActive) return [];
+  const ref = `origin/${baseBranch || 'main'}`;
+  return [
+    {
+      name: QUALITY_PREVIEW_GATE_NAME,
+      cmd: 'node',
+      args: ['.agents/scripts/quality-preview.js', '--changed-since', ref],
+      hint: QUALITY_PREVIEW_HINT,
+    },
+  ];
 }
 
 /**
- * Build the canonical close-validation gate list.
- *
- * Ordering (cheapest fast-fail first): typecheck → lint → [test] →
- * format → [coverage-capture] → check-baselines. The standalone `test`
- * gate is dropped when coverage-capture is the active test runner — i.e.
- * `crap.enabled === true` (Story #1798) AND a `test:coverage` script
- * exists (Story #4473) — because coverage-capture then carries
- * test-failure signalling under c8. When CRAP is on but `test:coverage` is
- * absent, coverage-capture is dropped and the `test` gate is restored so
- * there is always a working test gate.
- *
- * `typecheck` and `lint` are mandatory; consumers may customise either
- * command via `project.commands.typecheck` / `project.commands.lint`
- * (defaults `npm run typecheck` / `npm run lint`). Customising `lint` is how
- * a consumer whose hooks and CI already lint the diff stops paying for a
- * third whole-repo pass at close: `lint` runs in the parallel partition, so
- * a slow whole-repo lint sets the floor for that whole phase.
- *
- * Story #2210 retired the legacy per-kind in-process regression gates
- * (`check-maintainability`, `check-crap`, `check-mutation`) and their
- * shared in-process runner. The unified `check-baselines` gate is now the
- * single source of truth for per-kind regression enforcement
- * (attribution-wired floor + tolerance + schema).
- * The `baseBranch` parameter threads the close run's integration branch
- * into two gates: the `format` gate's `changedFileScope` (existing) and —
- * since Story #3890 — the `check-baselines` gate's `BASELINE_REF` env, so
- * the baselines regression compare diffs head against the epic integration
- * branch (`origin/<baseBranch>`) rather than the framework-default
- * `origin/main`. Without this, every child Story on an `epic/<id>` branch
- * re-discovered inherited main-vs-epic drift in untouched files as phantom
- * regressions and worked around it by hand-setting `BASELINE_REF`.
- *
- * Story #4473 — the coverage-capture gate spawns `npm run test:coverage`,
- * so it is registered ONLY when the consumer actually ships that script.
- * When CRAP is enabled but `test:coverage` is absent, coverage-capture is
- * dropped and the plain `test` gate is restored (see `buildTestGateEntry`),
- * so a consumer without a coverage script gets a working degraded test gate
- * instead of a deterministic close failure with no test gate at all. The
- * probe reads `package.json` at `cwd` (the gate execution directory).
- *
- * Story #4495 — the unified `check-baselines` gate reads a committed
- * `baselines/<kind>.json` for each enabled kind; a consumer that enables
- * baseline gates but ships no `baselines/` tree (every bench sandbox, any
- * greenfield consumer) failed the gate deterministically on first try. The
- * gate is now registered only when its consumer contract is satisfied
- * (`probeBaselinesGate`): at least one enabled kind carries a committed
- * baseline, OR the consumer opted into fail-closed enforcement via
- * `delivery.quality.requireBaselines`. When no baselines are committed and
- * none are required, the gate is skipped with a logged reason (via `log`)
- * instead of a blocking failure.
+ * Build the close-validation gate list, cheapest fast-fail first: typecheck →
+ * lint → [test] → format → [coverage-capture → quality-preview] →
+ * check-baselines. Coverage-capture registers only when CRAP is enabled AND a
+ * `test:coverage` script exists; it then carries test-failure signalling and
+ * the plain `test` gate is dropped, so there is always exactly one test gate.
  *
  * @param {{ config?: object, baseBranch?: string, cwd?: string, packageScripts?: Record<string, string>, presentBaselines?: string[]|Set<string>, log?: (message: string) => void, getChangedFilesImpl?: typeof getChangedFiles }} [opts]
- *   `config` is the canonical resolved config (`{ project, delivery, ... }`);
- *   gate commands resolve from `project.commands` and the CRAP toggle from
- *   `delivery.quality.gates.crap.enabled`. `baseBranch` is the close run's
- *   integration branch (`epic/<id>` for Epic-attached Stories, the base
- *   branch for standalone Stories). `cwd` is where the `package.json`
- *   coverage-script probe and the `baselines/<kind>.json` presence probe
- *   read from (defaults to `process.cwd()`); `packageScripts` injects the
- *   scripts map directly (tests) and short-circuits the coverage-script disk
- *   read; `presentBaselines` injects the set of kinds whose baseline artifact
- *   exists (tests) and short-circuits the baseline-presence disk read; `log`
- *   receives the skip reason when the `check-baselines` gate is not
- *   registered.
+ *   `cwd` is where the `package.json` and baseline-presence probes read;
+ *   `packageScripts` / `presentBaselines` inject those probes (tests).
  * @returns {Gate[]}
  */
 export function buildDefaultGates({
@@ -548,8 +349,8 @@ export function buildDefaultGates({
   const scripts = packageScripts ?? readPackageScripts(cwd);
   const coverageCaptureActive =
     isCrapGateEnabled(config) && hasNpmScript(scripts, 'test:coverage');
-  // Story #5313 — a credited bare `npm test` registers the plain `test` gate
-  // beside the capture so the credit is reported, never re-spent.
+  // A credited bare `npm test` registers the plain `test` gate beside the
+  // capture so the credit is reported, never re-spent.
   const testCredited = resolveTestCredited({
     coverageCaptureActive,
     storyId,
@@ -559,10 +360,8 @@ export function buildDefaultGates({
     shouldSkipImpl,
     log,
   });
-  // Story #5278 — a registered coverage-capture gate that is going to take
-  // its own incremental skip is not the test runner for this close, so the
-  // plain `test` gate comes back beside it and the capture gate registers as
-  // a pre-decided skip rather than as a suite that silently did not run.
+  // A predicted incremental skip registers the capture as a pre-decided skip
+  // and brings the plain `test` gate back.
   const captureSkipPredicted =
     coverageCaptureActive &&
     predictsIncrementalCaptureSkip({
@@ -603,10 +402,8 @@ export function buildDefaultGates({
       args: typecheck.args,
       hint: TYPECHECK_HINT,
     },
-    // Gate name kept generic ("lint") for the same reason the format gate's
-    // is: the command resolves from config, so a consumer pointing it at a
-    // scoped pair does not shift the close-orchestrator log line, the
-    // evidence keyspace, or the parallel-partition membership below.
+    // Gate names stay generic though commands resolve from config, so the
+    // log line, evidence keyspace and partition membership never shift.
     { name: 'lint', cmd: lint.cmd, args: lint.args },
     ...buildTestGateEntry(
       coverageCaptureRunsSuite({
@@ -616,10 +413,6 @@ export function buildDefaultGates({
       }),
     ),
     {
-      // Gate name kept generic ("format") so the close-orchestrator log line
-      // doesn't shift when a repo swaps biome for Prettier / dprint via
-      // `project.commands.formatCheck`. The
-      // actual command and the remediation hint resolve from config.
       name: 'format',
       cmd: format.cmd,
       args: format.args,
@@ -633,7 +426,7 @@ export function buildDefaultGates({
           {
             name: 'coverage-capture',
             cmd: 'node',
-            args: buildCoverageCaptureArgs(config),
+            args: [...COVERAGE_CAPTURE_ARGS],
             hint: 'Coverage capture failed — `npm run test:coverage` exited non-zero. Fix failing tests or coverage-threshold breaches, then re-run close.',
             ...(captureSkipPredicted
               ? { skip: { reason: 'incremental-no-crap-changes' } }
@@ -641,28 +434,7 @@ export function buildDefaultGates({
           },
         ]
       : []),
-    // Story #2210 — unified `check-baselines` gate is the only path for
-    // per-kind regression enforcement. The legacy per-kind in-process gates
-    // were retired because their regression-compare semantics are fully
-    // subsumed by this gate's attribution-wired floor + tolerance + schema
-    // enforcement, and running both paths in series was redundant and
-    // conflict-prone.
-    //
-    // `check-baselines.js` self-skips per-kind gates whose `enabled === false`
-    // is configured. Story #4495: it is now also skipped entirely when the
-    // consumer enables baseline gates but ships no committed baseline artifact
-    // (and has not set `delivery.quality.requireBaselines`) — otherwise the
-    // gate fails deterministically on first try reading a non-existent
-    // `baselines/<kind>.json` (`probeBaselinesGate`). When required-by-config
-    // but absent, it stays registered with a preflight hint naming the fix.
-    //
-    // Story #5172: the gate registers as up to TWO entries. The kinds that
-    // read no coverage artifact run in the parallel independent partition so
-    // a baseline breach fails beside `lint` / `format` / `typecheck` instead
-    // of minutes later behind `coverage-capture`; the coverage-consuming
-    // kinds keep the serial slot after it. `buildBaselinesGateEntries` owns
-    // that fan-out so both entries inherit ONE registration decision, ONE
-    // `BASELINE_REF` overlay and ONE hint.
+    ...buildQualityPreviewGateEntry({ coverageCaptureActive, baseBranch }),
     ...buildBaselinesGateEntries({
       decision: baselinesDecision,
       kinds: baselineKinds,
@@ -672,36 +444,25 @@ export function buildDefaultGates({
 }
 
 /**
- * Default gate list resolved with no consumer config — uses the
- * `npm run typecheck` fallback for the typecheck gate. Call sites that have a
- * resolved config object in scope (e.g. `single-story-close.js`) should
- * prefer `buildDefaultGates({ config })` so a configured
- * `project.commands.typecheck` is honoured.
+ * Config-less gate list; callers holding a config should use `buildDefaultGates({ config })`.
  *
  * @type {Gate[]}
  */
 export const DEFAULT_GATES = buildDefaultGates();
 
 /**
- * Gates whose I/O is read-only against the working tree (no shared mutable
- * state, no overlapping ports/sockets). Safe to run concurrently — see
- * `runCloseValidation` for the Promise.all + AbortController plumbing.
+ * Gates that are read-only against the working tree and share no ports, so
+ * they may run concurrently.
  */
 const INDEPENDENT_GATE_NAMES = new Set([
   'lint',
   'format',
   'typecheck',
-  // Story #5172 — the coverage-independent half of the baselines gate. It
-  // reads the committed `baselines/<kind>.json` files and scores the source
-  // tree in-process; it writes nothing and shares no port, so it satisfies
-  // the same read-only contract as the three gates above.
   BASELINES_GATE_NAMES.independent,
 ]);
 
 /**
- * Partition a gate list into the parallel-safe set and the order-sensitive
- * remainder. Order is preserved within each bucket so the serial walk stays
- * cheapest-fast-fail-first (test → coverage-capture → check-baselines).
+ * Order is preserved within each bucket.
  *
  * @param {Gate[]} gates
  * @returns {{ independent: Gate[], serial: Gate[] }}