mandrel 2.1.0 → 2.3.0

package/.agents/workflows/helpers/code-quality-guardrails.md

@@ -15,8 +15,10 @@ read the same numbers from here so a "high cyclomatic complexity" finding in
 
 Run [`npm run quality:preview`](../../../package.json) before committing
 on any Story that touches production source. The preview runs
-`quality-preview.js` with `--changed-since HEAD`, which exercises the
-same maintainability and CRAP engines (`escomplex` + `c8` coverage) that
+`quality-preview.js`, which scopes the diff to `HEAD` by default (the
+alias passes no `--changed-since`; the script defaults to `HEAD`) and
+exercises the same maintainability and CRAP engines (`escomplex` +
+`c8` coverage) that
 `check-baselines.js` enforces at merge time, then merges the results
 into a single per-file delta table. A clean preview means the commit
 will not bounce off the unified baselines gate. The `.husky/pre-commit`
@@ -66,8 +68,9 @@ must-refactor ceiling — any drop past it is treated as a regression that
 must be undone or offset, not absorbed. Set `tolerance` higher only when the
 project deliberately wants a looser MI-drop budget.
 
-`quality:preview --changed-since HEAD` shows the per-file MI delta in the
-working tree before the commit lands.
+`quality:preview` shows the per-file MI delta in the working tree before
+the commit lands (scoped to `HEAD` by default — the alias passes no
+`--changed-since`; the script defaults to `HEAD`).
 
 ## Rename = baseline-refresh
 

package/.agents/workflows/helpers/code-review.md

@@ -30,7 +30,7 @@ the change set is reviewed by a process the maker cannot influence. The
 enforcing code path is
 [`runStoryScopeReview`](../../scripts/lib/orchestration/single-story-close/phases/code-review.js)
 → shared
-[`runStoryReviewCore`](../../scripts/lib/orchestration/story-close/phases/code-review.js).
+[`runStoryReviewCore`](../../scripts/lib/orchestration/story-close/phases/review-core.js).
 A future refactor MUST preserve this isolation: do not move Story-scope
 review into the maker's context or run it as a step of the delivering
 child.
@@ -122,7 +122,7 @@ The pipeline will:
 ### Step 1a — Story-scope local-lens pass (`scope: story` only, Epic #4405)
 
 When `scope === 'story'`, the shared review spine
-[`runStoryReviewCore`](../../scripts/lib/orchestration/story-close/phases/code-review.js)
+[`runStoryReviewCore`](../../scripts/lib/orchestration/story-close/phases/review-core.js)
 runs a **shift-left local-lens pass** in the same close subprocess, *before*
 returning the review envelope. It:
 

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

@@ -205,12 +205,28 @@ Story-path specifics:
 Per-Story ceremony is selected by `delivery.routing.ceremonyProfile`
 (`minimal` | `standard` | `strict`, default `standard`) and the Story's
 **derived change level** — not a planner-authored verdict (Story #4542 retired
-that). Derive the level with
-[`deriveChangeLevel`](../../scripts/lib/orchestration/review-depth.js) over the
-Story's changed files (`git diff --name-only main...story-<id>`): a diff
-touching a sensitive path registered in `.agents/schemas/audit-rules.json`
-derives `high`, one touching none derives `low`, and an unenumerable diff
-derives `null`.
+that).
+
+**Compute the change set once** (Story #4593) with the shared enumerator
+[`computeChangeSet`](../../scripts/lib/orchestration/change-set.js) — the same
+module close uses — and reuse that one list for everything downstream:
+
+```bash
+node --input-type=module -e '
+  import { computeChangeSet } from "<main-repo>/.agents/scripts/lib/orchestration/change-set.js";
+  const { files } = computeChangeSet({ baseRef: "main", headRef: "story-<storyId>" });
+  console.log(JSON.stringify(files));
+'
+```
+
+Then derive the level with
+[`deriveChangeLevel`](../../scripts/lib/orchestration/review-depth.js) over that
+list: a diff touching a sensitive path registered in
+`.agents/schemas/audit-rules.json` derives `high`, one touching none derives
+`low`, and an unenumerable diff (`files === null`) derives `null`. Hand the
+**same** list to every acceptance critic you spawn (Step 1a) — a critic that
+re-ran its own `git diff` could score against a different set than the one that
+routed it.
 
 Resolve fresh-vs-inline acceptance critics per AC-cluster with
 [`resolveCeremonyForRisk`](../../scripts/lib/orchestration/ceremony-routing.js)

package/.agents/workflows/plan.md

@@ -141,6 +141,61 @@ total by default — an authored map is the only thing that can say
 `#4525-#4528 → #4530` while `#4529 → #4531`, which a blanket "superseded by
 this plan-run" reference could not.
 
+### 2.5 Critics
+
+Evaluate the critic-dispatch conditions against the authored draft — here,
+**before** persist, because this is the last point where a finding can still
+be folded into a re-author round rather than into live issues:
+
+```bash
+node .agents/scripts/plan-critics.js \
+  --stories temp/plan-<slug>/stories.json \
+  [--tech-spec temp/plan-<slug>/techspec.md]
+```
+
+It prints a verdict on stdout and exits 0 on **any** verdict — the verdict
+routes work, it does not gate the run. It exits **1** only on a usage/IO
+error (an unreadable or malformed `--stories` / `--tech-spec` path). That is
+not an advisory "proceed": no critic ran and no skip was ledgered, so **do
+not proceed to Persist** — fix the path and re-run:
+
+```jsonc
+{
+  "consolidation": { "critic": "consolidation", "dispatch": false, "reasons": ["…"] },
+  "premortem": { "critic": "pre-mortem", "dispatch": true, "reasons": ["…"] },
+  "textHygiene": { "critic": "text-hygiene", "findings": [] }
+}
+```
+
+The verdict's third entry, `textHygiene`, is advisory-only (Story #4599): it
+carries deterministic body lints (`dangling-citation` / `open-question` /
+`slicing-mass`) with no dispatch semantics — it spawns nothing and never
+gates the run. Fold `textHygiene.findings[]` into the re-author round the
+same way critic findings fold in: fix each named defect in `stories.json`
+(anchor or inline the citation, resolve the question into a declarative
+assumption, thin the Slicing checkpoint) and re-run this step. Empty
+`findings` add nothing to the round.
+
+- **Both `dispatch: false`** — proceed straight to Persist. The conditions
+  provably have nothing for a critic to find, and each skip is recorded on the
+  plan-metrics ledger so under-firing stays auditable.
+- **Either `dispatch: true`** — dispatch **one fresh-context sub-agent per
+  firing critic** (a generic sub-agent), then fold its findings into the
+  Gate #2 view or a re-author round before persist. Each critic is
+  **maker-blind**: hand it the draft artifacts (`stories.json`, and
+  `techspec.md` when present) plus its charter below — never the authoring
+  transcript or the reasons the planner believed its own draft is sound. A
+  critic that reads the maker's case grades the case, not the draft.
+  - `consolidation` — the draft's shape: Stories that should be one cohesive
+    slice, a slice split per-module rather than per-capability, and
+    `depends_on` edges that disagree with the Delivery Slicing table.
+  - `pre-mortem` — assume the plan shipped and failed: name the most likely
+    failure modes and what the draft would have to say to prevent them.
+
+Fold what survives back into `stories.json` and re-run this step. Findings are
+advisory input to the operator's Gate #2 decision, not an automatic re-author
+mandate.
+
 ### 3. Persist
 
 **Gate #2** — when the operator passed `--force-review`, STOP for approval of

package/docs/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.3.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.2.0...mandrel-v2.3.0) (2026-07-17)
+
+
+### Fixed
+
+* **test:** resolve Windows drive-letter path bug in quality-preview test ([#4614](https://github.com/dsj1984/mandrel/issues/4614)) ([a7da94d](https://github.com/dsj1984/mandrel/commit/a7da94d1c4a83b9b721e632e468bb34df07465dd))
+* **update:** make post-install bin re-exec pnpm/layout-agnostic ([#4613](https://github.com/dsj1984/mandrel/issues/4613)) ([#4616](https://github.com/dsj1984/mandrel/issues/4616)) ([82dc5a2](https://github.com/dsj1984/mandrel/commit/82dc5a2e9ce662f9b9c0c7880ea684fd370a507f))
+
+## [2.2.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.1.0...mandrel-v2.2.0) (2026-07-17)
+
+
+### Added
+
+* **deliver:** probe live state per beat, retiring hand-maintained --done/--in-flight (refs [#4594](https://github.com/dsj1984/mandrel/issues/4594)) ([#4597](https://github.com/dsj1984/mandrel/issues/4597)) ([96b2ef6](https://github.com/dsj1984/mandrel/commit/96b2ef6ce5f0526de2e5033e8cdb0ca02f6d5d89))
+* **plan:** add deterministic text-hygiene lints to the critic gate and codify authoring conventions (refs [#4599](https://github.com/dsj1984/mandrel/issues/4599)) ([#4607](https://github.com/dsj1984/mandrel/issues/4607)) ([8794459](https://github.com/dsj1984/mandrel/commit/87944593f8ba5c304cdbaef40a4d3e4430e5d71d))
+* **plan:** retire the [@epic](https://github.com/epic)-<id>-ac-N Gherkin AC tag namespace (refs [#4604](https://github.com/dsj1984/mandrel/issues/4604)) ([#4608](https://github.com/dsj1984/mandrel/issues/4608)) ([7388c58](https://github.com/dsj1984/mandrel/commit/7388c581d43e10a26c538e19a15897d2b5adafa7))
+* rewire the /plan critics into a live pre-persist gate ([#4592](https://github.com/dsj1984/mandrel/issues/4592)) ([#4598](https://github.com/dsj1984/mandrel/issues/4598)) ([349367d](https://github.com/dsj1984/mandrel/commit/349367d46bfbe59be5ce56952bca46cac8e5828c))
+* **story-body:** render numbered ACs, humanized path bullets, and visible wide rationale (refs [#4600](https://github.com/dsj1984/mandrel/issues/4600)) ([#4606](https://github.com/dsj1984/mandrel/issues/4606)) ([843779e](https://github.com/dsj1984/mandrel/commit/843779e2730832a1d7a6e081a0a18b40dd621981))
+
+
+### Fixed
+
+* fix probe mode's incomplete live classification: double-dispatch window and blocked-Story wedge ([#4601](https://github.com/dsj1984/mandrel/issues/4601)) ([#4605](https://github.com/dsj1984/mandrel/issues/4605)) ([0875b6a](https://github.com/dsj1984/mandrel/commit/0875b6af857fcfadc423e4e3731d792dc2a5fe60))
+* **story-close:** close [#4593](https://github.com/dsj1984/mandrel/issues/4593)'s single-enumeration leak and root-cause the un-fired MI gate ([#4610](https://github.com/dsj1984/mandrel/issues/4610)) ([1edf5a6](https://github.com/dsj1984/mandrel/commit/1edf5a67ceaf868f8faae92aec1c6280f191d33f))
+
+
+### Changed
+
+* **orchestration:** compute the Story change-set once and thread it through delivery (refs [#4593](https://github.com/dsj1984/mandrel/issues/4593)) ([#4595](https://github.com/dsj1984/mandrel/issues/4595)) ([d116015](https://github.com/dsj1984/mandrel/commit/d1160150836e8bf7107fac24189cde258ea93458))
+
 ## [2.1.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.0.0...mandrel-v2.1.0) (2026-07-17)
 
 

package/lib/cli/update.js

@@ -36,7 +36,9 @@
  * ## Re-exec of post-install phases (Story #4034)
  *
  * Steps 4–6 execute as **child processes spawned from the newly-installed
- * binary** (`<cwd>/node_modules/.bin/mandrel`) rather than in the running
+ * bin script** (`node <cwd>/node_modules/mandrel/bin/mandrel.js`; Story #4613
+ * resolves the script layout-agnostically rather than via the `.bin` shim)
+ * rather than in the running
  * process. Node cannot hot-swap a `require`d module mid-process, so without
  * re-exec, the still-running old binary's `runSync`/`runMigrations`/`runDoctor`
  * code would materialise the old payload even though the package on disk has
@@ -120,11 +122,12 @@
  * resolved semver string — see `lib/install-cmd-parser.js` for the shared
  * tokenize-and-spawn rationale this module reuses (no duplicated workaround).
  *
- * The `spawnPhase` default (Story #4034) similarly uses `shell: true` only on
- * Windows: the new binary resolves from `node_modules/.bin/mandrel` (a fixed,
- * non-operator-supplied path) and the per-phase argv vector is a constant
- * fixed list (e.g. `['sync']`, `['migrate', '--from', v, '--to', v]`,
- * `['doctor']`) with no injection risk regardless of the shell flag.
+ * The `spawnPhase` default (Story #4034) does **not** use the win32 shell flag:
+ * it spawns `process.execPath` (node) against the resolved `bin/mandrel.js`
+ * script (Story #4613), so it never touches a `.cmd` shim and needs no
+ * shell on any platform. The per-phase argv vector is a constant fixed list
+ * (e.g. `['sync']`, `['migrate', '--from', v, '--to', v]`, `['doctor']`) with
+ * no operator-supplied data.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -674,29 +677,55 @@ function parseChangelogSections(raw) {
 }
 
 /**
- * Resolve the path to the `mandrel` binary inside `node_modules/.bin/` for the
- * given project root. On Windows the binary is a `.cmd` shim; on POSIX it is a
- * plain executable. The resolved path is used as the target for the post-install
- * phase re-exec (Story #4034).
+ * Resolve the newly-installed `mandrel` bin **script**
+ * (`<packageRoot>/bin/mandrel.js`) from the consumer project root. This is the
+ * target for the post-install phase re-exec (Story #4034), spawned via
+ * `process.execPath` (node) rather than executed directly — see
+ * {@link defaultSpawnPhase}.
+ *
+ * It deliberately does **not** return the `node_modules/.bin/mandrel` shim.
+ * That shim only works because npm chmods the bin target `+x` at install time:
+ * `bin/mandrel.js` ships non-executable in the published tarball, and pnpm
+ * symlinks `.bin/mandrel` straight at it, so spawning the shim directly fails
+ * with `EACCES` under pnpm (Story #4613). Spawning node against the resolved
+ * `.js` script removes the dependency on the exec bit, the shebang, and the
+ * Windows `.cmd` shim entirely.
+ *
+ * Resolution reuses the same consumer-anchored resolver
+ * (`defaultResolvePackageRoot`) that {@link resolveCurrentVersionForUpdate}
+ * uses, so it points at the consumer's install rather than a copy hoisted next
+ * to this CLI module. The `mandrel` package directory is version-invariant
+ * (`node_modules/mandrel/`), so resolving it before the in-place `npm-update`
+ * step still yields the directory whose `bin/mandrel.js` the install overwrites.
  *
  * @param {string} projectRoot - Absolute path to the consumer project.
- * @returns {string} Absolute path to the new binary.
+ * @param {{ resolvePackageRoot?: (fromDir: string) => string }} [opts] - test
+ *   seam for the `node_modules` resolution; defaults to the real
+ *   `defaultResolvePackageRoot` from `sync.js`.
+ * @returns {string} Absolute path to the new bin script.
  */
-export function resolveNewBinPath(projectRoot) {
-  const binName = process.platform === 'win32' ? 'mandrel.cmd' : 'mandrel';
-  return path.join(projectRoot, 'node_modules', '.bin', binName);
+export function resolveNewBinScriptPath(
+  projectRoot,
+  { resolvePackageRoot = defaultResolvePackageRoot } = {},
+) {
+  const packageRoot = resolvePackageRoot(projectRoot);
+  return path.join(packageRoot, 'bin', 'mandrel.js');
 }
 
 /**
  * Default `spawnPhase` seam (Story #4034): spawn a post-install phase from the
- * newly-installed `mandrel` binary and stream its stdout/stderr through the
+ * newly-installed `mandrel` bin script and stream its stdout/stderr through the
  * parent's write sinks. Each phase runs as an isolated child process so the
  * newly-installed module code (not the currently-loaded old module) executes.
  *
- * The spawn uses `shell: true` only on Windows where the binary is a `.cmd`
- * shim (CVE-2024-27980 parity). The argv vector is a fixed constant list
- * per phase — no operator-supplied data enters the vector, so the shell flag
- * carries no injection risk (security-baseline § Output & Rendering).
+ * The child is spawned as `process.execPath <binScript> <phase> …` — node run
+ * against the resolved `bin/mandrel.js` (see {@link resolveNewBinScriptPath}).
+ * Spawning node against a plain `.js` file removes any dependency on the bin's
+ * exec bit, its shebang, or a Windows `.cmd` shim, so **no** `shell` flag is
+ * needed on any platform (this is the pnpm/layout-agnostic fix, Story #4613,
+ * that retired the former win32-only `shell: true` branch). The argv vector is
+ * a fixed constant list per phase — no operator-supplied data enters it
+ * (security-baseline § Output & Rendering).
  *
  * Throws when the child exits non-zero so the orchestrator can surface the
  * failure to the operator.
@@ -709,7 +738,8 @@ export function resolveNewBinPath(projectRoot) {
  *   write: (s: string) => void,
  *   writeErr: (s: string) => void,
  *   spawnFn?: typeof spawnSync,
- * }} opts
+ * }} opts - `binPath` is the resolved bin **script** path (not the
+ *   `node_modules/.bin` shim); it becomes node's first argv entry.
  * @returns {{ ok: boolean, stdout: string, stderr: string }}
  */
 export function defaultSpawnPhase(
@@ -718,10 +748,9 @@ export function defaultSpawnPhase(
   { binPath, cwd, write, writeErr, spawnFn = spawnSync },
 ) {
   const argv = [phase, ...args];
-  const r = spawnFn(binPath, argv, {
+  const r = spawnFn(process.execPath, [binPath, ...argv], {
     cwd,
     encoding: 'utf8',
-    shell: process.platform === 'win32',
   });
   const stdout = typeof r.stdout === 'string' ? r.stdout : '';
   const stderr = typeof r.stderr === 'string' ? r.stderr : '';
@@ -980,7 +1009,7 @@ async function resolveDrift(checkDrift) {
  *   npmUpdate: ((version: string, opts: { installCmd?: string }) => unknown | Promise<unknown>) | undefined,
  *   spawnPhase: ((phase: string, args: string[], opts: object) => { ok: boolean } | Promise<{ ok: boolean }>) | undefined,
  *   surfaceChangelog: ((version: string) => unknown | Promise<unknown>) | undefined,
- *   binPath: string,
+ *   resolveBinScript: (projectRoot: string) => string,
  *   projectRoot: string,
  *   write: (s: string) => void,
  *   writeErr: (s: string) => void,
@@ -995,7 +1024,7 @@ async function executePlan({
   npmUpdate,
   spawnPhase,
   surfaceChangelog,
-  binPath,
+  resolveBinScript,
   projectRoot,
   write,
   writeErr,
@@ -1004,6 +1033,17 @@ async function executePlan({
   const stepsRun = [];
   let doctorOk = true;
 
+  // Resolve the new bin script lazily and once, on the first spawn phase.
+  // Deferring it past the `npm-update` step means (a) a missing `npmUpdate`
+  // seam surfaces its own clear error first, and (b) resolution reflects the
+  // just-installed package. The `mandrel` package directory is version-stable,
+  // so resolving after the in-place bump yields the same directory either way.
+  let binPath;
+  const binScript = () => {
+    if (binPath === undefined) binPath = resolveBinScript(projectRoot);
+    return binPath;
+  };
+
   for (const step of steps) {
     if (step.kind === 'npm-update') {
       // Bump the dependency. The lockfile change is left STAGED on disk; this
@@ -1024,7 +1064,7 @@ async function executePlan({
     // package's module code — not the old loaded module — executes.
     // eslint-disable-next-line no-await-in-loop
     const result = await spawnPhase(step.phase, step.args, {
-      binPath,
+      binPath: binScript(),
       cwd: projectRoot,
       write,
       writeErr,
@@ -1080,6 +1120,7 @@ async function executePlan({
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
  *   cwd?: () => string,
+ *   resolveBinScript?: (projectRoot: string) => string,
  * }} [opts]
  * @returns {Promise<{
  *   ok: boolean,
@@ -1102,6 +1143,7 @@ export async function runUpdate({
   writeErr = (s) => process.stderr.write(s),
   exit = (code) => process.exit(code),
   cwd = () => process.cwd(),
+  resolveBinScript = resolveNewBinScriptPath,
 } = {}) {
   const dryRun = argv.includes('--dry-run');
   const installCmd = parseInstallCmdFlag(argv);
@@ -1176,7 +1218,6 @@ export async function runUpdate({
 
   // --- resynced / updated: execute the phase plan ---------------------------
   const projectRoot = cwd();
-  const binPath = resolveNewBinPath(projectRoot);
 
   if (plan.action === 'resynced') {
     write(
@@ -1193,7 +1234,7 @@ export async function runUpdate({
     npmUpdate,
     spawnPhase,
     surfaceChangelog,
-    binPath,
+    resolveBinScript,
     projectRoot,
     write,
     writeErr,
@@ -1251,8 +1292,9 @@ export async function runUpdate({
  *     through the shared `runInstallCommand` helper — no git mutation;
  *     lockfile left staged.
  *   - `spawnPhase` is wired to `defaultSpawnPhase`, which spawns each
- *     post-install phase (sync, sync-commands, migrate, doctor) from the
- *     newly-installed binary (`node_modules/.bin/mandrel`). This is the
+ *     post-install phase (sync, sync-commands, migrate, doctor) as
+ *     `node <packageRoot>/bin/mandrel.js …` (Story #4613 — the resolved bin
+ *     script, not the `node_modules/.bin` shim). This is the
  *     Story #4034 fix: the new bin loads the new package's module code and
  *     resolves paths against the new install dir, so these phases can never
  *     observe the old payload.
@@ -1289,6 +1331,7 @@ export async function runUpdate({
  *   fetchChangelog?: (version: string) => Promise<string>,
  *   runUpdate?: typeof runUpdate,
  *   cwd?: () => string,
+ *   resolveBinScript?: (projectRoot: string) => string,
  *   checkDrift?: () => (boolean | Promise<boolean>),
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
@@ -1313,6 +1356,7 @@ export default async function run(argv = [], deps = {}) {
     exit = (code) => process.exit(code),
     log,
     cwd,
+    resolveBinScript,
     checkDrift,
   } = deps;
 
@@ -1323,11 +1367,13 @@ export default async function run(argv = [], deps = {}) {
   const current =
     deps.currentVersion ?? resolveCurrentVersionForUpdate(cwdFn(), fs);
 
-  // The production spawnPhase: spawn each post-install phase from
-  // node_modules/.bin/mandrel (the newly-installed binary). This is the sole
-  // post-install execution path (No-Shim — Story #4182 retired the in-process
-  // runSync/runMigrations/runDoctor seam set). spawnFn is injectable so tests
-  // can stub the spawn boundary without running a real child process.
+  // The production spawnPhase: spawn each post-install phase as
+  // `node <packageRoot>/bin/mandrel.js …` (the newly-installed bin script,
+  // resolved layout-agnostically per Story #4613 — not the node_modules/.bin
+  // shim). This is the sole post-install execution path (No-Shim — Story #4182
+  // retired the in-process runSync/runMigrations/runDoctor seam set). spawnFn
+  // is injectable so tests can stub the spawn boundary without running a real
+  // child process.
   const productionSpawnPhase = (phase, args, opts) =>
     defaultSpawnPhase(phase, args, {
       ...opts,
@@ -1370,5 +1416,8 @@ export default async function run(argv = [], deps = {}) {
     writeErr,
     exit,
     cwd: cwdFn,
+    // Pass through undefined in production so runUpdate applies its default
+    // resolver (resolveNewBinScriptPath); tests inject a stub for a fake root.
+    resolveBinScript,
   });
 }

package/lib/migrations/index.js

@@ -54,6 +54,7 @@
 
 import { retireMiDropKnobs } from './steps/2.1.0-retire-mi-drop-knobs.js';
 import { retireVerifyConcurrencyCap } from './steps/2.1.0-retire-verify-concurrency-cap.js';
+import { retireEpicAcTags } from './steps/2.2.0-retire-epic-ac-tags.js';
 
 /**
  * Ordered registry of migration steps. MUST stay sorted ascending by
@@ -66,7 +67,11 @@ import { retireVerifyConcurrencyCap } from './steps/2.1.0-retire-verify-concurre
  *   apply: (ctx: unknown) => void,
  * }>}
  */
-export const migrations = [retireMiDropKnobs, retireVerifyConcurrencyCap];
+export const migrations = [
+  retireMiDropKnobs,
+  retireVerifyConcurrencyCap,
+  retireEpicAcTags,
+];
 
 /**
  * Parse a dotted semver-ish string into a numeric tuple for comparison.

package/lib/migrations/steps/2.2.0-retire-epic-ac-tags.js

@@ -0,0 +1,154 @@
+// lib/migrations/steps/2.2.0-retire-epic-ac-tags.js
+/**
+ * Story #4604 — strip the retired `@epic-<id>-ac-N` Gherkin AC tag namespace
+ * from consumer feature files.
+ *
+ * The v2 Epic removal deleted `acceptance-spec-reconciler.js`, the only
+ * consumer of the namespaced per-Epic AC tags, and the `/plan` authoring
+ * prompt no longer mandates them. Surviving tags in consumer `.feature`
+ * files are inert and violate the gherkin-standards tag taxonomy's
+ * no-ad-hoc-tags rule, so this step removes them: each `@epic-<digits>-ac-<digits>`
+ * token is deleted from tag lines, a tag line left with no tags is dropped
+ * entirely, and every other tag and line is preserved byte-for-byte. Files
+ * with no stale tags are never rewritten.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Mirror of `CANONICAL_FEATURE_ROOTS` in
+ * `.agents/scripts/lib/bdd-runner-detect.js`. Duplicated deliberately:
+ * `lib/` runs from the installed npm package inside a consumer project and
+ * must not import from the materialized `.agents/` payload.
+ */
+const CANONICAL_FEATURE_ROOTS = Object.freeze([
+  'tests/features',
+  'features',
+  'test/features',
+]);
+
+const EPIC_AC_TAG_RE = /@epic-\d+-ac-\d+/;
+
+/**
+ * A Gherkin tag line: optional indentation followed by one or more
+ * whitespace-separated `@tag` tokens and nothing else.
+ */
+const TAG_LINE_RE = /^(\s*)(@\S+(?:\s+@\S+)*)\s*$/;
+
+/**
+ * Recursively collect `.feature` file paths under `root`.
+ *
+ * @param {string} root
+ * @param {typeof nodeFs} fsImpl
+ * @returns {string[]}
+ */
+function collectFeatureFiles(root, fsImpl) {
+  /** @type {string[]} */
+  const found = [];
+  /** @type {string[]} */
+  const queue = [root];
+  while (queue.length > 0) {
+    const dir = queue.pop();
+    /** @type {import('node:fs').Dirent[]} */
+    let entries;
+    try {
+      entries = fsImpl.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(full);
+      } else if (entry.isFile() && entry.name.endsWith('.feature')) {
+        found.push(full);
+      }
+    }
+  }
+  return found.sort();
+}
+
+/**
+ * @param {unknown} ctx
+ * @param {typeof nodeFs} fsImpl
+ * @returns {string[]} Absolute paths of every `.feature` file under the
+ *   canonical feature roots that exist in the consumer tree.
+ */
+function resolveFeatureFiles(ctx, fsImpl) {
+  const projectRoot = ctx?.projectRoot ?? process.cwd();
+  return CANONICAL_FEATURE_ROOTS.flatMap((root) =>
+    collectFeatureFiles(path.join(projectRoot, root), fsImpl),
+  );
+}
+
+/**
+ * Strip retired `@epic-<id>-ac-<n>` tokens from one file's content.
+ * Only tag lines are touched; a tag line whose every tag was retired is
+ * dropped. Returns the original string when nothing matched.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function stripEpicAcTags(content) {
+  if (!EPIC_AC_TAG_RE.test(content)) return content;
+  const newline = content.includes('\r\n') ? '\r\n' : '\n';
+  const lines = content.split(newline);
+  /** @type {string[]} */
+  const out = [];
+  for (const line of lines) {
+    const match = line.match(TAG_LINE_RE);
+    if (!match || !EPIC_AC_TAG_RE.test(line)) {
+      out.push(line);
+      continue;
+    }
+    const [, indent, tagBlock] = match;
+    const kept = tagBlock
+      .split(/\s+/)
+      .filter((tag) => !EPIC_AC_TAG_RE.test(tag));
+    if (kept.length === 0) continue;
+    out.push(`${indent}${kept.join(' ')}`);
+  }
+  return out.join(newline);
+}
+
+export const retireEpicAcTags = {
+  version: '2.2.0',
+  description:
+    'strip retired @epic-<id>-ac-N Gherkin AC tags from feature files ' +
+    '(their reconciler consumer was deleted in the v2 Epic removal)',
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @returns {boolean}
+   */
+  detect(ctx) {
+    const fsImpl = ctx?.fs ?? nodeFs;
+    return resolveFeatureFiles(ctx, fsImpl).some((file) => {
+      try {
+        return EPIC_AC_TAG_RE.test(fsImpl.readFileSync(file, 'utf8'));
+      } catch {
+        return false;
+      }
+    });
+  },
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @returns {void}
+   */
+  apply(ctx) {
+    const fsImpl = ctx?.fs ?? nodeFs;
+    for (const file of resolveFeatureFiles(ctx, fsImpl)) {
+      /** @type {string} */
+      let content;
+      try {
+        content = fsImpl.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const stripped = stripEpicAcTags(content);
+      if (stripped !== content) {
+        fsImpl.writeFileSync(file, stripped);
+      }
+    }
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -45,7 +45,7 @@
     "crap:update": "node .agents/scripts/update-crap-baseline.js",
     "duplication:check": "node .agents/scripts/check-baselines.js --gate duplication",
     "duplication:update": "node .agents/scripts/update-duplication-baseline.js",
-    "quality:preview": "node .agents/scripts/quality-preview.js --changed-since HEAD && node .agents/scripts/check-dead-exports.js",
+    "quality:preview": "node .agents/scripts/check-dead-exports.js && node .agents/scripts/quality-preview.js",
     "quality:watch": "node .agents/scripts/quality-watch.js",
     "sync:commands": "node bin/mandrel.js sync-commands",
     "sync:agents": "node .agents/scripts/sync-claude-agents.js",