mandrel 2.39.0 → 2.40.0

package/.agents/README.md

@@ -322,9 +322,12 @@ in `runtime-deps.json`.
 Orchestration and planning are **Story-only** (`type::story`) — `/mandrel-plan`
 persists Stories with inline `acceptance[]` / `verify[]` and a folded
 `## Spec`; `/mandrel-deliver` runs `helpers/deliver-story` on `story-<id>` → PR →
-`main`. There is no `type::epic` / `type::task` label, Epic issue form, or
-`epic/<id>` integration branch; a ticket carrying an `Epic: #N` footer is
-refused by `/mandrel-deliver`. The execution-model contract is owned by
+`main`. There is no `type::task` label, Epic issue form, or `epic/<id>`
+integration branch; a ticket carrying an `Epic: #N` footer is refused by
+`/mandrel-deliver`. `type::epic` exists as a **pure container** — a goal plus a
+child checklist, never delivered itself, expanded to its open Stories by
+`/mandrel-deliver <epicId>` — and its linkage is parent→child only, which is
+what keeps that footer refused. The execution-model contract is owned by
 [`instructions.md` § 5.B](instructions.md) and [`docs/SDLC.md`](docs/SDLC.md).
 
 ---

package/.agents/agents/auditor.md

@@ -130,6 +130,11 @@ Record the outcome in the Executive Summary as a single line —
 `Self-cross-check: kept <k> / dropped <d>.` — and, when `d > 0`, name the
 dropped findings with their reason. The line's absence is itself a defect.
 
+Beside it, carry one machine-readable tally of the findings you kept —
+`Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>`, zeros
+included, `Info` never counted. `audit-to-stories` cross-checks that line
+against its parse and refuses a report whose tally is missing or wrong.
+
 ## Fan-out (heavyweight lenses)
 
 When your caller dispatches you for a single dimension of a heavyweight lens

package/.agents/docs/SDLC.md

@@ -7,12 +7,13 @@ each Story is delivered on its own `story-<id>` branch and reaches `main`
 through its own PR.
 
 An Epic may still exist as an **optional untyped human umbrella issue**
-(no `type::epic` label and no shipped Epic issue form — only
-`.github/ISSUE_TEMPLATE/story.yml`), but **delivery and planning
-orchestration are Story-only**: there is no Epic wave loop, no
-`epic/<id>` integration branch, no `epic.yaml` reconciler, and any ticket
-that still carries an `Epic: #N` footer is **refused** by `/mandrel-deliver`
-(close it or re-plan it as a v2 Story).
+(the only shipped issue form is `.github/ISSUE_TEMPLATE/story.yml`), and
+**delivery and planning orchestration are Story-only**: there is no Epic
+wave loop, no `epic/<id>` integration branch, no `epic.yaml` reconciler,
+and any ticket that still carries an `Epic: #N` footer is **refused** by
+`/mandrel-deliver` (close it or re-plan it as a v2 Story). `type::epic`
+exists as a **container only** — a grouping ticket with no execution
+payload, expanded to its children at delivery (ADR `20260905-5139`).
 
 The framework is **Claude Code-first**: `.claude/`, hooks, skills, and
 the slash-command surface lean in on Claude Code as the reference
@@ -247,9 +248,10 @@ self-eval, ceremony, close, CI watch, confirm-merge, cleanup) lives in the
 
 The single operator-facing entry point is `/mandrel-deliver`. It performs no
 git/label mutations itself — `deliver-story` owns every script invocation
-per Story. Any ticket that is not `type::story`, or that still carries an
-`Epic: #N` reference, is a hard error naming the ID and the fix (close or
-re-plan as a v2 Story).
+per Story. A `type::epic` id expands to its open child Stories before
+resolution. Any ticket that is neither of those two types, or that still
+carries an `Epic: #N` reference, is a hard error naming the ID and the fix
+(close or re-plan as a v2 Story).
 
 ### Branch model (authoritative)
 
@@ -560,9 +562,15 @@ Editing the main checkout's `.agentrc.json` only affects **the next**
 
 ### `Epic: #N` refusal
 
-`/mandrel-deliver` refuses any ticket that still carries an `Epic: #N` footer or is
-not `type::story`. This is expected — v2 has no Epic delivery path. Close
-the ticket or re-plan the work as a v2 Story via `/mandrel-plan --tickets <id>`.
+`/mandrel-deliver` refuses any ticket that still carries an `Epic: #N` footer,
+or that is neither `type::story` nor `type::epic`. This is expected — v2 has
+no Epic *delivery* path. Close the ticket or re-plan the work as a v2 Story
+via `/mandrel-plan --tickets <id>`.
+
+The container Epic (ADR `20260905-5139`) does **not** soften this. Its linkage
+runs parent→child only — the Epic body lists its children, and no Story body
+ever gains a footer pointing back — so a ticket carrying `Epic: #N` is still a
+v1 ticket and still refused.
 
 ---
 
@@ -573,6 +581,7 @@ the ticket or re-plan the work as a v2 Story via `/mandrel-plan --tickets <id>`.
 | `npx mandrel init` | Cold-start — install `mandrel` (if absent), `mandrel sync`, `bootstrap.js` (provisions repo + Projects V2 board, labels, branch protection), then the onboarding tail (stack detection, docs scaffolding, doctor gate, `/mandrel-plan` handoff). |
 | `/mandrel-plan --seed "<text>"` | Plan from chat text — interrogate → author **one Story by default** → persist `type::story`. |
 | `/mandrel-plan --seed-file <path>` | Plan from on-disk notes / a plan seed (the `/audit-to-stories` handoff). |
+| `/mandrel-deliver <epicId>` | Deliver every open Story under a container Epic — the id expands before resolution. |
 | `/mandrel-plan --tickets <ids>` | Analyze existing issue(s) into proper Stories (prefer an N=1 rewrite). |
 | `/mandrel-deliver <storyId>` | Deliver one Story via `helpers/deliver-story` — `story-<id>` → PR → `main`. |
 | `/mandrel-deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (resolved from live state), then run the per-run epilogue. |

package/.agents/instructions.md

@@ -147,9 +147,9 @@ sizing) **fail closed** naming what to trim:
   spawn only when the work justifies replicating context. One objective
   per subagent; depth compounds the cost (every nested level re-pays).
 - **Anti-Laziness / No Dead Code.** NEVER use placeholder comments like
-  `// ... existing code ...`; every edit must leave complete, runnable
-  code. Remove unused imports, commented-out code, and dead branches
-  before finalizing.
+  `// ... existing code ...`; every edit must leave complete, runnable code.
+  Remove unused imports, commented-out code, and dead branches before
+  finalizing.
 - **Verification.** Include explicit verification steps in every plan.
 
 ---
@@ -157,28 +157,29 @@ sizing) **fail closed** naming what to trim:
 ## 5. Git & Story Protocol (Strict Standards)
 
 [`rules/git-conventions.md`](rules/git-conventions.md) is the canonical
-reference: `story-<storyId>` branches seeded by `single-story-init.js`,
-every Story reaching `main` via its own PR
-(`helpers/deliver-story` / `single-story-close.js`).
+reference for branch shapes and commit subjects, and is always loaded —
+this section does not restate it.
 
 ### A. Status Tracking & Commit Standards
 
 State mutations are GitHub labels (`agent::ready`, `agent::executing`,
 `agent::done`) via
 `node .agents/scripts/update-ticket-state.js --ticket [ID] --state [STATUS]`.
-Do NOT manually update issue descriptions or status fields unless
-prompted.
+Do NOT manually update issue descriptions or status fields unless prompted.
 
-### B. Ticket hierarchy (Story-only)
+### B. Ticket hierarchy
 
-The v2 ticket model is Story-only: `acceptance[]` / `verify[]` live
+The Story is the only executable ticket: `acceptance[]` / `verify[]`
 inline plus the folded Tech Spec in `## Spec` (over-budget Specs fail
-closed — split or tighten; never write Specs under `docs/`). Optional
-`depends_on` edges order rare multi-Story runs, resolved by `/mandrel-deliver`
-from live state; the `plan-run::<id>` label is filter metadata only.
-Commit subjects reference the Story via `(refs #<storyId>)`. There is no
-`type::epic` / `type::task` label; `/mandrel-deliver` refuses tickets carrying an
-`Epic: #N` footer.
+closed — split or tighten; never under `docs/`). Optional `depends_on`
+edges order rare multi-Story runs, resolved by `/mandrel-deliver` from
+live state; `plan-run::<id>` is filter metadata. Commit subjects
+reference the Story via `(refs #<storyId>)`. There is no `type::task`.
+
+`type::epic` is a container only (goal + child checklist, no `agent::*`,
+never delivered): `/mandrel-plan` offers one above 2 Stories and
+`/mandrel-deliver <epicId>` expands it. Linkage is parent→child only, so
+an `Epic: #N` footer is still refused.
 
 ---