Checkpoint Lab — Pull Requests, Drafts, Linked Issues, Change Sets, and Collaboration Patterns

1. Checkpoint mission and evidence package

Build c07-pr-checkpoint and produce evidence for: repository/default branch, Issue URL/state, topic branch OIDs, PR number/state, base/head refs and OIDs, commit list, three-dot diff summary, closing-Issue relationship, check rollup, draft→ready transition, controlled base change, relationship change caused by non-default base, restored base, and a written handoff policy.

2. Preflight and collision gate

gh auth status --active --hostname github.com
OWNER=$(gh api user --jq .login)
REPO="c07-pr-checkpoint"

gh repo view "$OWNER/$REPO" >/dev/null 2>&1 && {
  echo "STOP: repository already exists" >&2
  exit 2
}

3. Create source Issue and a release-base branch

gh repo create "$OWNER/$REPO" --public --add-readme --clone
cd "$REPO"
DEFAULT_BRANCH=$(git branch --show-current)

ISSUE_URL=$(gh issue create   --title "Docs: publish retry handoff criteria"   --body "Synthetic Chapter 07 checkpoint issue.")
ISSUE_NUMBER=${ISSUE_URL##*/}

# Create a non-default candidate base with one harmless independent commit.
git switch -c release/c07
printf '
Release branch marker for Chapter 07 checkpoint.
' >> README.md
git add README.md
git commit -m "chore: add release branch marker"
git push -u origin release/c07
RELEASE_OID=$(git rev-parse HEAD)

# Return to default before creating the topic so the topic does NOT inherit release/c07.
git switch "$DEFAULT_BRANCH"

The release branch exists only to make the base-change exercise observable. The topic will start from the default branch, so changing the PR base later changes the comparison target but does not rewrite the topic branch.

4. Create the topic branch and first commit

git switch -c docs/retry-handoff
cat >> README.md <<'EOF'

## Retry handoff
A retry change is ready for review when scope, validation, and rollback notes are documented.
EOF

git add README.md
git commit -m "docs: add retry handoff criteria"
git push -u origin docs/retry-handoff
TOPIC1=$(git rev-parse HEAD)

5. Prediction 1: opening a draft PR changes hosted review state, not branch OIDs

Write this prediction in your evidence notes before executing: the PR will become a new GitHub resource, its head will point at TOPIC1, its base will point at the default branch, and Closes #N will establish a closing relationship because the target is the default branch; neither branch OID should move merely because the PR was opened.

PR_BODY=.c07-checkpoint-pr-body.md
cat > "$PR_BODY" <<EOF
Closes #$ISSUE_NUMBER

Checkpoint PR: review scope, validation, and rollback notes.
EOF

PR_URL=$(gh pr create   --base "$DEFAULT_BRANCH"   --head docs/retry-handoff   --draft   --title "docs: define retry handoff"   --body-file "$PR_BODY")
PR_NUMBER=${PR_URL##*/}

gh pr view "$PR_NUMBER" --json   number,state,isDraft,baseRefName,baseRefOid,headRefName,headRefOid,closingIssuesReferences,url

git rev-parse HEAD
git ls-remote origin "refs/heads/$DEFAULT_BRANCH" "refs/heads/docs/retry-handoff" "refs/pull/$PR_NUMBER/*"

6. Prove the initial change set and evidence planes

git fetch origin "$DEFAULT_BRANCH" docs/retry-handoff

git log --oneline "origin/$DEFAULT_BRANCH..origin/docs/retry-handoff"
git diff --stat "origin/$DEFAULT_BRANCH...origin/docs/retry-handoff"

gh pr diff "$PR_NUMBER" --name-only
gh pr view "$PR_NUMBER" --json commits,files,statusCheckRollup,reviewDecision,reviewRequests

gh api -H "Accept: application/vnd.github+json"   -H "X-GitHub-Api-Version: 2026-03-10"   "repos/$OWNER/$REPO/pulls/$PR_NUMBER"   --jq '{number,state,draft,mergeable,base:.base.ref,head:.head.ref,head_sha:.head.sha}'

7. Add a review-preparation commit and verify same-PR evolution

cat >> README.md <<'EOF'

Rollback note: revert the documentation commit if the guidance proves incorrect.
EOF

git add README.md
git commit -m "docs: add rollback note"
git push
git fetch origin "$DEFAULT_BRANCH" docs/retry-handoff
TOPIC2=$(git rev-parse HEAD)

gh pr view "$PR_NUMBER" --json number,headRefOid,commits,files,updatedAt

git log --oneline "origin/$DEFAULT_BRANCH..origin/docs/retry-handoff"

The second commit should appear in the existing PR. If GitHub shows a new PR number, you opened another PR rather than updating the head branch.

8. Mark ready and capture handoff state

gh pr ready "$PR_NUMBER"

gh pr view "$PR_NUMBER" --json   number,isDraft,state,reviewRequests,reviewDecision,statusCheckRollup,closingIssuesReferences,headRefOid

gh pr checks "$PR_NUMBER" || true

Record whether checks exist. “No checks reported” is acceptable in this disposable repository. Readiness is a collaboration signal, not proof that checks or reviews are complete.

9. Prediction 2: changing to a non-default base changes PR comparison/relationship, not topic history

Before acting, write: changing the PR base from the default branch to release/c07 will mutate PR base metadata and comparison context. The topic branch OID TOPIC2 must not change. Because the PR no longer targets the default branch, the closing keyword is no longer eligible to auto-close the Issue on merge; GitHub may also stop presenting it as a closing relationship. The Issue itself should remain open either way because we never merge.

10. Change the base and independently prove the result

BEFORE_HEAD=$(gh pr view "$PR_NUMBER" --json headRefOid --jq .headRefOid)

gh pr edit "$PR_NUMBER" --base release/c07

gh pr view "$PR_NUMBER" --json   number,baseRefName,baseRefOid,headRefName,headRefOid,commits,files,closingIssuesReferences

git fetch origin release/c07 docs/retry-handoff
printf 'local_topic='; git rev-parse origin/docs/retry-handoff
printf 'before_head='; printf '%s
' "$BEFORE_HEAD"

printf 'merge_base='; git merge-base origin/release/c07 origin/docs/retry-handoff

git log --oneline "origin/release/c07..origin/docs/retry-handoff"
git diff --stat "origin/release/c07...origin/docs/retry-handoff"

gh issue view "$ISSUE_NUMBER" --json number,state,url

Because release/c07 has an independent commit that the topic does not contain, the two branches diverge. The head OID still should equal TOPIC2. The exact three-dot file diff remains focused on what the topic introduced from the merge base; the PR’s base coordinate and closing-keyword semantics are the important hosted changes. Inspect closingIssuesReferences as evidence, but treat the documented non-default-base rule—not a particular UI rendering—as the authoritative reason auto-close is inactive.

11. Restore the intended default-branch target and verify relationship recovery

gh pr edit "$PR_NUMBER" --base "$DEFAULT_BRANCH"

gh pr view "$PR_NUMBER" --json   baseRefName,baseRefOid,headRefName,headRefOid,closingIssuesReferences

git fetch origin "$DEFAULT_BRANCH" docs/retry-handoff
git log --oneline "origin/$DEFAULT_BRANCH..origin/docs/retry-handoff"
git diff --stat "origin/$DEFAULT_BRANCH...origin/docs/retry-handoff"

The PR should again target the default branch; verify the closing relationship through structured PR output. The Issue remains open because the PR remains unmerged.

12. Write the PR handoff criteria before merge

13. Final verification checklist

• Issue is still open and its URL/number is preserved.
• PR is open and ready, with base restored to the default branch.
• Head OID equals the last pushed topic commit.
• Local git log base..head shows only the intended topic commits.
• Local three-dot diff and hosted Files changed agree on the intended file scope.
• Closing-Issue relationship exists only after restoring the default-branch target.
• Check/review state is recorded without being mistaken for deployment evidence.
• No force push, merge, repository transfer, secret change, or policy bypass was needed.

14. Cleanup and rollback

Close the PR without merging, then archive the disposable repository only after verifying its exact identity. Closing preserves the not-merged outcome and archiving makes the repository read-only while retaining the evidence. Permanent deletion is optional and should be performed separately only after a second identity check.

gh pr close "$PR_NUMBER" --comment "Chapter 07 checkpoint complete; intentionally not merged."
cd ..
printf 'archive-check=%s/%s
' "$OWNER" "$REPO"
gh repo archive "$OWNER/$REPO"
rm -rf "$REPO"

15. What Chapter 07 adds to the production GitHub operating model

Chapter 07 adds the primary change-control object: a PR that names intended integration coordinates, keeps reviewable change scope observable, links work deliberately, records human/automated evidence, and evolves as its head ref moves. The operating model can now distinguish “code proposed,” “review requested,” “checks reported,” “merged,” and “deployed” as separate facts.

16. Bridge to Chapter 08: Code Review discipline

This checkpoint deliberately stopped before substantive review. Chapter 08 takes the PR’s Files changed and conversation surfaces and turns them into a disciplined review system: suggested changes, CODEOWNERS, review requests, review states, reviewer responsibility, and how to avoid rubber-stamp approvals.

Knowledge check

Authoritative references

• About pull requests
• Changing a pull request base branch
• Changing the stage of a pull request
• Linking a pull request to an issue
• Branches and pull-request comparisons
• Comparing commits
• gh pr create
• gh pr ready
• gh pr edit
• gh pr view
• gh pr diff
• gh pr checks
• REST API endpoints for pull requests
• REST API versions