/handoff

name: handoff
version: 0.5.0
description: >
  Ship completed work: verify locally, commit related changes, push, create or
  update the PR, watch CI/reviews, and fix until merge-ready or escalated. Use
  for "ship it", "create PR", "handoff", or finished code needing delivery.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - Agent
  - AskUserQuestion
  - Monitor
  - TaskStop
  - mcp__codex__codex
  - mcp__codex__codex-reply

Ship: Handoff

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.

This is a goal-directed loop, not a counted one. Keep looping while each round makes progress toward the completion conditions; escalate on evidence, never on a round counter — the specific evidence classes are in [Loop Governance](#loop-governance). Done means every condition in [Completion](#completion) is satisfied.

Process Flow

Phase index — the phases below own the detail:

1. Pre-flight (resolve branch, base, and scope) 2. Verify locally 3. Update changelog / directly affected docs 4. Push and create/update the PR 5. Wait for GitHub checks 6. Fix loop — governed by the round ledger, not a counter

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
• Silently ignore a comment — a decline is a visible reply with a reason
• Apply "further fixes add no value" to CI or merge-readiness — that

judgment exists only for the comment decline classes

• Fix failures without reading the actual check logs or review comments
• Sync with base preemptively — only when drift, conflicts, or repo policy require it
• Re-attempt a fix for a failure signature that already survived a fix

aimed at it — the second identical outcome is evidence the approach is wrong; escalate with the ledger instead of iterating on hope

• Count rounds as a stopping condition — progress, judgment, and external

blockers are the only reasons to stop looping

• Leave doc debt implicit — carry it into the PR

---

Loop Governance

Modern harnesses run goal-directed loops natively — a fixed retry cap abandons hard-but-progressing PRs while adding no safety that progress detection doesn't provide better. The loop is governed by three things:

**1. Progress detection (the round ledger).** Every fix round appends one block to `<task_dir>/handoff.md` (or tracks inline when no task dir):

Round <i>: trigger=<check name + error class, or "conflict"/"review">
  action=<what was changed, one line>
  result=<next terminal state: new signature | same signature | green>

Before starting a round, compare the current failure to the ledger:

• **New failure signature** (different check, or same check failing

differently) → progress; loop.

• **Same signature after a fix aimed at it** → the approach is wrong.

Escalate with the ledger as evidence — do not iterate on hope.

• The ledger survives context compaction; after a compaction, trust it

over recollection.

**2. Judgment boundaries.** Product/security/architecture review comments, conflicts you cannot resolve confidently, and rebase-policy dead ends escalate immediately regardless of progress. A fix that would change the shipped behavior (not just repair its delivery) is scope drift — escalate; the fix loop repairs delivery, it does not redesign.

**3. The harness's own goal net.** Under `/ship:auto`, the stop gate already blocks session exit until the PR is merge-ready. In a standalone run on a harness with a native goal condition (e.g. Claude Code's `/goal`), suggest the user arm one at the start — `PR checks green and merge-ready, or stop after 25 turns` — as the outer bound; the harness's turn bound replaces any hand-rolled cap.

Progress Tracking

Track your progress with the harness's task/todo list. Create the items 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 item per phase the user would wait on. Fix rounds are dynamic — add them only when a check fails.

---

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 verificatio