mandrel 2.59.0 → 2.61.0

package/.agents/docs/configuration.md

@@ -42,7 +42,7 @@ hand-mirrored, so a key cannot exist in one artifact and not another.
   "$schema": "./.agents/schemas/agentrc.schema.json",
   "project":  { /* paths, commands, baseBranch, docsContextFiles */ },
   "github":   { /* owner, repo, branchProtection, mergeMethods, notifications */ },
-  "planning": { /* riskHeuristics, conflict gates, complexityGate, navigation */ },
+  "planning": { /* memoryPool, navigation */ },
   "delivery": { /* execution, quality, worktreeIsolation, deliverRunner, ... */ },
   "qa":       { /* featureRoot, fixturesManifest, environments, personas */ }
 }
@@ -102,7 +102,6 @@ GitHub provider identity plus the remote stance the bootstrap enforces. `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. |
 | `followUpRepos` | No | `object` | — | Repository slugs for the non-consumer follow-up ownership buckets, used when a CI gap, retro proposal, or audit finding belongs to someone other than the repo that surfaced it. |
 | `followUpRepos.framework` | No | `string` | `"dsj1984/mandrel"` | `<owner>/<repo>` that owns framework-level defects. Defaults to the Mandrel mirror — the one bucket with a knowable default. |
 | `followUpRepos.platform` | No | `string` \| `null` | `null` | `<owner>/<repo>` for a shared platform or infrastructure tracker (a shared base config, a runner fleet, a cross-repo toolchain). No default — nothing can guess a shared repo. Left unset, platform-owned findings file locally and say so. |
@@ -122,31 +121,26 @@ GitHub provider identity plus the remote stance the bootstrap enforces. `owner`,
 
 ### `planning` (optional)
 
-Inputs to `/mandrel-plan`: the memory-hygiene advisory ceiling and the opt-in navigability reachability gate.
+Inputs to `/mandrel-plan`: the opt-in navigability reachability gate.
 
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `memoryPool` | No | `object` | — | Threshold for the memory-hygiene advisory `/mandrel-plan` surfaces at Gate #1. Advisory only: it recommends `/memory-consolidate` and never gates, reroutes, or mutates the memory pool. |
-| `memoryPool.indexByteCeiling` | No | `integer` | `24576` | Recommend a consolidation pass once the pool's `MEMORY.md` index exceeds this many bytes. The harness truncates the index it loads into each session at its own byte cap, so an oversized index is a loss already happening — every entry listed after the cut is invisible — rather than a hygiene forecast. Default 24576, the harness cap itself. |
 | `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. |
 
 ### `delivery` (optional)
 
-Everything `/mandrel-deliver` and `single-story-close` consume: execution timeouts, worktree isolation, runner concurrency, docs freshness, quality gates, merge/CI watch, review ceremony, and the feedback loop.
+Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolation, runner concurrency, docs freshness, quality gates, merge/CI watch, review ceremony, and the feedback loop.
 
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `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. |
+| `execution` | No | `object` | — | Serialization of the full-suite spawns delivery drives. |
 | `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
-| `execution.requireCreditedCapture` | No | `boolean` | `false` | Refuse a full-suite coverage capture that no committed stamp covers, instead of paying for it. Default false — the run is announced (a warning naming the crediting invocation, emitted before the spawn) and then executed, which is the pre-existing behaviour. Set true when the whole-suite cost is large enough that a close should stop at zero seconds rather than absorb it silently. |
 | `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` | `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` | `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. |
@@ -163,19 +157,8 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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. |
-| `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` | No | `object` | — | Quality-gate configuration. Every gate lives under `gates.<tier>` and shares the same `{ enabled, baselinePath, tolerance, floors, components }` base. |
+| `quality.gates` | No | `object` | — | The six quality gates, each sharing the `{ enabled, baselinePath, tolerance, floors, components }` base. |
 | `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. |
@@ -185,7 +168,6 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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. |
@@ -198,16 +180,11 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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` | — | The two independent full-suite economies (Story #4981, split by Story #5173). `skipWhenUnchanged` (default true) decides WHETHER to capture — no changed file under `crap.targetDirs` versus `baseRef` means no capture at all — and is a pure saving. `baselineJoin` (default false) loosens gate semantics: the CRAP join resolves a method in an untouched file from its committed baseline row instead of requiring fresh coverage for it. Neither narrows the capture run itself: a capture that does happen is the ordinary full `npm run test:coverage` (Story #5065). |
 | `quality.gates.crap.incrementalCoverage.skipWhenUnchanged` | No | `boolean` | `true` | Skip the capture entirely when no changed file under `crap.targetDirs` versus `baseRef` was touched. The only measured saving, and gate-semantics-neutral. Defaults to true. |
 | `quality.gates.crap.incrementalCoverage.baselineJoin` | No | `boolean` | `false` | Let the CRAP join resolve a method in a file the diff did not touch from its committed baseline row instead of requiring fresh coverage for it. A gate loosening, not a saving — defaults to false. |
-| `quality.gates.crap.incrementalCoverage.enabled` | No | `boolean` | — | DEPRECATED alias for setting both `skipWhenUnchanged` and `baselineJoin`. Prefer the two switches: they are not equally safe, and bundling them is why the earlier default flip was reverted. Either explicit switch overrides this alias. |
-| `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.crap.incrementalCoverage.baseRef` | No | `string` | — | Default git ref the changed-file set is computed against, for a caller that passes no `--ref`. A `--ref` the caller named wins over this value, so a caller that anchors another gate on the same ref — `.husky/pre-push`, which passes `--ref origin/main` and then previews `--changed-since origin/main` — resolves ONE scope for both steps (Story #5365). Omitted and unpassed, the gate’s own default `main` applies. |
 | `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. |
@@ -217,8 +194,6 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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. |
@@ -228,17 +203,6 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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. |
@@ -248,7 +212,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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` | No | `object` | — | Code-duplication (DRY) gate (Story #3664). Shares the gate base and adds the scan-scope extras: the `targetDirs` the duplication scanner walks 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. |
@@ -257,68 +221,35 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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` | `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.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` | 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. The single-row CRAP jump cap (5) and the rescore scope (`diff`) are fixed. |
 | `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` | `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 /mandrel-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.journeySuite` | No | `string` | — | Path or command for the per-persona journey suite /mandrel-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` | No | `object` | — | Knobs consumed by the close-and-land merge wait (Story #4543). `mode` (Story #4698) selects the close-time merge posture. `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. The 30s poll cadence and the cap of 3 behind-the-base updates are fixed. |
 | `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` | — | 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` | — | 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 /mandrel-deliver code-review ceremony. |
+| `codeReview` | No | `object` | — | Review-provider chain and on-branch remediation threshold for the /mandrel-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` | `3` | Maximum auto-fix retry attempts per finding in /mandrel-deliver Phase 5 (code-review). 0 disables auto-fix. Default 3. |
 | `codeReview.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | Severity threshold for on-branch remediation in /mandrel-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` | — | 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 (0 = scored once, no redraft), then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the scoring pass is a hard cutover (always on). |
 | `acceptanceEval.maxRounds` | No | `integer` | `2` | Maximum number of redraft rounds before escalation. Default 2; 0 means the verdict is scored once with no redraft round (Story #5313 dropped the hard ceiling and the floor-of-one clamp). |
-| `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` | — | 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). |
+| `feedbackLoop` | No | `object` | — | Opt-in toggle for the close-time retro auto-file graduator. Auto-filing defaults to OFF (Story #5341). |
+| `feedbackLoop.retroProposals` | No | `boolean` | `false` | When true, 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. Defaults to false (Story #5341), which renders the command stanzas instead. |
+| `ci` | No | `object` | — | CI-aware delivery namespace (Story #4356, Epic #4355): the merge posture and the advisory-check policy. |
 | `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. |
 | `ci.blockOnAdvisoryFailure` | No | `boolean` | `true` | Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim. |
 | `ci.advisoryAllowlist` | No | `array<string>` | `[]` | Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks. |
 | `ci.rerunAdvisory` | No | `integer` | `0` | Story #5266. How many times close may re-run a failed advisory workflow run before blocking on it, per close invocation. Default 0: close spends no CI minutes and issues no GitHub mutation on an advisory red unless asked. At n > 0 the failed run(s) are re-run within that allowance and the merge wait re-polls inside its existing budget, landing or blocking on the re-run verdict. Overridden per invocation by --rerun-advisory <n>. |
-| `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313. |
+| `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313 and the derived-level ceremony routing in Story #5343. |
 | `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.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: high or underivable → fresh, low → inline. |
+| `routing.ceremonyProfile` | No | `"minimal"` \| `"standard"` \| `"strict"` | `"standard"` | Acceptance-ceremony depth — who authors the Story acceptance verdict. minimal and standard (default) = the inline self-eval, whatever the diff touches; strict = a fresh-context maker-blind critic. Review depth is a separate decision and still derives `deep` for any sensitive path (review-depth.js). |
 | `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)
@@ -382,7 +313,7 @@ names or defaults.
 - **`notifications`.** Both event allowlists filter their channel
   independently; their enums are pinned in the schema. Set an array to `[]` to
   suppress a channel. The severity vocabulary and shipped default allowlists
-  are documented under [`SDLC.md` § Notification system](SDLC.md#notification-system).
+  are documented under [`SDLC.md` § Notification system](https://github.com/dsj1984/mandrel/blob/main/docs/SDLC.md#notification-system).
 
 ### `planning`
 
@@ -400,38 +331,17 @@ pre-computed inventory added a second, staler answer to the same question.
 A config still carrying the retired key is a hard validation failure; the
 2.20.0 retirement migration strips it on upgrade.
 
-- **`complexityGate`.** Shape-derived ceremony-lite routing (Story #4722,
-  superseding the word-count gate of Stories #4683/#4707). The full ceremony
-  buys measurable quality on capability-sized work but imposes a large fixed
-  cost premium on genuinely trivial scopes — and seed word count is the wrong
-  proxy in both directions (a detailed prompt can describe trivial work, a
-  terse one complex work), so `maxSeedWords` was **removed** in the hard
-  cutover (a config still setting it is rejected as an additional property).
-  Routing is now staged on the objective shape of the work: `/mandrel-plan`'s context
-  envelope emits advisory `complexitySignals` (enumerated-artifact count,
-  risk-heuristic hits, repo state of predicted paths, sensitive-path classes)
-  with **no routing authority**; the planner authors the trivial-vs-standard
-  verdict via `plan-persist.js --route-downgrade-reason "<why>"` (recorded on
-  every created Story's `story-plan-state` checkpoint); persist validates a
-  lite claim against each authored Story's own shape (`changes[]` count,
-  acceptance count, creates-vs-refactors mix, sensitive-path classes — the
-  framework constants `STORY_SHAPE_CEILINGS`) and **fails closed to `full`**
-  when the shape exceeds the ceilings; and `/mandrel-deliver` re-derives the route
-  from the fetched Story body via the same shape function at dispatch. The
-  `route::lite` label is a human-visible hint only — a lost label cannot
-  misroute delivery. A lite-shaped Story executes inline (no story-worker or
-  acceptance-critic sub-agent fan-out); sensitivity always wins — a footprint
-  intersecting a sensitive-path class routes `full` and keeps its fresh
-  critic. The lite path **never** relaxes a non-negotiable: it still produces
-  a Story ticket, still lands via a PR to `main`, still runs every repo
-  quality gate, and still honours `rules/security-baseline.md` — those gates
-  run in `single-story-close.js` regardless of route. **Knobs:** `enabled`
-  (default `true`; `false` disables lite routing everywhere) and
-  `maxArtifacts` (default `1` — a signal threshold, not a router). Defaults
-  live on `DEFAULT_COMPLEXITY_GATE` in
-  [`lib/orchestration/complexity-gate.js`](../scripts/lib/orchestration/complexity-gate.js);
-  a malformed or negative value falls back to the default rather than
-  widening the lite path.
+- **`complexityGate`.** **Retired** (Story #5312). The planner's authored
+  lite claim (`plan-persist.js --route-downgrade-reason`), the persist-time
+  shape backstop that validated it against `STORY_SHAPE_CEILINGS`, the
+  `route::lite` hint label and this whole knob block are gone. Persist no
+  longer routes: every Story lands through the same engine and the same close
+  gates, and a config still setting `planning.complexityGate` is a hard
+  validation failure the `2.57.0` retirement migration strips on upgrade.
+  What survives is delivery-side and reads evidence rather than a declaration
+  — `/mandrel-plan`'s advisory `complexitySignals` (no routing authority), the
+  `/deliver-light` suitability gate's two absolute risk rules, and that path's
+  diff backstop against the actual change set.
 
 ### `delivery`
 
@@ -450,7 +360,7 @@ A config still carrying the retired key is a hard validation failure; the
   `duplication` `targetDirs` default `["src"]`. The `bundle-size` gate has
   **no** `refreshTag` — there is no scorer to regenerate its baseline, so its
   one-shot refresh is the `BUNDLE_SIZE_REFRESH=1` env var, not a config knob
-  (see [`quality-gates.md` § Bundle-size ratchet](quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)).
+  (see [`quality-gates.md` § Bundle-size ratchet](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)).
   Extend the list-valued gate keys with the deep-merge extender form (see
   [How to extend](#how-to-extend)).
 
@@ -489,14 +399,19 @@ non-Claude consumers can pin the same `.agents/` version unmodified. The fix
 budget (`maxFixAttempts` / `maxFixScopeFiles`) uses the same values for every
 Story in a run — there is no per-Story override.
 
-#### `delivery.feedbackLoop` — verification-results auto-graduation
+#### `delivery.feedbackLoop` — retro auto-graduation
 
-`auditResultsAutoFile` auto-graduates surviving non-blocking findings from the
-unified `verification-results` comment into follow-up issues; the graduator
-embeds a content-derived idempotency marker so re-runs skip findings that
-already have an issue (re-enabling after a manual-triage window is safe). The
-former `codeReviewAutoFile` key was retired when Story #4411 unified the pass —
-a config carrying it fails validation; delete it.
+`retroProposals` auto-graduates the retro's actionable routed proposals into
+follow-up issues; the graduator embeds a content-derived idempotency marker so
+re-runs skip proposals that already have an issue (re-enabling after a
+manual-triage window is safe). It defaults to `false` (Story #5341) — set it
+to `true` to opt in.
+
+Two sibling keys were retired and a config carrying either fails validation;
+delete it. `codeReviewAutoFile` went when Story #4411 unified the pass.
+`auditResultsAutoFile` went in Story #5366: its graduator had already been
+deleted, so the toggle had no runtime reader and Story #5341's flip of its
+default changed nothing. `mandrel update` strips it for you.
 
 ---
 
@@ -547,14 +462,15 @@ the lint ratchet, and the CRAP/MI gates.
 
 | File                              | Owner                                | Refresh                                                                |
 | --------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- |
-| `baselines/lint.json`             | the consumer's own linter            | No framework CLI — see [Lint baseline ratchet](quality-gates.md#lint-baseline-ratchet) |
+| `baselines/coverage.json`         | `update-coverage-baseline.js`        | `node .agents/scripts/update-coverage-baseline.js`                     |
 | `baselines/crap.json`             | `update-crap-baseline.js`            | `npm run crap:update`                                                   |
+| `baselines/duplication.json`      | `update-duplication-baseline.js`     | `node .agents/scripts/update-duplication-baseline.js`                  |
 | `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)) |
+| `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](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)) |
 
 These files are the contract — read by every gate (Story close, push hook, CI)
 and regenerated only via tagged `baseline-refresh:` commits with a non-empty
-body (see [`quality-gates.md`](quality-gates.md) for the policy). Paths are
+body (see [`quality-gates.md`](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md) for the policy). Paths are
 configured in `delivery.quality.gates.<tier>.baselinePath`, defaulting to the
 layout above. The `.agents/state/` directory is created on demand by the
 progress reporter and is not committed.
@@ -677,7 +593,7 @@ Claude Code web environment-variables UI for web sessions.
 | `WEBHOOK_SECRET`           | No        | Shared secret used to sign outbound webhook payloads as `X-Signature-256: sha256=<hmac>`. Unset ships unsigned payloads.                                 |
 | `MANDREL_ALLOW_TEST_WEBHOOKS` | No     | Set to `1` to keep `NOTIFICATION_WEBHOOK_URL` live inside `npm test` / `npm run test:profile`. Default behaviour scrubs the env var from the test child so no URL resolves and the webhook never fires (see below). |
 | `MANDREL_POOL_CONCURRENCY` | No | Upper bound on the width of every `runOnPool` worker pool in the process (the MI and CRAP scan pools). Precedence is: a caller's explicit `concurrency` → this variable → a clamp of 4 under `node:test` → `os.availableParallelism()`. Set it on a constrained or shared runner where one pool per core oversubscribes the host; a non-numeric value is ignored rather than collapsing the pool. |
-| `MANDREL_BASELINE_GENERATED_AT` | No | Pins the `generatedAt` stamp every baseline envelope carries, instead of reading the clock. Set it for a reproducible build, or to make a hand-run refresh diff against a known stamp. It changes only the stamp — rows and rollup are unaffected, and a refresh that moves no row still rewrites nothing. Concurrent refreshes no longer need it to avoid conflicting: `baselines/*.json` merges by row identity (see the baseline merge driver in [quality-gates.md](quality-gates.md)). |
+| `MANDREL_BASELINE_GENERATED_AT` | No | Pins the `generatedAt` stamp every baseline envelope carries, instead of reading the clock. Set it for a reproducible build, or to make a hand-run refresh diff against a known stamp. It changes only the stamp — rows and rollup are unaffected, and a refresh that moves no row still rewrites nothing. Concurrent refreshes no longer need it to avoid conflicting: `baselines/*.json` merges by row identity (see the baseline merge driver in [quality-gates.md](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md)). |
 | `MANDREL_AGENTRC_VALIDATOR` | No | Set to `dynamic` to compile the `.agentrc.json` AJV validator at runtime instead of loading the committed precompiled one (see below). Costs ~35 ms per process; the escape hatch exists for a hand-edited schema or a host where the generated module will not load. |
 
 ### The `.agentrc` validator is precompiled
@@ -690,7 +606,7 @@ resolve configuration, so the compile was being paid over and over to
 re-derive a function from a literal that is already in the repository.
 
 The artifact is generated — never hand-edited — by
-[`check-generated-validator.js`](../scripts/check-generated-validator.js):
+`scripts/check-generated-validator.js` (mandrel's own repository):
 
 ```bash
 npm run validator:gen     # rewrite it after a deliberate schema change
@@ -833,6 +749,6 @@ Run `mandrel --help` for the live list.
 - Bootstrap script —
   [`bootstrap.js`](../scripts/bootstrap.js)
 - Quality gates runbook (CRAP onboarding, MI ratchet, lint ratchet) —
-  [`quality-gates.md`](quality-gates.md)
+  [`quality-gates.md`](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md)
 - Activation pointers (slash commands, personas, skills) —
   [`.agents/README.md`](../README.md)

package/.agents/docs/workflows.md

@@ -10,7 +10,7 @@
 This is an **auto-generated reference index** of every slash command shipped
 under `.agents/workflows/` (top-level only — `helpers/` are path-included
 modules, not runnable commands). The canonical workflow narrative lives in
-[`SDLC.md`](SDLC.md) — read that first to understand how the commands
+[`SDLC.md`](https://github.com/dsj1984/mandrel/blob/main/docs/SDLC.md) — read that first to understand how the commands
 compose. This file is only for "which command does X?" lookups.
 
 Every command file lives at `.agents/workflows/<name>.md` and is projected
@@ -59,7 +59,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
 | `/mandrel-deliver` | Unified delivery entry point. Takes Story ids or a plain-language prompt, derives which path the work belongs on, and lands it via the single deliver-story engine — story-<id> → PR → main. |
 | `/mandrel-plan` | Unified planning entry point. Interrogate → author → persist. Emits one Story by default; splits into N>1 only under the default-single split policy. |
-| `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the stabilized quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
+| `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the stabilized quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the dependency bump the CLI's closing report describes. |
 | `/memory-consolidate` | Attended consolidation pass over this project's agent memory pool — merge duplicates, verify claims against the current tree, prune with operator confirmation, rewrite the index, and stamp the pool with the date and entry count the /mandrel-plan advisory measures its next nudge against. |
 | `/prototype` | Operator-invoked UI prototype pass. Discovers the consumer's design-system SSOT first, then — only after the operator confirms — writes exactly one self-contained HTML file under the gitignored workspace-root temp tree, so a layout can be reviewed before its UI acceptance criteria are authored. |
 | `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /mandrel-plan. |

package/.agents/instructions.md

@@ -63,9 +63,7 @@ shapes, commit subjects, push/hygiene MUSTs) — and an **on-demand set**,
 read **before** the matching work (each opens with a one-line "applies
 when…" scope header): `git-conventions-reference.md`,
 `testing-standards.md`, `ci-remediation.md`, `api-conventions.md`,
-`gherkin-standards.md`; plus `orchestration-error-handling.md`,
-`known-tooling-behavior.md`, `test-seams.md`
-(**mandrel contributors only** — consumers skip). Read when unsure;
+`gherkin-standards.md`. Read when unsure;
 on-demand loading does not lower a rule's authority (§ 1.K).
 
 ### G. Structured Configuration
@@ -176,8 +174,7 @@ reference the Story via `(refs #<storyId>)`. There is no `type::task`.
 
 `type::epic` is a container only (goal + child checklist, no `agent::*`,
 never delivered): `/mandrel-plan` offers one above 2 Stories and
-`/mandrel-deliver <epicId>` expands it. Linkage is parent→child only, so
-an `Epic: #N` footer is still refused.
+`/mandrel-deliver <epicId>` expands it. Linkage is parent→child only.
 
 ---
 
@@ -195,6 +192,6 @@ anything under it.
 delivers and self-verifies in one pass** — a broad footprint is normal
 when the change is cohesive, and no plan-time ceiling scores it; do not
 re-slice it into per-module fragments. On an out-of-scope task: **plan
-first** (numbered cohesive sub-steps in a `<!-- DECOMPOSITION -->`
-block), **commit incrementally** per sub-step, and **fail fast** — STOP
-and report if any sub-step fails validation.
+first** in numbered cohesive sub-steps, **commit incrementally** per
+sub-step, and **fail fast** — STOP and report if any sub-step fails
+validation.

package/.agents/rules/ci-remediation.md

@@ -96,10 +96,14 @@ the `friction` comment and flips the Story in one call; then hand back to the
 operator, who owns the runner pool. Do not sit in a retry loop waiting for
 capacity to return.
 
-**Rerunning a failed job to reach green stays forbidden under every verdict,
-`capacity` and `unreproducible-tier` included.** The verdict changes who owns the fix and where it is
-filed; it never licenses a re-run, and it is not a route to a green bar. A
-capacity-blocked delivery ends `agent::blocked` — not merged.
+**A rerun is earned by the filing, never by the hope.** Rerunning a failed job
+to reach green is forbidden — with exactly one exception, and it is gated on
+evidence you have already committed to: once `file-ci-gap.js` has recorded a
+`capacity` or `unreproducible-tier` verdict for the **current head SHA**, you
+may rerun the failed job **once**. Reaching the verdict is not enough; the
+filing is what records the allowance, which is what makes the claim auditable.
+See § One rerun after a recorded verdict below. A capacity-blocked delivery
+that never reaches a filing ends `agent::blocked` — not merged.
 
 ### The `unreproducible-tier` verdict
 
@@ -129,10 +133,36 @@ before. On the verdict: run
 as `--evidence`; then hand back to the operator, who owns the sandbox. Do not author a fix for a tier you could not
 run — a blind fix to a suite nobody exercised is how the gap compounds.
 
+## One rerun after a recorded verdict
+
+`capacity` and `unreproducible-tier` name failures that are proven properties
+of the **environment**: no commit on the branch can move the head SHA to clear
+them, so the no-rerun rule used to strand a correct delivery until a human
+cleared it by hand. Those two verdicts — and only those two — now buy exactly
+one rerun:
+
+1. Reach the verdict with its required readings (§ above). A green on re-run is
+   never one of those readings.
+2. File it: `node .agents/scripts/file-ci-gap.js --story <id> --verdict
+   <capacity|unreproducible-tier> --owner <bucket> --evidence "<proof reading>"`.
+   The filing stamps a `rerunAllowance` on the CI digest, keyed to the head SHA
+   the red was observed on.
+3. Rerun the failed job **once**. The watcher's same-SHA guard admits that one
+   green, retires the digest and lets the delivery proceed.
+
+The allowance is spent when it is honoured — it dies with the digest — so a
+second red after the rerun writes a fresh digest carrying none, and is a real
+red that routes to **Option 1**. An allowance recorded against a different head
+SHA is not an allowance. `pre-existing` earns none: it reproduces on `main`, so
+it names a real defect someone owns and a rerun cannot remove it. Skipping,
+quarantining or loosening a test to reach green stays forbidden under every
+verdict, always.
+
 ## Verifier
 
-The check is resolved only when it is **green with zero reruns of the failed
-job**, and the diff carries **no `.skip` / `.only`, no quarantine, and no
+The check is resolved only when it is **green with no rerun of the failed job**
+— save the one a recorded `capacity` / `unreproducible-tier` verdict buys (§
+above) — and the diff carries **no `.skip` / `.only`, no quarantine, and no
 deleted or loosened assertion** introduced to reach green. You may **not**
 re-run a failed job to "see if it goes green," and you may **not** skip,
 `.only`, or quarantine a flaky test to get a green bar. Both mask the defect
@@ -146,8 +176,11 @@ first red the watcher **disarms native auto-merge** (a disarm failure is a
 blocker, not a warning) and records the PR **head SHA** in the digest
 alongside the failing check-run identity. On green it adjudicates:
 
-- **Same head SHA** → the green came from re-running the failed job. The
-  watcher exits non-zero, flips the Story to `agent::blocked` with a
+- **Same head SHA, with a recorded allowance** → the one rerun the section
+  above buys. The digest is retired (spending the allowance), auto-merge is
+  re-armed, and the delivery continues.
+- **Same head SHA, no allowance** → the green came from re-running the failed
+  job. The watcher exits non-zero, flips the Story to `agent::blocked` with a
   `friction` comment, and requires the CI-gap intake issue
   (`file-ci-gap.js` — run link and failure signature are already in the
   digest) before the delivery proceeds.

package/.agents/rules/gherkin-standards.md

@@ -148,3 +148,7 @@ authored:
 
 When a step is superseded, mark it deprecated and migrate every call site in
 the same PR; do not leave two near-identical steps live.
+
+When `qa.gherkinLint` is configured, `node .agents/scripts/check-gherkin-corpus.js`
+enforces this statically: every `.feature` must compile, and every active
+step must bind within its own scope.

package/.agents/schemas/acceptance-eval-verdict.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "acceptance-eval-verdict",
   "title": "Acceptance Self-Eval Verdict",
-  "description": "Structured output of one independent (fresh-context) acceptance self-eval round (Story #3819). Produced by the critic pass in the Story-implementation phase (helpers/deliver-story.md Step 1a), written under the gitignored temp tree, and consumed by acceptance-eval.js to enforce the bounded round cap and decide whether the Story proceeds to `closing`, redrafts, or escalates to `agent::blocked`. The author MUST NOT be the evaluator — the verdict is an independent judgment of the caller-injected change set against each inline acceptance[] item.",
+  "description": "Structured output of one acceptance self-eval round (Story #3819). One file per Story covering every inline acceptance[] item exactly once, authored by the round's single verdict owner — the inline self-eval under ceremonyProfile minimal/standard, a fresh-context maker-blind critic under strict (Story #5343) — in the Story-implementation phase (helpers/deliver-story.md Step 1a). Written under the gitignored temp tree and consumed by acceptance-eval.js, which enforces the bounded round cap and decides whether the Story proceeds to `closing`, redrafts, or escalates to `agent::blocked`. Whoever owns it scores the caller-injected change set afresh against each criterion, treating the implementation reasoning as untrusted; the gate is the scorer of that verdict, never a second pass over the criteria.",
   "type": "object",
   "required": ["storyId", "schemaVersion", "round", "criteria"],
   "properties": {