mandrel 2.66.0 → 2.68.0

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/{git-cleanup.md → clean-git.md}

@@ -5,9 +5,9 @@ description: >-
   `git stash` entries — each step gated by operator confirmation.
 ---
 
-# /git-cleanup [--fast-forward-main] [--prune-remotes] [--branches] [--stashes] [--execute] [--remote] [--yes] [--include-content-merged] [--drop-stashes <ref>] [--exclude <pattern>] [--json]
+# /clean-git [--fast-forward-main] [--prune-remotes] [--branches] [--stashes] [--execute] [--remote] [--yes] [--include-content-merged] [--drop-stashes <ref>] [--exclude <pattern>] [--json]
 
-`/git-cleanup` folds the four cleanup steps operators routinely run by hand
+`/clean-git` folds the four cleanup steps operators routinely run by hand
 after a busy session into a single pipeline with per-step confirmation. It is a
 **recovery tool**, not a routine chore: the delivering flows already reap their
 own merged refs and fast-forward the base branch (see
@@ -22,13 +22,13 @@ Reach for it when the automated hygiene left an unusual state behind.
 > skill citation.
 
 The enumeration + reap logic lives in
-[`git-cleanup.js`](../scripts/git-cleanup.js) — it computes the candidate list,
+[`clean-git.js`](../scripts/clean-git.js) — it computes the candidate list,
 the skip taxonomy, the detection signals, and the JSON envelope, and prints them
 itself. Without `--execute` the script is a **dry-run preview**; nothing is
 mutated. When no phase flag is passed, **all four phases run** sequentially; a
 phase flag narrows the run. A failure in one phase does not short-circuit the
 others — each runs and reports independently. The script documents its own
-flags: `node .agents/scripts/git-cleanup.js --help`.
+flags: `node .agents/scripts/clean-git.js --help`.
 
 ## Phases
 
@@ -65,24 +65,24 @@ merged-PR branch in scope unless `--exclude`d.
 
 ```bash
 # Preview all four phases (no mutation).
-node .agents/scripts/git-cleanup.js
+node .agents/scripts/clean-git.js
 
 # Run everything non-interactively, including origin refs. Branches detected
 # only by content-equivalence keep their origin ref — see the note below.
-node .agents/scripts/git-cleanup.js --execute --remote --yes
+node .agents/scripts/clean-git.js --execute --remote --yes
 
 # Same, but also delete the origin refs of content-merged branches. Nobody is
 # watching, so opting in is the whole confirmation this delete ever gets.
-node .agents/scripts/git-cleanup.js --execute --remote --yes \
+node .agents/scripts/clean-git.js --execute --remote --yes \
   --include-content-merged
 
 # Only fast-forward main.
-node .agents/scripts/git-cleanup.js --fast-forward-main --execute
+node .agents/scripts/clean-git.js --fast-forward-main --execute
 
 # Only sweep merged branches + their origin refs.
-node .agents/scripts/git-cleanup.js --branches --execute --remote
+node .agents/scripts/clean-git.js --branches --execute --remote
 
 # Drop specific stashes under --yes.
-node .agents/scripts/git-cleanup.js --stashes --execute --yes \
+node .agents/scripts/clean-git.js --stashes --execute --yes \
   --drop-stashes 'stash@{0}' --drop-stashes 'stash@{2}'
 ```

package/.agents/workflows/clean-temp.md

@@ -0,0 +1,67 @@
+---
+description: >-
+  Clear the temp-tree backlog the land-time purge cannot attribute: sort every
+  top-level entry under the project's tempRoot into framework, closed-issue,
+  aged and kept buckets, preview by default, and delete only confirmed buckets.
+---
+
+# /clean-temp [--execute] [--yes] [--json]
+
+The land-time and boot-time purges only reap what they can attribute: the
+framework's own temp layouts and `temp/scratch/`. Everything else an agent
+dropped at the temp root is reported and left alone, so a busy consumer's temp
+tree grows without bound. `/clean-temp` is the operator's catch-up for that
+backlog. It classifies and deletes through the same temp-retention engine the
+purges use — there is no second walker.
+
+The script documents its own flags:
+`node .agents/scripts/clean-temp.js --help`. Without `--execute` it is a
+**dry-run preview**; nothing is deleted.
+
+## Buckets
+
+Every top-level entry under tempRoot lands in exactly one:
+
+| Bucket | What it holds | Unattended (`--yes`) |
+| --- | --- | --- |
+| **framework** | A framework layout holding artifacts the auto-purge would take — Story-keyed on a closed Story, or past `staleDays`. | Deleted |
+| **closed-issue** | An unrecognized entry whose basename names exactly one issue id, and that issue reads `closed`. | Deleted |
+| **aged** | An unrecognized entry naming no id, or several, older than `staleDays`. | **Never** — an age heuristic has no attribution, so it needs a human |
+| **kept** | Everything else, with the reason: issue open, issue read failed, too recent, reserved, or nothing spent. | Kept |
+
+An id is a standalone run of up to seven digits in the basename. A basename
+naming two ids is never attributed to either — it is treated as id-less.
+
+## Constraint
+
+> [!WARNING] `--execute` deletes files. Interactive runs confirm each bucket;
+> `--yes` deletes the framework and closed-issue buckets only.
+
+- Reads fail safe: an open issue, or one whose read fails, keeps its entry.
+- `qa/`, `cache/`, `*.lock` and `signals.ndjson` at any depth are never
+  deleted.
+- Project-scoped: the script exits 1 without deleting anything when the
+  resolved tempRoot is not inside the project root it was invoked from. It
+  never touches `$TMPDIR` or a sibling checkout.
+
+## Steps
+
+1. Preview and read the table (bucket, entry, size, age, reason):
+
+   ```bash
+   node .agents/scripts/clean-temp.js
+   ```
+
+2. Delete, confirming each bucket:
+
+   ```bash
+   node .agents/scripts/clean-temp.js --execute
+   ```
+
+   Unattended, `--execute --yes` deletes the framework and closed-issue buckets
+   and reports the aged bucket as left for a human. `--json` emits the envelope
+   (per-bucket totals and `bytesReclaimed`) instead of the table.
+
+Going forward, put ad-hoc scratch under `temp/scratch/story-<id>/` (or
+`temp/scratch/` with no Story): a Story's landing reaps its scratch directory,
+and the boot sweep age-floors the rest.

package/.agents/workflows/clean-worktrees.md

@@ -0,0 +1,63 @@
+---
+description: >-
+  Reclaim disk from dead worktrees: list every worktree of this project as a
+  removal candidate (closed Story, merged branch, orphaned directory, detached
+  HEAD) or as kept with a reason, then remove candidates only on `--execute`.
+---
+
+# /clean-worktrees [--execute] [--yes] [--json]
+
+Every Story worktree carries its own `node_modules`, so a worktree left behind
+costs gigabytes. Workflow boot already removes `.worktrees/story-<id>` trees
+whose Story is closed or `agent::done` (the boot sweep in
+[`boot-sweep.js`](../scripts/boot-sweep.js)); `/clean-worktrees` is the
+**recovery tool** for everything that sweep does not own — the backlog, trees
+on non-Story branches, directories git no longer registers, and detached
+trees such as the Claude Code app's `.claude/worktrees/*`.
+
+The enumeration, classification and removal live in
+[`clean-worktrees.js`](../scripts/clean-worktrees.js), which documents its own
+flags: `node .agents/scripts/clean-worktrees.js --help`.
+
+## Steps
+
+1. **Preview.** Run `node .agents/scripts/clean-worktrees.js` (dry-run, the
+   default). It prints one row per worktree — class, path, size, branch/HEAD,
+   action — and removes nothing. Show the operator the table.
+2. **Confirm.** Ask the operator which candidates to remove. Do not proceed
+   on your own judgment.
+3. **Remove.** Re-run with `--execute`. In a terminal it asks per entry;
+   `--execute --yes` removes every non-`detached` candidate without asking.
+   `--json` emits the envelope, including `bytesReclaimed`.
+
+## Classes
+
+| Class | Candidate when |
+| --- | --- |
+| `closed-story` | `.worktrees/story-<id>` on `story-<id>` whose Story is closed or `agent::done`. |
+| `merged-branch` | Any other branch whose PR is MERGED and whose HEAD is the merged head. |
+| `orphan-dir` | A directory under `.worktrees/` that `git worktree list` does not register. |
+| `detached` | A registered worktree with a detached HEAD. |
+
+Everything else is **kept** with its reason: the main checkout, an open Story,
+an unmerged branch, a dirty tree, unpushed commits, a tree in use.
+
+## Constraint
+
+> [!WARNING] `--execute` deletes worktree directories. Without it the script
+> only previews.
+
+- **Project-scoped.** Only worktrees inside the invoking checkout's project
+  root are candidates; one registered elsewhere is reported, never removed.
+- **Unique work survives.** A dirty tree, or a HEAD no remote-tracking ref
+  contains, is never removed.
+- **Live trees survive.** The tree this process runs from is never removed;
+  on macOS and Linux a tree any live process uses is refused outright.
+- **`detached` needs a person.** A detached tree carries no Story label and a
+  live session may own it (a blanket prune once destroyed a live delivery's
+  worktree), so it is removed only on a per-entry interactive yes — never
+  under `--yes`.
+- **Removal goes through the worktree removal seam** (Windows lock retry and
+  the pending-cleanup hand-off), never raw deletion.
+- **Branches are untouched.** Deleting local or remote branches is
+  [`/clean-git`](clean-git.md)'s job.

package/.agents/workflows/git-deliver.md

@@ -77,7 +77,7 @@ node .agents/scripts/boot-sweep.js \
   --current "$(git rev-parse --abbrev-ref HEAD)"
 ```
 
-The safe subset of the `/git-cleanup` phases: fast-forwards the base branch,
+The safe subset of the `/clean-git` phases: fast-forwards the base branch,
 prunes stale remote-tracking refs, and reaps merged branches. It never
 touches the stash, never reaps a candidate with unpushed work / dirty
 worktree / open parent ticket, and always exits `0` — a failed sweep is

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -95,7 +95,7 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      without being respawned; a stale or absent stamp reports `spawn: true` and
      the command runs for real. The credited run itself is stated once, in
      [`deliver-digest.md`](deliver-digest.md) § 5.
-   + Emits **one** verdict file under `temp/` conforming to
+   + Emits **one** verdict file under `temp/scratch/story-<id>/` conforming to
      [`acceptance-eval-verdict.schema.json`](../../schemas/acceptance-eval-verdict.schema.json):
      one `{ index, criterion, verdict: met|partial|unmet, evidence,
      verifyEvidence[] }` record per `acceptance[]` item, in acceptance-array
@@ -137,4 +137,5 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      (transition to `agent::blocked`) and post a `friction` comment naming the
      unmet criteria and their evidence. Never silently proceed to close.
 
-Write the verdict under `temp/` only — it is a scratch artifact.
+Write the verdict under `temp/scratch/story-<id>/` only — a scratch artifact
+the Story's landing reaps.

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-reference.md

@@ -48,7 +48,7 @@ presence, so re-running init on a partially-initialized Story is idempotent.
 ### Merged-`story-*` sweep
 
 Between the fetch and the branch seed, init runs the same primitive as
-`<agentRoot>/scripts/git-cleanup.js` scoped to `story-*` in
+`<agentRoot>/scripts/clean-git.js` scoped to `story-*` in
 `--execute --remote` mode, excluding this run's `story-<id>`, reaping merged
 siblings' local refs, `origin/` refs and stale tracking refs in one pass.
 
@@ -539,7 +539,7 @@ once per project to delete the conflicting bot workflows entirely.
 > cause), or after a manual merge on a `--no-wait-merge` run:
 
 ```bash
-node .agents/scripts/git-cleanup.js \
+node .agents/scripts/clean-git.js \
   --execute \
   --remote \
   --yes \