Skip to content

feat: run build passes in per-branch git worktrees - #24

Merged
jeremymcs merged 1 commit into
mainfrom
patch/issue-22-build-worktrees
Aug 22, 2026
Merged

jeremymcs merged 1 commit into
mainfrom
patch/issue-22-build-worktrees

Conversation

@jeremymcs

Copy link
Copy Markdown
Member

Summary

Implements the O-1..O-9 outcomes of #22: a build or repair pass now works in a dedicated git worktree at <repo>-worktrees/<flattened-branch> (sibling of the main tree) instead of checking its gsd/NNN-* branch out in the repository's main working tree. The main tree stays on the default branch across a pass and dependency installs never touch it.

The change is playbook prose (loop/build.md) plus wording fixes in README.md/docs/install.md (which used "worktree" loosely to mean "checkout") — no code changes, since the loop is agent-executed and lib/process.mjs is not involved in checkout location.

Open decisions in the issue resolved as:

  • O-9 — detected fallback, no new config surface: a pass attempts git worktree add; on failure it falls back to the current in-tree checkout under the existing dirty-worktree guards and discloses it via the worktree-fallback result reason.
  • O-4 — cleanup rides the recovery sweep: "Pick up after a dead pass" now lists gsd worktrees and removes any whose branch's PR is merged/closed or whose branch is gone from origin, before claiming new work. A successful pass explicitly leaves its worktree for this sweep.

Exclusions X-1..X-5 honored: no changes to review/spec/discover lanes, selection or verdict logic, branch naming, or merge semantics.

Closes #22

Test plan

  • bash tests/run.sh — all suites pass, including 9 new literal contract greps in tests/playbook_contract_test.sh pinning the new build.md prose
  • node tests/npm_package_test.mjs — passes
  • Note: the issue's behavioral testing notes (worktree create/reuse/remove against a scratch clone) have no executable harness — playbooks are agent-executed prose, and the repo's established pattern for playbook changes is contract greps. The issue's manual walkthrough remains the real end-to-end check.

Closes the checkout-location half of the loop: a build or repair pass now
works in a dedicated git worktree at <repo>-worktrees/<flattened-branch>
(sibling of the main tree) instead of checking its gsd/NNN-* branch out in
the repository's main working tree. The main tree stays on the default
branch across a pass and dependency installs never touch it.

Open decisions in the issue resolved as follows:

- O-9: detected fallback, no new config surface. A pass attempts
  `git worktree add`; if worktrees are unavailable or creation fails, it
  falls back to the current in-tree checkout behavior under the existing
  dirty-worktree guards and says so in the report and result `reason`
  (`worktree-fallback`).
- O-4: cleanup rides a later pass's recovery sweep. "Pick up after a dead
  pass" now starts by listing gsd worktrees and removing any whose branch's
  PR is merged/closed or whose branch is gone from origin, followed by
  `git worktree prune`, before claiming new work. Passes never merge, so
  no pass removes its own worktree.

Also updates the interrupted-pass recovery states to resolve against
worktrees (same verdicts as today), reuses existing worktrees on resume,
leaves a failed pass's worktree in place with its path named, clarifies
the `dirty-worktree` result reason, and fixes the loose "worktree" wording
(meaning "checkout") in README.md and docs/install.md.

Review passes, issue selection, verdict semantics, branch naming, and the
spec/discover playbooks are unchanged per X-1..X-5.
@jeremymcs
jeremymcs merged commit 3e9d143 into main Aug 22, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Build passes should use a per-branch git worktree instead of checking out in the main working tree

1 participant