mandrel 2.67.0 → 2.68.0

package/.agents/scripts/story-review-compute.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+/**
+ * story-review-compute.js — compute the Story-scope review on the worker, at
+ * push time, and deposit it for close to adopt.
+ *
+ * Runs close's compute step (`computeStoryScopeReview` over the configured
+ * provider chain, posting nothing) against `origin/<base>...story-<id>` and
+ * writes one held-review JSON beside the terminal envelope, keyed on the diff
+ * digest. Close adopts it when the digest still matches, so the serialized
+ * close tail only posts; a CRITICAL surfaces here, where the worker can fix
+ * and re-push inside its own parallel loop.
+ *
+ * Posts nothing to GitHub and takes no full-suite lock. Exit 0 whatever the
+ * findings; 1 only on a usage error or a provider throw.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { getStoryBranch, gitSpawn } from './lib/git-utils.js';
+import { runCodeReview } from './lib/orchestration/code-review.js';
+import { resolveSharedBaseRef } from './lib/orchestration/review-base-ref.js';
+import {
+  buildReviewDeposit,
+  computeReviewDiffDigest,
+  resolveRefSha,
+  writeReviewDeposit,
+} from './lib/orchestration/review-deposit.js';
+import { computeStoryScopeReview } from './lib/orchestration/single-story-close/phases/code-review.js';
+
+const USAGE = {
+  invocation:
+    'node .agents/scripts/story-review-compute.js --story <id> [--cwd <workCwd>]',
+  summary:
+    'Compute the Story-scope code review of origin/<base>...story-<id> without posting it, and write the held result (keyed on the diff digest) for close to adopt. Exits 0 whatever the findings.',
+  flags: [
+    ['--story <id>', 'Story issue number; the head ref is story-<id>.'],
+    [
+      '--cwd <path>',
+      'Checkout to resolve the branch and diff in (default: the current directory).',
+    ],
+  ],
+};
+
+/**
+ * @param {string[]} argv
+ * @returns {{ storyId: number|null, cwd: string|null }}
+ */
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      story: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    strict: false,
+  });
+  const storyId = Number.parseInt(values.story ?? '', 10);
+  return {
+    storyId: Number.isInteger(storyId) && storyId > 0 ? storyId : null,
+    cwd: values.cwd ?? null,
+  };
+}
+
+/**
+ * @param {object} severity
+ * @returns {string}
+ */
+function formatTally(severity) {
+  const s = severity ?? {};
+  return `critical=${s.critical ?? 0} high=${s.high ?? 0} medium=${s.medium ?? 0} suggestion=${s.suggestion ?? 0}`;
+}
+
+/**
+ * @param {{ storyId: number, cwd: string, config: object }} input
+ * @param {{
+ *   gitSpawnFn?: typeof gitSpawn,
+ *   runCodeReviewFn?: typeof runCodeReview,
+ *   writeDepositFn?: typeof writeReviewDeposit,
+ *   progress?: (tag: string, msg: string) => void,
+ *   nowIso?: () => string,
+ * }} [deps]
+ * @returns {Promise<{ written: boolean, path?: string, reason?: string,
+ *   deposit?: object }>}
+ */
+export async function computeStoryReviewDeposit(
+  { storyId, cwd, config },
+  deps = {},
+) {
+  const {
+    gitSpawnFn = gitSpawn,
+    runCodeReviewFn = runCodeReview,
+    writeDepositFn = writeReviewDeposit,
+    progress = () => {},
+    nowIso = () => new Date().toISOString(),
+  } = deps;
+  const storyBranch = getStoryBranch(storyId);
+  const baseBranch = config?.project?.baseBranch ?? 'main';
+  const headSha = resolveRefSha({ cwd, ref: storyBranch, gitSpawnFn });
+  if (!headSha) {
+    return { written: false, reason: `could not resolve ${storyBranch}` };
+  }
+  const base = resolveSharedBaseRef({ baseBranch, cwd, gitSpawnFn });
+  const diffDigest = computeReviewDiffDigest({
+    cwd,
+    baseRef: base.resolved ? base.ref : null,
+    headRef: headSha,
+    gitSpawnFn,
+  });
+  if (!diffDigest) {
+    return {
+      written: false,
+      reason: `could not read the ${base.remoteRef ?? baseBranch}...${storyBranch} diff`,
+    };
+  }
+  const computed = await computeStoryScopeReview({
+    cwd,
+    storyId,
+    headRef: headSha,
+    baseBranch,
+    deferPost: true,
+    provider: null,
+    runCodeReviewFn,
+    gitSpawnFn,
+    progress,
+  });
+  if (!computed.result) {
+    return { written: false, reason: 'the review base is unresolvable' };
+  }
+  const deposit = buildReviewDeposit({
+    storyId,
+    headSha,
+    baseRef: base.ref,
+    diffDigest,
+    result: computed.result,
+    createdAt: nowIso(),
+  });
+  const path = writeDepositFn(deposit, { config });
+  return { written: true, path, deposit };
+}
+
+/**
+ * @param {string[]} [argv]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   stdout?: { write: (s: string) => void },
+ *   cwd?: string,
+ * } & Parameters<typeof computeStoryReviewDeposit>[1]} [deps]
+ * @returns {Promise<object>} the outcome
+ */
+export async function runStoryReviewComputeCli(
+  argv = process.argv.slice(2),
+  deps = {},
+) {
+  const {
+    resolveConfigImpl = resolveConfig,
+    stdout = process.stdout,
+    cwd: defaultCwd = process.cwd(),
+    ...computeDeps
+  } = deps;
+  const { storyId, cwd } = parseArgv(argv);
+  if (!storyId) {
+    throw new Error(
+      'story-review-compute: --story <id> is required (a positive integer).',
+    );
+  }
+  const workCwd = cwd ?? defaultCwd;
+  const config = resolveConfigImpl({ cwd: workCwd });
+  const progress =
+    computeDeps.progress ??
+    ((tag, msg) => stdout.write(`[story-review-compute] [${tag}] ${msg}\n`));
+  const outcome = await computeStoryReviewDeposit(
+    { storyId, cwd: workCwd, config },
+    { ...computeDeps, progress },
+  );
+  if (!outcome.written) {
+    stdout.write(
+      `[story-review-compute] ⏭ No held review written: ${outcome.reason}. Close computes the review itself.\n`,
+    );
+    return outcome;
+  }
+  const { deposit } = outcome;
+  stdout.write(
+    `[story-review-compute] ✅ Held review for Story #${storyId} written → ${outcome.path}\n` +
+      `[story-review-compute] diff ${deposit.diffDigest.slice(0, 12)} @ ${deposit.headSha.slice(0, 12)} · ${formatTally(deposit.severity)}\n`,
+  );
+  if (deposit.halted) {
+    stdout.write(
+      `[story-review-compute] ❌ CRITICAL: fix, commit and re-push before hand-off. Report:\n${deposit.report}\n`,
+    );
+  }
+  return outcome;
+}
+
+async function main() {
+  await runStoryReviewComputeCli();
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'story-review-compute',
+  propagateExitCode: true,
+  errorPrefix: '[story-review-compute] ❌ Fatal error',
+  usage: USAGE,
+});

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

@@ -7,6 +7,7 @@
 
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { resolveUpdaterRefreshScope } from './lib/baselines/coverage-refresh-scope.js';
 import {
   buildCoverageUpdaterScorer,
   resolveCoverageUpdaterScope,
@@ -40,6 +41,7 @@ const USAGE = {
   ],
   notes: [
     'Run `npm run test:coverage` first — this script never runs the suite itself.',
+    'Against an `affected`-stamped artifact only measured rows are rewritten; rows the scoped run skipped are kept.',
   ],
 };
 
@@ -75,16 +77,19 @@ function main() {
       score: scoreCoverageFinal,
     }),
   };
-  // No flag -> scopeFiles=null + fullScope=false -> the service derives the
-  // diff via `origin/main..HEAD` (its default baseRef/headRef).
-  if (fullScope) refreshOpts.fullScope = true;
-  else if (diffScopeRef) refreshOpts.baseRef = diffScopeRef;
-
-  return refreshBaseline(refreshOpts).then((result) => {
-    Logger.info(
-      `[Coverage] ✅ Baseline updated: ${result.envelope.rows.length} file(s) recorded at ${COVERAGE_BASELINE_PATH} (${absBaselinePath}). scope=${result.scope.mode}, wrote=${result.wrote}.`,
-    );
-  });
+  // No flag and a full artifact -> the service derives the diff via
+  // `origin/main..HEAD` (its default baseRef/headRef).
+  return resolveUpdaterRefreshScope(cwd, {
+    fullScope,
+    diffScopeRef,
+    loadScope: loadC8Scope,
+  })
+    .then((scope) => refreshBaseline({ ...refreshOpts, ...scope }))
+    .then((result) => {
+      Logger.info(
+        `[Coverage] ✅ Baseline updated: ${result.envelope.rows.length} file(s) recorded at ${COVERAGE_BASELINE_PATH} (${absBaselinePath}). scope=${result.scope.mode}, wrote=${result.wrote}.`,
+      );
+    });
 }
 
 runAsCli(import.meta.url, main, {

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

@@ -4,6 +4,7 @@ import {
   buildCrapUpdaterScorer,
   parseCrapUpdaterArgs,
   resolveCrapUpdaterOptions,
+  seatCrapBaseline,
 } from './lib/baselines/crap-updater-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
 import { runAsCli } from './lib/cli-utils.js';
@@ -31,7 +32,7 @@ import { Logger } from './lib/Logger.js';
 /** `runAsCli` answers `--help` before `main`, so a usage probe never writes. */
 const USAGE = {
   invocation:
-    'node .agents/scripts/update-crap-baseline.js [--baseline <path>] [--coverage <path>] [--full-scope | --diff-scope <ref>]',
+    'node .agents/scripts/update-crap-baseline.js [--baseline <path>] [--coverage <path>] [--full-scope | --diff-scope <ref>] [--seat-missing]',
   summary:
     'Scan → score → write the CRAP baseline. With no scope flag the refresh is scoped to the files changed in `origin/main..HEAD`; out-of-scope rows are preserved verbatim.',
   flags: [
@@ -51,6 +52,10 @@ const USAGE = {
       '--diff-scope <ref>',
       'Scope the refresh to files changed between <ref> and HEAD. Incompatible with --full-scope.',
     ],
+    [
+      '--seat-missing',
+      'Insert-only: write rows ONLY for methods of changed files (merge-base of `--diff-scope <ref>`, default `origin/<baseBranch>`) that have no baseline row; every existing row stays byte-identical. Refuses unless the coverage capture stamp is fresh and method resolution is 100%. Prints `seated: N`. Incompatible with --full-scope.',
+    ],
   ],
   notes: [
     'Run `npm run test:coverage` first — without a coverage artifact every file is skipped.',
@@ -91,7 +96,12 @@ async function main() {
   );
 }
 
-runAsCli(import.meta.url, main, {
+async function seat() {
+  process.exitCode = await seatCrapBaseline(process.argv.slice(2));
+}
+
+const seating = process.argv.includes('--seat-missing');
+runAsCli(import.meta.url, seating ? seat : main, {
   source: 'crap-baseline',
   usage: USAGE,
   onError: (err) => {

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

@@ -9,6 +9,7 @@ import './lib/runtime-deps/ensure-installed.js';
 import path from 'node:path';
 import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { seatMaintainabilityBaseline } from './lib/baselines/seat-missing.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
 import { getBaselines, resolveConfig } from './lib/config-resolver.js';
@@ -17,7 +18,7 @@ import { Logger } from './lib/Logger.js';
 /** `runAsCli` answers `--help` before `main`, so a usage probe never writes. */
 const USAGE = {
   invocation:
-    'node .agents/scripts/update-maintainability-baseline.js [--full-scope | --diff-scope <ref>]',
+    'node .agents/scripts/update-maintainability-baseline.js [--full-scope | --diff-scope <ref>] [--seat-missing]',
   summary:
     'Score → write the maintainability baseline. With no scope flag the refresh is scoped to the files changed in `origin/main..HEAD`; out-of-scope rows are preserved verbatim.',
   flags: [
@@ -29,6 +30,10 @@ const USAGE = {
       '--diff-scope <ref>',
       'Scope the refresh to files changed between <ref> and HEAD. Incompatible with --full-scope.',
     ],
+    [
+      '--seat-missing',
+      'Insert-only: write rows ONLY for changed files (merge-base of `--diff-scope <ref>`, default `origin/<baseBranch>`) that have no baseline row; every existing row stays byte-identical. Prints `seated: N`. Incompatible with --full-scope.',
+    ],
   ],
 };
 
@@ -89,7 +94,12 @@ async function main() {
   );
 }
 
-runAsCli(import.meta.url, main, {
+async function seat() {
+  process.exitCode = await seatMaintainabilityBaseline(process.argv.slice(2));
+}
+
+const seating = process.argv.includes('--seat-missing');
+runAsCli(import.meta.url, seating ? seat : main, {
   source: 'maintainability-baseline',
   usage: USAGE,
   onError: (err) => {

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

@@ -13,10 +13,12 @@ description: >-
 This helper performs a comprehensive code review of a change set before it
 is merged to `main`. The live v2 path is **Story scope only**:
 
-- **Story scope** — reviews `main...story-<storyId>` (or
-  `project.baseBranch...story-<storyId>`) inside `single-story-close.js`
-  after the PR opens and before auto-merge. Findings post to the PR;
-  critical findings block close (`agent::blocked`).
+- **Story scope** — reviews `origin/<baseBranch>...<sha>` inside
+  `single-story-close.js`, computed alongside the close-validation gates
+  once the pre-gate self-heal commits land (`<sha>` is that HEAD) and
+  posted after the PR opens, before auto-merge; a HEAD that moved by then
+  re-reviews serially. Findings post to the PR; critical findings block
+  close (`agent::blocked`).
 
 **Invariant — Story-scope review runs outside the maker's LLM context.**
 The Story-scope review executes inside the `single-story-close.js` close
@@ -24,7 +26,7 @@ subprocess, **not** in the delivering child's (maker agent's) LLM context.
 The close pipeline invokes it after the delivering child has exited, so
 the change set is reviewed by a process the maker cannot influence. The
 enforcing code path is
-[`runStoryScopeReview`](../../scripts/lib/orchestration/single-story-close/phases/code-review.js)
+[`computeStoryScopeReview`](../../scripts/lib/orchestration/single-story-close/phases/code-review.js)
 → shared
 [`runStoryReviewCore`](../../scripts/lib/orchestration/story-close/phases/review-core.js).
 A future refactor MUST preserve this isolation: do not move Story-scope

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

@@ -77,8 +77,6 @@ therefore buys a **deep review**, not a fresh acceptance critic.
 > [`acceptance-self-eval.md`](acceptance-self-eval.md) — a host that cannot
 > spawn the critic at all, noted in the friction comment if you block.
 
-`--base <ref>` overrides `project.baseBranch`.
-
 ## 4. Acceptance self-eval (Step 1a, required)
 
 **One verdict owner per Story** — named by `verdictOwner`: the inline
@@ -93,48 +91,55 @@ scored in **one** gate call. Bounded by `delivery.acceptanceEval.maxRounds`
 --verdict <verdict-path>`
 
 The gate reads the Story's `acceptance[]` count itself and rejects a verdict
-whose `criteria[]` length differs **before** scoring, consuming no round;
-`--expected-criteria` is accepted but redundant. A second gate call in the
-same round spends a round for nothing and races the Story-scoped ledger.
+whose `criteria[]` length differs **before** scoring, consuming no round. A
+second gate call in the same round spends a round for nothing and races the
+Story-scoped ledger.
 
 `proceed` → close. `redraft` → one more round inside the cap. `block` → **do
 not close**: post a `friction` comment and flip `agent::blocked`.
 Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
 
-## 5. The one credited suite run
+## 5. The one credited run
 
-After the self-eval loop's last fix commit, fetch and merge
-`origin/<baseBranch>` into the Story branch **first**, ahead of this run and
-the push: close's base-sync then no-ops, so neither stamp goes stale. Then
-run the suite **once** in the worktree through the depositor — it spawns the
-project's own `npm test`, whatever that resolves to, and stamps the result,
-so any runner earns the credit:
+**Preflight first — blocking.** After the self-eval loop, run the configured
+`project.commands.lint` and `node <main-repo>/.agents/scripts/quality-preview.js
+--changed-since origin/<baseBranch>` in the worktree; fix and commit every
+finding. Close's gates stay authoritative
+([`deliver-reference.md`](deliver-reference.md) § Preflight).
 
-```bash
-node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
-  --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
-```
-
-Green deposits the `test` evidence close reads, keyed on the tree, so close
-reports the gate as **credited** at unchanged HEAD — a later commit voids it.
-Read its **output**, not the exit code: `✓ test passed` is the signal. The
-CRAP gate still captures coverage itself when it needs an artifact.
-
-A bare `npm test` earns the same credit **only** where the project's test
-script routes through mandrel's own runner, which prints the outcome. On any
-other runner it deposits nothing and prints nothing, so silence is never
-evidence of credit; `mandrel doctor`'s `test-credit-path` check names which
-shape this project is. If the suite outruns the host's sync Bash ceiling,
-dispatch it in the **background** — its completion re-invokes you; never spawn
-a task to poll or `sleep`-loop against it
-([`parallel-tooling.md`](parallel-tooling.md) Rule 2). Redraft rounds run the
-scoped projects for the roots you changed plus `verify[]`, not the whole
-suite; only this run needs credit.
+After the last fix commit, fetch and merge
+`origin/<baseBranch>` into the Story branch **first**, ahead of this run and
+the push: close's base-sync then no-ops, so neither stamp goes stale. Then run
+**one** depositor in the worktree, picked by the predicate close registers
+`coverage-capture` on — CRAP gate enabled **and** a `test:coverage` script:
+
+- **Capture-active** →
+  `node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>`.
+  It takes the host full-suite lock, runs `test:coverage` and writes the stamp
+  close's capture finds fresh. Signal: `Wrote content-digest capture stamp`.
+  Non-zero is a red suite (or the lock / timeout it names): fix, re-run. No
+  second `npm test`.
+- **Otherwise** → `node <main-repo>/.agents/scripts/evidence-gate.js
+  --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test`.
+  Signal: `✓ test passed` — the `test` evidence close reads, keyed on the tree.
+
+**Seat, then push.** CRAP or MI gate on → run
+`update-crap-baseline.js --seat-missing` and its maintainability twin (signal
+`seated: N`); commit it as `chore(baselines): baseline-refresh: …`.
+
+A later commit voids either credit; a baseline-JSON seat keeps the stamp. Read
+the **output**, not the exit code: a run that prints no signal deposits
+nothing. `mandrel doctor`'s `test-credit-path` check names this project's
+depositor. Seat order, runner shapes, background dispatch, redraft rounds:
+[`deliver-reference.md`](deliver-reference.md) § Credited run.
 
 `verify[]` is scoped entries **plus** this one run: an entry that is itself a
 full-suite command is reported credited against the same record, never
 respawned.
 
+After the push, compute the held review and fix a CRITICAL before hand-off:
+[`deliver-reference.md`](deliver-reference.md) § Held review.
+
 ## 6. Terminal envelope — the return contract
 
 `single-story-close.js` emits exactly one envelope on stdout between
@@ -157,10 +162,8 @@ Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
 reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
 reported, never omitted, so a missing gate is never read as a passing one.
 
-**Gate output is captured, not streamed.** Close writes gate lines to
-`temp/orchestration/close-gates-<storyId>.log` and reports a one-line digest on
-success; a failed gate replays its tail inline. `AGENT_LOG_LEVEL=verbose`
-restores live streaming.
+Gate output is captured to a log, not streamed
+([`deliver-reference.md`](deliver-reference.md) § Gate output).
 
 ## 7. When to leave this file
 

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

@@ -326,11 +326,15 @@ diff selects **review depth**.
 
 ## Async merge-confirm mode (`delivery.mergeWatch.mode: "async"`)
 
-In async mode the close arms auto-merge, probes for ~60s (catching an instant
-merge or, via the head-anchored required-check predicate, an instantly-red
-required check) and then returns `pending` with a `nextCommand`, instead of
-holding the host tool slot for a merge that lands after the wait would have
-expired anyway. When a close returns that `pending` envelope, launch its
+In async mode the close arms auto-merge and probes the PR **once**. A
+definitive probe settles as in sync mode — merged lands, closed or a red
+required check (the head-anchored predicate) blocks, a red advisory gate
+blocks. A probe whose checks have not started or are still running returns
+`pending` with a `nextCommand` at once, no sleep: CI never reddens inside the
+first minute, so a second probe could only hold the serialized slot. Two
+shapes poll on inside the ~60s window: checks already **green** (the merge is
+imminent — observed at the green cadence, it saves a whole confirm
+invocation) and a red rollup still awaiting its confirming probe. When a close returns that `pending` envelope, launch its
 `nextCommand` (`single-story-confirm-merge.js … --wait`) as a **background**
 invocation (host background Bash — its completion re-invokes the agent) and
 move on to the next Story; `single-story-confirm-merge.js` is idempotent and
@@ -352,3 +356,109 @@ config default stays `"sync"`. A slow-CI solo consumer may opt into `"async"`
 for the same reason — a foreground wait longer than the host tool ceiling
 expires `pending` anyway. Otherwise a one-Story run keeps `sync`: there is no
 sibling to unblock, and the foreground wait is the cheapest path to `landed`.
+
+## Preflight (before close) {#preflight}
+
+Digest § 5 states the rule: before the credited suite run, the worker runs
+the configured `project.commands.lint` (falling back to `npm run lint`) and
+`quality-preview.js --changed-since origin/<baseBranch>` in the worktree, and
+fixes and commits every finding. It runs **before** the credited run because a
+fix commit afterwards would void that run's credit.
+
+- **Why.** Close runs lint and the maintainability half of the preview
+  (`quality-preview-mi`) in its parallel phase, but a regression found there
+  still costs a close round-trip. Seconds of preflight in the worktree is
+  cheaper than any close.
+- **The CRAP half never captures.** It scores whatever coverage artifact is
+  on disk — the worker's credited capture when one exists — and triggers no
+  capture of its own. With no artifact its methods report unscorable; a stale
+  one can invent a violation. `--only mi` runs the maintainability half alone.
+- **Close stays authoritative.** Its `quality-preview-crap` gate scores a
+  fresh capture after `coverage-capture`; a preflight pass never skips it.
+
+## Credited run (situational) {#credited-run}
+
+Digest § 5 states the rule and both invocations; this is what surrounds them.
+
+- **Why the capture.** On a capture-active project close registers
+  `coverage-capture` instead of the plain `test` gate, so an evidence-gate
+  `test` deposit buys nothing there: close logs `no credited capture stamp
+  covers this change set` and pays the whole suite on the serialized tail. The
+  worker's capture writes the content-digest stamp in the worktree, and
+  close's capture then exits on its freshness probe without spawning
+  `test:coverage`. A base-sync that merges a path under `crap.targetDirs`
+  spends the stamp, and close re-captures.
+- **Runner shapes.** A bare `npm test` earns the `test` credit **only** where
+  the project's test script routes through mandrel's own runner, which prints
+  the outcome. On any other runner it deposits nothing and prints nothing, so
+  silence is never evidence of credit.
+- **Background dispatch.** If the run outruns the host's sync Bash ceiling,
+  dispatch it in the **background** — its completion re-invokes you; never
+  spawn a task to poll or `sleep`-loop against it
+  ([`parallel-tooling.md`](parallel-tooling.md) Rule 2).
+- **Redraft rounds.** Run the scoped projects for the roots you changed plus
+  `verify[]`, not the whole suite; only the one run needs credit.
+- **Seating new methods (`--seat-missing`).** Close fails a Story whose own
+  new methods have no baseline row, so after the credited run and before the
+  push the worker runs, in `<workCwd>`, for each enabled gate:
+  `node .agents/scripts/update-crap-baseline.js --seat-missing` (CRAP) and
+  `node .agents/scripts/update-maintainability-baseline.js --seat-missing`
+  (MI). Each scores the files changed since the `origin/<baseBranch>`
+  merge-base and writes **only** rows whose (path, method) key is absent —
+  every existing row stays byte-identical, including rows whose scores moved
+  (re-scoring stays close's auto-refresh). It prints `seated: N`; `seated: 0`
+  writes nothing. Commit a change as `chore(baselines): baseline-refresh: …`.
+- **Seat refusals.** The CRAP seat exits non-zero and writes nothing unless
+  the coverage-capture stamp is fresh for the tree **and** method resolution
+  over the in-scope files is exactly 100% — a lower rate means the artifact's
+  coordinates predate the tree. The refusal names the rate, the unresolved
+  files and the fix: re-run the digest § 5 capture, then seat.
+- **Seat order vs credit.** The capture stamp digests scorable sources only,
+  so a baseline-JSON-only seat commit leaves it fresh and the capture credit
+  stands. The evidence-gate `test` credit is keyed on the tree, so on that
+  path seat first — MI is static and needs no coverage — then run the suite.
+
+## Held review at hand-off {#held-review}
+
+The one home of this rule; the digest and the worker contract point here.
+After the credited run **and** the push, the worker computes the Story-scope
+code review itself, before handing off:
+
+```bash
+node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd <workCwd>
+```
+
+- **What it does.** It runs close's own review computation (the configured
+  provider chain) against `origin/<baseBranch>...story-<id>`, posts nothing,
+  takes no full-suite lock, and writes
+  `temp/orchestration/story-review-<id>.json` beside the terminal envelope,
+  keyed on the **diff digest** (sha256 of the exact three-dot diff text). It
+  exits 0 whatever the findings; non-zero means the provider threw — report
+  it in the hand-off; close computes the review itself.
+- **A CRITICAL is the worker's to fix.** Fix, commit, re-run the credited
+  run (the fix commit voided its credit), push, and re-run the compute — the
+  acceptance loop's redraft discipline, bounded by
+  `delivery.acceptanceEval.maxRounds`. Still CRITICAL at the cap → take the
+  blocked path. Anything else goes in the hand-off as the severity tally.
+- **Close adopts, else computes.** When the deposit's digest equals the
+  digest of the diff at close's held-review start, close starts no review and
+  posts the deposit after PR-open. A clean base-sync merge moves HEAD without
+  changing the diff, so it keeps the deposit; a commit that changes the diff
+  does not, and close reviews as it would without one. The CRITICAL halt and
+  `--override-review-block` apply to an adopted result unchanged.
+
+## Gate output {#gate-output}
+
+Close writes gate lines to `temp/orchestration/close-gates-<storyId>.log` and
+reports a one-line digest on success; a failed gate replays its tail inline.
+`AGENT_LOG_LEVEL=verbose` restores live streaming. A gate exiting `75` (its
+full-suite lock wait expired) logs a deferred line and the close settles
+`pending`; one exiting `124` (the suite outran its timeout) logs a timeout
+line naming host contention — neither is reported as failing tests.
+
+Every full-suite run ends on `⏲ suite timings: lockWaitMs=… hostWaitMs=…
+testRunMs=…`, which close carries as the envelope's `suiteTimings`. The
+`coverage.timeoutMs` clock starts at spawn, never in the lock queue; a suite
+that writes `$MANDREL_SUITE_READY_FILE` when its tests start (after a
+consumer load gate) gets a fresh bound for them, so worst-case wall is lock
+wait + 2 × `timeoutMs`.

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

@@ -101,7 +101,8 @@ Step 2.5's credited suite run is the sole exception.
 
 After the self-eval loop's last fix commit, run the one credited suite run
 in the worktree — **digest § 5** is its only home and carries the
-invocation. Red → fix, commit, re-run.
+invocation. Red → fix, commit, re-run. Then, before the push, seat the
+baseline rows for methods the Story added (`--seat-missing`, digest § 5).
 
 Push `story-<storyId>` to `origin`, confirming the remote ref moved. Then
 (sub-agent dispatch only) return the hand-off — Story id, `workCwd`,

package/docs/CHANGELOG.md

@@ -15,6 +15,32 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.68.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.67.0...mandrel-v2.68.0) (2026-09-26)
+
+
+### Added
+
+* baselines: add an insert-only `--seat-missing` refresh and have the story-worker seat rows for methods its diff adds before push ([#5486](https://github.com/dsj1984/mandrel/issues/5486)) ([#5492](https://github.com/dsj1984/mandrel/issues/5492)) ([325d7bb](https://github.com/dsj1984/mandrel/commit/325d7bbbc0bb08bb6fe3f05287d959f2b42d4da2))
+* close-validation: fail cheap gates before coverage capture and report lock expiry / timeout honestly ([#5471](https://github.com/dsj1984/mandrel/issues/5471)) ([#5474](https://github.com/dsj1984/mandrel/issues/5474)) ([ece115d](https://github.com/dsj1984/mandrel/commit/ece115d7961566c21de45f79f44b3957389e7623))
+* coverage-capture: after a base-sync, re-measure only main's delta instead of re-running the whole suite ([#5487](https://github.com/dsj1984/mandrel/issues/5487)) ([#5496](https://github.com/dsj1984/mandrel/issues/5496)) ([03694a4](https://github.com/dsj1984/mandrel/commit/03694a4bfa970ba122c1f508a7ed4b1271ccb222))
+* coverage-capture: opt-in `affected` scope that runs a consumer-owned scoped coverage script ([#5472](https://github.com/dsj1984/mandrel/issues/5472)) ([#5483](https://github.com/dsj1984/mandrel/issues/5483)) ([50bf942](https://github.com/dsj1984/mandrel/commit/50bf9424d38e776270cfaf19935dd265bb950625))
+* coverage-capture: spend the suite timeout on tests, queue on the full-suite lock, and make the cap configurable ([#5485](https://github.com/dsj1984/mandrel/issues/5485)) ([#5493](https://github.com/dsj1984/mandrel/issues/5493)) ([6a5bc69](https://github.com/dsj1984/mandrel/commit/6a5bc6929138e70ca66a9aea0e4354dcf5319ed7))
+* deliver: compute the Story-scope review at worker push time, keyed on the diff digest, so close posts a held result and a CRITICAL is fixed before hand-off ([#5480](https://github.com/dsj1984/mandrel/issues/5480)) ([#5490](https://github.com/dsj1984/mandrel/issues/5490)) ([c43b6bf](https://github.com/dsj1984/mandrel/commit/c43b6bf3beca4aeb0dc6350f3fe1f5c9cdcda250))
+* deliver: make the worker's one credited run the coverage capture close will otherwise re-pay, and let doctor name the credit gaps ([#5477](https://github.com/dsj1984/mandrel/issues/5477)) ([#5482](https://github.com/dsj1984/mandrel/issues/5482)) ([67e8d06](https://github.com/dsj1984/mandrel/commit/67e8d0687a6254f8ff8ab9957867c69588642aad))
+* deliver: warn in the beat envelope when a Story's footprint overlaps another session's in-flight Story ([#5488](https://github.com/dsj1984/mandrel/issues/5488)) ([#5491](https://github.com/dsj1984/mandrel/issues/5491)) ([be68220](https://github.com/dsj1984/mandrel/commit/be682205dc5959e12819bd2f2463c352449acd09))
+
+
+### Fixed
+
+* close: in async merge-watch mode return `pending` after one probe instead of burning the 60s window ([#5479](https://github.com/dsj1984/mandrel/issues/5479)) ([#5484](https://github.com/dsj1984/mandrel/issues/5484)) ([440b8bf](https://github.com/dsj1984/mandrel/commit/440b8bf70ed53d973c635662a12791a1d9f51953))
+* **close:** bound the full-suite lock wait by the suite's kill bound (refs [#5478](https://github.com/dsj1984/mandrel/issues/5478)) ([#5481](https://github.com/dsj1984/mandrel/issues/5481)) ([c7b7719](https://github.com/dsj1984/mandrel/commit/c7b7719bf50f7bc557c1979505ebab6a6851345b))
+* coverage-capture: a red capture must never leave an artifact a later pr… ([#5494](https://github.com/dsj1984/mandrel/issues/5494)) ([#5495](https://github.com/dsj1984/mandrel/issues/5495)) ([fa72738](https://github.com/dsj1984/mandrel/commit/fa72738d486626e892b5fd89e0350f745d925cfc))
+
+
+### Performance
+
+* close: run the Story-scope code review concurrently with the validation gates ([#5473](https://github.com/dsj1984/mandrel/issues/5473)) ([#5476](https://github.com/dsj1984/mandrel/issues/5476)) ([e098205](https://github.com/dsj1984/mandrel/commit/e09820592d70ba600df288c4e4b5ae1abd5b9aa1))
+
 ## [2.67.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.66.0...mandrel-v2.67.0) (2026-09-26)