ship-loop

$ship-loop — Bot-paired fast lane PR cycle

Codex orchestration default: when the operator types $ship-loop, run the 9-step cycle below. For fork-based OSS contributions use $pr-implement and the $pr-* family instead (different tier).

Capture of the discipline that lands single-scenario internal PRs at ~15-30 min median time-to-merge in repos with an auto-review bot workflow and gh pr merge --auto enabled.

When to use

| Use ship-loop when... | Use something else when... | |---|---| | Coherent-arc internal PR in your own repo (one closable bead or small-epic slice) | Fork-based OSS contribution → $pr-implement | | PR is the atomic-revert unit; scenarios ship-or-revert together | Large epic (15+ child beads) / multi-wave → $crank | | Closing a harvested next-work item | Architecture / contract change → slow lane / human review | | Mechanical drift fix or regression closure | Scenarios have independent rollback → split into separate arcs |

The 9-step cycle

1. Claim. bd ready → pick highest-severity unblocked, OR read .agents/rpi/next-work.jsonl for harvested items. bd update <id> --claim.
2. Branch off fresh main. git checkout main && git pull --rebase. Then git checkout -b <type>/<slug>-<bead-id>. Never stack off siblings.
3. First failing test. BDD scenario or unit test. Must fail for the right reason (asserting expected behavior). Per the project's L2-first/L1-always rule.
4. Minimal implementation. Smallest code change that makes the test green. Resist scope creep.
5. scripts/ship.sh (recommended) — auto-detects inventory-touching changes, runs the regen sweep, opens the PR. Mechanical fix for anti-pattern #1. CI (.github/workflows/validate.yml) is the sole authoritative push gate per docs/contracts/local-pre-push-gate-retirement.md (soc-g2r9, PR #357); the previous scripts/pre-push-gate.sh local mirror was retired. For per-tool sanity before push: cd cli && make test, bats tests/scripts/<file>.bats, scripts/regen-codex-hashes.sh. If a pre-existing blocker appears in unchanged-from-base content, file an atomic side-quest fix PR first (don't bundle). For PRs that change gate/validator/CI behavior: capture the targeted output line in PR body as Evidence:; the validate-pr-evidence-claims CI job (scripts/verify-gate-claim.sh, soc-o5kq + soc-eqjd) verifies each Evidence line against the workflow run's logs and blocks the PR if any claim is absent (mechanical AP#7).
6. Commit with conventional-commit scope. feat(<scope>):, fix(<scope>):. Body reproduces the failure mode the test catches.
7. Push + gh pr create. Body cites the bead, validation, and a learning-anchor reference in the script body (not a .agents/learnings/ file — that breaks CI).
8. gh pr merge <num> --squash --auto. Immediately. The bot fires the review check automatically on PR open.
9. Close the bead. bd close <id> --reason "Merged via PR #<num>". For multi-PR chains: scripts/gh-merge-chain.sh <pr1> <pr2> <pr3>.

Gate sequence

| Gate | Enforces | |---|---| | Per-tool local checks (optional) | cd cli && make test for Go; bats tests/scripts/<file>.bats for shell; only what your diff touches | | Review-bot workflow (auto on PR open) | Bot half of the pair — no mention required | | .github/workflows/validate.yml | Sole authoritative push gate (soc-g2r9, PR #357). Full 60+ job suite incl. validate-pr-evidence-claims (AP#7). | | gh pr merge --squash --auto | Auto-merge when all required checks pass | | scripts/gh-merge-chain.sh (optional) | Chain N PRs through auto-merge with update-branch on each successor |

Failure-mode mapping (F1-F5 + meta)

| ID | Failure | Mechanical guard | |---|---|---| | F1 | Script rewrite leaves dead variables | Unconditional shellcheck on staged .sh | | F2 | Pre-existing blocker compounds across branches | Open. Rule: fix as atomic side-quest PR first | | F3 | --auto doesn't auto-rebase BEHIND branches | scripts/gh-merge-chain.sh | | F4 | Bot trigger doc claimed mention-only | Doc corrected; observed auto-fire on PR open | | F5 | Stale ~/.config/evolve/KILL silently blocks $evolve | EVOLVE_KILL_TTL_DAYS=7 auto-expire | | meta | Tests asserting local-only file existence | grep -q '<slug>' "$SCRIPT" instead of [ -f .agents/learnings/<x>.md ] |

Anti-patterns

1. Adding inventory artifacts without running the regen sweep — new skill, contract, or schema → run scripts/ship.sh (auto-detects); CI catches what you missed
2. Bundling pre-existing fixes — file each as its own atomic PR
3. Keeping copied variables after a rewrite — first self-check after rewrite is "are all variable declarations used?"
4. Asserting local-only state in CI tests — grep the reference, don't check the file
5. Branches off out-of-date main — git pull --rebase at branch creation
6. Skipping the failing-test-first step — adding a test after the fix gives false confidence
7. Claiming a gate fix lands without verifying at HEAD — capture the target output line as PR Evidence:; the validate-pr-evidence-claims CI job verifies it against the workflow run's logs
8. Editing a gate/validator script without running its bats — the bats suite (under tests/scripts/) is the fast oracle; run bats on it before commit

Session scope (sister rule to coherent-arc)

Coherent-arc governs the shape of a single PR; session-scope governs the count of consecutive PRs.

• Default: 2-4 PRs per autonomous session.
• ≥5 PRs in flight or merged in one session triggers a mandatory post-mortem before continuing. Reactive-PR spirals (PR-fixes-fallout-from-prior-PR) dominate the back-half of long sessions.
• Post-mortem shape: which PRs were planned vs reactive, self-correction count, marginal PR = discovery or churn.

Derivation: 2026-05-19 session shipped 6 PRs with 3 self-corrections; PRs #5–#6 fixed fallout from #1–3. (soc-waxr)

Pair mechanics

• The review-bot workflow fires automatically on pull_request: opened/synchronize. No mention required.
• If IN_PROGRESS, wait. If silent, check workflow permissions (workflows: write for forward-port scenarios).
• Self-revert loop (bot reverting its own forward-port): rebase the branch locally onto fresh main and force-push.

Anti-Patterns (DO NOT)

| Anti-Pattern | Why It's Wrong | Correct Behavior | |---|---|---| | Stack feature branches on each other | Auto-merge serialization fails; conflicts compound | Always branch off fresh main | | Bundle a pre-existing fix into a feature PR | Other branches will hit + duplicate the same fix | File atomic side-quest PR first, rebase | | Assert .agents/learnings/<x>.md exists in CI | .agents/ is gitignored; test fails in fresh clone | grep -q '<slug>' "$SCRIPT" (reference assertion) | | Add tests after the fix without seeing them fail | False confidence | Write the failing test FIRST, see it red | | Push without --auto enabled immediately | Operator becomes the merge bottleneck | gh pr merge --squash --auto on PR open |

Examples

User says: $ship-loop after picking soc-<bead-id> from bd ready Run the 9-step cycle: branch, first failing test, minimal impl, pre-push --fast, commit, push, auto-merge, bd close.

User says: "ship this fix from the post-mortem" Read the harvested item from .agents/rpi/next-work.jsonl, run the 9-step cycle.

User says: "land the 4 PRs we have open" After all 4 PRs are open with auto-merge enabled: scripts/gh-merge-chain.sh <pr1> <pr2> <pr3> <pr4>.

See Also

• $pr-implement — fork-based OSS contribution (different tier; different use case)
• $crank — multi-wave epic execution
• $rpi — full lifecycle orchestrator
• $post-mortem — harvests next-work items that ship-loop consumes
• $beads — task tracker that drives the claim step