mandrel 2.1.0 → 2.2.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,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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/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.2.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",