mandrel 2.31.0 → 2.33.0

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
@@ -162,6 +161,63 @@ terminal envelope are byte-identical either way.
 
 ---
 
+## Declared dependency edges — what actually gates dispatch
+
+`resolve-stories.js` builds each `dag[].dependsOn` from the **union of two
+declared-edge channels**, and nothing else: the Story body's footer block and
+the issue's native GitHub `blocked_by` relations. Both are read strictly — an
+edge the resolver cannot read is never quietly reported as an edge that does
+not exist.
+
+**The body channel is footer-scoped.** Only a `blocked by #N` line standing
+alone inside the `---` footer block declares an edge:
+
+```markdown
+## Goal
+
+…
+
+---
+
+blocked by #42
+```
+
+Prose elsewhere in the body declares **nothing**, and this is a deliberate,
+user-visible change from the whole-body scan that preceded it. A sentence
+merely mentioning a blocker — an example, a changelog note, an acceptance
+criterion quoting the phrase — used to mint a real dispatch gate that withheld
+the Story until an unrelated issue closed. `plan-persist` has always
+serialized the canonical footer form, so no machine-authored body is affected;
+only a **hand-written prose edge** stops gating, and the fix is to move it into
+the footer block. The loose spellings never reached the footer grammar either:
+`depends on #N`, `Blocked by: #N`, and `blocked by #N once X lands` all declare
+nothing. One grammar serves both readers — the body parser and the
+dispatch-edge parser share it — so what a Story body round-trips and what gates
+dispatch cannot drift apart.
+
+**The native channel fails loud.** The read paginates to exhaustion (a
+first-page read silently truncated a Story's gates at GitHub's 30-item
+default), and **a 404 is not an empty result**. An issue with no dependencies
+answers `200 []`; a 404 is how GitHub also answers a token that cannot see the
+dependencies API, so treating it as "no edges" erased every native edge in the
+run under a mis-scoped token, silently, with a clean exit code. Any non-OK
+read now fails the resolution naming the Story — check the token's scopes
+first. The one degrade that is scoped rather than fatal is a **cross-repo
+edge**: another repository's issue number cannot be matched against this
+repo's same-numbered issue without risking a false match, so that edge is
+dropped with a warning naming the Story, and its siblings resolve normally.
+
+**Edges are monotone — retraction is not built.** Both channels only ever
+_add_ a gate for the current resolution. Removing a `blocked by` footer line
+or deleting a native relation makes the edge absent from the **next** resolve,
+but nothing reconciles an edge that a previous run already acted on, and the
+write path never deletes a native relation it did not need. In practice that
+means: re-resolve after editing edges, and treat a stale gate as a body/issue
+edit plus a fresh `resolve-stories.js` run, never as something delivery
+un-declares on your behalf. This is a known limitation, not an oversight.
+
+---
+
 ## Step 1 — Implementation detail
 
 **Docs context — digest-first.** Read a full doc only when the Story's own
@@ -200,8 +256,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 +335,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 +451,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/plan-reference.md

@@ -243,6 +243,82 @@ as a hard error — so the grounding contract is the author's own targeted reads
 plus that gate. There is no pre-computed codebase snapshot to fall back on,
 and no manifest-derived replacement to build.
 
+### Per-Story audit provenance (`provenance`)
+
+An audit-seeded plan carries dedup identities forward so the next sweep
+recognises what it already planned. The optional top-level `provenance` field
+says **which of them this Story owns**:
+
+```jsonc
+{
+  "slug": "own-the-seam",
+  "provenance": {
+    "fingerprints": ["<40-char sha1, one per finding this Story tracks>"],
+    "semanticKeys": ["architecture␟lib/owned.js"]
+  }
+}
+```
+
+Both arrays are optional; a malformed entry is a validator rejection, never a
+silent drop — a dropped identity is invisible until the next sweep re-files
+work this plan already tracked.
+
+| `provenance` | What persist stamps |
+| --- | --- |
+| Present | **Exactly** the identities listed — siblings' groups never leak in. |
+| Present but empty (`{}`) | Nothing. "Owns no findings" is a real answer. |
+| **Absent** | The **whole seed's** footers (the union) — the recall-safe default. |
+
+**The union fallback is load-bearing, not legacy.** Leaving the authoring agent
+to hand-carry provenance out of the seed's HTML comments was measured to fail —
+a remembered step is no step at all — and the mechanical union carry is what
+closed it. Attribution is additive: it sharpens a plan that opts in and changes
+nothing for one that does not. Never remove the fallback to "finish the
+migration".
+
+Attribution is what makes the next sweep's dedup answerable rather than
+arbitrary. Under the union every sibling carried every key, so a finding
+confirming against several open Stories could only pick one at random, and a
+key whose owning Story had since **closed** was masked by any open neighbour —
+a genuine regression filed as a routine update. With ownership stamped, the
+issue carrying a finding's own fingerprint decides both the match and its
+state (`lib/findings/route-finding.js`).
+
+The audit path authors this mechanically from the per-group footers the seed
+already carries — see [`audit-to-stories`](../audit-to-stories.md). A `--seed`
+or `--tickets` plan has nothing to attribute and omits the field.
+
+## Cross-Story conflict analysis at persist
+
+The conflict passes run **twice**: once over the raw `stories.json` payload
+(alongside the freshness, file-assumption and sizing gates), and again over the
+**assembled, footer-stamped bodies** — the artifact persist actually posts.
+The second pass is not belt-and-braces. The canonical authoring shape carries
+`acceptance[]` / `verify[]` at the ticket's top level and assembly folds them
+into the body, so the passes that scan `body.acceptance` / `body.verify`
+(`implicit-cross-story-dep`, `missing-bdd-scaffold`) saw two empty arrays on
+the real payload and emitted nothing. Both passes complete before the first
+`createIssue`, so a refusal still costs no writes.
+
+`shared-editor` findings are rendered into the posted `plan-summary` comment,
+directly beneath the wave table: the table promises which Stories can run
+together, and a path two same-wave Stories both write is exactly where that
+promise breaks. Promise and caveat belong on one durable surface — previously
+the caveat was a stderr warning nobody kept.
+
+Two `planning.*` knobs upgrade a conflict class from advisory to a hard
+refusal. **Both default to `false` and are documented, not recommended:**
+
+| Knob | Upgrades | Why it is off |
+| --- | --- | --- |
+| `planning.failOnSharedEditors` | `shared-editor` → `hard` | Co-editing one file is routine and often correct; the delivery scheduler already serializes file-overlapping Stories. |
+| `planning.requireExplicitCrossStoryDeps` | `implicit-cross-story-dep` → `hard` | Path references are matched by substring, so a legitimate mention in prose can read as a dependency. |
+
+Turn one on for a repo where the class is genuinely fatal; expect a refusal to
+name the Stories and the fix (a `depends_on` edge, or folding the shared edit
+into one Story). The sibling knobs `failOnRegistryConflicts`,
+`failOnMissingBddScaffold` and `failOnLargeFanOut` behave the same way.
+
 ## Tickets mode — authoring `supersedes[]`
 
 In `--tickets` mode each Story carries a top-level `supersedes` array claiming

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,64 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.33.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.32.0...mandrel-v2.33.0) (2026-08-07)
+
+
+### Added
+
+* deliver: widen footprints from edit intent only, explain every withhold, and give standalone audit cohorts declared edges ([#5044](https://github.com/dsj1984/mandrel/issues/5044)) ([#5049](https://github.com/dsj1984/mandrel/issues/5049)) ([6bd0653](https://github.com/dsj1984/mandrel/commit/6bd0653e88e07ddbcc90c3c947b5f135374649d4))
+* plan: stamp only the provenance a Story owns, and run cross-Story conflict analysis over the bodies persist actually writes ([#5045](https://github.com/dsj1984/mandrel/issues/5045)) ([#5048](https://github.com/dsj1984/mandrel/issues/5048)) ([804b308](https://github.com/dsj1984/mandrel/commit/804b3087c001f21815aecb109bb636e59a87b2cb))
+
+
+### Fixed
+
+* check-knip-entries: resolve the entry list through knip's own config resolver, and skip cleanly when there is no knip config ([#5039](https://github.com/dsj1984/mandrel/issues/5039)) ([#5041](https://github.com/dsj1984/mandrel/issues/5041)) ([7f69a18](https://github.com/dsj1984/mandrel/commit/7f69a18ead79da77779981bec3eed8772dc05643))
+* deliver: make the declared-edge channel trustworthy — paginate native reads, fail loud on 404, parse footers strictly ([#5046](https://github.com/dsj1984/mandrel/issues/5046)) ([#5047](https://github.com/dsj1984/mandrel/issues/5047)) ([38b543d](https://github.com/dsj1984/mandrel/commit/38b543dec2634318b2407b54404239e7ae34d381))
+* **lint:** add a --root scan seam so the lint test stops mutating the shared tree (refs [#5052](https://github.com/dsj1984/mandrel/issues/5052)) ([#5053](https://github.com/dsj1984/mandrel/issues/5053)) ([69d1952](https://github.com/dsj1984/mandrel/commit/69d1952fb7410659ca21a9bb0d34eefadb654d2e))
+* plan: resolve the cross-Story conflict policy once for the raw and assembled passes ([#5050](https://github.com/dsj1984/mandrel/issues/5050)) ([711199a](https://github.com/dsj1984/mandrel/commit/711199a861bc1e85218a09fe4674c507b0c0edb1))
+
+## [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`,
+      );
+    }
+  },
+};