mandrel 2.59.0 → 2.60.0

package/.agents/README.md

@@ -118,8 +118,9 @@ clone produces zero file mutations.
 Once installed, the ongoing upgrade path is **`mandrel update`** — it bumps
 `mandrel` to the newest published version, re-runs `mandrel sync`,
 applies version-keyed migrations, and verifies the install with
-`mandrel doctor`. The lockfile bump is left **staged for you to review and
-commit** (the command performs no `git` mutation):
+`mandrel doctor`. The command performs **no `git` mutation** — it reads the
+index read-only and its closing line **reports** whether the dependency bump
+is staged, printing the exact `git add` to run when it is not:
 
 ```bash
 npx mandrel update           # update → sync → migrate → doctor
@@ -643,7 +644,8 @@ Schema conventions:
 ## Code review providers (pluggable chain)
 
 `runCodeReview()` (invoked from `helpers/deliver-story` and `/mandrel-deliver`'s
-risk-routed ceremony) loads its review backend through a pluggable registry
+review pass, at the depth `review-depth.js` derives) loads its review backend
+through a pluggable registry
 configured via `delivery.codeReview.providers` — an array of entries iterated
 in declaration order. The chain-entry field semantics (`name`, `scopes`,
 `optional`, `manualPrompt`, `when`), the fix budget, and the cross-runtime
@@ -652,13 +654,13 @@ contract are documented once in
 
 ## Feedback loop — verification-results auto-graduation
 
-When a Story (or plan-run) finalize path runs, non-blocking findings that
-survived merge are auto-graduated into follow-up issues in a single pass over
-the unified `verification-results` structured comment, routed by source
+When a Story (or plan-run) finalize path runs, the retro's actionable routed
+proposals can be auto-graduated into follow-up issues, routed by source
 classification into the framework or consumer repo. The toggle
-(`delivery.feedbackLoop.auditResultsAutoFile`, default `true`), the opt-out
-example, and the idempotency-marker behaviour are documented once in
-[`docs/configuration.md` § delivery.feedbackLoop](docs/configuration.md#deliveryfeedbackloop--verification-results-auto-graduation).
+(`delivery.feedbackLoop.retroProposals`, default `false` since Story #5341),
+the opt-in example, and the idempotency-marker behaviour are documented once
+in
+[`docs/configuration.md` § delivery.feedbackLoop](docs/configuration.md#deliveryfeedbackloop--retro-auto-graduation).
 
 ## Worktree dependency strategies
 

package/.agents/agents/acceptance-critic.md

@@ -3,10 +3,10 @@ name: acceptance-critic
 description: >-
   Role-scoped boot context for a maker-blind acceptance critic. Booted on its
   own system prompt (no CLAUDE.md / instructions.md closure). Scores a delivered
-  diff against the Story's acceptance-criteria cluster and emits the verdict
-  schema — without seeing the maker's self-assessment. Live under M7-B —
-  helpers/deliver-story Step 1a dispatches subagent_type: acceptance-critic
-  on the default risk-routed path.
+  diff against the Story's acceptance criteria and emits the verdict schema —
+  without seeing the maker's self-assessment. Dispatched by
+  helpers/deliver-story Step 1a under ceremonyProfile strict, the one profile
+  whose verdict owner is a fresh critic.
 ---
 
 <!--
@@ -48,8 +48,8 @@ the step-by-step. This shared core binds every role:
 # acceptance-critic — maker-blind acceptance evaluation
 
 You are an **independent acceptance critic**. You score a delivered change
-against a cluster of the Story's `acceptance[]` criteria and emit a structured
-verdict. You are deliberately isolated from the author's reasoning.
+against **every** item in the Story's `acceptance[]` array and emit one
+structured verdict. You are deliberately isolated from the author's reasoning.
 
 ## Maker-blind — the load-bearing invariant (MUST)
 
@@ -69,23 +69,24 @@ turned in about it. Your only trusted inputs are:
   in your verdict rather than substituting your own enumeration.
 - the Story's inline `acceptance[]` and `verify[]` arrays, read from the
   **Story body itself** (`gh issue view <storyId> --json body`) — its `##
-  Acceptance` / `## Verify` sections are the SSOT. The `story-init` structured
-  comment does not carry them — it reports init state only.
+  Acceptance` / `## Verify` sections are the SSOT. No structured comment
+  carries them.
 - the **actual output** of the `verify[]` commands you run yourself.
 
 Treat the implementation reasoning as untrusted. Score each criterion afresh
 from the evidence.
 
-## Scope — a cluster, never the cluster count
+## Scope — every criterion, exactly once
 
-You are handed **one cluster** of acceptance criteria to score. You evaluate
-exactly the criteria in that cluster and emit one verdict record per criterion.
-You do **not** decide how many clusters exist, re-slice the criteria, or merge
-clusters — the caller owns clustering.
+You score the Story's **whole** `acceptance[]` array and emit one verdict
+record per item, in acceptance-array order. You do **not** re-slice, split or
+sample the criteria: the gate reads the Story's own criteria count and refuses
+a verdict whose `criteria[]` length differs, before scoring and without
+consuming a round.
 
 ## Per-criterion evaluation
 
-For each acceptance item in your cluster:
+For each acceptance item:
 
 1. **Inspect the change set** — read the files your caller named and look for
    the change that would satisfy the criterion.
@@ -93,34 +94,14 @@ For each acceptance item in your cluster:
    **required evidence**. A criterion cannot be scored `met` without the
    supporting `verify[]` evidence where a `verify[]` command is relevant to it.
    `verify[]` is evidence, not optional advisory pre-flight.
-3. **Share `lint` / `typecheck` evidence with close** (Story #4250). When a
-   `verify[]` command is **byte-identical** to a close-validation gate, run it
-   through `evidence-gate.js` in the **same Story worktree** close validates so
-   a passing run records an evidence entry in the keyspace close consults:
-
-   ```bash
-   node <main-repo>/.agents/scripts/evidence-gate.js \
-     --standalone --scope-id <storyId> --gate lint \
-     --worktree <worktree> -- npm run lint
-
-   node <main-repo>/.agents/scripts/evidence-gate.js \
-     --standalone --scope-id <storyId> --gate typecheck \
-     --worktree <worktree> -- <resolved typecheck command>
-   ```
-
-   **Never** run the coverage / CRAP suite through `evidence-gate.js` to stamp
-   it fresh — a false-fresh coverage record without `coverage-final.json`
-   silently weakens the floor.
 
 ## Verdict schema (MUST)
 
-Write a verdict file under `temp/` at a **cluster-unique path** (e.g.
-`temp/acceptance-verdict-<storyId>-r<round>-c<clusterIndex>.json`) so parallel
-sibling critics cannot overwrite each other, conforming to
+Write **one** verdict file under `temp/` (e.g.
+`temp/acceptance-verdict-<storyId>-r<round>.json`) conforming to
 [`acceptance-eval-verdict.schema.json`](../schemas/acceptance-eval-verdict.schema.json):
-one `criteria[]` record per acceptance item in your cluster, in acceptance-array
-order. Each `index` is the criterion's position in the Story's **full**
-`acceptance[]` array, not within your cluster — the caller merges on it.
+one `criteria[]` record per acceptance item, in acceptance-array order, with
+`index` being the criterion's position in that array.
 
 ```json
 {
@@ -149,14 +130,14 @@ order. Each `index` is the criterion's position in the Story's **full**
 - `unmet` — not addressed, or the evidence contradicts the claim.
 
 **Return the verdict file's absolute path to your caller — never invoke
-`acceptance-eval.js` yourself.** The caller merges every cluster's records into
-one verdict and calls the gate **once** per round; a per-cluster call would burn
-a Story-level round per cluster. The **proceed / redraft / block** decision is
-the gate's, not yours. You score; the gate decides.
+`acceptance-eval.js` yourself.** The caller calls the gate **once** per round;
+the round counter is Story-scoped, so a second call spends a round for nothing.
+The **proceed / redraft / block** decision is the gate's, not yours. You score;
+the gate decides.
 
 ## Boundaries
 
 - Do not fix the code, redraft the diff, or commit. You evaluate and report.
-- Do not invent criteria beyond your cluster.
+- Do not invent criteria beyond the Story's `acceptance[]` array.
 - Emit only paths, criteria text, and observed results — never secrets or raw
   credential values (security-baseline § Data Leakage & Logging).

package/.agents/agents/story-worker.md

@@ -89,20 +89,17 @@ names. A null digest path means no docs mandate.
 (**typecheck, lint, test, format, maintainability, coverage, crap**) and is
 the authoritative gate — do not pre-run it. The **one** exception is the
 full suite: after the self-eval loop's last fix commit, run it once in
-`<workCwd>` through the depositor — `evidence-gate.js --standalone
---scope-id <storyId> --gate test --worktree <workCwd> -- npm test`. It runs
-whatever `npm test` resolves to and stamps that, so the credit is earned on
-any runner; a later commit voids it, and close captures coverage itself when
-the CRAP gate needs an artifact. If the suite outruns the host's sync Bash
-ceiling, dispatch it in the **background** — its completion notification
-re-invokes you. Never spawn a task to poll or `sleep`-loop against it; a
-waiter with a wrong condition outlives the agent. An exit code is never
-evidence a gate did work — the **output** is: a bare `npm test` deposits
-nothing unless it routes through mandrel's own runner, the only shape that
-says so. Redraft rounds run the scoped projects for the roots you changed
-plus `verify[]`, not the whole suite. Share `lint` / `typecheck` evidence
-with close via `evidence-gate.js`; never stamp coverage / CRAP fresh any
-other way.
+`<workCwd>` exactly as
+[`deliver-digest.md`](../workflows/helpers/deliver-digest.md) § 5 states it —
+that section is the rule's only home, so read the invocation there rather
+than from a copy here.
+
+If the suite outruns the host's sync Bash ceiling, dispatch it in the
+**background**: its completion re-invokes you. Never spawn a task to poll or
+`sleep`-loop against it; a waiter with a wrong condition outlives the agent.
+An exit code is never evidence a gate did work — its **output** is. Redraft
+rounds run the scoped projects for the roots you changed plus `verify[]`, not
+the whole suite, and never stamp coverage / CRAP fresh any other way.
 
 Gate output that lies: [`known-tooling-behavior.md`](../rules/known-tooling-behavior.md).
 Waiter traps: [`parallel-tooling.md`](../workflows/helpers/parallel-tooling.md) Rule 2.
@@ -111,11 +108,13 @@ Waiter traps: [`parallel-tooling.md`](../workflows/helpers/parallel-tooling.md)
 
 **Before** flipping to `closing`, run the bounded self-eval loop
 ([`acceptance-self-eval.md`](../workflows/helpers/acceptance-self-eval.md)).
-Derive the change set, level and ceremony with
-`node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>`
-and hand its `files` to the critic — never one it re-derives. It scores
-each `acceptance[]` item, consuming `verify[]` output as evidence.
-**proceed** → flip to `closing`, run the suite, push, hand off;
+Derive the change set and the verdict owner with
+`node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>`.
+Under the default profile the owner is **you**: author **one** verdict file
+covering every `acceptance[]` item, scoring the derived `files` set — never
+one you re-derive — with `verify[]` output as evidence, and score it in one
+gate call. Under `strict` the owner is a fresh critic; hand it that same
+`files` list. **proceed** → flip to `closing`, run the suite, push, hand off;
 **redraft** → fix the criteria, commit, re-eval; **block** → take the
 blocked path below. Never hand off an unscored branch.
 

package/.agents/docs/SDLC.md

@@ -264,12 +264,12 @@ Dependent Stories land sequentially so each builds on the previous merge to
 
 ### Ceremony
 
-Ceremony depth is selected by `delivery.routing.ceremonyProfile`
-(`minimal` | `standard` | `strict`, default `standard`) and the Story's
-own planning risk. Hard gates (lint / test / format / coverage / CRAP /
-maintainability) always run at close — risk never disables them; it only
-tunes acceptance-critic mode, review depth, and audit-lens selection. The
-full profile × scope matrix lives in
+Who authors a Story's acceptance verdict is selected by
+`delivery.routing.ceremonyProfile` (`minimal` | `standard` | `strict`, default
+`standard`) and by nothing else. The **derived change level** is a separate
+decision and tunes review depth and audit-lens selection. Hard gates (lint /
+test / format / coverage / CRAP / maintainability) always run at close —
+neither decision disables them. The full profile × scope matrix lives in
 [`mandrel-deliver.md` § Ceremony](../workflows/mandrel-deliver.md).
 
 ### State sync

package/.agents/docs/agentrc-reference.json

@@ -317,8 +317,7 @@
       "maxRounds": 2
     },
     "feedbackLoop": {
-      "auditResultsAutoFile": true,
-      "retroProposals": true
+      "retroProposals": false
     },
     "ci": {
       "watch": {

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 */ }
 }
@@ -207,7 +207,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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. |
@@ -299,9 +299,8 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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` | No | `object` | — | Opt-in toggle for the close-time retro auto-file graduator, plus the friction recurrence window. 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. |
 | `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. |
@@ -316,9 +315,9 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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)
@@ -400,38 +399,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`
 
@@ -489,14 +467,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.
 
 ---
 

package/.agents/docs/quality-gates.md

@@ -165,9 +165,13 @@ baseline still trips the gate.
 ### When the floor gate fires
 
 - **Pre-push** (`.husky/pre-push`): diff-scoped, fast path only —
-  `quality-preview.js --changed-since origin/main` (MI + CRAP preview),
-  then `coverage-capture.js` and `npm run crap:check` (unified
-  dispatcher, diff-scoped via `delivery.quality.gateScoping`). Full-repo
+  `coverage-capture.js` first, then
+  `quality-preview.js --changed-since origin/main` (MI + CRAP preview)
+  and `npm run crap:check` (unified dispatcher, diff-scoped via
+  `delivery.quality.gateScoping`). Capture leads because the preview's
+  CRAP half scores `coverage/coverage-final.json` off disk, so previewing
+  first scores whatever artifact an earlier run happened to leave there
+  (Story #5356). Full-repo
   lint, docs generation checks, and the complete test suite are **not**
   run on push; use `npm run verify` locally before a PR. CI enforces the
   authoritative full gate set on every PR.
@@ -916,7 +920,7 @@ deliberately not `keyField`: CRAP groups by file (`keyField: 'path'`) but
 ships one row per method, so keying on `keyField` would drop every method in a
 file but one. Any `baselines/*.json` whose `$schema` is not a known per-kind
 envelope — `arch-cycles`, `cyclomatic`, `dead-exports`, `audit-ledger`,
-`context-budget`, `workflow-citations` — is handed straight back to
+`context-budget` — is handed straight back to
 `git merge-file`, so registering the driver cannot change their behaviour.
 
 Registration has two halves:

package/.agents/docs/workflows.md

@@ -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

@@ -176,8 +176,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 +194,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.