mandrel 2.30.0 → 2.32.0

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,55 @@ 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)
+
+
+### Added
+
+* **qa:** add an attach-don't-boot seam and an unreproducible-tier verdict (refs [#4994](https://github.com/dsj1984/mandrel/issues/4994)) ([#4995](https://github.com/dsj1984/mandrel/issues/4995)) ([dac7986](https://github.com/dsj1984/mandrel/commit/dac79868a305e34db01005f06f638fc384c21c17)), closes [#4993](https://github.com/dsj1984/mandrel/issues/4993)
+
 ## [2.30.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.29.0...mandrel-v2.30.0) (2026-08-04)
 
 

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`,
+      );
+    }
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.30.0",
+  "version": "2.32.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -28,10 +28,12 @@
     "coverage:update": "node .agents/scripts/update-coverage-baseline.js",
     "coverage:reanchor": "node .agents/scripts/update-coverage-baseline.js --full-scope",
     "baseline:agents-loc": "node baselines/agents-loc-baseline.mjs",
+    "baselines:scope": "node .agents/scripts/check-baseline-scope.js",
+    "baselines:prune": "node .agents/scripts/prune-baseline-orphans.js",
     "lint:md": "markdownlint-cli2 \".agents/**/*.md\" \"*.md\" \"!node_modules/**\" \"!.worktrees/**\"",
     "lint": "node .agents/scripts/run-lint.js && npm run docs:check",
     "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-lifecycle-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
-    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-lifecycle-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-lifecycle-doc-drift.js && node .agents/scripts/check-doc-links.js && node .agents/scripts/check-gherkin-placeholders.js && npm run skills:check",
+    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-lifecycle-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
     "skills:index": "node .agents/scripts/generate-skills-index.js",
     "skills:check": "node .agents/scripts/generate-skills-index.js --check",
     "format": "biome format --write .",
@@ -43,6 +45,8 @@
     "check:context-budget": "node .agents/scripts/check-context-budget.js",
     "check:cyclomatic": "node .agents/scripts/check-cyclomatic.js",
     "cyclomatic:update": "node .agents/scripts/check-cyclomatic.js --update",
+    "dead-exports:update": "node .agents/scripts/update-dead-exports-baseline.js && node .agents/scripts/update-dead-exports-baseline.js --production",
+    "check:knip-entries": "node .agents/scripts/check-knip-entries.js",
     "check:schema-refs": "node .agents/scripts/check-schema-references.js",
     "check:workflow-citations": "node .agents/scripts/check-workflow-citations.js",
     "crap:check": "node .agents/scripts/check-baselines.js --gate crap",
@@ -87,6 +91,7 @@
     "@biomejs/biome": "^2.5.0",
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
+    "@cucumber/gherkin": "^42.0.1",
     "c8": "^11.0.0",
     "chokidar": "^5.0.0",
     "husky": "^9.1.7",
@@ -104,18 +109,22 @@
     "js-yaml": "^4.2.0",
     "minimatch": "^10.0.0",
     "picomatch": "^4.0.4",
-    "string-argv": "^0.3.2",
     "typhonjs-escomplex": "^0.1.0"
   },
   "peerDependencies": {
+    "@cucumber/gherkin": ">=32.0.0",
     "typescript": ">=5.0.0"
   },
   "peerDependenciesMeta": {
+    "@cucumber/gherkin": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     }
   },
   "//": {
+    "peerDependencies.@cucumber/gherkin": "OPTIONAL peer, mirroring the `typescript` precedent, and deliberately NOT a runtime dependency. `check-gherkin-corpus.js` is the only consumer and it is opt-in behind `qa.gherkinLint`, so a consumer with no BDD tier must gain nothing from an upgrade. The devDependency alongside it is what lets this repository's own suite drive the real parser. The gate resolves it through a require path anchored at the consumer project — `.agents/` reaches a consumer by plain file copy, so a bare specifier would resolve against the consumer's module chain, which under a non-hoisting linker need not hold it.",
     "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.2.0 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended.",
     "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions."
   },

package/.agents/schemas/lifecycle/checkpoint.written.schema.json

@@ -1,13 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/checkpoint.written.schema.json",
-  "title": "checkpoint.written",
-  "description": "Self-emitted by CheckpointPointerWriter after the pointer file is updated. Carries the phase header for tracing and the last-completed seqId for the resume contract.",
-  "type": "object",
-  "required": ["phase", "lastCompletedSeqId"],
-  "properties": {
-    "phase": { "type": "string", "minLength": 1 },
-    "lastCompletedSeqId": { "type": "integer", "minimum": 0 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/close-validate.end.schema.json

@@ -1,18 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/close-validate.end.schema.json",
-  "title": "close-validate.end",
-  "description": "Emitted at the end of the close-validate sub-phase. ok=true => every gate passed; ok=false => failedGate identifies the first failed gate. durationMs is wall-clock time spent in the gate chain. Story #2250.",
-  "type": "object",
-  "required": ["epicId", "storyId", "ok"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "storyId": { "type": "integer", "minimum": 1 },
-    "ok": { "type": "boolean" },
-    "gateCount": { "type": "integer", "minimum": 0 },
-    "failedGate": { "type": "string", "minLength": 1 },
-    "exitCode": { "type": "integer" },
-    "durationMs": { "type": "integer", "minimum": 0 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/close-validate.start.schema.json

@@ -1,13 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/close-validate.start.schema.json",
-  "title": "close-validate.start",
-  "description": "Emitted at the start of the close-validate sub-phase (pre-merge gate chain typecheck/lint/test/format/maintainability/crap). Story #2250.",
-  "type": "object",
-  "required": ["epicId", "storyId"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "storyId": { "type": "integer", "minimum": 1 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/code-review.end.schema.json

@@ -1,30 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/code-review.end.schema.json",
-  "title": "code-review.end",
-  "description": "Emitted at the end of the code-review sub-phase. Carries a review-finding severity summary so the lifecycle ledger surfaces critical/high/medium/suggestion counts directly. The payload MUST NOT carry any secret-key-denylist fields (token, password, secret, apiKey, webhookUrl) — the LedgerWriter enforces this, but the schema's `additionalProperties: false` keeps the surface tight. Story #2252.",
-  "type": "object",
-  "required": ["epicId", "status"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "status": {
-      "type": "string",
-      "enum": ["ok", "no-changes", "invalid"]
-    },
-    "severity": {
-      "type": "object",
-      "required": ["critical", "high", "medium", "suggestion"],
-      "properties": {
-        "critical": { "type": "integer", "minimum": 0 },
-        "high": { "type": "integer", "minimum": 0 },
-        "medium": { "type": "integer", "minimum": 0 },
-        "suggestion": { "type": "integer", "minimum": 0 }
-      },
-      "additionalProperties": false
-    },
-    "halted": { "type": "boolean" },
-    "posted": { "type": "boolean" },
-    "durationMs": { "type": "integer", "minimum": 0 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/code-review.start.schema.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/code-review.start.schema.json",
-  "title": "code-review.start",
-  "description": "Emitted at the start of the code-review sub-phase (Phase D of the close-tail). Story #2252.",
-  "type": "object",
-  "required": ["epicId"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/intervention.recorded.schema.json

@@ -1,15 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/intervention.recorded.schema.json",
-  "title": "intervention.recorded",
-  "description": "Emitted whenever the host LLM performs an out-of-band manual intervention during an Epic delivery (e.g., AskUserQuestion, manual git restore/reset, --no-ff recovery merge, story-close --skipValidation). The InterventionRecorder listener appends the payload to the epic-run-state-store's manualInterventions array; a non-empty array disqualifies the Epic from auto-merge.",
-  "type": "object",
-  "required": ["epicId", "reason"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "reason": { "type": "string", "minLength": 1 },
-    "source": { "type": "string", "minLength": 1, "default": "host-llm" },
-    "ts": { "type": "string", "format": "date-time" }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/loop.tick.schema.json

@@ -1,20 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/loop.tick.schema.json",
-  "title": "loop.tick",
-  "description": "Emitted once per pass of a host-driven loop (e.g. a recurring loop command or a long-running poll) so each round lands an inspectable ledger record. Surfaces the loop as forward-progress evidence the /deliver idle watchdog already scans — distinct from story.heartbeat, which carries Story-phase info for a single in-flight Story. A loop is not tied to a Story tier: loop.tick carries a free-form loopName, a monotonic round counter, the configured cadence, and a status so a host loop never runs silently. cadence is the loop's configured interval label (e.g. '5m', 'self-paced'); status is the per-round verdict (running while the loop continues, done when it terminates normally, blocked when it stalls).",
-  "type": "object",
-  "required": ["event", "loopName", "round", "cadence", "status", "timestamp"],
-  "properties": {
-    "event": { "type": "string", "const": "loop.tick" },
-    "loopName": { "type": "string", "minLength": 1 },
-    "round": { "type": "integer", "minimum": 0 },
-    "cadence": { "type": "string", "minLength": 1 },
-    "status": {
-      "type": "string",
-      "enum": ["running", "done", "blocked"]
-    },
-    "timestamp": { "type": "string", "format": "date-time" }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/notification.emitted.schema.json

@@ -1,18 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/notification.emitted.schema.json",
-  "title": "notification.emitted",
-  "description": "Self-emitted by NotifyDispatcher after each webhook/comment dispatch. Carries the upstream event name, the channel, the severity, and the ok flag for trace fidelity.",
-  "type": "object",
-  "required": ["event", "channel", "severity", "ok"],
-  "properties": {
-    "event": { "type": "string", "minLength": 1 },
-    "channel": { "type": "string", "enum": ["webhook", "comment"] },
-    "severity": {
-      "type": "string",
-      "enum": ["info", "warn", "error", "critical"]
-    },
-    "ok": { "type": "boolean" }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/pr.created.schema.json

@@ -1,14 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/pr.created.schema.json",
-  "title": "pr.created",
-  "description": "Emitted by Finalizer immediately after gh pr create (or short-circuit). Must be preceded by acceptance.reconcile.ok from the same run.",
-  "type": "object",
-  "required": ["prUrl", "head", "base"],
-  "properties": {
-    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
-    "head": { "type": "string", "minLength": 1 },
-    "base": { "type": "string", "minLength": 1 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/retro.end.schema.json

@@ -1,16 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/retro.end.schema.json",
-  "title": "retro.end",
-  "description": "Emitted at the end of the retro sub-phase. `posted` indicates whether the retro structured comment was upserted onto the Epic; `retroPath` is the local mirror path under temp/run-<id>/ when written. Story #2252.",
-  "type": "object",
-  "required": ["epicId", "posted"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "posted": { "type": "boolean" },
-    "compact": { "type": "boolean" },
-    "retroPath": { "type": "string", "minLength": 1 },
-    "durationMs": { "type": "integer", "minimum": 0 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/retro.start.schema.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/retro.start.schema.json",
-  "title": "retro.start",
-  "description": "Emitted at the start of the retro sub-phase (Phase E of the close-tail). Story #2252.",
-  "type": "object",
-  "required": ["epicId"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 }
-  },
-  "additionalProperties": false
-}