Skip to content

fix(worktree): use hard reset to correct file tree when branch base is wrong#1982

Merged
trek-e merged 2 commits intogsd-build:mainfrom
Tibsfox:fix/worktree-hard-reset-1981
Apr 10, 2026
Merged

fix(worktree): use hard reset to correct file tree when branch base is wrong#1982
trek-e merged 2 commits intogsd-build:mainfrom
Tibsfox:fix/worktree-hard-reset-1981

Conversation

@Tibsfox
Copy link
Copy Markdown
Contributor

@Tibsfox Tibsfox commented Apr 8, 2026

Summary

Fixes the worktree_branch_check mitigation that was using git reset --soft to correct wrong worktree base branches. The soft reset only moved the commit pointer — the working tree still contained main's files, causing silent data loss when the agent's commits overwrote feature branch code on merge-back.

  • Changed --soft to --hard in all 4 workflow files that spawn worktree agents (execute-phase.md, quick.md, execute-plan.md, diagnose-issues.md). This is safe because the check runs as the very first action before any agent work — there are no uncommitted changes to lose.
  • Removed the broken git rebase --onto attempt in execute-phase.md that could replay main's commits onto the feature branch if it succeeded.
  • Added post-reset verification that aborts with exit 1 if the correction fails, preventing the agent from proceeding on a wrong branch base.
  • Updated documentation from "Windows" to "all platforms" since the upstream EnterWorktree bug affects macOS, Linux, and Windows alike (as reported in Worktree isolation branches from main instead of current branch (macOS, not just Windows) #1957).
  • Aligned settings.md worktree description to remove Windows-specific language, matching the workflow files.

Why --soft was wrong

git reset --soft moves HEAD but preserves the working tree and index. After the reset:

  • Branch pointer → correct (feature branch HEAD) ✓
  • Working tree → still main's files ✗
  • Index → still main's files ✗

The agent then committed diffs against main's file state on top of the feature branch history. On merge-back, these commits overwrote the feature branch with main's code — exactly the data loss reported in #1957.

Why --hard is safe here

The worktree_branch_check runs as "FIRST ACTION before any other work" in a freshly-created worktree. At that point the agent has made zero uncommitted changes and done zero work. git reset --hard correctly resets the commit pointer, working tree, and index to the expected feature branch state.

Closes #1981
Related: #1957

Test plan

  • All 2735 tests pass (1 pre-existing failure in stale-colon-refs.test.cjs unrelated to this change)
  • Verified no remaining reset --soft.*EXPECTED_BASE references in the codebase
  • Adversarial security review passed (0 critical/high/medium findings)
  • Manual verification: run /gsd-execute-phase with workflow.use_worktrees: true on a feature branch diverged from main — confirm worktree agents operate on the correct file tree

🤖 Generated with Claude Code

Tibsfox and others added 2 commits April 8, 2026 04:03
…s wrong (gsd-build#1981)

The worktree_branch_check mitigation detects when EnterWorktree creates
branches from main instead of the current feature branch, but used
git reset --soft to correct it. This only fixed the commit pointer —
the working tree still contained main's files, causing silent data loss
on merge-back when the agent's commits overwrote feature branch code.

Changed to git reset --hard which safely corrects both pointer and file
tree (the check runs before any agent work, so no changes to lose).
Also removed the broken rebase --onto attempt in execute-phase.md that
could replay main's commits onto the feature branch, and added post-reset
verification that aborts if the correction fails.

Updated documentation from "Windows" to "all platforms" since the
upstream EnterWorktree bug affects macOS, Linux, and Windows alike.

Closes gsd-build#1981

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…latform

Aligns with the workflow file updates — the EnterWorktree base-branch
bug affects all platforms, not just Windows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@Tibsfox Tibsfox requested a review from glittercowboy as a code owner April 8, 2026 11:07
Copy link
Copy Markdown
Collaborator

@trek-e trek-e left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review: APPROVE

Summary

The root cause analysis is correct. git reset --soft moves HEAD but leaves working tree and index unchanged — in a freshly created worktree where no work has been done yet, this means the working tree retains the wrong (main's) files while the commit pointer moves. The subsequent commits are made against main's file tree, causing silent data loss on merge-back.

--hard is safe here precisely because the check runs as the first action before any agent work.

Changes verified

All 4 workflow files updated consistently:

  • execute-phase.md: Removed the broken git rebase --onto attempt, replaced soft reset with hard reset + verification guard (exit 1 on failure)
  • quick.md: Hard reset + verify guard
  • execute-plan.md: Documentation line updated to describe hard reset + verify
  • diagnose-issues.md: Same pattern
  • settings.md: Windows-specific language removed, cross-platform note added

The post-reset verification ([ "3312de5e35a1066dee6c7752cf30a596bd067e30" != "{EXPECTED_BASE}" ] && exit 1) correctly aborts the agent if the correction fails, preventing work on a wrong base.

No issues found

@trek-e trek-e added the review: approved PR reviewed and approved by maintainer label Apr 10, 2026
@trek-e trek-e merged commit adec4ee into gsd-build:main Apr 10, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review: approved PR reviewed and approved by maintainer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(worktree): branch check uses reset --soft which fails to correct file tree

2 participants