Extend intent-gap patch-restore re-drive to the sweep workflow

[pbean]

Summary

The intent-gap patch-restore re-drive (added for story runs) should be extended to the sweep workflow (SweepEngine deferred-work bundles).

Background

BMAD-METHOD PR #2564 ("preserve the attempted change on intent-gap halts") makes bmad-dev-auto save the reverted attempt as a patch file before halting on an intent gap at the review step. The orchestrator now has a sanctioned recovery for story escalations: bmad-loop resolve (interactive, or --no-interactive --restore-patch <path>) re-arms the escalated spec to in-review, latches the patch onto the task, and the engine re-applies it onto the baseline after every reset of the re-drive — so the re-driven dev session resumes review on the restored diff instead of re-implementing from scratch.

This landed on branch feat/intent-gap-patch-restore (plan: i-received-a-message-unified-journal.md). Scope was deliberately limited to story runs; sweep-bundle escalations still take a from-scratch re-drive.

What's missing

SweepEngine bundle escalations should honor a restore_patch latch the same way story runs do:

• re-arm the bundle spec to in-review (mirroring runs.rearm_escalation's restore branch), rather than the bundle's from-scratch equivalent;
• re-apply the saved patch after the bundle's baseline reset, before dispatching the bundle dev session (mirroring Engine._restore_patch, called from the dev loop on feedback is None);
• clear the latch on the bundle commit (mirroring Engine._commit clearing task.restore_patch = None next to resolved_redrive = False).

Note the sweep path has its own _drive_story / _rollback_or_pause / _safe_reset call sites (sweep.py), and bundles have no sprint-status entry, so the story-run wiring can't just be inherited unchanged — the seams need porting.

Design references

• model.StoryTask.restore_patch — the persisted latch (already exists; bundle tasks reuse StoryTask).
• verify.apply_patch(repo, patch_path) — the git apply helper (already exists; reusable as-is).
• Engine._restore_patch — the apply/journal/escalate-on-failure helper and its feedback is None gating in _dev_phase (the pattern to mirror in the sweep dev loop).
• runs.rearm_escalation(..., restore_patch=...) — the in-review vs ready-for-dev re-arm branch (the sweep bundle re-arm needs the equivalent).

The sweep resolve/re-arm entry point (however bundle escalations are resolved) would need a restore_patch passthrough analogous to cli.cmd_resolve.

[coderabbitai]

🔗 Related PRs

#53 - fix(adapters): complete dev sessions only on Stop or window death [merged]
#54 - feat(scm): bounded retention for attempt-preserve-dirty worktree-snapshot refs [merged]
#62 - fix(engine): session-end durability + raw KeyboardInterrupt handling [merged]
#63 - fix(engine): close resume-replay edges from #62 (final-cycle replay, stale result_json, record bloat) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[pbean]

Status update after the intent-gap audit remediation (PR #86, merged as 9ea999c):

The story/sprint intent-gap patch-restore re-drive is now on main via #86. This issue — extending the same recovery to the sweep / deferred-work bundle workflow — is still open: sweep.py has no restore_patch handling. Specifically unimplemented for bundles:

• re-arm the bundle spec to in-review on a restore_patch latch (mirroring runs.rearm_escalation's restore branch),
• re-apply the saved patch after the bundle's baseline reset before dispatching the bundle dev session (mirroring Engine._restore_patch / its feedback is None gating),
• clear the latch on the bundle commit.

Partial head-start already on main: the bundle-side proof-of-work gate already honors a latched patch — verify.verify_dev_exclude_relpaths(paths, spec_path, task.restore_patch) is wired at all three call sites incl. the bundle path (verify.py:1299). So a future sweep implementation inherits the T4 protection (a latched patch file no longer vacuously satisfies "changes since baseline").

Related, worth landing alongside any sweep implementation: #88 (from-scratch re-drive: untracked halt residue can vacuously pass proof-of-work) and #90 (an abandoned restore attempt's untracked files get baselined at the next re-arm) both interact with a latched/from-scratch bundle re-drive.

Keeping this open; the core sweep wiring is genuinely outstanding.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
fd -i 'sweep.py|verify.py|runs.py|engine.py' -x echo {}

echo "---- sweep.py restore_patch grep ----"
rg -n 'restore_patch' -g 'sweep.py' -C3 || true

echo "---- verify.py verify_dev_exclude_relpaths ----"
rg -n 'verify_dev_exclude_relpaths' -C3 || true

echo "---- runs.py rearm_escalation ----"
rg -n 'rearm_escalation' -C5 || true

echo "---- engine.py _restore_patch ----"
rg -n '_restore_patch' -C5 || true

echo "---- general restore_patch usage across repo ----"
rg -n 'restore_patch' -C2 || true

Length of output: 1233

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "==== sweep.py: restore_patch ===="
rg -n 'restore_patch' src/bmad_loop/sweep.py -C3 || echo "NO MATCH in sweep.py"

echo ""
echo "==== verify.py: verify_dev_exclude_relpaths ===="
rg -n 'verify_dev_exclude_relpaths' src/bmad_loop/verify.py -C3 || echo "NO MATCH"

echo ""
echo "==== runs.py: rearm_escalation ===="
rg -n 'rearm_escalation' src/bmad_loop/runs.py -C8 || echo "NO MATCH"

echo ""
echo "==== engine.py: _restore_patch ===="
rg -n '_restore_patch' src/bmad_loop/engine.py -C8 || echo "NO MATCH"

echo ""
echo "==== sweep.py: in-review / bundle spec status transitions ===="
rg -n 'in-review|in_review' src/bmad_loop/sweep.py -C3 || echo "NO MATCH"

echo ""
echo "==== sweep.py: outline ===="
ast-grep outline src/bmad_loop/sweep.py --items all || true

Length of output: 8359

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "==== sweep.py: _dev_prompt ===="
rg -n '_dev_prompt' src/bmad_loop/sweep.py -A25 | head -60

echo ""
echo "==== sweep.py: _run_bundle ===="
rg -n 'def _run_bundle' src/bmad_loop/sweep.py -A60 | head -90

echo ""
echo "==== sweep.py: _commit_ledger ===="
rg -n 'def _commit_ledger' src/bmad_loop/sweep.py -A30 | head -40

echo ""
echo "==== StoryTask restore_patch field ===="
rg -n 'restore_patch' src/bmad_loop/model.py -C3 || echo "NO MATCH"

Length of output: 8910

---

@pbean Reviewed the current state of main against your status update — everything checks out precisely.

Confirmed gaps in sweep.py (SweepEngine):

• No restore_patch reference anywhere in src/bmad_loop/sweep.py — confirmed via search, zero matches.
• _run_bundle (Line 508) resets task.phase = Phase.PENDING on a mid-bundle resume but has no re-arm path analogous to runs.rearm_escalation (src/bmad_loop/runs.py, Line 508) that would flip a bundle spec to in-review on a latched restore.
• _dev_prompt → _generic_bundle_prompt (Line 974-999) branches only on feedback is None vs. repair, with no task.restore_patch check or spec-pointer intent framing — unlike Engine._dev_prompt's explicit restore_patch-aware branch in engine.py (Line 2133-2138) that points step-01 at the in-review spec.
• No call to anything like Engine._restore_patch (engine.py, Line 877, invoked at Line 1452 gated on feedback is None) before _run_story/dispatch in the bundle path — so a latched patch is never re-applied onto the bundle's baseline.
• _commit_ledger (Line 869) and the bundle commit path show no latch-clearing logic once a restored bundle change lands.

Confirmed head-start already on main:

• verify.verify_dev_exclude_relpaths(paths, spec_path, task.restore_patch) is indeed wired at all three call sites in verify.py, including the bundle path at Line 1299 (the other two at Lines 1143 and 1186). StoryTask.restore_patch (Line 191 in model.py) is a generic field already serialized/deserialized (Lines 246, 292), so it's available to bundle tasks without schema changes — a real head-start for whoever implements the sweep-side wiring.

So your assessment is accurate: the T4 proof-of-work protection is already bundle-aware, but the three sweep-specific behaviors (re-arm to in-review, patch re-apply pre-dispatch, latch-clear on commit) are still fully unimplemented in sweep.py. Nothing to correct here — this issue remains accurately scoped and open.

---

✏️ Learnings added

Learnt from: pbean
URL: https://github.com/bmad-code-org/bmad-loop/issues/75

Timestamp: 2026-07-08T22:33:39.950Z
Learning: In bmad-code-org/bmad-loop, the intent-gap patch-restore re-drive mechanism (BMAD-METHOD `#2564`) has two reference implementations to mirror when extending to new workflows: `runs.rearm_escalation` (src/bmad_loop/runs.py, restore branch) which re-arms a task to `in-review` on a latched `restore_patch`, and `Engine._restore_patch`/`Engine._dev_prompt` (src/bmad_loop/engine.py) which re-applies the saved patch onto the baseline before dispatch, gated on `feedback is None` so fixable-feedback retries that keep the attempt's tree are never double-applied. As of the `#86` merge, story/sprint workflows have this; the sweep/deferred-work bundle workflow (src/bmad_loop/sweep.py, `SweepEngine`) does not yet implement restore_patch handling (see `_run_bundle`, `_dev_prompt`/`_generic_bundle_prompt`, `_commit_ledger`), though `StoryTask.restore_patch` is a generic already-serialized field and `verify.verify_dev_exclude_relpaths` in verify.py is already wired at the bundle call site (~Line 1299), giving a head start for a future sweep implementation. Tracked in issue `#75`.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.