mandrel 1.57.0

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

@@ -0,0 +1,30 @@
+/**
+ * `delivery.ci` accessor + framework defaults — Story #2899 (Epic #2880, F13).
+ *
+ * `delivery.ci.skipForStoryPushes` defaults to `true` so per-Task Story-branch
+ * commits append a `[skip ci]` trailer out of the box. The Epic-branch merge
+ * commit produced by `story-close.js`'s merge runner never carries the
+ * marker — that path is the one consumers actually want CI to evaluate.
+ */
+
+export const CI_DELIVERY_DEFAULTS = Object.freeze({
+  skipForStoryPushes: true,
+});
+
+/**
+ * Read the merged `delivery.ci` block, applying framework defaults for any
+ * field the operator omitted. Accepts the full resolved config, the bare
+ * delivery bag, or the bare ci bag.
+ *
+ * @param {object | null | undefined} config
+ * @returns {typeof CI_DELIVERY_DEFAULTS}
+ */
+export function getCiDelivery(config) {
+  const ci = config?.delivery?.ci ?? config?.ci ?? config ?? {};
+  return {
+    skipForStoryPushes:
+      typeof ci.skipForStoryPushes === 'boolean'
+        ? ci.skipForStoryPushes
+        : CI_DELIVERY_DEFAULTS.skipForStoryPushes,
+  };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * `project.commands` accessor (Epic #1720 Story #1739 — top-level reshape).
+ *
+ * The surviving five command keys are `lintBaseline`, `test`,
+ * `typecheck`, `formatCheck`, `formatWrite`.
+ */
+
+export const COMMANDS_DEFAULTS = Object.freeze({
+  lintBaseline: 'npx eslint . --format json',
+  test: 'npm test',
+  typecheck: null,
+  formatCheck: 'npx biome format .',
+  formatWrite: 'npx biome format --write .',
+});
+
+/**
+ * Read the grouped `project.commands` block, applying framework defaults
+ * for any field the operator omitted. Accepts the full resolved config or
+ * a bare `{ project }` bag.
+ *
+ * @param {object | null | undefined} config
+ * @returns {{ lintBaseline: string, 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
+        ? COMMANDS_DEFAULTS.typecheck
+        : commands.typecheck,
+    formatCheck: commands.formatCheck ?? COMMANDS_DEFAULTS.formatCheck,
+    formatWrite: commands.formatWrite ?? COMMANDS_DEFAULTS.formatWrite,
+  };
+}

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

@@ -0,0 +1,119 @@
+/**
+ * `getAgentrcDefaults()` — single source of `.agentrc.json` defaults.
+ *
+ * `.agents/docs/agentrc-reference.json` is the authoritative editor-reference
+ * inventory of every field the framework supports plus its default
+ * value. Runtime accessors under `lib/config/*.js` (`COMMANDS_DEFAULTS`,
+ * `BRANCH_PROTECTION_DEFAULTS`, gate defaults, etc.) layer the same
+ * values onto whatever the project config carries; a parity test
+ * (tests/config/full-agentrc-runtime-parity.test.js) keeps the two in
+ * lockstep.
+ *
+ * Story #1995: the `/agents-update` sync helper consults this module
+ * (not the template directly) to decide whether a project value is
+ * "just the default" and therefore safe to omit from `.agentrc.json`.
+ *
+ * Identity placeholders (`[OWNER]`, `[REPO]`, `@[USERNAME]`) carry no
+ * meaningful default — the operator must set them. They survive in
+ * the returned object so the consumer can see the expected shape, but
+ * the sync helper treats them as "no usable default" via
+ * `IDENTITY_PLACEHOLDER_PATHS`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// .agents/scripts/lib/config/ → .agents/
+const AGENTS_ROOT = path.resolve(__dirname, '../../..');
+export const FULL_AGENTRC_PATH = path.join(
+  AGENTS_ROOT,
+  'docs',
+  'agentrc-reference.json',
+);
+
+/**
+ * Dotted paths whose template value is a human placeholder
+ * (`[OWNER]`, `[REPO]`, `@[USERNAME]`). The sync helper treats these
+ * as "no default" — they are never auto-filled, and a project value
+ * present at one of these paths is never flagged as redundant.
+ */
+export const IDENTITY_PLACEHOLDER_PATHS = Object.freeze([
+  'github.owner',
+  'github.repo',
+  'github.operatorHandle',
+]);
+
+let _cache = null;
+
+/**
+ * Parse `.agents/docs/agentrc-reference.json` and return a deep-frozen snapshot.
+ *
+ * @param {{ bustCache?: boolean }} [opts]
+ * @returns {object}
+ */
+export function getAgentrcDefaults(opts = {}) {
+  if (!opts.bustCache && _cache) return _cache;
+  const raw = fs.readFileSync(FULL_AGENTRC_PATH, 'utf8');
+  const parsed = JSON.parse(raw);
+  // Strip the `$schema` pointer — it's editor metadata, not a default.
+  delete parsed.$schema;
+  _cache = deepFreeze(parsed);
+  return _cache;
+}
+
+function deepFreeze(obj) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  for (const key of Object.keys(obj)) deepFreeze(obj[key]);
+  return Object.freeze(obj);
+}
+
+/**
+ * Walk a default object and yield `[dottedPath, value]` for every
+ * scalar / array leaf. Objects are descended into, not yielded.
+ *
+ * @param {object} defaults
+ * @returns {Generator<[string, unknown]>}
+ */
+export function* iterDefaultLeaves(defaults, prefix = '') {
+  if (defaults === null || typeof defaults !== 'object') return;
+  if (Array.isArray(defaults)) {
+    if (prefix) yield [prefix, defaults];
+    return;
+  }
+  for (const [key, value] of Object.entries(defaults)) {
+    const dotted = prefix ? `${prefix}.${key}` : key;
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      yield* iterDefaultLeaves(value, dotted);
+    } else {
+      yield [dotted, value];
+    }
+  }
+}
+
+/**
+ * Look up a dotted path inside an arbitrary nested object.
+ * Returns `{ present: boolean, value: unknown }`.
+ *
+ * @param {object|null|undefined} obj
+ * @param {string} dottedPath
+ */
+export function lookupPath(obj, dottedPath) {
+  if (obj == null || typeof obj !== 'object') {
+    return { present: false, value: undefined };
+  }
+  const parts = dottedPath.split('.');
+  let cursor = obj;
+  for (let i = 0; i < parts.length; i += 1) {
+    if (
+      cursor === null ||
+      typeof cursor !== 'object' ||
+      !Object.hasOwn(cursor, parts[i])
+    ) {
+      return { present: false, value: undefined };
+    }
+    cursor = cursor[parts[i]];
+  }
+  return { present: true, value: cursor };
+}

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

@@ -0,0 +1,348 @@
+/**
+ * Config-explain capability (Story #3523, Epic #3438).
+ *
+ * `explainConfig()` answers the operator question "what does each resolved
+ * config key mean, what is its effective value, and where did that value
+ * come from?". It pairs with the unified config resolver: the resolver
+ * decides the *effective* value, this module attributes that value to a
+ * *source* layer and pins a one-line *meaning* to every key.
+ *
+ * Source attribution is two-valued (Story #3690 removed the named
+ * config-profile layer):
+ *   - `agentrc`  — the key is present in the project's resolved `.agentrc.json`
+ *                  (including any `.agentrc.local.json` overlay). The operator
+ *                  set it.
+ *   - `default`  — the project does not carry the key; the framework default
+ *                  from `.agents/docs/agentrc-reference.json` applies.
+ *
+ * Secret hygiene: no key in the `.agentrc.json` surface is a credential today,
+ * but the report is defensive — any key whose dotted path matches a
+ * secret-shaped token (`token`, `secret`, `password`, `apiKey`, `credential`,
+ * …) has its value redacted to `null` and is flagged `redacted: true`. Only
+ * the *source* of a secret is ever reported, never the value.
+ */
+
+import { resolveConfig } from '../config-resolver.js';
+import {
+  getAgentrcDefaults,
+  iterDefaultLeaves,
+  lookupPath,
+} from './defaults.js';
+
+/**
+ * Dotted-path segment patterns that mark a key as secret-bearing. Matched
+ * case-insensitively against any segment of the dotted path. The
+ * `.agentrc.json` schema carries none of these today; the guard is forward
+ * defence so a future credential-shaped key never leaks its value through
+ * `mandrel explain`.
+ *
+ * @type {readonly RegExp[]}
+ */
+const SECRET_SEGMENT_PATTERNS = Object.freeze([
+  /secret/i,
+  /password/i,
+  /passwd/i,
+  /token/i,
+  /credential/i,
+  /apikey/i,
+  /api[-_]?key/i,
+  /(^|[^a-z])key$/i,
+  /private/i,
+]);
+
+/**
+ * Curated one-line meanings keyed by dotted config path. Wildcard floor
+ * paths (`...floors.*`) are covered by the prefix fallbacks below, so this
+ * map pins the operator-facing keys that benefit from a bespoke gloss. Any
+ * key without an exact entry falls back to the longest matching prefix gloss,
+ * then to a top-level block gloss, so every key always reports a non-empty
+ * meaning.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const KEY_MEANINGS = Object.freeze({
+  // project.*
+  'project.baseBranch':
+    'Default base branch Epics and Stories branch from and merge back into.',
+  'project.paths.agentRoot':
+    'Directory holding the distributed agent bundle (instructions, skills, scripts).',
+  'project.paths.docsRoot':
+    'Directory the mandatory docs-context reads resolve against.',
+  'project.paths.tempRoot':
+    'Root for gitignored scratch output (per-Epic 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).',
+  'project.commands.formatCheck':
+    'Format-verify command run without modifying files.',
+  'project.commands.formatWrite':
+    'Format-write command that applies formatting in place.',
+
+  // github.*
+  'github.owner': 'GitHub owner/org the repo lives under.',
+  'github.repo': 'GitHub repository name for ticket and PR operations.',
+  'github.projectNumber':
+    'GitHub Projects (v2) board number tickets are added to.',
+  'github.projectOwner': 'Owner of the GitHub Projects board.',
+  'github.operatorHandle':
+    'GitHub @handle mentioned when a run needs operator attention.',
+  'github.branchProtection.enforce':
+    'Whether the framework applies branch-protection rules.',
+  'github.branchProtection.requiredChecks':
+    'Status checks that must pass before a PR can merge.',
+  'github.mergeMethods.allow_squash_merge':
+    'Whether squash-merge is permitted on PRs.',
+  'github.mergeMethods.allow_rebase_merge':
+    'Whether rebase-merge is permitted on PRs.',
+  'github.mergeMethods.allow_merge_commit':
+    'Whether merge-commit merges are permitted on PRs.',
+  'github.mergeMethods.allow_auto_merge':
+    'Whether GitHub auto-merge is enabled for the repo.',
+  'github.mergeMethods.delete_branch_on_merge':
+    'Whether head branches are deleted after merge.',
+  'github.notifications.mentionOperator':
+    'Whether notifications @-mention the operator handle.',
+  'github.notifications.commentEvents':
+    'Allowlist of events that post a GitHub comment notification.',
+  'github.notifications.webhookEvents':
+    'Allowlist of events that fire a webhook notification.',
+
+  // planning.*
+  'planning.maxTickets':
+    'Upper bound on tickets a single /epic-plan run may create.',
+  'planning.context.maxBytes':
+    'Byte budget for the planning-context payload before summary mode kicks in.',
+  'planning.context.summaryMode':
+    'When the planner switches to a summarized context representation.',
+  'planning.codebaseSnapshot.tier':
+    'Depth of the structural codebase view threaded into spec authoring.',
+  'planning.codebaseSnapshot.include':
+    'Glob patterns included in the codebase snapshot.',
+  'planning.codebaseSnapshot.exclude':
+    'Glob patterns excluded from the codebase snapshot.',
+  'planning.codebaseSnapshot.recentCommitWindow':
+    'How many recent commits the snapshot summarizes.',
+  'planning.riskHeuristics':
+    'Phrases that flag a Story as high-risk for HITL escalation.',
+  'planning.taskSizing.maxAcceptance':
+    'Hard ceiling on acceptance criteria per Story.',
+  'planning.taskSizing.softAcceptanceCount':
+    'Acceptance-criteria count above which a Story is flagged as large.',
+  'planning.taskSizing.softFiles':
+    'Touched-file count above which a Story is flagged as large.',
+  'planning.taskSizing.hardFiles':
+    'Touched-file count above which a Story is rejected unless it declares `wide` with a reason.',
+  'planning.failOnSharedEditors':
+    'Whether shared-editor conflict findings are promoted to hard errors.',
+  'planning.requireExplicitCrossStoryDeps':
+    'Whether implicit cross-Story dependencies are promoted to hard errors.',
+
+  // delivery.*
+  'delivery.execution.timeoutMs':
+    'Per-execution timeout for orchestrated delivery steps.',
+  'delivery.maxTokenBudget':
+    'Cap on the hydrated task-prompt size handed to an agent.',
+  'delivery.lease.ttlMs':
+    'Time-to-live for the Epic lease before a stale claim is reclaimable.',
+  'delivery.ci.skipForStoryPushes':
+    'Whether Story-branch pushes carry a [skip ci] trailer.',
+  'delivery.preflight.maxStories':
+    'Pre-dispatch ceiling on estimated Story count (no cap when unset).',
+  'delivery.preflight.maxWaves':
+    'Pre-dispatch ceiling on estimated wave count.',
+  'delivery.preflight.maxInstallCostSeconds':
+    'Pre-dispatch ceiling on estimated dependency-install seconds.',
+  'delivery.preflight.maxGithubApiRequests':
+    'Pre-dispatch ceiling on estimated GitHub API request volume.',
+  'delivery.preflight.maxClaudeQuotaTokens':
+    'Pre-dispatch ceiling on estimated Claude quota-token burn.',
+  'delivery.docsFreshness.paths':
+    'Docs whose freshness is checked at delivery time.',
+  '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-wave Epics with adequate parallel-agent quota should raise this to reduce wall-clock time proportionally.',
+  'delivery.deliverRunner.progressReportIntervalSec':
+    'Cadence for delivery progress reporting.',
+  'delivery.deliverRunner.verifyConcurrencyCap':
+    'Maximum verify steps run in parallel.',
+  'delivery.worktreeIsolation.enabled':
+    'Whether each Story runs in its own git worktree.',
+  'delivery.worktreeIsolation.root':
+    'Directory under which per-Story worktrees are created.',
+  'delivery.worktreeIsolation.nodeModulesStrategy':
+    'How node_modules is provisioned per worktree.',
+  'delivery.worktreeIsolation.primeFromPath':
+    'Source path a worktree primes its node_modules from.',
+  'delivery.worktreeIsolation.allowSymlinkOnWindows':
+    'Whether symlink node_modules strategy is allowed on Windows.',
+  'delivery.worktreeIsolation.reapOnSuccess':
+    'Whether a worktree is removed after a Story closes cleanly.',
+  'delivery.worktreeIsolation.reapOnCancel':
+    'Whether a worktree is removed after a cancelled run.',
+  'delivery.worktreeIsolation.bootstrapFiles':
+    'Files copied into each new worktree (e.g. .env, .mcp.json).',
+  'delivery.codeReview.providers':
+    'Ordered provider chain the code-review phase consults.',
+  'delivery.codeReview.maxFixAttempts':
+    'Maximum auto-fix attempts the code-review phase makes.',
+  'delivery.codeReview.maxFixScopeFiles':
+    'Maximum files an auto-fix may touch in one attempt.',
+  'delivery.refactorStage.enabled':
+    '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).',
+
+  // qa.*
+  'qa.featureRoot': 'Root directory holding the QA harness .feature files.',
+  'qa.fixturesManifest': 'Path to the QA fixtures manifest.',
+  'qa.consoleAllowlist': 'Console-message patterns the QA harness tolerates.',
+  'qa.designTokens': 'Path to the design-token source the QA harness checks.',
+});
+
+/**
+ * Prefix-keyed fallback glosses. Used when a key has no exact entry in
+ * `KEY_MEANINGS` (notably wildcard floor paths and per-gate sub-keys). The
+ * longest matching prefix wins.
+ *
+ * @type {ReadonlyArray<[string, string]>}
+ */
+const PREFIX_MEANINGS = Object.freeze([
+  [
+    'delivery.quality.gates',
+    'Quality-gate threshold/configuration for the delivery close gate.',
+  ],
+  [
+    'delivery.quality.codingGuardrails',
+    'Per-commit coding-guardrail threshold.',
+  ],
+  [
+    'delivery.quality.autoRefresh',
+    'Auto-refresh policy for ratcheted baselines.',
+  ],
+  [
+    'delivery.quality.baselineEpsilon',
+    'Tolerance epsilon applied when comparing a quality baseline.',
+  ],
+  ['delivery.quality', 'Delivery-time quality configuration.'],
+  ['delivery.signals', 'Threshold for a delivery friction/telemetry signal.'],
+  ['delivery.lifecycle.timeouts', 'Timeout for a lifecycle-bus phase.'],
+  ['delivery.lifecycle', 'Lifecycle-bus configuration.'],
+  [
+    'planning.taskSizing',
+    'Story-sizing threshold for the decompose validator.',
+  ],
+  ['qa.signInSeam', 'QA harness sign-in seam configuration.'],
+  ['qa.personas', 'QA harness persona / credential mapping.'],
+]);
+
+/**
+ * Block-level fallback glosses by top-level prefix. Guarantees every key gets
+ * a non-empty meaning even if neither the exact map nor a prefix gloss matches.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const BLOCK_MEANINGS = Object.freeze({
+  project: 'Project identity, paths, and command configuration.',
+  github: 'GitHub provider identity and merge/notification policy.',
+  planning: 'Inputs and guardrails for /epic-plan.',
+  delivery:
+    'Execution, isolation, quality, and lifecycle settings for delivery.',
+  qa: 'Agent-driven QA harness contract.',
+});
+
+/**
+ * Is `dottedPath` a secret-bearing key whose value must be redacted?
+ *
+ * @param {string} dottedPath
+ * @returns {boolean}
+ */
+export function isSecretKey(dottedPath) {
+  return dottedPath
+    .split('.')
+    .some((segment) =>
+      SECRET_SEGMENT_PATTERNS.some((pattern) => pattern.test(segment)),
+    );
+}
+
+/**
+ * Resolve the one-line meaning for a dotted config key.
+ *
+ * @param {string} dottedPath
+ * @returns {string}
+ */
+export function meaningFor(dottedPath) {
+  if (Object.hasOwn(KEY_MEANINGS, dottedPath)) {
+    return KEY_MEANINGS[dottedPath];
+  }
+  // Longest matching prefix wins.
+  let best = null;
+  for (const [prefix, gloss] of PREFIX_MEANINGS) {
+    if (
+      (dottedPath === prefix || dottedPath.startsWith(`${prefix}.`)) &&
+      (best === null || prefix.length > best[0].length)
+    ) {
+      best = [prefix, gloss];
+    }
+  }
+  if (best) return best[1];
+
+  const block = dottedPath.split('.')[0];
+  return BLOCK_MEANINGS[block] ?? 'Configuration key.';
+}
+
+/**
+ * Attribute a key's effective value to a source layer and capture the value
+ * the resolver actually applies.
+ *
+ * @param {string} dottedPath
+ * @param {object|null} rawAgentrc  The resolver's `raw` (merged agentrc+local), or null.
+ * @param {unknown} defaultValue    The framework default for this key.
+ * @returns {{ source: 'agentrc'|'default', value: unknown }}
+ */
+function attribute(dottedPath, rawAgentrc, defaultValue) {
+  const inAgentrc = lookupPath(rawAgentrc, dottedPath);
+  if (inAgentrc.present) {
+    return { source: 'agentrc', value: inAgentrc.value };
+  }
+  return { source: 'default', value: defaultValue };
+}
+
+/**
+ * Build the config-explain report: one entry per known config key, each
+ * carrying its effective value, source layer, and one-line meaning.
+ *
+ * @param {{ cwd?: string }} [opts]
+ *   - `cwd`: project root whose `.agentrc.json` is resolved (default: the
+ *     framework root via `resolveConfig`).
+ * @returns {Array<{
+ *   key: string,
+ *   value: unknown,
+ *   source: 'agentrc'|'default',
+ *   meaning: string,
+ *   redacted: boolean,
+ * }>}
+ */
+export function explainConfig(opts = {}) {
+  const { cwd } = opts;
+
+  const resolved = resolveConfig(cwd ? { cwd } : undefined);
+  const rawAgentrc = resolved.raw ?? null;
+  const defaults = getAgentrcDefaults();
+
+  const report = [];
+  for (const [key, defaultValue] of iterDefaultLeaves(defaults)) {
+    const { source, value } = attribute(key, rawAgentrc, defaultValue);
+    const redacted = isSecretKey(key);
+    report.push({
+      key,
+      value: redacted ? null : value,
+      source,
+      meaning: meaningFor(key),
+      redacted,
+    });
+  }
+  return report;
+}

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

@@ -0,0 +1,23 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code) */
+
+import { GATE_BASE } from './shared.js';
+
+const BUNDLE_DECLARATION = {
+  type: 'object',
+  required: ['name', 'path', 'limit'],
+  properties: {
+    name: { type: 'string', minLength: 1 },
+    path: { type: 'string', minLength: 1 },
+    limit: { type: 'string', minLength: 1 },
+  },
+  additionalProperties: false,
+};
+
+export const BUNDLE_SIZE_GATE = {
+  type: 'object',
+  properties: {
+    ...GATE_BASE,
+    bundles: { type: 'array', items: BUNDLE_DECLARATION },
+  },
+  additionalProperties: false,
+};

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

@@ -0,0 +1,18 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code) */
+
+import { GATE_BASE, SAFE_STRING } from './shared.js';
+
+export const COVERAGE_GATE = {
+  type: 'object',
+  properties: {
+    ...GATE_BASE,
+    coveragePath: { ...SAFE_STRING, minLength: 1 },
+    // 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 },
+  },
+  additionalProperties: false,
+};

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

@@ -0,0 +1,33 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code) */
+
+import {
+  GATE_BASE,
+  LIST_OR_EXTENDER_OF_STRINGS,
+  SAFE_STRING,
+} from './shared.js';
+
+export const CRAP_GATE = {
+  type: 'object',
+  properties: {
+    ...GATE_BASE,
+    targetDirs: LIST_OR_EXTENDER_OF_STRINGS,
+    newMethodCeiling: { type: 'integer', minimum: 1 },
+    requireCoverage: { type: 'boolean' },
+    friction: {
+      type: 'object',
+      properties: { markerKey: { type: 'string', minLength: 1 } },
+      additionalProperties: false,
+    },
+    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 } },
+  },
+  additionalProperties: false,
+};

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

@@ -0,0 +1,26 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code) */
+
+import { GATE_BASE, 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',
+  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 } },
+  },
+  additionalProperties: false,
+};

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

@@ -0,0 +1,36 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code); thin aggregator over per-gate sub-schemas */
+
+import { BUNDLE_SIZE_GATE } from './bundle-size.schema.js';
+import { COVERAGE_GATE } from './coverage.schema.js';
+import { CRAP_GATE } from './crap.schema.js';
+import { DUPLICATION_GATE } from './duplication.schema.js';
+import { LIGHTHOUSE_GATE } from './lighthouse.schema.js';
+import { LINT_GATE } from './lint.schema.js';
+import { MAINTAINABILITY_GATE } from './maintainability.schema.js';
+import { MUTATION_GATE } from './mutation.schema.js';
+
+/**
+ * Composite `delivery.quality.gates` schema — closed shape.
+ *
+ * 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`,
+ * `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`.
+ */
+export const GATES_SCHEMA = {
+  type: 'object',
+  properties: {
+    lint: LINT_GATE,
+    coverage: COVERAGE_GATE,
+    crap: CRAP_GATE,
+    maintainability: MAINTAINABILITY_GATE,
+    mutation: MUTATION_GATE,
+    lighthouse: LIGHTHOUSE_GATE,
+    'bundle-size': BUNDLE_SIZE_GATE,
+    duplication: DUPLICATION_GATE,
+  },
+  additionalProperties: false,
+};