shipping-a-pr

1# Shipping a PR
2 
3The PR lifecycle: ship the workspace's finished work, maintain PR metadata, and keep the PR healthy
4when requested. One workflow, six phases as sibling docs — enter at the phase the ask names.
5 
6## Completion modes
7 
8- **Snapshot mode is the default** for creating, syncing, or updating a PR and for one-time status
9  requests. Take one fresh checks and merge-state snapshot, report pending/failing/indeterminate state
10  as observed, and stop without polling or fixing unrelated state. A push never upgrades the mode by
11  itself.
12- **Wait mode requires an explicit remote-completion ask**: monitor or watch checks, investigate CI,
13  wait until green, or make the PR merge-ready. Done means every configured check is green, the head
14  is current with its base, and GitHub reports an affirmative merge state; a requested draft is
15  reported as draft, never merge-ready. A repo with no CI is reported as exactly that, never silently
16  green.
17 
18## Observed, never assumed (applies to every phase)
19 
20Git and GitHub state is concurrent and mutable: the base moves, CI lags, mergeability is computed
21lazily, and this workflow's own steps dirty the tree they just checked. Four rules hold at every
22step of every phase:
23 
24- **Verify at the point of action.** An irreversible step — push, `gh pr create`, `gh pr edit`,
25  replying to a thread, declaring done — re-checks the exact state it consumes immediately before
26…