mandrel 1.94.0 → 2.1.0

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

@@ -37,16 +37,14 @@ and dedup/route decisions. The agent never invents those decisions in prose.
 > a structured agent-driven bug-hunt the operator wants captured into a
 > triageable ledger.
 >
-> **Persona**: `qa-engineer` · **Skills**: `core/qa-coverage-mapping`,
-> `stack/qa/qa-explore-driving`
+> **Skills**: `core/qa-coverage-mapping`, `stack/qa/qa-explore-driving`
 
-## Persona
+## Role framing
 
-Adopt the **`qa-engineer`** persona
-([`.agents/personas/qa-engineer.md`](../personas/qa-engineer.md)) for the whole
-run. You are the quality gatekeeper: you value coverage, hermetic
-environments, and deterministic results. Re-read that persona file as your
-first action so the Plan/Capture/Triage loop is governed by it.
+You are the quality gatekeeper for this run: value coverage, hermetic
+environments, and deterministic results. Do **not** invent signal — capture
+what the surface shows. Apply the QA skills below; there is no separate
+persona pack.
 
 ## Driving conventions skill
 
@@ -89,10 +87,10 @@ ledger**; do not switch methods mid-surface without a new Plan note.
 | --------- | -------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
 | `surface` | yes      | `feature:login`, `area:onboarding` | A human label for the single surface to explore. Recorded as each ledger item's `coverage`. |
 
-If no `surface` is supplied, **stop and ask** the operator to name one — the
-`qa-engineer` Golden Rule forbids inventing scope. `/qa-explore` is **bounded
-to one surface per session**: explore exactly the named surface, do not wander
-into adjacent surfaces, and start a fresh session for a different surface.
+If no `surface` is supplied, **stop and ask** the operator to name one — do
+not invent scope. `/qa-explore` is **bounded to one surface per session**:
+explore exactly the named surface, do not wander into adjacent surfaces, and
+start a fresh session for a different surface.
 
 ## Project contract
 
@@ -161,7 +159,7 @@ advances phases autonomously. If the operator does not confirm, stop and hold.
 Goal: agree on **what** will be explored and **how the agent will drive it**
 before touching the surface.
 
-1. Re-read the `qa-engineer` persona and the
+1. Re-read the
    [`stack/qa/qa-explore-driving`](../skills/stack/qa/qa-explore-driving/SKILL.md)
    skill, and resolve the `qa` contract and session (above).
 2. **Resolve the target environment** via
@@ -339,33 +337,26 @@ For each untriaged ledger item:
    import { promoteFindings } from '../scripts/lib/findings/promote-finding.js';
    const { promotions } = await promoteFindings(ledgerItems, {
      searchIssues, // GitHub provider, open + closed
-     createStory, // tight cluster (≤2 surfaces): render seed → /plan --from-notes
-     createEpic, // broad cluster (>2 surfaces): render seed → /plan --idea
+     createStory, // tight cluster (≤2 surfaces): seed → /plan --seed-file
+     createPlanSeed, // broad cluster (>2 surfaces): same /plan --seed-file path (may N>1)
    });
    ```
 
    - **Sizing is delegated, not decided in prose.** `promoteFindings` runs
      `clusterLedgerItems` + `targetForCluster`: a cluster spanning **≤2**
      distinct coverage surfaces routes to `createStory`; **>2** routes to
-     `createEpic`. The workflow introduces no new sizing, clustering, or dedup
-     logic — `route-finding.js` / `promote-finding.js` remain the single
-     implementation.
-   - **`createStory` (`/plan --from-notes`)** — render a **redacted**
-     `--from-notes` seed from the cluster (reuse the `/audit-to-stories`
-     Phase 5b notes shape; redaction already ran in Capture), **stamp the
+     `createPlanSeed`. Neither port opens an Epic ticket — both chain
+     `/plan --seed-file`. The workflow introduces no new sizing, clustering,
+     or dedup logic — `route-finding.js` / `promote-finding.js` remain the
+     single implementation.
+   - **`createStory` / `createPlanSeed` (`/plan --seed-file`)** — render a
+     **redacted** plan seed from the cluster (reuse the `/audit-to-stories`
+     Phase 5a seed shape; redaction already ran in Capture), **stamp the
      cluster's `fingerprintFooter(sha)` verbatim into the seed body**, then
-     chain `/plan --from-notes <seed>`. The footer must survive into the issue
-     body the Story create path writes — it round-trips through
-     `story-plan.js --body <file> --dry-run` unchanged (asserted by the
-     deterministic round-trip test under `tests/`) so a later `routeFinding`
-     dedups the same finding instead of re-filing it.
-   - **`createEpic` (`/plan --idea`)** — carry the cluster's
-     `fingerprintFooter(sha)` into the `/plan --idea` seed, then chain
-     `/plan --idea <seed>`. **Known limitation (not solved here):**
-     per-child-Story fingerprint propagation through full Epic decomposition is
-     *not* guaranteed — the fingerprint is carried in the Epic seed only; the
-     child Stories `/plan` spawns from that seed are not individually
-     footer-stamped.
+     chain `/plan --seed-file <seed>`. Prefer one Story; split only under
+     the default-single policy. The footer must survive into the issue body
+     so a later `routeFinding` dedups the same finding instead of re-filing
+     it.
    - **A `file` disposition never opens a raw GitHub Issue.** Every `file`
      finding flows through `promoteFindings` → `/plan`; only `defer` and
      `dismiss` skip the `/plan` handoff.
@@ -379,8 +370,8 @@ For each untriaged ledger item:
 After triage, write the updated dispositions back to the ledger (still under
 `temp/qa/`), and summarize: items captured, the driving method used, classes,
 routes (`new`/`update-existing`/`duplicate`/`regression-of-closed`), the
-Stories (`/plan --from-notes`) and Epics (`/plan --idea`) promoted, and the
-deferred rolling backlog that a resumed session will pick up.
+Stories (`/plan --seed-file`) promoted, and the deferred rolling backlog
+that a resumed session will pick up.
 
 ---
 
@@ -423,7 +414,7 @@ deferred rolling backlog that a resumed session will pick up.
   deterministic — never re-derive them in prose.
 - **Promote through `/plan`, never a raw Issue.** A `file`-dispositioned
   finding is promoted via `promoteFindings`, which chains into
-  [`/plan`](plan.md) (`--from-notes` for a tight cluster, `--idea` for a broad
+  [`/plan`](plan.md) (`--seed-file` for a tight cluster, `--seed` for a broad
   one) — mirroring [`/audit-to-stories`](audit-to-stories.md). `/qa-explore`
   never opens a bare GitHub Issue for a `file` finding. The cluster's
   `fingerprintFooter(sha)` is stamped verbatim into the seed so a future
@@ -435,8 +426,8 @@ deferred rolling backlog that a resumed session will pick up.
 ## See also
 
 - [`/plan`](plan.md) — the planning pipeline `/qa-explore` Triage chains into
-  for a `file`-dispositioned finding (`--from-notes` for a Story, `--idea` for
-  an Epic). The plan→deliver hard stop is preserved across the handoff.
+  for a `file`-dispositioned finding (`--seed-file` / `--seed`). The
+  plan→deliver hard stop is preserved across the handoff.
 - [`/qa-assist`](qa-assist.md) — the human-led sibling that enriches a single
   operator observation and triages through the same `/plan` handoff.
 - [`/audit-to-stories`](audit-to-stories.md) — the precedent for the

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

@@ -381,17 +381,13 @@ For each untriaged ledger item:
    [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) — the
    same cluster/size/route/file path `/qa-explore` and `/audit-to-stories`
    consume (`clusterLedgerItems` + `targetForCluster`: a cluster spanning ≤2
-   coverage surfaces routes to `createStory` via `/plan --from-notes`, >2 to
-   `createEpic` via `/plan --idea`, with the cluster's `fingerprintFooter(sha)`
+   coverage surfaces routes to `createStory` via `/plan --seed-file`, >2 to
+   `createPlanSeed` via `/plan --seed`, with the cluster's `fingerprintFooter(sha)`
    stamped verbatim into the seed). A `file` disposition never opens a raw
    GitHub Issue; only `defer` and `dismiss` skip the `/plan` handoff.
 5. **Gate:** any ticket-filing, seed write, `/plan` invocation, or label
    mutation is a write — confirm each with the operator before it happens.
 
-If the run was triggered from an Epic-testing context, hand the approved,
-promoted findings to the Epic-testing helper for attachment to the Epic's QA
-evidence ticket.
-
 ## Step 6 — Report
 
 Summarize the sweep in chat with:

package/README.md

@@ -3,7 +3,7 @@
 [![CI / CD](https://github.com/dsj1984/mandrel/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dsj1984/mandrel/actions/workflows/ci.yml)
 
 An opinionated workflow framework for AI coding assistants built on
-Epic-centric GitHub orchestration. Planning, execution, and state all live
+Story-centric GitHub orchestration. Planning, execution, and state all live
 natively in GitHub Issues, Labels, and Projects V2.
 
 ## Prerequisites
@@ -35,7 +35,8 @@ npx mandrel init        # install mandrel → sync → prompt → bootstrap →
 
 ```text
 # then, inside Claude Code (commands load from .claude/commands/):
-/plan          # ideation -> PRD/Tech Spec -> Epic with child Stories
+/plan --seed "…"   # interrogate → author one Story (default) → persist
+/deliver <id>      # story-<id> → PR → main
 ```
 
 `npx mandrel init` installs `mandrel` (when `./.agents/` is absent),
@@ -47,9 +48,9 @@ any time to configure). Pass `--assume-yes` for a non-interactive run that
 proceeds straight to configure (and forwards the flag to bootstrap). When
 `./.agents/` is already present (you ran `npm install mandrel` first), `init`
 skips the install/sync and goes straight to the prompt. Once `mandrel init`
-completes, you land at the `/plan` handoff — run `/plan --idea "<seed>"` to
-start planning your first Epic, then deliver it with `/deliver <id>` (wave
-loop → validation → review → retro → open PR).
+completes, you land at the `/plan` handoff — run `/plan --seed "<idea>"` to
+author your first Story, then deliver it with `/deliver <storyId>`
+(`story-<id>` → PR → `main`).
 
 ### Manual equivalent
 
@@ -217,9 +218,9 @@ against malicious lifecycle scripts in compromised transitive packages
 install scripts for a specific install, run
 `npm install --ignore-scripts=false` for that invocation only.
 
-CRAP and Maintainability gates fire at every checkpoint (keystroke,
-pre-commit, pre-push, story-close, CI, Epic merge) against the same
-thresholds from `delivery.quality.*` in `.agentrc.json`.
+CRAP and Maintainability gates fire at three sites — close-validation
+(story close), `.husky/pre-push`, and CI (`ci.yml`, push + PR) — against
+the same thresholds from `delivery.quality.*` in `.agentrc.json`.
 
 ## License
 

package/bin/mandrel.js

@@ -57,7 +57,18 @@ const SUBCOMMANDS = new Map([
     'sync-commands',
     {
       description: 'regenerate .claude/commands/ from .agents/workflows/',
-      knownFlags: new Set(['--dry-run']),
+      // No --dry-run: the projection scripts have no preview mode, and
+      // accepting the flag while syncing for real overwrote .claude/ on an
+      // operator who asked for a preview. Reject it at the dispatcher.
+      knownFlags: new Set([]),
+    },
+  ],
+  [
+    'sync-agents',
+    {
+      description: 'regenerate .claude/agents/ from .agents/agents/',
+      // Same contract as sync-commands: no preview mode, so no --dry-run.
+      knownFlags: new Set([]),
     },
   ],
   [

package/docs/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.1.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.0.0...mandrel-v2.1.0) (2026-07-17)
+
+
+### ⚠ BREAKING CHANGES
+
+* **plan:** plan-persist.js no longer accepts --risk-verdict and no plan-time step authors a risk verdict; review depth and the acceptance critic mode are derived from the diff at close time.
+* /deliver no longer accepts --run <planRunId> or --dep, and /plan no longer applies a plan-run::<id> label. Deliver Story ids; the graph resolves itself from live state.
+
+### Added
+
+* /deliver takes only Story ids and resolves dependencies dynamically (retire plan-run) ([#4540](https://github.com/dsj1984/mandrel/issues/4540)) ([#4560](https://github.com/dsj1984/mandrel/issues/4560)) ([e9935cc](https://github.com/dsj1984/mandrel/commit/e9935cc332b43862d79dca9979691077327e1882))
+* **dead-exports:** add a production-mode pass that discounts test-only importers (refs [#4575](https://github.com/dsj1984/mandrel/issues/4575)) ([#4582](https://github.com/dsj1984/mandrel/issues/4582)) ([0a77ca9](https://github.com/dsj1984/mandrel/commit/0a77ca91bdd67a294b66cc076e45c43bc4d691c8))
+* **deliver:** script-owned land tail, resumable pending status, terminal envelope, and deliver-recover ([#4543](https://github.com/dsj1984/mandrel/issues/4543)) ([#4566](https://github.com/dsj1984/mandrel/issues/4566)) ([f234306](https://github.com/dsj1984/mandrel/commit/f234306d1465fe96d19d361f1501ad8edf055cc3))
+* **plan:** close --tickets source issues as superseded by default ([#4535](https://github.com/dsj1984/mandrel/issues/4535)) ([#4553](https://github.com/dsj1984/mandrel/issues/4553)) ([c35e298](https://github.com/dsj1984/mandrel/commit/c35e29880edba4fec0c45687071fbea242236370))
+* **plan:** mirror sibling depends_on into native blocked_by edges (refs [#4544](https://github.com/dsj1984/mandrel/issues/4544)) ([#4570](https://github.com/dsj1984/mandrel/issues/4570)) ([6b94968](https://github.com/dsj1984/mandrel/commit/6b949688e4fd487c979044f2473e3837a4637e1a))
+
+
+### Fixed
+
+* **bootstrap:** honor command:false in the workflow/command parity check ([#4588](https://github.com/dsj1984/mandrel/issues/4588)) ([493b3eb](https://github.com/dsj1984/mandrel/commit/493b3eb039eefabbd2e33af6a08933d43876c052))
+* **cli:** resolve versions from the consumer, not the running CLI — and make the sync surface fail loudly on skew ([#4530](https://github.com/dsj1984/mandrel/issues/4530)) ([#4536](https://github.com/dsj1984/mandrel/issues/4536)) ([5f20563](https://github.com/dsj1984/mandrel/commit/5f20563eca79203096b49e8fa3dfaa64e2487e12))
+* **cli:** stop sync pruning generated .agents/ files — declare a never-pruned registry so the install ledger survives ([#4534](https://github.com/dsj1984/mandrel/issues/4534)) ([#4552](https://github.com/dsj1984/mandrel/issues/4552)) ([ceccd57](https://github.com/dsj1984/mandrel/commit/ceccd572614a7d8c5226bdd9f1a3b793381be4dd))
+* **column-sync:** stop two more test suites leaking into the shared meta cache ([#4561](https://github.com/dsj1984/mandrel/issues/4561)) ([757e509](https://github.com/dsj1984/mandrel/commit/757e509ff4aa95a091fe9a5de053396a78a26793)), closes [#4555](https://github.com/dsj1984/mandrel/issues/4555)
+* **deliver:** diff the plan-run epilogue against the pre-run base, not origin/main...HEAD (refs [#4550](https://github.com/dsj1984/mandrel/issues/4550)) ([#4558](https://github.com/dsj1984/mandrel/issues/4558)) ([79ddbf6](https://github.com/dsj1984/mandrel/commit/79ddbf61d19bdf256a06aabb860651be6bdce94b))
+* **deliver:** ground the audit roster's lens selection in the landed diff (refs [#4571](https://github.com/dsj1984/mandrel/issues/4571)) ([#4573](https://github.com/dsj1984/mandrel/issues/4573)) ([fa06aca](https://github.com/dsj1984/mandrel/commit/fa06acaedc0c3070516ec32d447f0755a06ea0eb))
+* **deliver:** repair the close-and-land default path (config, operator-merge, follow-ups, reap, reporting) ([#4539](https://github.com/dsj1984/mandrel/issues/4539)) ([#4551](https://github.com/dsj1984/mandrel/issues/4551)) ([9b5c3ee](https://github.com/dsj1984/mandrel/commit/9b5c3ee61b2030e96ff88091761b258eb43fdf43))
+* make `npm run verify` a true CI mirror: include dead-exports + arch-cycles (or catalogue them as CI-only) ([#4549](https://github.com/dsj1984/mandrel/issues/4549)) ([#4557](https://github.com/dsj1984/mandrel/issues/4557)) ([70d088a](https://github.com/dsj1984/mandrel/commit/70d088a646fd1867f3d536c541f89c1c49b0b866))
+* **plan:** make persist resumable and align its gates with the authoring contract ([#4541](https://github.com/dsj1984/mandrel/issues/4541)) ([#4565](https://github.com/dsj1984/mandrel/issues/4565)) ([1cbe974](https://github.com/dsj1984/mandrel/commit/1cbe974154403edab14e006e83f42a5c414150d1))
+* **plan:** make the fan-out deletion gate count importers, not basename word matches ([#4547](https://github.com/dsj1984/mandrel/issues/4547)) ([#4567](https://github.com/dsj1984/mandrel/issues/4567)) ([4c5c724](https://github.com/dsj1984/mandrel/commit/4c5c7248e88136bac83cd91db38658390139c588))
+* **plan:** thread sourceTickets through the envelope so --tickets superseding cannot silently no-op ([#4554](https://github.com/dsj1984/mandrel/issues/4554)) ([#4559](https://github.com/dsj1984/mandrel/issues/4559)) ([4546c40](https://github.com/dsj1984/mandrel/commit/4546c405b2131f6c5afd3ccf40bccb357f4223a0))
+* **quality:** retire the unconsumed miDropMustRefactor/miDropCap knobs and make maintainability.tolerance the single MI-drop control ([#4531](https://github.com/dsj1984/mandrel/issues/4531)) ([#4548](https://github.com/dsj1984/mandrel/issues/4548)) ([fe0c7ce](https://github.com/dsj1984/mandrel/commit/fe0c7ce3ad40e21b957cd6d0a916efbc5e75f634))
+* **skills-index:** emit biome-formatted JSON so regeneration leaves no drift (refs [#4546](https://github.com/dsj1984/mandrel/issues/4546)) ([#4568](https://github.com/dsj1984/mandrel/issues/4568)) ([bdb223e](https://github.com/dsj1984/mandrel/commit/bdb223e2979c0d386ca260b6743cdf2062dbff09))
+
+
+### Changed
+
+* **checks:** drop the dead epic merge-lock and epic-branch probes ([#4581](https://github.com/dsj1984/mandrel/issues/4581)) ([28cb4ab](https://github.com/dsj1984/mandrel/commit/28cb4abf4aa9c0c0120598c26dd5b7220b195678))
+* **docs:** move weight out of always-loaded prompts and skill essays into on-demand references ([#4546](https://github.com/dsj1984/mandrel/issues/4546)) ([#4564](https://github.com/dsj1984/mandrel/issues/4564)) ([14381b3](https://github.com/dsj1984/mandrel/commit/14381b3efd7ce774e39dd47f535bb55991387617))
+* **plan:** derive review depth from the diff and retire the authored risk verdict (refs [#4542](https://github.com/dsj1984/mandrel/issues/4542)) ([#4569](https://github.com/dsj1984/mandrel/issues/4569)) ([7a7fb50](https://github.com/dsj1984/mandrel/commit/7a7fb50f7ec0e33d616fa54618fc0b93c2e310a6))
+
+## [2.0.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.94.0...mandrel-v2.0.0) (2026-07-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* **v2 Story collapse:** one ticket type (`type::story`), one delivery
+  path (`/deliver` → `helpers/deliver-story`), one branch model
+  (`story-<id>` → PR → `main`). `type::epic`, the epic integration
+  branch, wave/dispatch fan-out, and `delivery.routing.singleDelivery`
+  are removed. Per-Story file/AC ceilings are replaced by
+  `planning.modelCapacity` session-mass thresholds. In-flight v1 Epics
+  must land before upgrading.
+
+
+### Features
+
+* collapse `/plan` to a single flat-Story path and retire epic/story routers
+* collapse delivery onto `helpers/deliver-story` with plan-run sequencing
+* deletion sweep for wave/dispatch, epic-runner, and epic lifecycle strata
+* re-key run temp to `temp/run-<id>/`; slim personas and drop `type::epic`
+* drop `delivery.routing.singleDelivery`; land Story-only docs freshness
+
+
+### Documentation
+
+* refresh always-loaded hierarchy prose (`AGENTS.md`, `CLAUDE.md`,
+  `instructions.md` §5, `SDLC.md`, `architecture.md`, consumer README)
+* regenerate `.agents/docs/configuration.md` without the inert
+  `singleDelivery` cell
+
 ## [1.94.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.93.0...mandrel-v1.94.0) (2026-07-13)
 
 

package/lib/cli/registry.js

@@ -31,12 +31,17 @@ import {
   satisfiesNodeEngine,
 } from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
 import { isCommandExcluded } from '../../.agents/scripts/lib/command-header.js';
+import { getDeliveryRouting } from '../../.agents/scripts/lib/config/delivery-routing.js';
 import {
   defaultResolvePackageRoot,
   listFiles as listPayloadFiles,
 } from './sync.js';
 import { readCache } from './version-check.js';
-import { compareVersions as compareSemver } from './version-helpers.js';
+import {
+  compareVersions as compareSemver,
+  resolveConsumerPinSpec,
+  satisfiesPinSpec,
+} from './version-helpers.js';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -309,6 +314,60 @@ function runCommandsInSync({ projectRoot, cwd, readDir, readFile } = {}) {
 // check: agents-in-sync
 // ---------------------------------------------------------------------------
 
+/**
+ * Best-effort raw JSON read — no AJV, no merge validation. Absent, unreadable,
+ * or malformed files degrade to `null` so a config problem never crashes a
+ * doctor check; the caller applies framework defaults on `null`.
+ *
+ * @param {string} absPath
+ * @param {typeof fs} fsImpl
+ * @returns {object | null}
+ */
+function readJsonSafe(absPath, fsImpl) {
+  try {
+    return JSON.parse(fsImpl.readFileSync(absPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve `delivery.routing.roleScopedAgents` (default `true`) for
+ * `agents-in-sync`'s fatal/advisory branch below, WITHOUT importing the full
+ * `resolveConfig()` chain — that chain pulls in AJV (`config-schema.js`),
+ * which would violate this module's own "Node built-ins only" contract (see
+ * the module doc: registry.js must load inside the preflight guard, before
+ * any third-party package is guaranteed present).
+ *
+ * Reads `.agentrc.json` and `.agentrc.local.json` directly and shallow-merges
+ * only the `delivery.routing` block (local wins per-key) — narrower than the
+ * resolver's full deep-merge, but sufficient for this one boolean, and it
+ * still honours a local override rather than silently ignoring it. Delegates
+ * the actual default/coercion to `getDeliveryRouting` (`config/delivery-
+ * routing.js`), which has zero imports of its own and is already the single
+ * source of truth for this default elsewhere in the framework.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} fsImpl
+ * @returns {boolean}
+ */
+function resolveRoleScopedAgentsFlag(projectRoot, fsImpl) {
+  const base = readJsonSafe(path.join(projectRoot, '.agentrc.json'), fsImpl);
+  const local = readJsonSafe(
+    path.join(projectRoot, '.agentrc.local.json'),
+    fsImpl,
+  );
+  const merged = {
+    delivery: {
+      routing: {
+        ...(base?.delivery?.routing ?? {}),
+        ...(local?.delivery?.routing ?? {}),
+      },
+    },
+  };
+  return getDeliveryRouting(merged).roleScopedAgents;
+}
+
 /**
  * Dry-run the sync-claude-agents logic: compare `.agents/agents/*.md` sources
  * to the generated `.claude/agents/*.md` role-agent tree and report parity.
@@ -326,30 +385,52 @@ function runCommandsInSync({ projectRoot, cwd, readDir, readFile } = {}) {
  * A repo with no `.agents/agents/` sources and no `.claude/agents/` tree is a
  * clean no-op (0 sources, 0 dests → "up to date").
  *
- * **Inert-scaffolding divergence from `commands-in-sync` (#4478 PR-2).** The
- * role agents are inert — no workflow spawns them yet — so a **never
- * materialized** agent tree (sources present, but the `.claude/agents/` tree
- * empty) is NOT a readiness failure: it is reported as advisory, not fatal.
- * Once the tree HAS been materialized, drift (a source missing from the dest,
- * or a stale dest file) fails the check exactly like `commands-in-sync`. M7-B
- * (the spawn flip) is where the sync is wired into the delivery flows and this
- * tolerance is tightened.
+ * **Tightened from advisory to fatal (Story #4530, M7-B).** Prior to this
+ * Story, a **never materialized** agent tree (sources present, `.claude/
+ * agents/` empty) was reported as advisory — "inert", because no workflow
+ * spawned the role agents yet. M7-B has landed: `helpers/deliver-story` Step
+ * 1a dispatches `subagent_type: acceptance-critic` on the **default** path
+ * (`roleScopedAgents` defaults `true`). An unmaterialized tree under that
+ * default is no longer a benign scaffolding gap — it is the acceptance
+ * ceremony's fresh-context critic silently failing to spawn and falling back
+ * to a weaker inline critic, with doctor reporting green throughout. This
+ * check now fails in exactly that case. When `roleScopedAgents` is `false`
+ * (the operator kill-switch), an unmaterialized tree is expected — the check
+ * stays advisory. Once the tree HAS been materialized, drift (a source
+ * missing from the dest, or a stale dest file) fails the check exactly like
+ * `commands-in-sync`, unconditionally, exactly as before this Story.
  *
  * Injectable seams (used by tests so no real filesystem is touched):
  * - `cwd()` replaces `process.cwd` so tests can pin the consumer root.
  * - `readDir` replaces `fs.readdirSync`.
+ * - `fsImpl` replaces the `node:fs` surface used for the `.agentrc.json` /
+ *   `.agentrc.local.json` reads.
+ * - `roleScopedAgents` overrides the resolved flag directly, bypassing the
+ *   config reads entirely.
  *
- * @param {{ projectRoot?: string, cwd?: () => string, readDir?: (dir: string) => string[] }} [opts]
+ * @param {{
+ *   projectRoot?: string,
+ *   cwd?: () => string,
+ *   readDir?: (dir: string) => string[],
+ *   fsImpl?: typeof fs,
+ *   roleScopedAgents?: boolean,
+ * }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
  */
-function runAgentsInSync({ projectRoot, cwd, readDir } = {}) {
+function runAgentsInSync({
+  projectRoot,
+  cwd,
+  readDir,
+  fsImpl = fs,
+  roleScopedAgents,
+} = {}) {
   const getCwd = cwd ?? (() => process.cwd());
   const root = projectRoot ?? getCwd();
   const listDir =
     readDir ??
     ((dir) => {
       try {
-        return fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+        return fsImpl.readdirSync(dir).filter((f) => f.endsWith('.md'));
       } catch {
         return [];
       }
@@ -365,14 +446,26 @@ function runAgentsInSync({ projectRoot, cwd, readDir } = {}) {
     .filter((f) => !f.startsWith('.'))
     .sort();
 
-  // Never-materialized agent tree: inert, so advisory (ok:true), not fatal.
   if (dests.length === 0) {
+    if (sources.length === 0) {
+      return { ok: true, detail: '0 agents up to date' };
+    }
+    const resolvedFlag =
+      typeof roleScopedAgents === 'boolean'
+        ? roleScopedAgents
+        : resolveRoleScopedAgentsFlag(root, fsImpl);
+    if (!resolvedFlag) {
+      // Kill-switch off: an unmaterialized tree is expected, not a defect.
+      return {
+        ok: true,
+        detail: `${sources.length} agent def(s) not materialized (roleScopedAgents is disabled)`,
+      };
+    }
     return {
-      ok: true,
-      detail:
-        sources.length === 0
-          ? '0 agents up to date'
-          : `${sources.length} agent def(s) not yet materialized (inert)`,
+      ok: false,
+      detail: `${sources.length} agent def(s) not yet materialized in .claude/agents/`,
+      remedy:
+        'Run `mandrel sync-agents` to regenerate the `.claude/agents/` tree.',
     };
   }
 
@@ -392,7 +485,7 @@ function runAgentsInSync({ projectRoot, cwd, readDir } = {}) {
     ok: false,
     detail: parts.join(', '),
     remedy:
-      'Run `npm run sync:agents` to regenerate the `.claude/agents/` tree.',
+      'Run `mandrel sync-agents` to regenerate the `.claude/agents/` tree.',
   };
 }
 
@@ -705,6 +798,149 @@ export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// check: pin-current
+// ---------------------------------------------------------------------------
+
+/**
+ * Fatal doctor check (Story #4525 / #4530): is the version actually
+ * resolvable in `node_modules` **consistent with** the consumer's declared
+ * `mandrel` dependency range (`package.json`)?
+ *
+ * This is a **different** signal from `agents-drift` (are the materialized
+ * `.agents/` file *contents* byte-identical to the installed payload) and
+ * from `version-current` below (is a *newer* version *published*). Neither
+ * of those catches the shape of bug #4525 reported: a `package.json` pin
+ * that has fallen out of agreement with what `node_modules` actually
+ * resolves to — e.g. an out-of-band symlink, or `npm install mandrel@latest
+ * --no-save` — which `mandrel doctor` graded as fully green before this
+ * check existed, because the only version `defaultCurrentVersion` ever read
+ * WAS the inflated `node_modules` one.
+ *
+ * **Range-aware.** The declared pin is a *range*, not an equality, so the
+ * question this check asks is satisfaction, not identity. A consumer who
+ * declares `^2.1.0` and runs a routine `npm update` gets 2.4.0 in
+ * `node_modules` with `package.json` untouched — that is npm behaving
+ * exactly as documented, and under this project's `always-bump-minor`
+ * release cadence it is the *normal* steady state, not a defect. Grading it
+ * fatal (as this check originally did, comparing only the pin's base
+ * version) made `mandrel doctor` cry wolf on healthy installs.
+ *
+ * The graded contract:
+ * - installed **satisfies** the declared range and equals its base version
+ *   → pass, quietly.
+ * - installed **satisfies** the declared range but is newer than its base
+ *   (`^2.1.0` + 2.4.0) → pass with an **advisory** `detail`. Re-pinning via
+ *   `mandrel update` is tidier, but nothing is broken. This mirrors how
+ *   `version-current` stays non-fatal: `ok: true` with the advisory carried
+ *   in `detail` (the registry's `advisory: true` flag documents an entry
+ *   whose `run()` *never* fails, which is not true of this check).
+ * - installed does **not** satisfy the declared range (`^2.1.0` + 3.0.0, or
+ *   an exact `2.1.0` pin + 2.4.0) → **fail**. The declared dependency does
+ *   not describe the code that is running.
+ * - installed is **behind** the pin's base version (`^2.4.0` + 2.1.0) →
+ *   **fail**, and note that `<` the base never satisfies any of the ranges
+ *   `resolveConsumerPinSpec` yields, so this is a sub-case of the above
+ *   given a distinct, more actionable message.
+ *
+ * Skips cleanly (not a failure) when there is no resolvable pin at all — no
+ * `package.json`, no `mandrel` entry in `dependencies`/`devDependencies`, or
+ * a non-semver specifier (`workspace:`, `git+`, `latest`, a comparator
+ * range) — via {@link resolveConsumerPinSpec}'s own `null` contract. This
+ * is also how mandrel's own repo (no self-dependency) and workspace/npx
+ * consumers degrade to a clean pass rather than a false failure.
+ *
+ * Injectable seams (used by tests so no real filesystem or package is
+ * needed):
+ * - `cwd()` — replaces `process.cwd`, anchoring both the pin read and the
+ *   `node_modules` resolution at the same consumer root (mirrors
+ *   `agents-drift` / `agents-in-sync`).
+ * - `fsImpl` — replaces the `node:fs` surface.
+ * - `resolvePackageRoot(fromDir)` — replaces `mandrel` resolution; throws
+ *   when the package is not installed.
+ *
+ * @param {{
+ *   cwd?: () => string,
+ *   fsImpl?: typeof fs,
+ *   resolvePackageRoot?: (fromDir: string) => string,
+ * }} [opts]
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
+ */
+export function runPinCurrent({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
+  const getCwd = cwd ?? (() => process.cwd());
+  const resolveRoot = resolvePackageRoot ?? defaultResolvePackageRoot;
+  const projectRoot = getCwd();
+
+  const spec = resolveConsumerPinSpec(projectRoot, fsImpl);
+  if (!spec) {
+    return {
+      ok: true,
+      detail: 'no resolvable mandrel dependency pin — skipped',
+    };
+  }
+
+  let installedRoot;
+  try {
+    installedRoot = resolveRoot(projectRoot);
+  } catch {
+    // No baseline to compare the pin against; agents-materialized /
+    // runtime-deps own the "not installed" remedy.
+    return {
+      ok: true,
+      detail: 'mandrel not installed — pin check skipped',
+    };
+  }
+
+  let installed;
+  try {
+    const parsed = JSON.parse(
+      fsImpl.readFileSync(path.join(installedRoot, 'package.json'), 'utf8'),
+    );
+    installed = String(parsed.version);
+  } catch {
+    return {
+      ok: true,
+      detail: 'installed version unreadable — pin check skipped',
+    };
+  }
+
+  const declared = `${spec.operator}${spec.version}`;
+
+  if (compareSemver(installed, spec.version) < 0) {
+    return {
+      ok: false,
+      detail: `package.json pins ${declared} but an older v${installed} is installed`,
+      remedy:
+        'Run `npm install` to install a version satisfying the package.json pin.',
+    };
+  }
+
+  if (!satisfiesPinSpec(installed, spec)) {
+    return {
+      ok: false,
+      detail: `package.json pins ${declared} but v${installed} is installed — outside the declared range`,
+      remedy:
+        'Run `mandrel update` to reconcile the package.json pin with the installed version.',
+    };
+  }
+
+  if (compareSemver(installed, spec.version) > 0) {
+    // In range, just newer than the declared base — the ordinary result of an
+    // `npm update` under a caret/tilde pin. Healthy, so `ok: true`; the
+    // advisory rides in `detail` (the doctor runner only prints `remedy` for
+    // failures).
+    return {
+      ok: true,
+      detail: `v${installed} satisfies the ${declared} pin but is newer than it — run \`mandrel update\` to re-pin (advisory)`,
+    };
+  }
+
+  return {
+    ok: true,
+    detail: `pin ${declared} matches the installed version`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // check: version-current
 // ---------------------------------------------------------------------------
@@ -870,6 +1106,13 @@ export const registry = [
     name: 'agents-drift',
     run: (opts) => runAgentsDrift(opts),
   },
+  {
+    name: 'pin-current',
+    // Fatal, unlike version-current below (Story #4525/#4530): a pin/install
+    // disagreement means the declared dependency does not describe the code
+    // that is running.
+    run: (opts) => runPinCurrent(opts),
+  },
   {
     name: 'version-current',
     // Non-fatal: surfaces a cache-only stale-version advisory. `run()` always