mandrel 2.31.0 → 2.32.0

package/.agents/workflows/audit-documentation.md

@@ -7,10 +7,10 @@ description: Audit the repository's main documentation for staleness, semantic d
 You are a Staff Engineer & Documentation Steward verifying the repository's prose
 documentation is **up to date and complete**. Prose rots silently: commands get
 renamed, scripts move, workflows change shape, version/topology claims go stale.
-The deterministic gates (`check-doc-links.js`, `check-lifecycle-doc-drift.js`,
-`validate-docs-freshness.js`) catch broken links, generator drift, and
-per-delivery freshness — they cannot tell whether the prose still describes how
-the code actually behaves. That semantic verification is this lens's job. The
+The deterministic gates (`check-doc-links.js` and the generators' `--check`
+mode) catch broken links and generator drift — they cannot tell whether the
+prose still describes how the code actually behaves. That semantic
+verification is this lens's job. The
 shared lens machinery — read-only constraint, scope interpretation, report
 envelope + finding-block skeleton, severity scale, self-cross-check, and
 execution strategy — lives in
@@ -78,7 +78,6 @@ are cheap, exact, and de-duplicate the easy findings:
 
 ```bash
 node .agents/scripts/check-doc-links.js
-node .agents/scripts/check-lifecycle-doc-drift.js
 node .agents/scripts/generate-config-docs.js --check
 node .agents/scripts/generate-lifecycle-docs.js --check
 node .agents/scripts/generate-workflows-doc.js --check
@@ -87,7 +86,7 @@ node .agents/scripts/resolve-doc-tiers.js --json
 
 Fold the results in as findings:
 
-- **Checker failures** (broken links, lifecycle drift) become individual
+- **Checker failures** (broken links, generator drift) become individual
   findings with `Category: Link Integrity` (or `Generator Drift` for the
   lifecycle gate), citing the checker output verbatim.
 - **Generator dirtiness** (any `--check` reporting stale output, including

package/.agents/workflows/audit-to-stories.md

@@ -227,8 +227,8 @@ runs FIRST and widens the net across open + closed issues; the exact
 was reworded but whose *location* is unchanged still confirms against the Issue
 that already tracks that location, because the audit filers stamp a
 location-based `audit-semantic-keys` footer alongside the `audit-fingerprints`
-footer. Close-time filings from the
-[`audit-results-graduator`](../scripts/lib/feedback-loop/audit-results-graduator.js)
+footer. Filings from the
+[`retro-proposals-graduator`](../scripts/lib/feedback-loop/retro-proposals-graduator.js)
 carry the same canonical `audit-fingerprints` footer, so a sweep recognizes a
 graduator-filed issue and never re-files it.
 

package/.agents/workflows/helpers/audit-lens-core.md

@@ -229,18 +229,17 @@ which path produced it.
 > stage before synthesising the report. It derives its per-dimension prompts
 > from the *lens* markdown at run time — the lens stays the single source of
 > truth. This is a performance optimization over path 1, **not** a separate
-> contract: strategy selection lives in
-> [`../../scripts/lib/dynamic-workflow/capability.js`](../../scripts/lib/dynamic-workflow/capability.js)
-> (`selectAuditStrategy`), and it is not covered by the No-Shim / hard-cutover
-> rule in [`../../rules/git-conventions.md`](../../rules/git-conventions.md)
-> because there is one report contract and only the execution strategy varies —
-> the same capability-degradation pattern the protocol endorses for live-docs
-> fallback. Force a path for testing with `MANDREL_AUDIT_STRATEGY=sequential`
-> or `MANDREL_AUDIT_STRATEGY=orchestrated`; exercise the real disable signals
-> with `CLAUDE_CODE_DISABLE_WORKFLOWS=1` or `disableWorkflows: true` in
-> `.claude/settings.json`. On the orchestrated path the analysis subagents are
-> granted only read/search tools (`Read`, `Grep`, `Glob`) — the single write is
-> the final report artifact.
+> contract, and it is not covered by the No-Shim / hard-cutover rule in
+> [`../../rules/git-conventions.md`](../../rules/git-conventions.md) because
+> there is one report contract and only the execution strategy varies — the
+> same capability-degradation pattern the protocol endorses for live-docs
+> fallback. **The host owns the choice.** Mandrel ships no in-repo strategy
+> selector and no force-override env var: Claude Code launches the saved
+> workflow when it can, and you get path 1 or 2 above when it cannot.
+> Suppress the orchestrated path with `CLAUDE_CODE_DISABLE_WORKFLOWS=1`
+> or `disableWorkflows: true` in `.claude/settings.json`. On the orchestrated
+> path the analysis subagents are granted only read/search tools (`Read`,
+> `Grep`, `Glob`) — the single write is the final report artifact.
 
 ## Parallel tooling {#parallel-tooling}
 

package/.agents/workflows/helpers/code-quality-guardrails.md

@@ -95,17 +95,18 @@ suppress the noise.
 
 ## When a number changes
 
-Update three places **in the same commit**:
-
-1. `delivery.quality.codingGuardrails.<key>` in
-   [`agentrc-reference.json`](../../docs/agentrc-reference.json).
-2. The matching schema bound in
-   [`schemas/agentrc.schema.json`](../../schemas/agentrc.schema.json) and the
-   AJV mirror in
-   [`scripts/lib/config-settings-schema.js`](../../scripts/lib/config-settings-schema.js).
-3. The threshold cell or sentence in this helper.
-
-The drift test (`tests/config-schema-mirror-drift.test.js`) catches schema
-divergence between the JSON mirror and the AJV runtime; the helper-prose
-drift is caught by `audit-clean-code` and `agent-protocol` linking back here
-rather than restating the numbers.
+Update two places **in the same commit**:
+
+1. `CODING_GUARDRAILS_DEFAULTS` in
+   [`scripts/lib/config/quality.js`](../../scripts/lib/config/quality.js).
+   The schema literal in
+   [`config-settings-schema-quality.js`](../../scripts/lib/config-settings-schema-quality.js)
+   imports it, and `npm run docs:gen` propagates the number into
+   [`agentrc-reference.json`](../../docs/agentrc-reference.json), the shipped
+   JSON-Schema mirror, and the `configuration.md` key table.
+2. The threshold cell or sentence in this helper.
+
+The generator-fidelity test (`tests/config-schema-mirror-drift.test.js`)
+catches a stale generated artifact; the helper-prose drift is caught by
+`audit-clean-code` and `agent-protocol` linking back here rather than
+restating the numbers.

package/.agents/workflows/helpers/code-review.md

@@ -293,14 +293,9 @@ For every finding, provide:
 
 Findings that Step 4.5 remediated on `[HEAD_REF]` MUST be rendered under a
 dedicated **`## Fixed on-branch`** heading, **not** in the severity groups
-above. This is the contract seam that keeps remediated findings from
-spawning ghost follow-up issues: the
-[audit-results graduator](../../scripts/lib/feedback-loop/audit-results-graduator.js)
-(the sole canonical reader of the unified comment)
-skips every entry inside this section (both because a fixed entry is
-rendered with a **✅ prefix** — so it carries no leading severity emoji the
-parser would match — and because the parser has an explicit
-Fixed-on-branch section guard).
+above. This keeps a remediated finding legible as remediated to every reader
+of the unified comment — human or downstream — rather than reading as an
+outstanding severity-grouped finding.
 
 Render each fixed finding as a `✅`-prefixed line naming its original
 severity, the file path in backticks, and the remediating commit SHA, e.g.:

package/.agents/workflows/helpers/deliver-reference.md

@@ -118,7 +118,8 @@ engine runs, never what runs — gates, PR, and terminal envelope are identical.
 **Read the mode; never infer it from shape.** Before spawning
 anything, read the Story's `dispatchMode` from the resolver envelope
 (`stories[].dispatchMode`, produced by `resolveStoryDispatchMode` in
-`lib/orchestration/complexity-gate.js`). A Story with `dispatchMode: "inline"`
+`lib/orchestration/complexity-gate.js`, which decides on the resolved set size
+alone — it does not read the Story body). A Story with `dispatchMode: "inline"`
 executes [`deliver-story.md`](deliver-story.md) **inline in this session** — no
 `story-worker` sub-agent boot and no fresh acceptance-critic sub-agents
 (sub-agent boots are the dominant deliver-phase token cost at trivial scope) —

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -139,19 +139,18 @@ and the `rules/security-baseline.md` MUSTs all run exactly as for a
 full-ceremony Story. The lite route's `preserves` field is the machine-readable
 record of those non-negotiables; there is no lite-specific gate bypass.
 
-**Deliver derives the route from the Story body's shape — and the
-dispatch mode from the run.** Persist stamps a lite cohort's Stories with the
-`route::lite` label as a _human-visible hint only_ (and ledgers the authored
-verdict — recorded reason plus per-Story shape evidence — on the
-`story-plan-state` checkpoint); the label is never the control signal.
-`/deliver` computes the route from the fetched Story body via
-`resolveStoryDispatchMode` (`lib/orchestration/complexity-gate.js`) — the same
-shape taxonomy `deriveChangeLevel` applies to the landed diff at close:
-`changes[]` count, acceptance count, creates-vs-refactors mix, sensitive-path
-classes. A footprint intersecting a sensitive-path class derives `full` —
-sensitivity wins, and the Story keeps its fresh acceptance critic.
-
-That derived route sets ceremony. It does **not** set the dispatch mode,
+**Ceremony comes from the landed diff; the dispatch mode comes from the
+run.** Persist stamps a lite cohort's Stories with the `route::lite` label as a
+_human-visible hint only_ (and ledgers the authored verdict — recorded reason
+plus per-Story shape evidence — on the `story-plan-state` checkpoint); the
+label is never the control signal. Ceremony is resolved from the **derived
+change level** (`deriveChangeLevel` over the computed change set — digest § 3),
+not from a body-shape read: a footprint intersecting a sensitive-path class
+derives `high`, so the Story keeps its fresh acceptance critic. The light path
+is the one caller that reads the authored body's shape, through
+`deriveStoryShape` (`lib/orchestration/complexity-gate.js`).
+
+That derived level sets ceremony. It does **not** set the dispatch mode,
 because `inline` names one indivisible resource — the router's own session —
 and only run topology can say whether it is free: a **single-Story run**
 executes inline, and every Story of a multi-Story run dispatches as a
@@ -200,8 +199,8 @@ critic (the redundant pre-pass buys no measurable quality and roughly
 triples the acceptance-block cost). `acceptance-eval.js` is the
 deterministic **scorer** of that one authored verdict — schema validation,
 round cap, proceed / redraft / block — not an independent additional pass
-over the criteria. The M4-B floor holds: one verdict per cluster, the
-cluster count owned by `acceptance-clusters.js` alone.
+over the criteria. The M4-B floor holds: one verdict per cluster, with the
+cluster count owned by the dispatching caller and never by routing.
 
 **One round = N cluster critics → ONE merged verdict → ONE gate call.** The
 clusters are how a round is _authored_; they are not how it is _scored_.
@@ -279,7 +278,9 @@ floor forces `fresh`). Review depth reads the same derived level via
 `review-depth.js` inside close, so the two decisions cannot disagree.
 
 **Inline-dispatch override.** When the Story dispatches
-`inline` (`resolveStoryDispatchMode` → `inline`, i.e. a single-Story run), run
+`inline` (`resolveStoryDispatchMode` → `inline`, which is exactly a
+single-Story run — the function reads the resolved set size and nothing
+else), run
 every acceptance critic **inline** — do not spawn fresh-context critic
 sub-agents regardless of what the profile would otherwise resolve. The self-eval rigor
 (scoring each `acceptance[]` item against the one computed change set, with
@@ -393,6 +394,16 @@ judgment that help text cannot carry.
   wants the PR left at `agent::closing` for a human land (or a wrapper that
   will invoke `single-story-confirm-merge.js` itself). Reports `pending` —
   the work is not done, nothing is broken, and one named command finishes it.
+- `--override-review-block "<reason>"` — when the Story-scope review's
+  **critical** blocker is one you have read and judged wrong (a false positive,
+  or a finding the ratchet correctly exempts). It is the only sanctioned way
+  past that halt: reach for it instead of merging the PR by hand, because a
+  hand-merge bypasses the gate and records nothing. The reason is mandatory and
+  is written to three places (Story comment, PR comment, a
+  `review-block-overridden` friction signal), and the terminal envelope reports
+  `gates.codeReview: "overridden"` rather than `"passed"`. If you find yourself
+  reaching for it twice for the same shape of finding, the gate is
+  miscalibrated — fix the gate, not the run.
 - `--max-wait-seconds <n>` — from a headless caller with no host
   tool-invocation ceiling, to keep single-block semantics
   without editing the consumer's config.

package/.agents/workflows/helpers/worktree-lifecycle.md

@@ -116,8 +116,7 @@ PowerShell `Get-CimInstance Win32_Process`, terminating them with
 - The close output reports `pending-cleanup persistent-lock: story-N, ...`.
 - `git worktree list` shows `.worktrees/story-N/` for a closed Story.
 - `npm run lint` fails because of a nested `biome.json` in a half-reaped
-  worktree. The `worktree-residue-biome` self-healing check detects this
-  failure mode.
+  worktree.
 
 ### Manual usage
 

package/.agents/workflows/mandrel-update.md

@@ -150,22 +150,22 @@ in Step 5). Full procedure:
 node .agents/scripts/apply-quality-bootstrap.js
 ```
 
-Runs the same idempotent installs the quality-gates phase of
-[`bootstrap.js`](../scripts/bootstrap.js) uses — `applyQualityBootstrap`
-then `migrateBaselinesLayout` — and prints a `{ quality, baselines }` JSON
-envelope. The four quality-bootstrap outcomes: **helper** (materialize
+Runs the same idempotent install the quality-gates phase of
+[`bootstrap.js`](../scripts/bootstrap.js) uses — `applyQualityBootstrap` —
+and prints a `{ quality }` JSON envelope. The five quality-bootstrap
+outcomes: **helper** (materialize
 [`code-quality-guardrails.md`](helpers/code-quality-guardrails.md)),
 **hook** (install the `.husky/pre-commit` diff-scoped `quality:preview`
 invocation — a pre-existing **custom hook is never overwritten silently**;
 the action is `custom-hook-skip` and the helper returns the snippet to
 append by hand), **scripts** (backfill `quality:preview` /
 `quality:watch` only when absent), **config** (seed missing
-`delivery.quality.*` defaults — operator overrides survive). The baselines
-step migrates legacy per-Epic snapshot layouts into the ephemeral
-`temp/epic/<id>/baselines/` namespace when upgrading from pre-v2 shapes; the
-main-tracked root baselines are never touched. A second run reports
-`no-change` on every path — the idempotence contract this workflow
-requires.
+`delivery.quality.*` defaults — operator overrides survive), and
+**legacyBaselines** (`git rm` a committed pre-v2 `baselines/epic/` tree —
+the Story-only v2 model retired every reader of those per-Epic snapshots;
+the main-tracked root baselines are never touched). A second run reports
+`no-change` / `already-present` / `absent` on every path — the idempotence
+contract this workflow requires.
 
 ## Step 3.6 — Refresh the harness permission allowlist
 

package/.agents/workflows/qa-assist.md

@@ -172,27 +172,21 @@ every decision to the shared helpers; never re-derive them in prose.
      surfaces it touches, the **options**, and a brief **recommendation** with
      trade-offs. Still pin the relevant `file:line` anchor(s) where the change
      would land.
-3. **Hydrate the QA context** to locate code precisely, via
-   [`qa-context-hydrator.js`](../scripts/lib/qa/qa-context-hydrator.js) — it
-   resolves the source ticket body, the feature-file set, the surface map, and
-   recent git log:
-
-   ```js
-   import { hydrateQaContext } from '../scripts/lib/qa/qa-context-hydrator.js';
-   const context = await hydrateQaContext({ ticketNumber, githubPort, gitPort, surfaceMap });
-   ```
-
+3. **Locate the code.** Read the source ticket with
+   `gh issue view <ticketNumber> --json title,body,labels`, and verify each
+   surface-map path resolves with `git cat-file -e HEAD:<path>` — flag every
+   miss rather than citing a path that does not exist.
 4. **Compute the coverage verdict** for the surface the observation points at,
    via [`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js) — the
    deterministic seam behind the
    [`core/qa-coverage-mapping`](../skills/core/qa-coverage-mapping/SKILL.md)
    skill. Read that skill for how to assemble the `surface` input and read the
-   per-tier `{present|absent}` verdict. Optionally render a human-readable
-   summary via [`coverage-report.js`](../scripts/lib/qa/coverage-report.js).
-5. **Propose the missing test** (if any) from that verdict, via
-   [`propose-missing-test.js`](../scripts/lib/qa/propose-missing-test.js) — it
-   names the lowest absent tier, or returns `null` when every tier is covered.
-   Record its `description` as the ledger item's `missingTest`.
+   per-tier `{present|absent}` verdict.
+5. **Name the missing test** (if any) from that verdict: take the lowest tier
+   the verdict marks `absent` (unit → contract → acceptance) and write one
+   concrete sentence describing the test that would close it. Every tier
+   `present` means no missing test. Record that sentence as the ledger item's
+   `missingTest`.
 6. **Classify** the finding via
    [`classify-finding.js`](../scripts/lib/findings/classify-finding.js) so the
    tentative `class` resolves to the correct focus/meta label set. The helper
@@ -273,10 +267,11 @@ the `/qa-assist`-specific deltas are:
 - **Persistent, resumable rolling session** — `/qa-assist` defaults to resuming
   the same session and appending; a reused session carries the untriaged backlog
   forward and never overwrites a prior ledger.
-- **Enrichment helpers are deterministic** — context hydration
-  ([`qa-context-hydrator.js`](../scripts/lib/qa/qa-context-hydrator.js)),
-  coverage verdict/report, missing-test, and classification are never re-derived
-  in prose.
+- **Enrichment delegates where a helper exists** — the coverage verdict and
+  the finding classification come from their deterministic helpers, never from
+  prose. Context lookup and the missing-test sentence are the model's own work:
+  they are judgments, not computations, and routing them through a module only
+  bought a round-trip.
 
 ## See also
 

package/.agents/workflows/qa-explore.md

@@ -176,10 +176,11 @@ For each observation the agent makes while driving:
    [`core/qa-coverage-mapping`](../skills/core/qa-coverage-mapping/SKILL.md)
    skill. Read that skill for how to assemble the `surface` input and read the
    per-tier `{present|absent}` verdict.
-3. **Propose the missing test** (if any) from that verdict, via
-   [`propose-missing-test.js`](../scripts/lib/qa/propose-missing-test.js) — it
-   names the lowest absent tier, or returns `null` when every tier is covered.
-   Record its `description` as the ledger item's `missingTest` (or `null`).
+3. **Name the missing test** (if any) from that verdict: take the lowest tier
+   the verdict marks `absent` (unit → contract → acceptance) and write one
+   concrete sentence describing the test that would close it. Every tier
+   `present` means no missing test. Record that sentence as the ledger item's
+   `missingTest` (or `null`).
 4. **Append a `QaLedgerItem`** to the ledger (shape per
    [`helpers/qa-core.md`](helpers/qa-core.md)): a stable `id`, the redacted
    `evidence`, the `coverage` label (the `surface`, or `unknown`), a tentative
@@ -230,10 +231,10 @@ the `/qa-explore`-specific deltas are:
   and fall back to static.
 - **Broken navigation is a finding, not a workaround** — never URL-jump around a
   missing affordance, a nav 404, or a guard redirect loop.
-- **Delegate coverage decisions to the helpers.** Coverage verdict
-  ([`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js)) and
-  missing-test ([`propose-missing-test.js`](../scripts/lib/qa/propose-missing-test.js))
-  are deterministic — never re-derive them in prose.
+- **Delegate the coverage verdict to the helper.** Tier placement comes from
+  [`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js) — deterministic,
+  never re-derived in prose. The missing-test sentence is yours to write from
+  that verdict's lowest `absent` tier.
 
 ## See also
 

package/README.md

@@ -87,7 +87,7 @@ time to confirm the install is healthy.
 > Prefer a surgical alternative? Replace `shamefully-hoist` with a scoped
 > `public-hoist-pattern[]=` line per package listed in
 > `.agents/runtime-deps.json` (`ajv`, `ajv-formats`, `js-yaml`, `minimatch`,
-> `picomatch`, `string-argv`, `typhonjs-escomplex`). If `mandrel doctor`
+> `picomatch`, `typhonjs-escomplex`). If `mandrel doctor`
 > reports `runtime-deps missing: …`, this is the fix.
 
 `bootstrap.js` is interactive on a TTY and auto-accepts the

package/docs/CHANGELOG.md

@@ -15,6 +15,48 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.32.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.31.0...mandrel-v2.32.0) (2026-08-06)
+
+
+### ⚠ BREAKING CHANGES
+
+* `.agents/scripts/validate-docs-freshness.js` is removed from the published payload. It had no invoker in `package.json` scripts, Husky hooks, CI workflows, or any workflow markdown, so no shipped flow loses a step. A consumer calling it by hand should drop the call; the `delivery.docsFreshness.paths` key it read is unchanged and is still consumed by the audit-documentation lens.
+* `project.commands.lintBaseline` is removed from the `.agentrc.json` schema. The `project.commands` block is `additionalProperties: false`, so a config still carrying the key now fails validation instead of being ignored. `npx mandrel update` deletes it for you; delete it by hand otherwise. Nothing replaces it — the framework no longer ships a lint-baseline capture CLI, and a consumer that wants the `lint` baseline kind writes `baselines/lint.json` from its own linter.
+* `ITicketingProvider` no longer declares `getRecentComments`, `addSubIssue`, `removeSubIssue` or `createPullRequest`, and `GitHubProvider` no longer installs them. A consumer implementing or calling those members must drop them: open pull requests with `gh pr create` (as `single-story-close.js` does) and read a ticket's comments through `getTicketComments`.
+* `apply-quality-bootstrap.js` no longer prints a `baselines` key. Its stdout envelope is now `{ quality }`, and the retired baselines migration is reported as `quality.legacyBaselines` instead. A consumer parsing `.baselines.action` from `/mandrel-update` Step 3.5 must read `.quality.legacyBaselines.action` (`absent` | `pruned`); the pre-v2 snapshot relocation into `temp/epic/<id>/baselines/` no longer happens at all.
+* the delivery.lease config block (delivery.lease.ttlMs) is removed from .agentrc.json. The schema now rejects it as an unknown key, so a consumer carrying it must delete the block. Nothing replaces it: the lease has no TTL, and a stranded claim is cleared with --steal.
+* `delivery.acceptanceEval.clusterCeiling` is removed from the agentrc schema. The block is `additionalProperties: false`, so a consumer `.agentrc.json` still carrying the key now fails AJV validation — delete the key; nothing read it.
+
+### Added
+
+* baseline honesty surface: framework-owned scope/staleness gate + measurement-free orphan pruner ([#5012](https://github.com/dsj1984/mandrel/issues/5012)) ([#5016](https://github.com/dsj1984/mandrel/issues/5016)) ([71f7134](https://github.com/dsj1984/mandrel/commit/71f713419bba8523ab6bbca60fb962d5919f18b1))
+* **baselines:** baseline-refresh: schedule the full-scope re-score ([#5028](https://github.com/dsj1984/mandrel/issues/5028)) ([eee9005](https://github.com/dsj1984/mandrel/commit/eee9005933a572f69ac3faa94bfc1d7193dfd7d4))
+* **gates:** make the dead-exports ratchet detect whole-file death (refs [#5001](https://github.com/dsj1984/mandrel/issues/5001)) ([#5014](https://github.com/dsj1984/mandrel/issues/5014)) ([38dfc3c](https://github.com/dsj1984/mandrel/commit/38dfc3c690c14c80b0fd2dc97dd7cbd599a19322))
+* one child-process exec wrapper: single maxBuffer SSOT, normalized errors, lint-banned raw spawns ([#5009](https://github.com/dsj1984/mandrel/issues/5009)) ([#5029](https://github.com/dsj1984/mandrel/issues/5029)) ([956dcfc](https://github.com/dsj1984/mandrel/commit/956dcfc777fe74b2c35e208ee1a44ee7a47a3fd1))
+* planning surface diet: delete the parallel authoring pipeline and stop rejecting output the validator can already fix ([#5005](https://github.com/dsj1984/mandrel/issues/5005)) ([#5020](https://github.com/dsj1984/mandrel/issues/5020)) ([a62efd5](https://github.com/dsj1984/mandrel/commit/a62efd5d27f9d82761f150a5edd0388eb0370493))
+* **quality:** derive knip's CLI entry list instead of trusting memory ([#5026](https://github.com/dsj1984/mandrel/issues/5026)) ([7554851](https://github.com/dsj1984/mandrel/commit/7554851979de86622baf58f2467b5198d3202ed9))
+* ship a fail-closed dead-exports baseline producer so the ratchet has an updater, not a hand-edit ([#5011](https://github.com/dsj1984/mandrel/issues/5011)) ([#5033](https://github.com/dsj1984/mandrel/issues/5033)) ([eede007](https://github.com/dsj1984/mandrel/commit/eede007c502fab485de480c2517516f8e015491d))
+* ship a static gherkin corpus gate: must-compile with the real parser, must-bind scoped per step root ([#5013](https://github.com/dsj1984/mandrel/issues/5013)) ([#5034](https://github.com/dsj1984/mandrel/issues/5034)) ([9f4e83e](https://github.com/dsj1984/mandrel/commit/9f4e83ede2c7a55a6dd94e2d8b162e54fb4de217))
+
+
+### Fixed
+
+* close six defects found reviewing the v2.32.0 release diff ([#5035](https://github.com/dsj1984/mandrel/issues/5035)) ([625004c](https://github.com/dsj1984/mandrel/commit/625004ccc65a65508ef99b239ddd09fafb13c56f))
+* **close:** review lens must honour maintainability ignoreGlobs; add a logged override ([#5030](https://github.com/dsj1984/mandrel/issues/5030)) ([e21ff82](https://github.com/dsj1984/mandrel/commit/e21ff82b8ee80c80a9d3ff7803247c992f0a3abc))
+* derive the squash subject from release impact, keep acronyms, propagate breaking changes ([#5027](https://github.com/dsj1984/mandrel/issues/5027)) ([a7bb9af](https://github.com/dsj1984/mandrel/commit/a7bb9af0353853c60ac6a2b59ea04b7c66695dbc))
+
+
+### Changed
+
+* cRAP surface diet: delete the dead combined scan, unify the baseline read path, stop the c≈5 cap on untestable CLI wiring ([#5002](https://github.com/dsj1984/mandrel/issues/5002)) ([#5017](https://github.com/dsj1984/mandrel/issues/5017)) ([7624c12](https://github.com/dsj1984/mandrel/commit/7624c125f974cce0820d494b63efad6e56b9beae))
+* delivery/orchestration sweep: retire Epic-era close residue and collapse self-documented-unreachable machinery ([#5006](https://github.com/dsj1984/mandrel/issues/5006)) ([#5021](https://github.com/dsj1984/mandrel/issues/5021)) ([7c19dc5](https://github.com/dsj1984/mandrel/commit/7c19dc5d449f4a9926a7b59c9c9f0dbadf92e091))
+* **orchestration:** delete production-dead story-lifecycle module ([#5025](https://github.com/dsj1984/mandrel/issues/5025)) ([811966c](https://github.com/dsj1984/mandrel/commit/811966c0e1d0f2a746261e342f64acfe1b6f6bd5))
+* providers/QA/misc sweep: prune Epic-era provider surface, dead subsystems, and QA round-trip ceremony ([#5008](https://github.com/dsj1984/mandrel/issues/5008)) ([#5023](https://github.com/dsj1984/mandrel/issues/5023)) ([a019c14](https://github.com/dsj1984/mandrel/commit/a019c144149b23b7102fcd39e466842a3880cfa2))
+* remove the write-only observability surface: tool-trace hooks, dead signals viewer, Epic-era graduator ([#5003](https://github.com/dsj1984/mandrel/issues/5003)) ([#5018](https://github.com/dsj1984/mandrel/issues/5018)) ([3a6273f](https://github.com/dsj1984/mandrel/commit/3a6273f3dc78796ac89a62c1fefa0d95200bac8e))
+* retire the orphaned lifecycle-bus stratum: bus, both observers, the emitter-less schemas, and the doc-drift guard behind them ([#5024](https://github.com/dsj1984/mandrel/issues/5024)) ([#5032](https://github.com/dsj1984/mandrel/issues/5032)) ([caed250](https://github.com/dsj1984/mandrel/commit/caed2501520ce292832b99f12a5478350954c8b9))
+* rules refresh: retire the phantom docs-freshness gate, demote §1.H, condense testing pedagogy ([#5010](https://github.com/dsj1984/mandrel/issues/5010)) ([#5031](https://github.com/dsj1984/mandrel/issues/5031)) ([18715c4](https://github.com/dsj1984/mandrel/commit/18715c4a13448b0992ad8b005193414a0fcf493f))
+* single-source the config surface and finish the bootstrap vestige cleanup ([#5007](https://github.com/dsj1984/mandrel/issues/5007)) ([#5022](https://github.com/dsj1984/mandrel/issues/5022)) ([073415e](https://github.com/dsj1984/mandrel/commit/073415ebbefb2b5d4df05e3e52bbd4b11cf73120))
+
 ## [2.31.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.30.0...mandrel-v2.31.0) (2026-08-05)
 
 

package/lib/migrations/index.js

@@ -57,6 +57,7 @@ import { retireVerifyConcurrencyCap } from './steps/2.1.0-retire-verify-concurre
 import { retireEpicAcTags } from './steps/2.2.0-retire-epic-ac-tags.js';
 import { retireMaxSeedWords } from './steps/2.11.0-retire-max-seed-words.js';
 import { retireCodebaseSnapshot } from './steps/2.20.0-retire-codebase-snapshot.js';
+import { retireLintBaselineCommand } from './steps/2.32.0-retire-lint-baseline-command.js';
 
 /**
  * Ordered registry of migration steps. MUST stay sorted ascending by
@@ -75,6 +76,7 @@ export const migrations = [
   retireEpicAcTags,
   retireMaxSeedWords,
   retireCodebaseSnapshot,
+  retireLintBaselineCommand,
 ];
 
 /**

package/lib/migrations/steps/2.32.0-retire-lint-baseline-command.js

@@ -0,0 +1,127 @@
+// lib/migrations/steps/2.32.0-retire-lint-baseline-command.js
+/**
+ * Story #5004 follow-up — strip the retired `project.commands.lintBaseline`
+ * key from a consumer's `.agentrc.json`.
+ *
+ * #5004 (PR #5019) deleted `lint-baseline.js` and
+ * `lib/orchestration/lint-baseline-service.js`: the CLI spawned the configured
+ * command and parsed ESLint-shaped JSON, a shape this repo's own `npm run
+ * lint` (Biome + markdownlint fan-out) never produced, and nothing invoked the
+ * service. The key left the runtime AJV schema, the published mirror,
+ * `.agentrc.json` and `agentrc-reference.json` in the same change.
+ *
+ * `project.commands` carries `additionalProperties: false`, so a consumer
+ * whose config still sets `lintBaseline` hits a hard validation failure on
+ * upgrade, not a warning. This step strips the key before that check runs —
+ * the same contract-cutover pattern as `2.11.0-retire-max-seed-words.js`.
+ *
+ * It sweeps **both** config surfaces. `config-resolver.js` deep-merges
+ * `.agentrc.local.json` over `.agentrc.json` and validates the result, so a
+ * key surviving in the operator's overlay fails exactly as a base one would.
+ * Sweeping only the base would report "nothing to migrate" and leave that
+ * consumer hard-broken with no self-service remedy — re-running
+ * `mandrel update` would keep reporting clean — while this commit's
+ * `BREAKING CHANGE:` footer promises the upgrade deletes the key for them.
+ *
+ * The `lint` baseline KIND survives for consumers whose own linter writes
+ * `baselines/lint.json`; only the framework-owned capture shell is gone, so
+ * nothing here touches the baseline file or the gate config.
+ *
+ * This step is also the carrier for the release note #5004 never emitted: its
+ * commit ships the `BREAKING CHANGE:` footer that the squash subject on `main`
+ * (`227e1af4`) lacks, and which release-please therefore could not surface.
+ * See `single-story-close/phases/conventional-subject.js` for the close-side
+ * fix that stops the next one being lost.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Both config surfaces the resolver reads. `.agentrc.local.json` is deep-merged
+ * over the base *before* the AJV gate runs
+ * (`.agents/scripts/lib/config-resolver.js`), so a `lintBaseline` surviving in
+ * the overlay fails validation exactly as one in the base would — and a step
+ * that swept only the base would leave that consumer hard-broken with no
+ * self-service remedy, since re-running `mandrel update` would keep reporting
+ * clean. The overlay is operator-owned and gitignored, which is why it is easy
+ * to forget and why the sweep has to name it explicitly.
+ */
+const AGENTRC_FILENAMES = Object.freeze([
+  '.agentrc.json',
+  '.agentrc.local.json',
+]);
+
+/**
+ * @param {unknown} ctx
+ * @param {string} filename
+ * @returns {string}
+ */
+function resolveAgentrcPath(ctx, filename) {
+  const projectRoot = ctx?.projectRoot ?? process.cwd();
+  return path.join(projectRoot, filename);
+}
+
+/**
+ * @param {unknown} ctx
+ * @param {typeof nodeFs} fsImpl
+ * @param {string} filename
+ * @returns {object | null}
+ */
+function readAgentrcConfig(ctx, fsImpl, filename) {
+  try {
+    const raw = fsImpl.readFileSync(resolveAgentrcPath(ctx, filename), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {object | null} config
+ * @returns {boolean}
+ */
+function hasRetiredKey(config) {
+  const commands = config?.project?.commands;
+  return Boolean(commands) && Object.hasOwn(commands, 'lintBaseline');
+}
+
+export const retireLintBaselineCommand = {
+  version: '2.32.0',
+  description:
+    'strip retired project.commands.lintBaseline from .agentrc.json ' +
+    '(the framework lint-baseline capture CLI is gone — Story #5004)',
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @returns {boolean}
+   */
+  detect(ctx) {
+    const fsImpl = ctx?.fs ?? nodeFs;
+    return AGENTRC_FILENAMES.some((filename) =>
+      hasRetiredKey(readAgentrcConfig(ctx, fsImpl, filename)),
+    );
+  },
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @returns {void}
+   */
+  apply(ctx) {
+    const fsImpl = ctx?.fs ?? nodeFs;
+    for (const filename of AGENTRC_FILENAMES) {
+      const config = readAgentrcConfig(ctx, fsImpl, filename);
+      // An absent overlay is the common case, not an error.
+      if (!config || !hasRetiredKey(config)) continue;
+
+      delete config.project.commands.lintBaseline;
+      // An emptied `commands` block is left in place: unlike
+      // `planning.complexityGate`, `project` is a required block and an empty
+      // `commands` object is valid against the schema, so pruning it would be
+      // a cosmetic edit to a config the consumer owns.
+
+      fsImpl.writeFileSync(
+        resolveAgentrcPath(ctx, filename),
+        `${JSON.stringify(config, null, 2)}\n`,
+      );
+    }
+  },
+};