mandrel 2.11.0 → 2.13.0

package/.agents/workflows/helpers/deliver-reference.md

@@ -51,6 +51,16 @@ probe logs a warning and leans on init's lease refusal alone.
 
 ## Dispatch mechanics (role-scoped by default)
 
+**A single-Story run executes inline (Story #4736).** Sub-agent isolation is
+load-bearing only for **concurrent** dispatch — two workers sharing a checkout
+would race on worktrees and branch refs — so a run resolving exactly one Story
+has no sibling to isolate from and pays the spawn premium for nothing (a boot is
+a cache write at full rate; an inline continuation is a cache read at ~10%).
+`resolve-stories.js` already reports it: a one-id run comes back with
+`dispatchMode: "inline"` whatever the Story's shape. Role-scoped spawning is
+retained in full for multi-Story waves, and the rule changes **where** the
+engine runs, never what runs — gates, PR, and terminal envelope are identical.
+
 **Lite-shaped Stories execute inline (Story #4722).** Before spawning anything,
 read the Story's `dispatchMode` from the resolver envelope
 (`stories[].dispatchMode`, derived by `resolveStoryDispatchMode` in
@@ -114,6 +124,17 @@ execute it directly, in this turn, threading the same `docsDigestPath` /
 content, execute directly without a re-read turn. The engine, gates, and
 terminal envelope are identical either way — only the isolation differs.
 
+## Operator-merge implies no-wait
+
+`--no-auto-merge` and `delivery.ci.autoMerge: "strict"` leave the PR
+deliberately un-armed: there is nothing for close to land, so the Story rests
+at `agent::closing` for the human merge and is **not** flipped to
+`agent::blocked` — `--wait-merge` does not override this, because the operator
+owning the merge is a decision to respect, not a fault to report. A genuine
+*arm failure* is the opposite case: nobody chose it, so close still waits and
+still blocks. That asymmetry is what keeps the must-land contract intact
+without misfiling deliberate human merges as blocks.
+
 ## Per-run epilogue (N>1)
 
 Once the sequence reports `epilogueDue: true` (every Story done), keyed on the

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -341,6 +341,12 @@ The `single-story-close.js` script, in order:
 
 1. Runs the close-validation gates against `baseBranch` as the baseline.
    On any gate failure it throws — the operator fixes and re-runs close.
+   **Gate output is captured, not streamed (Story #4736).** Every gate line
+   goes to `temp/orchestration/close-gates-<storyId>.log`; a clean run reports
+   one digest line naming that artifact, and a **failed** gate replays its
+   captured tail inline so the evidence is in front of you without opening a
+   file. Read the artifact when you need the full text — or re-run under
+   `AGENT_LOG_LEVEL=verbose` for live streaming.
 1a. **Syncs the Story branch from `origin/<baseBranch>`** before push
    (Story #2580). Runs `git fetch origin <baseBranch>` followed by
    `git merge --no-edit origin/<baseBranch>` inside the worktree. This

package/.agents/workflows/helpers/deliver-story.md

@@ -11,6 +11,13 @@ description:
 > reference detail lives in
 > [`deliver-story-reference.md`](deliver-story-reference.md) ("reference"
 > below); consult on demand. Invoked by [`/deliver`](../deliver.md).
+>
+> **Read [`deliver-digest.md`](deliver-digest.md) once, first.** It is the
+> one bundled read of what every delivery needs — dispatch decision, engine
+> invariants, the change-set/ceremony incantation, the acceptance-eval gate,
+> and the terminal-envelope contract — replacing the per-session re-reads of
+> the helper set and `story-deliver-terminal.schema.json` (Story #4736). The
+> steps below cite it as "digest § N" rather than restating it.
 
 ## Overview
 
@@ -74,15 +81,10 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
 
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 
-Follow the single-homed include
-[`acceptance-self-eval.md`](acceptance-self-eval.md) (single verdict-owner,
-`verify[]`-as-evidence, proceed / redraft / block). Gate invocation (omit
-`--epic`):
-
-```bash
-node <main-repo>/.agents/scripts/acceptance-eval.js \
-  --story <storyId> --verdict <verdict-path>
-```
+Run the loop and score it with `acceptance-eval.js` — **digest § 4** carries
+the invocation and the proceed / redraft / block contract; per-round critic
+mechanics live in the single-homed include
+[`acceptance-self-eval.md`](acceptance-self-eval.md).
 
 **`proceed`** → Step 2 then Step 3. **`block`** → **do not close**: post a
 `friction` comment and flip `agent::blocked` — commands and the
@@ -92,16 +94,12 @@ node <main-repo>/.agents/scripts/acceptance-eval.js \
 ## Step 2 — Ceremony (profile + derived level)
 
 Ceremony is `delivery.routing.ceremonyProfile` × the **derived change
-level** — never a planner-authored verdict (Story #4542).
-**Compute the change set once** (Story #4593) with the shared enumerator
-[`computeChangeSet`](../../scripts/lib/orchestration/change-set.js) — the
-same module close uses — and hand that one list to every critic. Derive the
-level with `deriveChangeLevel`, resolve fresh-vs-inline critics with
-`resolveCeremonyForRisk` (`ceremony-routing.js`); a lite Story runs inline
-regardless (exact incantation and routing rules: reference § Step 2).
-Hard gates (lint / test / format / coverage / CRAP / maintainability)
-always run in Step 3 — the derived level never disables them; do **not**
-pre-run the full close chain here.
+level** — never a planner-authored verdict (Story #4542). **Digest § 3** is
+the incantation: compute the change set once (Story #4593), derive the level,
+resolve fresh-vs-inline critics with `ceremony-routing.js`; a lite Story runs
+inline regardless (routing edge cases: reference § Step 2). Hard gates always
+run in Step 3 — the derived level never disables them; do **not** pre-run the
+close chain here.
 
 ## Step 3 — Close and land (`single-story-close.js`)
 
@@ -110,15 +108,12 @@ node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <
 ```
 
 **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
-post-land tail in one process. Run it and **branch on the terminal
-envelope's `status`** (Story #4543):
-
-| `status` | Exit | Meaning | You do |
-| --- | --- | --- | --- |
-| `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land). | Relay the envelope (Step 7). |
-| `pending` | 3 | **Resumable, not a failure** — wait expired healthy, or a human owns the merge. | Run `nextCommand` until resolved. |
-| `blocked` | 1 | Hard block; `blocked.blockClass` names it. | `checks-failed` → Step 4; else relay. |
-| `failed` | 1 | A phase crashed; `phase` names which. | Diagnose, fix, re-run close. |
+post-land tail in one process. Run it and **branch on the terminal envelope's
+`status`** per the table in **digest § 5** (`landed` → Step 7; `pending` → run
+`nextCommand`; `blocked`/`checks-failed` → Step 4; `failed` → diagnose and
+re-run). Gate output is captured to
+`temp/orchestration/close-gates-<storyId>.log` — a clean run prints a digest
+line, a red gate replays its tail inline (Story #4736).
 
 Internals (gate order, base-sync, auto-merge arming), the merge-wait
 budgets, the slow-CI **async** confirm mode (Story #4698 — launch the
@@ -143,13 +138,13 @@ recovery path **only** when the envelope routes you there:
 
 ## Step 7 — Return contract (**required as a sub-agent**) {#return-contract}
 
-The contract is the shipped schema
-[`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
-— the SSOT for every field (Story #4543). End your turn by relaying the
-validated envelope close emits between its `--- STORY DELIVER TERMINAL ---`
-markers — never free-form prose, never a hand-composed object. `pending` is
-the only sanctioned no-merge ending, returned only when your own budget is
-exhausted (Story #1553). Reference § Step 7.
+End your turn by relaying the validated envelope close emits between its
+`--- STORY DELIVER TERMINAL ---` markers — never free-form prose, never a
+hand-composed object. Statuses, exits, and required fields: **digest § 5**
+(whose SSOT is the shipped
+[schema](../../schemas/story-deliver-terminal.schema.json), Story #4543).
+`pending` is the only sanctioned no-merge ending, returned only when your own
+budget is exhausted (Story #1553). Reference § Step 7.
 
 ## Recovering a stranded Story {#recover}
 
@@ -175,6 +170,7 @@ reuses an open PR).
 
 ## See also
 
+- [`deliver-digest.md`](deliver-digest.md) — the one bundled framework read.
 - [`/deliver`](../deliver.md) — unified entry point.
 - [`deliver-story-reference.md`](deliver-story-reference.md) — all on-demand
   detail.

package/.agents/workflows/plan.md

@@ -7,8 +7,7 @@ description:
 
 # /plan --seed "<text>" | --seed-file <path> | --tickets <ids>
 
-> **Lean spine.** Happy path + gate list; edge-case and reference detail
-> lives in the on-demand
+> **Lean spine.** Happy path + gate list; edge-case detail lives in on-demand
 > [`helpers/plan-reference.md`](helpers/plan-reference.md).
 
 ## Inputs
@@ -20,9 +19,9 @@ Epic/Story router, no scope-triage `epic|story` verdict:
 | --- | --- |
 | `/plan --seed "<text>"` / `--seed-file <path>` | Ideation from chat text or on-disk notes: interrogate → author **one Story by default** → persist. |
 | `/plan --tickets 123[,456…]` | Fetch issue(s), analyze into proper Stories (prefer N=1 rewrite). |
+| `/plan --amends #<id>` | Amend a shipped Story from a **delta envelope** (prior body + acceptance + delivered file map), not a from-scratch re-interrogation (#4741). |
 
-`--body` is **not** a `/plan` entry; persist always goes through
-`plan-persist.js`.
+`--body` is **not** a `/plan` entry; persist always goes through `plan-persist.js`.
 
 ## Flags
 
@@ -30,23 +29,24 @@ Epic/Story router, no scope-triage `epic|story` verdict:
 | --- | --- |
 | `--seed "<text>"` / `--seed-file <path>` | Seed text / pre-authored notes path. |
 | `--tickets <ids>` | Issue ids to analyze; closed as superseded at persist. |
+| `--amends #<id>` | Prior Story to amend; emits a delta envelope, not a full re-interrogation (#4741). |
+| `--chain-on-clean` | Persist: chain a clean lite dry-run into the real persist in one round-trip; full-route plans keep the review round-trip (#4741). |
 | `--no-close-superseded` | Keep the source issues open — no supersede comment, no close. |
-| `--force-review` | STOP at gate #2 for operator review — the only review gate (Story #4542). |
-| `--route-downgrade-reason "<text>"` | Authored `lite` verdict + reason (Story #4722), ledgered per Story; shape-validated, fails closed to `full`. |
+| `--force-review` | STOP at gate #2 for operator review — the only review gate (#4542). |
+| `--route-downgrade-reason "<text>"` | Authored `lite` verdict + reason (#4722); shape-validated, fails closed to `full`. |
 | `--allow-over-budget` | Permit a plan exceeding `maxTickets`. |
 | `--yes` | Non-interactive: auto-proceed gate #1 and gate #2 HITL waits. |
 | `--dry-run` | Author + validate without GitHub writes; run as a pre-pass. |
 
 ## Default-single split policy
 
-Author **one Story** unless (1) the pieces have **near-zero overlap**
-(genuinely independent capabilities), or (2) there is an **architectural
-seam** (different deployables, migration vs consumer). Coupled work stays
-one Story — decompose it inside `## Slicing` as intra-session checkpoints,
-not sibling tickets. When N>1, every acceptance criterion belongs to exactly
-one Story (`assertAcceptancePartition` refuses coupled splits). **N=1 is the
-lean path:** one authoring prompt, folded `## Spec`, light risk/critic
-profile — no Epic-scale ceremony.
+Author **one Story** unless the pieces have **near-zero overlap** (genuinely
+independent capabilities) or sit across an **architectural seam** (different
+deployables, migration vs consumer). Coupled work stays one Story —
+`## Slicing` intra-session checkpoints, not sibling tickets; when N>1 every
+acceptance criterion belongs to exactly one Story
+(`assertAcceptancePartition` refuses coupled splits). **N=1 is the lean
+path:** one authoring prompt, folded `## Spec`, no Epic-scale ceremony.
 
 ## Procedure
 
@@ -55,69 +55,52 @@ profile — no Epic-scale ceremony.
 ```bash
 node .agents/scripts/plan-context.js --seed "<seed>" \
   --out temp/plan-<slug>/plan-context.json
-# or: --seed-file <path>
-# or: --tickets 123,456
+# or: --seed-file <path>  |  --tickets 123,456  |  --amends #<id>
 ```
 
-**Always pass `--out`.** Persist auto-discovers that envelope from
-`--plan-dir` and derives source-ticket ids from its `sourceTickets[]`
-(Story #4554); the CLI also writes **`stories.template.json`** — the
-authoring skeleton step 2 starts from.
-
-The envelope carries docs context, codebase snapshot, the story-author
-prompt, `sourceTickets[]`, `duplicates[]` (open **Stories** overlapping the
-seed — never Epics), and advisory `complexitySignals` (**no routing
-authority**, Story #4722). A genuinely trivial scope earns
-`--route-downgrade-reason "<why>"` at persist — shape-validated, failing
-closed to `full`. Detail:
-[`helpers/plan-reference.md` § Shape-derived routing](helpers/plan-reference.md).
-Under `--yes`, do not ask free-form operator questions — unresolved
-unknowns land in Key Assumptions.
+**Always pass `--out`.** Persist auto-discovers that envelope from `--plan-dir`
+and derives source-ticket ids from its `sourceTickets[]` (#4554); the CLI also
+writes **`stories.template.json`** — the authoring skeleton step 2 starts from.
+
+The envelope carries docs context, the codebase snapshot, the story-author
+prompt, `sourceTickets[]`, `duplicates[]` (open **Stories**, never Epics), and
+advisory `complexitySignals` (**no routing authority**, #4722). A trivial scope
+earns `--route-downgrade-reason "<why>"` at persist — shape-validated, failing
+closed to `full`
+([detail](helpers/plan-reference.md)).
+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.
+duplicate-candidate review. Under `--yes`, auto-proceed. When
+`complexitySignals.deliverLightSuggestion.suggested` is `true`, surface an
+**advisory** `/deliver-light` suggestion — the operator decides; under `--yes`
+it is recorded and planning proceeds, **never an automatic reroute** (#4741).
 
 ### 2. Author
 
 **One-shot authoring (Story #4707).** Start from `stories.template.json`;
 author `stories.json` in one pass. Entries are pre-resolved (#4723); keep
-tiers/assumptions valid. `body` is a
-markdown string **or** a structured object; persist parses either,
-serializes the canonical markdown, and syncs the top-level `acceptance[]` /
-`verify[]` into the body — never dual-author those lists.
-
-```jsonc
-// temp/plan-<slug>/stories.json
-[
-  {
-    "slug": "hyphen-case-slug", // ^[a-z0-9][a-z0-9-]*$
-    "type": "story",
-    "title": "Short descriptive title",
-    "body": {
-      "goal": "One sentence: why this Story exists.",
-      "spec": "Optional — contract and invariants.",
-      "changes": [{ "path": "path/to/file.ext", "assumption": "refactors-existing" }], // creates | refactors-existing | deletes
-      "non_goals": [],
-      "reason_to_exist": "One coherent reason this Story exists."
-    },
-    "acceptance": ["A testable, observable criterion"],
-    "verify": ["exact command (unit|contract|e2e|validate)"],
-    "depends_on": [] // sibling Story slugs, N>1 only
-  }
-]
-```
+tiers/assumptions valid. `body` is a markdown string **or** a structured
+object; persist parses either, serializes the canonical markdown, and syncs the
+top-level `acceptance[]` / `verify[]` into it — never dual-author those lists.
+
+Each entry (the `stories.template.json` shape): `slug`
+(`^[a-z0-9][a-z0-9-]*$`), `type: "story"`, `title`, `body` (`goal`, optional
+`spec`, `changes[{path, assumption}]` — `creates|refactors-existing|deletes`,
+`non_goals`, `reason_to_exist`), top-level `acceptance[]`, `verify[]`
+(`… (unit|contract|e2e|validate)`), `depends_on[]` (N>1 only).
 
 Artifacts under `temp/plan-<slug>/`: `stories.json`
 (**length 1 by default**; over-budget Specs fail closed — split or tighten,
-never write Specs under `docs/`); optional `techspec.md` (**N===1 only** —
-folded into `## Spec`); optional `acceptance-manifest.json` (N>1 partition
-list — pass 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.
+never under `docs/`); optional `techspec.md` (**N===1 only** — folded into
+`## Spec`); optional `acceptance-manifest.json` (N>1 partition list — pass as
+`--plan-acceptance`). For N=1, use the envelope `systemPrompts.story` and emit
+one cohesive Story. Split only under the policy above.
 
-**Tickets mode:** every Story authors a top-level `supersedes[]` claiming
-the source issues it replaces; persist refuses a partial map (shape:
-[`helpers/plan-reference.md` § Tickets mode](helpers/plan-reference.md)).
+**Tickets mode:** every Story authors a top-level `supersedes[]` claiming the
+source issues it replaces; persist refuses a partial map
+([shape](helpers/plan-reference.md)).
 
 ### 2.5 Critics
 
@@ -147,9 +130,9 @@ ledgered: **do not proceed to Persist**; fix and re-run.
 **only** trigger). Under `--yes`, auto-proceed.
 
 Run persist with `--dry-run` **first** — same command, GitHub writes
-suppressed; every gate (ticket validator, body parse, DAG, capacity,
-budget, reachability, split-policy and supersede partitions, Spec fold)
-runs before the first `createIssue`. Then:
+suppressed; every gate (validator, body parse, DAG, capacity, budget,
+reachability, split/supersede partitions, Spec fold) runs before the first
+`createIssue`. Then:
 
 ```bash
 node .agents/scripts/plan-persist.js \
@@ -160,30 +143,29 @@ node .agents/scripts/plan-persist.js \
   [--source-tickets 123,456] [...flags from the table above]
 ```
 
-Persist creates Story issue(s) with `type::story` plus a `plan-run::<id>`
-grouping label (**metadata only** — never a delivery-resolution input, Story #4692); N>1 `depends_on` edges become `blocked by #<id>` body footers.
-`agent::ready` is the **terminal** flip, after all receipts are upserted — a
-ready Story is always fully persisted (Story #4541). stdout is pure JSON
-(logs on stderr).
+At lite shape, `--chain-on-clean` chains that dry-run into the real persist in
+one round-trip **only** when it is clean and `lite`; a full-route plan keeps
+its review round-trip (#4741).
+
+Persist creates `type::story` issue(s) plus a `plan-run::<id>` grouping label
+(**metadata only**, #4692); N>1 `depends_on` edges become `blocked by #<id>`
+footers. `agent::ready` is the **terminal** flip after all receipts land — a
+ready Story is fully persisted (#4541). stdout is pure JSON.
 
-In `--tickets` mode persist resolves source ids **envelope-first** and
-closes each superseded source as `not_planned` with a comment (default on).
-Detail (channels, close contract, resume, temp hygiene):
-[`helpers/plan-reference.md`](helpers/plan-reference.md) — on a stranded
-persist, re-run the same command; never hand-delete issues.
+In `--tickets` mode persist resolves source ids **envelope-first** and closes
+each as `not_planned` with a comment (default on;
+[detail](helpers/plan-reference.md)). On a stranded persist, re-run the same
+command — never hand-delete issues.
 
 ## Constraints
 
-- `/plan` never starts delivery. No Epic ticket, no reconciler, no
-  `delivery::single` marker.
-- Duplicate search targets open Stories (`type::story`), not Epics.
+- `/plan` never starts delivery — no Epic ticket, no reconciler. Duplicate
+  search targets open Stories (`type::story`), not Epics.
 - Deterministic gates still fail closed under `--yes`.
 
 ## See also
 
-- [`/deliver`](deliver.md) — delivery entry point.
-- [`/audit-to-stories`](audit-to-stories.md) — audit findings → plan seed.
-- [`helpers/plan-reference.md`](helpers/plan-reference.md) — on-demand
-  detail.
+- [`/deliver`](deliver.md), [`/audit-to-stories`](audit-to-stories.md),
+  [`helpers/plan-reference.md`](helpers/plan-reference.md) — on-demand detail.
 - [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) — optional
   split-advisory notes only (no routing verdict).

package/docs/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.13.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.12.0...mandrel-v2.13.0) (2026-07-24)
+
+
+### Added
+
+* **orchestration:** add /deliver-light — validated single-session delivery with full gates (refs [#4740](https://github.com/dsj1984/mandrel/issues/4740)) ([#4742](https://github.com/dsj1984/mandrel/issues/4742)) ([605c20b](https://github.com/dsj1984/mandrel/commit/605c20b5ce9c17c6dc7c40356a2e496bb2f25a44))
+* plan-phase turn diet: same artifacts, fewer round-trips, amendment-aware envelope ([#4741](https://github.com/dsj1984/mandrel/issues/4741)) ([#4744](https://github.com/dsj1984/mandrel/issues/4744)) ([65b6790](https://github.com/dsj1984/mandrel/commit/65b67900ae58aea8a15e8a96e28895b1283df079))
+
+## [2.12.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.11.0...mandrel-v2.12.0) (2026-07-24)
+
+
+### Performance
+
+* **orchestration:** cut deliver-path cost — inline single-Story dispatch, bounded close output, bundled reads (refs [#4736](https://github.com/dsj1984/mandrel/issues/4736)) ([#4737](https://github.com/dsj1984/mandrel/issues/4737)) ([81e62a8](https://github.com/dsj1984/mandrel/commit/81e62a87ca49add2aeb5b5a6b9ac11014edc3374))
+
+
+### Changed
+
+* **orchestration:** thread injectedRules seam through route composition layers ([#4734](https://github.com/dsj1984/mandrel/issues/4734)) ([6e1daad](https://github.com/dsj1984/mandrel/commit/6e1daadbc24210fdb34e4892c0077256f2ccd051))
+
 ## [2.11.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.10.0...mandrel-v2.11.0) (2026-07-23)
 
 

package/package.json

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