mandrel 2.14.0 → 2.16.0

package/.agents/workflows/helpers/worktree-lifecycle.md

@@ -108,10 +108,7 @@ PowerShell `Get-CimInstance Win32_Process`, terminating them with
 
 > **Not a slash command (decision overturned).** The drain is **not** a
 > `/drain-pending-cleanup` slash command — it was demoted to a
-> directly-runnable script (Story #3706, overturning the
-> `docs/decisions.md` matrix row that originally kept it as a command).
-> The wave-era automatic callers were deleted with the epic-runner in
-> the v2 cutover, so the drain is now operator-driven:
+> directly-runnable script. The drain is operator-driven:
 > `node .agents/scripts/drain-pending-cleanup.js`.
 
 ### When to run it manually

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

@@ -4,7 +4,7 @@ description: >-
   (resolve newest published version → install → re-materialize `.agents/` →
   migrate → doctor → surface changelog) as the single mechanical step, then
   walks the operator through the judgment wraparound the CLI deliberately
-  leaves unowned: reconcile `.agentrc.json`, install the Epic #1386
+  leaves unowned: reconcile `.agentrc.json`, install the stabilized
   quality-gate surface, refresh the harness permission allowlist, reconcile
   the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and
   stage + commit the staged lockfile bump.
@@ -14,10 +14,10 @@ description: >-
 
 > **Upgrade owner.** The mechanical upgrade is owned end to end by the
 > [`mandrel update`](../../lib/cli/update.js) CLI under the npm distribution
-> model (#3436/#3437). This workflow wraps that CLI: it runs
+> model. This workflow wraps that CLI: it runs
 > `npx mandrel update`, then walks the operator through the
 > **distribution-agnostic judgment steps** the CLI deliberately does **not**
-> perform — config reconciliation, the Epic #1386 quality-gate installs, the
+> perform — config reconciliation, the quality-gate installs, the
 > permission-allowlist refresh, the consumer-side changelog reconciliation,
 > and the stage-and-commit of the staged lockfile bump.
 
@@ -125,7 +125,7 @@ Recovery sequence: run the matching remedy, then **re-run
 `npx mandrel update`** — it is idempotent (the install already landed, so a
 clean re-run short-circuits the bump and re-drives the post-install
 phases). Repeat until it reports success; only then proceed. A dedicated
-`--resume` entrypoint was evaluated and deferred (Story #4172) — the
+`--resume` entrypoint was evaluated and deferred — the
 per-phase remedies plus the idempotent re-run already cover every recovery
 case.
 
@@ -135,7 +135,7 @@ case.
 node .agents/scripts/sync-agentrc.js
 ```
 
-The helper (Story #1995) is default-aware and **read-only**: it validates
+The helper is default-aware and **read-only**: it validates
 the consumer config against the new schema (non-zero exit → fix the
 validation error and re-run before proceeding), never auto-fills missing
 optional keys (the runtime layers defaults at read time), and flags
@@ -144,7 +144,7 @@ advisory rows you may optionally delete by hand (commit alongside the bump
 in Step 5). Full procedure:
 [`helpers/mandrel-sync-config.md`](helpers/mandrel-sync-config.md).
 
-## Step 3.5 — Upgrade the stabilized-quality-gates surface (Epic #1386)
+## Step 3.5 — Upgrade the stabilized-quality-gates surface
 
 ```bash
 node .agents/scripts/apply-quality-bootstrap.js

package/.agents/workflows/plan.md

@@ -5,48 +5,50 @@ description:
   policy.
 ---
 
-# /plan --seed "<text>" | --seed-file <path> | --tickets <ids>
+# /plan
 
 > **Lean spine.** Happy path + gate list; edge-case detail lives in on-demand
 > [`helpers/plan-reference.md`](helpers/plan-reference.md).
 
 ## Inputs
 
-Single planning path — there is no
-Epic/Story router, no scope-triage `epic|story` verdict:
+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, then act**; there is nothing for them to remember:
 
-| Invocation | Behavior |
-| --- | --- |
-| `/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). |
+| Invocation | Mode | Behavior |
+| --- | --- | --- |
+| `/plan` | ask | Ask what to plan; nothing runs first. |
+| `/plan add a --json flag to doctor` | seed | Ideation from the prose: interrogate → author **one Story by default** → persist. |
+| `/plan temp/notes/idea.md` | seed-file | Same, from notes. An argument resolving to an existing file is a path, never prose. |
+| `/plan 4712[,4713…]` | tickets | Fetch issue(s), analyze into proper Stories (prefer N=1 rewrite). |
+| `/plan 4712`, already delivered | amends | Amend a shipped Story from a **delta envelope**, not a re-interrogation. |
 
-`--body` is **not** a `/plan` entry; persist always goes through `plan-persist.js`.
+**Resolving a bare id.** Ids alone are ambiguous between *amend* and *tickets*,
+so 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" — so a wrong read costs one correction, not a
+wasted run. Ask **only** for an open Story already at `agent::ready`.
 
-## Flags
+`--body` is **not** a `/plan` entry; persist goes through `plan-persist.js`.
 
-| Flag | Meaning |
-| --- | --- |
-| `--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 (#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. |
+## Saying what you want
+
+No flags to remember — state intent and the workflow fills in the CLI
+([reference](helpers/plan-reference.md)). Run any script with `--help` rather
+than copying its surface here.
+
+`--yes` is **runner-set, never operator-typed** — cron, `/loop`, and headless
+dispatch set it to mean *nobody is at the keyboard*, which is what auto-proceeds
+the gates below. Never offer it to an operator or add it to an attended run.
 
 ## Default-single split policy
 
-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.
+Author **one Story** unless the pieces have **near-zero overlap** or sit across
+an **architectural seam** (different deployables, migration vs consumer).
+Coupled work stays one Story — `## Slicing` 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.**
 
 ## Procedure
 
@@ -58,49 +60,53 @@ node .agents/scripts/plan-context.js --seed "<seed>" \
 # 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[]` (#4554); the CLI also
-writes **`stories.template.json`** — the authoring skeleton step 2 starts from.
+**Always pass `--out`.** Persist auto-discovers the envelope from `--plan-dir`
+and derives source ids from its `sourceTickets[]`; the CLI also writes
+**`stories.template.json`**, the 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.
+advisory `complexitySignals` (**no routing authority**). 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 — unknowns land in Key Assumptions.
 
 **Gate #1** — STOP to confirm the sharpened plan intent and any
-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).
+duplicate-candidate review. Under `--yes`, auto-proceed.
+
+When `complexitySignals.deliverLightSuggestion.suggested` is `true`, offer —
+**advisory, never an automatic reroute** — to deliver the seed instead of
+planning it. On confirm, route **in this session** into
+[`helpers/deliver-light.md`](helpers/deliver-light.md), filling its gate from
+this envelope, not the raw seed; an `ask-operator` verdict returns here to
+step 2 with the interrogation intact. Under `--yes` it is recorded and planning
+proceeds — never auto-downgraded to light.
+
+A truthy `complexitySignals.uiSurface` marks a UI-touching plan: name
+[`/prototype`](prototype.md) as an operator option — never invoke it here.
 
 ### 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 it — never dual-author those lists.
+**One-shot authoring.** Start from `stories.template.json`; author
+`stories.json` in one pass. Entries are pre-resolved; keep tiers/assumptions
+valid. `body` is a markdown string **or** a structured object; persist parses
+either, serializes the canonical markdown, and syncs 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).
+`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 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.
+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 list — `--plan-acceptance`). For N=1
+use the envelope `systemPrompts.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:** every Story authors a top-level `supersedes[]`; persist
+refuses a partial map ([shape](helpers/plan-reference.md)).
 
 ### 2.5 Critics
 
@@ -110,29 +116,28 @@ node .agents/scripts/plan-critics.js \
   [--tech-spec temp/plan-<slug>/techspec.md]
 ```
 
-Run **before** persist — the last point a finding folds into a re-author
-round. 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.
+Run **before** persist — the last point a finding folds into a re-author round.
+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.
 
 - **Both `dispatch: false`** — proceed to Persist (each skip is ledgered).
 - **Either `dispatch: true`** — dispatch **one fresh-context, maker-blind
-  sub-agent per firing critic** (hand it only the draft artifacts,
-  never the authoring transcript), fold findings into Gate #2 or a
-  re-author round, re-run this step. Pre-mortem triggers (incl. the
-  external-dependency probe, #4700), folding the advisory-only
-  `textHygiene.findings[]` lints, and the role-scoped dispatch shape:
+  sub-agent per firing critic** (hand it only the draft artifacts, never the
+  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 the dispatch shape:
   [`helpers/plan-reference.md` § Critic dispatch detail](helpers/plan-reference.md).
 
 ### 3. Persist
 
-**Gate #2** — with `--force-review`, STOP for approval before persist (the
-**only** trigger). Under `--yes`, auto-proceed.
+**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, GitHub writes
-suppressed; every gate (validator, body parse, DAG, capacity, budget,
-reachability, split/supersede partitions, Spec fold) runs before the first
-`createIssue`. Then:
+Run persist with `--dry-run` **first** — same command, GitHub writes 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 \
@@ -140,27 +145,27 @@ 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] [...flags from the table above]
+  [--source-tickets 123,456]
 ```
 
 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).
+one round-trip **only** when it is clean and `lite`; a full plan keeps its
+review round-trip.
 
 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.
+(**metadata only**); N>1 `depends_on` edges become `blocked by #<id>` footers.
+`agent::ready` is the **terminal** flip after all receipts land. stdout is pure
+JSON.
 
-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.
+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)).
 
 ## Constraints
 
-- `/plan` never starts delivery — no Epic ticket, no reconciler. Duplicate
-  search targets open Stories (`type::story`), not Epics.
+- `/plan` starts delivery **only** through a confirmed Gate #1 light route —
+  never off its own authored Stories, which land via [`/deliver`](deliver.md).
+- Duplicate search targets open Stories (`type::story`), not Epics.
 - Deterministic gates still fail closed under `--yes`.
 
 ## See also

package/.agents/workflows/prototype.md

@@ -0,0 +1,104 @@
+---
+description: >-
+  Operator-invoked UI prototype pass. Discovers the consumer's design-system
+  SSOT first, then — only after the operator confirms — writes exactly one
+  self-contained HTML file under the gitignored workspace-root temp tree, so a
+  layout can be reviewed before its UI acceptance criteria are authored.
+---
+
+# /prototype [what to prototype]
+
+UI acceptance criteria are otherwise authored blind: "the dashboard shows the
+active runs" says nothing about layout, density, or interaction, so delivery
+resolves those by taste. `/prototype` puts a reviewable artifact in front of the
+operator before the criteria are written.
+
+**Operator-invoked only.** `/plan` may report that a plan touches UI and that
+this command exists; it must never run it. No workflow, gate, or script invokes
+`/prototype` — the whole design rests on the operator asking for it.
+
+## Procedure
+
+### Step 0 — Discover the design-system SSOT (first, before anything is drawn)
+
+You cannot prototype *in the project's visual language* until you have found the
+language. Locate and read the consumer's sources of truth — the same set
+[`/audit-ux-ui`](audit-ux-ui.md) Step 0 mandates:
+
+- **Design tokens / theme** — a `tailwind.config.{js,ts}`, CSS custom properties
+  (`:root { --color-*, --space-* }`), a `theme/` / `tokens/` /
+  `design-system/` directory, or a CSS-in-JS theme object.
+- **Component roster** — the shared component directory (`components/ui/**`, a
+  published design-system package) that raw elements are expected to defer to.
+- **Documented conventions** — `docs/style-guide.md`, plus `docs/web-routes.md`
+  when the surface is a route, whenever they exist in the consumer checkout.
+
+Report what you found — token names, the component roster, the style-guide rules
+— and draw only against that discovered baseline. **No artifact is drawn until
+this step has run.**
+
+### Step 0a — When no design-system SSOT is discoverable
+
+Report the absence explicitly, then emit a **low-fidelity frame**: boxes,
+labels, and hierarchy, in the host's default typography with no colour system.
+Do **not** invent a visual language. A prototype in a palette the project never
+adopted reviews the invention rather than the layout, and the operator cannot
+tell which of the two they are approving.
+
+### Step 1 — Confirm before writing (**hard gate**)
+
+Describe the layout you intend — surfaces, hierarchy, states, and which
+discovered tokens and components it reuses — and **STOP**. Nothing is written to
+disk until the operator confirms; never write silently. This is the disk-write
+policy [`core/idea-refinement`](../skills/core/idea-refinement/SKILL.md) already
+applies to its one-pager.
+
+### Step 2 — Write exactly one self-contained HTML file
+
+On confirm, write **exactly one** self-contained `.html` file — inline CSS, no
+build step, no fetched external assets — under the **gitignored workspace-root
+temp tree** (`temp/prototypes/<slug>.html`). One file, because a prototype is a
+thing to look at, not a codebase to maintain; self-contained, because it has to
+open from disk with no server and no install.
+
+Report the path, and iterate in place on that same file.
+
+### Step 3 — Optional: publish to a host
+
+Host publishing is an **optional upgrade of that same file** and never the
+artifact of record — the file under the temp tree stays authoritative. Publish
+only when the operator asks, and keep the two identical by re-publishing the
+file rather than editing a published copy.
+
+### Step 4 — Carry the review through to the Story
+
+The **default carry-through is a fold into the Story's `## Spec`.** Delivery
+reads the Story body and never the temp tree, so a layout that exists only as a
+temp artifact is a layout delivery cannot see. Record the reviewed decisions —
+surfaces, hierarchy, states, and the named tokens and components — as contract
+prose in `## Spec`, and turn the observable ones into UI acceptance criteria.
+
+**Committing a prototype is opt-in, per Story.** Ask; never default to it. A
+prototype is wrong the moment the real UI ships, and a repository with a
+documentation-freshness gate already carries that failure mode.
+
+## Constraint
+
+- **Nothing reaches disk without a confirm.** Step 1 is a hard gate, not a
+  courtesy.
+- **One file, under the temp tree.** Never a second artifact, never outside the
+  gitignored workspace-root temp tree, and never a committed prototype
+  directory by default.
+- **Never invoked automatically.** `/plan` records the offer and proceeds with
+  planning; no workflow, gate, or script may call this command.
+- **Read-only over the codebase.** The prototype file is the only write. Do not
+  edit application source, tokens, or components to make a prototype render.
+- **Discovered baseline only.** No invented palette, type scale, or component
+  vocabulary when the project defines none.
+
+## See also
+
+- [`/audit-ux-ui`](audit-ux-ui.md) — the same design-system SSOT discovery,
+  applied as a review lens after the UI ships.
+- [`/plan`](plan.md) — where the advisory `complexitySignals.uiSurface` offer
+  surfaces. It names this command; it never runs it.

package/docs/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.16.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.15.0...mandrel-v2.16.0) (2026-07-25)
+
+
+### Added
+
+* **workflows:** add operator-invoked /prototype and an advisory uiSurface offer (refs [#4765](https://github.com/dsj1984/mandrel/issues/4765)) ([#4769](https://github.com/dsj1984/mandrel/issues/4769)) ([d3f7173](https://github.com/dsj1984/mandrel/commit/d3f71734ef8573ffa40187b5f4f8a97be6e32041))
+
+
+### Fixed
+
+* **close-validation:** drain gate output without stalling the child's pipe (refs [#4766](https://github.com/dsj1984/mandrel/issues/4766)) ([#4770](https://github.com/dsj1984/mandrel/issues/4770)) ([fd75550](https://github.com/dsj1984/mandrel/commit/fd75550288411a4c92831ac7c9b946e2cce5a686))
+
+
+### Changed
+
+* **routing:** scope the light path by effort and risk (refs [#4764](https://github.com/dsj1984/mandrel/issues/4764)) ([#4767](https://github.com/dsj1984/mandrel/issues/4767)) ([c4851ab](https://github.com/dsj1984/mandrel/commit/c4851abe218721145daaeb4353af400223b588e6))
+
+## [2.15.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.14.0...mandrel-v2.15.0) (2026-07-25)
+
+
+### Added
+
+* gate the workflow read-tier with a transitive mandatory-closure ratchet ([#4752](https://github.com/dsj1984/mandrel/issues/4752)) ([#4755](https://github.com/dsj1984/mandrel/issues/4755)) ([ac0f1e0](https://github.com/dsj1984/mandrel/commit/ac0f1e038560f4d69146f6dae46c2eb97ae2dbb2))
+* make workflow-invoked orchestration scripts self-describing via --help ([#4750](https://github.com/dsj1984/mandrel/issues/4750)) ([#4756](https://github.com/dsj1984/mandrel/issues/4756)) ([922c278](https://github.com/dsj1984/mandrel/commit/922c278ed15f77761c88366ce6d166e0a0dd9157))
+* **workflows:** one delivery door and derived invocation intent (refs [#4760](https://github.com/dsj1984/mandrel/issues/4760)) ([#4761](https://github.com/dsj1984/mandrel/issues/4761)) ([36bff50](https://github.com/dsj1984/mandrel/commit/36bff502b7d4e475569da7cae2eb0ec66d24b85d))
+
+
+### Fixed
+
+* **deps:** bump brace-expansion to 5.0.8 for GHSA-mh99-v99m-4gvg ([#4753](https://github.com/dsj1984/mandrel/issues/4753)) ([3351100](https://github.com/dsj1984/mandrel/commit/3351100801b70e9e17cf3ed99245b3d81e162232))
+* **tests:** resolve cli-usage argv[1] with fileURLToPath for Windows ([#4759](https://github.com/dsj1984/mandrel/issues/4759)) ([7fa3ee1](https://github.com/dsj1984/mandrel/commit/7fa3ee1e17c46995b9043fa879970a768b04b298))
+
 ## [2.14.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.13.0...mandrel-v2.14.0) (2026-07-24)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -41,6 +41,7 @@
     "maintainability:update": "node .agents/scripts/update-maintainability-baseline.js",
     "check:arch": "node .agents/scripts/check-arch-cycles.js",
     "check:context-budget": "node .agents/scripts/check-context-budget.js",
+    "check:workflow-citations": "node .agents/scripts/check-workflow-citations.js",
     "crap:check": "node .agents/scripts/check-baselines.js --gate crap",
     "crap:update": "node .agents/scripts/update-crap-baseline.js",
     "duplication:check": "node .agents/scripts/check-baselines.js --gate duplication",

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

@@ -1,148 +0,0 @@
----
-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 an **`escalated` terminal envelope** that ends the session
-   (§ Escalation is terminal).
-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. This is a **question, not a terminal** — wait for the answer.
-   - **over-scope under `--yes`** — no `action` to branch on: the gate emits an
-     **`escalated` terminal envelope** instead (exit 2). § Escalation is
-     terminal governs; you are finished.
-
-   `--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.
-
-## Escalation is terminal {#escalation-is-terminal}
-
-Over-scope under `--yes` emits a schema-validated `story-deliver-terminal`
-envelope with **`status: "escalated"`**, `storyId: null`, and a `nextCommand`
-naming the `/plan` invocation that owns the work.
-
-**That envelope IS this session's terminal output.** Relay it and stop. There is
-no remaining step, no degraded fallback, and no smaller version of the work to
-attempt.
-
-**Invoking `/plan` in this same session is forbidden.** Hand the operator the
-`nextCommand`; `/plan` runs in a **fresh** session.
-
-This is not style — it is the empirical finding that motivated the envelope.
-A mandrel-bench 2.13.0 light-arm run read the escalation and continued anyway:
-it invoked `/plan` in-session and delivered. The in-session plan authored **one**
-Story against the scenario's 3–5 contract, where a fresh `/plan` session on the
-identical seed authored **four**. Planning inside a session already framed as
-small work under-decomposes, so walking past the escalation silently produced
-the very outcome the guard exists to prevent. The gate's decision was right both
-times; only the outcome's finality was missing.
-
-Nothing is left half-started: an escalated run creates **no receipt Story, no
-`story-<id>` branch, and no worktree** — the escalation path returns before
-every creation call site, and `escalation.created` records all three as `false`
-in a shape the schema pins, so a later run finds nothing to trip over.
-
-## Constraints
-
-- **Land, block, or escalate — never a silent local build.** The close push is
-  the only sanctioned landing; an `escalated` terminal is the only sanctioned
-  ending that delivers nothing, and it ends the session
-  (§ Escalation is terminal).
-- **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.