mandrel 2.30.0 → 2.32.0

package/.agents/docs/configuration.md

@@ -7,17 +7,33 @@ against AJV schemas at runtime, and consumed through grouped accessors
 (`getCommands()`, `getQuality()`, `getPaths()`, etc.).
 
 This document is the reader-facing reference for the post-Epic-#1720 grouped
-shape. The authoritative contract is the JSON Schema mirror at
-[`.agents/schemas/agentrc.schema.json`](../schemas/agentrc.schema.json),
-which is itself a mirror of the AJV schemas under
-[`.agents/scripts/lib/`](../scripts/lib/). A drift test
-(`tests/config-schema-mirror-drift.test.js`) keeps the static mirror aligned
-with the runtime validators.
+shape. The authoritative contract is the runtime AJV schema under
+[`.agents/scripts/lib/`](../scripts/lib/) — `config-settings-schema.js` plus
+its `-delivery` / `-quality` / `config/gates/*` modules. Since Story #5007
+that schema is the **single annotated source** for the whole surface: the
+shipped JSON-Schema mirror at
+[`.agents/schemas/agentrc.schema.json`](../schemas/agentrc.schema.json), the
+defaults inventory at
+[`.agents/docs/agentrc-reference.json`](agentrc-reference.json), and the key
+table below are all emitted from it by
+[`generate-config-docs.js`](../scripts/generate-config-docs.js), and
+`npm run docs:check` (hence `npm run lint`) fails closed on drift. Nothing is
+hand-mirrored, so a key cannot exist in one artifact and not another.
 
 > **Editor support.** `.agentrc.json`, `.agents/starter-agentrc.json`, and
 > `.agents/docs/agentrc-reference.json` all declare
 > `"$schema": "./.agents/schemas/agentrc.schema.json"`, so any editor with
 > JSON Schema support gets autocomplete and inline validation.
+>
+> **Upgrading — the shipped mirror no longer has a `$defs` block.** Story
+> #5007 replaced the hand-kept mirror with a serialization of the runtime
+> schema, which inlines every sub-schema at its point of use. Validation is
+> unchanged (2020-12, same keywords, same accept/reject set on every
+> document) and every key survives, but the named definitions and the
+> `#/$defs/<name>` pointers into them are gone. A `$ref` from your own schema
+> into one of them — e.g.
+> `.agents/schemas/agentrc.schema.json#/$defs/crapGate` — no longer resolves;
+> inline the shape you needed, or point at the containing property path.
 
 ## Top-level shape
 
@@ -27,7 +43,8 @@ with the runtime validators.
   "project":  { /* paths, commands, baseBranch, docsContextFiles */ },
   "github":   { /* owner, repo, branchProtection, mergeMethods, notifications */ },
   "planning": { /* riskHeuristics, conflict gates, complexityGate, navigation */ },
-  "delivery": { /* execution, quality, worktreeIsolation, deliverRunner, ... */ }
+  "delivery": { /* execution, quality, worktreeIsolation, deliverRunner, ... */ },
+  "qa":       { /* featureRoot, fixturesManifest, environments, personas */ }
 }
 ```
 
@@ -40,265 +57,290 @@ top-level keys are validation errors.
 | `github`      | No       | Ticketing provider config: owner/repo, branch protection, merge methods, notifications. |
 | `planning`    | No       | `/plan` tuning: conflict advisories, complexity routing, navigability gate. (Story sizing ceilings and the planner-context cap are code-absolute — not agentrc.) |
 | `delivery`    | No       | `/deliver` tuning: quality gates, worktree isolation, runners, CI watch, code-review providers. |
+| `qa`          | No       | Agent-driven QA harness contract: feature root, fixtures, environments, personas. |
 | `$schema`     | No       | JSON Schema pointer for editor tooling.                                            |
 
 ---
 
 <!-- BEGIN GENERATED:agentrc -->
 
-> Generated by `node .agents/scripts/generate-config-docs.js` from
-> [`.agents/schemas/agentrc.schema.json`](../schemas/agentrc.schema.json).
-> Edit the schema (and its AJV mirror under `.agents/scripts/lib/`),
-> then re-run the generator — do not hand-edit this region.
+> Generated by `node .agents/scripts/generate-config-docs.js` from the
+> runtime AJV schema in
+> [`.agents/scripts/lib/config-settings-schema.js`](../scripts/lib/config-settings-schema.js).
+> Edit the `description` / `default` annotations on those schema literals
+> and re-run `npm run docs:gen` — do not hand-edit this region, and do not
+> hand-edit `agentrc.schema.json` or `agentrc-reference.json` either: both
+> are emitted by the same generator.
 
 ### `project` (required)
 
+Project identity, filesystem roots, planner docs context, and the commands the close-validation chain spawns.
+
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `baseBranch` | No | `string` | — | — |
-| `paths` | Yes | `object` | — | Nested configuration block. |
-| `paths.agentRoot` | Yes | `string` | — | — |
-| `paths.docsRoot` | Yes | `string` | — | — |
-| `paths.tempRoot` | Yes | `string` | — | — |
-| `docsContextFiles` | No | `array<string>` | — | — |
-| `commands` | No | `object` | — | Nested configuration block. |
-| `commands.lintBaseline` | No | `string` | — | — |
-| `commands.test` | No | `string` | — | — |
-| `commands.typecheck` | No | `string` \| `null` | — | — |
-| `commands.formatCheck` | No | `string` | — | — |
-| `commands.formatWrite` | No | `string` | — | — |
+| `baseBranch` | No | `string` | `"main"` | Branch every `story-<id>` branch is seeded from and every Story PR targets. |
+| `paths` | Yes | `object` | — | The three required filesystem roots. Every `${dir}Root` the framework needs is derived at runtime as `${agentRoot}/<dir>`, and the audit output dir as `${tempRoot}/audits`. |
+| `paths.agentRoot` | Yes | `string` | `".agents"` | Repo-relative root of the materialized framework tree (`mandrel sync` writes here). |
+| `paths.docsRoot` | Yes | `string` | `"docs"` | Repo-relative root of the project documentation the planner reads for context. |
+| `paths.tempRoot` | Yes | `string` | `"temp"` | Repo-relative gitignored scratch root. Every temporary artifact — gate transcripts, audit reports, plan authoring dirs — lands under it. |
+| `docsContextFiles` | No | `array<string>` | `["architecture.md","data-dictionary.md","decisions.md","patterns.md"]` | Files under `paths.docsRoot` the planner treats as standing context. Read digest-first — the docs digest names the file and the line range, and only the named section is pulled. |
+| `commands` | No | `object` | — | Shell commands the close-validation chain spawns. Each is run from the repo root. |
+| `commands.test` | No | `string` | `"npm test"` | Full test-suite command run by the close-validation chain. |
+| `commands.typecheck` | No | `string` \| `null` | `null` | Static type-check command. `null` disables the gate for projects with no type layer; the empty string is rejected so a typo cannot silently disable it. |
+| `commands.formatCheck` | No | `string` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. |
+| `commands.formatWrite` | No | `string` | `"npx biome format --write ."` | Mutating format command the close-time format-autofix step spawns. |
 
 ### `github` (optional)
 
+GitHub provider identity plus the remote stance the bootstrap enforces. `owner`, `repo`, and `operatorHandle` are operator identity — the shipped values are placeholders, not usable defaults.
+
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `owner` | Yes | `string` | — | — |
-| `repo` | Yes | `string` | — | — |
-| `projectNumber` | No | `integer` \| `null` | — | — |
-| `projectOwner` | No | `string` \| `null` | — | — |
-| `operatorHandle` | Yes | `string` | — | — |
-| `defaultTimeoutMs` | No | `integer` | — | Default `timeoutMs` (in milliseconds) applied to every `gh` subprocess spawned by the GitHub provider facade. Caps any single `gh api` / `gh issue ...` / `gh pr ...` invocation so a stalled TCP socket or long-poll cannot hang an orchestration indefinitely. A `GhExecTimeoutError` from a hit ceiling is classified `transient` and retried by `withTransientRetry`. Recommended floor 1000ms; recommended default 60000 (60s). Omit to use the in-code default of 60000. Story #2860. |
-| `branchProtection` | No | `object` | — | Nested configuration block. |
-| `branchProtection.enforce` | No | `boolean` | — | — |
-| `branchProtection.requiredChecks[]` | No | `array<branchProtectionCheck>` | — | Each item (`branchProtectionCheck`) has: name, cmd. |
-| `mergeMethods` | No | `object` | — | Nested configuration block. |
-| `mergeMethods.allow_squash_merge` | No | `boolean` | — | — |
-| `mergeMethods.allow_rebase_merge` | No | `boolean` | — | — |
-| `mergeMethods.allow_merge_commit` | No | `boolean` | — | — |
-| `mergeMethods.allow_auto_merge` | No | `boolean` | — | — |
-| `mergeMethods.delete_branch_on_merge` | No | `boolean` | — | — |
-| `notifications` | No | `object` | — | Nested configuration block. |
-| `notifications.mentionOperator` | No | `boolean` | — | — |
-| `notifications.commentEvents` | No | `array<enum>` | — | — |
-| `notifications.webhookEvents` | No | `array<enum>` | — | — |
+| `owner` | Yes | `string` | `"[OWNER]"` | GitHub owner (user or org) that hosts the repository. |
+| `repo` | Yes | `string` | `"[REPO]"` | Repository name under `owner`. |
+| `projectNumber` | No | `integer` \| `null` | `null` | Projects V2 board number the orchestrator syncs Story status onto. `null` disables board sync. |
+| `projectOwner` | No | `string` \| `null` | `null` | Owner of the Projects V2 board when it lives outside `owner` (an org board fed by a user repo). `null` means the board shares `owner`. |
+| `operatorHandle` | Yes | `string` | `"@[USERNAME]"` | The human the framework escalates to, `@`-prefixed. Used for HITL @-mentions on `agent::blocked`. |
+| `defaultTimeoutMs` | No | `integer` | `60000` | Default `timeoutMs` applied to every `gh` subprocess the provider facade spawns, so a stalled socket or long-poll cannot hang an orchestration indefinitely. A `GhExecTimeoutError` from a hit ceiling is classified `transient` and retried by `withTransientRetry`. Story #2860. |
+| `branchProtection` | No | `object` | — | Branch-protection stance applied to `project.baseBranch` by the GitHub bootstrap, and reproduced locally before every push. |
+| `branchProtection.enforce` | No | `boolean` | `true` | When true, the GitHub bootstrap writes the required-check ruleset. False leaves the remote stance alone. |
+| `branchProtection.requiredChecks[]` | No | `array<object>` | `[{"name":"lint","cmd":["npm","run","lint"]},{"name":"test","cmd":["npm","test"]},{"name":"baselines","cmd":["node",".agents/scripts/check-baselines.js"]}]` | Checks that must pass before a Story PR merges. Each entry carries both the remote context name and the local argv. Each item has: name, cmd. |
+| `mergeMethods` | No | `object` | — | Repository merge-method stance the GitHub bootstrap enforces. The framework ships squash-only with auto-merge on, which is what the one-PR-per-Story model needs for release-please to parse each landed subject. |
+| `mergeMethods.allow_squash_merge` | No | `boolean` | `true` | — |
+| `mergeMethods.allow_rebase_merge` | No | `boolean` | `false` | — |
+| `mergeMethods.allow_merge_commit` | No | `boolean` | `false` | — |
+| `mergeMethods.allow_auto_merge` | No | `boolean` | `true` | — |
+| `mergeMethods.delete_branch_on_merge` | No | `boolean` | `true` | — |
+| `notifications` | No | `object` | — | Allowlist-gated notification channels. An event fires on a channel only when it is named in that channel's array. |
+| `notifications.mentionOperator` | No | `boolean` | `false` | When true, `github.operatorHandle` is @-mentioned in the comments the notifier posts. |
+| `notifications.commentEvents` | No | `array<enum>` | `["state-transition","story-merged","operator-message"]` | Events mirrored onto the Story issue as a comment. Deliberately narrower than `webhookEvents`: only Story-scoped events whose message reads as narrative an operator wants durably on the ticket belong here. |
+| `notifications.webhookEvents` | No | `array<enum>` | `["state-transition","story-merged","story-closing","operator-message","merge.unlanded","merge.flip-failed"]` | Events dispatched to the configured webhook. The vocabulary is the allowlist the webhook channel gates on; `merge.unlanded` and `merge.flip-failed` are allowlistable but reach the run ledger rather than `notify()` today. |
 
 ### `planning` (optional)
 
+Inputs to `/plan`: risk escalation heuristics, ceremony-lite routing, and the cross-Story conflict-finding severity gates.
+
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `riskHeuristics` | No | `string[]` or `{ append?, prepend? }` | — | — |
+| `riskHeuristics` | No | `string[]` or `{ append?, prepend? }` | `["Destructive or irreversible data mutations (dropping tables, deleting rows without soft-delete or backup, truncating production state).","Modifications to shared security or auth infrastructure (IAM policies, auth middleware, session or token handling, secret rotation).","Changes to CI/CD, deployment pipelines, or release gating that could disable safety checks or ship unverified code to production.","Monorepo-wide AST or text replacements touching overlapping files in parallel (catastrophic merge-conflict risk across concurrent agents).","Schema migrations that rewrite existing rows or drop columns without a backfill or rollback plan."]` | Prose heuristics the planner escalates a Story against. A plain array replaces the framework list; the `{ append, prepend }` extender form deep-merges with it. |
 | `complexityGate` | No | `object` | — | Shape-derived ceremony-lite complexity routing. A lite claim is validated against the authored Story shape at persist and re-derived from the Story body at dispatch; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables. |
 | `complexityGate.enabled` | No | `boolean` | — | Master switch. When false, lite routing is disabled everywhere: persist refuses lite claims and dispatch always takes the sub-agent path. Default true. |
 | `complexityGate.maxArtifacts` | No | `integer` | — | Enumerated-artifact threshold reported by the plan-context complexity signals. An input signal for the planner verdict — carries no routing authority. Default 1. |
-| `failOnSharedEditors` | No | `boolean` | — | When true, upgrade shared-editor conflict findings to hard errors (default false — advisory soft findings only). |
-| `requireExplicitCrossStoryDeps` | No | `boolean` | — | When true, upgrade implicit cross-Story dependency findings to hard errors (default false — advisory soft findings only). |
-| `failOnRegistryConflicts` | No | `boolean` | — | When true, upgrade cross-cutting registry conflict findings to hard errors (default false). |
-| `failOnLargeFanOut` | No | `boolean` | — | When true, upgrade fan-out-warning findings (delete blast radius) to hard errors (default false — soft advisory). |
-| `largeFanOutThreshold` | No | `integer` | — | Call-site count above which a Story that deletes a module emits a fan-out-warning. Counts base-branch references to the deleted path basename. Soft by default; does not size or reject Stories. Default 10. |
-| `crossCuttingRegistries` | No | `string[]` or `{ append?, prepend? }` | — | Registry path patterns whose concurrent edits across Stories are flagged as conflicts. Defaults to the framework listener/handler index patterns when omitted. |
+| `failOnSharedEditors` | No | `boolean` | `false` | When true, upgrade shared-editor conflict findings to hard errors (default false — advisory soft findings only). |
+| `requireExplicitCrossStoryDeps` | No | `boolean` | `false` | When true, upgrade implicit cross-Story dependency findings to hard errors (default false — advisory soft findings only). |
+| `crossCuttingRegistries` | No | `string[]` or `{ append?, prepend? }` | `["lib/orchestration/lifecycle/listeners/index.js","**/listeners/index.js","**/handlers/index.js"]` | Registry path patterns whose concurrent edits across Stories are flagged as conflicts. Defaults to the framework listener/handler index patterns when omitted. |
+| `failOnRegistryConflicts` | No | `boolean` | `false` | When true, upgrade cross-cutting registry conflict findings to hard errors (default false). |
+| `failOnLargeFanOut` | No | `boolean` | `false` | When true, upgrade fan-out-warning findings (delete blast radius) to hard errors (default false — soft advisory). |
+| `largeFanOutThreshold` | No | `integer` | `10` | Call-site count above which a Story that deletes a module emits a fan-out-warning. Counts base-branch references to the deleted path basename. Soft by default; does not size or reject Stories. Default 10. |
 | `navigation` | No | `object` | — | Opt-in navigability reachability gate. Absent or empty routeGlobs is a silent no-op. |
-| `navigation.routeGlobs` | No | `array<string>` | — | Glob patterns (e.g. pages/**, app/**/route.ts) marking paths that add a user-facing route. |
-| `navigation.navRegistry` | No | `array<string>` | — | Tokens identifying the nav-registry SSOT a route-adding Story is expected to reference. |
+| `navigation.routeGlobs` | No | `array<string>` | `[]` | Glob patterns (e.g. pages/**, app/**/route.ts) marking paths that add a user-facing route. |
+| `navigation.navRegistry` | No | `array<string>` | `[]` | Tokens identifying the nav-registry SSOT a route-adding Story is expected to reference. |
 
 ### `delivery` (optional)
 
+Everything `/deliver` and `single-story-close` consume: execution timeouts, worktree isolation, runner concurrency, docs freshness, signals, quality gates, merge/CI watch, review ceremony, and the feedback loop.
+
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `execution` | No | `object` | — | Nested configuration block. |
-| `execution.timeoutMs` | No | `integer` | — | — |
-| `lease` | No | `object` | — | Story #3480 (Epic #3457). Assignee-as-lease primitive. ttlMs is the staleness window — a ticket claim whose owner's last heartbeat is older than this many milliseconds is reclaimable by another operator. Defaults to 900000 (15 min) in lib/config/limits.js. Note the shipped guards fail closed (there is no live heartbeat source), so a stranded claim is cleared with --steal rather than by TTL expiry. |
-| `lease.ttlMs` | No | `integer` | — | — |
-| `docsFreshness` | No | `object` | — | Nested configuration block. |
-| `docsFreshness.paths` | No | `array` | — | — |
+| `execution` | No | `object` | — | Wall-clock bounds on the subprocesses delivery spawns. |
+| `execution.timeoutMs` | No | `integer` | `600000` | Per-command timeout (ms) for the long-running spawns delivery drives — the close-validation chain and the gate CLIs. |
+| `docsFreshness` | No | `object` | — | Documentation-freshness scope: the files a change of consequence is expected to touch. Read by the audit-documentation lens to seed its target set; no delivery gate enforces it. |
+| `docsFreshness.paths` | No | `array<string>` | `["README.md"]` | Repo-relative documentation paths the audit-documentation lens adds to its target set. |
 | `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so operator scratch files under tempRoot are reported with their size and left alone. signals.ndjson is never purged by any path. |
-| `tempRetention.enabled` | No | `boolean` | — | Master switch. Default true — reclaiming a landed Story's gate transcripts and validation evidence is the behaviour, and this knob turns it off. When false every purge path is a reported no-op. |
-| `tempRetention.staleDays` | No | `integer` | — | Age floor (days, default 7) for the families no Story id can be recovered from — roster-level audit reports and abandoned plan-<slug>/ dirs. Story-keyed artifacts do not wait for it: they are purged as soon as their merge is confirmed. |
+| `tempRetention.enabled` | No | `boolean` | `true` | Master switch. Default true — reclaiming a landed Story's gate transcripts and validation evidence is the behaviour, and this knob turns it off. When false every purge path is a reported no-op. |
+| `tempRetention.staleDays` | No | `integer` | `7` | Age floor (days, default 7) for the families no Story id can be recovered from — roster-level audit reports and abandoned plan-<slug>/ dirs. Story-keyed artifacts do not wait for it: they are purged as soon as their merge is confirmed. |
 | `tempRetention.classes` | No | `object` | — | Per-class opt-out. Each defaults to true; set one false to keep that family while the rest are purged. |
-| `tempRetention.classes.orchestrationLogs` | No | `boolean` | — | <tempRoot>/orchestration/*.log — close gate transcripts and terse-result detail dumps. |
-| `tempRetention.classes.validationEvidence` | No | `boolean` | — | Per-Story validation-evidence.json, lifecycle.ndjson, and manifest.md under the standalone and per-run story trees. |
-| `tempRetention.classes.auditResults` | No | `boolean` | — | <tempRoot>/audits/ — audit lens reports. |
-| `tempRetention.classes.planDirs` | No | `boolean` | — | <tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. Age-floored only; the current run is always excluded. |
-| `deliverRunner` | No | `object` | — | Nested configuration block. |
-| `deliverRunner.concurrencyCap` | No | `integer` | — | Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff. |
-| `worktreeIsolation` | No | `object` | — | Nested configuration block. |
-| `worktreeIsolation.enabled` | No | `boolean` | — | — |
-| `worktreeIsolation.root` | No | `string` | — | — |
-| `worktreeIsolation.nodeModulesStrategy` | No | `"per-worktree"` \| `"clone"` \| `"symlink"` \| `"pnpm-store"` | — | — |
-| `worktreeIsolation.primeFromPath` | No | `string` \| `null` | — | — |
-| `worktreeIsolation.allowSymlinkOnWindows` | No | `boolean` | — | — |
-| `worktreeIsolation.reapOnSuccess` | No | `boolean` | — | — |
-| `worktreeIsolation.bootstrapFiles` | No | `array<string>` | `[".env",".mcp.json",".agentrc.local.json",".agents/instructions.local.md"]` | — |
-| `signals` | No | `object` | — | Nested configuration block. |
-| `signals.rework` | No | `object` | — | Nested configuration block. |
-| `signals.rework.editsPerFile` | No | `integer` | — | — |
-| `signals.retry` | No | `object` | — | Nested configuration block. |
-| `signals.retry.repeatCount` | No | `integer` | — | — |
-| `quality` | No | `object` | — | Nested configuration block. |
-| `quality.gateScoping` | No | `object` | — | Nested configuration block. |
-| `quality.gateScoping.scope` | No | `"diff"` \| `"full"` | — | — |
-| `quality.gateScoping.diffRef` | No | `string` | — | — |
-| `quality.gates` | No | `object` | — | Nested configuration block. |
-| `quality.gates.lint` | No | `object` | — | Nested configuration block. |
-| `quality.gates.lint.enabled` | No | `boolean` | — | — |
-| `quality.gates.lint.baselinePath` | No | `string` | — | — |
-| `quality.gates.lint.tolerance` | No | `object` | — | Nested configuration block. |
-| `quality.gates.lint.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | — |
-| `quality.gates.lint.tolerance.value` | Yes | `number` | — | — |
-| `quality.gates.lint.floors` | No | `object<map>` | — | — |
-| `quality.gates.lint.components` | No | `object<map>` | — | — |
-| `quality.gates.coverage` | No | `object` | — | Nested configuration block. |
-| `quality.gates.coverage.enabled` | No | `boolean` | — | — |
-| `quality.gates.coverage.baselinePath` | No | `string` | — | — |
-| `quality.gates.coverage.tolerance` | No | `object` | — | Nested configuration block. |
-| `quality.gates.coverage.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | — |
-| `quality.gates.coverage.tolerance.value` | Yes | `number` | — | — |
-| `quality.gates.coverage.floors` | No | `object<map>` | — | — |
-| `quality.gates.coverage.components` | No | `object<map>` | — | — |
-| `quality.gates.coverage.coveragePath` | No | `string` | — | — |
-| `quality.gates.coverage.timeoutMs` | No | `integer` | — | — |
-| `quality.gates.crap` | No | `object` | — | Nested configuration block. |
-| `quality.gates.crap.enabled` | No | `boolean` | — | — |
-| `quality.gates.crap.baselinePath` | No | `string` | — | — |
-| `quality.gates.crap.tolerance` | No | `object` | — | Nested configuration block. |
-| `quality.gates.crap.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | — |
-| `quality.gates.crap.tolerance.value` | Yes | `number` | — | — |
-| `quality.gates.crap.floors` | No | `object<map>` | — | — |
-| `quality.gates.crap.components` | No | `object<map>` | — | — |
-| `quality.gates.crap.targetDirs` | No | `string[]` or `{ append?, prepend? }` | — | 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. |
-| `quality.gates.crap.newMethodCeiling` | No | `integer` | — | — |
-| `quality.gates.crap.requireCoverage` | No | `boolean` | — | — |
-| `quality.gates.crap.minMethodResolutionRate` | No | `number` | — | 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%. |
-| `quality.gates.crap.friction` | No | `object` | — | Nested configuration block. |
-| `quality.gates.crap.friction.markerKey` | No | `string` | — | — |
-| `quality.gates.crap.refreshTag` | No | `string` | — | — |
-| `quality.gates.crap.refreshTimeoutMs` | No | `integer` | — | 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). |
-| `quality.gates.crap.ignoreGlobs` | No | `array<string>` | — | 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). |
-| `quality.gates.crap.incrementalCoverage` | No | `object` | — | 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. |
-| `quality.gates.crap.incrementalCoverage.enabled` | No | `boolean` | — | — |
-| `quality.gates.crap.incrementalCoverage.baseRef` | No | `string` | — | — |
-| `quality.gates.maintainability` | No | `object` | — | Nested configuration block. |
-| `quality.gates.maintainability.enabled` | No | `boolean` | — | — |
-| `quality.gates.maintainability.baselinePath` | No | `string` | — | — |
-| `quality.gates.maintainability.tolerance` | No | `object` | — | Nested configuration block. |
-| `quality.gates.maintainability.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | — |
-| `quality.gates.maintainability.tolerance.value` | Yes | `number` | — | — |
-| `quality.gates.maintainability.floors` | No | `object<map>` | — | — |
-| `quality.gates.maintainability.components` | No | `object<map>` | — | — |
-| `quality.gates.maintainability.targetDirs` | No | `string[]` or `{ append?, prepend? }` | — | 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. |
-| `quality.gates.maintainability.refreshTag` | No | `string` | — | — |
-| `quality.gates.maintainability.refreshTimeoutMs` | No | `integer` | — | 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). |
-| `quality.gates.maintainability.ignoreGlobs` | No | `array<string>` | — | 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). |
-| `quality.gates.mutation` | No | `object` | — | Nested configuration block. |
-| `quality.gates.mutation.enabled` | No | `boolean` | — | — |
-| `quality.gates.mutation.baselinePath` | No | `string` | — | — |
-| `quality.gates.mutation.tolerance` | No | `object` | — | Nested configuration block. |
-| `quality.gates.mutation.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | — |
-| `quality.gates.mutation.tolerance.value` | Yes | `number` | — | — |
-| `quality.gates.mutation.floors` | No | `object<map>` | — | — |
-| `quality.gates.mutation.components` | No | `object<map>` | — | — |
-| `quality.gates.mutation.strykerConfigPath` | No | `string` \| `null` | — | — |
-| `quality.gates.lighthouse` | No | `object` | — | Nested configuration block. |
-| `quality.gates.lighthouse.enabled` | No | `boolean` | — | — |
-| `quality.gates.lighthouse.baselinePath` | No | `string` | — | — |
-| `quality.gates.lighthouse.tolerance` | No | `object` | — | Nested configuration block. |
-| `quality.gates.lighthouse.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | — |
-| `quality.gates.lighthouse.tolerance.value` | Yes | `number` | — | — |
-| `quality.gates.lighthouse.floors` | No | `object<map>` | — | — |
-| `quality.gates.lighthouse.components` | No | `object<map>` | — | — |
-| `quality.gates.lighthouse.baseUrl` | No | `string` \| `null` | — | — |
-| `quality.gates.lighthouse.routes[]` | No | `array<lighthouseRoute>` | — | Each item (`lighthouseRoute`) has: path, formFactor. |
-| `quality.gates.bundle-size` | No | `object` | — | Nested configuration block. |
-| `quality.gates.bundle-size.enabled` | No | `boolean` | — | — |
-| `quality.gates.bundle-size.baselinePath` | No | `string` | — | — |
-| `quality.gates.bundle-size.tolerance` | No | `object` | — | Nested configuration block. |
-| `quality.gates.bundle-size.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | — |
-| `quality.gates.bundle-size.tolerance.value` | Yes | `number` | — | — |
-| `quality.gates.bundle-size.floors` | No | `object<map>` | — | — |
-| `quality.gates.bundle-size.components` | No | `object<map>` | — | — |
-| `quality.gates.bundle-size.bundles[]` | No | `array<bundleDeclaration>` | — | Each item (`bundleDeclaration`) has: name, path, limit. |
-| `quality.gates.duplication` | No | `object` | — | Nested configuration block. |
-| `quality.gates.duplication.enabled` | No | `boolean` | — | — |
-| `quality.gates.duplication.baselinePath` | No | `string` | — | — |
-| `quality.gates.duplication.tolerance` | No | `object` | — | Nested configuration block. |
-| `quality.gates.duplication.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | — |
-| `quality.gates.duplication.tolerance.value` | Yes | `number` | — | — |
-| `quality.gates.duplication.floors` | No | `object<map>` | — | — |
-| `quality.gates.duplication.components` | No | `object<map>` | — | — |
-| `quality.gates.duplication.targetDirs` | No | `string[]` or `{ append?, prepend? }` | — | 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). |
-| `quality.gates.duplication.refreshTimeoutMs` | No | `integer` | — | 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). |
-| `quality.gates.duplication.ignoreGlobs` | No | `array<string>` | — | 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). |
+| `tempRetention.classes.orchestrationLogs` | No | `boolean` | `true` | <tempRoot>/orchestration/*.log — close gate transcripts and terse-result detail dumps. |
+| `tempRetention.classes.validationEvidence` | No | `boolean` | `true` | Per-Story validation-evidence.json, lifecycle.ndjson, and manifest.md under the standalone and per-run story trees. |
+| `tempRetention.classes.auditResults` | No | `boolean` | `true` | <tempRoot>/audits/ — audit lens reports. |
+| `tempRetention.classes.planDirs` | No | `boolean` | `true` | <tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. Age-floored only; the current run is always excluded. |
+| `deliverRunner` | No | `object` | — | Bounded-concurrency knob for the /deliver fan-out. |
+| `deliverRunner.concurrencyCap` | No | `integer` | `3` | Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff. |
+| `worktreeIsolation` | No | `object` | — | Per-Story git worktree provisioning. Each Story is implemented in its own checkout so concurrent siblings never share a working tree. |
+| `worktreeIsolation.enabled` | No | `boolean` | `true` | When true, `single-story-init.js` materializes a worktree per Story. False implements every Story in the main checkout, which is only safe for strictly serial delivery. |
+| `worktreeIsolation.root` | No | `string` | `".worktrees"` | Repo-relative directory the per-Story worktrees are created under. Required whenever `enabled` is explicitly true. |
+| `worktreeIsolation.nodeModulesStrategy` | No | `"per-worktree"` \| `"clone"` \| `"symlink"` \| `"pnpm-store"` | `"clone"` | How each worktree gets its dependencies. `clone` copy-on-writes the main checkout tree (fast, cross-platform); `per-worktree` runs a full install; `symlink` links the shared tree (POSIX only unless `allowSymlinkOnWindows`); `pnpm-store` re-links from the pnpm content store. |
+| `worktreeIsolation.primeFromPath` | No | `string` \| `null` | `null` | Absolute path to an existing `node_modules` tree to prime new worktrees from, instead of the main checkout. `null` uses the main checkout. |
+| `worktreeIsolation.allowSymlinkOnWindows` | No | `boolean` | `false` | Permit the `symlink` strategy on win32, where it needs Developer Mode or elevation. Off by default so a Windows consumer fails over to a strategy that works. |
+| `worktreeIsolation.reapOnSuccess` | No | `boolean` | `true` | Remove the Story's worktree once its PR merges. False keeps it for post-mortem inspection. |
+| `worktreeIsolation.bootstrapFiles` | No | `array<string>` | `[".env",".mcp.json",".agentrc.local.json",".agents/instructions.local.md"]` | Gitignored files copied from the main checkout into every new worktree. A worktree checks out tracked files only, so local secrets and overrides would otherwise be missing. |
+| `signals` | No | `object` | — | Detector thresholds for the surviving performance-signal categories. Each block is shallow-merged by the resolver. |
+| `signals.rework` | No | `object` | — | Rework detector — repeated edits to one file in a run. |
+| `signals.rework.editsPerFile` | No | `integer` | `5` | Edits to a single file within one run that trip the rework signal. |
+| `signals.retry` | No | `object` | — | Retry detector — the same command failing repeatedly. |
+| `signals.retry.repeatCount` | No | `integer` | `3` | Repeats of an identical failing command that trip the retry signal. |
+| `quality` | No | `object` | — | Quality-gate configuration. Every gate lives under `gates.<tier>` and shares the same `{ enabled, baselinePath, tolerance, floors, components }` base; shared scoping lives at this block root. |
+| `quality.gateScoping` | No | `object` | — | Shared scope applied to every gate that supports one, unless the gate overrides it. |
+| `quality.gateScoping.scope` | No | `"diff"` \| `"full"` | `"diff"` | Score only the files changed against `diffRef` (`diff`) or every file in the gate target dirs (`full`). |
+| `quality.gateScoping.diffRef` | No | `string` | `"main"` | Git ref the `diff` scope is computed against. |
+| `quality.gates` | No | `object` | — | The eight quality gates, each sharing the `{ enabled, baselinePath, tolerance, floors, components }` base. |
+| `quality.gates.lint` | No | `object` | — | 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. |
+| `quality.gates.lint.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
+| `quality.gates.lint.baselinePath` | No | `string` | `"baselines/lint.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
+| `quality.gates.lint.tolerance` | No | `object` | `{"kind":"absolute","value":0}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
+| `quality.gates.lint.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
+| `quality.gates.lint.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
+| `quality.gates.lint.floors` | No | `object<map>` | `{"*":{"errorCount":0}}` | 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. |
+| `quality.gates.lint.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
+| `quality.gates.coverage` | No | `object` | — | Line/branch/function coverage ratchet, read from the Istanbul JSON summary the project test run emits. |
+| `quality.gates.coverage.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
+| `quality.gates.coverage.baselinePath` | No | `string` | `"baselines/coverage.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
+| `quality.gates.coverage.tolerance` | No | `object` | `{"kind":"absolute","value":0}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
+| `quality.gates.coverage.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
+| `quality.gates.coverage.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
+| `quality.gates.coverage.floors` | No | `object<map>` | `{"*":{"lines":90,"branches":85,"functions":90}}` | 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. |
+| `quality.gates.coverage.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
+| `quality.gates.coverage.coveragePath` | No | `string` | `"coverage/coverage-final.json"` | Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. |
+| `quality.gates.coverage.timeoutMs` | No | `integer` | `600000` | 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. |
+| `quality.gates.crap` | No | `object` | — | CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage. |
+| `quality.gates.crap.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
+| `quality.gates.crap.baselinePath` | No | `string` | `"baselines/crap.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
+| `quality.gates.crap.tolerance` | No | `object` | `{"kind":"absolute","value":0.05}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
+| `quality.gates.crap.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
+| `quality.gates.crap.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
+| `quality.gates.crap.floors` | No | `object<map>` | `{"*":{"max":30,"p95":20,"methodsAbove20":50}}` | 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. |
+| `quality.gates.crap.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
+| `quality.gates.crap.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `["src"]` | 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. |
+| `quality.gates.crap.newMethodCeiling` | No | `integer` | `30` | Hard CRAP ceiling applied to a method the diff introduces. A new method above it fails the gate regardless of the baseline. |
+| `quality.gates.crap.requireCoverage` | No | `boolean` | `true` | When true, the gate refuses to score without a coverage artifact rather than silently reporting complexity-only rows. |
+| `quality.gates.crap.minMethodResolutionRate` | No | `number` | — | 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%. |
+| `quality.gates.crap.friction` | No | `object` | `{"markerKey":"crap-baseline-regression"}` | Friction-signal wiring for a CRAP baseline regression, so a recurring one can reach the actionable threshold. |
+| `quality.gates.crap.friction.markerKey` | No | `string` | — | Signal marker key the regression is recorded under. |
+| `quality.gates.crap.refreshTag` | No | `string` | `"baseline-refresh:"` | 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. |
+| `quality.gates.crap.refreshTimeoutMs` | No | `integer` | `60000` | 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). |
+| `quality.gates.crap.ignoreGlobs` | No | `array<string>` | `[]` | 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). |
+| `quality.gates.crap.incrementalCoverage` | No | `object` | — | 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. |
+| `quality.gates.crap.incrementalCoverage.enabled` | No | `boolean` | — | Master switch for incremental capture + join scoping. |
+| `quality.gates.crap.incrementalCoverage.baseRef` | No | `string` | — | Git ref the changed-file set is computed against. Omitted falls back to the gate’s own `--ref` (`main`). |
+| `quality.gates.maintainability` | No | `object` | — | 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. |
+| `quality.gates.maintainability.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
+| `quality.gates.maintainability.baselinePath` | No | `string` | `"baselines/maintainability.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
+| `quality.gates.maintainability.tolerance` | No | `object` | `{"kind":"absolute","value":0.5}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
+| `quality.gates.maintainability.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
+| `quality.gates.maintainability.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
+| `quality.gates.maintainability.floors` | No | `object<map>` | `{"*":{"min":70}}` | 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. |
+| `quality.gates.maintainability.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
+| `quality.gates.maintainability.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `[]` | 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. |
+| `quality.gates.maintainability.refreshTag` | No | `string` | — | 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). |
+| `quality.gates.maintainability.refreshTimeoutMs` | No | `integer` | `60000` | 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). |
+| `quality.gates.maintainability.ignoreGlobs` | No | `array<string>` | `[]` | 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). |
+| `quality.gates.mutation` | No | `object` | — | Stryker mutation-score ratchet. Off in practice for most consumers — the baseline kind is registered but no framework path runs Stryker. |
+| `quality.gates.mutation.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
+| `quality.gates.mutation.baselinePath` | No | `string` | `"baselines/mutation.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
+| `quality.gates.mutation.tolerance` | No | `object` | `{"kind":"percent","value":0}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
+| `quality.gates.mutation.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
+| `quality.gates.mutation.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
+| `quality.gates.mutation.floors` | No | `object<map>` | `{"*":{"score":60}}` | 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. |
+| `quality.gates.mutation.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
+| `quality.gates.mutation.strykerConfigPath` | No | `string` \| `null` | `null` | Repo-relative path to the Stryker config. `null` lets Stryker resolve its own default. |
+| `quality.gates.lighthouse` | No | `object` | — | Lighthouse category-score ratchet for web targets. Off by default — it needs a running deployment. |
+| `quality.gates.lighthouse.enabled` | No | `boolean` | `false` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
+| `quality.gates.lighthouse.baselinePath` | No | `string` | `"baselines/lighthouse.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
+| `quality.gates.lighthouse.tolerance` | No | `object` | `{"kind":"absolute","value":0}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
+| `quality.gates.lighthouse.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
+| `quality.gates.lighthouse.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
+| `quality.gates.lighthouse.floors` | No | `object<map>` | `{"*":{"performance":0,"accessibility":0,"bestPractices":0,"seo":0}}` | 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. |
+| `quality.gates.lighthouse.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
+| `quality.gates.lighthouse.baseUrl` | No | `string` \| `null` | `null` | Origin the routes are resolved against. `null` leaves the gate unusable, which is why it ships disabled. |
+| `quality.gates.lighthouse.routes[]` | No | `array<object>` | `[]` | Routes to score on each run. Each item has: path, formFactor. |
+| `quality.gates.bundle-size` | No | `object` | — | Built-artifact size ratchet for web targets. Off by default — it needs declared bundles. |
+| `quality.gates.bundle-size.enabled` | No | `boolean` | `false` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
+| `quality.gates.bundle-size.baselinePath` | No | `string` | `"baselines/bundle-size.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
+| `quality.gates.bundle-size.tolerance` | No | `object` | `{"kind":"percent","value":0}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
+| `quality.gates.bundle-size.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
+| `quality.gates.bundle-size.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
+| `quality.gates.bundle-size.floors` | No | `object<map>` | `{"*":{}}` | 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. |
+| `quality.gates.bundle-size.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
+| `quality.gates.bundle-size.bundles[]` | No | `array<object>` | `[]` | The artifacts to weigh. Empty means the gate has nothing to do. Each item has: name, path, limit. |
+| `quality.gates.duplication` | No | `object` | — | 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. |
+| `quality.gates.duplication.enabled` | No | `boolean` | `false` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
+| `quality.gates.duplication.baselinePath` | No | `string` | `"baselines/duplication.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
+| `quality.gates.duplication.tolerance` | No | `object` | `{"kind":"absolute","value":1}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
+| `quality.gates.duplication.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
+| `quality.gates.duplication.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
+| `quality.gates.duplication.floors` | No | `object<map>` | `{"*":{"percentage":25}}` | 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. |
+| `quality.gates.duplication.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
+| `quality.gates.duplication.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `["src"]` | 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). |
+| `quality.gates.duplication.refreshTimeoutMs` | No | `integer` | `60000` | 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). |
+| `quality.gates.duplication.ignoreGlobs` | No | `array<string>` | `[]` | 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). |
 | `quality.formatAutofix` | No | `object` | — | Bounded-timeout knob for the close-time `npx biome format --write` spawn (Story #2165). A SIGKILL fired at the budget boundary maps to exit 124 so the close orchestrator can flip the Story to `agent::blocked` with a friction comment. |
-| `quality.formatAutofix.timeoutMs` | No | `integer` | — | — |
-| `quality.codingGuardrails` | No | `object` | — | Nested configuration block. |
-| `quality.codingGuardrails.cyclomaticFlag` | No | `integer` | — | — |
-| `quality.codingGuardrails.cyclomaticMustFix` | No | `integer` | — | — |
-| `quality.codingGuardrails.requireSiblingTest` | No | `boolean` | — | — |
-| `quality.autoRefresh` | No | `object` | — | Nested configuration block. |
-| `quality.autoRefresh.enabled` | No | `boolean` | — | — |
-| `quality.autoRefresh.crapJumpCap` | No | `number` | — | — |
-| `quality.autoRefresh.scope` | No | `"diff"` \| `"full"` | — | — |
+| `quality.formatAutofix.timeoutMs` | No | `integer` | `60000` | Timeout (ms) for the format-write spawn. |
+| `quality.codingGuardrails` | No | `object` | — | Authoring-time cyclomatic-complexity advisories surfaced by the quality-preview pre-commit gate. |
+| `quality.codingGuardrails.cyclomaticFlag` | No | `integer` | `8` | Cyclomatic complexity at which a new or changed method is flagged for a refactor look. |
+| `quality.codingGuardrails.cyclomaticMustFix` | No | `integer` | `12` | Cyclomatic complexity at which a new or changed method must be decomposed before the diff closes. |
+| `quality.codingGuardrails.requireSiblingTest` | No | `boolean` | `false` | When true, a new source file with no colocated sibling test is reported by the guardrails pass. |
+| `quality.autoRefresh` | No | `object` | — | Baseline-attribution auto-refresh: when a gate can prove a regression is a legitimate consequence of the diff, it rewrites the baseline instead of blocking. |
+| `quality.autoRefresh.enabled` | No | `boolean` | `true` | Master switch for the auto-refresh path. When false, every baseline refresh is a deliberate operator action. |
+| `quality.autoRefresh.crapJumpCap` | No | `number` | `5` | Largest single-row CRAP jump the auto-refresh will absorb. A larger jump is reported as a regression rather than rewritten. |
+| `quality.autoRefresh.scope` | No | `"diff"` \| `"full"` | `"diff"` | Whether an auto-refresh rescores only the changed files (`diff`) or every file in the target dirs (`full`). |
 | `quality.baselineEpsilon` | No | `object` | — | Per-kind epsilon for s-stability-epsilon (Story #1964). Sub-epsilon row deltas resolve to prior bytes so env variance does not rewrite the on-disk baseline. |
-| `quality.baselineEpsilon.maintainability` | No | `number` | — | — |
-| `quality.baselineEpsilon.crap` | No | `number` | — | — |
-| `quality.baselineEpsilon.coverage` | No | `number` | — | — |
-| `quality.baselineEpsilon.mutation` | No | `number` | — | — |
-| `quality.baselineEpsilon.lint` | No | `number` | — | — |
-| `quality.baselineEpsilon.lighthouse` | No | `number` | — | — |
-| `quality.baselineEpsilon.bundle-size` | No | `number` | — | — |
-| `quality.baselineEpsilon.duplication` | No | `number` | — | — |
-| `quality.requireBaselines` | No | `boolean` | — | Story #4495. Fail-closed baseline-enforcement policy for the unified check-baselines close-validation gate. When false (default), a consumer that enables baseline gates (crap/maintainability/…) but has not committed the corresponding baseline artifacts under baselines/ gets a clean skip-with-reason instead of a deterministic first-try close failure. Set true to keep the gate registered so an absent baseline artifact fails close-validation with a preflight hint naming the fix (the fail-closed posture). |
+| `quality.baselineEpsilon.maintainability` | No | `number` | `0.5` | — |
+| `quality.baselineEpsilon.crap` | No | `number` | `0.5` | — |
+| `quality.baselineEpsilon.coverage` | No | `number` | `0.1` | — |
+| `quality.baselineEpsilon.mutation` | No | `number` | `0.5` | — |
+| `quality.baselineEpsilon.lint` | No | `number` | `0` | — |
+| `quality.baselineEpsilon.lighthouse` | No | `number` | `1` | — |
+| `quality.baselineEpsilon.bundle-size` | No | `number` | `1024` | — |
+| `quality.baselineEpsilon.duplication` | No | `number` | `0.5` | — |
+| `quality.requireBaselines` | No | `boolean` | `false` | Story #4495. Fail-closed baseline-enforcement policy for the unified check-baselines close-validation gate. When false (default), a consumer that enables baseline gates (crap/maintainability/…) but has not committed the corresponding baseline artifacts under baselines/ gets a clean skip-with-reason instead of a deterministic first-try close failure. Set true to keep the gate registered so an absent baseline artifact fails close-validation with a preflight hint naming the fix (the fail-closed posture). |
 | `quality.navigability` | No | `object` | — | Navigability lens + journey-suite config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and /deliver's per-Story ceremony (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op. |
-| `quality.navigability.routeGlobs` | No | `array<string>` | — | Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route — the route-tree SSOT the navigability lens enumerates and the route-added routing predicate matches against. |
-| `quality.navigability.navRegistry` | No | `array<string>` | — | Tokens identifying the nav-registry SSOT the navigability lens checks every route resolves a nav door against. |
+| `quality.navigability.routeGlobs` | No | `array<string>` | `[]` | Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route — the route-tree SSOT the navigability lens enumerates and the route-added routing predicate matches against. |
+| `quality.navigability.navRegistry` | No | `array<string>` | `[]` | Tokens identifying the nav-registry SSOT the navigability lens checks every route resolves a nav door against. |
 | `quality.navigability.journeySuite` | No | `string` | — | Path or command for the per-persona journey suite /deliver's per-Story ceremony runs. |
 | `mergeWatch` | No | `object` | — | Knobs consumed by the close-and-land merge wait (Story #4543; defaults in `lib/orchestration/merge-poll.js`). `mode` (Story #4698) selects the close-time merge posture. `intervalSeconds` is the poll cadence between `gh pr view` probes after the arm. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. `updateAttempts` caps the bounded update of a behind-the-base PR. |
-| `mergeWatch.mode` | No | `"sync"` \| `"async"` | `"sync"` | Close-time merge-wait posture (Story #4698). `sync` (default) keeps the in-close foreground merge wait unchanged. `async` caps the per-invocation wait to a short ~60s probe window — long enough to catch an instant merge and, via the head-anchored required-check predicate, an instantly-red required check — then returns the resumable `pending` terminal (exit 3) with a `nextCommand`. Opt in when slow CI makes the foreground wait routinely expire: the worker launches `nextCommand` in the background instead of burning the host tool slot polling. `maxBudgetSeconds` (the cumulative give-up) is unchanged. |
+| `mergeWatch.mode` | No | `"sync"` \| `"async"` | — | Close-time merge-wait posture (Story #4698). `sync` (default) keeps the in-close foreground merge wait unchanged. `async` caps the per-invocation wait to a short ~60s probe window — long enough to catch an instant merge and, via the head-anchored required-check predicate, an instantly-red required check — then returns the resumable `pending` terminal (exit 3) with a `nextCommand`. Opt in when slow CI makes the foreground wait routinely expire: the worker launches `nextCommand` in the background instead of burning the host tool slot polling. `maxBudgetSeconds` (the cumulative give-up) is unchanged. |
 | `mergeWatch.intervalSeconds` | No | `integer` | `30` | Seconds between merge-wait polls. Default 30. |
-| `mergeWatch.maxWaitSeconds` | No | `integer` | `300` | Per-invocation merge-wait bound (seconds). Default 300 (5 minutes) — chosen to fit inside a single host tool invocation (~10 min ceiling) alongside the close gates that precede the wait. Expiry yields `pending` (exit 3), never a block. Headless callers with no host ceiling raise this to land in one block. |
+| `mergeWatch.maxWaitSeconds` | No | `integer` | — | Per-invocation merge-wait bound (seconds). Default 300 (5 minutes) — chosen to fit inside a single host tool invocation (~10 min ceiling) alongside the close gates that precede the wait. Expiry yields `pending` (exit 3), never a block. Headless callers with no host ceiling raise this to land in one block. |
 | `mergeWatch.maxBudgetSeconds` | No | `integer` | `3600` | Cumulative wall-clock budget (seconds) across merge-wait resumes, anchored at the PR's createdAt. Default 3600 (60 minutes). Exhausting this classifies the block and transitions the Story to agent::blocked. |
-| `mergeWatch.updateAttempts` | No | `integer` | `3` | Maximum times the merge wait will bring a behind-the-base PR up to date before giving up on the branch. Default 3. Set 0 to disable the update. |
-| `codeReview` | No | `object` | — | Nested configuration block. |
-| `codeReview.providers[]` | No | `array<object>` | — | Review-provider chain (Story #2871). When unset or empty, defaults to [{ name: "native" }]. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. Each item has: name, scopes, optional, manualPrompt, when. |
+| `mergeWatch.updateAttempts` | No | `integer` | — | Maximum times the merge wait will bring a behind-the-base PR up to date before giving up on the branch. Default 3. Set 0 to disable the update. |
+| `codeReview` | No | `object` | — | Review-provider chain plus bounded-retry knobs for the /deliver code-review ceremony. |
+| `codeReview.providers[]` | No | `array<object>` | `[{"name":"native"},{"name":"security-review","scopes":["story"],"optional":true},{"name":"ultrareview","scopes":["story"],"manualPrompt":true,"when":{"label":"risk::high"}}]` | Review-provider chain (Story #2871). When unset or empty, defaults to [{ name: "native" }]. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. Each item has: name, scopes, optional, manualPrompt, when. |
 | `codeReview.providerConfig` | No | `object` | — | Optional escape hatch for adapter-specific configuration. No documented keys in Epic #2815; reserved so future adapters can be configured without another schema migration. |
-| `codeReview.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /deliver Phase 5 (code-review). 0 disables auto-fix. Default 3. |
-| `codeReview.maxFixScopeFiles` | No | `integer` | — | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
+| `codeReview.maxFixAttempts` | No | `integer` | `3` | Maximum auto-fix retry attempts per finding in /deliver Phase 5 (code-review). 0 disables auto-fix. Default 3. |
+| `codeReview.maxFixScopeFiles` | No | `integer` | `5` | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
 | `codeReview.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | Severity threshold for on-branch remediation in /deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag. |
 | `review` | No | `object` | — | Close-scope review tuning (Story #4699). Governs the Story-scope local-lens pass that runs inside the close subprocess; the maker-blind code-review pass and all hard gates are unaffected. |
-| `review.lensDiffFloor` | No | `integer` | `40` | Changed-line floor for the close-scope lens walk (Story #4699). A diff strictly below this many changed lines (additions + deletions) with zero sensitive-path hits skips lens materialization and records the skip in the findings-yield ledger. Default 40; 0 disables the skip. |
+| `review.lensDiffFloor` | No | `integer` | — | Changed-line floor for the close-scope lens walk (Story #4699). A diff strictly below this many changed lines (additions + deletions) with zero sensitive-path hits skips lens materialization and records the skip in the findings-yield ledger. Default 40; 0 disables the skip. Hard gates and the maker-blind code-review pass are unaffected. |
 | `refactorStage` | No | `object` | — | Opt-in, config-gated post-green refactor checkpoint wired into story-deliver (Story #3430, Epic #3418). Strictly additive and default-OFF: when disabled, story-deliver behaves exactly as before. Advisory only — never changes existing close-validation gate semantics. |
 | `refactorStage.enabled` | No | `boolean` | `false` | When true, story-deliver runs an advisory post-green refactor stage (core/code-review-and-quality skill, Post-Green Refactor Pass) after the suite is green. Default false — when unset the stage is skipped and close-validation gate semantics are unchanged. |
 | `acceptanceEval` | No | `object` | — | Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds, then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the loop is a hard cutover (always on). |
-| `acceptanceEval.maxRounds` | No | `integer` | — | Maximum number of redraft rounds before escalation. Default 2; clamped into [1, hard ceiling] by lib/config/acceptance-eval.js so the cap can never be disabled (maxRounds: 0 clamps up to 1). |
-| `acceptanceEval.clusterCeiling` | No | `integer` | — | Epic #4475 (M4-B). Max acceptance criteria one single-delivery acceptance critic scores in a single fresh-context pass. Single delivery clusters the Epic ## Acceptance Table ACs into ceil(totalACs / clusterCeiling) groups and spawns one maker-blind critic per cluster, restoring the distributed acceptance coverage the per-Story critic fan-out gave for free. Default 4; clamped into [1, 8] by lib/config/acceptance-eval.js so a large value cannot collapse the fan-out to a single diluted critic. Ignored on the fan-out route. |
-| `ci` | No | `object` | — | Nested configuration block. |
-| `ci.watch` | No | `object` | — | Story #4356 (Epic #4355). Poll-loop tuning for the merge/CI watch. pollIntervalMs is the cadence between check probes; maxPolls caps total probes before the watcher gives up; maxResumes caps how many times the watcher may resume after a transient stall; attachWindowMs bounds the wait for a required context to attach at all. |
-| `ci.watch.pollIntervalMs` | No | `integer` | — | — |
-| `ci.watch.maxPolls` | No | `integer` | — | — |
-| `ci.watch.maxResumes` | No | `integer` | — | — |
-| `ci.watch.attachWindowMs` | No | `integer` | — | Story #4890. How long (ms) the watch keeps re-resolving an EMPTY `gh pr checks --required` set before it stops waiting for a required context to attach. A ruleset attaches its contexts asynchronously and the arrival latency is set by the slowest one, so a required context that is an aggregator job gated on every other tier is the last to appear — measured at 16m52s on this repository. Default 1200000 (20 minutes). Raise it for a repository whose contexts arrive later still; exhausting the window is never reported as a red check (the watch exits 2, not-yet-started). |
-| `ci.autoMerge` | No | `"trust-ci"` \| `"strict"` | — | Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate. |
-| `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6. |
-| `routing.roleScopedAgents` | No | `boolean` | — | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure (≈50KB → ≈8KB per spawn — the payoff of the context diet). When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
-| `routing.freshCriticSampleRate` | No | `number` | — | Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Default 0.2. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js). |
-| `routing.ceremonyProfile` | No | `"minimal"` \| `"standard"` \| `"strict"` | — | Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff, with the maker-checker sampling floor. |
-| `routing.closeAndLand` | No | `boolean` | — | When true (default), single-story-close lands through merge in one close. Opt out per-run with --no-wait-merge. |
-| `feedbackLoop` | No | `object` | — | Nested configuration block. |
+| `acceptanceEval.maxRounds` | No | `integer` | `2` | Maximum number of redraft rounds before escalation. Default 2; clamped into [1, hard ceiling] by lib/config/acceptance-eval.js so the cap can never be disabled (maxRounds: 0 clamps up to 1). |
+| `feedbackLoop` | No | `object` | — | Opt-out toggles for the close-time auto-file graduators. All default to auto-filing on. |
 | `feedbackLoop.auditResultsAutoFile` | No | `boolean` | `true` | When true (default), the close-time audit-results graduator auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Story. |
 | `feedbackLoop.retroProposals` | No | `boolean` | `true` | When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap\|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas. |
-| `feedbackLoop.frictionWindowDays` | No | `integer` | `30` | How many days back the run-scope friction recurrence window reaches (Story #4850). The window spans every surviving per-Story signal stream rather than the triggering run's own Stories, so that a defect firing once per Story can reach the actionable threshold; this bounds it by age so a defect fixed weeks ago stops re-routing. Rows older than the bound — and rows carrying no readable timestamp — are excluded and counted on the roll-up step result. Default 30. |
-| `auditToStories` | No | `object` | — | Nested configuration block. |
-| `auditToStories.severityFloor` | No | `"critical"` \| `"high"` \| `"medium"` \| `"low"` \| `"all"` | `"high"` | Minimum severity a finding must meet to be proposed as a Story on an unattended `/audit-to-stories --auto` sweep (Story #4626). Default high. |
-| `auditToStories.autoComment` | No | `boolean` | `true` | When true (default), `/audit-to-stories --auto` posts a re-detected comment on an already-open matched Issue instead of silently skipping it. |
+| `feedbackLoop.frictionWindowDays` | No | `integer` | — | How many days back the run-scope friction recurrence window reaches (Story #4850). The window spans every surviving per-Story signal stream rather than the triggering run's own Stories, so that a defect firing once per Story can reach the actionable threshold; this bounds it by age so a defect fixed weeks ago stops re-routing. Rows older than the bound — and rows carrying no readable timestamp — are excluded and counted on the roll-up step result. Default 30. |
+| `auditToStories` | No | `object` | — | Knobs for the `/audit-to-stories` unattended (`--auto`) sweep (Story #4626). |
+| `auditToStories.severityFloor` | No | `"critical"` \| `"high"` \| `"medium"` \| `"low"` \| `"all"` | — | Minimum severity a finding must meet to be proposed as a Story on an unattended `/audit-to-stories --auto` sweep (Story #4626). Default high. |
+| `auditToStories.autoComment` | No | `boolean` | — | When true (default), `/audit-to-stories --auto` posts a re-detected comment on an already-open matched Issue instead of silently skipping it. |
+| `ci` | No | `object` | — | CI-aware delivery namespace (Story #4356, Epic #4355): the merge/CI watch poll loop and the merge posture. |
+| `ci.watch` | No | `object` | — | Story #4356 (Epic #4355). Poll-loop tuning for the merge/CI watch. pollIntervalMs is the cadence between check probes; maxPolls caps total probes before the watcher gives up; maxResumes caps how many times the watcher may resume after a transient stall; attachWindowMs bounds the wait for a required context to attach at all. |
+| `ci.watch.pollIntervalMs` | No | `integer` | `10000` | Milliseconds between check probes. |
+| `ci.watch.maxPolls` | No | `integer` | `180` | Total probes before the watcher gives up on one invocation. |
+| `ci.watch.maxResumes` | No | `integer` | `3` | How many times the watcher may resume after a transient stall. 0 disables resuming. |
+| `ci.watch.attachWindowMs` | No | `integer` | `1200000` | Story #4890. How long (ms) the watch keeps re-resolving an EMPTY `gh pr checks --required` set before it stops waiting for a required context to attach. A ruleset attaches its contexts asynchronously and the arrival latency is set by the slowest one, so a required context that is an aggregator job gated on every other tier is the last to appear — measured at 16m52s on this repository. Default 1200000 (20 minutes). Raise it for a repository whose contexts arrive later still; exhausting the window is never reported as a red check (the watch exits 2, not-yet-started). |
+| `ci.autoMerge` | No | `"trust-ci"` \| `"strict"` | `"trust-ci"` | Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate. |
+| `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6. |
+| `routing.roleScopedAgents` | No | `boolean` | `true` | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
+| `routing.freshCriticSampleRate` | No | `number` | `0.2` | Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js). |
+| `routing.ceremonyProfile` | No | `"minimal"` \| `"standard"` \| `"strict"` | `"standard"` | Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff, with the maker-checker sampling floor. |
+| `routing.closeAndLand` | No | `boolean` | `true` | When true (default), single-story-close lands through merge in one close. Opt out per-run with --no-wait-merge. |
+
+### `qa` (optional)
+
+Agent-driven QA harness contract (Epic #3214; environment-keyed by Epic #4326). Optional top-level block. All filesystem-pointer fields (featureRoot, fixturesManifest, designTokens) carry safeString guards rejecting shell-injection metacharacters. environments is a map of named deployment targets (each with a baseUrl, a per-environment url-template/skill sign-in seam, and an optional allowWrites gate); personas resolve to a stored credential reference or a sign-in skill, never an inline secret.
+
+| Key | Required | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `featureRoot` | No | `string` | `"tests/features"` | Directory holding the Gherkin feature files the QA sweep drives. |
+| `fixturesManifest` | No | `string` | `"tests/fixtures/personas.json"` | Path to the persona/fixture manifest the harness seeds from. |
+| `environments` | No | `object<map>` | `{"local":{"baseUrl":"http://localhost:3000","signInSeam":{"urlTemplate":"/dev/sign-in-as/{persona}"}},"staging":{"baseUrl":"https://staging.example.test","signInSeam":{"skill":"stack/qa/sign-in"},"allowWrites":false}}` | Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, its own per-environment sign-in seam (the same url-template/skill union as the top-level seam), and an optional `allowWrites` gate. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`. |
+| `personas` | No | one of: `array`, `object` | `{"admin":{"credentialRef":"QA_ADMIN_CREDENTIAL"},"member":{"signInSkill":"stack/qa/sign-in-member"}}` | Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names — the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a skill-based or credential-based seam. |
+| `gherkinLint` | No | `object` | `{"scopes":{"web":{"featureRoots":["apps/web/tests/features"],"stepRoots":["apps/web/tests/steps"]}},"exemptionTags":["@skip"],"stepWaivers":[]}` | Static Gherkin corpus gate (Story #5013). Optional; the gate runs only when this block is present, so an upgrade never reddens the lint of a consumer that never asked the framework to police its `.feature` files. Inside the opt-in it fails closed: an unresolvable `@cucumber/gherkin` parser, or a scope resolving zero step definitions, exits 1 rather than reporting a clean run. |
+| `gherkinLint.scopes` | Yes | `object<map>` | — | Binding scopes, keyed by name. Each scope resolves its own features against its own step definitions only — pooling every step root into one matcher list is what makes a cross-app false bind possible, where a step defined solely in app B silently vouches for app A. The scope name appears verbatim in every unbound finding. |
+| `gherkinLint.exemptionTags` | No | `array<string>` | `["@skip"]` | Tags marking a scenario as intentionally non-binding, so must-bind skips it. Never an escape from must-compile: a parse error in the file still fails the run. Default: ["@skip"]. |
+| `gherkinLint.stepWaivers` | No | `array<string>` | `[]` | Exact step texts must-bind never reports as unbound. The step index is a source scan and therefore heuristic while the parser is exact, so a false unbound must always have an escape that does not require switching the gate off. Default: []. |
+| `consoleAllowlist` | No | `array<string>` | `["Download the React DevTools","[HMR]"]` | Console-message substrings the QA run tolerates instead of reporting as a finding (framework dev-mode chatter). |
+| `designTokens` | No | `string` | `"src/styles/tokens.css"` | Path to the design-token SSOT the UX/UI lens checks rendered styles against. |
 
 <!-- END GENERATED:agentrc -->
 
@@ -476,7 +518,6 @@ number of keys.
 
 | Key                                                  | Root dogfood                          | Distributed template (`agentrc-reference.json`) | Why they differ                                                                                                                  |
 | ---------------------------------------------------- | ------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
-| `project.commands.lintBaseline`                      | `npm run lint`                        | `npx eslint . --format json`               | Root piggybacks on the repo's existing lint script; consumer template assumes a generic ESLint setup with structured output.     |
 | `delivery.quality.gates.maintainability.targetDirs`  | `[".agents/scripts", "tests"]`        | `["src"]`                                  | Root scans the framework's own source tree; consumer template scans the conventional `src/`.                                     |
 | `delivery.quality.gates.crap.targetDirs`             | `[".agents/scripts"]`                 | `["src"]`                                  | Same reason as maintainability above.                                                                                            |
 | `github.owner` / `.repo` / `.projectNumber` | Populated for `dsj1984/mandrel` | `[OWNER]` / `[REPO]` / `null` | Shared repo identifiers; placeholders in the template are replaced by `node .agents/scripts/bootstrap.js` (or by hand). |
@@ -510,7 +551,7 @@ the lint ratchet, and the CRAP/MI gates.
 
 | File                              | Owner                                | Refresh                                                                |
 | --------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- |
-| `baselines/lint.json`             | `lint-baseline.js`                   | `node .agents/scripts/lint-baseline.js capture`                       |
+| `baselines/lint.json`             | the consumer's own linter            | No framework CLI — see [Lint baseline ratchet](quality-gates.md#lint-baseline-ratchet) |
 | `baselines/crap.json`             | `update-crap-baseline.js`            | `npm run crap:update`                                                   |
 | `baselines/maintainability.json`  | `update-maintainability-baseline.js` | `npm run maintainability:update`                                        |
 | `baselines/bundle-size.json`      | consumer's own build/measure step    | Commit the build's measured sizes; for an intentional growth, run the check with `BUNDLE_SIZE_REFRESH=1` (see [Bundle-size ratchet](quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)) |
@@ -606,14 +647,20 @@ and stay committed with real values.
 This is a framework-level change, not a project-level one. The path is:
 
 1. Add the AJV schema in the relevant module under
-   `.agents/scripts/lib/`.
-2. Mirror it manually in `.agents/schemas/agentrc.schema.json`.
-3. Add a resolver getter in
+   `.agents/scripts/lib/`, carrying a `description` annotation — that string
+   is the operator-facing gloss in the shipped mirror and in the key table
+   above. Add a `default` annotation only when the key belongs in the
+   defaults inventory (see the annotation contract at the top of
+   `config-settings-schema.js`), importing the matching runtime `*_DEFAULTS`
+   constant rather than restating a literal.
+2. Add a resolver getter in
    [`config-resolver.js`](../scripts/lib/config-resolver.js).
+3. Run `npm run docs:gen`. The mirror, the defaults inventory, and this
+   file's key table are regenerated — never hand-edited.
 4. Add tests under `tests/lib/config-*.test.js` and confirm
-   `tests/config-schema-mirror-drift.test.js` passes.
-5. Document the key in this file and update `mandrel-sync-config.md` only if
-   the merge semantics differ from the default (project-wins) rule.
+   `tests/config-schema-mirror-drift.test.js` (generator fidelity) passes.
+5. Update `mandrel-sync-config.md` only if the merge semantics differ from
+   the default (project-wins) rule.
 
 ---