mandrel 2.48.0 → 2.50.0

package/.agents/agents/story-worker.md

@@ -48,53 +48,47 @@ the step-by-step. This shared core binds every role:
 You are a **Story delivery worker**: you take one Story from init through
 implementation to a **pushed branch**, then return. You do **not** close it —
 your caller owns the close-and-land tail. Follow the `helpers/deliver-story`
-workflow prose your caller hands you; this delta states the non-negotiable
+prose your caller hands you; this delta states the non-negotiable
 MUSTs. Treat a blocking tool-permission prompt as a harness condition —
-transition to `agent::blocked` rather than waiting on an approval that
-cannot come.
+flip to `agent::blocked` rather than waiting on an approval that cannot
+come.
 
 ## Worktree discipline (MUST)
 
 1. Initialize with
    `node .agents/scripts/single-story-init.js --story <storyId>` from the
-   **main checkout**, synchronously with the Bash maximum timeout — a
-   per-worktree install can take minutes; do not background it.
-2. Capture `workCwd` and `dependenciesInstalled` from the init envelope.
+   **main checkout**, synchronously at max Bash timeout — a per-worktree
+   install can take minutes; do not background it.
+2. Capture `workCwd` and `dependenciesInstalled` from the envelope.
    Work only inside the absolute `workCwd`; never move the main checkout's
-   HEAD. Because cwd may reset between calls, anchor every path at `workCwd`.
+   HEAD. cwd may reset between calls, so anchor every path at `workCwd`.
 
 ## Verify branch before every commit (MUST)
 
-Before staging or committing anything:
-
-```bash
-git -C "<workCwd>" branch --show-current   # MUST print story-<storyId>
-```
-
-If it does not, **STOP** — never commit Story work to `main` or outside the
-worktree/branch. Re-run `single-story-init.js` (idempotent on partial
-state) to restore the branch first.
+Before staging or committing, `git -C "<workCwd>" branch --show-current`
+MUST print `story-<storyId>`. If it does not, **STOP** — never commit Story
+work to `main` or outside the worktree/branch. Re-run
+`single-story-init.js` (idempotent) to restore it.
 
 ## Commit discipline
 
-Author Conventional Commit subjects directly on `story-<storyId>` per
+Author Conventional Commit subjects on `story-<storyId>` per
 [`git-conventions.md`](../rules/git-conventions.md): imperative mood,
-≤100 chars, referencing the Story via `(refs #<storyId>)`. Never bypass the
-`commit-msg` hook with `--no-verify` / `--no-gpg-sign`. If a hook fails, fix
-the cause and add a follow-up commit; never amend the rejected one.
+≤100 chars, `(refs #<storyId>)`. Never bypass the `commit-msg` hook
+(`--no-verify` / `--no-gpg-sign`); if one fails, fix the cause and add a
+follow-up commit, never amend.
 
 ## Docs context — digest first
 
 Do **not** re-read every file in `project.docsContextFiles`. Read the
-`docsDigestPath` digest your caller passes, then pull full files on demand
-at the line numbers it names. A null `docsDigestPath` means no docs
-mandate — read a full doc only when the Story's context points at one.
+`docsDigestPath` digest your caller passes, then pull files on demand at
+the lines it names. A null `docsDigestPath` means no mandate.
 
-## Close gates — one credited run, no ad-hoc stamping
+## Close gates — one credited run
 
 `single-story-close.js` runs the canonical close-validation chain
 (**typecheck, lint, test, format, maintainability, coverage, crap**) and is
-the authoritative gate — do not pre-run the chain. The **one** exception is
+the authoritative gate — do not pre-run it. The **one** exception is
 the full suite: run it exactly once, after the self-eval loop's last fix
 commit and immediately before the push, in the shape close credits. A bare
 `npm test` / `pnpm run test` deposits **no** credit:
@@ -107,12 +101,20 @@ node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
   --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
 ```
 
-Sharing `lint` / `typecheck` evidence with close via `evidence-gate.js` is
-fine; never stamp coverage / CRAP fresh any other way.
+Dispatch it in the **background**: it routinely outruns the host's
+synchronous Bash ceiling, and its completion re-invokes you — that
+notification is the signal. Never spawn a task to poll or `sleep`-loop
+against it; a waiter whose condition is wrong outlives the agent. Share
+`lint` / `typecheck` evidence with close via `evidence-gate.js`; never
+stamp coverage / CRAP fresh any other way.
+
+**It can legitimately run nothing.** With nothing changed under the CRAP
+`targetDirs` it skips capture and exits 0. An exit code is never evidence a
+gate did work — its **output** is: no credit was deposited, so run the full
+suite yourself before handing off.
 
-Before trusting a gate's output — or diagnosing a red one — read
-[`known-tooling-behavior.md`](../rules/known-tooling-behavior.md): measured
-cases where a command prints what it does not mean.
+Gate output that lies: [`known-tooling-behavior.md`](../rules/known-tooling-behavior.md).
+Waiter traps: [`parallel-tooling.md`](../workflows/helpers/parallel-tooling.md) Rule 2.
 
 ## Acceptance self-eval before close (MUST)
 
@@ -120,27 +122,27 @@ After the implementation commits land and **before** flipping to `closing`,
 run the bounded acceptance self-eval loop
 ([`acceptance-self-eval.md`](../workflows/helpers/acceptance-self-eval.md)).
 It scores the change set you computed **once** and injected into the critic
-— never one the critic re-derives (Story #4593) — against each
-`acceptance[]` item, consuming `verify[]` output as required evidence. Gate
-outcomes: **proceed** → flip to `closing`, push, hand off; **redraft** → fix
-the flagged criteria, commit, re-eval; **block** → take the blocked path
-below. Never silently hand off an unscored branch.
+— never one it re-derives — against each `acceptance[]` item,
+consuming `verify[]` output as evidence. **proceed** → flip to `closing`,
+push, hand off; **redraft** → fix the flagged criteria, commit, re-eval;
+**block** → take the blocked path below. Never hand off an unscored
+branch.
 
 ## Lifecycle: progress & blocked (MUST)
 
-- **Progress.** Relay one terse line per phase transition (e.g.
+- **Progress.** One terse line per phase transition (e.g.
   `Story #<id>: implementing → closing`).
-- **Blocked.** When you genuinely cannot proceed, transition the Story to
+- **Blocked.** When you cannot proceed, transition the Story to
   `agent::blocked`, post a `friction` comment naming the decision needed
   (or the unmet criteria and their evidence), and **exit non-zero**.
-  **Never fall silent** — a stalled child without an `agent::blocked` label
-  and no commit is indistinguishable from a dead one.
+  **Never fall silent** — a stalled child with no label and no commit is
+  indistinguishable from a dead one.
 
-## Land or block — the only sanctioned landing (#4483, MUST)
+## Land or block — the only sanctioned landing (MUST)
 
-The Story's init envelope carries `remoteVerified` + `remoteProbe`. When
-`remoteVerified` is `false`, transition the Story to `agent::blocked`
-quoting `remoteProbe.detail` and stop. A PR opened by
+The init envelope carries `remoteVerified` + `remoteProbe`. When
+`remoteVerified` is `false`, flip to `agent::blocked` quoting
+`remoteProbe.detail` and stop. A PR opened by
 `single-story-close.js` is the only sanctioned landing.
 
 ## Your turn ends at a pushed branch (MUST)
@@ -148,14 +150,12 @@ quoting `remoteProbe.detail` and stop. A PR opened by
 You do **not** run close. Push `story-<storyId>` to `origin` — confirming
 the remote ref moved — and return. The dispatching orchestrator runs
 `single-story-close.js` in its own session, serialized against your
-siblings. Do not open the PR, do not flip `agent::done`, and do not spawn
-a child to close on your behalf. If the push itself fails, take the blocked
-path above rather than returning a hand-off you cannot back.
+siblings. Do not open the PR, flip `agent::done`, or spawn a child to close
+on your behalf. If the push fails, take the blocked path above.
 
 ## Return contract — the hand-off report
 
 A short, literal hand-off your caller can act on: Story id, `workCwd`,
 branch, pushed head SHA, self-eval verdict, `verify[]` evidence. Say plainly
-that the branch is pushed and unclosed. Never hand-compose a terminal
-envelope — that document belongs to close, and inventing one makes an
-unlanded Story look landed.
+the branch is pushed and unclosed. Never hand-compose a terminal envelope —
+inventing one makes an unlanded Story look landed.

package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js

@@ -8,8 +8,8 @@
  *   - the **creator** — `audit-labels-bootstrap.js`, which ran `gh label create`
  *     over the `audit::<lens>` list and nothing else;
  *   - the **generator** — `audit-to-stories/build-story-body.js`, which emitted
- *     `type::story`, `agent::ready`, `audit::<lens>` and — as a bare string
- *     literal — `risk::high`.
+ *     `type::story`, `audit::<lens>` and — as a bare string literal —
+ *     `risk::high`.
  *
  * `risk::high` was therefore generated by the filer and defined by **no**
  * taxonomy: not `LABEL_TAXONOMY` (the repo-wide bootstrap), not the audit
@@ -136,6 +136,14 @@ const AUDIT_STORY_AXIS_LABELS = Object.freeze([
     color: hex(LABEL_COLORS.TYPE),
     description: 'Story work item',
   },
+  // Created, never generated — the one deliberate asymmetry in this module.
+  // The filer emits no `agent::` state (see `STATIC_LABELS` in
+  // build-story-body.js): a freshly-filed audit Story is not delivery-ready,
+  // and `/mandrel-plan` stamps this label as its terminal flip after
+  // enrichment. The bootstrap still creates it so that flip has a label to
+  // apply on a repo where only the audit bootstrap has been run. The drift
+  // this module guards runs the other way — a generator inventing names the
+  // creator never made — so a creator-only entry is safe (Story #5229).
   {
     name: AGENT_LABELS.READY,
     color: hex(LABEL_COLORS.AGENT),

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -10,9 +10,9 @@
  * Pure: returns { title, body, labels }. Labels carry one canonical
  * `audit::<lens>` per distinct source report represented in the merge
  * (derived from each finding's `sourceReport` basename, NEVER from the
- * fine-grained `dimension` text — see Story #4195), plus the standard
- * `type::story`, `agent::ready`, and (when any finding is Critical)
- * `risk::high`.
+ * fine-grained `dimension` text — see Story #4195), plus `type::story` and
+ * (when any finding is Critical) `risk::high`. Deliberately **no `agent::`
+ * state label** — see {@link STATIC_LABELS}.
  *
  * The body is serialized via the canonical story-body serializer
  * (`.agents/scripts/lib/story-body/story-body.js`) so the output round-trips
@@ -23,7 +23,7 @@
  */
 
 import path from 'node:path';
-import { AGENT_LABELS, RISK_LABELS, TYPE_LABELS } from '../label-constants.js';
+import { RISK_LABELS, TYPE_LABELS } from '../label-constants.js';
 import { serialize } from '../story-body/story-body.js';
 import { definesAuditLabel } from './audit-label-taxonomy.js';
 import { auditLabelsForFindings } from './audit-lenses.js';
@@ -32,7 +32,26 @@ import {
   renderSemanticKeyFooter,
 } from './finding-adapter.js';
 
-const STATIC_LABELS = Object.freeze([TYPE_LABELS.STORY, AGENT_LABELS.READY]);
+// The story-axis labels every generated audit Story carries, and the one it
+// deliberately does NOT: an `agent::` state.
+//
+// This used to be `[TYPE_LABELS.STORY, AGENT_LABELS.READY]`, which put every
+// Story the sweep filed one step from execution. `agent::ready` is precisely
+// what `/mandrel-deliver` reads as "available for pickup", and the bodies
+// reaching this function are audit prose — a synthesized acceptance line per
+// finding and an Agent Prompts section that is empty whenever the lens
+// captured no `agentPrompt`. Filing them ready contradicted the sweep's own
+// shipped runbook, whose enrich-before-you-deliver step says not to point
+// `/mandrel-deliver` at a freshly-filed audit Story; the label said the
+// opposite of the prose, and the label is the half a machine reads.
+//
+// The state axis therefore belongs to whoever enriches the finding:
+// `/mandrel-plan` stamps `agent::ready` as its terminal flip once the Story
+// has a `## Spec`, real acceptance criteria and runnable verify lines. An
+// absent `agent::` label is a legal initial state — `isValidTransition`
+// treats a null from-state as the initial-entry edge and permits any target —
+// so nothing downstream has to special-case the gap (Story #5229).
+const STATIC_LABELS = Object.freeze([TYPE_LABELS.STORY]);
 
 // The verify[] contract every generated audit Story carries. These commands
 // exist in this repo's harness (package.json scripts) so the Story satisfies

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -17,12 +17,12 @@
  * `temp/standalone/stories/story-<id>/validation-evidence.json`, so a
  * second close at unchanged HEAD short-circuits the already-passed gates.
  *
- * Format-autofix self-heal (Story #4250). The Epic path runs
- * `runScopedFormatAutofix` before the check-only gates so benign JSON/YAML
- * drift the formatter can fix is folded into a `fix(story-close):` commit
- * rather than hard-failing the format gate. The standalone path now does
- * the same, with `baseBranch` as the diff anchor and the Story worktree as
- * the commit target.
+ * Pre-gate self-heal (Stories #4250, #5224). Two best-effort steps run on the
+ * Story branch before the check-only gates score it — the scoped format
+ * autofix and the upward maintainability write-back — so whatever they commit
+ * is part of what the gates see and part of the branch's own PR. Both live in
+ * [`pre-gate-steps.js`](pre-gate-steps.js); neither can fail a close, because
+ * an authoritative gate for each runs immediately below.
  *
  * Bounded gate output (Story #4736). Every gate line goes to the run's
  * `gate-log.js` sink — an artifact under the gitignored temp tree — instead
@@ -40,25 +40,24 @@
  * `*:update` + `baseline-refresh:` remedy — advisory only, so the close
  * verdict is unchanged.
  *
- * `runCloseValidation`, `buildDefaultGates`, and `runScopedFormatAutofix`
- * are accepted as injected dependencies so the parent CLI's cache-busted
- * bindings win in tests that mock the upstream module URLs.
+ * `runCloseValidation`, `buildDefaultGates` and the pre-gate steps (whole, or
+ * their two individual collaborators) are accepted as injected dependencies so
+ * the parent CLI's cache-busted bindings win in tests that mock the upstream
+ * module URLs.
  */
 
 import { buildDefaultGates as defaultBuildDefaultGates } from '../../../close-validation/gates.js';
 import { runCloseValidation as defaultRunCloseValidation } from '../../../close-validation/runner.js';
-import { Logger } from '../../../Logger.js';
-import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../story-close/format-autofix.js';
 import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
+import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
 
 /**
  * Run the close-validation gate chain. Throws on first gate failure.
  *
- * Order (Story #4250): format-autofix self-heal → close-validation gates.
- * The autofix step scopes the formatter to the `baseBranch...storyBranch`
- * diff, commits any fix on the Story branch inside the Story worktree, and
- * is best-effort — a missing `storyBranch` (resume/legacy callers) skips it
- * with a log line rather than failing.
+ * Order: pre-gate self-heal steps → close-validation gates. The steps scope
+ * to the `baseBranch...storyBranch` diff, commit inside the Story worktree,
+ * and are best-effort — a missing `storyBranch` (resume/legacy callers) skips
+ * them with a log line rather than failing.
  *
  * Gates are built from the canonical resolved config (`buildDefaultGates`
  * reads `project.commands` and `delivery.quality.gates.crap.enabled`); the
@@ -76,7 +75,9 @@ import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
  *   progress: (tag: string, msg: string) => void,
  *   runCloseValidation?: typeof defaultRunCloseValidation,
  *   buildDefaultGates?: typeof defaultBuildDefaultGates,
- *   runScopedFormatAutofix?: typeof defaultRunScopedFormatAutofix,
+ *   runPreGateSteps?: typeof defaultRunPreGateSteps,
+ *   runScopedFormatAutofix?: Function,
+ *   runBaselineUpwardWriteback?: Function,
  *   createGateLogSink?: typeof defaultCreateGateLogSink,
  * }} args
  * @returns {Promise<{ gates: Record<string, 'passed'|'skipped'> }>} Per-gate
@@ -94,52 +95,22 @@ export async function runCloseValidationPhase({
   progress,
   runCloseValidation = defaultRunCloseValidation,
   buildDefaultGates = defaultBuildDefaultGates,
-  runScopedFormatAutofix = defaultRunScopedFormatAutofix,
+  runPreGateSteps = defaultRunPreGateSteps,
+  runScopedFormatAutofix,
+  runBaselineUpwardWriteback,
   createGateLogSink = defaultCreateGateLogSink,
 }) {
-  // Story #4250 — format-autofix self-heal before the check-only gates.
-  // Mirrors the Epic path (story-close/phases/gates.js): the formatter is
-  // scoped to the baseBranch...storyBranch diff, and any fix is committed on
-  // the Story branch in the Story worktree. Skipped (with a log) when no
-  // storyBranch is available so resume/legacy callers don't trip a throw.
-  if (storyBranch) {
-    progress(
-      'FORMAT',
-      `Running scoped format-autofix on ${baseBranch}...${storyBranch}${worktreePath ? ` in ${worktreePath}` : ''}...`,
-    );
-    // Best-effort self-heal: a failure to even compute the diff (e.g. a
-    // missing ref) must never abort close — the format check gate downstream
-    // is the source of truth for "is the tree formatted". We log and proceed.
-    try {
-      const autofix = runScopedFormatAutofix({
-        cwd,
-        worktreePath,
-        storyId,
-        baseBranch,
-        storyBranch,
-        config,
-        logger: Logger,
-      });
-      if (autofix?.committed) {
-        progress(
-          'FORMAT',
-          `✅ Auto-applied format fix committed as ${autofix.sha} on ${storyBranch}.`,
-        );
-      } else {
-        progress(
-          'FORMAT',
-          `⏭ No format-autofix commit (${autofix?.reason ?? 'clean'}).`,
-        );
-      }
-    } catch (err) {
-      progress(
-        'FORMAT',
-        `⚠️ scoped format-autofix failed (close continues; format gate is authoritative): ${err?.message ?? err}`,
-      );
-    }
-  } else {
-    progress('FORMAT', '⏭ Skipped scoped format-autofix (no story branch).');
-  }
+  await runPreGateSteps({
+    cwd,
+    worktreePath,
+    storyId,
+    baseBranch,
+    storyBranch,
+    config,
+    progress,
+    runScopedFormatAutofix,
+    runBaselineUpwardWriteback,
+  });
 
   progress(
     'VALIDATE',

package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-gate-steps.js

@@ -0,0 +1,171 @@
+/**
+ * phases/pre-gate-steps.js — the self-heal steps the standalone close runs on
+ * the Story branch *before* the check-only gate chain scores it.
+ *
+ * Two steps live here, and they share one contract that is the reason they
+ * share a module: each may author a commit on `story-<id>`, each must run
+ * ahead of the gates so its commit is part of what the gates score and part of
+ * the branch's own PR, and **neither may ever fail the close**. Downstream
+ * there is always an authoritative gate — `biome ci` for formatting,
+ * `check-baselines` for the ratchet — so a failure here is a missed
+ * opportunity to self-heal, never a verdict.
+ *
+ *   1. **Scoped format-autofix** (Story #4250) — run the formatter over the
+ *      `baseBranch...storyBranch` diff and fold any rewrite into a
+ *      `fix(story-close):` commit, so benign JSON/YAML drift that lint-staged
+ *      does not glob never reaches the check-only format gate.
+ *   2. **Upward baseline write-back** (Story #5224) — persist the
+ *      maintainability rows this branch improved on files it touched, as a
+ *      `baseline-refresh:` commit, so the committed baseline stops falling
+ *      behind the tree in the upward direction.
+ *
+ * Extracted from `close-validation.js` when the second step landed. The phase
+ * module's job is the gate chain, the evidence keyspace and the gate-log sink;
+ * carrying two multi-branch best-effort wrappers inline alongside that was the
+ * mass that made it the file it was. Both collaborators stay injectable — the
+ * parent CLI's cache-busted bindings must win in tests that mock the upstream
+ * module URLs — and are threaded through from the phase unchanged.
+ */
+
+import { Logger } from '../../../Logger.js';
+import { runBaselineUpwardWriteback as defaultRunBaselineUpwardWriteback } from '../../story-close/baseline-upward-writeback.js';
+import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../story-close/format-autofix.js';
+
+/**
+ * Run the scoped formatter self-heal.
+ *
+ * @param {object} ctx the shared step context (see {@link runPreGateSteps})
+ * @returns {void}
+ */
+function formatAutofixStep({
+  cwd,
+  worktreePath,
+  storyId,
+  baseBranch,
+  storyBranch,
+  config,
+  progress,
+  runScopedFormatAutofix,
+}) {
+  progress(
+    'FORMAT',
+    `Running scoped format-autofix on ${baseBranch}...${storyBranch}${worktreePath ? ` in ${worktreePath}` : ''}...`,
+  );
+  const autofix = runScopedFormatAutofix({
+    cwd,
+    worktreePath,
+    storyId,
+    baseBranch,
+    storyBranch,
+    config,
+    logger: Logger,
+  });
+  progress(
+    'FORMAT',
+    autofix?.committed
+      ? `✅ Auto-applied format fix committed as ${autofix.sha} on ${storyBranch}.`
+      : `⏭ No format-autofix commit (${autofix?.reason ?? 'clean'}).`,
+  );
+}
+
+/**
+ * Run the upward maintainability write-back.
+ *
+ * @param {object} ctx the shared step context (see {@link runPreGateSteps})
+ * @returns {Promise<void>}
+ */
+async function baselineWritebackStep({
+  cwd,
+  worktreePath,
+  storyId,
+  baseBranch,
+  storyBranch,
+  config,
+  progress,
+  runBaselineUpwardWriteback,
+}) {
+  const writeback = await runBaselineUpwardWriteback({
+    cwd,
+    worktreePath,
+    storyId,
+    baseBranch,
+    storyBranch,
+    config,
+    logger: Logger,
+  });
+  progress(
+    'BASELINE',
+    writeback?.committed
+      ? `✅ Wrote back ${writeback.improvedPaths?.length ?? 0} improved maintainability row(s) as ${writeback.sha} on ${storyBranch}.`
+      : `⏭ No baseline write-back (${writeback?.reason ?? 'nothing to write'}).`,
+  );
+}
+
+/**
+ * Run one step, absorbing any throw into a progress line.
+ *
+ * The absorption is the point, not laziness about error handling: every step
+ * here is the *refresh* half of a loop whose *enforcement* half runs
+ * immediately afterwards. A step that could abort the close would convert a
+ * self-heal opportunity into an outage, and would do it on the path with the
+ * least operator attention.
+ *
+ * @param {{ tag: string, label: string, progress: Function, run: () => Promise<void>|void }} opts
+ * @returns {Promise<void>}
+ */
+async function bestEffort({ tag, label, progress, run }) {
+  try {
+    await run();
+  } catch (err) {
+    progress(
+      tag,
+      `⚠️ ${label} failed (close continues; the gate chain is authoritative): ${err?.message ?? err}`,
+    );
+  }
+}
+
+/**
+ * Run every pre-gate self-heal step for a standalone Story close.
+ *
+ * Both steps commit to `story-<id>`, so both are skipped — with a log line, not
+ * a throw — when the caller has no `storyBranch`. That is the resume/legacy
+ * path, which has no branch to commit onto and must not trip an exception for
+ * saying so.
+ *
+ * @param {{
+ *   cwd: string,
+ *   worktreePath: string|null,
+ *   storyId: number,
+ *   baseBranch: string,
+ *   storyBranch?: string,
+ *   config: object,
+ *   progress: (tag: string, msg: string) => void,
+ *   runScopedFormatAutofix?: typeof defaultRunScopedFormatAutofix,
+ *   runBaselineUpwardWriteback?: typeof defaultRunBaselineUpwardWriteback,
+ * }} args
+ * @returns {Promise<void>}
+ */
+export async function runPreGateSteps({
+  runScopedFormatAutofix = defaultRunScopedFormatAutofix,
+  runBaselineUpwardWriteback = defaultRunBaselineUpwardWriteback,
+  ...ctx
+}) {
+  const { storyBranch, progress } = ctx;
+  if (!storyBranch) {
+    progress('FORMAT', '⏭ Skipped scoped format-autofix (no story branch).');
+    progress('BASELINE', '⏭ Skipped baseline write-back (no story branch).');
+    return;
+  }
+  await bestEffort({
+    tag: 'FORMAT',
+    label: 'scoped format-autofix',
+    progress,
+    run: () => formatAutofixStep({ ...ctx, runScopedFormatAutofix }),
+  });
+  await bestEffort({
+    tag: 'BASELINE',
+    label: 'baseline write-back',
+    progress,
+    run: () => baselineWritebackStep({ ...ctx, runBaselineUpwardWriteback }),
+  });
+}

package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js

@@ -0,0 +1,483 @@
+/**
+ * baseline-upward-writeback.js — persist improved maintainability rows on the
+ * branch that earned them (Story #5224).
+ *
+ * The diff-scoped baseline ratchet only ever reds on a REGRESSION. A branch
+ * that *improves* a file it touched is therefore waved through with its
+ * committed row left describing the worse, older tree — and nothing on the
+ * per-PR path ever writes it back. The only thing that notices is the nightly
+ * full-scope re-score (`check-baseline-drift.js`), which had filed the same
+ * one-command chore seven times before this module existed.
+ *
+ * The classifier already does the hard half: `kinds/kind-factory.js#classify`
+ * partitions every compared row into `regressions` / `improvements` /
+ * `unchanged` / `additions`, and the enforcement path forwards `improvements`
+ * all the way to the report. Nothing persisted it. This module is that
+ * missing half — run from the close's `close-validation` phase, ahead of the
+ * gate chain, so the refreshed row lands in the branch's own PR.
+ *
+ * Shape borrowed from {@link ../story-close/format-autofix.js#runScopedFormatAutofix}:
+ * scope to the branch's changed-file set, fold the writes into one dedicated
+ * commit ahead of the gates, log the paths touched, and inject every
+ * git / baseline / scoring collaborator so the unit tests never spawn git
+ * (`.agents/rules/test-seams.md`).
+ *
+ * Four constraints bind the design, and every one of them is a "must not":
+ *
+ *  1. **Only `improvements` are written.** A regression must still fail the
+ *     gate exactly as it does today. A write-back that could launder one
+ *     makes the baseline actively worse than leaving it stale, so a regressed
+ *     row is never in the written set — it is not filtered out downstream, it
+ *     never enters.
+ *  2. **`maintainability` only.** CRAP's drift identity is
+ *     `path::method@startLine`, which re-keys whenever anything above a
+ *     method moves, so the same treatment there is churn rather than signal.
+ *     That is exactly why the nightly watches maintainability alone.
+ *  3. **Changed files only — never a full-scope regeneration.** A full-scope
+ *     write at land time would absorb unrelated drift from other branches
+ *     into whichever PR happened to land next, and would fight the
+ *     row-identity merge driver that exists to keep concurrent refreshes
+ *     apart (Story #5215).
+ *  4. **Idempotent and silent.** No empty commit; a second close over the
+ *     same tree finds nothing left to improve and commits nothing.
+ *
+ * The authored commit carries the `baseline-refresh:` marker
+ * `phases/refresh-ack.js` recognises, so the refreshed rows are vouched for
+ * rather than read as fresh drift, and its subject is conventional so
+ * commitlint accepts it.
+ */
+
+import path from 'node:path';
+
+import {
+  compare as compareMaintainability,
+  projectRow as projectMaintainabilityRow,
+} from '../../baselines/kinds/maintainability.js';
+import {
+  _internals as baselineReaderInternals,
+  load as loadBaselineEnvelope,
+} from '../../baselines/reader.js';
+import {
+  refreshBaseline as defaultRefreshBaseline,
+  resolveDefaultScorer,
+} from '../../baselines/refresh-service.js';
+import { getQuality } from '../../config-resolver.js';
+import { gitSync as defaultGitSync } from '../../git-utils.js';
+import { Logger as DefaultLogger } from '../../Logger.js';
+import { currentBranch, listChangedFiles } from './format-autofix.js';
+
+const TAG = '[baseline-writeback]';
+
+/** The one kind this module touches. See constraint 2 in the preamble. */
+const KIND = 'maintainability';
+
+/**
+ * Absolute drift tolerance when the gate configures none. Mirrors
+ * `drift-detector.js`'s `KIND_SPECS.maintainability.defaultTolerance`, so the
+ * per-PR write-back and the nightly full-scope check agree on what counts as
+ * movement rather than float noise.
+ */
+const DEFAULT_TOLERANCE = 0.5;
+
+/** Files the maintainability scorer can measure at all. */
+const SCORABLE = /\.(?:m?[jt]sx?)$/i;
+
+/**
+ * Reasons reported before the step scored anything, so `ran: false` means
+ * exactly "a guard stopped this before any work happened" rather than the
+ * softer "nothing came of it". `no-scored-rows`, `no-improvements` and
+ * `unchanged` are deliberately absent: those are outcomes of a run.
+ */
+const GUARD_REASONS = new Set([
+  'gate-disabled',
+  'no-changed-files',
+  'wrong-branch',
+  'no-baseline',
+  'no-scorer',
+]);
+
+/**
+ * Resolve the gate's absolute tolerance. Anything below it is float noise the
+ * ratchet already refuses to red on, so writing it back would be churn — and
+ * churn on a file every concurrent branch also touches is the one cost this
+ * step must not add.
+ *
+ * @param {object|undefined} gate resolved `delivery.quality.gates.maintainability`
+ * @returns {number}
+ */
+function resolveTolerance(gate) {
+  const configured = gate?.tolerance;
+  if (configured?.kind === 'absolute') {
+    const value = Number(configured.value);
+    if (Number.isFinite(value)) return Math.abs(value);
+  }
+  return DEFAULT_TOLERANCE;
+}
+
+/**
+ * Read the maintainability gate block as DECLARED — `quality.gates[kind]`, not
+ * the sibling `quality[kind]` projection. The two differ in exactly the two
+ * fields this module reads: the projection drops `enabled` entirely and
+ * flattens `tolerance` to a bare number, so reading it would silently make the
+ * gate un-disablable and every configured tolerance unreadable. `evaluate.js`
+ * receives this same declared block as its `gateBlock`, which is what keeps
+ * the write-back's notion of "moved" identical to the gate's.
+ *
+ * Tolerates a resolver that throws (a malformed config under a tmp cwd). An
+ * unresolvable config reads as "framework defaults", which enable the gate —
+ * the same reading `projections/advisories.js#isEnabled` applies.
+ *
+ * @param {object|undefined} config
+ * @returns {object|undefined}
+ */
+function resolveGate(config) {
+  try {
+    return getQuality(config)?.gates?.[KIND];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Normalise scorer output into the on-disk row shape so scored rows and
+ * committed rows are directly comparable. `projectRow` is the same projection
+ * the writer applies, which is what makes the two sides comparable at all.
+ * A row the writer itself would refuse is dropped rather than compared.
+ *
+ * @param {Array<object>} rows
+ * @returns {Array<{ path: string, mi: number }>}
+ */
+function projectRows(rows) {
+  const out = [];
+  for (const row of rows ?? []) {
+    try {
+      const projected = projectMaintainabilityRow(row);
+      if (Number.isFinite(projected.mi)) out.push(projected);
+    } catch {
+      // Unprojectable row → not evidence of an improvement.
+    }
+  }
+  return out;
+}
+
+/**
+ * Select the rows this branch has genuinely improved.
+ *
+ * The base side is deliberately narrowed to the rows the head side actually
+ * scored. `compare()` classifies a base row with no head row through the
+ * kind's `removedRowPolicy`, which for maintainability pushes an
+ * **improvement** ("the file is gone, so its debt is gone too"). That policy
+ * is correct for a full-scope compare and catastrophic for a scoped one: every
+ * untouched file in the repo would arrive here as an improvement and be
+ * rewritten from a score nobody computed. Narrowing the base to the scored
+ * keys means every comparison has both sides, so the removed-row arm cannot
+ * fire at all — and the `head === null` guard below makes that structural
+ * rather than incidental.
+ *
+ * `additions` — a scored file with no committed row — is likewise excluded:
+ * constraint 1 admits only what the classifier calls an improvement, and a new
+ * file's row is the ordinary refresh path's business, not this step's.
+ *
+ * Pure.
+ *
+ * @param {{ scoredRows: Array<object>, baselineRows: Array<object>, tolerance: number }} opts
+ * @returns {Array<{ path: string, mi: number }>} the head rows to persist
+ */
+function selectImprovedRows({ scoredRows, baselineRows, tolerance }) {
+  const scoredPaths = new Set(scoredRows.map((row) => row.path));
+  const baseSubset = (baselineRows ?? []).filter((row) =>
+    scoredPaths.has(row?.path),
+  );
+  if (baseSubset.length === 0) return [];
+
+  const result = compareMaintainability(
+    { rows: scoredRows },
+    { rows: baseSubset },
+  );
+  const improved = [];
+  for (const entry of result?.improvements ?? []) {
+    const head = entry?.head;
+    const base = entry?.base;
+    if (!head || !base) continue;
+    if (head.mi - base.mi <= tolerance) continue;
+    improved.push(head);
+  }
+  return improved;
+}
+
+/**
+ * Render the commit body: one line per rewritten row, before → after. The body
+ * is the durable record of what the step touched — the `Logger` line scrolls
+ * out of a close transcript, this does not — and `check-baseline-drift.js`'s
+ * remedy text asks a `baseline-refresh:` commit to carry a non-empty body.
+ *
+ * @param {Array<{ path: string, mi: number }>} improved
+ * @param {Array<object>} baselineRows
+ * @returns {string}
+ */
+function buildCommitBody(improved, baselineRows) {
+  const priorByPath = new Map(
+    (baselineRows ?? []).map((row) => [row?.path, row?.mi]),
+  );
+  const lines = [
+    'Rows the branch improved on files it touched, written back so the',
+    'committed baseline stops falling behind the tree in the upward',
+    'direction. Scoped to the branch changed set; no regression is rewritten.',
+    '',
+  ];
+  for (const row of improved) {
+    const before = Number(priorByPath.get(row.path) ?? 0).toFixed(2);
+    lines.push(`- ${row.path}: ${before} -> ${row.mi.toFixed(2)}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build the commit subject. Conventional (`chore(baselines): …`) so commitlint
+ * accepts it, carrying the `baseline-refresh:` marker as a plain substring so
+ * `refresh-ack.js#resolveRefreshTrigger` recognises it, and fixed-length in
+ * everything but the Story id so it cannot drift past commitlint's 100-char
+ * subject cap.
+ *
+ * @param {number|string} storyId
+ * @returns {string}
+ */
+function buildCommitSubject(storyId) {
+  return `chore(baselines): baseline-refresh: improved maintainability rows (story #${storyId})`;
+}
+
+/**
+ * Stage the single baseline file and commit it. Hooks must run; never pass
+ * `--no-verify` (project policy).
+ *
+ * On a commit failure the written file is restored, because everything
+ * downstream — base-sync, the push, the gate chain's own reads — assumes the
+ * close left the worktree clean. A half-applied write-back that survives as an
+ * uncommitted edit would silently change what the gates score without ever
+ * reaching the PR.
+ *
+ * @param {{ cwd: string, git: Function, relPath: string, subject: string, body: string }} opts
+ * @returns {{ sha: string }}
+ */
+function commitBaseline({ cwd, git, relPath, subject, body }) {
+  git(['add', '--', relPath], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+  try {
+    git(['commit', '-m', subject, '-m', body], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    git(['checkout', '--', relPath], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    throw err;
+  }
+  const sha = git(['rev-parse', '--short', 'HEAD'], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return { sha: String(sha ?? '').trim() };
+}
+
+/**
+ * Everything that must hold before the step is allowed to score anything.
+ * Returns a skip reason, or `null` to proceed.
+ *
+ * The branch assertion runs here — before the write, not before the commit —
+ * so a mis-wired `worktreePath` can never leave a modified baseline in a tree
+ * whose history we then refuse to touch.
+ *
+ * @param {{ gate: object|undefined, workTree: string, storyBranch: string, git: Function, changed: string[] }} ctx
+ * @returns {string|null}
+ */
+function precheck({ gate, workTree, storyBranch, git, changed }) {
+  if (gate?.enabled === false) return 'gate-disabled';
+  if (changed.length === 0) return 'no-changed-files';
+  const onBranch = currentBranch(workTree, git);
+  if (onBranch !== storyBranch) return 'wrong-branch';
+  return null;
+}
+
+/**
+ * Persist improved maintainability rows for the files this branch changed, and
+ * fold them into one `baseline-refresh:` commit on the Story branch.
+ *
+ * Every no-op is reported by name rather than silently: `gate-disabled`,
+ * `no-changed-files`, `wrong-branch`, `no-baseline`, `no-scored-rows`,
+ * `no-improvements`, `unchanged`. The caller logs the reason and proceeds —
+ * this step is never allowed to fail a close, because `check-baselines` is
+ * still the gate and this is only the refresh half of the loop.
+ *
+ * @param {{
+ *   cwd: string,
+ *   worktreePath?: string,
+ *   storyId: number|string,
+ *   baseBranch: string,
+ *   storyBranch: string,
+ *   config?: object,
+ *   logger?: object,
+ *   gitSync?: (cwd: string, ...args: string[]) => string,
+ *   loadBaselineRows?: (opts: { cwd: string }) => Array<object>|null,
+ *   scoreFiles?: (files: string[], opts: object) => Promise<Array<object>>|Array<object>,
+ *   refreshBaseline?: typeof defaultRefreshBaseline,
+ *   resolveWritePath?: (opts: { cwd: string }) => string,
+ * }} opts
+ * @returns {Promise<{
+ *   ran: boolean,
+ *   committed: boolean,
+ *   sha?: string,
+ *   improvedPaths?: string[],
+ *   reason?: string,
+ * }>}
+ */
+export async function runBaselineUpwardWriteback({
+  cwd,
+  worktreePath,
+  storyId,
+  baseBranch,
+  storyBranch,
+  config,
+  logger = DefaultLogger,
+  gitSync = defaultGitSync,
+  loadBaselineRows = defaultLoadBaselineRows,
+  scoreFiles,
+  refreshBaseline = defaultRefreshBaseline,
+  resolveWritePath = defaultResolveWritePath,
+} = {}) {
+  if (!cwd) throw new Error('runBaselineUpwardWriteback: cwd is required');
+  if (!baseBranch)
+    throw new Error('runBaselineUpwardWriteback: baseBranch is required');
+  if (!storyBranch)
+    throw new Error('runBaselineUpwardWriteback: storyBranch is required');
+
+  const workTree = worktreePath || cwd;
+  // The two format-autofix helpers below take git as `(args, opts) => stdout`;
+  // `git-utils.gitSync` is `(cwd, ...args) => trimmed stdout` and throws on a
+  // non-zero exit. Adapt rather than reach for `node:child_process` directly —
+  // the shared surface owns the stdout ceiling, `shell: false` and error
+  // normalisation, and `tests/enforcement/child-process-imports.test.js`
+  // enforces that.
+  const git = (args, opts = {}) => gitSync(opts.cwd ?? workTree, ...args);
+  const gate = resolveGate(config);
+
+  const changed = listChangedFiles({
+    cwd: workTree,
+    baseBranch,
+    storyBranch,
+    git,
+  }).filter((file) => SCORABLE.test(file));
+
+  const blocked = precheck({ gate, workTree, storyBranch, git, changed });
+  if (blocked) return skip(logger, blocked);
+
+  const baselineRows = loadBaselineRows({ cwd: workTree });
+  if (!Array.isArray(baselineRows) || baselineRows.length === 0) {
+    return skip(logger, 'no-baseline');
+  }
+
+  const score = scoreFiles ?? resolveDefaultScorer(KIND, { cwd: workTree });
+  if (typeof score !== 'function') return skip(logger, 'no-scorer');
+  const scoredRows = projectRows(
+    await score(changed, { kind: KIND, fullScope: false, cwd: workTree }),
+  );
+  if (scoredRows.length === 0) return skip(logger, 'no-scored-rows');
+
+  const improved = selectImprovedRows({
+    scoredRows,
+    baselineRows,
+    tolerance: resolveTolerance(gate),
+  });
+  if (improved.length === 0) return skip(logger, 'no-improvements');
+
+  return await persist({
+    improved,
+    baselineRows,
+    workTree,
+    git,
+    storyId,
+    logger,
+    refreshBaseline,
+    resolveWritePath,
+  });
+}
+
+/**
+ * Write the selected rows through the one sanctioned write funnel and commit
+ * them. The already-computed rows are handed to `refreshBaseline` as its
+ * scorer so the files are scored exactly once — the service still owns path
+ * canonicalization, `mergeRows` (which preserves every out-of-scope row
+ * byte-for-byte), rollup, envelope stamping and the atomic write.
+ *
+ * @returns {Promise<{ ran: boolean, committed: boolean, sha?: string, improvedPaths?: string[], reason?: string }>}
+ */
+async function persist({
+  improved,
+  baselineRows,
+  workTree,
+  git,
+  storyId,
+  logger,
+  refreshBaseline,
+  resolveWritePath,
+}) {
+  const improvedPaths = improved.map((row) => row.path);
+  const writePath = resolveWritePath({ cwd: workTree });
+  const { wrote } = await refreshBaseline({
+    kind: KIND,
+    cwd: workTree,
+    writePath,
+    scopeFiles: improvedPaths,
+    scorer: () => improved,
+  });
+  // The writer short-circuits on structural equality, so `wrote: false` means
+  // the committed rows already carried these values — nothing to commit, and
+  // nothing worth a log line above debug.
+  if (!wrote) return skip(logger, 'unchanged');
+
+  const relPath = path.relative(workTree, writePath).split(path.sep).join('/');
+  const { sha } = commitBaseline({
+    cwd: workTree,
+    git,
+    relPath,
+    subject: buildCommitSubject(storyId),
+    body: buildCommitBody(improved, baselineRows),
+  });
+
+  logger.warn?.(
+    `${TAG} wrote back ${improvedPaths.length} improved ${KIND} row(s) ` +
+      `on story #${storyId}: ${improvedPaths.join(', ')}; committed as ${sha}.`,
+  );
+  return { ran: true, committed: true, sha, improvedPaths };
+}
+
+/**
+ * Report a no-op by name. Every skip is `info`-level: none of them is a
+ * problem, and the close transcript already carries one line per phase.
+ *
+ * @param {object} logger
+ * @param {string} reason
+ */
+function skip(logger, reason) {
+  logger.info?.(`${TAG} no write-back (${reason}).`);
+  return { ran: !GUARD_REASONS.has(reason), committed: false, reason };
+}
+
+/**
+ * Default committed-row loader — the schema-validating reader, so a baseline
+ * this module would refuse to compare against is reported as `no-baseline`
+ * rather than half-read.
+ */
+function defaultLoadBaselineRows({ cwd }) {
+  try {
+    return loadBaselineEnvelope(KIND, { cwd })?.rows ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Default on-disk location of the maintainability baseline. */
+function defaultResolveWritePath({ cwd }) {
+  return baselineReaderInternals.resolveBaselinePath(KIND, { cwd });
+}

package/.agents/scripts/lib/orchestration/story-close/format-autofix.js

@@ -333,10 +333,15 @@ export function runFormatAutofix({
  * `(args: string[], opts: object) => string`. A bridge adapter wraps it into
  * the `gitSpawn(cwd, ...args)` shape that `diffNameOnly` expects.
  *
+ * Exported since Story #5224: the sibling `baseline-upward-writeback.js` step
+ * scopes to the same branch changed-file set, and a second copy of this
+ * `(args, opts)` → `gitSpawn` bridge is exactly the kind of near-duplicate the
+ * duplication gate exists to refuse.
+ *
  * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: Function }} opts
  * @returns {string[]}
  */
-function listChangedFiles({ cwd, baseBranch, storyBranch, git }) {
+export function listChangedFiles({ cwd, baseBranch, storyBranch, git }) {
   // Bridge the (args, opts) → string interface into gitSpawn(cwd, ...args).
   const gitSpawn = (_cwd, ...args) => {
     try {

package/.agents/templates/docs/audit-sweep-runbook.md

@@ -145,10 +145,18 @@ Audit-sourced Stories carry a closed label set, so they can be filtered out of
 | Label | Meaning |
 | --- | --- |
 | `type::story` | Every emitted Story — the sweep never opens Epics or tasks. |
-| `agent::ready` | Filed and available for pickup. |
 | `audit::<lens>` | One per lens represented in the group; a cross-audit merge carries several. |
 | `risk::high` | Added when any finding in the group is Critical. |
 
+**There is no `agent::` state label in that set, and that is the point.** The
+sweep files a Story it has deliberately not made deliverable — Step 5 above is
+the reason. `agent::ready` is what `/mandrel-deliver` reads as "available for
+pickup", so a sweep that applied it would route unenriched audit prose straight
+into delivery, which is the outcome Step 5 tells you to avoid. The label is
+applied by `/mandrel-plan`, at the end of planning, once the finding is a
+scoped slice. If you file these Issues by hand, apply the emitted `labels[]`
+verbatim and do not top it up with a state.
+
 The lens labels are a **closed taxonomy**: only the canonical `audit::<lens>`
 names are valid, and the filer refuses to emit a label the repository has never
 created. Create them once with `audit-labels-bootstrap.js` before the first live

package/.agents/workflows/audit-to-stories.md

@@ -211,11 +211,17 @@ shared helper's `fingerprintFooter(sha)`
 Labels applied:
 
 - `type::story`
-- `agent::ready`
 - `audit::<dimension>` — one per dimension represented in the merge
   (cross-audit groups carry multiple).
 - `risk::high` — added when any finding in the group is Critical.
 
+**No `agent::` state label, deliberately.** The filer used to emit
+`agent::ready`, which is exactly what `/mandrel-deliver` reads as "available
+for pickup" — and these bodies are audit prose, not a delivery-ready Spec. A
+Story with no `agent::` label is a legal initial state; `/mandrel-plan` stamps
+`agent::ready` as its terminal flip once the finding has become a scoped
+capability slice. Do not re-add it here or apply it by hand at create time.
+
 ### Phase 5c — Wire the cohort's declared ordering (**required**)
 
 Creating the Issues is only the first pass. `groupFindings` detects `edges[]`

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

@@ -1,10 +1,9 @@
 ---
 description: >-
-  The deliver path's one bundled framework read. Carries what
-  every Story delivery always needs — dispatch decision, engine invariants,
-  the change-set/ceremony incantation, the acceptance-eval gate, the credited
-  full-suite run, and the terminal envelope contract — so the engine reads one
-  file instead of re-reading the helper/schema set each session.
+  The deliver path's one bundled framework read: dispatch decision, engine
+  invariants, the change-set/ceremony incantation, the acceptance-eval gate,
+  the credited full-suite run, and the terminal envelope contract — the
+  engine reads one file, not the helper/schema set, each session.
 ---
 
 # Deliver digest (read once per session)
@@ -23,9 +22,9 @@ Read `stories[].dispatchMode` from the `resolve-stories.js` envelope.
 `inline` names one indivisible resource — **the router's own session** — so one
 rule produces it:
 
-1. **Run topology.** A run resolving **one** Story is `inline`
-   whatever its shape — sub-agent isolation is load-bearing only against a
-   *concurrent* sibling racing the same checkout, and a one-Story run has none.
+1. **Run topology.** A run resolving **one** Story is `inline` whatever its
+   shape — sub-agent isolation only matters against a *concurrent* sibling
+   racing the same checkout, and a one-Story run has none.
 2. **Every other run is `subagent`.** A multi-Story run dispatches every Story
    as a sub-agent however trivial its shape. Shape still sets ceremony; the
    `route::lite` label is a human-visible hint, never the control signal.
@@ -67,8 +66,8 @@ node --input-type=module -e '
   const { level, classes } = deriveChangeLevel({ changedFiles: files });
   // resolveCeremonyForRisk({ derivedLevel, clusterIndex?, freshCriticSampleRate?,
   //   ceremonyProfile? }) -> { mode, reason, sampled, profile, verdictOwner }.
-  // derivedLevel is that level STRING. Handing it the object above matches no
-  // tier, so it routes to the null fail-safe: a fresh critic, silently.
+  // derivedLevel is that level STRING — the object above matches no tier and
+  // routes to the null fail-safe: a fresh critic, silently.
   const ceremony = resolveCeremonyForRisk({ derivedLevel: level, clusterIndex: 0 });
   console.log(JSON.stringify({ files, level, classes, ...ceremony }));
 '
@@ -96,11 +95,8 @@ every cluster's records into a single `criteria[]` in `acceptance[]` order, one
 per acceptance item, and score that once. A gate call per cluster spends a
 round *per cluster* and races the round ledger:
 
-```bash
-node <main-repo>/.agents/scripts/acceptance-eval.js \
-  --story <storyId> --verdict <merged-verdict-path> \
-  --expected-criteria <acceptance[] count>
-```
+`node <main-repo>/.agents/scripts/acceptance-eval.js --story <storyId>
+--verdict <merged-verdict-path> --expected-criteria <acceptance[] count>`
 
 Pass `--expected-criteria` — **without it the coverage assertion is inert**, so
 an unmerged cluster verdict scores a fraction of the criteria and still reports
@@ -115,20 +111,27 @@ Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
 **After the self-eval loop's last fix commit, immediately before the push** —
 the credit is keyed on the tree, so any later commit invalidates it. Redraft
 rounds run scoped tests; only this final run needs credit, and a bare
-`npm test` / `pnpm run test` deposits **none**, so close re-runs the identical
-suite. Shape it by the predicate `close-validation/gates.js` uses for its test
-gate:
+`npm test` / `pnpm run test` deposits **none**, so close re-runs it. Shape it
+by what `close-validation/gates.js` runs:
 
 ```bash
-# CRAP gate on (default) + a `test:coverage` script — writes the stamp the
-# close `coverage-capture` gate reads:
+# CRAP gate on (default) + a `test:coverage` script — writes close's stamp:
 node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>
-# otherwise — the record the close `test` gate reads. <workCwd> ABSOLUTE,
-# runner exactly `npm test`: both sides hash {cmd, args, cwd}.
+# otherwise — the record close's `test` gate reads; <workCwd> ABSOLUTE,
+# runner exactly `npm test` (both sides hash {cmd, args, cwd}):
 node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
   --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
 ```
 
+Dispatch it in the **background**: it outruns the host's synchronous Bash
+ceiling, and its completion re-invokes you. Never spawn a task to poll or
+`sleep`-loop against it ([`parallel-tooling.md`](parallel-tooling.md)
+Rule 2).
+
+Read the **output**, not the exit code: capture skips — no test run, no
+credit — when nothing changed under the CRAP `targetDirs`, so run the suite
+yourself before handing off.
+
 `verify[]` is scoped entries **plus** this one run: an entry that is itself a
 full-suite command is reported credited against the same stamp, never
 respawned.
@@ -162,7 +165,8 @@ restores live streaming.
 
 ## 7. When to leave this file
 
-- Unclear state / a re-run refusal → `deliver-recover.js --story <id>` (read-only).
-- Lease, sweep, worktree-scope detail → [`deliver-story-reference.md`](deliver-story-reference.md).
-- CI red after the PR opens → [`rules/ci-remediation.md`](../../rules/ci-remediation.md).
-- Sequencing, epilogue, checklist threading → [`deliver-reference.md`](deliver-reference.md).
+Unclear state / a re-run refusal → `deliver-recover.js --story <id>`
+(read-only). Lease, sweep, worktree scope; sequencing, epilogue, checklist
+threading → [`deliver-story-reference.md`](deliver-story-reference.md) and
+[`deliver-reference.md`](deliver-reference.md). CI red after the PR opens →
+[`rules/ci-remediation.md`](../../rules/ci-remediation.md).

package/.agents/workflows/helpers/parallel-tooling.md

@@ -47,6 +47,23 @@ the full duration and blocks every other parallel opportunity.
 - **Don't poll with `sleep`:** `Monitor` returns on each stdout line. Loop
   on `until <condition>; do sleep 2; done` only when no event stream is
   available — never as a substitute for the event channel.
+- **A hand-rolled waiter outlives the agent that spawned it.** Prefer the
+  completion notification: it is the signal, and needs no waiter at all. Two
+  measured failure shapes, both from one delivery run whose waiters were
+  still listed running nearly eight hours after their agent had finished and
+  its worktree had been deleted:
+  - An `until` guard that inverts to permanently-false the moment the run
+    **succeeds** — `until [ -n "$(grep -l 'Test Files' $LOG)" ] && ! grep -q
+    'Test Files' $LOG` exits only while the log both has and lacks the same
+    marker.
+  - `pgrep -f <literal>` matching the waiter's **own** command line, so it
+    finds itself and concludes the work is still running. Forever.
+
+  The tell is a task file of **0 bytes** with no backing process. If you must
+  wait, hold the PID and test `kill -0 "$PID"`, or break the self-match with
+  a bracketed pattern (`pgrep -f "[m]y-script.js"`) — and always bound the
+  loop with a maximum iteration count so a wrong condition ends the wait
+  instead of the agent.
 
 ## Rule 3 — N parallel `Agent` calls in one turn for N independent units
 

package/docs/CHANGELOG.md

@@ -15,6 +15,26 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.50.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.49.0...mandrel-v2.50.0) (2026-09-08)
+
+
+### Fixed
+
+* stop /audit-to-stories emitting agent::ready on generated audit Stories… ([#5229](https://github.com/dsj1984/mandrel/issues/5229)) ([#5230](https://github.com/dsj1984/mandrel/issues/5230)) ([d095608](https://github.com/dsj1984/mandrel/commit/d09560866c42084aed3fb92fb91d8c9a49fe66e3))
+
+## [2.49.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.48.0...mandrel-v2.49.0) (2026-09-08)
+
+
+### Added
+
+* give story-worker a reachable long-command dispatch contract so the credited suite run stops growing hand-rolled waiters ([#5219](https://github.com/dsj1984/mandrel/issues/5219)) ([#5220](https://github.com/dsj1984/mandrel/issues/5220)) ([e2bb9eb](https://github.com/dsj1984/mandrel/commit/e2bb9eba8aaaf49ecf0d8069f36fc4438edf5e40))
+* write improved maintainability rows back at land time so upward baseline drift stops accumulating ([#5224](https://github.com/dsj1984/mandrel/issues/5224)) ([#5227](https://github.com/dsj1984/mandrel/issues/5227)) ([95d2e38](https://github.com/dsj1984/mandrel/commit/95d2e38db7fe87c410dbb40d43818e31ee80a497))
+
+
+### Fixed
+
+* tell the worker what to do when the credited full-suite command legitimately skips ([#5225](https://github.com/dsj1984/mandrel/issues/5225)) ([#5226](https://github.com/dsj1984/mandrel/issues/5226)) ([330ecaf](https://github.com/dsj1984/mandrel/commit/330ecaf6001755a515c45f69a495310d8b65643a))
+
 ## [2.48.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.47.0...mandrel-v2.48.0) (2026-09-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.48.0",
+  "version": "2.50.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",