mandrel 2.59.0 → 2.61.0

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

@@ -6,23 +6,17 @@ description: Drive Gherkin scenarios through a real browser as an agent-driven Q
 
 Execute a consumer's Gherkin `.feature` scenarios through a **real browser**
 (the chrome-devtools MCP surface), with the agent acting as the step executor
-and a human observing. The sweep resolves a **run envelope** — a target
-environment, a concrete scenario set, and an authenticated persona session —
-then delegates each scenario to
-[`helpers/qa-run-scenario.md`](helpers/qa-run-scenario.md), which drives it
-navigation-first and asserts `Then` outcomes semantically against the
-accessibility snapshot. Per-surface console and network are captured as
-structured findings, recorded as `QaLedgerItem`s on the shared session ledger,
-and triaged — after operator sign-off — through the shared classify/route/
-dedup/promote core. The harness never files tickets autonomously.
+and a human observing: resolve a run envelope, drive each scenario through
+[`helpers/qa-run-scenario.md`](helpers/qa-run-scenario.md), record findings as
+`QaLedgerItem`s, and triage after operator sign-off.
 
 The shared machinery — contract resolution + loud failure, the session & ledger
 contract, redact-first, the `QaLedgerItem` shape, the triage procedure, and the
 HITL write gate — lives once in [`helpers/qa-core.md`](helpers/qa-core.md); this
 workflow states only the `/qa-run`-specific phases (env → scope → sign-in →
-drive) plus a Constraints delta. Deterministic Node helpers under
-`.agents/scripts/lib/qa/` own contract, environment, and scenario resolution;
-the agent never invents those decisions in prose.
+drive). Deterministic Node helpers under `.agents/scripts/lib/qa/` own
+contract, environment, and scenario resolution; the agent never invents those
+decisions in prose.
 
 > **When to run**: during sprint testing to exercise a targeted slice of the
 > acceptance suite (a feature, a tag expression, or a domain), for regression
@@ -99,7 +93,8 @@ The chrome-devtools MCP surface (`navigate_page`, `take_snapshot`, `click`,
 `list_network_requests`) is **host-provided** — an external runtime dependency,
 not in-repo code. If the host does not expose it, degrade with a clear error
 ("the chrome-devtools MCP server is unavailable; the QA harness requires a live
-browser surface") and stop. Never attempt a headless fallback.
+browser surface") and stop. Never attempt a headless fallback, and never fall
+back to a retired headless BDD runner.
 
 ### Step 1 — Resolve the environment, then the scope
 
@@ -234,23 +229,6 @@ Then summarize the sweep in chat with:
 
 ## Constraints
 
-Beyond the shared core ([`helpers/qa-core.md`](helpers/qa-core.md): contract +
-loud failure, session/ledger, redact-first, QaLedgerItem, triage, HITL gate)
-and the driving rules ([`helpers/qa-run-scenario.md`](helpers/qa-run-scenario.md):
-navigation-first, semantic `Then`, redaction, sequential-only), the
-`/qa-run`-specific deltas are:
-
-- **Always** resolve a target environment (Step 1) — prompt when no `<env>` is
-  supplied — and **fail loudly** on an unknown name or unmatched URL; never
-  silently fall back to the default.
-- **Always** apply the `allowWrites` guardrail: on a read-only environment,
-  exclude mutating scenarios and report the exclusion count; include them only
-  on explicit in-session operator confirmation.
-- **Always** sign in per persona through the environment's `signInSeam` and
-  confirm the authenticated state with a post-sign-in `take_snapshot` before
-  driving.
-- An **empty selection is operator error**, not a passing sweep — report it and
-  stop.
-- **Never** expand `consoleAllowlist` to suppress genuine error signal.
-- **Never** file follow-up tickets autonomously, and **never** fall back to a
-  retired headless BDD runner.
+The shared core in [`helpers/qa-core.md`](helpers/qa-core.md) and the driving
+rules in [`helpers/qa-run-scenario.md`](helpers/qa-run-scenario.md) bind this
+workflow; the `/qa-run` deltas are the MUSTs in Steps 0–5 above.

package/README.md

@@ -105,7 +105,7 @@ idempotent — safe to re-run anytime.
 
 For the consumer reference and the end-to-end workflow narrative, see
 [`.agents/README.md`](.agents/README.md) and
-[`.agents/docs/SDLC.md`](.agents/docs/SDLC.md). Every `.agentrc.json` key is
+[`docs/SDLC.md`](docs/SDLC.md). Every `.agentrc.json` key is
 documented in [`.agents/docs/configuration.md`](.agents/docs/configuration.md), and the
 slash-command index lives in
 [`.agents/docs/workflows.md`](.agents/docs/workflows.md).

package/bin/mandrel.js

@@ -2,17 +2,8 @@
 // bin/mandrel.js — mandrel CLI entry point
 
 /**
- * Allowlist-based subcommand dispatcher.
- *
- * Only modules listed in SUBCOMMANDS are dispatchable. Each entry declares the
- * name, a one-line description for help output, and the set of known flags so
- * the dispatcher can reject unknown flags before loading the subcommand.
- *
- * Supported top-level flags:
- *   --help / -h    Print subcommand list and exit 0.
- *   --version      Print installed version and exit 0.
- *
- * Each subcommand module must export a default function `run(argv)`.
+ * Allowlist dispatcher: only SUBCOMMANDS entries load, and unknown flags are
+ * rejected before loading. Each module default-exports `run(argv)`.
  */
 
 import { createRequire } from 'node:module';
@@ -21,10 +12,6 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-// ---------------------------------------------------------------------------
-// Subcommand registry — the ONLY allowed dispatch targets
-// ---------------------------------------------------------------------------
-
 /**
  * @typedef {{ description: string, knownFlags: Set<string> }} SubcommandMeta
  * @type {Map<string, SubcommandMeta>}
@@ -108,13 +95,7 @@ const SUBCOMMANDS = new Map([
   ],
 ]);
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
 /**
- * Read the installed mandrel version from the root package.json.
- *
  * @returns {string}
  */
 function installedVersion() {
@@ -124,8 +105,6 @@ function installedVersion() {
 }
 
 /**
- * Print the help screen listing all subcommands with descriptions.
- *
  * @param {(s: string) => void} [write]
  */
 function printHelp(write = (s) => process.stdout.write(s)) {
@@ -144,8 +123,6 @@ function printHelp(write = (s) => process.stdout.write(s)) {
 }
 
 /**
- * Suggest the closest known subcommand name for a typo (Levenshtein-1).
- *
  * @param {string} input
  * @returns {string | undefined}
  */
@@ -157,8 +134,7 @@ function suggest(input) {
 }
 
 /**
- * Compute Levenshtein edit distance between two strings (capped at 3 for
- * performance — we only care about small distances).
+ * Edit distance; returns 4 early when lengths differ by more than 3.
  *
  * @param {string} a
  * @param {string} b
@@ -182,19 +158,11 @@ function levenshtein(a, b) {
   return prev[b.length];
 }
 
-/**
- * Universal flags that all subcommands accept and that bypass per-subcommand
- * flag validation. Subcommands may handle these themselves internally.
- */
+/** Accepted by every subcommand, bypassing per-subcommand validation. */
 const UNIVERSAL_FLAGS = new Set(['--help', '-h']);
 
 /**
- * Validate the argv array against the known flags for a subcommand.
- * Returns null when all flags are known; an error message string when an
- * unknown flag is detected. Values following `=` or the next positional are
- * allowed — only the flag name prefix is checked.
- *
- * Universal flags (--help, -h) are always allowed and bypass this check.
+ * Only flag names are checked (`--flag=value` is split).
  *
  * @param {string} subName
  * @param {Set<string>} knownFlags
@@ -204,7 +172,6 @@ const UNIVERSAL_FLAGS = new Set(['--help', '-h']);
 function findUnknownFlag(subName, knownFlags, argv) {
   for (const arg of argv) {
     if (!arg.startsWith('-')) continue;
-    // Strip value portion for `--flag=value` form.
     const flagName = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
     if (UNIVERSAL_FLAGS.has(flagName)) continue;
     if (!knownFlags.has(flagName)) {
@@ -219,14 +186,9 @@ function findUnknownFlag(subName, knownFlags, argv) {
   return null;
 }
 
-// ---------------------------------------------------------------------------
-// Dispatch
-// ---------------------------------------------------------------------------
-
 const args = process.argv.slice(2);
 const sub = args[0];
 
-// --- Top-level flags (no subcommand) ---
 if (!sub || sub === '--help' || sub === '-h') {
   printHelp();
   process.exit(0);
@@ -237,7 +199,6 @@ if (sub === '--version') {
   process.exit(0);
 }
 
-// --- Subcommand lookup ---
 const meta = SUBCOMMANDS.get(sub);
 if (!meta) {
   const subcommandList = [...SUBCOMMANDS.keys()].join(', ');
@@ -250,7 +211,6 @@ if (!meta) {
   process.exit(1);
 }
 
-// --- Unknown-flag rejection ---
 const subArgv = args.slice(1);
 const unknownFlagError = findUnknownFlag(sub, meta.knownFlags, subArgv);
 if (unknownFlagError) {
@@ -258,7 +218,6 @@ if (unknownFlagError) {
   process.exit(1);
 }
 
-// --- Load and dispatch ---
 const subFile = path.resolve(__dirname, '..', 'lib', 'cli', `${sub}.js`);
 const subFileUrl = pathToFileURL(subFile).href;
 

package/bin/postinstall.js

@@ -2,38 +2,11 @@
 // bin/postinstall.js — best-effort `.agents/` materializer on install.
 
 /**
- * Published-package `postinstall` hook.
- *
- * Runs `mandrel sync` to materialize the package payload into the consumer's
- * `./.agents/` working copy. This hook is **best-effort by contract** (Tech
- * Spec #3459 "Postinstall safety", Feature #3461): it MUST exit 0 even when
- * the sync fails, so that `--ignore-scripts` installs, sandboxed CI, or a
- * transient copy error degrade to the `mandrel doctor`-detected
- * "not materialized" state rather than failing the consumer's install.
- *
- * On any failure it logs a single actionable hint — "run `mandrel sync`" —
- * and exits 0. It performs nothing beyond the local file copy that
- * `mandrel sync` itself does: no network, no shell, no writes outside
- * `./.agents/`.
- *
- * **Source-checkout guard (Story #3489, fixed in #3580).** In the Mandrel
- * framework repo itself, `./.agents/` is not a regenerated working copy — it
- * *is* the committed product, and `mandrel sync` would clobber that source of
- * truth with a copy of `node_modules/mandrel/.agents/`. Today the
- * repo `.npmrc` (`ignore-scripts=true`) masks this, but a contributor running
- * `npm install --ignore-scripts=false` (or a tool that re-enables scripts)
- * would overwrite the source tree. To make the guard intrinsic rather than
- * config-dependent, the hook detects the source checkout and no-ops (exit 0)
- * without invoking the materializer. Consumer installs (where the package is
- * a dependency under `node_modules/`) are unaffected and still materialize
- * `.agents/` as before — see `isSourceCheckout` for the two signals used to
- * tell them apart.
- *
- * Injectable seams (used by tests/cli/postinstall.test.js):
- *   - `sync`             — replaces the real `runSync` from lib/cli/sync.js
- *   - `isSourceCheckout` — replaces the source-checkout detector
- *   - `writeErr`         — replaces process.stderr.write
- *   - `exit`             — replaces process.exit
+ * Runs `mandrel sync` on install. Best-effort by contract: always exits 0 so
+ * `--ignore-scripts`, sandboxed CI, or a copy error degrade to the
+ * doctor-detected "not materialized" state instead of failing the install.
+ * In the framework's own source checkout it no-ops, since `.agents/` there is
+ * the committed product and a sync would clobber it.
  */
 
 import nodeFs from 'node:fs';
@@ -47,36 +20,13 @@ const HINT =
   'mandrel: could not materialize ./.agents/ during install — run `mandrel sync` to finish setup.\n';
 
 /**
- * Detect whether this hook is running inside the Mandrel framework source
- * checkout (as opposed to a consumer project that depends on the package).
- *
- * Two complementary, fail-safe signals — both biased toward running the sync
- * (the safe default for a consumer) — tell the two cases apart:
- *
- * 1. **`node_modules` path guard (primary).** When the package is installed as
- *    a dependency this module lives at
- *    `<consumer>/node_modules/mandrel/bin/postinstall.js`, so its own
- *    resolved path contains a `node_modules` segment. That is true *by
- *    construction* for every dependency install and needs no env var, so a
- *    `node_modules` ancestor is treated as an unambiguous consumer install →
- *    return `false` (run the sync). This is the signal the original guard
- *    (Story #3489) was missing: it resolved the package's **own**
- *    `package.json` (always named `mandrel`) instead of the consumer
- *    root, so it misfired on every consumer install and skipped the sync
- *    (Story #3580).
- *
- * 2. **`INIT_CWD`-rooted name check (source-repo signal).** Outside
- *    `node_modules`, resolve the **invoking project root** and compare its
- *    `package.json#name` to `mandrel`. npm sets `INIT_CWD` to the
- *    directory where `npm install` was invoked — the framework repo root when
- *    a contributor installs the framework itself. When `INIT_CWD` is unset
- *    (e.g. the hook is run directly via `node`, outside npm), fall back to the
- *    module-relative repo root (`bin/postinstall.js` sits one directory below
- *    it), which still resolves to the source repo's own `package.json`.
- *
- * Fails safe: any read/parse error returns `false` (treat as a consumer
- * install and let the best-effort sync run), so a malformed or missing
- * `package.json` never strands a consumer without their `.agents/` payload.
+ * Two signals, both biased toward running the sync:
+ * 1. A `node_modules` segment in this module's own path means a dependency
+ *    install — never the source repo (reading the package's own
+ *    `package.json` would always say `mandrel`).
+ * 2. Otherwise compare the invoking root's `package.json#name` (`INIT_CWD`,
+ *    or the module-relative repo root outside npm) to `mandrel`.
+ * Any read/parse error returns `false`.
  *
  * @param {{ fs?: typeof nodeFs, initCwd?: string, moduleUrl?: string }} [opts]
  * @returns {boolean} `true` when running in the `mandrel` source repo.
@@ -88,13 +38,8 @@ export function isSourceCheckout({
 } = {}) {
   try {
     const here = path.dirname(fileURLToPath(moduleUrl));
-    // Installed as a dependency → unambiguously a consumer install, regardless
-    // of what any package.json#name says. Run the sync.
     if (here.split(path.sep).includes('node_modules')) return false;
 
-    // Source checkout: resolve the invoking project root (the dir where
-    // `npm install` ran) and compare its package name. Fall back to the
-    // module-relative repo root when npm did not set INIT_CWD.
     const root = initCwd || path.join(here, '..');
     const pkg = JSON.parse(
       fs.readFileSync(path.join(root, 'package.json'), 'utf8'),
@@ -106,30 +51,10 @@ export function isSourceCheckout({
 }
 
 /**
- * Run the materializer, swallowing any failure into an exit-0 hint.
- *
- * When invoked inside the framework source checkout the hook short-circuits
- * to a clean exit 0 *before* touching the materializer (Story #3489), so the
- * committed `.agents/` source is never overwritten — even under
- * `--ignore-scripts=false`.
- *
- * `runSync` calls its injected `exit` with a non-zero code when the package
- * is not resolvable (the common `--ignore-scripts`-adjacent failure). We
- * intercept that here instead of letting it propagate to `process.exit`,
- * and we also catch any thrown error (e.g. a mid-copy filesystem fault), so
- * the postinstall lifecycle can never fail the consumer's `npm install`.
- *
- * **Destination root (Story #3584).** `runSync` derives its destination from
- * `process.cwd()`, but npm runs a dependency's lifecycle scripts with cwd set
- * to the **package's own directory** (`node_modules/mandrel`), not
- * the consumer project root. Left unset, the materializer would copy
- * `.agents/` back onto the package's own payload and the consumer's project
- * root would get nothing. We pass `runSync` a `cwd` resolving to `INIT_CWD` —
- * the directory where `npm install` was invoked (the consumer root) — falling
- * back to `process.cwd()` only when the hook runs outside npm (`INIT_CWD`
- * unset). This is scoped to the postinstall path: the manual `mandrel sync` /
- * `mandrel update` paths already run from the project root and keep
- * `runSync`'s default `process.cwd()` behaviour.
+ * Both a non-zero `exit` from `runSync` and a thrown error become the exit-0
+ * hint. The destination is `INIT_CWD` (the consumer root), because npm runs
+ * lifecycle scripts with cwd set to `node_modules/mandrel` — syncing there
+ * would copy the payload onto itself.
  *
  * @param {{
  *   sync?: typeof runSync,
@@ -148,9 +73,7 @@ export function runPostinstall({
   writeErr = (s) => process.stderr.write(s),
   exit = (code) => process.exit(code),
 } = {}) {
-  // Source-checkout guard (Story #3489): never materialize over the
-  // framework's own committed `.agents/` source. No hint — this is the
-  // expected, correct no-op in the framework repo, not a degraded state.
+  // Expected no-op in the framework repo, so no hint.
   if (detectSource()) {
     exit(0);
     return { exitCode: 0, hinted: false, skipped: true };
@@ -158,18 +81,8 @@ export function runPostinstall({
 
   let syncFailed = false;
   try {
-    // No argv is forwarded: the install-time materialization is a plain,
-    // overwrite-in-place copy. The `mandrel sync` tokens in the package.json
-    // `postinstall` string document intent (and are what the hint points
-    // operators at); they are not flags this hook needs to honor.
     sync({
-      // Resolve the destination from INIT_CWD (the consumer project root,
-      // where `npm install` ran), not the package dir npm makes cwd during
-      // the postinstall lifecycle (Story #3584). Fall back to process.cwd()
-      // outside npm, when INIT_CWD is unset.
       cwd: () => initCwd || process.cwd(),
-      // Best-effort: never let sync's own non-zero exit terminate the
-      // install. Record the failure and fall through to the exit-0 hint.
       exit: (code) => {
         if (code !== 0) syncFailed = true;
       },
@@ -182,13 +95,11 @@ export function runPostinstall({
     writeErr(HINT);
   }
 
-  // Always succeed: the install must not fail on a best-effort sync.
   exit(0);
   return { exitCode: 0, hinted: syncFailed, skipped: false };
 }
 
-// Run when invoked directly as the postinstall hook (not when imported by a
-// test). `process.argv[1]` is the resolved path to this file under npm.
+// Only when run as the hook, not when imported by a test.
 const invokedDirectly = process.argv[1]?.endsWith('postinstall.js');
 if (invokedDirectly) {
   runPostinstall();

package/docs/CHANGELOG.md

@@ -15,6 +15,66 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.61.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.60.0...mandrel-v2.61.0) (2026-09-18)
+
+
+### ⚠ BREAKING CHANGES
+
+* these .agentrc keys are removed and now fail validation (mandrel update strips them first): delivery.quality.gates.lint, delivery.quality.gates.lighthouse, delivery.quality.gateScoping, delivery.quality.formatAutofix, delivery.quality.codingGuardrails, delivery.quality.baselineEpsilon, delivery.quality.autoRefresh.crapJumpCap, delivery.quality.autoRefresh.scope, delivery.quality.gates.crap.friction, delivery.quality.gates.crap.refreshTag, delivery.quality.gates.crap.refreshTimeoutMs, delivery.quality.gates.crap.incrementalCoverage.enabled, delivery.quality.gates.maintainability.refreshTag, delivery.quality.gates.maintainability.refreshTimeoutMs, delivery.quality.gates.duplication.refreshTimeoutMs, delivery.quality.gates.coverage.timeoutMs, delivery.quality.gates.mutation.strykerConfigPath, delivery.ci.watch, delivery.execution.timeoutMs, delivery.execution.requireCreditedCapture, delivery.tempRetention.staleDays, delivery.mergeWatch.intervalSeconds, delivery.mergeWatch.updateAttempts, delivery.review, delivery.feedbackLoop.frictionWindowDays, delivery.auditToStories, delivery.codeReview.providerConfig, delivery.codeReview.maxFixAttempts, github.defaultTimeoutMs, planning.memoryPool. The lint and lighthouse baseline kinds are gone from check-baselines.
+* removed from the shipped payload (now repo-root scripts/, not distributed): .agents/scripts/test-isolate.js, .agents/scripts/check-test-portability.js, .agents/scripts/install-matrix-assert.js, .agents/scripts/check-audit-attribution.js, .agents/scripts/check-pinned-override-notes.js, .agents/scripts/check-action-pinning.js, .agents/scripts/check-baseline-drift.js, .agents/scripts/check-baseline-scope.js, .agents/scripts/check-generated-validator.js, .agents/scripts/check-knip-entries.js, .agents/scripts/check-lifecycle-lint.js, .agents/scripts/check-schema-references.js, .agents/scripts/check-workflow-citations.js, .agents/scripts/check-workflow-cli-lint.js, .agents/scripts/check-workflow-timeouts.js, .agents/scripts/lint-label-vocabulary.js, .agents/scripts/provision-git-hooks.js, .agents/scripts/run-coverage.js, .agents/scripts/run-lint.js, .agents/scripts/run-test-profile.js, .agents/scripts/run-verify.js, .agents/scripts/update-dead-exports-baseline.js, .agents/scripts/prune-baseline-orphans.js, .agents/scripts/post-structured-comment.js, plus .agents/scripts/lib/test-isolate/, .agents/scripts/lib/test-profile/, .agents/scripts/lib/dynamic-workflow/ and the rules .agents/rules/known-tooling-behavior.md, .agents/rules/test-seams.md and .agents/rules/orchestration-error-handling.md (now docs/contributing/).
+
+### Added
+
+* adopt a contract-once comment policy and trim source comments to it ([#5384](https://github.com/dsj1984/mandrel/issues/5384)) ([#5391](https://github.com/dsj1984/mandrel/issues/5391)) ([13b98de](https://github.com/dsj1984/mandrel/commit/13b98de474019fd61935f8e95b855b8c6f923d7d))
+* cut the unused .agentrc config surface and migrate consumers off it ([#5382](https://github.com/dsj1984/mandrel/issues/5382)) ([#5389](https://github.com/dsj1984/mandrel/issues/5389)) ([660a71c](https://github.com/dsj1984/mandrel/commit/660a71cf5b1acd77a44a4460c4424e43746bf738))
+* stop close re-running the suite after base-sync and failing at pre-push on CRAP scope ([#5378](https://github.com/dsj1984/mandrel/issues/5378)) ([#5379](https://github.com/dsj1984/mandrel/issues/5379)) ([83bda93](https://github.com/dsj1984/mandrel/commit/83bda93942a909bd18307ae0dedabf3c814768af))
+
+
+### Fixed
+
+* make the full-suite lock and close's suite spawns signal-safe, bounded and visible ([#5377](https://github.com/dsj1984/mandrel/issues/5377)) ([#5387](https://github.com/dsj1984/mandrel/issues/5387)) ([e3a32cb](https://github.com/dsj1984/mandrel/commit/e3a32cb6f773892b8cbfd0d4b9bbc81256038777))
+* move contributor-only tooling out of the .agents payload ([#5381](https://github.com/dsj1984/mandrel/issues/5381)) ([#5388](https://github.com/dsj1984/mandrel/issues/5388)) ([984352b](https://github.com/dsj1984/mandrel/commit/984352b0cdcdd5707c8ed0c49e728bc9875634c6))
+
+
+### Changed
+
+* make each close-path merge decision once ([#5383](https://github.com/dsj1984/mandrel/issues/5383)) ([#5390](https://github.com/dsj1984/mandrel/issues/5390)) ([027da2e](https://github.com/dsj1984/mandrel/commit/027da2efe4719c0dc2a6a5065afc710bd0f796a0))
+
+## [2.60.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.59.0...mandrel-v2.60.0) (2026-09-18)
+
+
+### ⚠ BREAKING CHANGES
+
+* `delivery.feedbackLoop.auditResultsAutoFile` is no longer a valid `.agentrc.json` key. `mandrel update` strips it automatically.
+* deliver-light.js no longer accepts --kinds, --magnitude, --uncertainty or --route; STORY_SHAPE_CEILINGS and the four ceiling SHAPE_CODES are removed, and no gate envelope carries warnings[].
+* under delivery.routing.ceremonyProfile standard the acceptance verdict is authored inline; set strict to keep a fresh-context critic.
+* plan-persist.js persists on a clean dry-run by default — pass --dry-run to validate only; the "Commit subject begins with '<prefix>:'" acceptance validator is removed; an empty verify[] is a warning, not a refusal.
+* delivery.feedbackLoop.retroProposals and delivery.feedbackLoop.auditResultsAutoFile now default to false; a consumer that relied on auto-filed follow-up issues sets both to true in .agentrc.json.
+
+### Added
+
+* add deliver-run.js so a multi-Story run is one script beat plus spawns and closes, not a hand-driven protocol ([#5345](https://github.com/dsj1984/mandrel/issues/5345)) ([#5354](https://github.com/dsj1984/mandrel/issues/5354)) ([591dad7](https://github.com/dsj1984/mandrel/commit/591dad75923133bef9e3a9d095ac47442464943b))
+* clamp deliver-runner concurrency to one when worktree isolation resolves off, so two workers can never share a checkout ([#5357](https://github.com/dsj1984/mandrel/issues/5357)) ([#5360](https://github.com/dsj1984/mandrel/issues/5360)) ([1f3f651](https://github.com/dsj1984/mandrel/commit/1f3f6515e4a7a4fd2c730001dc6dd4cdb44f251e))
+* close fails fast with a named blocker when GitHub GraphQL is unavailable, instead of a raw 403 after the full gate chain ([#5355](https://github.com/dsj1984/mandrel/issues/5355)) ([#5359](https://github.com/dsj1984/mandrel/issues/5359)) ([b46c263](https://github.com/dsj1984/mandrel/commit/b46c26329dd7cc1e968e607ccaae9d51a9f1ef84))
+* collapse the ceremony decision to what it decides and delete the inert layer around it ([#5366](https://github.com/dsj1984/mandrel/issues/5366)) ([#5375](https://github.com/dsj1984/mandrel/issues/5375)) ([54d0ece](https://github.com/dsj1984/mandrel/commit/54d0ece864d8cb3ec824228dc097999781f7b29f))
+* collapse the light path to one gate and let an escalation continue in-session ([#5344](https://github.com/dsj1984/mandrel/issues/5344)) ([#5353](https://github.com/dsj1984/mandrel/issues/5353)) ([c09acd6](https://github.com/dsj1984/mandrel/commit/c09acd69a8525dd33073922a7541bb9488929249))
+* cut the restated delivery rules, the v1 refusals and the sibling-coherence step, and turn auto-filing off by default ([#5341](https://github.com/dsj1984/mandrel/issues/5341)) ([#5350](https://github.com/dsj1984/mandrel/issues/5350)) ([349d346](https://github.com/dsj1984/mandrel/commit/349d3468c11a23504b510ac80d0716b5dd709853))
+* delivery ceremony diet: one inline verdict per Story, opt-in fresh critics and audit roster, fewer Story comments, and one CI rerun after a recorded verdict ([#5343](https://github.com/dsj1984/mandrel/issues/5343)) ([#5352](https://github.com/dsj1984/mandrel/issues/5352)) ([1ac35c4](https://github.com/dsj1984/mandrel/commit/1ac35c40745bd1d6f0945f9a5ffd3f975452dbff))
+* loosen plan authoring: one persist command, bare paths in changes[], empty verify[] as a warning, and the fossil validators removed ([#5342](https://github.com/dsj1984/mandrel/issues/5342)) ([#5351](https://github.com/dsj1984/mandrel/issues/5351)) ([c7534a5](https://github.com/dsj1984/mandrel/commit/c7534a523cf39b24324d26f2cad81b2ec4fb22df))
+* make a dispatch that never reached init visible in the beat envelope ([#5363](https://github.com/dsj1984/mandrel/issues/5363)) ([#5370](https://github.com/dsj1984/mandrel/issues/5370)) ([ab3c755](https://github.com/dsj1984/mandrel/commit/ab3c7553975ef5dce8c60112d7f8c278c5dd0d8d))
+
+
+### Fixed
+
+* `mandrel update` reports whether the bump is actually staged instead of asserting it ([#5339](https://github.com/dsj1984/mandrel/issues/5339)) ([#5349](https://github.com/dsj1984/mandrel/issues/5349)) ([07f63c7](https://github.com/dsj1984/mandrel/commit/07f63c79bdb19a532e82d413de719a194c170504))
+* anchor pre-push coverage capture and the CRAP preview on one resolved ref ([#5365](https://github.com/dsj1984/mandrel/issues/5365)) ([#5373](https://github.com/dsj1984/mandrel/issues/5373)) ([cb189e3](https://github.com/dsj1984/mandrel/commit/cb189e3a005749305cc0ce2075ea17793493bb0e))
+* capture coverage before the pre-push quality preview (refs [#5356](https://github.com/dsj1984/mandrel/issues/5356)) ([#5358](https://github.com/dsj1984/mandrel/issues/5358)) ([14ef1dd](https://github.com/dsj1984/mandrel/commit/14ef1dde384455f16f3ddd502881c132fd6ae056))
+* close the three correctness holes the plan-authoring loosening left in persist ([#5361](https://github.com/dsj1984/mandrel/issues/5361)) ([#5372](https://github.com/dsj1984/mandrel/issues/5372)) ([aef03bd](https://github.com/dsj1984/mandrel/commit/aef03bd90e14cc2dac68ea4d7a04f0f262e2494e))
+* delete the write-only plan checkpoint payload and the three unreachable modules ([#5367](https://github.com/dsj1984/mandrel/issues/5367)) ([#5374](https://github.com/dsj1984/mandrel/issues/5374)) ([4c0c835](https://github.com/dsj1984/mandrel/commit/4c0c835d9eded8e993bb7ebd3e66e86bec4d2377))
+* demote the workflow prose ratchets to reports and delete the reference sections that describe retired mechanisms ([#5340](https://github.com/dsj1984/mandrel/issues/5340)) ([#5347](https://github.com/dsj1984/mandrel/issues/5347)) ([8d76329](https://github.com/dsj1984/mandrel/commit/8d76329e3aacc726e39d1839f01e618fb7361662))
+* report the index mandrel update actually observes, from one read ([#5364](https://github.com/dsj1984/mandrel/issues/5364)) ([#5371](https://github.com/dsj1984/mandrel/issues/5371)) ([12af953](https://github.com/dsj1984/mandrel/commit/12af95383f7ddbfe137715aa10bce3b25a7b95a3))
+* treat a rate-limited GraphQL probe as fail-open rather than unreachable (refs [#5362](https://github.com/dsj1984/mandrel/issues/5362)) ([#5369](https://github.com/dsj1984/mandrel/issues/5369)) ([db6a9e0](https://github.com/dsj1984/mandrel/commit/db6a9e08441baf40281962e0b226575f9c7b1846))
+
 ## [2.59.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.58.0...mandrel-v2.59.0) (2026-09-14)
 
 

package/lib/cli/doctor.js

@@ -1,26 +1,8 @@
 // lib/cli/doctor.js
 /**
- * `mandrel doctor` subcommand.
- *
- * Runs every check from lib/cli/registry.js in registration order,
- * prints a ✔/✘ per-check report with remedies for failures, prints a
- * final summary line, and exits 0 when all checks pass or non-zero when
- * any check fails.
- *
- * Output contract (per Story #3450 AC):
- *   pass  → "✔  <name>   <detail>"
- *   fail  → "✘  <name>   <detail>\n   → <remedy>"
- *   final → "✅  Ready (N/N checks passed)"
- *         | "❌  Not ready (N/N checks failed)"
- *
- * All output goes to process.stdout so it can be captured by tests.
- * Exit code 0 = all pass, 1 = any fail.
- *
- * Injectable seams (used by tests):
- *   - `checks`           — replaces the default registry array
- *   - `write`            — replaces process.stdout.write
- *   - `exit`             — replaces process.exit
- *   - `writeResultCache` — replaces the temp/doctor-result.json writer
+ * `mandrel doctor`: run the registry checks in order, print a ✔/✘ line per
+ * check (with the remedy under a failure) and a summary; exit 1 on any
+ * failure.
  */
 
 import nodeFs from 'node:fs';
@@ -32,13 +14,7 @@ import {
 } from '../../.agents/scripts/lib/doc-tiers.js';
 import { registry } from './registry.js';
 
-// ---------------------------------------------------------------------------
-// Formatting helpers
-// ---------------------------------------------------------------------------
-
 /**
- * Pad or truncate `name` to `width` characters so columns line up neatly.
- *
  * @param {string} name
  * @param {number} width
  * @returns {string}
@@ -47,13 +23,10 @@ function padName(name, width) {
   return name.length >= width ? name : name + ' '.repeat(width - name.length);
 }
 
-// Column width for the check-name field (longest registry name is
-// "agents-materialized" = 19 chars; use 21 for breathing room).
+// Longest check name is 19 chars.
 const NAME_COL = 21;
 
 /**
- * Format a single check result line (or lines when a remedy is present).
- *
  * @param {{ name: string, ok: boolean, detail: string, remedy?: string }} result
  * @returns {string}
  */
@@ -68,8 +41,6 @@ function formatResult({ name, ok, detail, remedy }) {
 }
 
 /**
- * Format the final summary line.
- *
  * @param {number} passed
  * @param {number} total
  * @returns {string}
@@ -83,17 +54,9 @@ function formatSummary(passed, total) {
 }
 
 /**
- * Build the one report-only line describing the always-loaded documentation
- * closure (the `CLAUDE.md` `@`-import graph) — its file count and total size in
- * KB. This is **informational only**: it is never counted toward the pass/fail
- * tally and therefore never changes the doctor exit code (Story #4438). Any
- * failure to resolve the closure degrades to a neutral line rather than
- * throwing, so an unreadable tree never breaks the doctor run.
- *
- * Security (security-baseline § 5 — Data Leakage & Logging): emits only a file
- * count and byte total, never file contents.
- *
- * Exported for testing.
+ * Informational line for the `CLAUDE.md` always-loaded closure (file count,
+ * KB). Never counted toward the verdict; a resolve failure degrades to a
+ * neutral line.
  *
  * @param {{ cwd?: () => string, resolveClosure?: (root: string) => Array<{ path: string, bytes: number }> }} [opts]
  * @returns {string} a single line terminated by `\n`
@@ -116,19 +79,9 @@ export function formatClosureReport({
   return `ℹ  ${label}  ${files.length} file(s), ${kb} KB always-loaded\n`;
 }
 
-// ---------------------------------------------------------------------------
-// Result cache
-// ---------------------------------------------------------------------------
-
 /**
- * Best-effort write of the doctor verdict to `temp/doctor-result.json` under
- * the consumer root so downstream workflows (e.g. the `/mandrel-plan` first-run
- * preflight) can read the last recorded verdict without re-running doctor.
- * `temp/` is the gitignored scratch root, so neither git nor the sync prune
- * pass ever sees the cache. Any write failure is swallowed — the cache is
- * advisory, never a gate.
- *
- * Exported for testing.
+ * Record the verdict in `temp/doctor-result.json` for workflows that read it
+ * without re-running doctor. Advisory: write failures are swallowed.
  *
  * @param {'ready'|'unready'} verdict
  * @param {{ fs?: typeof nodeFs, cwd?: () => string }} [opts]
@@ -146,17 +99,11 @@ export function writeDoctorResultCache(
       `${JSON.stringify({ verdict, checkedAt: new Date().toISOString() }, null, 2)}\n`,
     );
   } catch {
-    // Best-effort only — an unwritable temp/ must never fail the doctor run.
+    // An unwritable temp/ must never fail the doctor run.
   }
 }
 
-// ---------------------------------------------------------------------------
-// Doctor runner (exported for testing)
-// ---------------------------------------------------------------------------
-
 /**
- * Run all checks and emit a formatted report.
- *
  * @param {{
  *   checks?: Array<{ name: string, run(opts?: unknown): { ok: boolean, detail: string, remedy?: string } }>,
  *   write?: (s: string) => void,
@@ -181,8 +128,7 @@ export async function runDoctor({
     write(formatResult({ name: check.name, ...result }));
   }
 
-  // Report-only informational line — NOT counted toward passed/total, so it
-  // never affects the doctor verdict or exit code (Story #4438).
+  // Report-only: not counted toward passed/total.
   write(closureReport());
 
   const total = checks.length;
@@ -195,13 +141,7 @@ export async function runDoctor({
   }
 }
 
-// ---------------------------------------------------------------------------
-// Subcommand entry point (called by bin/mandrel.js)
-// ---------------------------------------------------------------------------
-
 /**
- * Default export consumed by `bin/mandrel.js`.
- *
  * @param {string[]} _argv  Unused — `mandrel doctor` takes no arguments.
  * @returns {Promise<void>}
  */