docs(runbooks): PR creation from linked worktrees (ag-9zls #worktree-pr-runbook)#775
Draft
boshu2 wants to merge 1 commit into
Draft
docs(runbooks): PR creation from linked worktrees (ag-9zls #worktree-pr-runbook)#775boshu2 wants to merge 1 commit into
boshu2 wants to merge 1 commit into
Conversation
…ls #worktree-pr-runbook) Document the verified root cause of 'No branch name available for PR creation' from linked-worktree branches: 'git worktree add -b <b> origin/main' inherits upstream tracking from main, so branch.<b>.merge = refs/heads/main and any PR tool that infers head from upstream resolves it to main. Fix: 'git push -u origin HEAD:<b>' rewrites tracking to the branch. Adds a three-tier PR-creation path (gh --head / gh api / compare-URL) that never relies on head inference, plus prevention options. Validated live in this repo; index entry added. Closes-scenario: ag-9zls#worktree-pr-runbook Bounded-context: BC5-Runtime Evidence: docs/runbooks/pr-creation-from-linked-worktrees.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
docs/runbooks/pr-creation-from-linked-worktrees.md— root cause + verified fix for the background-agent bugag-9zls: "No branch name available for PR creation" from linked-worktree branches.Root cause (verified live)
git worktree add -b <branch> origin/maininherits upstream tracking from the start point, sobranch.<branch>.merge = refs/heads/main. Any PR tool that infers the head from upstream config resolves it tomain→ no distinct head → the error. The branch is pushed and real; only the inferred head is wrong.Fix
git push -u origin HEAD:<branch>rewrites tracking to the branch itself; always pass--head <branch>to PR creation. Runbook gives a three-tier path (gh--head/gh api/ compare-URL fallback for no-write-token agents) plus prevention.Evidence
This PR was itself opened from the linked worktree
docs/ag-9zls-worktree-pr-runbookusing the documented Tier-1 path — the before/after tracking flip was captured live.Checks
.markdownlint.json): passdocs/documentation-index.mdCloses-scenario: ag-9zls#worktree-pr-runbook
Bounded-context: BC5-Runtime
Evidence: docs/runbooks/pr-creation-from-linked-worktrees.md