mandrel 1.69.0 → 1.71.0

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

@@ -6,12 +6,12 @@ description: QA Epic-testing workflow — ingest the agent-driven QA harness swe
 
 > **Helper module.** Not a slash command. Invoked from the QA gate during
 > `/deliver` or directly by an operator when the Epic-testing ticket
-> needs refreshed evidence. For ad-hoc acceptance runs use `/qa-run-harness` —
+> needs refreshed evidence. For ad-hoc acceptance runs use `/qa-run` —
 > this helper owns the Epic-evidence ticket lifecycle on top of it.
 
 Gather and attach the acceptance-suite evidence that gates Epic closure. The
 evidence artifact is the **agent-driven QA harness sweep report** produced by
-`/qa-run-harness` (scenario pass/fail/blocked totals plus structured
+`/qa-run` (scenario pass/fail/blocked totals plus structured
 findings), **not** a hand-ticked markdown checklist.
 
 > **When to run**: During the QA phase of an Epic, after all Story merges
@@ -38,13 +38,13 @@ findings), **not** a hand-ticked markdown checklist.
 
 ## Step 1 — Execute the QA Harness Sweep
 
-Invoke `/qa-run-harness` with the chosen selector:
+Invoke `/qa-run` with the chosen selector:
 
 ```text
-/qa-run-harness "tag:@smoke and @risk-high"
+/qa-run "tag:@smoke and @risk-high"
 ```
 
-The `/qa-run-harness` workflow (`.agents/workflows/qa-run-harness.md`) owns the
+The `/qa-run` workflow (`.agents/workflows/qa-run.md`) owns the
 execution mechanics — `qa` contract resolution, scenario selection, browser
 navigation, and finding capture. This workflow consumes its output.
 
@@ -117,7 +117,7 @@ and deleting the checklist in the same change.
 
 ## Cross-References
 
-- Execution mechanics: `.agents/workflows/qa-run-harness.md`.
+- Execution mechanics: `.agents/workflows/qa-run.md`.
 - Scenario authoring rules: `.agents/rules/gherkin-standards.md`.
 - Runner / fixture / trace conventions:
   `.agents/skills/stack/qa/playwright-bdd/SKILL.md`.

package/.agents/workflows/helpers/{agents-sync-config.md → mandrel-sync-config.md}

@@ -5,15 +5,16 @@ description: >-
   surfacing redundant keys (project values that already match framework
   defaults). The runtime layers defaults at read time, so the helper never
   auto-fills optional keys from the template. Invoked by reference from
-  /agents-update.
+  /mandrel-update.
 ---
 
-# agents-sync-config (helper)
+# mandrel-sync-config (helper)
 
 > **Not a slash command.** Lives under `.agents/workflows/helpers/` so it is
 > not projected into the mandrel plugin command tree. Invoked by reference from
-> [`/agents-update`](../agents-update.md) after a framework update; previously
-> shipped as `/agents-sync-config`. The reconciliation runs as part of the
+> [`/mandrel-update`](../mandrel-update.md) after a framework update; previously
+> shipped as the standalone `/agents-sync-config` command (later demoted to a
+> helper, then renamed alongside `/mandrel-update`). The reconciliation runs as part of the
 > `mandrel update` upgrade path (bump → sync → migrate → doctor).
 >
 > **Configuration reference.** The full set of configurable keys, defaults,

package/.agents/workflows/{agents-update.md → mandrel-update.md}

@@ -1,6 +1,6 @@
 ---
 description: >-
-  npm-era upgrade wraparound for a Mandrel consumer. Runs `mandrel update`
+  npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update`
   (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
@@ -10,12 +10,12 @@ description: >-
   stage + commit the staged lockfile bump.
 ---
 
-# /agents-update
+# /mandrel-update
 
 > **Upgrade owner.** The mechanical upgrade is owned end to end by the
 > [`mandrel update`](../../lib/cli/update.js) CLI under the npm distribution
 > model (`mandrel`, #3436/#3437). This workflow wraps that CLI: it
-> runs `mandrel update`, then walks the operator through the
+> 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
 > permission-allowlist refresh, the consumer-side changelog reconciliation,
@@ -23,7 +23,7 @@ description: >-
 
 ## Overview
 
-`/agents-update` advances the consumer repo to the newest published
+`/mandrel-update` advances the consumer repo to the newest published
 `mandrel` release, re-materializes `.agents/`, and regenerates the
 flat `.claude/commands/` tree (invoked as `/<name>`) against the new workflow
 set — then reconciles the consumer's own config, harness allowlist, and
@@ -60,22 +60,105 @@ The upgrade contract:
 > **Persona**: `devops-engineer` · **Skills**:
 > `core/ci-cd-and-automation`, `core/documentation-and-adrs`
 
+**Invocation form.** In a consumer project `mandrel` is a local
+devDependency at `node_modules/.bin/mandrel` and is **not** on `PATH`, so a
+bare `mandrel <subcommand>` fails with `command not found` before any of the
+hardened CLI logic ([`lib/cli/update.js`](../../lib/cli/update.js)) runs.
+Every **runnable** command in this workflow therefore uses the
+`npx mandrel <subcommand>` form, matching [`README.md`](../../README.md).
+Prose that names the CLI as a noun (e.g. "`mandrel update`'s sync step")
+refers to the binary by name, not as a command to type — run it via the form
+Step 0 selects. The exception is a project where `mandrel` is installed
+**globally**: there, the bare form works and Step 0 says so.
+
+## Step 0 — Detect the install state and pick the invocation form
+
+Before running the updater, detect how `mandrel` resolves in this project and
+route to the matching invocation form. Run from the consumer repo root:
+
+```bash
+# 1. Globally installed and on PATH?
+command -v mandrel
+# 2. Installed as a local devDependency?
+ls node_modules/.bin/mandrel 2>/dev/null || npm ls mandrel
+```
+
+Three real states, three routes:
+
+| State                                   | Detection                                                              | Invocation form                                                   |
+| --------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| **Global install (on `PATH`)**          | `command -v mandrel` prints a path                                     | Bare `mandrel <subcommand>` works.                                |
+| **Local devDependency (not on `PATH`)** | `command -v mandrel` is empty; `node_modules/.bin/mandrel` exists      | Use `npx mandrel <subcommand>` (resolves the local bin).          |
+| **Not installed**                       | `command -v mandrel` empty **and** `node_modules/.bin/mandrel` absent  | Run `npm install -D mandrel` first, then `npx mandrel`.           |
+
+The common consumer case is **local devDependency** — `npx mandrel` is the
+default form the rest of this workflow uses. On a global install you may drop
+the `npx` prefix; on a fresh project, install the package first. The `npx`
+form is harmless on a global install too (it prefers the local bin and falls
+back to a one-off fetch), so when unsure, use `npx mandrel`.
+
+## Step 0.5 — First-run preflight (before any bump)
+
+Before running the updater, run the first-run preflight. It catches three
+day-0 failure modes — **wrong project**, a **dirty git index**, and being
+**offline** — before `npx mandrel update` bumps anything. Run from the
+consumer repo root:
+
+```bash
+node .agents/scripts/mandrel-update-preflight.js
+```
+
+The preflight runs three checks and prints a JSON envelope
+(`{ ok, blocked, findings[] }`) on stdout plus a human-readable report:
+
+| Check              | Severity            | What it verifies                                                                                                                                                       |
+| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **consumer-shape** | **blocker** (exit 2) | `package.json` lists `mandrel` as a dependency **and** a `.agents/` directory exists. Hard-stops in the framework repo itself or any non-consumer project.             |
+| **dirty-index**    | warn-only           | The git index has no pre-existing staged changes. `mandrel update` leaves the lockfile staged and Step 5 would otherwise sweep unrelated staged files into the commit. |
+| **offline**        | warn-only           | The npm registry is reachable (`npm ping`), so the version probe in Step 1 will not fail with a confusing offline error.                                               |
+
+Severity follows framework preflight conventions (cf.
+[`epic-deliver-preflight.js`](../scripts/epic-deliver-preflight.js), the
+`story-close` preflight): the **consumer-shape** check is a hard stop — the
+script exits `2` and you MUST NOT proceed until it is resolved; **dirty-index**
+and **offline** are warn-only and never block the run.
+
+Routing:
+
+- **Exit 0, `ok: true`** — all checks passed; proceed to Step 1.
+- **Exit 0 with warnings** (`blocked: false`, non-empty `findings[]`) —
+  review the warnings. For **dirty-index**, unstage unrelated changes
+  (`git restore --staged <path>`) so they are not swept into the
+  `chore: update mandrel` commit. For **offline**, restore connectivity
+  before the version probe. Then proceed.
+- **Exit 2, `blocked: true`** — the consumer-shape check failed. Stop. You
+  are not in a Mandrel consumer project (wrong directory, the framework repo
+  itself, or a project that never ran `mandrel sync`). `cd` into the consumer
+  repo, or bootstrap one with `npm install -D mandrel && npx mandrel sync`,
+  then re-run the preflight.
+
+> **Scope.** The preflight is a **workflow-layer** guard; it deliberately
+> lives outside [`lib/cli/update.js`](../../lib/cli/update.js), which stays
+> git-free and side-effect-scoped. It composes cleanly with the Step 0
+> invocation-form detection above — Step 0 picks *how* to call the updater;
+> Step 0.5 verifies it is *safe* to call it at all.
+
 ## Step 1 — Run the updater
 
 Preview first, then apply. From the consumer repo root:
 
 ```bash
-mandrel update --dry-run
-mandrel update
+npx mandrel update --dry-run
+npx mandrel update
 ```
 
-`mandrel update --dry-run` resolves the newest published version and prints
-the ordered step plan (`npm-update → runSync → runMigrations → doctor →
+`npx mandrel update --dry-run` resolves the newest published version and
+prints the ordered step plan (`npm-update → runSync → runMigrations → doctor →
 surface changelog`) without invoking any effectful seam — no dependency bump,
 no sync, no migrations, no doctor, nothing written. Read the planned target
 version before applying.
 
-`mandrel update` (no flags) runs the live cycle:
+`npx mandrel update` (no flags) runs the live cycle:
 
 1. **Resolve target** — the newest published `mandrel` version (via
    the daily freshness cache in `temp/version-check.json`) and the currently
@@ -130,6 +213,86 @@ mandrel update — planned upgrade v1.44.0 → v1.46.0
 Dry run: no files written, no dependency bumped.
 ```
 
+## Step 2.5 — Partial-upgrade recovery (**blocker — resolve before Step 5**)
+
+`mandrel update` runs its post-install phases in order — **install** →
+**sync** → **sync-commands** → **migrate** → **doctor** — and the install
+phase bumps `package.json` / `package-lock.json` and leaves the change
+**staged on disk** *before* any of the later phases run. By deliberate
+design the CLI **never rolls back the install on failure** (the lockfile
+bump is left staged for the operator — see the Out-of-Scope note in
+[`lib/cli/update.js`](../../lib/cli/update.js)). So when a post-install
+phase exits non-zero, you land in a **partially-upgraded state**:
+
+- The lockfile bump to the new version is **already staged**, *and*
+- `.agents/` may be **half-materialized** (sync failed midway), the flat
+  `.claude/commands/` tree may be **out of sync** (sync-commands failed), a
+  version-keyed migration may have **partially applied** (migrate failed), or
+  the post-upgrade state failed validation (doctor failed).
+
+This is the dangerous case the whole workflow exists to guard: the operator
+is now **one `git commit` away** (Step 5) from recording a broken
+half-upgrade as "done". `mandrel update` prints the per-phase manual remedy
+to **stderr**, but a line buried in stderr is easy to scroll past and commit
+right over. **Treat any post-install phase failure as an explicit blocker:
+do not proceed to Step 5 (commit) until the failed phase is recovered and a
+clean re-run reports success.**
+
+When `npx mandrel update` exits non-zero, identify which phase failed (the
+CLI's stderr names it) and run the matching manual remedy from the consumer
+repo root. These commands match the hint strings
+[`lib/cli/update.js`](../../lib/cli/update.js) emits verbatim — it is the
+single source of truth, kept in lockstep with this table by the
+`mandrel-update-recovery-drift` contract test
+([`tests/bootstrap/mandrel-update-recovery-drift.test.js`](../../tests/bootstrap/mandrel-update-recovery-drift.test.js)):
+
+| Failed phase      | Manual remedy                                            |
+| ----------------- | ------------------------------------------------------- |
+| **sync**          | `npx mandrel sync`                                       |
+| **sync-commands** | `npm run sync:commands`                                  |
+| **migrate**       | `npx mandrel migrate --from <cur> --to <target>`        |
+| **doctor**        | `npx mandrel doctor` (then apply the per-check remedies) |
+
+The exact stderr the CLI prints per failed phase — quoted verbatim from
+[`lib/cli/update.js`](../../lib/cli/update.js) so the table above can never
+drift from what the operator actually sees:
+
+- **sync** — the .agents/ materialization may be incomplete. Run `mandrel
+  sync` manually to restore.
+- **sync-commands** — the .claude/commands/ tree may be out of sync. Run `npm
+  run sync:commands` manually to restore.
+- **migrate** — some migrations for v\<cur\> → v\<target\> may not have
+  applied. Run `mandrel migrate --from <cur> --to <target>` manually to retry.
+- **doctor** — upgraded to v\<target\> but doctor reported failures. → Run
+  `mandrel doctor` for remedies.
+
+> **`<cur>` / `<target>`** are the installed and resolved-newest version
+> strings the CLI printed in Step 1 (e.g. `--from 1.44.0 --to 1.46.0`).
+> Substitute the real values the failing run reported.
+
+Recovery sequence:
+
+1. **Run the matching remedy** for the failed phase from the table above.
+2. **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 the per-phase remedy until the run reports
+   `✅  Updated to v<target>. The lockfile bump is staged for review.` (or
+   `✅  Already up to date`).
+3. **Only then proceed** to Step 3. The staged lockfile bump is safe to
+   commit (Step 5) once — and only once — the post-install phases have all
+   gone green.
+
+> **Why not auto-rollback / `mandrel update --resume`?** A `--resume` flag
+> that re-enters the cycle at the failed phase was **evaluated and
+> deferred** (Story #4172, Out of Scope). The per-phase manual remedies
+> above fully cover recovery: each failed phase has an exact, idempotent
+> command, and re-running `npx mandrel update` already short-circuits the
+> completed install and re-drives the remaining phases — so a dedicated
+> resume entrypoint would add a parallel code path without covering any
+> recovery case the manual remedies miss. If a future change makes the
+> phases expensive enough that re-driving completed ones is wasteful,
+> revisit `--resume` then; today it is unnecessary.
+
 ## Step 3 — Reconcile `.agentrc.json` against the new defaults
 
 A framework bump can add or reshape fields in
@@ -156,7 +319,7 @@ The helper (Story #1995) is **default-aware** and **read-only**:
   modified.
 
 Full procedure reference:
-[`helpers/agents-sync-config.md`](helpers/agents-sync-config.md).
+[`helpers/mandrel-sync-config.md`](helpers/mandrel-sync-config.md).
 
 If the helper prints `No changes required` with no advisories, the config
 is already in sync — carry on. If it lists `[REDUNDANT]` rows, you may
@@ -177,22 +340,18 @@ framework version sees `no-change` everywhere here.
 Run from the consumer repo root:
 
 ```bash
-node -e "
-  Promise.all([
-    import('./.agents/scripts/lib/bootstrap/quality-bootstrap.js'),
-    import('./.agents/scripts/lib/bootstrap/baselines-layout-migration.js'),
-  ]).then(([qb, bm]) => {
-    const root = process.cwd();
-    const quality = qb.applyQualityBootstrap({ projectRoot: root });
-    const baselines = bm.migrateBaselinesLayout({
-      baselinesDir: require('node:path').join(root, 'baselines'),
-      repoRoot: root,
-    });
-    console.log(JSON.stringify({ quality, baselines }, null, 2));
-  });
-"
+node .agents/scripts/apply-quality-bootstrap.js
 ```
 
+The script (Story #4171) replaced the prior inline `node -e` heredoc — a
+shell-fragile, untested block that silently drifted whenever the two helper
+signatures moved (see
+[`apply-quality-bootstrap.js`](../scripts/apply-quality-bootstrap.js)). It
+runs the same two installs in order against `process.cwd()` —
+`applyQualityBootstrap` then `migrateBaselinesLayout` — and prints the same
+`{ quality, baselines }` JSON envelope to stdout. It is idempotent: a second
+run is a no-op beyond reporting `no-change` on every install path.
+
 The four `quality-bootstrap` outcomes:
 
 1. **`helper`** — copies
@@ -233,7 +392,7 @@ rest of the per-Epic temp tree):
   contract for the framework.
 
 A second run produces `no-change` on every install path, which is the
-guarantee `agents-update`'s idempotence contract requires.
+guarantee `mandrel-update`'s idempotence contract requires.
 
 ## Step 3.6 — Refresh the harness permission allowlist (`/fewer-permission-prompts`)
 
@@ -272,7 +431,7 @@ auto-applied change:
 - Apply the accepted subset by editing `.claude/settings.json` and
   stage it alongside the version bump in Step 5.
 
-The maintenance cadence is **once per `/agents-update` invocation** —
+The maintenance cadence is **once per `/mandrel-update` invocation** —
 the same operator who just ran `mandrel update` is the one with the
 freshest transcript context to review the proposed allowlist
 diff. Skipping the step is fine when the bump introduces no new
@@ -329,6 +488,14 @@ response."
 
 ## Step 5 — Commit the bump
 
+> **Blocker check before you commit.** The staged lockfile bump is only safe
+> to commit once every post-install phase has gone green. If `npx mandrel
+> update` exited non-zero, you are in a partially-upgraded state — resolve it
+> via [Step 2.5 — Partial-upgrade recovery](#step-25--partial-upgrade-recovery-blocker--resolve-before-step-5)
+> (run the per-phase remedy, re-run the updater to success) **before** running
+> the `git commit` below. Committing over a half-upgrade records a broken
+> state as "done".
+
 `mandrel update` leaves the dependency bump **staged on disk** but never
 commits. After reviewing the surfaced changelog, any `.agentrc.json`
 reconciliation diff from Step 3, the `.claude/settings.json` allowlist
@@ -359,7 +526,7 @@ no-op.
 > distribution `.agents/` is a
 > materialized directory rebuilt from the installed package — whether the
 > consumer commits the regenerated `.agents/` tree, or treats it as a
-> gitignored install artifact rebuilt by `mandrel sync`, depends on the
+> gitignored install artifact rebuilt by `npx mandrel sync`, depends on the
 > consumer's own vendoring policy. Stage the `.agents/` / `.claude/`
 > changes here only if the project commits its materialized tree.
 
@@ -367,21 +534,31 @@ no-op.
 
 - **`doctor reported failures: …`** — the dependency bumped and `.agents/`
   re-materialized, but a doctor check failed (and the run exited
-  non-zero). Run `mandrel doctor` for the per-check remedies. The lockfile
-  bump is already staged; fix the doctor finding (often a missing
-  bootstrap install — Step 3.5 — or a stale `.agentrc.json` — Step 3)
-  before committing in Step 5.
+  non-zero). This is one shape of the **partial-upgrade** failure mode —
+  the lockfile bump is already staged, so it is a **blocker** you MUST
+  resolve before the commit step (see
+  [Step 2.5 — Partial-upgrade recovery](#step-25--partial-upgrade-recovery-blocker--resolve-before-step-5)).
+  Run `npx mandrel doctor` for the per-check remedies; fix the doctor
+  finding (often a missing bootstrap install — Step 3.5 — or a stale
+  `.agentrc.json` — Step 3), re-run `npx mandrel update` until it reports
+  success, and only then commit in Step 5.
+
+- **A post-install phase failed (`sync` / `sync-commands` / `migrate`)** —
+  the install bumped the lockfile but a later phase exited non-zero, leaving
+  a partially-upgraded tree. Do not commit. Run the matching per-phase
+  remedy and re-run the updater per
+  [Step 2.5 — Partial-upgrade recovery](#step-25--partial-upgrade-recovery-blocker--resolve-before-step-5).
 
 - **Install command failed / `npm install … exited <n>`** — the npm
   install step could not bump the dependency (network hiccup, registry
   auth gap, or a peer-dependency conflict). Resolve the underlying npm
-  error and re-run `mandrel update`; it is idempotent — a clean re-run
+  error and re-run `npx mandrel update`; it is idempotent — a clean re-run
   resumes from the resolve step and short-circuits if the install already
   landed.
 
 - **Wrong package manager** — the default install is `npm install`. For a
   pnpm or yarn workspace, pass the package manager explicitly:
-  `mandrel update --install-cmd "pnpm add mandrel@<target>"`.
+  `npx mandrel update --install-cmd "pnpm add mandrel@<target>"`.
   The registry probe always stays on `npm view` (a PM-agnostic query); only
   the install seam honours the override.
 

package/.agents/workflows/qa-explore.md

@@ -19,7 +19,7 @@ operator watches and gates.** Its human-led sibling is
 the agent scribes/enriches. No human-driven flow lives in `/qa-explore`; if you
 want to capture something *you* observed, use `/qa-assist` instead.
 
-Unlike [`/qa-run-harness`](qa-run-harness.md) (which steps a known set of
+Unlike [`/qa-run`](qa-run.md) (which steps a known set of
 Gherkin `.feature` scenarios through a browser), `/qa-explore` is **open-ended
 exploration**: the agent probes the surface for product bugs, environment-setup
 friction, tooling/DX gaps, missing tests, and enhancement ideas — each captured

package/.agents/workflows/{qa-run-harness.md → qa-run.md}

@@ -2,7 +2,7 @@
 description: Drive Gherkin scenarios through a real browser as an agent-driven QA sweep
 ---
 
-# /qa-run-harness
+# /qa-run
 
 Execute a consumer's Gherkin `.feature` scenarios through a **real browser**
 (the chrome-devtools MCP surface), with the agent acting as the step executor
@@ -31,7 +31,7 @@ console filtering.
 ## Slash Command
 
 ```text
-/qa-run-harness <selector>
+/qa-run <selector>
 ```
 
 ### Arguments
@@ -58,9 +58,9 @@ deterministic, `(file, line)`-sorted scenario set under the contract's
 ### Examples
 
 ```text
-/qa-run-harness feature:login
-/qa-run-harness "tag:@smoke and not @wip"
-/qa-run-harness domain:billing
+/qa-run feature:login
+/qa-run "tag:@smoke and not @wip"
+/qa-run domain:billing
 ```
 
 The canonical tag taxonomy — `@smoke`, `@risk-high`, `@platform-web`,

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
@@ -138,6 +158,26 @@ npx mandrel sync                        # re-materialize ./.agents/
 npx mandrel doctor                      # verify the install
 ```
 
+## Benchmarking
+
+Mandrel's effectiveness is measured by a separate companion repo,
+**[mandrel-bench](https://github.com/dsj1984/mandrel-bench)** — a *consumer* of
+the published `mandrel` package. It pins a specific framework version,
+materializes it via `mandrel sync`, and drives Mandrel's own `/plan`→`/deliver`
+pipeline (plus a bare-model control) over a scenario corpus. Each run is scored
+across five dimensions — Quality, Planning fidelity, and Autonomy (what the
+scaffolding *buys*) versus Efficiency and Overhead ratio (what it *costs*) —
+reported as distributions with a noise-band, tracking the framework's
+**value-add over the bare-model baseline** across versions and models.
+
+The benchmark lives in its own repo on purpose: holding the harness fixed while
+varying the pinned `mandrel` version cleanly decouples harness-version from
+framework-version, and running through the published-package + `mandrel sync`
+path exercises the real consumer contract. The dependency is one-directional —
+`mandrel-bench` depends on `mandrel`, never the reverse. See the
+[mandrel-bench README](https://github.com/dsj1984/mandrel-bench#readme) for the
+dimensions, run model, and how to benchmark a new version.
+
 ## Contributors
 
 Only `.agents/` is distributed to consumers — it ships inside the

package/docs/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.71.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.70.0...mandrel-v1.71.0) (2026-06-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* **workflows:** three operator-facing slash commands are renamed and three git commands are consolidated. Consumers must update muscle memory and any scripts: `/agents-update`→`/mandrel-update`, `/qa-run-harness`→`/qa-run`, and `/git-commit-all` / `/git-push` / `/git-pr-all`→`/git-deliver` (detection picks the old behavior by default; `--no-push` reproduces `/git-commit-all`, a feature-branch run reproduces `/git-push`, and a base-branch run or `--pr` reproduces `/git-pr-all`).
+
+### Changed
+
+* **workflows:** rename agents-update→mandrel-update, qa-run-harness→qa-run; collapse 3 git commands into git-deliver ([#4209](https://github.com/dsj1984/mandrel/issues/4209)) ([fc30a3d](https://github.com/dsj1984/mandrel/commit/fc30a3d579d80fd854217e066f97899b813c6be9))
+
+## [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)
 
 

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`,