mandrel 2.31.0 → 2.33.0

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

@@ -109,6 +109,59 @@ function tolerantMergeWatchMode(value) {
   }
 }
 
+/**
+ * Shortest override reason that can plausibly name a rejected finding. Below
+ * this, the flag is being used to silence the gate rather than to record a
+ * judgement, which is the failure mode the reason requirement exists to stop.
+ */
+const MIN_OVERRIDE_REASON_LENGTH = 12;
+
+/**
+ * Parse `--override-review-block <reason>` — the sanctioned,
+ * logged override of a Story-scope code-review critical blocker.
+ *
+ * The reason is **mandatory and validated**, because the alternative it
+ * replaces is not "no override" but `gh pr merge` run by hand: before this
+ * flag, a review blocker the operator had reviewed and rejected left bypassing
+ * the gate entirely as the only way to land, and that bypass wrote nothing
+ * down anywhere. An override that records why is strictly more auditable than
+ * the hand-merge it displaces; an override that records nothing is not, so a
+ * bare or blank `--override-review-block` fails closed here — before any phase
+ * runs, at no mutation cost — rather than arming a silent one.
+ *
+ * @param {unknown} value
+ * @returns {string|undefined} the trimmed reason, or `undefined` when absent.
+ */
+export function parseOverrideReviewBlock(value) {
+  if (value == null) return undefined;
+  // `parseArgs` with `strict: false` yields `true` for a bare string flag.
+  const reason = typeof value === 'string' ? value.trim() : '';
+  if (reason.length >= MIN_OVERRIDE_REASON_LENGTH) return reason;
+  throw new Error(
+    '--override-review-block requires a reason of at least ' +
+      `${MIN_OVERRIDE_REASON_LENGTH} characters naming the finding you reviewed ` +
+      `and rejected (got ${JSON.stringify(value)}). The reason is posted to the ` +
+      'PR and the Story and recorded as friction telemetry.',
+  );
+}
+
+/**
+ * {@link parseOverrideReviewBlock} degraded to absent instead of throwing, for
+ * the tolerant reporting parse. Same contract as
+ * {@link tolerantMergeWatchMode}: safe only because a tolerant parse runs no
+ * phase.
+ *
+ * @param {unknown} value
+ * @returns {string|undefined}
+ */
+function tolerantOverrideReviewBlock(value) {
+  try {
+    return parseOverrideReviewBlock(value);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Standardized CLI argument parser for sprint scripts.
  * Supports options like --epic, --story, --dry-run, --skip-dashboard.
@@ -147,6 +200,11 @@ export function parseSprintArgs(
       // Absent means "use the config"; see `parseMergeWatchMode` for why an
       // unrecognized value fails closed instead of degrading to absent.
       'merge-watch-mode': { type: 'string' },
+      // Sanctioned override of a code-review critical blocker.
+      // Absent means "the blocker blocks"; see `parseOverrideReviewBlock` for
+      // why a bare or too-short reason fails closed instead of arming a silent
+      // override.
+      'override-review-block': { type: 'string' },
       executor: { type: 'string' },
       cwd: { type: 'string' },
       'recut-of': { type: 'string' },
@@ -183,6 +241,12 @@ export function parseSprintArgs(
     mergeWatchMode: tolerant
       ? tolerantMergeWatchMode(values['merge-watch-mode'])
       : parseMergeWatchMode(values['merge-watch-mode']),
+    // The operator's recorded reason for overriding a review
+    // blocker. `undefined` when the flag is absent, which is what keeps the
+    // blocker blocking by default.
+    overrideReviewBlock: tolerant
+      ? tolerantOverrideReviewBlock(values['override-review-block'])
+      : parseOverrideReviewBlock(values['override-review-block']),
     executor: values.executor ?? null,
     // Resolve worktree cwd from flag or env. Empty string/whitespace → null.
     cwd:

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

@@ -327,8 +327,8 @@ export function buildDefaultGates({
     ...buildTestGateEntry(coverageCaptureActive),
     {
       // Gate name kept generic ("format") so the close-orchestrator log line
-      // and the per-gate phase-timer key don't shift when a repo swaps biome
-      // for Prettier / dprint via `project.commands.formatCheck`. The
+      // 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: formatCmd,

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

@@ -87,9 +87,9 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  * `<tempRoot>/standalone/stories/story-<id>/validation-evidence.json`
  * keyspace. v2.0.0 removed the Epic tier and its Epic-keyed keyspace.
  *
- * `onGateStart` is invoked immediately before each gate's runner spawn.
- * story-close uses it to drive `phaseTimer.mark(...)` for per-gate
- * wall-clock telemetry. Errors thrown from the hook propagate.
+ * `onGateStart` is invoked immediately before each gate's runner spawn, so a
+ * caller can record per-gate wall-clock telemetry. Errors thrown from the
+ * hook propagate.
  *
  * Projection advisories (Story #4776): when `baseBranch` and `storyBranch`
  * are both supplied and every gate passed, the maintainability and CRAP

package/.agents/scripts/lib/config/acceptance-eval.js

@@ -38,7 +38,6 @@
  */
 export const ACCEPTANCE_EVAL_DEFAULTS = Object.freeze({
   maxRounds: 2,
-  clusterCeiling: 4,
 });
 
 /**
@@ -51,22 +50,6 @@ export const ACCEPTANCE_EVAL_DEFAULTS = Object.freeze({
  */
 export const ACCEPTANCE_EVAL_MAX_ROUNDS_CEILING = 5;
 
-/**
- * Hard, undisableable ceiling on `clusterCeiling` — the max ACs one
- * single-delivery acceptance critic scores in a single fresh-context pass
- * (Epic #4475, M4-B, design §S2a). It is the **acceptance-dilution guard**:
- * single delivery collapses the whole Epic into one session, so the only
- * acceptance coverage left is the per-AC-cluster critic fan-out
- * (`ceil(totalACs / clusterCeiling)` independent maker-blind passes). A
- * pathologically large `clusterCeiling` would collapse that fan-out to a
- * single critic scoring every AC at once — exactly the dilution the design
- * forecloses — so a configured value above this ceiling is clamped down to
- * it. Kept small on purpose.
- *
- * @type {number}
- */
-export const ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX = 8;
-
 /**
  * Clamp a candidate round count into the inviolable `[1, ceiling]` range.
  * Non-integer / non-finite inputs fall back to the documented default.
@@ -85,43 +68,19 @@ function clampRounds(value, fallback) {
   return candidate;
 }
 
-/**
- * Clamp a candidate cluster ceiling into the inviolable
- * `[1, ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX]` range. Non-integer / non-finite
- * inputs fall back to the documented default. Mirrors `clampRounds` — the
- * anti-dilution guard cannot be disabled (`clusterCeiling: 0` or a negative
- * clamps up to 1; an over-max value clamps down to the hard cap).
- *
- * @param {unknown} value
- * @param {number} fallback
- * @returns {number}
- */
-function clampClusterCeiling(value, fallback) {
-  const candidate =
-    typeof value === 'number' && Number.isInteger(value) ? value : fallback;
-  if (candidate < 1) return 1;
-  if (candidate > ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX) {
-    return ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX;
-  }
-  return candidate;
-}
-
 /**
  * Read the merged acceptance-eval block. Returns the canonical shape:
  *
  *   {
- *     maxRounds: number,        // clamped into [1, roundsCeiling]
- *     ceiling: number,          // the undisableable hard cap on rounds
- *     clusterCeiling: number,   // clamped into [1, clusterCeilingMax]
- *     clusterCeilingMax: number // the undisableable hard cap on cluster size
+ *     maxRounds: number,  // clamped into [1, ceiling]
+ *     ceiling: number     // the undisableable hard cap on rounds
  *   }
  *
- * `maxRounds` is always a positive integer no greater than `ceiling`;
- * `clusterCeiling` is always a positive integer no greater than
- * `clusterCeilingMax`, regardless of what the resolved config carried.
+ * `maxRounds` is always a positive integer no greater than `ceiling`,
+ * regardless of what the resolved config carried.
  *
  * @param {object | null | undefined} config
- * @returns {{ maxRounds: number, ceiling: number, clusterCeiling: number, clusterCeilingMax: number }}
+ * @returns {{ maxRounds: number, ceiling: number }}
  */
 export function getAcceptanceEval(config) {
   const user = config?.delivery?.acceptanceEval ?? {};
@@ -129,14 +88,8 @@ export function getAcceptanceEval(config) {
     user.maxRounds,
     ACCEPTANCE_EVAL_DEFAULTS.maxRounds,
   );
-  const clusterCeiling = clampClusterCeiling(
-    user.clusterCeiling,
-    ACCEPTANCE_EVAL_DEFAULTS.clusterCeiling,
-  );
   return {
     maxRounds,
     ceiling: ACCEPTANCE_EVAL_MAX_ROUNDS_CEILING,
-    clusterCeiling,
-    clusterCeilingMax: ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX,
   };
 }

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

@@ -1,12 +1,11 @@
 /**
  * `project.commands` accessor (Epic #1720 Story #1739 — top-level reshape).
  *
- * The surviving five command keys are `lintBaseline`, `test`,
- * `typecheck`, `formatCheck`, `formatWrite`.
+ * The surviving four command keys are `test`, `typecheck`,
+ * `formatCheck`, `formatWrite`.
  */
 
 export const COMMANDS_DEFAULTS = Object.freeze({
-  lintBaseline: 'npx eslint . --format json',
   test: 'npm test',
   typecheck: null,
   formatCheck: 'npx biome format .',
@@ -19,12 +18,11 @@ export const COMMANDS_DEFAULTS = Object.freeze({
  * a bare `{ project }` bag.
  *
  * @param {object | null | undefined} config
- * @returns {{ lintBaseline: string, test: string, typecheck: string|null, formatCheck: string, formatWrite: string }}
+ * @returns {{ test: string, typecheck: string|null, formatCheck: string, formatWrite: string }}
  */
 export function getCommands(config) {
   const commands = config?.project?.commands ?? {};
   return {
-    lintBaseline: commands.lintBaseline ?? COMMANDS_DEFAULTS.lintBaseline,
     test: commands.test ?? COMMANDS_DEFAULTS.test,
     typecheck:
       commands.typecheck === undefined

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,
 };