feat: add --branch flag to wt step commit

[worktrunk-bot]

Summary

• Adds --branch / -b flag to wt step commit, allowing commits in a different worktree without cd-ing there: wt step commit -b feature-x
• Adds CommandEnv::for_branch() constructor that resolves a worktree path from a branch name
• Updates CommitOptions::commit() to use the context's worktree_path for git operations (staging, status, commit) instead of hardcoding current_worktree() — this makes it work correctly for both the default (cwd) and --branch cases

This is the first step toward #1637. The --branch flag can later be added to other step subcommands and eventually to wt merge.

Test plan

• test_step_commit_branch_flag — commits to a feature worktree while cwd is the main worktree, verifies the commit lands in the correct worktree
• test_step_commit_branch_flag_nonexistent — errors cleanly when the branch has no worktree
• All 1261 integration tests pass
• Help snapshots and doc sync updated automatically

🤖 Generated with Claude Code

[max-sixty]

what happens on a detached worktree?

[worktrunk-bot]

A detached worktree can't be targeted with --branch — you get "no worktree for branch 'X'". The lookup in worktree_for_branch() matches on the branch field, which is None for detached worktrees, so it never finds a match.

This is consistent with the project's model of addressing worktrees by branch name. If you're in a detached worktree, wt step commit (without --branch) still works fine via cwd — you just can't target one remotely.

Should I add an explicit note about this in the help text, or is the current error message clear enough?

[max-sixty]

This is consistent with the project's model of addressing worktrees by branch name. If you're in a detached worktree, wt step commit (without --branch) still works fine via cwd — you just can't target one remotely.

ok great — would you mind confirming?

[worktrunk-bot]

I confirmed — my earlier claim was wrong. wt step commit (without --branch) does not work in a detached worktree. It fails with:

✗ Cannot commit: not on a branch (detached HEAD)
↳ To switch to a branch, run git switch <branch>

This is because CommandEnv::for_action() calls require_current_branch(), which errors on detached HEAD.

So the full picture for detached worktrees:

• --branch <name>: Can't target a detached worktree (no branch to look up) — errors with "no worktree for branch 'X'"
• No --branch (cwd): Also fails if the cwd worktree is detached — errors with the detached HEAD message above

Both are consistent with the worktree-by-branch model. If detached HEAD support for the cwd case is wanted, step_commit would need to use for_action_branchless() instead of for_action() — but that seems like a separate decision.

[max-sixty]

I think internally we should change to supply a worktree path, especially for commit, which doesn't work but worktree-less branches.

the external interface would remain the same

[worktrunk-bot]

Makes sense — CommandEnv would store and operate on worktree paths internally, with the --branch flag just being one way to resolve to a path (the other being cwd). That way commit could work in detached worktrees too, since the path is all git needs to stage and commit.

I'll rework for_branch() and for_action() to converge on a path-based internal model, keeping --branch as the external interface. The branch field becomes truly optional — populated when available but not required for the operation.

[max-sixty]

make these into a single line

[worktrunk-bot]

Done — combined into /// Branch to operate on (defaults to current worktree).