mandrel 2.16.0 → 2.17.0

package/.agents/scripts/resolve-doc-tiers.js

@@ -50,24 +50,34 @@ export function parseArgv(argv = []) {
  * Top-level CLI entry. Exported so tests can drive it against a fixture root
  * with an injected sink and config.
  *
+ * The optional final `deps` parameter is the module's injectable seam
+ * (`.agents/rules/test-seams.md` rules 1-2): every entry defaults to the real
+ * implementation, so the CLI path below — and any production caller — needs no
+ * configuration change.
+ *
  * @param {{
  *   argv?: string[],
  *   config?: object,
  *   root?: string,
  *   stdout?: { write: (s: string) => void },
  * }} [opts]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   resolveDocTiersImpl?: typeof resolveDocTiers,
+ * }} [deps]
  * @returns {Promise<number>} always 0
  */
-export async function runCli({
-  argv = process.argv.slice(2),
-  config,
-  root,
-  stdout = process.stdout,
-} = {}) {
+export async function runCli(
+  { argv = process.argv.slice(2), config, root, stdout = process.stdout } = {},
+  {
+    resolveConfigImpl = resolveConfig,
+    resolveDocTiersImpl = resolveDocTiers,
+  } = {},
+) {
   const { rootPath } = parseArgv(argv);
-  const resolvedConfig = config ?? resolveConfig();
+  const resolvedConfig = config ?? resolveConfigImpl();
   const resolvedRoot = root ?? rootPath ?? PROJECT_ROOT;
-  const result = resolveDocTiers(resolvedConfig, { root: resolvedRoot });
+  const result = resolveDocTiersImpl(resolvedConfig, { root: resolvedRoot });
   stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   return 0;
 }

package/.agents/scripts/single-story-close.js

@@ -90,6 +90,10 @@ import { runAsCli } from './lib/cli-utils.js';
 import { formatCliError } from './lib/error-redactor.js';
 import { Logger } from './lib/Logger.js';
 import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
+import {
+  failedTerminalFor,
+  gatesForFailedPhase,
+} from './lib/orchestration/single-story-close/failed-terminal.js';
 import { enableAutoMergeWith } from './lib/orchestration/single-story-close/phases/auto-merge.js';
 import {
   buildSyncFailureCommentBody,
@@ -102,10 +106,8 @@ import {
 } from './lib/orchestration/single-story-close/phases/code-review.js';
 import { ensurePullRequestWith } from './lib/orchestration/single-story-close/phases/pull-request.js';
 import {
-  buildTerminalEnvelope,
   emitTerminalEnvelope,
   exitCodeForTerminal,
-  NEXT_COMMANDS,
 } from './lib/orchestration/story-deliver-terminal.js';
 
 // Story #2990 moved the `gh`-spawn boundary into the `lib/gh-exec.js`
@@ -118,9 +120,13 @@ export const enableAutoMerge = enableAutoMergeWith;
 
 // Re-export pure helpers verbatim — they don't touch `execFileSync`
 // or any URL-mocked module, so the phase exports work unmodified.
+// `gatesForFailedPhase` now lives beside the envelope it feeds
+// (`single-story-close/failed-terminal.js`); it is re-exported here so the
+// CLI's public surface is unchanged by that move.
 export {
   buildStoryReviewCrossRefBody,
   buildSyncFailureCommentBody,
+  gatesForFailedPhase,
   handleSyncFailure,
   parsePrNumber,
   runStoryScopeReview,
@@ -134,95 +140,6 @@ export async function runSingleStoryClose(opts) {
   return mod.runSingleStoryClose(opts);
 }
 
-/**
- * The close pipeline's phase order, as `setPhase` walks it. Only used to
- * decide whether a gate had already run when a later phase died.
- */
-const PHASE_ORDER = Object.freeze([
-  'init',
-  'wrong-tree-guard',
-  'close-validation',
-  'base-sync',
-  'push',
-  'pull-request',
-  'code-review',
-  'auto-merge',
-  'confirm-merge',
-  'post-land',
-  'done',
-]);
-
-/** Each reported gate and the pipeline phase that decides it. */
-const GATE_PHASES = Object.freeze([
-  ['validation', 'close-validation'],
-  ['baseSync', 'base-sync'],
-  ['codeReview', 'code-review'],
-]);
-
-/**
- * Report every gate's outcome for a run that died at `phase`.
- *
- * The schema's contract: "A gate the run skipped … reports `skipped` rather
- * than being omitted, so a missing gate is never mistaken for a passing one."
- * The previous shape named only the gate that died and omitted the rest
- * entirely — exactly the ambiguity the contract forbids.
- *
- * Reconstructed from the phase order, which is sound because the pipeline is
- * strictly sequential: reaching phase N means every gate before it completed.
- * A gate whose phase the run never reached is `skipped`; one the operator
- * turned off via `--skip-validation` / `--skip-sync` is `skipped` too (it did
- * not pass — it never ran).
- *
- * @param {string} phase The phase the run died in.
- * @param {{ skipValidation?: boolean, skipSync?: boolean }} args Parsed CLI args.
- * @returns {Record<string, 'passed'|'failed'|'skipped'>}
- */
-export function gatesForFailedPhase(phase, args = {}) {
-  const skipped = { validation: args.skipValidation, baseSync: args.skipSync };
-  const failedAt = PHASE_ORDER.indexOf(phase);
-  const gates = {};
-  for (const [gate, gatePhase] of GATE_PHASES) {
-    const at = PHASE_ORDER.indexOf(gatePhase);
-    if (gatePhase === phase) gates[gate] = 'failed';
-    else if (failedAt < 0 || at > failedAt) gates[gate] = 'skipped';
-    else gates[gate] = skipped[gate] ? 'skipped' : 'passed';
-  }
-  return gates;
-}
-
-/**
- * Build the `failed` terminal for a phase that crashed.
- *
- * The runner deliberately throws rather than returning a failure (a red gate
- * must not look like a return value), so without this the most common
- * non-happy ending — a failing close-validation gate — would emit **no
- * envelope at all**, exiting 1 with only a stderr line while the workflow
- * docs promise the agent a `failed` envelope naming the phase. Every close
- * invocation emits exactly one envelope; this is the path that keeps that
- * true when a phase dies.
- *
- * `err.closePhase` is tagged by the runner's phase tracker.
- *
- * @param {unknown} err
- * @returns {object|null} A validated envelope, or null when even the story id
- *   is unknown (a usage error — there is nothing to report an envelope about).
- */
-function failedTerminalFor(err) {
-  const phase = err?.closePhase ?? 'init';
-  const args = parseSprintArgs();
-  const storyId = Number(args.storyId);
-  if (!Number.isInteger(storyId) || storyId <= 0) return null;
-  return buildTerminalEnvelope({
-    storyId,
-    status: 'failed',
-    phase,
-    gates: gatesForFailedPhase(phase, args),
-    failure: { reason: String(err?.message ?? err) },
-    nextCommand: NEXT_COMMANDS.recover(storyId),
-    elapsedSeconds: 0,
-  });
-}
-
 /**
  * CLI entry — resolves the process exit code from the terminal envelope's
  * status rather than from a thrown/not-thrown distinction, so `pending`
@@ -234,7 +151,7 @@ async function main() {
     const outcome = await runSingleStoryClose();
     return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });
   } catch (err) {
-    const terminal = failedTerminalFor(err);
+    const terminal = failedTerminalFor(err, parseSprintArgs());
     if (!terminal) throw err;
     // Mirror runAsCli's default error line (which this catch pre-empts) so the
     // human-facing failure text is unchanged, then emit the envelope.

package/.agents/scripts/update-crap-baseline.js

@@ -13,6 +13,7 @@ import {
 } from './lib/config-resolver.js';
 import { loadCoverage } from './lib/coverage-utils.js';
 import {
+  checkResolutionFloor,
   resolveEscomplexVersion,
   resolveTsTranspilerVersion,
   scanAndScore,
@@ -71,6 +72,7 @@ async function main() {
   const crap = getQuality(config).crap;
   const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
   const requireCoverage = crap.requireCoverage !== false;
+  const minMethodResolutionRate = crap.minMethodResolutionRate ?? 0.75;
   const coveragePath =
     args.coveragePath ?? crap.coveragePath ?? 'coverage/coverage-final.json';
   const baselinePath = args.baselinePath ?? getBaselines(config).crap.path;
@@ -117,6 +119,7 @@ async function main() {
       scannedFiles,
       skippedFilesNoCoverage,
       skippedMethodsNoCoverage,
+      resolution,
     } = await scanAndScore({
       targetDirs,
       coverage,
@@ -137,6 +140,16 @@ async function main() {
         `[CRAP] Skipped ${skippedMethodsNoCoverage} method(s) whose per-method coverage was unresolved.`,
       );
     }
+    if (resolution) {
+      Logger.info(
+        `[CRAP] Method resolution: ${resolution.resolvedMethods}/${resolution.joinableMethods} ` +
+          `(${(resolution.rate * 100).toFixed(1)}%) in files with coverage.`,
+      );
+    }
+    // Fail closed BEFORE the service persists anything — a thin baseline is
+    // never written and then apologised for.
+    const refusal = checkResolutionFloor(resolution, minMethodResolutionRate);
+    if (refusal) throw new Error(refusal);
 
     return (rows ?? []).filter(
       (r) => typeof r?.crap === 'number' && Number.isFinite(r.crap),

package/README.md

@@ -181,10 +181,14 @@ dimensions, run model, and how to benchmark a new version.
 
 ## Contributors
 
-Only `.agents/` is distributed to consumers — it ships inside the
-`mandrel` npm package and is materialized into a consumer's
-`./.agents/` directory by `mandrel sync`. Everything else in this
-repository is internal development tooling.
+The published `mandrel` package ships three directories — `.agents/`, `bin/`,
+and `lib/` (see the `files` array in [`package.json`](package.json)).
+`.agents/` is the payload `mandrel sync` materializes into a consumer's
+`./.agents/` directory; `bin/mandrel.js` and its `lib/` implementation stay
+inside `node_modules/mandrel/` and back the `npx mandrel …` CLI used
+throughout this README. Everything else in this repository — `docs/`,
+`tests/`, `.github/`, the root tooling configs — is internal development
+tooling and is not published.
 
 Common commands while developing the framework itself:
 
@@ -204,8 +208,12 @@ Deeper reference material lives in `docs/` rather than inline here:
 - [`.agents/docs/workflows.md`](.agents/docs/workflows.md) — slash-command
   index (auto-generated from the workflow set).
 - [`docs/CHANGELOG.md`](docs/CHANGELOG.md) — release history.
-- [`AGENTS.md`](AGENTS.md) — repository onboarding, the single-package release
-  topology, PAT / npm-token setup, and major-version policy. Releases are
+- [`AGENTS.md`](AGENTS.md) — the repository-level orientation pointer; it
+  links on to [`docs/onboarding.md`](docs/onboarding.md) for the layout,
+  commands, and development standards.
+- [`docs/release-operations.md`](docs/release-operations.md) — the Release
+  Checklist, the Install Matrix release gate, the single-package release
+  topology, PAT / npm-token setup, and the major-version policy. Releases are
   automated by `release-please`: land Conventional Commits on `main` and it
   opens a combined `chore: release main` PR that squash-merges itself once
   CI is green, tags `main`, and publishes `mandrel` to npm.

package/docs/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.17.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.16.0...mandrel-v2.17.0) (2026-07-26)
+
+
+### Added
+
+* **crap:** wire the baseline-refresh projection layer and add CRAP freshness + full-scope drift detection ([#4776](https://github.com/dsj1984/mandrel/issues/4776)) ([#4778](https://github.com/dsj1984/mandrel/issues/4778)) ([8c49a12](https://github.com/dsj1984/mandrel/commit/8c49a12be6ca5ecaca60d8f0bc868f47c9a02534))
+
+
+### Fixed
+
+* **audit-to-stories:** anchor findings to their real primary file (refs [#4781](https://github.com/dsj1984/mandrel/issues/4781)) ([#4782](https://github.com/dsj1984/mandrel/issues/4782)) ([a5794c0](https://github.com/dsj1984/mandrel/commit/a5794c02c3443c39ce116699c311b4cdd8001788))
+* **cli:** drain stdio before exit and settle the audit fan-out per dimension (refs [#4783](https://github.com/dsj1984/mandrel/issues/4783)) ([#4787](https://github.com/dsj1984/mandrel/issues/4787)) ([3422fd5](https://github.com/dsj1984/mandrel/commit/3422fd564773d0e79ac4d16af5bbc5414d06c65b))
+* **crap:** join per-method coverage in original-source coordinates — TS scoring resolves ~5% of methods ([#4775](https://github.com/dsj1984/mandrel/issues/4775)) ([#4777](https://github.com/dsj1984/mandrel/issues/4777)) ([1464c75](https://github.com/dsj1984/mandrel/commit/1464c75c061960aaa9ee1af88175d9706b044c26))
+* **deliver:** keep the terminal envelope alive after the worktree reap (refs [#4784](https://github.com/dsj1984/mandrel/issues/4784)) ([#4791](https://github.com/dsj1984/mandrel/issues/4791)) ([907b7bd](https://github.com/dsj1984/mandrel/commit/907b7bdb951a70a7155e5a9a50afdbea7a81d6a6))
+* **deps:** decouple the js-yaml override from markdownlint-cli2, close Node-engine drift, and re-enable knip dependency rules ([#4784](https://github.com/dsj1984/mandrel/issues/4784)) ([#4788](https://github.com/dsj1984/mandrel/issues/4788)) ([9ed687b](https://github.com/dsj1984/mandrel/commit/9ed687bead90d3e0edf76e7d0e700b0f51e8cb5d))
+* **docs:** re-sync the reference docs to the contracts the code actually implements ([#4785](https://github.com/dsj1984/mandrel/issues/4785)) ([#4790](https://github.com/dsj1984/mandrel/issues/4790)) ([00d9270](https://github.com/dsj1984/mandrel/commit/00d92708b3d3ac0978c073c5a31fd6a80a25767e))
+* **docs:** supersede the stale ADR chain in place and archive the retired pattern history ([#4786](https://github.com/dsj1984/mandrel/issues/4786)) ([#4789](https://github.com/dsj1984/mandrel/issues/4789)) ([5ba2e34](https://github.com/dsj1984/mandrel/commit/5ba2e3486973b87603fd3f2f23f750f18e75e240))
+* **git-cleanup:** report the refs the prune phase actually dropped (refs [#4772](https://github.com/dsj1984/mandrel/issues/4772)) ([#4773](https://github.com/dsj1984/mandrel/issues/4773)) ([16424d5](https://github.com/dsj1984/mandrel/commit/16424d53305549841b6294ceb1d7651baf1f98e7))
+
+
+### Changed
+
+* **quality:** floor CRAP on methodsAbove20 instead of a fitted max ceiling ([#4779](https://github.com/dsj1984/mandrel/issues/4779)) ([647130b](https://github.com/dsj1984/mandrel/commit/647130b313a85add64978205d4bb300e90e3c9a3)), closes [#4775](https://github.com/dsj1984/mandrel/issues/4775)
+
 ## [2.16.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.15.0...mandrel-v2.16.0) (2026-07-25)
 
 

package/lib/cli/version-helpers.js

@@ -16,6 +16,13 @@
  * Builtins only — this module is imported from both the CLI surface
  * (`lib/cli/`) and the doctor registry which runs before third-party
  * packages are guaranteed to be present.
+ *
+ * The two filesystem-touching helpers below take the module's injectable
+ * seam as their optional final `fsImpl` parameter, defaulting to the real
+ * `node:fs` (`.agents/rules/test-seams.md` rules 1-2);
+ * `resolveConsumerPinVersion` forwards that seam to
+ * `resolveConsumerPinSpec` rather than re-acquiring `fs` itself (rule 4).
+ * Every other export here is pure, so it needs no seam of its own.
  */
 
 import nodeFs from 'node:fs';

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

@@ -40,10 +40,11 @@ const TAG_LINE_RE = /^(\s*)(@\S+(?:\s+@\S+)*)\s*$/;
  * Recursively collect `.feature` file paths under `root`.
  *
  * @param {string} root
- * @param {typeof nodeFs} fsImpl
+ * @param {typeof nodeFs} [fsImpl] Filesystem seam; defaults to the real
+ *   `node:fs` per `.agents/rules/test-seams.md` rule 1.
  * @returns {string[]}
  */
-function collectFeatureFiles(root, fsImpl) {
+function collectFeatureFiles(root, fsImpl = nodeFs) {
   /** @type {string[]} */
   const found = [];
   /** @type {string[]} */
@@ -71,11 +72,13 @@ function collectFeatureFiles(root, fsImpl) {
 
 /**
  * @param {unknown} ctx
- * @param {typeof nodeFs} fsImpl
+ * @param {typeof nodeFs} [fsImpl] Filesystem seam; forwarded to
+ *   {@link collectFeatureFiles} rather than re-acquired there
+ *   (`.agents/rules/test-seams.md` rule 4).
  * @returns {string[]} Absolute paths of every `.feature` file under the
  *   canonical feature roots that exist in the consumer tree.
  */
-function resolveFeatureFiles(ctx, fsImpl) {
+function resolveFeatureFiles(ctx, fsImpl = nodeFs) {
   const projectRoot = ctx?.projectRoot ?? process.cwd();
   return CANONICAL_FEATURE_ROOTS.flatMap((root) =>
     collectFeatureFiles(path.join(projectRoot, root), fsImpl),
@@ -119,10 +122,12 @@ export const retireEpicAcTags = {
     '(their reconciler consumer was deleted in the v2 Epic removal)',
   /**
    * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @param {typeof nodeFs} [fsImpl] Optional final filesystem seam; defaults
+   *   to `ctx.fs` when the migration runner threads one, else the real
+   *   `node:fs` (`.agents/rules/test-seams.md` rule 1).
    * @returns {boolean}
    */
-  detect(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
+  detect(ctx, fsImpl = ctx?.fs ?? nodeFs) {
     return resolveFeatureFiles(ctx, fsImpl).some((file) => {
       try {
         return EPIC_AC_TAG_RE.test(fsImpl.readFileSync(file, 'utf8'));
@@ -133,10 +138,12 @@ export const retireEpicAcTags = {
   },
   /**
    * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @param {typeof nodeFs} [fsImpl] Optional final filesystem seam; defaults
+   *   to `ctx.fs` when the migration runner threads one, else the real
+   *   `node:fs` (`.agents/rules/test-seams.md` rule 1).
    * @returns {void}
    */
-  apply(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
+  apply(ctx, fsImpl = ctx?.fs ?? nodeFs) {
     for (const file of resolveFeatureFiles(ctx, fsImpl)) {
       /** @type {string} */
       let content;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -110,6 +110,10 @@
       "optional": true
     }
   },
+  "//": {
+    "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.2.0 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended.",
+    "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions."
+  },
   "overrides": {
     "js-yaml": "^4.2.0",
     "markdown-it": "^14.2.0"