mandrel 2.20.0 → 2.22.0

package/.agents/scripts/single-story-confirm-merge.js

@@ -158,14 +158,13 @@ function readMaxWaitSecondsFlag() {
  * Resolve the PR number for the Story branch when one was not passed on
  * the CLI. Probes `gh pr list --head <branch> --state all` (the merged PR
  * is no longer `open`, so `--state all` is required). Returns `null` when
- * no PR is found.
+ * no PR is found. Exported for testing.
  *
- * @param {{ cwd: string, storyBranch: string, gh: object }} args
+ * @param {{ storyBranch: string, gh: object }} args
  * @returns {Promise<number|null>}
  */
-async function resolvePrNumber({ cwd, storyBranch, gh }) {
+export async function resolvePrNumber({ storyBranch, gh }) {
   try {
-    void cwd;
     const rows = await gh.pr.list(
       ['--head', storyBranch, '--state', 'all'],
       ['number', 'url'],
@@ -204,7 +203,7 @@ async function logConfirmResult(result, terminal, config) {
       status: terminal?.status,
     },
   });
-  emitTerminalEnvelope(terminal);
+  emitTerminalEnvelope(terminal, { config });
   await emitTerminalFriction({ envelope: terminal, config });
   return { success: terminal.status !== 'failed', result, terminal };
 }
@@ -293,11 +292,11 @@ function buildConfirmTerminal({
   });
 }
 
-async function resolveConfirmPrNumber({ prParam, cwd, storyBranch, gh }) {
+async function resolveConfirmPrNumber({ prParam, storyBranch, gh }) {
   const rawPr = prParam ?? readPrFlag();
   let prNumber = Number.parseInt(String(rawPr ?? ''), 10);
   if (!Number.isInteger(prNumber) || prNumber <= 0) {
-    prNumber = await resolvePrNumber({ cwd, storyBranch, gh });
+    prNumber = await resolvePrNumber({ storyBranch, gh });
   }
   return Number.isInteger(prNumber) && prNumber > 0 ? prNumber : null;
 }
@@ -340,7 +339,6 @@ export async function runConfirmMerge({
 
   const prNumber = await resolveConfirmPrNumber({
     prParam,
-    cwd,
     storyBranch,
     gh,
   });

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

@@ -20,16 +20,18 @@ description: >-
 
 ## 1. Dispatch — where the engine runs
 
-Read `stories[].dispatchMode` from the `resolve-stories.js` envelope. Two
-rules produce it, in order:
+Read `stories[].dispatchMode` from the `resolve-stories.js` envelope.
+`inline` names one indivisible resource — **the router's own session** — so one
+rule produces it:
 
 1. **Run topology.** A run resolving **one** Story is `inline`
    whatever its shape — sub-agent isolation is load-bearing only against a
    *concurrent* sibling racing the same checkout, and a one-Story run has none.
-2. **Body shape.** In a multi-Story run, a lite-shaped body is
-   `inline`; a full-shaped body, an unparseable one, or a footprint touching a
-   sensitive-path class is `subagent`. The `route::lite` label is a
-   human-visible hint, never the control signal.
+2. **Every other run is `subagent`.** A multi-Story run dispatches every Story
+   as a sub-agent however trivial its shape: a lite body does not conjure a
+   second session for a sibling to run in, and the wave tick may hand you the
+   whole set on one beat. Shape still sets ceremony and is reported alongside;
+   the `route::lite` label is a human-visible hint, never the control signal.
 
 `inline` removes model-side fan-out only — no `story-worker` boot, no fresh
 acceptance-critic spawn. **`subagent` and `inline` run the same engine**: same

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

@@ -49,7 +49,9 @@ multi-capability enumeration). Size is enforced where ground truth is available:
 the diff backstop in step 4. Do not talk yourself past that one.
 
 Sensitivity is the exception and stays absolute: a footprint touching an auth,
-crypto, billing, or migration class routes `full` however small or mechanical.
+crypto, billing, or migration class routes `full` however small or mechanical —
+and unlike a ceiling, it is **not overridable** (§ Recording a proceed-light
+answer).
 
 ## Four invariants (do not skip one)
 
@@ -58,9 +60,11 @@ crypto, billing, or migration class routes `full` however small or mechanical.
    **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).
+   asks the operator to escalate to `/plan` or proceed light. **Both answers
+   are executable** — `--operator-proceed-light` records the second one
+   (§ Recording a proceed-light answer). 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.
@@ -89,7 +93,10 @@ crypto, billing, or migration class routes `full` however small or mechanical.
      `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.
+     on your own. This is a **question, not a terminal** — wait for the answer,
+     then act on it: *escalate* leaves for `/plan`, *proceed light* re-runs the
+     same command with `--operator-proceed-light "<their reason>"`
+     (§ Recording a proceed-light 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.
@@ -144,6 +151,39 @@ crypto, billing, or migration class routes `full` however small or mechanical.
    [`deliver-digest.md`](deliver-digest.md) § 5 — every close
    gate runs byte-identical to the full path.
 
+## Recording a proceed-light answer {#recording-a-proceed-light-answer}
+
+The gate offers the operator two options, so **both** have to be executable.
+Re-run the identical gate command with their answer appended:
+
+```bash
+node .agents/scripts/deliver-light.js --prompt "<prompt>" … \
+  --operator-proceed-light "<the operator's reason, in their words>"
+```
+
+The gate then proceeds light, records the decision in the receipt Story, and
+returns it on the envelope's `override`. Do **not** instead re-shape the
+prediction — shrinking `--refactors` until the gate stops objecting is
+under-declaring the footprint, which is the one thing the coarse design must
+not reward.
+
+It is deliberately narrow, and a refusal is printed rather than silent:
+
+- **Only a size prediction is waivable** — change kinds, magnitude,
+  uncertainty, deployable span. A sensitive-path class, a
+  migration-with-consumers span, and an unknown footprint (undeclared, glob,
+  no acceptance, unclassifiable) are refused: those are risk, not size, and
+  § Scope by effort keeps them absolute.
+- **The ledgered verdict still stands on its own.** The override substitutes
+  for the predicted *shape* only; `--route lite --reason "<why>"` is still
+  required.
+- **Attended-only.** With `--yes` it is a usage error, not a quiet no-op —
+  an unattended run has no operator whose answer this could be, and over-scope
+  there still fails closed (§ Escalation is terminal).
+
+What licenses this at all is step 4: the operator waives a *guess*, never the
+diff backstop, which re-checks the actual change set against ground truth.
+
 ## Escalation is terminal {#escalation-is-terminal}
 
 Over-scope under `--yes` emits a schema-validated `story-deliver-terminal`

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

@@ -61,23 +61,26 @@ a cache write at full rate; an inline continuation is a cache read at ~10%).
 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.** Before spawning anything,
-read the Story's `dispatchMode` from the resolver envelope
-(`stories[].dispatchMode`, derived by `resolveStoryDispatchMode` in
-`lib/orchestration/complexity-gate.js` **from the fetched Story body's own
-shape** — `changes[]` count, acceptance count, creates-vs-refactors mix, and
-sensitive-path classes; the `route::lite` label is a human-visible hint only,
-never the control signal, so a lost or never-written label cannot misroute
-delivery): a Story with `dispatchMode: "inline"` executes
-[`deliver-story.md`](deliver-story.md) **inline in this session** — no
+**Read the mode; never infer it from shape.** Before spawning
+anything, read the Story's `dispatchMode` from the resolver envelope
+(`stories[].dispatchMode`, produced by `resolveStoryDispatchMode` in
+`lib/orchestration/complexity-gate.js`). A Story with `dispatchMode: "inline"`
+executes [`deliver-story.md`](deliver-story.md) **inline in this session** — no
 `story-worker` sub-agent boot and no fresh acceptance-critic sub-agents
 (sub-agent boots are the dominant deliver-phase token cost at trivial scope) —
 threading the same `docsDigestPath` / `checklistPath` / change-set discipline
 as a spawned worker. Inline removes model-side fan-out only: every
 `single-story-close.js` gate, the PR to `main`, and the terminal envelope are
-identical. Everything else — a full-shaped body, a missing/unparseable body,
-or a footprint intersecting a sensitive-path class (sensitivity wins and
-keeps the fresh acceptance critic) — takes the standard sub-agent path.
+identical.
+
+**A trivial shape does not buy that session.** Only the
+one-Story rule above yields `inline`; every Story of a multi-Story run comes
+back `subagent` however lite its body, because the ready set below may offer
+several Stories on one beat and a session cannot be split between them. The
+Story's derived shape is still reported (it sets ceremony, and a sensitive
+footprint keeps the fresh acceptance critic), and the `route::lite` label
+remains a human-visible hint only, never the control signal — a lost or
+never-written label cannot misroute delivery.
 
 **Dispatch each `ready` Story (role-scoped by default).** When
 `delivery.routing.roleScopedAgents` is enabled (the **default**) and the host

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

@@ -133,23 +133,25 @@ and the `rules/security-baseline.md` MUSTs all run exactly as for a
 full-ceremony Story. The lite route's `preserves` field is the machine-readable
 record of those non-negotiables; there is no lite-specific gate bypass.
 
-**Deliver derives the route from the Story body's shape.**
-Persist stamps a lite cohort's Stories with the `route::lite` label as a
-*human-visible hint only* (and ledgers the authored verdict — recorded
-reason plus per-Story shape evidence — on the `story-plan-state`
-checkpoint); the label is never the control signal. `/deliver` computes the
-route from the fetched Story body via `resolveStoryDispatchMode`
-(`lib/orchestration/complexity-gate.js`) — the same shape taxonomy
-`deriveChangeLevel` applies to the landed diff at close: `changes[]` count,
-acceptance count, creates-vs-refactors mix, sensitive-path classes. A
-lite-shaped Story executes **inline in the deliver session** — even when the
-label is absent or its write failed — with no `story-worker` sub-agent boot,
-and the Step 1a acceptance self-eval runs its critics **inline** (no
-fresh-context acceptance-critic sub-agent dispatch; sub-agent boots are the
-dominant deliver-phase token cost at trivial scope). A footprint
-intersecting a sensitive-path class derives `full` — sensitivity wins, and
-the Story keeps its fresh acceptance critic. Inline execution
-changes the isolation only: the engine, every script gate, and the
+**Deliver derives the route from the Story body's shape — and the
+dispatch mode from the run.** Persist stamps a lite cohort's Stories with the
+`route::lite` label as a *human-visible hint only* (and ledgers the authored
+verdict — recorded reason plus per-Story shape evidence — on the
+`story-plan-state` checkpoint); the label is never the control signal.
+`/deliver` computes the route from the fetched Story body via
+`resolveStoryDispatchMode` (`lib/orchestration/complexity-gate.js`) — the same
+shape taxonomy `deriveChangeLevel` applies to the landed diff at close:
+`changes[]` count, acceptance count, creates-vs-refactors mix, sensitive-path
+classes. A footprint intersecting a sensitive-path class derives `full` —
+sensitivity wins, and the Story keeps its fresh acceptance critic.
+
+That derived route sets ceremony. It does **not** set the dispatch mode,
+because `inline` names one indivisible resource — the router's own session —
+and only run topology can say whether it is free: a **single-Story run**
+executes inline, and every Story of a multi-Story run dispatches as a
+`story-worker` sub-agent whatever its shape — a lite shape makes the work
+cheap, it does not conjure a second session for a sibling. Inline
+execution changes the isolation only: the engine, every script gate, and the
 terminal envelope are byte-identical either way.
 
 ---
@@ -247,10 +249,10 @@ Resolve fresh-vs-inline acceptance critics per AC-cluster with
 floor forces `fresh`). Review depth reads the same derived level via
 `review-depth.js` inside close, so the two decisions cannot disagree.
 
-**Lite-route override.** When the Story's body derives the
-lite shape (`resolveStoryDispatchMode` → `inline`), run every
-acceptance critic **inline** — do not spawn fresh-context critic sub-agents
-regardless of what the profile would otherwise resolve. The self-eval rigor
+**Inline-dispatch override.** When the Story dispatches
+`inline` (`resolveStoryDispatchMode` → `inline`, i.e. a single-Story run), run
+every acceptance critic **inline** — do not spawn fresh-context critic
+sub-agents regardless of what the profile would otherwise resolve. The self-eval rigor
 (scoring each `acceptance[]` item against the one computed change set, with
 `verify[]` output as evidence) is unchanged; only the sub-agent boot is
 removed. Hard gates are untouched.
@@ -745,6 +747,39 @@ unconfirmed merge is a **contract violation** — the parent cannot distinguish
 "still working" from "done but silent". `pending` is the honest,
 machine-readable alternative: "not finished, here is exactly how to continue."
 
+### The envelope also lands on disk
+
+Stdout has exactly one reader — the turn that launched the close — and that
+reader is not always still listening. A child that reports progress and ends
+its turn while its close is mid-gate-chain is behaving reasonably, but the
+envelope it never relayed is gone, and reconstructing the Story's state from
+labels costs a recovery round trip plus a full resume of the child. Observed
+four times across three workers in a single consumer run, on unrelated
+footprints, and not new to that run.
+
+So `emitTerminalEnvelope` — the one writer behind every emit site — also
+persists the validated envelope to
+`<tempRoot>/orchestration/story-deliver-terminal-<storyId>.json`:
+
+- **It is the same object**, not a summary. Read it and branch exactly as you
+  would on stdout; the copy is written before the markers are, so a caller
+  that saw them can rely on the file.
+- **It is best-effort.** A failed write returns null and changes nothing about
+  the emitted envelope or the exit code — a landed PR must never become a
+  crash because a temp directory was unwritable.
+- **It is a fallback, not a licence.** A worker still holds its turn until the
+  envelope arrives; see [`agents/story-worker.md`](../../agents/story-worker.md).
+
+`deliver-recover.js` reads the same artifact, plus the freshness of
+`close-gates-<storyId>.log`, to split the one genuinely ambiguous row of its
+table. `agent::executing` with no PR used to answer "Implementation never
+finished" — false for the whole duration of a close, whose gates and push
+happen before any PR exists, and actively hazardous, because acting on its
+re-init suggestion can put a second close on one PR. It now answers
+`close-in-flight` (a gate log touched inside the window: wait, then re-probe)
+or `close-envelope-on-disk` (the close already reached a verdict: relay it),
+and falls back to the original verdict only when neither artifact exists.
+
 ### Exit-code compatibility note (`--no-wait-merge`)
 
 Every close flag keeps its meaning, but the **exit code** of a

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

@@ -22,8 +22,8 @@ mandatoryReads: [deliver-digest.md]
 
 ## Overview
 
-The **one** delivery engine in v2 — every Story (a lite-**shaped** Story
-runs inline with inline critics; engine, gates, envelope byte-identical):
+The **one** delivery engine in v2 — every Story (a **one-Story** run
+goes inline with inline critics; engine, gates, envelope byte-identical):
 
 ```text
 single-story-init.js → implement + commits → derived-level ceremony
@@ -148,10 +148,13 @@ budget is exhausted. Reference § Step 7.
 
 ## Recovering a stranded Story {#recover}
 
-Unclear state (killed run, lost envelope, a re-run refusal — incl.
-merged-but-label-stale)? Do not guess — probe **read-only** with
+**Lost envelope first: read it off disk.** Close persists each to
+`temp/orchestration/story-deliver-terminal-<storyId>.json`; branch on it per
+digest § 5. Otherwise (killed run, re-run refusal, merged-but-label-stale)
+do not guess — probe **read-only** with
 `node .agents/scripts/deliver-recover.js --story <storyId>`; it prints the
-**one** next command with its evidence, never a menu.
+**one** next command with its evidence, never a menu. A live close answers
+`close-in-flight`: wait, never re-init underneath it.
 
 ## Idempotence & constraints
 

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

@@ -120,10 +120,11 @@ decision:
 lite cohort's Stories with **`route::lite`** as a *human-visible hint only* —
 `/deliver` computes the route from each fetched Story body via the same shape
 function at dispatch, so neither a lost label nor an unread marker can
-misroute delivery: a lite-shaped Story executes **inline** (no story-worker
-or acceptance-critic sub-agent boots) even with the label absent, and a
-sensitive-footprint Story routes `full` and keeps its fresh critic even with
-the label present. The `route::*` axis stays runtime-derived: hand-authored
+misroute delivery: a lite-shaped Story derives `lite` even with the label
+absent, and a sensitive-footprint Story routes `full` and keeps its fresh
+critic even with the label present. The derived route sets ceremony, not
+where the engine runs — sub-agent boots are collapsed by a **single-Story
+run**, never by a trivial shape. The `route::*` axis stays runtime-derived: hand-authored
 `route::*` entries in `labels[]` are dropped by persist.
 
 The knobs (`planning.complexityGate.{enabled, maxArtifacts}`) are documented

package/docs/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.22.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.21.0...mandrel-v2.22.0) (2026-07-30)
+
+
+### Fixed
+
+* **context-budget:** hold agentBoot baseline rows in sync with the tree (refs [#4830](https://github.com/dsj1984/mandrel/issues/4830)) ([#4831](https://github.com/dsj1984/mandrel/issues/4831)) ([8a14f8b](https://github.com/dsj1984/mandrel/commit/8a14f8b85951819ef391382355fa2ba4d7998d43))
+* correct the always-on instruction spine and give its budget one honest definition (refs [#4821](https://github.com/dsj1984/mandrel/issues/4821)) ([#4822](https://github.com/dsj1984/mandrel/issues/4822)) ([436d7f0](https://github.com/dsj1984/mandrel/commit/436d7f05d36bd35a6b1a934f19e9a85b37b69f93))
+* feedback-loop: give an auto-filed issue a stable identity, an actionable body, and no path to the live API from a test ([#4837](https://github.com/dsj1984/mandrel/issues/4837)) ([#4838](https://github.com/dsj1984/mandrel/issues/4838)) ([43bbf57](https://github.com/dsj1984/mandrel/commit/43bbf578fc129c9b15ad068925722732fd264c7f))
+* make an inline dispatch verdict mean the engine can actually run inline (refs [#4829](https://github.com/dsj1984/mandrel/issues/4829)) ([#4832](https://github.com/dsj1984/mandrel/issues/4832)) ([f554830](https://github.com/dsj1984/mandrel/commit/f55483085eb201aa126275bb0ed6250fc5a452a3))
+* make the framework limb of the feedback loop reachable (refs [#4824](https://github.com/dsj1984/mandrel/issues/4824)) ([#4827](https://github.com/dsj1984/mandrel/issues/4827)) ([91816a2](https://github.com/dsj1984/mandrel/commit/91816a2dceda127a0cdf1ad3f48f53d7770cbf0b))
+* make the friction roll-up file its proposals and make an all-empty result legible (refs [#4828](https://github.com/dsj1984/mandrel/issues/4828)) ([#4835](https://github.com/dsj1984/mandrel/issues/4835)) ([c017f9a](https://github.com/dsj1984/mandrel/commit/c017f9a9145122b15e41b55a9126a35171f3f1b9))
+* review: stop the scoped-lint gate failing open silently, and fix why its runner cannot execute ([#4839](https://github.com/dsj1984/mandrel/issues/4839)) ([#4840](https://github.com/dsj1984/mandrel/issues/4840)) ([8f3f007](https://github.com/dsj1984/mandrel/commit/8f3f0072abef020439d555af698829ebfc8900f8))
+* rules: ship a known-tooling-behavior rule so measured gate quirks stop being rediscovered per session ([#4825](https://github.com/dsj1984/mandrel/issues/4825)) ([#4826](https://github.com/dsj1984/mandrel/issues/4826)) ([2c20403](https://github.com/dsj1984/mandrel/commit/2c2040318055026307518de57b1433c11c56efc1))
+* **test:** probe bins on either path separator so [#4839](https://github.com/dsj1984/mandrel/issues/4839)'s tests pass on Windows ([#4841](https://github.com/dsj1984/mandrel/issues/4841)) ([98e6048](https://github.com/dsj1984/mandrel/commit/98e6048774b7483717931d0b4a63179800815941))
+
+
+### Changed
+
+* restore clean-code gate headroom: cover CRAP-capacity shells, flatten selectAudits, table-drive story-body parsing ([#4842](https://github.com/dsj1984/mandrel/issues/4842)) ([#4843](https://github.com/dsj1984/mandrel/issues/4843)) ([cc5dc5e](https://github.com/dsj1984/mandrel/commit/cc5dc5e7eaf423612495441f0f8f9007dbb9b8a4))
+
+## [2.21.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.20.0...mandrel-v2.21.0) (2026-07-28)
+
+
+### Added
+
+* deliver-light: make the gate's `proceed-light` answer representable, attended-only, and auditable ([#4815](https://github.com/dsj1984/mandrel/issues/4815)) ([#4817](https://github.com/dsj1984/mandrel/issues/4817)) ([74aa28e](https://github.com/dsj1984/mandrel/commit/74aa28e57d0192bcad698461d600806a77de092f))
+* persist the close terminal envelope and teach recovery a live-close state (refs [#4816](https://github.com/dsj1984/mandrel/issues/4816)) ([#4819](https://github.com/dsj1984/mandrel/issues/4819)) ([ffa61d8](https://github.com/dsj1984/mandrel/commit/ffa61d8f56f39c33705bfa379cefdcaaeb523115))
+
 ## [2.20.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.19.0...mandrel-v2.20.0) (2026-07-27)
 
 

package/package.json

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