mandrel 1.84.0 → 1.86.0

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

@@ -70,6 +70,33 @@ it is about to run** before it acts.
 
 ---
 
+## Boot sweep
+
+Before detecting the git setup, run the **protected boot sweep** so
+`/git-deliver` starts from a tidy local checkout — a feature branch this
+command opened and pushed on a prior run, once its PR has merged, is reaped
+here rather than left to accumulate:
+
+```bash
+node .agents/scripts/boot-sweep.js \
+  --include 'feat/*' --include 'fix/*' --include 'chore/*' \
+  --include 'docs/*' --include 'refactor/*' \
+  --current "$(git rev-parse --abbrev-ref HEAD)"
+```
+
+This is the **safe subset** of the `/git-cleanup` phases: it fast-forwards the
+base branch (`main`), prunes stale remote-tracking refs, and reaps every local
+branch whose PR is **merged** and whose HEAD matches the merged `headRefOid`.
+It **never** touches the stash stack, and its `evaluateProtection` partition
+skips (never reaps) any candidate with unpushed work, a dirty worktree, or a
+still-open parent ticket; `--current` always excludes the branch you are on.
+The sweep is **silent on a no-op** — nothing merged, `main` already current →
+one summary line (`[boot-sweep] reaped 0 local + 0 remote; protected 0.`). Its
+exit code is always `0`; a failed sweep is reported in that summary, never
+allowed to fail the delivery run.
+
+---
+
 ## Step 0 — Detect Git Setup & Resolve Level
 
 1. Resolve `[BASE_BRANCH]` from `--base` or `.agentrc.json` →
@@ -248,6 +275,15 @@ Do **not** poll CI. That is the `/deliver` Phase 7 job and is overkill for
 ad-hoc changes. The operator (or GitHub's email notification) is the next
 watcher.
 
+> **Local ref left behind — reaped at the next boot.** At the **pr** level
+> this command leaves a local feature branch behind after the PR merges; it
+> does **not** reap it inline (the merge happens later, out of band). You do
+> not need to run `/git-cleanup` by hand: the next time `/git-deliver` (or
+> `/plan`) runs, its **Boot sweep** step reaps that merged ad-hoc branch and
+> fast-forwards `main` automatically. The delivering flow owns tidying its own
+> refs on the next boot — see
+> [`.agents/rules/git-conventions.md` § Local checkout hygiene](../rules/git-conventions.md).
+
 ---
 
 ## Troubleshooting

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

@@ -342,14 +342,28 @@ just fires the emit and reads the resulting ledger.
    refusing to run when the body has no `## Acceptance Table` section
    and no waiver is set (the
    start gate in Phase 1 would normally catch that first).
-2. **PR open — bus-driven (Story #2894).** On
-   `acceptance.reconcile.ok` the `Finalizer` listener invokes
-   [`openOrLocatePr`](../../scripts/lib/orchestration/finalize/open-or-locate-pr.js)
-   with `{ epicId, headBranch: 'epic/<id>', baseBranch: 'main' }`.
-   The helper probes for an existing open PR on the head branch
-   first (idempotent locate path — a re-run of `/deliver`
-   on the same branch short-circuits without opening a duplicate)
-   and only opens a new PR when none exists. The listener then
+2. **PR open / ready — bus-driven (Story #2894; earlyPr split Story
+   #4359).** On `acceptance.reconcile.ok` the `Finalizer` listener
+   resolves `delivery.ci.earlyPr` via
+   [`getCiDelivery`](../../scripts/lib/config/ci.js) (default `true`) and
+   branches:
+   - **`earlyPr` on (default)** — the Epic PR already exists as a draft
+     (Phase 2 opened it at wave 1 with
+     [`openOrLocatePr`](../../scripts/lib/orchestration/finalize/open-or-locate-pr.js)
+     `{ draft: true }`). Finalize locates it and flips it ready-for-review
+     via
+     [`markPrReady`](../../scripts/lib/orchestration/finalize/open-or-locate-pr.js)
+     rather than creating a PR. `gh pr ready` on an already-ready PR is a
+     no-op, so replay is idempotent.
+   - **`earlyPr` off** — finalize invokes `openOrLocatePr` with
+     `{ epicId, headBranch: 'epic/<id>', baseBranch: 'main' }` (no
+     `draft`). The helper probes for an existing open PR on the head branch
+     first (idempotent locate path — a re-run of `/deliver` on the same
+     branch short-circuits without opening a duplicate) and only opens a
+     new PR when none exists.
+
+   In both modes the PR title/body contract (`feat: Epic #<id>` /
+   `Closes #<id>`) is identical. The listener then
    emits `pr.created` → `epic.finalize.end` and **stops** (Story
    #3367). It does **not** emit `epic.merge.ready`: that event is
    the sole `AutomergeArmer` trigger, and emitting it from finalize
@@ -495,20 +509,26 @@ node .agents/scripts/lifecycle-emit.js --epic <epicId> \
 
 If Phase 8.5 fell back to the operator-merges-button path (`gh pr
 merge --auto` was declined), the `epic.merge.armed` event never fires
-inside this run and Phase 9 will not run automatically. After the
-operator merges the PR, `epic/<epicId>` and each `story-<id>` ref can
-be reaped manually:
+inside this run and Phase 9 will not run automatically. **Do not** hand-reap
+the refs with a raw `git branch -D` sequence — drive the same
+`BranchCleaner`-backed reap the auto-merge path uses by firing
+`epic.merge.armed` after the operator merges the PR:
 
 ```bash
-git checkout main
-git pull --ff-only origin main
-git branch -D epic/<epicId>
-git branch -D story-<id1> story-<id2> ...
-git remote prune origin
+node .agents/scripts/lifecycle-emit.js --epic <epicId> \
+  --event epic.merge.armed --pr-url <prUrl>
 ```
 
-Note that `git-cleanup.js` alone will not catch `story-<id>` refs in
-this case because the epic PR squash-merges break the `git branch
---merged main` signal and the stories never had their own PRs. Wiring
-a CLI surface that drives the BranchCleaner listener for this
-fallback is tracked as follow-up to Story #2398.
+That single emit reaps `epic/<epicId>` and every `story-<id>` ref from the
+checkpoint, prunes stale tracking refs, and fast-forwards local `main` to
+`origin/main` — the whole Phase 9 reap, not a partial hand-roll. A plain
+`git-cleanup.js` sweep alone will **not** catch the `story-<id>` refs here,
+because the epic PR squash-merge breaks the `git branch --merged main` signal
+and the stories never had their own PRs; the lifecycle-emit surface above is
+the correct driver.
+
+Re-running `/deliver <epicId>` reaches the same outcome without the manual
+emit: the idempotent-resume auto-arm
+(`detectMergedUncleanedEpic` → `armCleanupIfMerged` in
+[`epic-cleanup.js`](../../scripts/lib/orchestration/epic-cleanup.js)) detects
+the merged-but-uncleaned Epic and fires `epic.merge.armed` for you.

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

@@ -220,6 +220,41 @@ returned Story's terminal status, and re-tick until terminal. There is no
 `record-wave` / `currentWave` step — the checkpoint carries only a flat
 per-Story status map (for resume + the operator rollup) and the global cap.
 
+### 2.0. Open the Epic PR as a draft at wave 1 (Story #4359)
+
+When `delivery.ci.earlyPr` is on (the default), open the Epic PR as a
+**draft** once, before the first `tick`, so every subsequent per-wave push
+to `epic/<epicId>` runs CI attributed to its own wave. (CI is keyed on the PR
+ref with `cancel-in-progress`, so each new wave push **supersedes** the prior
+wave's in-flight run rather than queuing behind it — the latest wave always
+gets the verdict, and CI-minute use stays bounded; intermediate wave runs are
+cancelled, not completed.) Resolve the flag through the
+[`getCiDelivery`](../../scripts/lib/config/ci.js) accessor (default `true`);
+do not read `delivery.ci.earlyPr` directly.
+
+> **This step is host-LLM-driven, with no runtime enforcement seam** — unlike
+> the Phase 7 ready-flip, which the `Finalizer` listener wires in
+> deterministically (`finalizer.js` resolves `earlyPr` and calls
+> `markPrReady`). The asymmetry is intentional and safe: if this wave-1
+> draft-open is skipped, the `earlyPr`-on Phase 7 `markPrReady` call degrades
+> to a no-op on the PR that finalize opens at close time (`gh pr ready` is a
+> no-op on an already-ready PR), so the merge gate is never stranded — the run
+> only loses the per-wave CI attribution this step buys.
+
+- **`earlyPr` on** — call
+  [`openOrLocatePr`](../../scripts/lib/orchestration/finalize/open-or-locate-pr.js)
+  with `{ epicId, headBranch: 'epic/<epicId>', baseBranch: 'main', draft: true }`.
+  The helper probes for an existing open PR first, so this is idempotent — a
+  resumed `/deliver` run re-locates the same draft and opens no duplicate.
+  Phase 7 later flips this draft to ready-for-review (it does **not**
+  re-create the PR).
+- **`earlyPr` off** — skip this step entirely. No draft is opened at wave 1;
+  Phase 7 opens the PR at close time on the pre-Story timing.
+
+The draft carries the same title/body contract Phase 7 uses
+(`feat: Epic #<epicId>` / `Closes #<epicId>`), so no title/body reconciliation
+is needed when it is marked ready.
+
 ### 2a. Tick — plan the next action
 
 ```bash
@@ -556,7 +591,7 @@ degradation contract, and the fail-safe-and-loud security note.
 
 ---
 
-## Phase 7 — Finalize (open PR to main)
+## Phase 7 — Finalize (ready the PR / open PR to main)
 
 Before the close-tail emit, sync the Epic branch with `origin/main` so the
 PR opens with the latest base commits already integrated (a stale base
@@ -577,12 +612,28 @@ node .agents/scripts/lifecycle-emit.js --epic <epicId> --event epic.close.end
 
 `epic.close.end` drives the bus-owned `Finalizer` chain: acceptance-table
 reconciliation (throws and aborts finalize on a coverage gap, `waived` under
-`acceptance::n-a`), idempotent PR open/locate against `main`, and the
+`acceptance::n-a`), the PR-open/ready step (below), and the
 `epic-handoff` comment naming the PR URL. The chain emits `pr.created` →
 `epic.finalize.end` and **stops** — it never emits `epic.merge.ready` (the
 auto-merge arm is driven later from the Phase 8.5 gated watch path). The
 operator shells nothing beyond the sync and the single emit.
 
+**PR-open/ready is gated by `delivery.ci.earlyPr` (Story #4359).** Resolve
+the flag through the [`getCiDelivery`](../../scripts/lib/config/ci.js)
+accessor (default `true`); do not read `delivery.ci.earlyPr` directly.
+
+- **`earlyPr` on (default)** — the Epic PR already exists as a draft (Phase
+  2 opened it at wave 1). Finalize **locates** the existing PR and flips it
+  ready-for-review via
+  [`markPrReady`](../../scripts/lib/orchestration/finalize/open-or-locate-pr.js)
+  rather than creating a PR. `gh pr ready` on an already-ready PR is a
+  no-op, so a re-run is idempotent.
+- **`earlyPr` off** — no draft was opened at wave 1; finalize opens the PR
+  now via `openOrLocatePr` (no `draft`), exactly as the pre-Story timing.
+
+In both modes the PR title/body contract (`feat: Epic #<epicId>` /
+`Closes #<epicId>`) is identical.
+
 See
 [`deliver-epic-reference.md` § Phase 7 — Finalize](deliver-epic-reference.md#phase-7--finalize-close-tail-listener-chain)
 for the branch-sync outcome table (conflict / fetch-failed recovery) and the
@@ -595,25 +646,51 @@ sweep).
 ## Phase 8 — Watch-and-iterate until CI is green
 
 The host LLM owns the green-bar loop until the operator merges. Use
-the shared watch-and-recover helper, which wraps `gh pr checks --watch`
-and additionally auto-recovers from `mergeStateStatus: BEHIND` by
-calling `gh pr update-branch` once every required check is green
-(branch-protection rules requiring "up to date before merging"
-otherwise park the PR until the operator clicks **Update branch**
-manually):
+`pr-watch-with-update.js` — the **single CI-watch mechanism** shared with
+the standalone single-Story Step 4 path (Story #4358). It polls the PR's
+required checks to a terminal state and additionally auto-recovers from
+`mergeStateStatus: BEHIND` by calling `gh pr update-branch` once every
+required check is green (branch-protection rules requiring "up to date
+before merging" otherwise park the PR until the operator clicks **Update
+branch** manually):
 
 ```bash
-node <agentRoot>/scripts/pr-watch-with-update.js --pr <prNumber>
+node <agentRoot>/scripts/pr-watch-with-update.js --pr <prNumber> --epic <epicId>
 ```
 
-`<agentRoot>` resolves from `project.paths.agentRoot` (default
-`.agents`). Pass `--max-updates N` (default 3) to cap update-branch
-calls per session and `--poll-interval-ms MS` (default 10000) to
-override the polling cadence.
-
-Exit 0 → proceed to Phase 8.5. Non-zero → remediate and re-run the helper
-(push fixes to `epic/<epicId>`; auto-merge stays armed across retries).
-
+`<agentRoot>` resolves from `project.paths.agentRoot` (default `.agents`).
+Poll cadence and caps come from `delivery.ci.watch.*`
+(`pollIntervalMs`, `maxPolls`, `maxResumes`); pass `--poll-interval-ms`,
+`--max-polls`, `--max-resumes`, or `--max-updates` to override for one
+run. Passing `--epic <epicId>` scopes the red-path failure digest to
+`temp/epic-<epicId>-ci-digest.{json,md}`.
+
+**Three-way exit (slow-vs-failed semantics):**
+
+- **Exit 0** — every required check is green → proceed to Phase 8.5.
+- **Exit 1** — a required check genuinely failed (red). The CLI writes
+  `temp/epic-<epicId>-ci-digest.{json,md}` (failing check, run id,
+  `gh run view --log-failed` tail, coarse classification) and surfaces
+  the fix-loop handoff. Remediate on `epic/<epicId>` and re-run the
+  helper (auto-merge stays armed across retries). If the same failure
+  class recurs, hand the convergence off to the host loop:
+  `/loop /loops:fix-failing-tests`.
+- **Exit 2** — **still-running** (slow CI, not red): the poll cap fired
+  with checks still pending and the watcher exhausted its
+  `delivery.ci.watch.maxResumes` re-arm budget with nothing red. This is
+  **never** a failure and **never** `timed_out`. Hand the wait off to the
+  host's interval loop rather than blocking the delivery turn:
+  `/loop 5m /loops:watch-ci`.
+
+> **Triage authority.** How to classify and remediate a red (or repeatedly
+> slow) check — the root-cause-only decision tree for infra/transient and
+> flaky failures (reproduce → check `main` → bisect env vs code → fix in-scope
+> or file a `meta::framework-gap` issue), the never-rerun / never-quarantine
+> prohibitions, and the escalation criteria (three-strikes, the 30-minute
+> wall-clock timebox, and the clearly-environmental fast path) — is defined
+> once in [`.agents/rules/ci-remediation.md`](../../rules/ci-remediation.md).
+> Read it before remediating.
+>
 > **Remediation + hard prohibitions.** For the per-check fix table (lint,
 > baseline drift, test, coverage), the three-strikes halt rule, and the
 > never-merge / never-force-push / never-dodge prohibitions, see
@@ -631,14 +708,43 @@ node .agents/scripts/lifecycle-emit.js --epic <epicId> \
   --event epic.automerge.start --pr-url <prUrl>
 ```
 
-`AutomergePredicate` evaluates the structured-signal verdict and emits
-`epic.merge.ready` on a clean verdict or `epic.merge.blocked` otherwise. The
-downstream `AutomergeArmer` fires `gh pr merge --auto --squash
---delete-branch` **only** when `clean: true` (empty manual-interventions,
-every wave complete, no story blocked, `0` 🔴 + `0` 🟠 review findings, and
-the retro's `automerge-verdict` trailer reports `cleanSprint: true`).
-Otherwise it records disqualifying reasons and exits without merging — the
-operator merges manually.
+`AutomergePredicate` first runs a **live `gh pr checks --required` probe**
+(Story #4361): green required CI is the arming signal, so if any required
+check is red, pending, or the probe is unreadable it emits
+`epic.merge.blocked` immediately — even if the Phase 8 watch was interrupted
+before it observed green (closing the Story #3901 interrupted-watch hole).
+When the probe is green it evaluates the structured-signal verdict under the
+`delivery.ci.autoMerge` policy (default `"trust-ci"`; see
+[`configuration.md`](../../docs/configuration.md)):
+
+- **`trust-ci`** (default) — the ONLY structured conditions that block
+  arming are an unresolved 🔴 critical (red) code-review finding or an
+  `agent::blocked` state (a story-level blocker recorded in run-state, a
+  non-done story, or a missing run-state checkpoint). Manual interventions,
+  🟠 warning-level findings, and a non-clean retro are **recorded for audit**
+  (surfaced on the classification log and the arm-reason) but no longer block.
+- **`strict`** — restores the prior clean-sprint predicate exactly: empty
+  manual-interventions, every story done, no story blocked, `0` 🔴 + `0` 🟠
+  review findings, and the retro's `automerge-verdict` trailer reporting
+  `cleanSprint: true`. Any dirty signal blocks.
+
+On an arming decision the predicate emits `epic.merge.ready`; the downstream
+`AutomergeArmer` (the sole authorized `gh pr merge` call site) fires
+`gh pr merge --auto --squash --delete-branch`. Otherwise the predicate emits
+`epic.merge.blocked` with the disqualifying reasons and exits without merging
+— the operator merges manually.
+
+**Blocked-path output (operator merges the button).** When arming is
+declined, `epic.merge.armed` never fires inside this run, so Phase 9 does not
+reap automatically. Surface the exact one-liner the operator runs **after**
+they merge the PR by hand so local refs are reaped and `main` is
+fast-forwarded (the idempotent-resume path below runs this automatically on
+the next `/deliver <epicId>`):
+
+```bash
+node .agents/scripts/lifecycle-emit.js --epic <epicId> \
+  --event epic.merge.armed --pr-url <prUrl>
+```
 
 Close the phase wrapper by emitting `epic.automerge.end` (records the arm
 outcome on the ledger; `merged: true` once GitHub completes the squash,
@@ -650,9 +756,10 @@ node .agents/scripts/lifecycle-emit.js --epic <epicId> \
 ```
 
 > **Predicate wiring + manual-intervention recording.** For the full
-> `clean: true` predicate contract (Story #3901 — the trailer read, the
-> CI-freshness skip) and the `epic-deliver-note-intervention.js` command +
-> its trigger list, see
+> predicate contract (the trailer read, the `delivery.ci.autoMerge` policy
+> split, and the Story #4361 live `gh pr checks --required` probe that
+> replaced the former CI-freshness skip) and the
+> `epic-deliver-note-intervention.js` command + its trigger list, see
 > [`deliver-epic-reference.md` § Phase 8.5 — Auto-merge predicate detail](deliver-epic-reference.md#phase-85--auto-merge-predicate-detail).
 
 ---
@@ -689,6 +796,19 @@ via `helpers/epic-deliver-story`'s own checkpointing). The PR from Phase 7 is
 updated in place on subsequent runs. The authoritative live view is
 the `epic-run-progress` structured comment.
 
+**Resume auto-arm for a merged-but-uncleaned Epic.** When `/deliver` resumes
+against an Epic whose PR already merged (operator merged the button in a prior
+session) but whose local `epic/<id>` / `story-<id>` refs still linger, the
+resume path detects the merged-but-uncleaned state
+(`detectMergedUncleanedEpic` in
+[`epic-cleanup.js`](../../scripts/lib/orchestration/epic-cleanup.js)) and fires
+`epic.merge.armed` automatically so Phase 9 reaps — no manual command. The
+detection is idempotent: an already-reaped Epic (no local refs) is a clean
+no-op, and an unmerged Epic never arms. It resolves the merged PR's URL for the
+required `epic.merge.armed` payload and fails closed (does **not** arm) on any
+indeterminate `gh` probe. The one-liner under Phase 8.5 / Phase 9 is the manual
+equivalent for the case where the operator does not re-run `/deliver`.
+
 ---
 
 ## Constraints

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

@@ -235,7 +235,7 @@ Each Agent call:
    child MUST drive the close → CI-watch → merge-confirm → `agent::done`
    sequence to a terminal state *within its own turn* and end **only** by
    returning the § 2c JSON object. The auto-merge wait is an
-   internally-blocking step (`gh pr checks --watch` blocks the turn), **not**
+   internally-blocking step (`pr-watch-with-update.js` blocks the turn), **not**
    a reason to suspend and hand back. A child that ends its turn with
    free-form prose and an unconfirmed merge (e.g. "I'll wait for the
    background watch task…") has violated the contract — the loop cannot
@@ -279,7 +279,7 @@ free-form prose:
 
 The status enum is **closed** — `done`, `blocked`, or `failed`. There is no
 "pending" / "waiting" status, because the close-phase auto-merge wait is
-**not** a returnable suspension: the child blocks on `gh pr checks --watch`
+**not** a returnable suspension: the child blocks on `pr-watch-with-update.js`
 *inside its own turn*, confirms the merge, flips `agent::done`, and only then
 returns `status: "done"`. A child that returns prose instead — parking on the
 CI wait with an unconfirmed merge — breaks the loop's ability to advance
@@ -318,11 +318,24 @@ Print a final run summary listing every delivered Story in completion order:
 All Stories delivered. PRs opened, auto-merge armed. CI will merge each
 PR when checks pass; each child then confirms the merge and flips its
 Story to `agent::done` (Story #3385 — until the merge confirms, a Story
-rests at `agent::closing` with its issue OPEN). Run
-`git-cleanup --fast-forward-main` after the last merge to bring local
-main up to date.
+rests at `agent::closing` with its issue OPEN).
 ```
 
+Then **fast-forward `main` yourself** — do not instruct the operator to run it
+after the last merge. The delivering flow owns bringing the local base branch
+up to whatever has merged so far:
+
+```bash
+node .agents/scripts/git-cleanup.js --fast-forward-main --execute --yes
+```
+
+This runs only the fast-forward-main phase (`git fetch origin main` →
+`git merge --ff-only`); it is idempotent and a no-op when `main` is already
+current, so it is safe to run even while some PRs are still queued in
+auto-merge. Report its one-line result in the summary. Merged Story branches
+themselves are reaped by the boot sweep at the next `/plan` / `/deliver` boot —
+see [`.agents/rules/git-conventions.md` § Local checkout hygiene](../../rules/git-conventions.md).
+
 When some Stories are blocked or failed, list them explicitly with the
 `blockerCommentId` or failure detail so the operator knows where to look.
 

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

@@ -197,8 +197,8 @@ then ends its turn with **free-form prose** — e.g. "I'll wait for the
 background watch task to complete" or "the next event will be its completion
 notification" — leaving the merge unconfirmed and the Story stranded at
 `agent::closing` (observed on Story #1553 / PR #1554). **Do not do this.**
-`gh pr checks <prNumber> --watch` *blocks the current turn* until CI resolves
-— that is the mechanism by which you wait. You MUST keep your turn alive
+`pr-watch-with-update.js --pr <prNumber>` *blocks the current turn* until CI
+resolves — that is the mechanism by which you wait. You MUST keep your turn alive
 across the wait: watch → (fix + push + re-watch on red) → confirm the merge
 (Step 5) → flip `agent::done` → run the post-merge steps → and only then
 return the terminal JSON status contract. The CI wait NEVER terminates your
@@ -389,7 +389,7 @@ up").
 
 **The auto-merge wait does not produce a fourth status.** There is no
 "pending" or "waiting" terminal — the CI/auto-merge wait is handled
-*internally* by blocking on `gh pr checks --watch` (Step 4) and confirming
+*internally* by blocking on `pr-watch-with-update.js` (Step 4) and confirming
 the merge (Step 5). You return **only** when you have reached a genuinely
 terminal state:
 

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

@@ -223,10 +223,23 @@ The script runs the close-validation gates against `baseBranch`, syncs the
 Story branch from `origin/<baseBranch>` (Story #2580 — the parallel-race
 defence), pushes `story-<id>`, opens (or reuses) a PR against `baseBranch`
 with a `Closes #<storyId>` footer, enables GitHub native auto-merge
-(`--auto --squash --delete-branch`), flips the Story to **`agent::closing`**
+(`--auto --squash --delete-branch`) **when `delivery.ci.autoMerge` is
+`"trust-ci"` (the default)**, flips the Story to **`agent::closing`**
 (NOT `agent::done` — the issue stays OPEN until Step 5 confirms the merge,
 Story #3385), reaps the worktree, and releases the Story lease.
 
+> **`delivery.ci.autoMerge` policy (shared with the Epic path).** The
+> standalone close honours the same config knob the Epic Phase 8.5 gate
+> reads. Under the default `"trust-ci"`, GitHub native auto-merge is armed
+> and the PR squash-merges once its **required** checks pass (GitHub's
+> `--auto` is the required-check gate — no client-side predicate is needed
+> here, unlike the Epic path, because a standalone Story runs no
+> audit/review/retro phase to gate on). Under `"strict"`, the close **does
+> not arm auto-merge** — the PR opens and waits for an **operator merge**,
+> exactly as `--no-auto-merge` does per-run. This lets a consumer who tightens
+> Epic merges with `"strict"` get the same operator-in-the-loop behaviour for
+> standalone Stories.
+
 Flags:
 
 - `--skip-validation` — bypass the gates (Step 1). Use only when re-running
@@ -255,31 +268,55 @@ timing-sensitive tests routinely drift between the two. The agent owns the
 green-CI outcome, not just the push.
 
 > **The auto-merge wait is an internally-blocking step, not a reason to end
-> your turn.** `gh pr checks <prNumber> --watch` blocks the current turn
-> until CI resolves — that IS how you wait. Keep the turn alive: watch →
-> (fix + push + re-watch on red) → confirm the merge (Step 5) → flip
+> your turn.** `pr-watch-with-update.js` blocks the current turn until CI
+> resolves — that IS how you wait. Keep the turn alive: watch → (fix +
+> push + re-watch on red) → confirm the merge (Step 5) → flip
 > `agent::done` → post-merge steps → return the terminal JSON contract.
 > Ending the turn with prose and an unconfirmed merge is a contract
 > violation (the Story #1553 / PR #1554 failure mode). See
 > [`single-story-deliver-reference.md` § The auto-merge wait is an internally-blocking step](single-story-deliver-reference.md#the-auto-merge-wait-is-an-internally-blocking-step).
 
-After `single-story-close.js` succeeds, enter the watch + fix loop:
+After `single-story-close.js` succeeds, enter the watch + fix loop. Drive
+`pr-watch-with-update.js` — the **single CI-watch mechanism** shared with
+the Epic Phase 8 path (Story #4358). It polls the required checks to a
+terminal state and auto-recovers from `mergeStateStatus: BEHIND`; do
+**not** fall back to a bare `gh pr checks` watch invocation:
 
 ```bash
-gh pr checks <prNumber> --watch
+node <agentRoot>/scripts/pr-watch-with-update.js --pr <prNumber>
 ```
 
-When the watch exits:
-
-- **All checks ✓** — auto-merge will fire (or has already). The Story is
-  still at `agent::closing` with its issue OPEN. **Proceed to Step 5 within
-  the same turn** — green CI is the *start* of the merge-confirm sequence,
-  not a terminal state.
-- **Any check ✗** — diagnose, fix, and push a new commit on
-  `story-<storyId>`, then re-watch. Auto-merge stays enabled across
-  retries; no need to re-arm it. The Story stays at `agent::closing`
-  throughout, so a failed/abandoned PR never strands a CLOSED issue.
-
+Poll cadence and caps come from `delivery.ci.watch.*`
+(`pollIntervalMs`, `maxPolls`, `maxResumes`); pass `--poll-interval-ms`,
+`--max-polls`, or `--max-resumes` to override for one run.
+
+When the watch exits, branch on the exit code:
+
+- **Exit 0 (all checks ✓)** — auto-merge will fire (or has already). The
+  Story is still at `agent::closing` with its issue OPEN. **Proceed to
+  Step 5 within the same turn** — green CI is the *start* of the
+  merge-confirm sequence, not a terminal state.
+- **Exit 1 (a check genuinely failed)** — diagnose, fix, and push a new
+  commit on `story-<storyId>`, then re-watch. Auto-merge stays enabled
+  across retries; no need to re-arm it. The Story stays at
+  `agent::closing` throughout, so a failed/abandoned PR never strands a
+  CLOSED issue. If the same failure class recurs, hand convergence off to
+  the host loop: `/loop /loops:fix-failing-tests`.
+- **Exit 2 (still-running — slow CI, not red)** — the poll cap fired with
+  checks still pending and the watcher exhausted its resume budget with
+  nothing red. This is **never** a failure. Hand the wait off to the
+  host's interval loop rather than ending your turn:
+  `/loop 5m /loops:watch-ci`.
+
+> **Triage authority.** How to classify and remediate a red (or repeatedly
+> slow) check — the root-cause-only decision tree for infra/transient and
+> flaky failures (reproduce → check `main` → bisect env vs code → fix in-scope
+> or file a `meta::framework-gap` issue), the never-rerun / never-quarantine
+> prohibitions, and the escalation criteria (three-strikes, the 30-minute
+> wall-clock timebox, and the clearly-environmental fast path) — is defined
+> once in [`.agents/rules/ci-remediation.md`](../../rules/ci-remediation.md).
+> Read it before remediating a red check above.
+>
 > **CI recovery procedures.** For resurrecting the worktree after
 > `reapOnSuccess`, pulling the failing job log, fixing coverage/CRAP
 > baselines without re-running close-validation, and the when-to-stop
@@ -401,8 +438,8 @@ worker so the contract is self-contained when this workflow is the entry
 point.
 
 There is **no fourth "pending" status** — the CI/auto-merge wait is handled
-internally by blocking on `gh pr checks --watch` (Step 4) and confirming the
-merge (Step 5). Return **only** on a confirmed `MERGED` PR (`status: "done"`),
+internally by blocking on `pr-watch-with-update.js` (Step 4) and confirming
+the merge (Step 5). Return **only** on a confirmed `MERGED` PR (`status: "done"`),
 an `agent::blocked` transition (`status: "blocked"`), or an unrecoverable
 failure (`status: "failed"`).
 

package/.agents/workflows/plan.md

@@ -124,6 +124,30 @@ are operator-input waits, not validators. The two *named* HITL STOP gates the
 Story tracks (gate #1, gate #2) are the load-bearing pair; these additional
 waits are auto-proceeded for the same headless reason.
 
+## Boot sweep
+
+Before anything else — ahead of the first-run preflight — run the **protected
+boot sweep** so `/plan` opens against a tidy local checkout instead of one
+still carrying the merged refs of the last delivered Epic or Story:
+
+```bash
+node .agents/scripts/boot-sweep.js \
+  --include 'story-*' --include 'epic/*' \
+  --include 'feat/*' --include 'fix/*' --include 'chore/*'
+```
+
+This is the **safe subset** of the `/git-cleanup` phases: it fast-forwards the
+base branch (`main`), prunes stale remote-tracking refs, and reaps every local
+branch whose PR is **merged** and whose HEAD matches the merged `headRefOid`.
+It **never** touches the stash stack, and its `evaluateProtection` partition
+skips (never reaps) any candidate with unpushed work, a dirty worktree, or a
+still-open parent Story ticket — so it is safe to run unattended at the top of
+a planning session. The sweep is **silent on a no-op**: with nothing to reap
+and `main` already current it prints a single summary line
+(`[boot-sweep] reaped 0 local + 0 remote; protected 0.`) and moves on. Its exit
+code is always `0` — a failed sweep is swallowed and reported in the summary,
+never allowed to fail the planning run.
+
 ## First-run preflight
 
 Before routing to a path helper, run a **first-run preflight** to catch
@@ -169,18 +193,22 @@ stubbed docs, or an unready doctor verdict).
 1. **Parse args.** Exactly one of `<epicId>`, `--idea`, `--from-notes`, or
    `--body` must be present; anything else is a usage error naming the four
    forms. A `--body` invocation routes to the story path (no triage).
-2. **First-run preflight.** Run the preflight above. Skip when all signals
+2. **Boot sweep.** Run the protected boot sweep above
+   (`node .agents/scripts/boot-sweep.js …`) to fast-forward `main`, prune
+   stale remotes, and reap merged-PR branches. Silent on a no-op; never fails
+   the run.
+3. **First-run preflight.** Run the preflight above. Skip when all signals
    are clear (healthy project).
-3. **Triage (idea path only).** Run the
+4. **Triage (idea path only).** Run the
    [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) skill on the
    seed. Record the verdict in chat (one line).
-4. **Delegate.** Read the selected path helper **in full** and execute it
+5. **Delegate.** Read the selected path helper **in full** and execute it
    from its entry phase, forwarding the absorbed flags (including `--yes`).
    The helper's phase numbering, HITL gates, and scripts are unchanged — this
    router adds no phase content. When `--yes` is present, the two HITL STOP
    gates auto-proceed per [Headless / non-interactive mode](#headless--non-interactive-mode---yes)
    above; every deterministic gate still runs.
-5. **Internal returns.** When a path helper would historically have handed
+6. **Internal returns.** When a path helper would historically have handed
    off to the other planning command, switch helpers in-place and continue;
    surface the switch to the operator as a one-line note.
 

package/docs/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.86.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.85.0...mandrel-v1.86.0) (2026-07-07)
+
+
+### Added
+
+* Epic [#4372](https://github.com/dsj1984/mandrel/issues/4372) ([#4376](https://github.com/dsj1984/mandrel/issues/4376)) ([98a82a4](https://github.com/dsj1984/mandrel/commit/98a82a4c27e5eafdfa2f1c54cfb42ed537a69a2e))
+
+
+### Fixed
+
+* **baselines:** repair check-baselines auto-refresh + dedupe FF probes ([#4380](https://github.com/dsj1984/mandrel/issues/4380)) ([20a4ecd](https://github.com/dsj1984/mandrel/commit/20a4ecd97f92cb6a88be474c321b139fed95db56)), closes [#4379](https://github.com/dsj1984/mandrel/issues/4379)
+
+## [1.85.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.84.0...mandrel-v1.85.0) (2026-07-06)
+
+
+### Added
+
+* **delivery:** honor delivery.ci.autoMerge policy in standalone Story close ([#4371](https://github.com/dsj1984/mandrel/issues/4371)) ([0938d6b](https://github.com/dsj1984/mandrel/commit/0938d6b45bc0357bdcbc3d3ae148f18ab7ee5627))
+* Epic [#4355](https://github.com/dsj1984/mandrel/issues/4355) ([#4368](https://github.com/dsj1984/mandrel/issues/4368)) ([585b823](https://github.com/dsj1984/mandrel/commit/585b82364190ea5676f96616e4c7a36a6d3468b5))
+* **planning:** remove hard acceptance ceiling and add delivery-schedule simulation to decomposer ([#4366](https://github.com/dsj1984/mandrel/issues/4366)) ([bfc3f12](https://github.com/dsj1984/mandrel/commit/bfc3f12812ea5bc6e4d9f599d130b6f53b1009c3))
+
 ## [1.84.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.83.0...mandrel-v1.84.0) (2026-07-05)
 
 

package/package.json

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