mandrel 2.41.0 → 2.42.0

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

@@ -233,17 +233,19 @@ runs maker-blind at Story-scope review inside the close subprocess. The
 dispatch step produces `checklistPath` from the Story's predicted footprint
 before it spawns the worker — see [`/mandrel-deliver`](../mandrel-deliver.md).
 
-**Pre-eval full-suite discipline (spine step 1.3).** Repo-invariant guards —
+**Full-suite discipline (spine Step 2.5).** Repo-invariant guards —
 drift-guard and schema tests living outside the Story's scoped greps — are
 the failure class that actually bounces deliveries: close-validation
 discovers them only after the whole close pipeline has run, at several times
-the cost of one pre-eval full-suite run.
+the cost of one full-suite run in the worktree.
 
-**Run it so close can credit it.** Close skips a gate that already passed at
-the current HEAD, but a bare `npm test` deposits no such record — the suite
-then runs twice per delivery, once here and once in the close gate chain.
-Pick the invocation by the same predicate `close-validation/gates.js` uses to
-choose its test gate:
+**Run it once, last, so close can credit it.** The run belongs **after** the
+self-eval loop's last fix commit and immediately **before** the hand-off push,
+so its stamp describes the tree that is pushed; redraft rounds run scoped
+tests. Close skips a gate that already passed at the current HEAD, but a bare
+`npm test` deposits no such record — the suite then runs twice per delivery,
+once here and once in the close gate chain. Pick the invocation by the same
+predicate `close-validation/gates.js` uses to choose its test gate:
 
 ```bash
 # CRAP gate enabled (default) + a `test:coverage` script — writes the stamp
@@ -259,7 +261,15 @@ node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
 The credit expires the moment it stops describing the tree: evidence is keyed
 on HEAD, the capture stamp on a content digest of `crap.targetDirs`. A
 self-eval fix — or any commit — invalidates it and close re-runs the suite for
-real, so this never trades away the gate.
+real, so this never trades away the gate. That keying is exactly why the run
+comes last.
+
+**`verify[]` reuses the same stamp.** A `verify[]` entry that is itself a
+full-suite command is reported **credited** against that stamp rather than
+respawned (`resolveVerifyCredit` in
+[`verify-credit.js`](../../scripts/lib/orchestration/verify-credit.js)), and the
+self-eval gate warns when it sees one: the intended shape is scoped `verify[]`
+entries **plus** the single credited run.
 
 **Conflict with `main` mid-implementation** → resolve as you would any branch
 rebase. There is no `epic/<id>` intermediate, so the rebase base is `main`
@@ -500,22 +510,16 @@ judgment that help text cannot carry.
 
 The `single-story-close.js` script, in order:
 
-1. Runs the close-validation gates against `baseBranch` as the baseline.
-   On any gate failure it throws — the operator fixes and re-runs close.
-   **Gate output is captured, not streamed.** Every gate line
-   goes to `temp/orchestration/close-gates-<storyId>.log`; a clean run reports
-   one digest line naming that artifact, and a **failed** gate replays its
-   captured tail inline so the evidence is in front of you without opening a
-   file. Read the artifact when you need the full text — or re-run under
-   `AGENT_LOG_LEVEL=verbose` for live streaming.
-   1a. **Syncs the Story branch from `origin/<baseBranch>`** before push.
-   Runs `git fetch origin <baseBranch>` followed by
-   `git merge --no-edit origin/<baseBranch>` inside the worktree. This
+1. **Syncs the Story branch from `origin/<baseBranch>`** — before the gates,
+   not after them. Runs `git fetch origin <baseBranch>` followed
+   by `git merge --no-edit origin/<baseBranch>` inside the worktree. This
    defends against the parallel-`/deliver-story` race: when
    multiple sessions run in parallel, the Story that auto-merges first
    bumps `baseBranch`, and without this sync the lagging Stories open
    PRs that are "behind base" and stall against branch-protection's
-   `up-to-date branch` rule. Outcomes:
+   `up-to-date branch` rule. Running it first also means a conflict costs
+   no gate run at all, and — the load-bearing half — the tree the gates
+   validate is the tree the push sends. Outcomes:
    - **No-op / fast-forward / clean merge-commit** → close proceeds to
      push.
    - **Merge conflict** → the merge is aborted, a `friction` structured
@@ -533,12 +537,26 @@ The `single-story-close.js` script, in order:
    closes the PR-open-time race but a residual race remains between PR
    open and auto-merge fire.
 
-2. Pushes `story-<id>` to `origin`.
-3. Probes for an existing open PR with `head = story-<id>`. If none
+2. Runs the close-validation gates against `baseBranch` as the baseline.
+   On any gate failure it throws — the operator fixes and re-runs close.
+   The chain fails cheapest-first: `typecheck`, `lint`, `format` and the
+   coverage-independent half of the baselines gate
+   (`check-baselines-independent`) run in parallel, and only once they are
+   green does the serial walk pay for `coverage-capture` and the
+   coverage-consuming half (`check-baselines-coverage`).
+   **Gate output is captured, not streamed.** Every gate line
+   goes to `temp/orchestration/close-gates-<storyId>.log`; a clean run reports
+   one digest line naming that artifact, and a **failed** gate replays its
+   captured tail inline so the evidence is in front of you without opening a
+   file. Read the artifact when you need the full text — or re-run under
+   `AGENT_LOG_LEVEL=verbose` for live streaming.
+
+3. Pushes `story-<id>` to `origin`.
+4. Probes for an existing open PR with `head = story-<id>`. If none
    exists, opens one via `gh pr create --base <baseBranch>`. The PR
    body carries `Closes #<storyId>` so the GitHub merge auto-closes the
    issue.
-   3a. **Enables GitHub native auto-merge by default** via
+   4a. **Enables GitHub native auto-merge by default** via
    `gh pr merge <prNumber> --auto --squash --delete-branch`. Once CI's
    required checks turn green, GitHub squash-merges the PR and deletes
    the source branch — the operator does not need to babysit the merge
@@ -546,7 +564,7 @@ The `single-story-close.js` script, in order:
    non-fatal: the operator retains the manual merge surface in the
    GitHub UI. Pass `--no-auto-merge` to opt out when the PR needs a
    pre-merge eyeball.
-4. Flips the Story to **`agent::closing`** (NOT `agent::done`) and leaves
+5. Flips the Story to **`agent::closing`** (NOT `agent::done`) and leaves
    the GitHub issue **OPEN**. Auto-merge completes
    asynchronously _after_ this script exits, so closing the issue here
    would strand a CLOSED issue with no merged work if the PR later failed
@@ -557,9 +575,9 @@ The `single-story-close.js` script, in order:
    `--no-wait-merge` run, or the in-close confirm phase on the
    close-and-land default. (Step 5.5 is the Status-column resync.) A Story
    only reaches `agent::done` once its PR to `main` is confirmed merged.
-5. Reaps the worktree when `delivery.worktreeIsolation.reapOnSuccess`
+6. Reaps the worktree when `delivery.worktreeIsolation.reapOnSuccess`
    is enabled.
-6. **Releases the Story lease.** Clears the Story assignment
+7. **Releases the Story lease.** Clears the Story assignment
    that init claimed so the next `/deliver-story` run sees an
    unclaimed ticket. The release is a no-op when the operator no longer
    holds the claim (a later run took over via reclaim/steal), so a late
@@ -572,13 +590,15 @@ The `single-story-close.js` script, in order:
    de-assigning the ticket. The close result carries
    `leaseReleased: <boolean>`.
 
-`--skip-validation` bypasses Step 1 (gates). Use only when re-running
+`--skip-validation` bypasses the gate step. Use only when re-running
 close after a fixed gate failure that's already known to pass.
 
-`--skip-sync` bypasses Step 1a (base-sync). Use only when re-running
-close after a hand-resolved sync, or in tests.
+`--skip-sync` bypasses the base-sync step. Use only when re-running
+close after a hand-resolved sync, or in tests. The two flags are
+independent: either, both or neither may be set, and each elides exactly
+its own phase.
 
-`--no-auto-merge` disables Step 3a. Use when the PR materially changes
+`--no-auto-merge` disables the auto-merge arm (step 4a). Use when the PR materially changes
 behaviour and warrants pre-merge review.
 
 ---

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

@@ -40,7 +40,7 @@ that dispatched the work**, never to a spawned worker.
 
 **A worker returning no terminal envelope is expected, not a failure** — only
 Step 3 mints one. Never re-dispatch the Story on it; resume per § Recovery
-(reference § Idempotence and the standing constraints).
+(reference § Idempotence).
 
 ## Step 0 — Initialize (`single-story-init.js`)
 
@@ -73,12 +73,8 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
    digest-first; read a caller-provided `checklistPath` first, and walk any
    `## Slicing` rows as **intra-session checkpoints** (reference § Step 1).
 2. Implement and commit on the Story branch, iterating with quick advisory
-   gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3.
-3. Run the full suite once in the worktree **before Step 1a**: repo-invariant
-   guards outside the Story's scoped greps are the failure class that bounces
-   deliveries. Fix and commit first, then run the self-eval loop. Run it **so
-   Step 3 credits it** — a bare `npm test` records nothing, so close re-runs
-   the identical suite (reference § Step 1, "Pre-eval full-suite discipline").
+   gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3,
+   and the **one** creditable full-suite run at Step 2.5.
 
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 
@@ -94,14 +90,21 @@ Ceremony is `delivery.routing.ceremonyProfile` × the **derived change level**,
 never a planner-authored verdict. **Digest § 3** is the incantation (change set
 once, derive the level, resolve critics with `ceremony-routing.js`); edge cases
 are reference § Step 2. Hard gates always run in Step 3 — the derived level
-never disables them; do **not** pre-run the chain here.
+never disables them; do **not** pre-run the chain here — Step 2.5's credited
+suite run is the sole exception.
 
-### Step 2.5 — Push and hand off (sub-agent dispatch only)
+### Step 2.5 — The creditable full-suite run, then push and hand off
 
-Push `story-<storyId>` to `origin` and confirm the remote ref moved. Return the
-hand-off — Story id, `workCwd`, branch, pushed head SHA, self-eval verdict,
-`verify[]` evidence — then stop. Do not open the PR; do not compose a terminal
-envelope. An inline run skips this.
+Run the full suite **once**, after the self-eval loop's last fix commit and
+immediately **before** the push, in the shape close credits (**digest § 5**):
+the credit is keyed on the tree, so any later commit invalidates it, and a bare
+`npm test` deposits none. Red → fix, commit, re-run. An inline run makes the
+same run before Step 3.
+
+Then (sub-agent dispatch only) push `story-<storyId>` to `origin`, confirm the
+remote ref moved, and return the hand-off — Story id, `workCwd`, branch, pushed
+head SHA, self-eval verdict, `verify[]` evidence — then stop. Do not open the
+PR; do not compose a terminal envelope.
 
 ## Step 3 — Close and land (`single-story-close.js`)
 
@@ -115,7 +118,7 @@ node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <
 **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
 post-land tail in one process. Never background it, never delegate it to a
 child, and never end your turn while it is still running: "close is running"
-is not a return value. Branch on the envelope's `status` per **digest § 5**
+is not a return value. Branch on the envelope's `status` per **digest § 6**
 (`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
 → Step 4; `failed` → diagnose, re-run). Gate output is captured.
 
@@ -126,7 +129,7 @@ Internals, merge-wait budgets, the slow-CI **async** confirm mode, the
 
 Relay the validated envelope close emits between its
 `--- STORY DELIVER TERMINAL ---` markers — never free-form prose, never a
-hand-composed object. Statuses, exits and fields: **digest § 5** (SSOT: the
+hand-composed object. Statuses, exits and fields: **digest § 6** (SSOT: the
 shipped [schema](../../schemas/story-deliver-terminal.schema.json)).
 `pending` is the only sanctioned no-merge ending.
 
@@ -139,15 +142,14 @@ so only a green on a NEW head SHA re-arms it — a re-run is refused; fix at sou
 and push ([`rules/ci-remediation.md`](../../rules/ci-remediation.md)). And a
 `tail.*: false` degrades the report, never the land.
 
-**Watch exit codes** — `pr-watch-with-update.js` exits 0 green, 1 only when a
-required check genuinely failed (or the PR is unreadable), 2 slow-but-not-red:
-still-running, unresolved, **or** `notYetStarted` — no required context attached
-inside `attachWindowMs`. Never route a 2 onto the red path; nothing is broken
-and no digest exists to read.
+**Watch exit codes** — `pr-watch-with-update.js` exits 0 green, 1 on a genuine
+red, 2 slow-but-not-red (still-running, unresolved, or `notYetStarted`). Never
+route a 2 onto the red path: nothing is broken and no digest exists to read.
+Which slow condition, and what to do: reference § Step 4.
 
 **Lost envelope first: read it off disk.** Close persists each to
 `temp/orchestration/story-deliver-terminal-<storyId>.json`; branch on it per
-digest § 5. Otherwise do not guess — probe **read-only** with
+digest § 6. Otherwise do not guess — probe **read-only** with
 `node .agents/scripts/deliver-recover.js --story <storyId>`; it prints the
 **one** next command with its evidence, never a menu. A live close answers
 `close-in-flight`: wait, never re-init underneath it.

package/docs/CHANGELOG.md

@@ -15,6 +15,24 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.42.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.41.0...mandrel-v2.42.0) (2026-09-06)
+
+
+### Added
+
+* full-suite capture economy: default the coverage-independent skip on, and serialize concurrent captures behind a host lock ([#5173](https://github.com/dsj1984/mandrel/issues/5173)) ([#5178](https://github.com/dsj1984/mandrel/issues/5178)) ([ed79751](https://github.com/dsj1984/mandrel/commit/ed7975199b6e2a3279a5d0d02b50e3068509987f))
+* story-worker digest carries the creditable full-suite invocation, runs it after self-eval, and the critic reuses its stamp ([#5174](https://github.com/dsj1984/mandrel/issues/5174)) ([#5175](https://github.com/dsj1984/mandrel/issues/5175)) ([1e46457](https://github.com/dsj1984/mandrel/commit/1e464574aa6305dcc8f1ff8522015ae0f9a5301a))
+
+
+### Fixed
+
+* scope the baseline refresh acknowledgment to the rows the refresh commit actually refreshed ([#5179](https://github.com/dsj1984/mandrel/issues/5179)) ([#5180](https://github.com/dsj1984/mandrel/issues/5180)) ([e8758b9](https://github.com/dsj1984/mandrel/commit/e8758b909ec19ed55c0678c05f481d515937f978))
+
+
+### Changed
+
+* close fails fast: base-sync before validation, and coverage-independent baseline kinds in the parallel gate phase ([#5172](https://github.com/dsj1984/mandrel/issues/5172)) ([#5177](https://github.com/dsj1984/mandrel/issues/5177)) ([dff33d5](https://github.com/dsj1984/mandrel/commit/dff33d530965ef7da8ee3dd4f1f218d11805273f))
+
 ## [2.41.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.40.0...mandrel-v2.41.0) (2026-09-06)
 
 

package/package.json

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