mandrel 2.12.0 → 2.13.0

package/.agents/workflows/deliver-light.md

@@ -0,0 +1,117 @@
+---
+description:
+  Single-session delivery for genuinely small work. Judges a prompt's
+  predicted footprint, authors a receipt Story, then lands it through the same
+  single-story-init / single-story-close engine — every close gate unchanged.
+---
+
+# /deliver-light "<prompt>" | --amends '#<id>' "<prompt>"
+
+> **Thin entry point, not a second engine.** `/deliver-light` removes the
+> `/plan` session for small work — nothing else. It runs a suitability gate,
+> authors a minimal receipt Story, then hands off to the SAME scripts
+> [`/deliver`](deliver.md) uses. Read
+> [`helpers/deliver-digest.md`](helpers/deliver-digest.md) once first — the
+> engine invariants, gates, and terminal-envelope contract below are its.
+
+## Role
+
+For a genuinely trivial change — a one-file fix, a small addition, a small
+amendment — the multi-session plan→deliver ceremony buys nothing the bare model
+lacks except **gates and landing**. `/deliver-light` keeps exactly those: one
+session straight to execution from an operator prompt, landing through the
+unchanged close path. It never relaxes a close gate, never bypasses the PR to
+`main`, and never lands over-scope work silently.
+
+## Four invariants (do not skip one)
+
+1. **Suitability gate.** The prompt's predicted footprint is judged by the
+   shared shape machinery (`deriveStoryShape` / `deriveChangeLevel`) **and** a
+   ledgered model verdict with a recorded reason. Both must agree on `lite`.
+2. **Over-scope stops — it never hard-fails.** An over-ceiling prompt STOPS and
+   asks the operator to escalate to `/plan` or proceed light. Under `--yes` it
+   fails closed to recommending `/plan`.
+3. **Diff-derived backstop.** After implementation the ACTUAL change set is
+   re-checked — the diff is the real scope signal — and an over-ceiling diff is
+   blocked rather than landed.
+4. **Minimal receipt Story.** A `type::story` is authored inline so `refs #`,
+   history, telemetry, and the `agent::executing → agent::done` state machine
+   all survive.
+
+## Procedure
+
+1. **Predict + gate.** Form the predicted footprint (new files, edited files,
+   acceptance count) and your ledgered verdict (a recorded reason for `lite`),
+   then run the gate:
+
+   ```bash
+   node .agents/scripts/deliver-light.js --prompt "<prompt>" \
+     --creates <csv> --refactors <csv> --acceptance <n> \
+     --route lite --reason "<why this is trivial>" [--amends '#<id>'] [--yes]
+   ```
+
+   Branch on `action` in the JSON envelope:
+   - **`proceed-light`** — the receipt Story is authored; read `storyId` and
+     `nextCommands`. Continue to step 2.
+   - **`ask-operator`** — predicted scope exceeds the light ceilings. STOP and
+     ask the operator to escalate to `/plan` or proceed light. Do not proceed
+     on your own.
+   - **`escalate-plan`** — over-scope under `--yes`: recommend `/plan` and stop.
+     `/deliver-light` never lands over-scope work.
+
+   `--amends '#<id>'` is the canonical light case — shape-checked identically; a
+   heavy amendment escalates to `/plan` like any other over-scope prompt.
+
+2. **Init (same engine).** From the main checkout, synchronously, with the
+   maximum Bash timeout:
+
+   ```bash
+   node .agents/scripts/single-story-init.js --story <storyId>
+   ```
+
+   Capture `workCwd`; `remoteVerified: false` → flip `agent::blocked` and stop.
+   This is [`/deliver`](deliver.md)'s worktree/branch/lease/label engine,
+   invoked, not reimplemented.
+
+3. **Implement + self-eval.** `cd` into `workCwd`, implement the change, run
+   `npm test` once in the worktree, then run the bounded acceptance self-eval
+   loop ([`helpers/deliver-story.md`](helpers/deliver-story.md) Step 1a). Commit
+   on `story-<id>` with `(refs #<storyId>)`.
+
+4. **Diff backstop.** Before close, re-check the ACTUAL diff:
+
+   ```bash
+   node .agents/scripts/deliver-light.js --backstop --story <storyId>
+   ```
+
+   Exit `3` (`blocked: true`) means the landed diff exceeds the light ceilings
+   (file count or a sensitive-path class). STOP, flip `agent::blocked`, and
+   escalate to `/plan` — do not land.
+
+5. **Close and land (same engine).** Exactly [`/deliver`](deliver.md)'s close:
+
+   ```bash
+   node .agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo>
+   ```
+
+   Branch on the terminal envelope's `status` per
+   [`helpers/deliver-digest.md`](helpers/deliver-digest.md) § 5 — every close
+   gate runs byte-identical to the full path.
+
+## Constraints
+
+- **Land or block — never a silent local build.** The close push is the only
+  sanctioned landing.
+- **No parallel engine.** `/deliver-light` invokes `single-story-init.js` and
+  `single-story-close.js`; it never reimplements worktree, branch, PR, or merge
+  mechanics.
+- **State only via `update-ticket-state.js`.** Drive every `agent::*`
+  transition through the script; report state, not process.
+
+## See also
+
+- [`/deliver`](deliver.md) — the multi-Story / planned delivery entry point.
+- [`helpers/deliver-story.md`](helpers/deliver-story.md) — the one Story
+  delivery engine both entry points share.
+- [`helpers/deliver-digest.md`](helpers/deliver-digest.md) — engine invariants,
+  gates, and the terminal-envelope contract.

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,14 @@
 
 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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.12.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/",