Ship: Handoff

Commit the related changes, push the branch, create or update the PR, then keep looping until GitHub checks are fully green and the PR is merge-ready.

Do not stop when the PR is created. Do not stop while any GitHub check is pending. If any GitHub check fails, fix the problem, push again, and wait again. If the PR is not merge-ready, sync with base or resolve conflicts inside the same fix loop.

Escalate to the user only for judgment decisions or after retry limits are exhausted.

Done means every condition in Completion is satisfied: the PR exists, checks are green with no relevant pending contexts, the PR is merge-ready with no unresolved conflicts or required branch update, and no actionable review or bot feedback remains.

(Full termination + escalation criteria in "Completion" at the bottom.)

Process Flow

Run this loop:

1. Pre-flight: resolve the branch, task context, and related changes to ship.
2. Run the relevant local verification.
3. Update any required changelog or directly affected docs.
4. Commit the related changes.
5. Push the branch.
6. Create or update the PR.
7. Inspect .github/workflows and current PR checks so you know what this repo treats as CI/CD.
8. Wait until GitHub checks finish.
9. If any relevant check is still pending, keep waiting.
10. If any relevant check fails, or an AI review workflow leaves actionable comments, fix the problem, verify the fix, commit, push, and wait again.
11. If the branch must be updated from base to clear drift, conflicts, or repo policy, sync with base inside the fix loop, then verify, commit, push, and wait again.
12. If the PR is not merge-ready, fix the cause inside the same loop.
13. Ignore cancelled checks unless they block the repo's normal CI/CD path.
14. Stop after 3 fix rounds and escalate to the user.

Red Flag

Never:

• Stop when the PR is created — #1 failure mode
• Push code changes without re-running relevant local verification
• Force push without --force-with-lease
• Rewrite an already-pushed PR branch when there are human review, approval, or shared-branch signals
• Treat pending checks as "good enough"
• Treat green checks as sufficient when mergeStateStatus is still blocked
• Create the PR before local verification runs
• Use git add -A when unrelated local changes are present
• Forget to stage and commit changelog or doc edits before the first push
• Mark a thread or comment as resolved before the fix is actually pushed
• Resolve comments that still need product, security, or architecture judgment
• Fix failures without reading the actual check logs or review comments
• Sync with base preemptively — only when drift, conflicts, or repo policy require it
• Loop past 3 fix rounds — escalate instead
• Leave doc debt implicit — carry it into the PR

Progress Tracking

Use TodoWrite to track your own progress through the handoff phases. Create todos at the start based on what the repo actually needs. Not every repo has a CHANGELOG, CI, or docs to update — only include items for work that will actually happen.

Principle: one todo per phase the user would wait on. Fix rounds are dynamic — add them only when a check fails.

Example (repo with CHANGELOG and CI):

TodoWrite([
  { content: "Pre-flight (resolve branch and scope)", status: "in_progress", activeForm: "Resolving branch and scope" },
  { content: "Run local verification",                status: "pending",     activeForm: "Running local verification" },
  { content: "Update CHANGELOG and docs",             status: "pending",     activeForm: "Updating CHANGELOG and docs" },
  { content: "Push and create PR",                    status: "pending",     activeForm: "Pushing and creating PR" },
  { content: "Wait for GitHub checks",                status: "pending",     activeForm: "Watching PR checks" }
])

Adaptations (not exhaustive — use judgment):

• No CHANGELOG.md and no doc changes needed → drop that item entirely
• No CI workflows and no PR check contexts after PR creation → drop "Wait for GitHub checks"
• Check fails → insert "Fix round N/3 — <issue summary>" with in_progress
• PR already exists (update flow) → rename "Push and create PR" to "Push update to existing PR"

Phase 1: Pre-flight

Resolve only the context needed to ship the PR:

1. Determine the current branch.
   • If HEAD is detached, create a feature branch before continuing.
2. Determine the base branch:
   • use the existing PR base if a PR already exists
   • otherwise use the repo default branch
3. If the current branch is the base branch, create a feature branch before continuing.
4. Inspect the current scope with git status --short, git diff <base>...HEAD --stat, git diff --cached --stat, and git diff --stat.
5. Decide which local changes belong to this handoff.
6. Do not use git add -A unless every dirty file belongs to this handoff.
7. If unrelated local changes cannot be separated safely, stop and escalate instead of guessing.
8. If the caller already provides task_dir, use it. Otherwise do not guess one here; resolve it only if a later phase needs to write artifacts.

Output a short start summary with the branch, base branch, and scope being shipped.

Phase 2: Verify Before PR

Before the first push in handoff, run the most relevant local verification available for this repo.

• Prefer the same commands the repo or CI already uses.
• Run only the checks that are relevant to the changed area: tests, lint, typecheck, build, or targeted smoke checks as applicable.
• If code changes during handoff, run the relevant verification again before the next push.
• If a task directory already exists, do not invent extra artifacts just for handoff.
• If verification fails, fix the issue before pushing.

Output a short summary of what was run and whether it passed.

Phase 3: Update CHANGELOG and Docs

Step A: CHANGELOG (auto-generate)

[ -f CHANGELOG.md ] || echo 'NO_CHANGELOG'

• No CHANGELOG.md → skip silently.

If CHANGELOG.md exists:

1. Read header to learn the format
2. Generate entry from: git log <base>..HEAD --oneline
3. Categorize: Added / Changed / Fixed / Removed
4. Insert after header, dated today
5. Commit: git add CHANGELOG.md && git commit -m "docs: update CHANGELOG"

After changelog handling, check whether the shipped changes also changed any user-facing or repo-facing documentation truths before the first push.

Use references/documentation.md for the documentation decision tree and ownership rules.

• Only inspect docs that directly describe the changed commands, config, file paths, workflow, or behavior.
• Do not scan every markdown file in the repo.
• Route each changed truth to the narrowest correct document instead of defaulting to top-level docs.
• If a doc is mechanically stale, fix it in the same handoff loop.
• If the doc issue is semantic and you are not confident about the right wording, carry that note into the PR instead of inventing an explanation.
• Before moving on, explicitly record one of:
  • docs updated
  • docs checked, no update needed
  • doc debt to note in the PR

Phase 4: Push and Create PR

When opening or updating the PR, keep the title and body concise.

Include only:

• what changed
• what local verification ran
• any known follow-up, risk, or skipped check

Do not invent a long template if the change is simple.

Push and create:

1. Review the final diff, then stage all related changes that should ship now, including any changelog or doc edits made in this handoff.
2. Commit the staged changes if anything new was staged in this phase.
3. git push -u origin HEAD
4. Create the PR if it does not exist.
5. If the PR already exists, update the body or add a short comment with the latest verification summary.
6. If task_dir exists, write or update <task_dir>/handoff.md with: PR URL, branch, base, verification commands/results, docs outcome, current check summa