mandrel 2.39.0 → 2.40.0

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

@@ -7,14 +7,14 @@ description:
 
 # /mandrel-plan
 
-> **Lean spine.** Happy path + gate list; edge-case detail lives on demand in
+> **Lean spine.** Happy path + gate list; edge-case detail is on demand in
 > [`helpers/plan-reference.md`](helpers/plan-reference.md).
 
 ## Inputs
 
 Single planning path — there is no Epic/Story router, no scope-triage
-`epic|story` verdict. **Derive the mode from what the operator typed, announce
-it, act**:
+`epic|story` verdict (Gate #3's container groups, never routes). **Derive the
+mode from what the operator typed, announce it, act**:
 
 | Invocation | Mode | Behavior |
 | --- | --- | --- |
@@ -25,9 +25,9 @@ it, act**:
 | `/mandrel-plan 4712`, already delivered | amends | Amend a shipped Story from a **delta envelope**, not a re-interrogation. |
 
 **Resolving a bare id.** Read live state rather than asking: `agent::done` can
-only be amended, an open unplanned issue can only be planned. **Announce the
-derivation** — "4712 is `agent::done` → amending". Ask **only** for an open
-Story already at `agent::ready`.
+only be amended, an open unplanned issue only planned. **Announce the derivation** —
+"4712 is `agent::done` → amending". Ask **only** for an open Story already at
+`agent::ready`.
 
 ## Saying what you want
 
@@ -36,7 +36,7 @@ No flags to remember — state intent; the workflow fills in the CLI
 
 `--yes` is **runner-set, never operator-typed** — cron, `/loop`, and headless
 dispatch set it to mean *nobody is at the keyboard*, which auto-proceeds the
-gates below (#1 and #2). Never offer it to an operator or an attended run.
+gates below (#1 and #2) and skips #3. Never offer it to an operator.
 
 ## Default-single split policy
 
@@ -62,46 +62,44 @@ and derives source ids from its `sourceTickets[]`; the CLI also writes
 The envelope carries docs context, the story-author prompt, `sourceTickets[]`,
 `duplicates[]` (open **Stories**, never Epics) and advisory `complexitySignals`
 (**no routing authority**). A trivial scope can claim the lite route at
-persist — shape-validated, failing closed to `full`
-([detail](helpers/plan-reference.md)).
+persist — shape-validated, failing closed to `full` ([detail](helpers/plan-reference.md)).
 
 **Triage each unknown by resolver** ([detail](helpers/plan-reference.md)): an
 **AFK** unknown (research settles it) is resolved before authoring, never
-assumed; a **HITL** unknown (an operator call) goes to Gate #1 as "needs your
-decision". Under `--yes` do not ask free-form operator questions — AFK unknowns
-are still researched; only HITL unknowns land in Key Assumptions, each marked a
-decision-made-by-default.
+assumed; a **HITL** unknown goes to Gate #1. Under `--yes` do not ask free-form
+operator questions — AFK unknowns are still researched; only HITL unknowns land
+in Key Assumptions, each a decision-made-by-default.
 
 **Gate #1** — STOP to confirm the sharpened plan intent and any
 duplicate-candidate review. Under `--yes`, auto-proceed.
 
-On a truthy `memoryPoolAdvisory.recommend`, name [`/memory-consolidate`](memory-consolidate.md)
-as an operator option, quoting its `reasons[]` — advisory, never invoked here.
+On a truthy `memoryPoolAdvisory.recommend`, name
+[`/memory-consolidate`](memory-consolidate.md) quoting its `reasons[]` —
+advisory, never invoked here.
 
 On a truthy `deliverLightSuggestion.suggested`, offer — advisory, never an
-automatic reroute — to deliver the seed instead; on confirm, route **in this
+automatic reroute — to deliver the seed instead; on confirm route **in this
 session** into [`helpers/deliver-light.md`](helpers/deliver-light.md), its gate
-filled from this envelope. A truthy `complexitySignals.uiSurface` marks a
-UI-touching plan: name [`/prototype`](prototype.md) as an operator option,
-never invoke it here. [Both offers](helpers/plan-reference.md).
+filled from this envelope. A truthy `complexitySignals.uiSurface` names
+[`/prototype`](prototype.md) as an option; never invoke it here.
+[Both offers](helpers/plan-reference.md).
 
 ### 2. Author
 
 **One-shot authoring.** Start from `stories.template.json`; author
 `stories.json` in one pass. `body` is markdown **or** a structured object;
 persist parses either, serializes canonical markdown and syncs top-level
-`acceptance[]` / `verify[]` into it — never dual-author those lists.
+`acceptance[]` / `verify[]` in — never dual-author those lists.
 
 **Grounding = your reads + Phase 8.** Nothing inventories the repo: read each
-file you cite; persist's file-assumption gate hard-errors on any
-`{path, assumption}` absent from the tree. Entry fields:
-[reference](helpers/plan-reference.md).
+file you cite; persist hard-errors on any `{path, assumption}` absent from
+the tree. Fields: [reference](helpers/plan-reference.md).
 
 Artifacts under `temp/plan-<slug>/`: `stories.json` (**length 1 by default**;
 over-budget Specs fail closed — split or tighten, never under `docs/`); optional
-`techspec.md` (**N===1 only** — folded into `## Spec`); optional
-`acceptance-manifest.json` (N>1 partition — `--plan-acceptance`). For N=1 use
-the envelope `systemPrompts.story`; split only under the policy above.
+`techspec.md` (**N===1 only**, folded into `## Spec`) and
+`acceptance-manifest.json` (N>1 — `--plan-acceptance`). Use the envelope
+`systemPrompts.story`; split only under the policy above.
 
 **Tickets mode:** every Story authors a top-level `supersedes[]`; persist
 refuses a partial map ([shape](helpers/plan-reference.md)).
@@ -115,9 +113,9 @@ node .agents/scripts/plan-critics.js \
 ```
 
 Run **before** persist — the last point a finding folds into a re-author.
-It exits 0 on **any** verdict (verdicts route work, they do not gate) and exits
-**1** only on a usage/IO error — no critic ran, no skip ledgered: **do not
-proceed to Persist**, fix and re-run.
+It exits 0 on **any** verdict (verdicts route work, they do not gate) and
+exits **1** only on a usage/IO error — no critic ran: **do not proceed to
+Persist**, fix and re-run.
 
 - **Both `dispatch: false`** — proceed to Persist (each skip is ledgered).
 - **Either `dispatch: true`** — dispatch **one fresh-context, maker-blind
@@ -125,16 +123,19 @@ proceed to Persist**, fix and re-run.
   authoring transcript), fold findings into Gate #2 or a re-author round, re-run
   this step. Pre-mortem triggers (incl. the external-dependency probe), the
   advisory-only `textHygiene.findings[]` lints and dispatch shape:
-  [reference § Critic dispatch detail](helpers/plan-reference.md).
+  [reference](helpers/plan-reference.md).
 
 ### 3. Persist
 
 **Gate #2** — STOP for approval before persist **only** when the operator asked
 to review (`--force-review`). Under `--yes`, auto-proceed.
 
-Run persist with `--dry-run` **first** — same command, writes suppressed;
-every gate runs before the first `createIssue`
-([the list](helpers/plan-reference.md)):
+**Gate #3 (N>2 only)** — offer a **container Epic**; on a yes add
+`--epic-title` / `--epic-goal` below. It carries nothing a child does not
+([shape](helpers/plan-reference.md)). Never below 3 Stories, never unasked.
+
+Run persist with `--dry-run` **first** — same command, writes suppressed; every
+gate runs before the first `createIssue` ([list](helpers/plan-reference.md)):
 
 ```bash
 node .agents/scripts/plan-persist.js \
@@ -142,24 +143,29 @@ node .agents/scripts/plan-persist.js \
   --plan-dir temp/plan-<slug> \
   [--plan-acceptance temp/plan-<slug>/acceptance-manifest.json] \
   [--tech-spec temp/plan-<slug>/techspec.md] \
-  [--source-tickets 123,456]
+  [--source-tickets 123,456] \
+  [--epic-title "<name>" --epic-goal "<one paragraph>"]
 ```
 
-At lite shape, `--chain-on-clean` folds a clean dry-run into the real persist;
+At lite shape `--chain-on-clean` folds a clean dry-run into the real persist;
 a full plan keeps its review trip.
 
 Persist creates `type::story` issue(s), a **metadata-only** `plan-run::<id>`
-label, and `blocked by #<id>` footers for N>1 `depends_on` edges.
+label, `blocked by #<id>` footers for N>1 `depends_on` edges, and on a confirmed
+Gate #3 a `type::epic` container linking every created Story.
 `agent::ready` is the **terminal** flip after receipts land; stdout is pure
 JSON. Tickets mode also comments on and closes each source id
 ([detail](helpers/plan-reference.md)).
 
 ## Constraints
 
-- `/mandrel-plan` starts delivery **only** through a confirmed Gate #1 light route —
-  never off its own authored Stories, which land via [`/mandrel-deliver`](mandrel-deliver.md).
+- `/mandrel-plan` starts delivery **only** through a confirmed Gate #1 light
+  route — never off its own authored Stories, which land via
+  [`/mandrel-deliver`](mandrel-deliver.md).
 - Duplicate search targets open Stories (`type::story`), not Epics; and
   deterministic gates still fail closed under `--yes`.
+- A container Epic is never a work item, and no Story body gains an `Epic: #N`
+  footer: linkage is parent→child only.
 
 ## See also
 

package/docs/CHANGELOG.md

@@ -15,6 +15,22 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.40.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.39.0...mandrel-v2.40.0) (2026-09-06)
+
+
+### Added
+
+* audit-to-stories --auto: persist the cross-run ledger via a `--ledger-commit` PR and ship the audit-sweep runbook template ([#5145](https://github.com/dsj1984/mandrel/issues/5145)) ([#5151](https://github.com/dsj1984/mandrel/issues/5151)) ([7274e6a](https://github.com/dsj1984/mandrel/commit/7274e6abe1bbf4fca6e1ed09abc8b4ebc9598d89))
+* audit-to-stories: parse `####` findings under grouping headers and fail closed on a missing or mismatched `Severity tally:` line ([#5144](https://github.com/dsj1984/mandrel/issues/5144)) ([#5149](https://github.com/dsj1984/mandrel/issues/5149)) ([d9d8275](https://github.com/dsj1984/mandrel/commit/d9d827584989406e85d3e22110e6b741dab837e9))
+* container Epic: /mandrel-plan offers one above 2 Stories, /mandrel-deliver expands an Epic id, /audit-to-stories requests one by default ([#5139](https://github.com/dsj1984/mandrel/issues/5139)) ([#5147](https://github.com/dsj1984/mandrel/issues/5147)) ([60dd912](https://github.com/dsj1984/mandrel/commit/60dd912f9d00dbf2fb7c17f8c98639b4008b5892))
+
+
+### Fixed
+
+* audit-to-stories --wire-edges: carry the live provider's write ports through the dedup adapter ([#5143](https://github.com/dsj1984/mandrel/issues/5143)) ([#5146](https://github.com/dsj1984/mandrel/issues/5146)) ([380577e](https://github.com/dsj1984/mandrel/commit/380577e5e8f215bf28bb15ef8f2ac03c5958f0b8))
+* **tests:** assert the report path separator-agnostically for Windows ([#5153](https://github.com/dsj1984/mandrel/issues/5153)) ([afe7fda](https://github.com/dsj1984/mandrel/commit/afe7fda7aa257bfb5e0745160363189ed84c2ad1))
+* **tests:** import the provider fixture as a file URL for Windows ([#5150](https://github.com/dsj1984/mandrel/issues/5150)) ([797af46](https://github.com/dsj1984/mandrel/commit/797af46269e22e878fbd13293e5e5df6a044a1d3))
+
 ## [2.39.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.38.0...mandrel-v2.39.0) (2026-09-05)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.39.0",
+  "version": "2.40.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",