mandrel 2.21.0 → 2.23.0

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-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.

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

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

@@ -36,6 +36,46 @@ whole surface exists to remove.
 Mixed ids and prose in one invocation is a **hard error**: refuse and ask which
 was meant, rather than guessing a mode and doing the wrong work.
 
+## Unknown triage — AFK vs HITL
+
+Every open question interrogation surfaces is triaged by **who can resolve
+it**, not parked in one bucket (a shape borrowed from the Wayfinder skill's
+HITL/AFK ticket typing):
+
+- **AFK** (away from keyboard — the agent resolves it alone): the answer is a
+  fact something already records — third-party docs, a dependency's API
+  surface, observable behavior of this repo. Research it during interrogation
+  (per `.agents/instructions.md` § 1.C) and fold the answer into the plan as a
+  verified claim. An AFK unknown never becomes a Key Assumption — an
+  assumption standing in for a checkable fact is just an unchecked fact.
+- **HITL** (human in the loop — only the operator can resolve it): a genuine
+  product or architecture call — what to support, what to drop, which
+  trade-off to prefer. Nothing the agent reads can answer it; presenting a
+  researched recommendation is fine, deciding is not.
+
+Boundary examples: *"does library X support streaming?"* is AFK (read its
+docs); *"should we drop Node 18 support?"* is HITL (a support-policy call);
+*"does our CLI already validate this flag?"* is AFK (read the code);
+*"which of two valid schema shapes should the new field use?"* is HITL when
+both fit — but first verify it is not settled by an existing convention,
+which would make it AFK.
+
+**Attended runs** present the HITL list at Gate #1 as "needs your decision",
+one line each, alongside the sharpened intent. **Under `--yes`** nobody is at
+the keyboard: AFK unknowns are researched exactly as in an attended run, and
+each HITL unknown degrades to a declarative Key Assumption that names the
+default chosen and marks it a decision-made-by-default, e.g.:
+
+> **Key Assumption (decision-made-by-default):** new-style envelopes only;
+> re-emitting legacy envelopes was ruled out by default, not by the operator.
+
+(Keep the assumption itself declarative — "flag if wrong" phrasing trips the
+open-question hygiene lint, and the deliverer cannot answer it anyway.)
+
+The marker keeps the operator's undelegated decisions findable after the
+fact: reviewing a `--yes` plan means scanning its decisions-made-by-default,
+not re-deriving which assumptions were really the agent's to make.
+
 ## Gate #1 → the light path (in-session handoff)
 
 On a confirmed `deliverLightSuggestion`, `/plan` routes into
@@ -120,10 +160,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/.agents/workflows/plan.md

@@ -14,7 +14,7 @@ description:
 
 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:
+it, then act**:
 
 | Invocation | Mode | Behavior |
 | --- | --- | --- |
@@ -24,11 +24,10 @@ it, then act**; there is nothing for them to remember:
 | `/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. |
 
-**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`.
+**Resolving a bare id.** 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. Ask **only** for an open Story already at `agent::ready`.
 
 `--body` is **not** a `/plan` entry; persist goes through `plan-persist.js`.
 
@@ -62,19 +61,26 @@ node .agents/scripts/plan-context.js --seed "<seed>" \
 
 **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.
+**`stories.template.json`**, step 2's skeleton.
 
 The envelope carries docs context, the story-author
 prompt, `sourceTickets[]`, `duplicates[]` (open **Stories**, never Epics), and
 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.
+to `full` ([detail](helpers/plan-reference.md)).
+
+**Triage each unknown by resolver**
+([detail](helpers/plan-reference.md)): an **AFK** unknown (research settles
+it) is resolved before authoring, never assumed; a **HITL** unknown (an
+operator call) goes to Gate #1 as "needs your decision". Under `--yes`, do
+not ask free-form operator questions — AFK unknowns are still researched;
+only HITL unknowns land in Key Assumptions, each marked a
+decision-made-by-default.
 
 **Gate #1** — STOP to confirm the sharpened plan intent and any
 duplicate-candidate review. Under `--yes`, auto-proceed.
 
-When `complexitySignals.deliverLightSuggestion.suggested` is `true`, offer —
+On a truthy `deliverLightSuggestion.suggested`, 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
@@ -88,9 +94,9 @@ A truthy `complexitySignals.uiSurface` marks a UI-touching plan: name
 ### 2. Author
 
 **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[]` /
+`stories.json` in one pass. `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.
 
 **Grounding = your reads + Phase 8.** Nothing inventories the repo for you:
@@ -149,9 +155,8 @@ node .agents/scripts/plan-persist.js \
   [--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 plan keeps its
-review round-trip.
+At lite shape, `--chain-on-clean` chains a clean dry-run into the real persist
+in one round-trip; a full plan keeps its review round-trip.
 
 Persist creates `type::story` issue(s) plus a `plan-run::<id>` grouping label
 (**metadata only**); N>1 `depends_on` edges become `blocked by #<id>` footers.

package/docs/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.23.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.22.0...mandrel-v2.23.0) (2026-07-30)
+
+
+### Added
+
+* **plan:** triage interrogation unknowns by resolver — AFK research vs HITL operator decision (refs [#4845](https://github.com/dsj1984/mandrel/issues/4845)) ([#4846](https://github.com/dsj1984/mandrel/issues/4846)) ([3cfcd00](https://github.com/dsj1984/mandrel/commit/3cfcd00f3885fc588bdf2bb4597118a790f9b270))
+
+
+### Fixed
+
+* **diagnose-friction:** name the signal that killed a child instead of reporting "Unknown exit code null" and exiting 0 ([#4851](https://github.com/dsj1984/mandrel/issues/4851)) ([#4853](https://github.com/dsj1984/mandrel/issues/4853)) ([1985be1](https://github.com/dsj1984/mandrel/commit/1985be1b97d751d094acf7dd371b97124039cc6d))
+* **rollup:** describe the friction corpus by its own window, not the triggering run (refs [#4850](https://github.com/dsj1984/mandrel/issues/4850)) ([#4852](https://github.com/dsj1984/mandrel/issues/4852)) ([d866697](https://github.com/dsj1984/mandrel/commit/d8666976be30d218115b9db32602359d55379f88))
+* **rollup:** track anchorKind in the triggering-anchor label ([#4854](https://github.com/dsj1984/mandrel/issues/4854)) ([b7e4ddf](https://github.com/dsj1984/mandrel/commit/b7e4ddf8c362f7c31c2abd73ee181a94f78f6dd2))
+
+## [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)
 
 

package/package.json

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