mandrel 2.14.0 → 2.15.0

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,50 @@ 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.
 
 ### 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 +113,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 +142,28 @@ 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;
+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. 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/docs/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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.15.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",