/guardian

PR Ship Flow Reference

Purpose: After PR preparation is complete (typically the output of the pr Recipe), execute the full delivery flow: create the PR, monitor CI, verify approval gates, merge, and clean up. Every state-changing step is a proposal — guardian does not auto-execute merges without explicit user consent.

Contents

• When to use ship vs pr
• Preconditions
• Workflow phases
• Command recipes
• Hard gates (cannot bypass)
• Ask First gates
• Risks and rollback
• Verification checklist
• Output template

When to Use

Preconditions

Before proposing ship commands, verify:

1. Working tree is clean: git status shows no uncommitted changes
2. Branch is pushed and up-to-date with base: git fetch origin && git log origin/<base>..HEAD shows expected commits; git log HEAD..origin/<base> is empty (or rebase recommended)
3. pr Recipe output exists: title, body, reviewer list, quality_score, risk_band
4. Quality gate passed: quality_score >= 65 (B grade or higher) — otherwise stop
5. Risk gate passed: risk_score <= 85 (not Critical) — otherwise require explicit override
6. Security gate passed: security_classification != CRITICAL — otherwise require Sentinel handoff completion
7. Intent alignment gate passed: Judge intent_alignment != FAIL — otherwise reconcile code with stated intent or obtain explicit waiver (NOT_CHECKED allowed only with an explicit unverified-intent note)
8. gh CLI authenticated: gh auth status succeeds
9. CI configuration discovered: detected required status checks from branch protection rules

If any precondition fails, stop and request confirmation or route to the appropriate Recipe.

Workflow

PREFLIGHT → CREATE → WATCH → GATE → MERGE → CLEANUP

Command Recipes

1. PREFLIGHT — Verify all gates

BASE="${BASE:-main}"
SRC="$(git branch --show-current)"

# State checks
git fetch origin "$BASE"
test -z "$(git status --porcelain)" || { echo "uncommitted changes"; exit 1; }
gh auth status >/dev/null || { echo "gh CLI not authenticated"; exit 1; }

# Quality gates (sourced from pr Recipe output)
# - quality_score >= 65
# - risk_score <= 85
# - security_classification != CRITICAL
# - intent_alignment != FAIL  (Judge verdict; NOT_CHECKED only with unverified-intent note)
# - noise_ratio <= 0.30
# - coverage_gap <= 0.40

2. CREATE — Open the PR

Build the body via HEREDOC to preserve formatting. Follow the canonical lean template (pr-workflow-patterns.md § PR Description Template): essence only — Summary + Test plan are the baseline; add ## Changes / ## Risk only when the change warrants them. Do not dump the pr Recipe's full Change Classification Table or Risk breakdown into the body — distill, don't paste.

gh pr create \
  --base "$BASE" \
  --head "$SRC" \
  --title "<pr Recipe title>" \
  --body "$(cat <<'EOF'
## Summary
<1-3 sentences from pr Recipe: why + what>

## Test plan
- <CI suite run>
- <manual verification, if any>
EOF
)" \
  --reviewer "<from pr Recipe>" \
  --label "<inferred from change classification>"

Add ## Changes (one bullet per distinct essential change) only when the Summary cannot carry them, and ## Risk only when the risk band is Medium+ — both distilled from the pr Recipe output, not pasted verbatim. Add ## Review focus only when the change crosses a public contract, persisted state, a security boundary, or another team's consumers (block spec → pr-workflow-patterns.md).

For low quality_score (B band 65-74) or first-pass validation, propose --draft:

gh pr create --draft ...   # signals direction-only review

3. WATCH — Monitor CI to terminal state

PR_NUMBER=$(gh pr view --json number -q .number)

# Poll with timeout
gh pr checks "$PR_NUMBER" --watch --interval 30 --fail-fast
# Exit codes: 0 = all passed, 1 = one or more failed/cancelled, 8 = pending timeout

Surface failing checks with diagnostic context:

gh pr checks "$PR_NUMBER" --required | awk '$2 == "fail" || $2 == "cancelled"'
gh run view --log-failed   # for the most recent failed run

4. GATE — Verify merge readiness

# All required checks green
gh pr view "$PR_NUMBER" --json mergeStateStatus,mergeable,reviewDecision,statusCheckRollup

# Expected:
# mergeStateStatus: CLEAN
# mergeable: MERGEABLE
# reviewDecision: APPROVED
# statusCheckRollup: all SUCCESS

Decision table:

5. MERGE — Ask First, then execute

# Strategy from `strategy` Recipe output (default: squash for feature branches)
gh pr merge "$PR_NUMBER" --squash --delete-branch
# Alternatives:
# gh pr merge "$PR_NUMBER" --rebase --delete-branch     # linear history
# gh pr merge "$PR_NUMBER" --merge --delete-branch      # preserve merge commit
# gh pr merge "$PR_NUMBER" --auto --squash              # queue when checks pass

If repository uses merge queue:

gh pr merge "$PR_NUMBER" --auto --squash
# GitHub merge queue handles batching and bisection

6. CLEANUP — Sync base, prune local

git checkout "$BASE"
git pull --ff-only origin "$BASE"
git branch -D "$SRC" 2>/dev/null || true
git remote prune origin

Verify merge landed:

git log --oneline -1 origin/"$BASE"   # should contain merged commit subject
gh pr view "$PR_NUMBER" --json state -q .state   # MERGED

Hard Gates (cannot bypass)

Ask First Gates

Never

• Auto-merge without explicit user consent
• Use --admin or otherwise bypass branch protection
• Delete unmerged branches
• Skip required CI checks
• Merge with failing security scans
• Force-push to the PR branch after approval without re-requesting review

Risks

Rollback

Pre-merge rollback (PR open):

gh pr close "$PR_NUMBER" --comment "Rolling back: <reason>"
# Branch remains; resume after fixes

Post-merge rollback (already merged):

# Revert commit on base (preferred — preserves history)
gh pr revert "$PR_NUMBER"   # opens a revert PR
# OR manual:
git checkout "$BASE" && git pull
git revert -m 1 <merge-commit-sha>
git push origin "$BASE"

If destructive recovery is needed (force-push reversal), escalate to user; never auto-execute.

Verification Checklist

Deliver this with every ship output:

• All preconditions satisfied (clean tree, pushed, base synced, gh authed)
• All hard gates passed (quality, risk, security, intent alignment, CI, approvals)
• PR title and body match pr Recipe output
• Reviewers requested per CODEOWNERS + expertise routing
• CI watched to terminal state (no premature merge)
• mergeStateStatus == CLEAN before merge
• Merge strategy matches strategy Recipe choice
• Branch deleted both locally and remotely
• Base branch synced post-merge
• PR final state confirmed as MERGED

Output Template

## Guardian Ship Plan

**Source**: `feat/payment-webhook` (HEAD: a1b2c3d)
**Base**: `origin/main`
**PR**: #1234 (to be created) | existing #1234
**Strategy**: squash + delete-branch
**Quality**: 88/100 (A) | **Risk**: Low (22/100) | **Security**: NEUTRAL

### Preflight
- Working tree: clean
- Base sync: up-to-date
- `gh` auth: OK
- Required checks discovered: `ci/test`, `ci/lint`, `ci/security-scan`

### Execution Script (proposal — Ask First on MERGE)

\```bash
# PREFLIGHT, CREATE, WATCH, GATE — see Command Recipes
# MERGE step prompts before execution
gh pr merge 1234 --squash --delete-branch
\```

### Hard Gates
- [x] quality_score 88 >= 65
- [x] risk_score 22 <= 85
- [x] security NEUTRAL
- [ ] CI to be verified at WATCH
- [ ] Approval to be verified at GATE

### Rollback
\```bash
gh pr revert 1234
\```

Orbit Boundary

• ship consumes pr Recipe output as input — it does not re-derive title/body/reviewers
• ship consumes strategy Recipe output for merge mode — defaults to --squash when absent
• For XXL/MEGA branches, refuse ship and route to split first
• For PRs requiring deep architecture review, route to judge before MERGE phase
• Release-coordinated merges (multiple dependent PRs) hand off to launch
• Auto-bisection of failing merge queue batches stays in merge queue's domain — ship only reports outcomes