mandrel 2.31.0 → 2.32.0

package/.agents/scripts/lib/config/explain.js

@@ -72,8 +72,6 @@ const KEY_MEANINGS = Object.freeze({
     'Root for gitignored scratch output (per-run state, mirrors, logs).',
   'project.docsContextFiles':
     'Authoritative files an agent must read before starting any task.',
-  'project.commands.lintBaseline':
-    'Lint command the close-validation chain runs.',
   'project.commands.test': 'Test command the close-validation chain runs.',
   'project.commands.typecheck':
     'Typecheck command (null disables the typecheck gate).',
@@ -136,8 +134,6 @@ const KEY_MEANINGS = Object.freeze({
   // delivery.*
   'delivery.execution.timeoutMs':
     'Per-execution timeout for orchestrated delivery steps.',
-  'delivery.lease.ttlMs':
-    'Time-to-live for the delivery lease before a stale claim is reclaimable.',
   'delivery.ci.watch.pollIntervalMs':
     'Poll cadence (ms) for the merge/CI watch loop.',
   'delivery.ci.watch.maxPolls':
@@ -147,7 +143,7 @@ const KEY_MEANINGS = Object.freeze({
   'delivery.ci.autoMerge':
     'Merge posture: trust-ci merges on green checks; strict also requires a clean review gate.',
   'delivery.docsFreshness.paths':
-    'Docs whose freshness is checked at delivery time.',
+    'Docs the audit-documentation lens folds into its target set.',
   'delivery.deliverRunner.concurrencyCap':
     'Maximum Stories dispatched in parallel within one wave. Default 3 — conservative by design to keep host-quota consumption predictable. Operators running wide waves with adequate parallel-agent quota should raise this to reduce wall-clock time proportionally.',
   'delivery.worktreeIsolation.enabled':
@@ -202,8 +198,6 @@ const KEY_MEANINGS = Object.freeze({
     'Whether a dedicated refactor stage runs during delivery.',
   'delivery.acceptanceEval.maxRounds':
     'Redraft rounds the per-Story acceptance self-eval loop runs before escalating to agent::blocked (default 2; clamped to a hard ceiling that cannot be disabled).',
-  'delivery.acceptanceEval.clusterCeiling':
-    'Max acceptance criteria one single-delivery acceptance critic scores per fresh-context pass; the Story ACs are split into ceil(totalACs / clusterCeiling) maker-blind critic clusters (default 4; clamped to [1, 8]).',
 
   // qa.*
   'qa.featureRoot': 'Root directory holding the QA harness .feature files.',
@@ -257,6 +251,10 @@ const PREFIX_MEANINGS = Object.freeze([
     'QA harness deployment target (baseUrl, per-environment sign-in seam, allowWrites gate).',
   ],
   ['qa.personas', 'QA harness persona / credential mapping.'],
+  [
+    'qa.gherkinLint',
+    'Static Gherkin corpus gate: per-scope feature/step roots plus the exemption-tag and step-waiver escapes.',
+  ],
 ]);
 
 /**

package/.agents/scripts/lib/config/gates/bundle-size.schema.js

@@ -1,23 +1,49 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
-import { GATE_BASE } from './shared.js';
+import { gateBase } from './shared.js';
 
 const BUNDLE_DECLARATION = {
   type: 'object',
+  description: 'One built artifact the bundle-size gate weighs.',
   required: ['name', 'path', 'limit'],
   properties: {
-    name: { type: 'string', minLength: 1 },
-    path: { type: 'string', minLength: 1 },
-    limit: { type: 'string', minLength: 1 },
+    name: {
+      type: 'string',
+      minLength: 1,
+      description: 'Label the rollup row is keyed by.',
+    },
+    path: {
+      type: 'string',
+      minLength: 1,
+      description: 'Glob or path of the built artifact to measure.',
+    },
+    limit: {
+      type: 'string',
+      minLength: 1,
+      description: 'Human size ceiling (e.g. `"180 kB"`).',
+    },
   },
   additionalProperties: false,
 };
 
 export const BUNDLE_SIZE_GATE = {
   type: 'object',
+  description:
+    'Built-artifact size ratchet for web targets. Off by default — it needs declared bundles.',
   properties: {
-    ...GATE_BASE,
-    bundles: { type: 'array', items: BUNDLE_DECLARATION },
+    ...gateBase({
+      enabled: false,
+      baselinePath: 'baselines/bundle-size.json',
+      tolerance: { kind: 'percent', value: 0 },
+      floors: { '*': {} },
+    }),
+    bundles: {
+      type: 'array',
+      items: BUNDLE_DECLARATION,
+      description:
+        'The artifacts to weigh. Empty means the gate has nothing to do.',
+      default: [],
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/coverage.schema.js

@@ -1,18 +1,38 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
-import { GATE_BASE, SAFE_STRING } from './shared.js';
+import { COVERAGE_GATE_DEFAULTS } from '../quality.js';
+import { gateBase, SAFE_STRING } from './shared.js';
 
 export const COVERAGE_GATE = {
   type: 'object',
+  description:
+    'Line/branch/function coverage ratchet, read from the Istanbul JSON summary the project test run emits.',
   properties: {
-    ...GATE_BASE,
-    coveragePath: { ...SAFE_STRING, minLength: 1 },
+    ...gateBase({
+      enabled: COVERAGE_GATE_DEFAULTS.enabled,
+      baselinePath: COVERAGE_GATE_DEFAULTS.baselinePath,
+      tolerance: COVERAGE_GATE_DEFAULTS.tolerance,
+      floors: COVERAGE_GATE_DEFAULTS.floors,
+    }),
+    coveragePath: {
+      ...SAFE_STRING,
+      minLength: 1,
+      description:
+        'Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads.',
+      default: COVERAGE_GATE_DEFAULTS.coveragePath,
+    },
     // Story #2136 / Task #2142 — bounded timeout for `npm run test:coverage`.
     // Wired into `runCapture` via `spawnSync({ timeout, killSignal })`. A
     // SIGKILL fired by the timeout is translated to exit code 124 (the GNU
     // `timeout` convention) so close-validation can branch on "hang" vs.
-    // "test failed". Default 600000 (10 min) resolved in `config/quality.js`.
-    timeoutMs: { type: 'integer', minimum: 1 },
+    // "test failed".
+    timeoutMs: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Bounded timeout (ms) for the `npm run test:coverage` capture spawn. A SIGKILL at the budget boundary maps to exit 124 so close-validation can tell a hang from a test failure.',
+      default: COVERAGE_GATE_DEFAULTS.timeoutMs,
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js

@@ -18,9 +18,19 @@
  */
 export const INCREMENTAL_COVERAGE_SCHEMA = {
   type: 'object',
+  description:
+    'Story #4981 — opt-in incremental coverage-capture + CRAP-join scoping. Default (key absent) preserves today’s full-repo behaviour byte-for-byte. When `enabled: true`, `coverage-capture.js` scopes `npm run test:coverage` to the files changed against `baseRef` (default: the gate’s own `--ref` / `main`), and the CRAP join treats a method in a file the diff did not touch as resolved by its committed baseline row instead of requiring fresh coverage for it.',
   properties: {
-    enabled: { type: 'boolean' },
-    baseRef: { type: 'string', minLength: 1 },
+    enabled: {
+      type: 'boolean',
+      description: 'Master switch for incremental capture + join scoping.',
+    },
+    baseRef: {
+      type: 'string',
+      minLength: 1,
+      description:
+        'Git ref the changed-file set is computed against. Omitted falls back to the gate’s own `--ref` (`main`).',
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/crap.schema.js

@@ -1,41 +1,86 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
+import { CRAP_GATE_DEFAULTS } from '../quality.js';
 import { INCREMENTAL_COVERAGE_SCHEMA } from './crap-incremental-coverage.schema.js';
 import {
-  GATE_BASE,
+  gateBase,
   LIST_OR_EXTENDER_OF_STRINGS,
   SAFE_STRING,
 } from './shared.js';
 
 export const CRAP_GATE = {
   type: 'object',
+  description:
+    'CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage.',
   properties: {
-    ...GATE_BASE,
-    targetDirs: LIST_OR_EXTENDER_OF_STRINGS,
-    newMethodCeiling: { type: 'integer', minimum: 1 },
-    requireCoverage: { type: 'boolean' },
-    // Story #4775 — fail-closed floor on the per-method coverage JOIN: the
-    // fraction of methods that must resolve a coverage entry, counted only
-    // over files that HAVE one, before `update-crap-baseline.js` will
-    // persist. A broken join is silent by construction (unresolved methods
-    // are simply absent), so the updater refuses rather than writing a thin
-    // baseline and logging it as success. Default 0.75.
-    minMethodResolutionRate: { type: 'number', minimum: 0, maximum: 1 },
+    ...gateBase({
+      enabled: CRAP_GATE_DEFAULTS.enabled,
+      baselinePath: CRAP_GATE_DEFAULTS.baselinePath,
+      tolerance: CRAP_GATE_DEFAULTS.tolerance,
+      floors: CRAP_GATE_DEFAULTS.floors,
+    }),
+    targetDirs: {
+      ...LIST_OR_EXTENDER_OF_STRINGS,
+      description:
+        "Directories whose JS sources the CRAP gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal.",
+      default: [...CRAP_GATE_DEFAULTS.targetDirs],
+    },
+    newMethodCeiling: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Hard CRAP ceiling applied to a method the diff introduces. A new method above it fails the gate regardless of the baseline.',
+      default: CRAP_GATE_DEFAULTS.newMethodCeiling,
+    },
+    requireCoverage: {
+      type: 'boolean',
+      description:
+        'When true, the gate refuses to score without a coverage artifact rather than silently reporting complexity-only rows.',
+      default: CRAP_GATE_DEFAULTS.requireCoverage,
+    },
+    // Story #4775 — fail-closed floor on the per-method coverage JOIN.
+    minMethodResolutionRate: {
+      type: 'number',
+      minimum: 0,
+      maximum: 1,
+      description:
+        'Fail-closed floor on the per-method coverage JOIN (Story #4775): the fraction of methods that must resolve a coverage entry, counted only over files that HAVE one, before `update-crap-baseline.js` will persist. A broken join is silent by construction — unresolved methods are simply absent — so the updater refuses rather than writing a thin baseline and logging it as success. Not enforced below 25 joinable methods, where a diff-scoped run’s rate is noise. Default 0.75; a healthy repo resolves ~98%.',
+    },
     friction: {
       type: 'object',
-      properties: { markerKey: { type: 'string', minLength: 1 } },
+      description:
+        'Friction-signal wiring for a CRAP baseline regression, so a recurring one can reach the actionable threshold.',
+      properties: {
+        markerKey: {
+          type: 'string',
+          minLength: 1,
+          description: 'Signal marker key the regression is recorded under.',
+        },
+      },
       additionalProperties: false,
+      default: { ...CRAP_GATE_DEFAULTS.friction },
+    },
+    refreshTag: {
+      ...SAFE_STRING,
+      minLength: 1,
+      description:
+        'Commit-subject substring that acknowledges a deliberate CRAP baseline refresh in the compared range. A range commit carrying it that also touches the baseline file demotes head-vs-base regressions; floors stay enforced.',
+      default: CRAP_GATE_DEFAULTS.refreshTag,
+    },
+    refreshTimeoutMs: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Bounded timeout (ms) for `npm run crap:update` spawned by the baseline-attribution refresh path. Mirrors `coverage.timeoutMs`: a SIGKILL fired at the budget boundary maps to exit 124 so the close orchestrator can flip the Story to `agent::blocked`. Default 60000 (Story #2165).',
+      default: CRAP_GATE_DEFAULTS.refreshTimeoutMs,
+    },
+    ignoreGlobs: {
+      type: 'array',
+      items: { type: 'string', minLength: 1 },
+      description:
+        'Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from CRAP discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217).',
+      default: [...CRAP_GATE_DEFAULTS.ignoreGlobs],
     },
-    refreshTag: { ...SAFE_STRING, minLength: 1 },
-    // Story #2165 — bounded timeout for `npm run crap:update` spawned by the
-    // baseline-attribution refresh path. Mirrors `coverage.timeoutMs` (Story
-    // #2142): a SIGKILL fired at the budget boundary maps to exit code 124
-    // so the close orchestrator can flip the Story to `agent::blocked`.
-    refreshTimeoutMs: { type: 'integer', minimum: 1 },
-    // Story #3217 — glob patterns matched against canonicalised repo-relative
-    // paths to exclude files from CRAP discovery before scoring. Orthogonal
-    // to `components` (grouping). Absent/empty preserves existing behaviour.
-    ignoreGlobs: { type: 'array', items: { type: 'string', minLength: 1 } },
     incrementalCoverage: INCREMENTAL_COVERAGE_SCHEMA,
   },
   additionalProperties: false,

package/.agents/scripts/lib/config/gates/duplication.schema.js

@@ -1,26 +1,38 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
-import { GATE_BASE, LIST_OR_EXTENDER_OF_STRINGS } from './shared.js';
+import { gateBase, LIST_OR_EXTENDER_OF_STRINGS } from './shared.js';
 
-/**
- * `delivery.quality.gates.duplication` — code-duplication (DRY) gate
- * (Story #3664). Shares the four-field `GATE_BASE` (enabled, baselinePath,
- * tolerance, floors, components) and adds the scan-scope extras: the
- * `targetDirs` the duplication scanner walks, a bounded refresh timeout
- * mirroring crap/MI, and `ignoreGlobs` to exclude files from the scan.
- */
 export const DUPLICATION_GATE = {
   type: 'object',
+  description:
+    'Code-duplication (DRY) gate (Story #3664). Shares the gate base and adds the scan-scope extras: the `targetDirs` the duplication scanner walks, a bounded refresh timeout mirroring crap/MI, and `ignoreGlobs` to exclude files from the scan.',
   properties: {
-    ...GATE_BASE,
-    targetDirs: LIST_OR_EXTENDER_OF_STRINGS,
-    // Bounded timeout (ms) for the `npm run duplication:update` scanner spawn.
-    // Mirrors `crap.refreshTimeoutMs` / `maintainability.refreshTimeoutMs`.
-    refreshTimeoutMs: { type: 'integer', minimum: 1 },
-    // Glob patterns matched against canonicalised repo-relative paths to
-    // exclude files from duplication discovery before scoring. Orthogonal to
-    // `components` (grouping). Absent/empty preserves existing behaviour.
-    ignoreGlobs: { type: 'array', items: { type: 'string', minLength: 1 } },
+    ...gateBase({
+      enabled: false,
+      baselinePath: 'baselines/duplication.json',
+      tolerance: { kind: 'absolute', value: 1 },
+      floors: { '*': { percentage: 25 } },
+    }),
+    targetDirs: {
+      ...LIST_OR_EXTENDER_OF_STRINGS,
+      description:
+        "Directories whose JS sources the duplication (DRY) gate scans for copy-paste clones. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal (Story #3664).",
+      default: ['src'],
+    },
+    refreshTimeoutMs: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Bounded timeout (ms) for `npm run duplication:update` spawned by the baseline-attribution refresh path. Mirrors `crap.refreshTimeoutMs` / `coverage.timeoutMs`: a SIGKILL fired at the budget boundary maps to exit 124. Default 60000 (Story #3664).',
+      default: 60000,
+    },
+    ignoreGlobs: {
+      type: 'array',
+      items: { type: 'string', minLength: 1 },
+      description:
+        'Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from duplication discovery before scanning. Orthogonal to `components` (grouping). Absent or empty preserves the existing behaviour (Story #3664).',
+      default: [],
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/index.js

@@ -14,14 +14,17 @@ import { MUTATION_GATE } from './mutation.schema.js';
  *
  * Split from the former `lib/config-gates-schema.js` aggregate
  * (Story #2987) into per-gate sub-schema files under
- * `lib/config/gates/`. Shared fragments (`GATE_BASE`, `SAFE_STRING`,
+ * `lib/config/gates/`. Shared fragments (`gateBase()`, `SAFE_STRING`,
  * `TOLERANCE_SCHEMA`, `FLOORS_SCHEMA`, `COMPONENTS_SCHEMA`,
  * `LIST_OR_EXTENDER_OF_STRINGS`, `NULLABLE_NONEMPTY_SAFE_STRING`) live
  * in `./shared.js`. Each per-gate file exports one sub-schema literal
- * with the gate-specific extras layered on top of `GATE_BASE`.
+ * with the gate-specific extras layered on top of `gateBase()`, passing
+ * that gate's own base-field defaults (Story #5007).
  */
 export const GATES_SCHEMA = {
   type: 'object',
+  description:
+    'The eight quality gates, each sharing the `{ enabled, baselinePath, tolerance, floors, components }` base.',
   properties: {
     lint: LINT_GATE,
     coverage: COVERAGE_GATE,

package/.agents/scripts/lib/config/gates/lighthouse.schema.js

@@ -1,23 +1,51 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
-import { GATE_BASE, NULLABLE_NONEMPTY_SAFE_STRING } from './shared.js';
+import { gateBase, NULLABLE_NONEMPTY_SAFE_STRING } from './shared.js';
 
 const LIGHTHOUSE_ROUTE = {
   type: 'object',
+  description: 'One route the Lighthouse run scores.',
   required: ['path'],
   properties: {
-    path: { type: 'string', minLength: 1 },
-    formFactor: { type: 'string', enum: ['mobile', 'desktop'] },
+    path: {
+      type: 'string',
+      minLength: 1,
+      description: 'Route path appended to `baseUrl`.',
+    },
+    formFactor: {
+      type: 'string',
+      enum: ['mobile', 'desktop'],
+      description: 'Emulated form factor for this route.',
+    },
   },
   additionalProperties: false,
 };
 
 export const LIGHTHOUSE_GATE = {
   type: 'object',
+  description:
+    'Lighthouse category-score ratchet for web targets. Off by default — it needs a running deployment.',
   properties: {
-    ...GATE_BASE,
-    baseUrl: NULLABLE_NONEMPTY_SAFE_STRING,
-    routes: { type: 'array', items: LIGHTHOUSE_ROUTE },
+    ...gateBase({
+      enabled: false,
+      baselinePath: 'baselines/lighthouse.json',
+      tolerance: { kind: 'absolute', value: 0 },
+      floors: {
+        '*': { performance: 0, accessibility: 0, bestPractices: 0, seo: 0 },
+      },
+    }),
+    baseUrl: {
+      ...NULLABLE_NONEMPTY_SAFE_STRING,
+      description:
+        'Origin the routes are resolved against. `null` leaves the gate unusable, which is why it ships disabled.',
+      default: null,
+    },
+    routes: {
+      type: 'array',
+      items: LIGHTHOUSE_ROUTE,
+      description: 'Routes to score on each run.',
+      default: [],
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/lint.schema.js

@@ -1,9 +1,18 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
-import { GATE_BASE } from './shared.js';
+import { gateBase } from './shared.js';
 
 export const LINT_GATE = {
   type: 'object',
-  properties: { ...GATE_BASE },
+  description:
+    'Lint-count ratchet. Floors are absolute error/warning counts; the baseline pins the current count so a regression is visible even while the floor is not yet met.',
+  properties: {
+    ...gateBase({
+      enabled: true,
+      baselinePath: 'baselines/lint.json',
+      tolerance: { kind: 'absolute', value: 0 },
+      floors: { '*': { errorCount: 0 } },
+    }),
+  },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/maintainability.schema.js

@@ -1,29 +1,51 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
+import { MAINTAINABILITY_GATE_DEFAULTS } from '../quality.js';
 import {
-  GATE_BASE,
+  gateBase,
   LIST_OR_EXTENDER_OF_STRINGS,
   SAFE_STRING,
 } from './shared.js';
 
 export const MAINTAINABILITY_GATE = {
   type: 'object',
+  description:
+    'Maintainability-index ratchet. Scores per file as the average over its methods, so deleting a small high-MI method can legitimately lower a file’s score.',
   properties: {
-    ...GATE_BASE,
-    targetDirs: LIST_OR_EXTENDER_OF_STRINGS,
+    ...gateBase({
+      enabled: MAINTAINABILITY_GATE_DEFAULTS.enabled,
+      baselinePath: MAINTAINABILITY_GATE_DEFAULTS.baselinePath,
+      tolerance: MAINTAINABILITY_GATE_DEFAULTS.tolerance,
+      floors: MAINTAINABILITY_GATE_DEFAULTS.floors,
+    }),
+    targetDirs: {
+      ...LIST_OR_EXTENDER_OF_STRINGS,
+      description:
+        "Directories whose JS sources the maintainability gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/` plus `tests/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal.",
+      default: [...MAINTAINABILITY_GATE_DEFAULTS.targetDirs],
+    },
     // Story #4731 — commit-subject substring that acknowledges a deliberate
-    // maintainability baseline refresh in the compared range. Mirrors the CRAP
-    // gate's `refreshTag`; a range commit carrying it that touches the baseline
-    // file demotes head-vs-base regressions (floors still enforced).
-    refreshTag: { ...SAFE_STRING, minLength: 1 },
-    // Story #2165 — bounded timeout for `npm run maintainability:update`
-    // spawned by the baseline-attribution refresh path. Mirrors
-    // `coverage.timeoutMs` (Story #2142).
-    refreshTimeoutMs: { type: 'integer', minimum: 1 },
-    // Story #3217 — glob patterns matched against canonicalised repo-relative
-    // paths to exclude files from MI discovery before scoring. Orthogonal to
-    // `components` (grouping). Absent/empty preserves existing behaviour.
-    ignoreGlobs: { type: 'array', items: { type: 'string', minLength: 1 } },
+    // maintainability baseline refresh in the compared range.
+    refreshTag: {
+      ...SAFE_STRING,
+      minLength: 1,
+      description:
+        "Commit-subject substring that acknowledges a deliberate maintainability baseline refresh in the compared range. Mirrors the CRAP gate's `refreshTag`; a range commit carrying it that touches the baseline file demotes head-vs-base regressions (floors still enforced).",
+    },
+    refreshTimeoutMs: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Bounded timeout (ms) for `npm run maintainability:update` spawned by the baseline-attribution refresh path. Mirrors `coverage.timeoutMs`: a SIGKILL fired at the budget boundary maps to exit 124 so the close orchestrator can flip the Story to `agent::blocked`. Default 60000 (Story #2165).',
+      default: MAINTAINABILITY_GATE_DEFAULTS.refreshTimeoutMs,
+    },
+    ignoreGlobs: {
+      type: 'array',
+      items: { type: 'string', minLength: 1 },
+      description:
+        'Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from MI discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217).',
+      default: [...MAINTAINABILITY_GATE_DEFAULTS.ignoreGlobs],
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/mutation.schema.js

@@ -1,12 +1,24 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
-import { GATE_BASE, NULLABLE_NONEMPTY_SAFE_STRING } from './shared.js';
+import { gateBase, NULLABLE_NONEMPTY_SAFE_STRING } from './shared.js';
 
 export const MUTATION_GATE = {
   type: 'object',
+  description:
+    'Stryker mutation-score ratchet. Off in practice for most consumers — the baseline kind is registered but no framework path runs Stryker.',
   properties: {
-    ...GATE_BASE,
-    strykerConfigPath: NULLABLE_NONEMPTY_SAFE_STRING,
+    ...gateBase({
+      enabled: true,
+      baselinePath: 'baselines/mutation.json',
+      tolerance: { kind: 'percent', value: 0 },
+      floors: { '*': { score: 60 } },
+    }),
+    strykerConfigPath: {
+      ...NULLABLE_NONEMPTY_SAFE_STRING,
+      description:
+        'Repo-relative path to the Stryker config. `null` lets Stryker resolve its own default.',
+      default: null,
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/shared.js

@@ -48,10 +48,21 @@ export const LIST_OR_EXTENDER_OF_STRINGS = {
 /** Object-shaped tolerance: `{ kind: 'absolute' | 'percent', value: number }`. */
 export const TOLERANCE_SCHEMA = {
   type: 'object',
+  description:
+    'How much a rollup may drift from the committed baseline before the gate reports a regression.',
   required: ['kind', 'value'],
   properties: {
-    kind: { type: 'string', enum: ['absolute', 'percent'] },
-    value: { type: 'number', minimum: 0 },
+    kind: {
+      type: 'string',
+      enum: ['absolute', 'percent'],
+      description:
+        'Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`).',
+    },
+    value: {
+      type: 'number',
+      minimum: 0,
+      description: 'The tolerance magnitude. 0 means no drift is allowed.',
+    },
   },
   additionalProperties: false,
 };
@@ -84,6 +95,8 @@ export const TOLERANCE_SCHEMA = {
  */
 export const FLOORS_SCHEMA = {
   type: 'object',
+  description:
+    'Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.',
   additionalProperties: {
     type: 'object',
     additionalProperties: { type: 'number' },
@@ -102,16 +115,52 @@ export const FLOORS_SCHEMA = {
  */
 export const COMPONENTS_SCHEMA = {
   type: 'object',
+  description:
+    'Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer.',
   additionalProperties: {
     type: 'array',
     items: { type: 'string', minLength: 1 },
   },
 };
 
-export const GATE_BASE = {
-  enabled: { type: 'boolean' },
-  baselinePath: { ...SAFE_STRING, minLength: 1 },
-  tolerance: TOLERANCE_SCHEMA,
-  floors: FLOORS_SCHEMA,
-  components: COMPONENTS_SCHEMA,
-};
+/**
+ * Build the shared four-field gate base with per-gate `default` annotations
+ * layered on (Story #5007). The base fields are identical in shape across
+ * every gate but their defaults are not — each gate ships its own
+ * `baselinePath`, tolerance, and floors — so the defaults are supplied by the
+ * calling gate module rather than baked in here.
+ *
+ * @param {{ enabled?: boolean, baselinePath?: string,
+ *   tolerance?: object, floors?: object }} [defaults]
+ * @returns {object} A fresh `properties` fragment; never a shared reference.
+ */
+export function gateBase(defaults = {}) {
+  return {
+    enabled: {
+      type: 'boolean',
+      description:
+        'When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted.',
+      ...(defaults.enabled === undefined ? {} : { default: defaults.enabled }),
+    },
+    baselinePath: {
+      ...SAFE_STRING,
+      minLength: 1,
+      description:
+        "Repo-root-relative path to the gate's committed baseline artifact.",
+      ...(defaults.baselinePath === undefined
+        ? {}
+        : { default: defaults.baselinePath }),
+    },
+    tolerance: {
+      ...TOLERANCE_SCHEMA,
+      ...(defaults.tolerance === undefined
+        ? {}
+        : { default: defaults.tolerance }),
+    },
+    floors: {
+      ...FLOORS_SCHEMA,
+      ...(defaults.floors === undefined ? {} : { default: defaults.floors }),
+    },
+    components: COMPONENTS_SCHEMA,
+  };
+}

package/.agents/scripts/lib/config/github.js

@@ -61,7 +61,6 @@ export const NOTIFICATIONS_DEFAULTS = Object.freeze({
     'operator-message',
     'merge.unlanded',
     'merge.flip-failed',
-    'loop.tick',
   ]),
 });