mandrel 1.68.0 → 1.70.0

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

@@ -1,10 +1,12 @@
 ---
 description: >-
   Deliver one or more standalone Stories end-to-end. Accepts 1+ Story IDs,
-  computes a dependency-aware wave plan via `stories-wave-tick.js`, asks the
-  operator to confirm the plan, then fans out parallel Agent calls per wave
-  — each delegating to `helpers/single-story-deliver`. Stories without an
-  `Epic: #N` reference only; Epic-attached Stories use `/deliver`.
+  builds a dependency DAG, asks the operator to confirm it, then drives a
+  continuous ready-set loop via `stories-wave-tick.js` (the shared
+  `selectReadySet` core) — dispatching each Story the instant its own deps
+  are done, under one global concurrency cap and one file-overlap guard,
+  each dispatch delegating to `helpers/single-story-deliver`. Stories
+  without an `Epic: #N` reference only; Epic-attached Stories use `/deliver`.
 ---
 
 # helpers/deliver-stories — multi-Story delivery path (invoked by /deliver)
@@ -16,17 +18,24 @@ This helper is the **standalone multi-Story delivery path** behind
 standalone Stories — either as the sole route (Story-only input) or as the
 **standalone segment** of a mixed segment plan (run first, before any Epic
 segments; see [`deliver.md`](../deliver.md)). It takes one or more Story
-IDs, builds a dependency-aware wave plan, optionally confirms it with the
-operator, and fans out one Agent call per Story per wave — parallel within
-each wave, serialised across waves.
+IDs, builds a dependency DAG, optionally confirms it with the operator, and
+then drives a **continuous ready-set loop**: it dispatches each Story the
+instant its **own** dependencies are done — there is no wave barrier where a
+whole group must drain before the next opens — capped by one global
+concurrency limit and guarded by one file-overlap rule, the same scheduling
+core (`lib/wave-runner/ready-set.js#selectReadySet`) the Epic path uses.
 
 ```text
 /deliver 101 102 103
   → Phase 0 — Validate input & build DAG
-  → Phase 1 — stories-wave-tick.js → wave plan + operator confirmation
-  → Phase 2 — for each wave:
-        Agent tool × min(wave.stories.length, plan.concurrencyCap) parallel calls
-          helpers/single-story-deliver <storyId>
+  → Phase 1 — stories-wave-tick.js → DAG sanity + operator confirmation
+  → Phase 2 — continuous ready-set loop:
+        repeat until every Story is done:
+          stories-wave-tick.js --dag … --done <doneIds> --in-flight <n>
+            → ready[] = Stories dispatchable on this beat
+          Agent tool × ready.length parallel calls (≤ concurrencyCap − inFlight)
+            helpers/single-story-deliver <storyId>
+          as each child returns done, add its id to <doneIds> and re-tick
   → Phase 3 — Summary
 ```
 
@@ -42,17 +51,19 @@ each wave, serialised across waves.
 This helper **refuses** Stories that carry an `Epic: #N` reference in
 their body. Those Stories belong to an Epic's dispatch manifest and must flow
 through `/deliver <epicId>`. Use `/single-story-deliver` for a single
-Epic-free Story when you want the leaner one-story path without wave
-machinery.
+Epic-free Story when you want the leaner one-story path without the
+ready-set scheduling loop.
 
 > **Concurrency cap.** The cap is resolved **deterministically in code** by
-> `stories-wave-tick.js` (Phase 1a) — the same `resolveConfig` + `getRunners`
-> seam `/deliver` uses — and emitted as the `concurrencyCap` field on the
-> `stories-wave-plan` envelope. The default is 3; override persistently via
-> `delivery.deliverRunner.concurrencyCap` in `.agentrc.json` (a
-> `.agentrc.local.json` override is honored) or per-run via the `--concurrency`
-> flag below. Phase 2 dispatches `min(wave.stories.length, plan.concurrencyCap)`
-> straight from the emitted field — do **not** re-read or merge config yourself.
+> `stories-wave-tick.js` — the same `resolveConfig` + `getRunners` seam
+> `/deliver` uses — and emitted as the `concurrencyCap` field on the
+> `stories-ready-set` envelope on **every** beat. The default is 3; override
+> persistently via `delivery.deliverRunner.concurrencyCap` in `.agentrc.json`
+> (a `.agentrc.local.json` override is honored) or per-run via the
+> `--concurrency` flag below. The cap is global, not per-wave: the core caps
+> each beat's `ready[]` at `concurrencyCap − inFlight`, so the workflow simply
+> dispatches every id in `ready[]` — do **not** re-read or merge config
+> yourself, and do **not** re-throttle the returned set.
 
 ---
 
@@ -66,13 +77,13 @@ machinery.
   **no** `Epic: #N` reference. At least one is required.
 - `--dep <fromId>:<toId>` — Declare an explicit dependency edge: `<fromId>`
   must complete before `<toId>` runs. Repeat for each edge. When omitted,
-  all Stories are treated as independent (wave 0 catches everything) unless
-  `blocked by #N` references between the supplied IDs are detected
-  automatically.
+  all Stories are treated as independent (every Story is dispatchable on the
+  first beat) unless `blocked by #N` references between the supplied IDs are
+  detected automatically.
 - `--yes` — Skip the operator confirmation in Phase 1 and proceed
   immediately. Safe for scripted / sub-agent invocations.
-- `--concurrency <n>` — Override the per-wave concurrency cap for this run
-  only. Passed through to `stories-wave-tick.js` in Phase 1a, which validates
+- `--concurrency <n>` — Override the global concurrency cap for this run
+  only. Passed through to `stories-wave-tick.js` on every beat, which validates
   it (must be a positive integer) and reflects it in the emitted
   `concurrencyCap` field. When omitted, the cap is resolved from
   `delivery.deliverRunner.concurrencyCap` (default 3).
@@ -108,9 +119,9 @@ Construct the DAG input array:
 
 ---
 
-## Phase 1 — Wave planning and operator confirmation
+## Phase 1 — DAG sanity check and operator confirmation
 
-### 1a. Compute the wave plan
+### 1a. Sanity-check the DAG (first beat, nothing done yet)
 
 ```bash
 node .agents/scripts/stories-wave-tick.js --dag '<dag-json>'
@@ -123,17 +134,16 @@ verbatim to `stories-wave-tick.js`. The script resolves the cap from config
 (`delivery.deliverRunner.concurrencyCap`, default 3) and the override wins for
 that run.
 
-Stdout is one JSON envelope:
+With no `--done` / `--in-flight` (the first beat), stdout is one JSON
+envelope describing the Stories dispatchable **right now** — the roots:
 
 ```json
 {
-  "kind": "stories-wave-plan",
-  "waves": [
-    { "waveIndex": 0, "stories": [101, 103] },
-    { "waveIndex": 1, "stories": [102] }
-  ],
+  "kind": "stories-ready-set",
+  "ready": [101, 103],
   "totalStories": 3,
   "concurrencyCap": 3,
+  "inFlight": 0,
   "cycleError": null
 }
 ```
@@ -141,27 +151,35 @@ Stdout is one JSON envelope:
 - **`cycleError` non-null** → STOP. Report the cycle to the operator and
   exit. The Story set cannot be delivered until the circular dependency is
   resolved.
-- **`waves` empty** → STOP. Zero Stories resolved — report and exit.
-- **`concurrencyCap`** is the resolved per-wave cap. Phase 2 dispatches
-  `min(wave.stories.length, plan.concurrencyCap)` from this field — the
-  workflow never re-reads or merges config to recover the cap.
-- An invalid `--concurrency` value (non-positive / non-integer) makes the
+- **`totalStories === 0`** → STOP. Zero Stories resolved — report and exit.
+- **`ready` empty with `totalStories > 0` on the first beat** → STOP. Every
+  Story is gated behind a dependency outside the supplied set; report and
+  exit (the operator must include the missing prerequisites).
+- **`concurrencyCap`** is the resolved global cap. Phase 2 re-reads it from
+  each beat's envelope and never re-derives it from config.
+- An invalid `--concurrency` / `--in-flight` / `--done` value makes the
   script exit non-zero with an `inputError` → STOP and surface the message.
 
-### 1b. Operator confirmation (skipped with `--yes` or for single-story plans)
+This first call is a **sanity gate**, not the schedule: Phase 2 re-ticks
+continuously as Stories complete. The envelope no longer enumerates future
+waves — ordering emerges beat by beat from the live `--done` set.
 
-**Auto-skip rule (Story #3302):** When `waves.length === 1` and
-`waves[0].stories.length === 1`, skip the confirmation prompt
-automatically and proceed. A single-Story plan has no ordering ambiguity
-and no meaningful operator decision to make — the plan *is* "deliver this
-one Story". Prompting for confirmation would just be friction.
+### 1b. Operator confirmation (skipped with `--yes` or for single-story runs)
 
-Otherwise, present the wave plan to the operator in a readable table:
+**Auto-skip rule (Story #3302):** When `totalStories === 1`, skip the
+confirmation prompt automatically and proceed. A single-Story run has no
+ordering ambiguity and no meaningful operator decision to make — the run
+*is* "deliver this one Story". Prompting for confirmation would just be
+friction.
+
+Otherwise, present the dependency DAG to the operator in a readable table —
+the roots dispatch immediately, dependents unlock as their prerequisites
+complete:
 
 ```text
-Wave plan — 3 Stories across 2 waves
-  Wave 0 (parallel): #101 "<title>", #103 "<title>"
-  Wave 1 (after wave 0): #102 "<title>"
+Delivery plan — 3 Stories (continuous, dependency-driven)
+  Ready now: #101 "<title>", #103 "<title>"
+  Unlocks after its deps complete: #102 "<title>" (needs #101)
 
 Proceed? [Y/n]
 ```
@@ -169,23 +187,44 @@ Proceed? [Y/n]
 Wait for the operator to confirm before dispatching. When the operator
 types `n` or `N`, abort cleanly with a summary of the plan that was
 declined. When `--yes` was passed, skip this step and proceed regardless
-of wave count.
+of Story count.
 
 ---
 
-## Phase 2 — Wave dispatch loop
+## Phase 2 — Continuous ready-set loop
+
+Drive a single loop, re-ticking after every child returns. Maintain two
+pieces of state across the loop:
+
+- **`doneIds`** — the set of Story IDs that have returned `status: 'done'`
+  (start empty).
+- **`inFlight`** — the count of Stories dispatched but not yet returned
+  (start at 0).
+
+Each iteration (one **beat**):
+
+### 2a. Tick the ready set
+
+```bash
+node .agents/scripts/stories-wave-tick.js --dag '<dag-json>' \
+  --done '<comma-separated doneIds>' --in-flight <inFlight> [--concurrency <n>]
+```
 
-For each wave in `waves` (in `waveIndex` order):
+The envelope's `ready[]` is the set of Stories whose **own** dependencies
+are all in `doneIds` and that fit the remaining capacity
+(`concurrencyCap − inFlight`) without a file-overlap collision — the core
+has already applied the global cap and the overlap guard, so the list is
+safe to dispatch verbatim. **Termination:** when `ready` is empty **and**
+`inFlight === 0` **and** `doneIds` covers every Story, the run is complete →
+go to Phase 3. When `ready` is empty but `inFlight > 0`, dispatch nothing
+and wait for an in-flight child to return (a dependent is waiting on it).
 
-### 2a. Fan out per-Story Agent calls
+### 2b. Fan out per-Story Agent calls
 
-Emit **one `Agent` tool call per Story** in the wave, capped at
-`plan.concurrencyCap` from the Phase 1a `stories-wave-plan` envelope. When
-the wave contains more Stories than `plan.concurrencyCap`, dispatch the first
-`plan.concurrencyCap` in one turn with `run_in_background: true` and refill
-as each child returns — never exceed the cap, never wait for the whole
-batch before refilling. Do **not** re-derive the cap from config here; the
-envelope field is the single deterministic source.
+Emit **one `Agent` tool call per Story ID in `ready[]`**, all with
+`run_in_background: true`. The list is already capped, so dispatch the whole
+of `ready[]` and increment `inFlight` by `ready.length`. Do **not** re-derive
+or re-throttle the cap here; the core sized `ready[]` for you.
 
 Each Agent call:
 
@@ -199,7 +238,7 @@ Each Agent call:
    internally-blocking step (`gh pr checks --watch` blocks the turn), **not**
    a reason to suspend and hand back. A child that ends its turn with
    free-form prose and an unconfirmed merge (e.g. "I'll wait for the
-   background watch task…") has violated the contract — the wave loop cannot
+   background watch task…") has violated the contract — the loop cannot
    advance, and the Story strands at `agent::closing` (the Story #1553 /
    PR #1554 failure mode). There is no "pending" return status: the child
    returns `done` (merge confirmed), `blocked` (transitioned + friction
@@ -212,11 +251,14 @@ Each Agent call:
 
 Use `subagent_type: general-purpose`.
 
-### 2b. Collect results
+### 2b′. Collect each return and re-tick
 
-Wait for all dispatched Stories in the current wave to return before
-advancing to the next wave. A wave is complete when every dispatched
-Agent call has returned a result (success, blocked, or failed).
+As each child returns, decrement `inFlight` by 1 and apply its outcome
+(§ 2d). When a child returns `done`, add its id to `doneIds`. Then **re-tick
+immediately** (§ 2a) so a newly-unblocked Story dispatches the instant its
+last dependency clears — do not wait for the whole batch to drain. This is
+the no-false-barrier behavior: an unrelated still-running Story never holds
+back a Story whose own deps are already done.
 
 ### 2c. Per-Story return contract
 
@@ -240,36 +282,38 @@ The status enum is **closed** — `done`, `blocked`, or `failed`. There is no
 **not** a returnable suspension: the child blocks on `gh pr checks --watch`
 *inside its own turn*, confirms the merge, flips `agent::done`, and only then
 returns `status: "done"`. A child that returns prose instead — parking on the
-CI wait with an unconfirmed merge — breaks the wave loop's ability to advance
+CI wait with an unconfirmed merge — breaks the loop's ability to advance
 and leaves the Story at `agent::closing` (Story #1553 / PR #1554). The
 single-homed restatement of this no-park rule for the child's own perspective
 is [`single-story-deliver.md` § Step 7](single-story-deliver.md#return-contract).
 
-### 2d. Wave outcome handling
+### 2d. Per-return outcome handling
 
-After every Story in a wave returns:
+As each child returns (before the next re-tick):
 
-- **All `status === 'done'`** → Advance to the next wave (or Phase 3 if
-  this was the last wave). Print a one-line wave-complete summary.
-- **Any `status === 'blocked'`** → STOP the wave loop. Post a summary
-  of blocked Stories and their `blockerCommentId` references. Do not
-  dispatch the next wave. Wait for the operator to resolve each blocker
-  and re-run `/deliver` with the same set (already-done Stories
-  will short-circuit because `single-story-close.js` is idempotent).
-- **Any `status === 'failed'`** → STOP the wave loop. Report the
-  failures. The operator must fix the failing Stories before re-running.
+- **`status === 'done'`** → Add its id to `doneIds` and re-tick. Print a
+  one-line per-Story complete summary.
+- **`status === 'blocked'`** → STOP dispatching new Stories. Drain the
+  Stories still in flight (let them return), then post a summary of blocked
+  Stories and their `blockerCommentId` references. Do not dispatch any
+  further beat. Wait for the operator to resolve each blocker and re-run
+  `/deliver` with the same set (already-done Stories will short-circuit
+  because `single-story-close.js` is idempotent).
+- **`status === 'failed'`** → STOP dispatching new Stories, drain the
+  in-flight set, and report the failures. The operator must fix the failing
+  Stories before re-running.
 
 ---
 
 ## Phase 3 — Summary
 
-Print a final run summary:
+Print a final run summary listing every delivered Story in completion order:
 
 ```text
-/deliver — 3 Stories delivered in 2 waves
+/deliver — 3 Stories delivered (continuous, dependency-driven)
 
-  Wave 0: #101 ✅ done, #103 ✅ done
-  Wave 1: #102 ✅ done
+  #101 ✅ done, #103 ✅ done (dispatched first — roots)
+  #102 ✅ done (after #101 cleared)
 
 All Stories delivered. PRs opened, auto-merge armed. CI will merge each
 PR when checks pass; each child then confirms the merge and flips its
@@ -331,11 +375,13 @@ blocked or unstarted Stories execute.
 
 - **Never** pass Epic-attached Stories to this command. Detect `Epic: #N`
   in Phase 0 and STOP.
-- **Never** advance to the next wave while any Story in the current wave
-  is `blocked` or `failed`.
-- **Never** exceed `plan.concurrencyCap` (the resolved cap emitted by
-  `stories-wave-tick.js`) parallel Agent calls at any moment.
-- **Always** confirm the wave plan with the operator before dispatching,
+- **Never** dispatch a new beat once any Story has returned `blocked` or
+  `failed` — drain the in-flight set and stop.
+- **Never** exceed the resolved `concurrencyCap` (emitted by
+  `stories-wave-tick.js` on every beat) parallel Agent calls at any moment.
+  The core caps each beat's `ready[]` at `concurrencyCap − inFlight`;
+  dispatch the whole list and never add to it.
+- **Always** confirm the dependency DAG with the operator before dispatching,
   unless `--yes` was passed.
 - **Label transitions**: drive every `agent::*` state change through
   `node .agents/scripts/update-ticket-state.js --ticket <id> --state <state>`.

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

@@ -713,16 +713,19 @@ node .agents/scripts/epic-plan-spec-validate.js \
    ticket array to `temp/epic-[Epic_ID]/tickets.json`. Do **not** inline
    the JSON authoring in the workflow body.
 
-   The `maxTickets` cap (`planning.maxTickets` in
-   `.agentrc.json`; framework default in
-   `.agents/scripts/lib/config/limits.js`) is a **reviewability budget**,
-   not a hard authoring ceiling: a draft over budget warns at authoring
-   time and is rejected at persist unless rerun with `--allow-over-budget`
-   (after confirming the over-budget rationale on the Epic). The
-   `epic-plan-decompose.js` script also logs the resolved budget to stderr
-   so a misconfigured key surfaces immediately. The skill body is the
-   authoritative source of the decomposer prompt; the `systemPrompt`
-   field on the emit envelope is a backstop for legacy callers.
+   The `maxTickets` cap is a **framework constant**
+   (`LIMITS_DEFAULTS.maxTickets` in
+   `.agents/scripts/lib/config/limits.js`; not operator-configurable) and
+   a **reviewability budget**, not a hard authoring ceiling: a draft over
+   budget warns at authoring time and is rejected at persist unless rerun
+   with `--allow-over-budget` (after confirming the over-budget rationale
+   on the Epic). The `epic-plan-decompose.js` script also logs the
+   resolved budget to stderr. The decomposer system prompt is
+   single-sourced in
+   `.agents/scripts/lib/templates/decomposer-prompts.js`
+   (`renderDecomposerSystemPrompt`); the `epic-plan-decompose-author`
+   skill references that rendered `systemPrompt` rather than carrying
+   its own copy of the prompt body.
 
    When the Tech Spec carries a `## Delivery Slicing` section (authored by
    `epic-plan-spec-author` in Phase 7), the decompose-author skill authors

package/.agents/workflows/plan.md

@@ -43,7 +43,7 @@ forwards them to the active path helper:
 | `--from-notes <path>` | both | Pre-triaged handoff notes; skips triage. |
 | `--force` | Epic | Close + recreate an existing ticket tree on re-plan. |
 | `--force-review` | Epic | Force the operator review gate even when risk routing would skip it. |
-| `--allow-over-budget` | Epic | Permit a decomposition that exceeds `planning.maxTickets`. |
+| `--allow-over-budget` | Epic | Permit a decomposition that exceeds the framework `maxTickets` reviewability budget. |
 | `--steal` | Epic | Forcibly transfer a foreign Epic-lease. |
 | `--dry-run` | both | Author + validate without GitHub writes. |
 | `--body <path>` | Story | Pre-authored Story body file; validate (and create, unless `--dry-run`) without re-authoring. |

package/README.md

@@ -69,6 +69,26 @@ explicit `npx mandrel sync` above is the belt-and-suspenders step for
 `--ignore-scripts` or sandboxed-CI installs. Run `npx mandrel doctor` any
 time to confirm the install is healthy.
 
+> **pnpm users — hoist mandrel's runtime deps.** The materialized
+> `./.agents/scripts/*.js` run from your project root and resolve their
+> third-party deps (ajv, js-yaml, …) from your top-level `node_modules`.
+> npm and yarn hoist transitive deps there automatically; pnpm's default
+> isolated layout does **not** — it keeps them in the `.pnpm` virtual store,
+> so the framework scripts (and `mandrel doctor`'s `runtime-deps` check)
+> cannot see them. Add the following to your `.npmrc` before installing:
+>
+> ```ini
+> # Lift mandrel's runtime deps to the top-level node_modules so the
+> # materialized .agents/scripts can resolve them.
+> shamefully-hoist=true
+> ```
+>
+> Prefer a surgical alternative? Replace `shamefully-hoist` with a scoped
+> `public-hoist-pattern[]=` line per package listed in
+> `.agents/runtime-deps.json` (`ajv`, `ajv-formats`, `js-yaml`, `minimatch`,
+> `picomatch`, `string-argv`, `typhonjs-escomplex`). If `mandrel doctor`
+> reports `runtime-deps missing: …`, this is the fix.
+
 `bootstrap.js` is interactive on a TTY and auto-accepts the
 owner/repo/base branch/operator handle it can infer from your local
 `git remote` and `git config user.name` — you only get prompted for

package/docs/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.70.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.69.0...mandrel-v1.70.0) (2026-06-16)
+
+
+### Added
+
+* **agents-update:** add a first-run preflight before the updater (refs [#4170](https://github.com/dsj1984/mandrel/issues/4170)) ([#4177](https://github.com/dsj1984/mandrel/issues/4177)) ([82d30c6](https://github.com/dsj1984/mandrel/commit/82d30c6877d567d8272e1f433da00797a71bdeb9))
+* **agents-update:** make partial-upgrade recovery a first-class workflow step (refs [#4172](https://github.com/dsj1984/mandrel/issues/4172)) ([#4179](https://github.com/dsj1984/mandrel/issues/4179)) ([9959fd8](https://github.com/dsj1984/mandrel/commit/9959fd8e480067b1c35d25c9e37f8be0908f9a9e))
+
+
+### Fixed
+
+* /audit-to-stories: fix silent-no-op dedup (GitHubProvider.searchIssues missing) + junk audit:: label derivation ([#4195](https://github.com/dsj1984/mandrel/issues/4195)) ([#4207](https://github.com/dsj1984/mandrel/issues/4207)) ([d4fed9b](https://github.com/dsj1984/mandrel/commit/d4fed9b6a3077c6c9371ec00debae5c422ac89c6))
+* **agents-update:** invoke mandrel via npx and detect install state (refs [#4169](https://github.com/dsj1984/mandrel/issues/4169)) ([#4174](https://github.com/dsj1984/mandrel/issues/4174)) ([9aab7ba](https://github.com/dsj1984/mandrel/commit/9aab7ba3f2c425a5ecaf16e1008078538093a985))
+* **bootstrap:** relax owner/repo under --skip-github so non-interactive init works in a fresh dir ([#4181](https://github.com/dsj1984/mandrel/issues/4181)) ([e560116](https://github.com/dsj1984/mandrel/commit/e560116aa33178f182752558e7d646c2cb7cdeb4))
+* **deps:** bump markdownlint-cli2 0.18.1 -> 0.22.1, force patched js-yaml/markdown-it (refs [#4187](https://github.com/dsj1984/mandrel/issues/4187)) ([#4200](https://github.com/dsj1984/mandrel/issues/4200)) ([9fe1e09](https://github.com/dsj1984/mandrel/commit/9fe1e09daf91fab0ca5d44d5a701cd2576406a5b))
+* **install-matrix:** hoist mandrel runtime deps in pnpm legs so doctor is honest ([#4180](https://github.com/dsj1984/mandrel/issues/4180)) ([5e7aca7](https://github.com/dsj1984/mandrel/commit/5e7aca7d48b9ab9d0ddd5c157a28bea8978fb90a))
+
+
+### Performance
+
+* **baselines:** collapse the two escomplex passes in full-tree regen into one (refs [#4192](https://github.com/dsj1984/mandrel/issues/4192)) ([#4205](https://github.com/dsj1984/mandrel/issues/4205)) ([4f971c3](https://github.com/dsj1984/mandrel/commit/4f971c36723521058322b346980d6e1822c9d35d))
+* **doctor:** short-circuit payload-drift on statSync size mismatch (refs [#4193](https://github.com/dsj1984/mandrel/issues/4193)) ([#4204](https://github.com/dsj1984/mandrel/issues/4204)) ([a85c050](https://github.com/dsj1984/mandrel/commit/a85c0501a02ff346024fa9d8c9aa48046999f08c))
+
+
+### Changed
+
+* **agents-update:** extract quality-bootstrap heredoc into a tested script (refs [#4171](https://github.com/dsj1984/mandrel/issues/4171)) ([#4178](https://github.com/dsj1984/mandrel/issues/4178)) ([032ecf7](https://github.com/dsj1984/mandrel/commit/032ecf70f5840ad5291c0bcdb6b11a9d23bec1be))
+* **baselines:** triage dead-export allowlist 198 -> 185 (refs [#4184](https://github.com/dsj1984/mandrel/issues/4184)) ([#4197](https://github.com/dsj1984/mandrel/issues/4197)) ([2a39e61](https://github.com/dsj1984/mandrel/commit/2a39e616bb9a843325bf151d8f057f85a43fcd95))
+* **renderers:** table-drive flat section ladders to lower CC ceilings (refs [#4186](https://github.com/dsj1984/mandrel/issues/4186)) ([#4201](https://github.com/dsj1984/mandrel/issues/4201)) ([36df937](https://github.com/dsj1984/mandrel/commit/36df9370d8e9cdef8f6bc47d0341ef8425314222))
+* **update:** retire No-Shim in-process path and extract pure planUpdate (refs [#4182](https://github.com/dsj1984/mandrel/issues/4182)) ([#4198](https://github.com/dsj1984/mandrel/issues/4198)) ([d5ed325](https://github.com/dsj1984/mandrel/commit/d5ed32560d98fa43d6103789efac530f16244a91))
+* **wave-runner:** decompose tick() into coordinator + phases (refs [#4183](https://github.com/dsj1984/mandrel/issues/4183)) ([#4196](https://github.com/dsj1984/mandrel/issues/4196)) ([0d7a6b4](https://github.com/dsj1984/mandrel/commit/0d7a6b4326b60ec3f2dd58a0798c8a37b6117d9c))
+
+## [1.69.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.68.0...mandrel-v1.69.0) (2026-06-16)
+
+
+### Added
+
+* Epic [#4151](https://github.com/dsj1984/mandrel/issues/4151) ([#4159](https://github.com/dsj1984/mandrel/issues/4159)) ([f4ad69b](https://github.com/dsj1984/mandrel/commit/f4ad69b1663fca95c8e121f837a2e511ab306706))
+* Epic [#4158](https://github.com/dsj1984/mandrel/issues/4158) ([#4167](https://github.com/dsj1984/mandrel/issues/4167)) ([939265e](https://github.com/dsj1984/mandrel/commit/939265ef589a24a72d6beebad14197a245ec31ec))
+
+
+### Fixed
+
+* **baselines:** apply ignoreGlobs in diff-scope maintainability refresh ([#4166](https://github.com/dsj1984/mandrel/issues/4166)) ([436e3a4](https://github.com/dsj1984/mandrel/commit/436e3a424db9aac54f720a9a993ad0dd285998f3))
+* **lifecycle:** allow epicId in epic.automerge.end schema so the CLI can emit it ([#4168](https://github.com/dsj1984/mandrel/issues/4168)) ([5536cdc](https://github.com/dsj1984/mandrel/commit/5536cdc348e4958b9d05eebd3cd90e1554a1675c))
+
 ## [1.68.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.67.0...mandrel-v1.68.0) (2026-06-15)
 
 

package/lib/cli/registry.js

@@ -371,7 +371,14 @@ function runRuntimeDeps({
   return {
     ok: false,
     detail: `missing: ${missing.join(', ')}`,
-    remedy: `Run \`npm install\` in the repository root to install missing packages: ${missing.join(', ')}`,
+    remedy:
+      'The framework runtime deps are not resolvable from the consumer root, ' +
+      'where the materialized .agents/scripts/*.js run. npm and yarn hoist ' +
+      "them automatically — run the installer if you haven't. pnpm's default " +
+      'isolated layout does NOT hoist transitive deps to the top level: add ' +
+      '`shamefully-hoist=true` (or a scoped `public-hoist-pattern[]` for ' +
+      'each dep) to your `.npmrc` and reinstall. ' +
+      `Missing: ${missing.join(', ')}`,
   };
 }
 
@@ -457,6 +464,39 @@ function runAgentsMaterialized({ cwd, existsSync, resolvePackage } = {}) {
 // from sync.js) are imported from `lib/cli/sync.js` at the top of this file
 // (Story #4048 B3 — no mirror copies).
 
+/**
+ * Decide whether a single materialized payload file has drifted from its
+ * package-payload source.
+ *
+ * Size short-circuit (Story #4193): when the injected `fsImpl` exposes
+ * `statSync`, a `statSync(src).size !== statSync(dest).size` mismatch is
+ * sufficient proof of drift, so it returns `true` on two `stat` syscalls
+ * **without reading either file's contents** — the overwhelmingly common
+ * drift shape after a stale `sync` is a size change. Equal sizes do not
+ * guarantee equal content, so an equal-size pair falls through to the
+ * `readFileSync` + `Buffer.equals` byte comparison. The short-circuit is
+ * opt-in on `statSync` being present; a seam that omits it (e.g. a legacy
+ * test double) transparently uses the byte-read path, preserving the prior
+ * behaviour exactly.
+ *
+ * Security: returns only a boolean — it never surfaces file contents to the
+ * caller (security baseline §5 — Data Leakage & Logging).
+ *
+ * @param {string} src - absolute path to the package-payload file
+ * @param {string} dest - absolute path to the materialized file
+ * @param {{ readFileSync: Function, statSync?: Function }} fsImpl
+ * @returns {boolean} `true` when the files differ
+ */
+function payloadFileDrifted(src, dest, fsImpl) {
+  if (
+    typeof fsImpl.statSync === 'function' &&
+    fsImpl.statSync(src).size !== fsImpl.statSync(dest).size
+  ) {
+    return true;
+  }
+  return !fsImpl.readFileSync(src).equals(fsImpl.readFileSync(dest));
+}
+
 /**
  * Compare the consumer's materialized `./.agents/<f>` bytes against the
  * installed package payload (`node_modules/mandrel/.agents/<f>`),
@@ -469,16 +509,21 @@ function runAgentsMaterialized({ cwd, existsSync, resolvePackage } = {}) {
  * §5 — Data Leakage & Logging). The comparison is short-circuiting and never
  * accumulates file contents.
  *
+ * Performance: per-file drift is decided by `payloadFileDrifted`, which gates
+ * the byte read behind a cheap `statSync` size comparison (Story #4193) so a
+ * size-changed file — the common drift shape after a stale `sync` — reports
+ * without reading either file's contents.
+ *
  * Injectable seams (used by tests so no real filesystem or package is needed):
  * - `cwd()` — replaces `process.cwd`.
  * - `fsImpl` — replaces the `node:fs` surface (`existsSync`, `readdirSync`,
- *   `readFileSync`).
+ *   `readFileSync`, and optionally `statSync` for the size short-circuit).
  * - `resolvePackageRoot(fromDir)` — replaces `mandrel` resolution;
  *   throws when the package is not installed.
  *
  * @param {{
  *   cwd?: () => string,
- *   fsImpl?: { existsSync: (p: string) => boolean, readdirSync: Function, readFileSync: Function },
+ *   fsImpl?: { existsSync: (p: string) => boolean, readdirSync: Function, readFileSync: Function, statSync?: Function },
  *   resolvePackageRoot?: (fromDir: string) => string,
  * }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -534,10 +579,8 @@ export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
       };
     }
 
-    const srcBytes = fsImpl.readFileSync(src);
-    const destBytes = fsImpl.readFileSync(dest);
     comparedCount += 1;
-    if (!srcBytes.equals(destBytes)) {
+    if (payloadFileDrifted(src, dest, fsImpl)) {
       return {
         ok: false,
         detail: `${relLabel} differs from the installed package payload`,