mandrel 2.0.0 → 2.2.0

package/.agents/workflows/plan.md

@@ -37,11 +37,12 @@ Audit findings become Stories via [`/audit-to-stories`](audit-to-stories.md)
 | --- | --- |
 | `--seed "<text>"` | Seed text for ideation. |
 | `--seed-file <path>` | Pre-authored notes / plan-seed path. |
-| `--tickets <ids>` | Comma-separated issue ids to analyze. |
-| `--force-review` | Force gate #2 operator review even when risk routing would skip it. |
+| `--tickets <ids>` | Comma-separated issue ids to analyze. Closed as superseded at persist (see below). |
+| `--no-close-superseded` | Keep the `--tickets` source issues open — no supersede comment, no close. |
+| `--force-review` | STOP at gate #2 for operator review of the assembled plan. The only thing that gates review — there is no risk-derived routing (Story #4542). |
 | `--allow-over-budget` | Permit a plan that exceeds `maxTickets` (rare N>1). |
 | `--yes` | Non-interactive: auto-proceed gate #1 and gate #2 HITL waits. |
-| `--dry-run` | Author + validate without GitHub writes. |
+| `--dry-run` | Author + validate without GitHub writes. Run it as a pre-pass before every real persist (see below). |
 
 ## Default-single split policy
 
@@ -64,16 +65,24 @@ clarity, or reconciler ceremony for a single Story.
 ### 1. Interrogate
 
 ```bash
-node .agents/scripts/plan-context.js --seed "<seed>"
+node .agents/scripts/plan-context.js --seed "<seed>" \
+  --out temp/plan-<slug>/plan-context.json
 # or: --seed-file <path>
 # or: --tickets 123,456
 ```
 
+**Always pass `--out temp/plan-<slug>/plan-context.json`.** The CLI writes the
+envelope there (creating parent dirs); persist auto-discovers that file from
+`--plan-dir` and derives the `--tickets` source ids from its `sourceTickets[]`.
+That is what makes superseding work without anyone re-typing ids
+(Story #4554). The envelope still goes to stdout too, so piping is unaffected.
+
 The envelope carries docs context, codebase snapshot, BDD probe, risk
-heuristics, the story-author system prompt, and `duplicates[]` (open
-**Stories** whose title/body overlap the seed — never Epics). Under
-`--yes`, do not ask free-form operator questions — unresolved unknowns
-land in Key Assumptions.
+heuristics, the story-author system prompt, `sourceTickets[]` (`--tickets`
+mode), and `duplicates[]` (open **Stories** whose title/body overlap the
+seed — never Epics).
+Under `--yes`, do not ask free-form operator questions — unresolved
+unknowns land in Key Assumptions.
 
 **Gate #1** — STOP to confirm the sharpened plan intent and any
 duplicate-candidate review. Under `--yes`, auto-proceed.
@@ -90,36 +99,247 @@ Write artifacts under `temp/plan-<slug>/`:
   `acceptance[]` / `verify[]` (persist syncs them into the body). Do not
   restate Goal/Acceptance inside Spec. Over-budget Specs fail closed —
   split the Story or tighten Spec; never write Specs under `docs/`.
-- `risk-verdict.json` — axes + summary only (**no `deliveryShape`**).
 - optional `techspec.md` — **N===1 only** convenience when Spec was authored
   outside the Story JSON; persist folds it into that Story's `## Spec`.
   Forbidden for N>1 (each Story must carry its own Spec).
-- optional `acceptance-manifest.json` — plan-level AC list for partition
-  coverage when N>1.
+- optional `acceptance-manifest.json` — plan-level AC list (a JSON
+  `string[]`) for partition coverage when N>1. Pass it to persist as
+  `--plan-acceptance` or it is not read.
 
 For N=1, use the envelope `systemPrompts.story` and emit one cohesive
 Story. Split only under the policy above.
 
+**Tickets mode — author `supersedes[]` on every Story.** In `--tickets`
+mode each Story carries a top-level `supersedes` array claiming the source
+issues it replaces. It is bookkeeping, not part of the Story body, so it is
+never serialized into the markdown:
+
+```jsonc
+{
+  "slug": "close-superseded",
+  "supersedes": [
+    4525,
+    { "id": 4529, "note": "The filed `--changed-only` fix is provably inert; the correction is recorded here." }
+  ]
+}
+```
+
+Entries are bare issue numbers, or `{ id, note }` when the plan has
+something to say about *that* source issue — a correction to its analysis,
+or why it was folded in with others. The optional `note` is rendered into
+that issue's supersede comment, so planning that materially corrects a
+source issue records the correction on the ticket rather than emitting
+template-only prose.
+
+### Supersede-map partition
+
+`plan-persist` refuses a partial supersede map **before** it creates any
+Story (mirroring `assertAcceptancePartition`): every id passed to
+`--tickets` must be claimed by **exactly one** Story, and no Story may
+claim an id that was not a source ticket. With N>1 the mapping is not
+total by default — an authored map is the only thing that can say
+`#4525-#4528 → #4530` while `#4529 → #4531`, which a blanket "superseded by
+this plan-run" reference could not.
+
+### 2.5 Critics
+
+Evaluate the critic-dispatch conditions against the authored draft — here,
+**before** persist, because this is the last point where a finding can still
+be folded into a re-author round rather than into live issues:
+
+```bash
+node .agents/scripts/plan-critics.js \
+  --stories temp/plan-<slug>/stories.json \
+  [--tech-spec temp/plan-<slug>/techspec.md]
+```
+
+It prints a verdict on stdout and exits 0 on **any** verdict — the verdict
+routes work, it does not gate the run. It exits **1** only on a usage/IO
+error (an unreadable or malformed `--stories` / `--tech-spec` path). That is
+not an advisory "proceed": no critic ran and no skip was ledgered, so **do
+not proceed to Persist** — fix the path and re-run:
+
+```jsonc
+{
+  "consolidation": { "critic": "consolidation", "dispatch": false, "reasons": ["…"] },
+  "premortem": { "critic": "pre-mortem", "dispatch": true, "reasons": ["…"] },
+  "textHygiene": { "critic": "text-hygiene", "findings": [] }
+}
+```
+
+The verdict's third entry, `textHygiene`, is advisory-only (Story #4599): it
+carries deterministic body lints (`dangling-citation` / `open-question` /
+`slicing-mass`) with no dispatch semantics — it spawns nothing and never
+gates the run. Fold `textHygiene.findings[]` into the re-author round the
+same way critic findings fold in: fix each named defect in `stories.json`
+(anchor or inline the citation, resolve the question into a declarative
+assumption, thin the Slicing checkpoint) and re-run this step. Empty
+`findings` add nothing to the round.
+
+- **Both `dispatch: false`** — proceed straight to Persist. The conditions
+  provably have nothing for a critic to find, and each skip is recorded on the
+  plan-metrics ledger so under-firing stays auditable.
+- **Either `dispatch: true`** — dispatch **one fresh-context sub-agent per
+  firing critic** (a generic sub-agent), then fold its findings into the
+  Gate #2 view or a re-author round before persist. Each critic is
+  **maker-blind**: hand it the draft artifacts (`stories.json`, and
+  `techspec.md` when present) plus its charter below — never the authoring
+  transcript or the reasons the planner believed its own draft is sound. A
+  critic that reads the maker's case grades the case, not the draft.
+  - `consolidation` — the draft's shape: Stories that should be one cohesive
+    slice, a slice split per-module rather than per-capability, and
+    `depends_on` edges that disagree with the Delivery Slicing table.
+  - `pre-mortem` — assume the plan shipped and failed: name the most likely
+    failure modes and what the draft would have to say to prevent them.
+
+Fold what survives back into `stories.json` and re-run this step. Findings are
+advisory input to the operator's Gate #2 decision, not an automatic re-author
+mandate.
+
 ### 3. Persist
 
-**Gate #2** — when risk routing requires review (or `--force-review`), STOP
-for operator approval of the assembled plan before persist. Under `--yes`, auto-proceed.
-N=1 low-risk plans typically skip this gate.
+**Gate #2** — when the operator passed `--force-review`, STOP for approval of
+the assembled plan before persist. Under `--yes`, auto-proceed.
+
+`--force-review` is the **only** thing that raises this gate. Story #4542
+retired the risk-derived alternative: the planner authored its own risk verdict,
+persist computed a `requiresStop` from it *after* `createStoryIssues` had already
+run, and nothing read the result — the STOP was prose executed by the same
+session that wrote the verdict. A gate a plan can lower for itself is not a gate.
+
+#### Dry-run pre-pass (always)
+
+Run persist with `--dry-run` **before** the real one. It is the same command
+with the same flags — only the GitHub writes are suppressed:
+
+```bash
+node .agents/scripts/plan-persist.js \
+  --stories temp/plan-<slug>/stories.json \
+  [--plan-acceptance temp/plan-<slug>/acceptance-manifest.json] \
+  [--tech-spec temp/plan-<slug>/techspec.md] \
+  --plan-dir temp/plan-<slug> \
+  --dry-run
+```
+
+Every gate — ticket validator, body parse, subject-prefix, DAG, capacity,
+budget, reachability, split-policy and supersede partitions, Spec fold —
+runs **before** the first `createIssue`, so a dry-run exercises all of them
+write-free. An authoring mistake surfaces here, where the fix costs one
+re-author, instead of after `k` of `N` Stories are already live.
+
+#### The real persist
 
 ```bash
 node .agents/scripts/plan-persist.js \
   --stories temp/plan-<slug>/stories.json \
-  --risk-verdict temp/plan-<slug>/risk-verdict.json \
+  [--plan-acceptance temp/plan-<slug>/acceptance-manifest.json] \
   [--tech-spec temp/plan-<slug>/techspec.md] \
   [--plan-dir temp/plan-<slug>] \
-  [--dry-run] \
+  [--plan-context temp/plan-<slug>/plan-context.json] \
+  [--source-tickets 123,456] \
+  [--no-close-superseded] \
   [--force-review] \
   [--allow-over-budget]
 ```
 
-Persist creates Story issue(s) with `type::story` + `agent::ready`. When
-N>1 it also applies a shared `plan-run::<id>` label. Ends by naming
-`/deliver <storyId>` (or `/deliver --run <planRunId>` for N>1).
+Pass `--plan-acceptance` whenever step 2 wrote an `acceptance-manifest.json`
+— it is what `assertAcceptancePartition` checks the N>1 split against.
+
+Persist creates Story issue(s) with `type::story` (plus any sanitized
+authored `labels[]`) and, when N>1, writes each authored `depends_on` edge
+into the sibling's body as a `blocked by #<id>` footer — the ordering
+`/deliver` resolves from. No batch label is applied (Story #4540 retired
+`plan-run::<id>`). Ends by naming the exact command:
+`/deliver <storyId> [<storyId> ...]`.
+
+stdout is a pure JSON result; all log lines go to stderr, so a headless
+driver can `JSON.parse` the stdout stream directly.
+
+#### Ready means fully persisted
+
+`agent::ready` is the **terminal** step, not part of the creating POST
+(Story #4541). The order is: create unlabelled → upsert `story-plan-state` on
+every Story → upsert `plan-summary` on the primary → flip every Story to
+`agent::ready`.
+
+This is what lets `/deliver` trust the label: a Story carrying
+`agent::ready` always has its persist receipt on the ticket, so nothing can
+pick it up mid-write and read a half-persisted plan.
+
+#### Resuming a failed persist
+
+Persist is **idempotent over the same authored artifacts**. Each created body
+carries an invisible plan fingerprint (derived from the Story's slug +
+title), and persist indexes the open `type::story` backlog by it before
+creating anything.
+
+So if a transient GitHub failure strands the run at Story `k` of `N`:
+
+| | Behaviour |
+| --- | --- |
+| The `1..k-1` Stories | Live, but **not** `agent::ready` — invisible to `/deliver`, not half-delivered. |
+| Re-running persist | Adopts them by fingerprint, creates only the missing ones, then flips the whole cohort ready. |
+| Editing `stories.json` first | Changing a slug or title changes the fingerprint — the old issue is orphaned rather than adopted. Close it by hand. |
+
+Just re-run the same command. Do not hand-delete the stranded issues first.
+
+#### Temp hygiene
+
+A terminal-success run deletes its own `--plan-dir`. Every persist also reaps
+abandoned `temp/plan-*` directories older than 7 days, so dry-runs, failed
+gates, and abandoned authoring sessions do not accumulate under `temp/`.
+
+### How the source ids reach persist
+
+In `--tickets` mode persist needs to know which ids were fetched. It resolves
+them **envelope-first** (Story #4554):
+
+| Channel | When it wins |
+| --- | --- |
+| Envelope `sourceTickets[]` | **The normal path.** Written by step 1's `--out`, then read from `--plan-context <file>` or auto-discovered at `<plan-dir>/plan-context.json`. No ids to re-type. |
+| `--source-tickets <ids>` | Explicit **override** for hand-driven runs (no captured envelope, or deliberately narrowing the set). Wins over the envelope; a disagreement is warned about, not silently reconciled. |
+
+The result envelope's `supersede.sourceTicketOrigin` reports which channel was
+used (`envelope` \| `flag` \| `none`).
+
+Every path with no envelope is **audible** — persist cannot tell a legitimate
+`--seed` run from a `--tickets` run whose envelope was never captured, so it
+says so rather than deciding silently:
+
+| Situation | Behaviour |
+| --- | --- |
+| Neither `--plan-dir` nor `--plan-context` | **Warn** — nothing was read; only `--source-tickets` can supply ids. |
+| Auto-discovered `<plan-dir>/plan-context.json` absent | **Warn** — degrade to `--source-tickets`; a `--seed` run legitimately has none. |
+| Explicit `--plan-context` missing | **Fatal** — the operator named a file and meant it. |
+| Envelope present but unparseable | **Fatal** — a corrupt envelope is not "no source tickets"; treating it as such is how a `--tickets` run used to report success having superseded nothing. |
+
+Whichever channel supplies them, the supersede-map partition above still
+fail-closes: a `--tickets` run whose Stories forgot `supersedes[]` is now
+**caught** (`source ticket #N is not claimed by any Story`) instead of
+partitioning an empty set and passing vacuously.
+
+### Closing superseded source tickets
+
+**Default on.** After the Stories exist, persist comments on each source
+issue naming the specific Story that claims it — plus that Story's optional
+per-supersede `note` — and closes it with reason **`not_planned`**
+(`state_reason`). Nothing has shipped at persist time and the issue will not
+be actioned in its own right, so `not_planned` is the honest reason;
+`completed` would be a lie. This is what keeps the tracker from asserting
+that already-planned work is still unowned, and it writes down the supersede
+link that makes the history readable.
+
+| Behaviour | Contract |
+| --- | --- |
+| Default | Comment + close every source ticket as `not_planned`. |
+| `--no-close-superseded` | Skips all commenting and closing. Story creation is unchanged. Use it for a genuinely partial supersede — when the plan folded in only *part* of an issue and the remainder must stay open. |
+| `--dry-run` | Posts no comment and closes nothing; reports what it would have done. |
+| Re-run | Idempotent — the comment is keyed off a `superseded-by` structured-comment marker, and an already-closed source is skipped. |
+| Already closed / deleted / inaccessible | Skipped and reported. Never throws. |
+| Close-phase failure | **Never fails the run.** Stories stay created; the result envelope's `supersede` report names which tickets were and were not closed so the operator can finish by hand. |
+
+`--seed` / `--seed-file` modes have no source tickets, so no close phase
+runs at all.
 
 ## Constraints
 

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

@@ -21,7 +21,7 @@ high-quality, triage-ready ledger. The session has four movements:
    a final review of the **entire** ledger and asks any last clarifying
    questions.
 4. **Triage & Plan** (Phase 4) — only then does the agent route the full ledger
-   into [`/plan`](plan.md) to generate Epics and/or Stories.
+   into [`/plan`](plan.md) to generate Stories.
 
 Unlike [`/qa-explore`](qa-explore.md) (where the *agent* drives open-ended
 exploration of a named surface), `/qa-assist` is **human-led**: the human owns
@@ -224,13 +224,13 @@ every decision to the shared core helpers; never re-derive them in prose.
 
 3. **Hydrate the QA context** to locate code precisely, via
    [`qa-context-hydrator.js`](../scripts/lib/qa/qa-context-hydrator.js) — it
-   resolves the Epic (whose body carries the planning sections), the
+   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({ epicNumber, githubPort, gitPort, surfaceMap });
+   const context = await hydrateQaContext({ ticketNumber, githubPort, gitPort, surfaceMap });
    ```
 
 4. **Compute the coverage verdict** for the surface the observation points at,
@@ -320,20 +320,20 @@ its transition is **explicitly operator-gated**.
    const { promotions } = await promoteFindings(ledgerItems, {
      searchIssues, // GitHub provider, open + closed
      createStory, // tight cluster (≤2 surfaces): seed → /plan --seed-file
-     createEpic, // broad cluster (>2 surfaces): same /plan --seed-file path (may N>1)
+     createPlanSeed, // broad cluster (>2 surfaces): same /plan --seed-file path (may N>1)
    });
    ```
 
    - **Sizing is delegated, not decided in prose.** `promoteFindings` runs
      `clusterLedgerItems` + `targetForCluster`: a cluster spanning **≤2**
      distinct coverage surfaces routes to `createStory`; **>2** routes to
-     `createEpic`. Neither port opens an Epic ticket — both chain
+     `createPlanSeed`. Neither port opens an Epic ticket — both chain
      `/plan --seed-file`. Do not re-cluster, re-size, or re-dedup in the
      workflow —
      [`route-finding.js`](../scripts/lib/findings/route-finding.js) /
      [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) are the
      single implementation.
-   - **`createStory` / `createEpic` (`/plan --seed-file`)** — render a
+   - **`createStory` / `createPlanSeed` (`/plan --seed-file`)** — render a
      **redacted** plan seed from the cluster (reuse the `/audit-to-stories`
      Phase 5a seed shape; redaction already ran in Phase 2), **stamp the
      cluster's `fingerprintFooter(sha)` verbatim into the seed body**, then

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

@@ -338,18 +338,18 @@ For each untriaged ledger item:
    const { promotions } = await promoteFindings(ledgerItems, {
      searchIssues, // GitHub provider, open + closed
      createStory, // tight cluster (≤2 surfaces): seed → /plan --seed-file
-     createEpic, // broad cluster (>2 surfaces): same /plan --seed-file path (may N>1)
+     createPlanSeed, // broad cluster (>2 surfaces): same /plan --seed-file path (may N>1)
    });
    ```
 
    - **Sizing is delegated, not decided in prose.** `promoteFindings` runs
      `clusterLedgerItems` + `targetForCluster`: a cluster spanning **≤2**
      distinct coverage surfaces routes to `createStory`; **>2** routes to
-     `createEpic`. Neither port opens an Epic ticket — both chain
+     `createPlanSeed`. Neither port opens an Epic ticket — both chain
      `/plan --seed-file`. The workflow introduces no new sizing, clustering,
      or dedup logic — `route-finding.js` / `promote-finding.js` remain the
      single implementation.
-   - **`createStory` / `createEpic` (`/plan --seed-file`)** — render a
+   - **`createStory` / `createPlanSeed` (`/plan --seed-file`)** — render a
      **redacted** plan seed from the cluster (reuse the `/audit-to-stories`
      Phase 5a seed shape; redaction already ran in Capture), **stamp the
      cluster's `fingerprintFooter(sha)` verbatim into the seed body**, then

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

@@ -382,16 +382,12 @@ For each untriaged ledger item:
    same cluster/size/route/file path `/qa-explore` and `/audit-to-stories`
    consume (`clusterLedgerItems` + `targetForCluster`: a cluster spanning ≤2
    coverage surfaces routes to `createStory` via `/plan --seed-file`, >2 to
-   `createEpic` via `/plan --seed`, with the cluster's `fingerprintFooter(sha)`
+   `createPlanSeed` via `/plan --seed`, with the cluster's `fingerprintFooter(sha)`
    stamped verbatim into the seed). A `file` disposition never opens a raw
    GitHub Issue; only `defer` and `dismiss` skip the `/plan` handoff.
 5. **Gate:** any ticket-filing, seed write, `/plan` invocation, or label
    mutation is a write — confirm each with the operator before it happens.
 
-If the run was triggered from an Epic-testing context, hand the approved,
-promoted findings to the Epic-testing helper for attachment to the Epic's QA
-evidence ticket.
-
 ## Step 6 — Report
 
 Summarize the sweep in chat with:

package/bin/mandrel.js

@@ -57,7 +57,18 @@ const SUBCOMMANDS = new Map([
     'sync-commands',
     {
       description: 'regenerate .claude/commands/ from .agents/workflows/',
-      knownFlags: new Set(['--dry-run']),
+      // No --dry-run: the projection scripts have no preview mode, and
+      // accepting the flag while syncing for real overwrote .claude/ on an
+      // operator who asked for a preview. Reject it at the dispatcher.
+      knownFlags: new Set([]),
+    },
+  ],
+  [
+    'sync-agents',
+    {
+      description: 'regenerate .claude/agents/ from .agents/agents/',
+      // Same contract as sync-commands: no preview mode, so no --dry-run.
+      knownFlags: new Set([]),
     },
   ],
   [

package/docs/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.1.0...mandrel-v2.2.0) (2026-07-17)
+
+
+### Added
+
+* **deliver:** probe live state per beat, retiring hand-maintained --done/--in-flight (refs [#4594](https://github.com/dsj1984/mandrel/issues/4594)) ([#4597](https://github.com/dsj1984/mandrel/issues/4597)) ([96b2ef6](https://github.com/dsj1984/mandrel/commit/96b2ef6ce5f0526de2e5033e8cdb0ca02f6d5d89))
+* **plan:** add deterministic text-hygiene lints to the critic gate and codify authoring conventions (refs [#4599](https://github.com/dsj1984/mandrel/issues/4599)) ([#4607](https://github.com/dsj1984/mandrel/issues/4607)) ([8794459](https://github.com/dsj1984/mandrel/commit/87944593f8ba5c304cdbaef40a4d3e4430e5d71d))
+* **plan:** retire the [@epic](https://github.com/epic)-<id>-ac-N Gherkin AC tag namespace (refs [#4604](https://github.com/dsj1984/mandrel/issues/4604)) ([#4608](https://github.com/dsj1984/mandrel/issues/4608)) ([7388c58](https://github.com/dsj1984/mandrel/commit/7388c581d43e10a26c538e19a15897d2b5adafa7))
+* rewire the /plan critics into a live pre-persist gate ([#4592](https://github.com/dsj1984/mandrel/issues/4592)) ([#4598](https://github.com/dsj1984/mandrel/issues/4598)) ([349367d](https://github.com/dsj1984/mandrel/commit/349367d46bfbe59be5ce56952bca46cac8e5828c))
+* **story-body:** render numbered ACs, humanized path bullets, and visible wide rationale (refs [#4600](https://github.com/dsj1984/mandrel/issues/4600)) ([#4606](https://github.com/dsj1984/mandrel/issues/4606)) ([843779e](https://github.com/dsj1984/mandrel/commit/843779e2730832a1d7a6e081a0a18b40dd621981))
+
+
+### Fixed
+
+* fix probe mode's incomplete live classification: double-dispatch window and blocked-Story wedge ([#4601](https://github.com/dsj1984/mandrel/issues/4601)) ([#4605](https://github.com/dsj1984/mandrel/issues/4605)) ([0875b6a](https://github.com/dsj1984/mandrel/commit/0875b6af857fcfadc423e4e3731d792dc2a5fe60))
+* **story-close:** close [#4593](https://github.com/dsj1984/mandrel/issues/4593)'s single-enumeration leak and root-cause the un-fired MI gate ([#4610](https://github.com/dsj1984/mandrel/issues/4610)) ([1edf5a6](https://github.com/dsj1984/mandrel/commit/1edf5a67ceaf868f8faae92aec1c6280f191d33f))
+
+
+### Changed
+
+* **orchestration:** compute the Story change-set once and thread it through delivery (refs [#4593](https://github.com/dsj1984/mandrel/issues/4593)) ([#4595](https://github.com/dsj1984/mandrel/issues/4595)) ([d116015](https://github.com/dsj1984/mandrel/commit/d1160150836e8bf7107fac24189cde258ea93458))
+
+## [2.1.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.0.0...mandrel-v2.1.0) (2026-07-17)
+
+
+### ⚠ BREAKING CHANGES
+
+* **plan:** plan-persist.js no longer accepts --risk-verdict and no plan-time step authors a risk verdict; review depth and the acceptance critic mode are derived from the diff at close time.
+* /deliver no longer accepts --run <planRunId> or --dep, and /plan no longer applies a plan-run::<id> label. Deliver Story ids; the graph resolves itself from live state.
+
+### Added
+
+* /deliver takes only Story ids and resolves dependencies dynamically (retire plan-run) ([#4540](https://github.com/dsj1984/mandrel/issues/4540)) ([#4560](https://github.com/dsj1984/mandrel/issues/4560)) ([e9935cc](https://github.com/dsj1984/mandrel/commit/e9935cc332b43862d79dca9979691077327e1882))
+* **dead-exports:** add a production-mode pass that discounts test-only importers (refs [#4575](https://github.com/dsj1984/mandrel/issues/4575)) ([#4582](https://github.com/dsj1984/mandrel/issues/4582)) ([0a77ca9](https://github.com/dsj1984/mandrel/commit/0a77ca91bdd67a294b66cc076e45c43bc4d691c8))
+* **deliver:** script-owned land tail, resumable pending status, terminal envelope, and deliver-recover ([#4543](https://github.com/dsj1984/mandrel/issues/4543)) ([#4566](https://github.com/dsj1984/mandrel/issues/4566)) ([f234306](https://github.com/dsj1984/mandrel/commit/f234306d1465fe96d19d361f1501ad8edf055cc3))
+* **plan:** close --tickets source issues as superseded by default ([#4535](https://github.com/dsj1984/mandrel/issues/4535)) ([#4553](https://github.com/dsj1984/mandrel/issues/4553)) ([c35e298](https://github.com/dsj1984/mandrel/commit/c35e29880edba4fec0c45687071fbea242236370))
+* **plan:** mirror sibling depends_on into native blocked_by edges (refs [#4544](https://github.com/dsj1984/mandrel/issues/4544)) ([#4570](https://github.com/dsj1984/mandrel/issues/4570)) ([6b94968](https://github.com/dsj1984/mandrel/commit/6b949688e4fd487c979044f2473e3837a4637e1a))
+
+
+### Fixed
+
+* **bootstrap:** honor command:false in the workflow/command parity check ([#4588](https://github.com/dsj1984/mandrel/issues/4588)) ([493b3eb](https://github.com/dsj1984/mandrel/commit/493b3eb039eefabbd2e33af6a08933d43876c052))
+* **cli:** resolve versions from the consumer, not the running CLI — and make the sync surface fail loudly on skew ([#4530](https://github.com/dsj1984/mandrel/issues/4530)) ([#4536](https://github.com/dsj1984/mandrel/issues/4536)) ([5f20563](https://github.com/dsj1984/mandrel/commit/5f20563eca79203096b49e8fa3dfaa64e2487e12))
+* **cli:** stop sync pruning generated .agents/ files — declare a never-pruned registry so the install ledger survives ([#4534](https://github.com/dsj1984/mandrel/issues/4534)) ([#4552](https://github.com/dsj1984/mandrel/issues/4552)) ([ceccd57](https://github.com/dsj1984/mandrel/commit/ceccd572614a7d8c5226bdd9f1a3b793381be4dd))
+* **column-sync:** stop two more test suites leaking into the shared meta cache ([#4561](https://github.com/dsj1984/mandrel/issues/4561)) ([757e509](https://github.com/dsj1984/mandrel/commit/757e509ff4aa95a091fe9a5de053396a78a26793)), closes [#4555](https://github.com/dsj1984/mandrel/issues/4555)
+* **deliver:** diff the plan-run epilogue against the pre-run base, not origin/main...HEAD (refs [#4550](https://github.com/dsj1984/mandrel/issues/4550)) ([#4558](https://github.com/dsj1984/mandrel/issues/4558)) ([79ddbf6](https://github.com/dsj1984/mandrel/commit/79ddbf61d19bdf256a06aabb860651be6bdce94b))
+* **deliver:** ground the audit roster's lens selection in the landed diff (refs [#4571](https://github.com/dsj1984/mandrel/issues/4571)) ([#4573](https://github.com/dsj1984/mandrel/issues/4573)) ([fa06aca](https://github.com/dsj1984/mandrel/commit/fa06acaedc0c3070516ec32d447f0755a06ea0eb))
+* **deliver:** repair the close-and-land default path (config, operator-merge, follow-ups, reap, reporting) ([#4539](https://github.com/dsj1984/mandrel/issues/4539)) ([#4551](https://github.com/dsj1984/mandrel/issues/4551)) ([9b5c3ee](https://github.com/dsj1984/mandrel/commit/9b5c3ee61b2030e96ff88091761b258eb43fdf43))
+* make `npm run verify` a true CI mirror: include dead-exports + arch-cycles (or catalogue them as CI-only) ([#4549](https://github.com/dsj1984/mandrel/issues/4549)) ([#4557](https://github.com/dsj1984/mandrel/issues/4557)) ([70d088a](https://github.com/dsj1984/mandrel/commit/70d088a646fd1867f3d536c541f89c1c49b0b866))
+* **plan:** make persist resumable and align its gates with the authoring contract ([#4541](https://github.com/dsj1984/mandrel/issues/4541)) ([#4565](https://github.com/dsj1984/mandrel/issues/4565)) ([1cbe974](https://github.com/dsj1984/mandrel/commit/1cbe974154403edab14e006e83f42a5c414150d1))
+* **plan:** make the fan-out deletion gate count importers, not basename word matches ([#4547](https://github.com/dsj1984/mandrel/issues/4547)) ([#4567](https://github.com/dsj1984/mandrel/issues/4567)) ([4c5c724](https://github.com/dsj1984/mandrel/commit/4c5c7248e88136bac83cd91db38658390139c588))
+* **plan:** thread sourceTickets through the envelope so --tickets superseding cannot silently no-op ([#4554](https://github.com/dsj1984/mandrel/issues/4554)) ([#4559](https://github.com/dsj1984/mandrel/issues/4559)) ([4546c40](https://github.com/dsj1984/mandrel/commit/4546c405b2131f6c5afd3ccf40bccb357f4223a0))
+* **quality:** retire the unconsumed miDropMustRefactor/miDropCap knobs and make maintainability.tolerance the single MI-drop control ([#4531](https://github.com/dsj1984/mandrel/issues/4531)) ([#4548](https://github.com/dsj1984/mandrel/issues/4548)) ([fe0c7ce](https://github.com/dsj1984/mandrel/commit/fe0c7ce3ad40e21b957cd6d0a916efbc5e75f634))
+* **skills-index:** emit biome-formatted JSON so regeneration leaves no drift (refs [#4546](https://github.com/dsj1984/mandrel/issues/4546)) ([#4568](https://github.com/dsj1984/mandrel/issues/4568)) ([bdb223e](https://github.com/dsj1984/mandrel/commit/bdb223e2979c0d386ca260b6743cdf2062dbff09))
+
+
+### Changed
+
+* **checks:** drop the dead epic merge-lock and epic-branch probes ([#4581](https://github.com/dsj1984/mandrel/issues/4581)) ([28cb4ab](https://github.com/dsj1984/mandrel/commit/28cb4abf4aa9c0c0120598c26dd5b7220b195678))
+* **docs:** move weight out of always-loaded prompts and skill essays into on-demand references ([#4546](https://github.com/dsj1984/mandrel/issues/4546)) ([#4564](https://github.com/dsj1984/mandrel/issues/4564)) ([14381b3](https://github.com/dsj1984/mandrel/commit/14381b3efd7ce774e39dd47f535bb55991387617))
+* **plan:** derive review depth from the diff and retire the authored risk verdict (refs [#4542](https://github.com/dsj1984/mandrel/issues/4542)) ([#4569](https://github.com/dsj1984/mandrel/issues/4569)) ([7a7fb50](https://github.com/dsj1984/mandrel/commit/7a7fb50f7ec0e33d616fa54618fc0b93c2e310a6))
+
 ## [2.0.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.94.0...mandrel-v2.0.0) (2026-07-14)