cmd_run refuses to start on a dirty main tree; cmd_resume has no such gate

Open Beginner friendly

#621 opened on Aug 15, 2026 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty: 2/5
Estimated time: 1-3 hours
Newbie friendliness: 68/100

Issue type: Documentation
Clarity: Mostly clear
Activity status: Quiet
Tech stack: python
Domain: cli, documentation

Research direction

Read cmd_run at src/bmad_loop/cli.py:1703 and cmd_resume at src/bmad_loop/cli.py:2273, then compare the existing worktree_clean checks in cmd_validate, cmd_run, and cmd_sweep. Review the isolation behavior described in docs/FEATURES.md and resolve whether resume's asymmetry is intentional; done means the decision and its rationale are documented at the relevant entry point and in the feature documentation.

Written by the indexing model from the issue text.

Description

area:engine documentation P3 question

cmd_run refuses to start on a dirty main tree (src/bmad_loop/cli.py:1703):

if not verify.worktree_clean(paths.repo_root):
    print("git worktree is not clean — commit or stash first", file=sys.stderr)
    return 1

cmd_resume (src/bmad_loop/cli.py:2273) has no equivalent check — worktree_clean appears in
cmd_validate, cmd_run and cmd_sweep, and nowhere in the resume path.

Whether that asymmetry is intended is worth stating one way or the other. There is a coherent
argument for it: a resume continues a run whose worktrees already exist, and under
[scm] isolation = "worktree" the main checkout is explicitly expected to be usable while a run
is in flight (docs/FEATURES.md: "the main checkout stays free while a run is in flight"), so
demanding a clean tree to resume would refuse the very workflow the feature invites. There is also
an argument against: under isolation = "none" a resume drives the loop in the main checkout,
where pre-existing dirt is the same hazard cmd_run refuses over.

This surfaced while scoping #460. The gate is what bounds that issue's practical reach — a fresh
run cannot begin over pre-existing dirt, so the reachable triggers are dirt appearing after the
run starts, plus every resume — and that reasoning only holds while the asymmetry is deliberate
and documented. Right now it is neither confirmed nor written down.

Cheapest resolution may be a comment at the resume path plus a line in docs/FEATURES.md, rather
than a behavior change.

Dominant language: Python
Stars: 137
Forks: 60
Avg merge: 1d 3h
Merged PRs (30d): 44

Contributor guide

Open the contributing guide

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.