/ship-workflow

name: ship-workflow
description: 'Resumable shipping lifecycle: reconciles current Git and GitHub facts from any entry (dirty default or feature branch, local commits, published branch, open PR, existing manual or native stack, merged work), commits dirty work as lossless logical commits, publishes or reuses the PR, requires current CI and review evidence, lands it through the supported path and cleans up only proven-stale branches and worktrees. Stops at the requested endpoint and never bumps versions, edits changelogs, tags or publishes. Triggers on: "ship it", "ship this", "open a PR", "push and PR", "land this PR", "merge PR and clean up", "check CI on my PR", "resume the ship run", "/ship-workflow".'
metadata:
  version: 2.2.0
  category: review
  tags: [shipping, pull-request, ci-cd, merge, cleanup]
  difficulty: intermediate
  phase: ship

Ship Workflow

Ship through the authorized endpoint using the repository's current checks, required reviews, branch protections and merge policy. Routine shipping is the default. The executable owns Git/provider mutations, journals, reconciliation and cleanup; the assistant owns scope, logical change grouping, repository conventions and unfamiliar failure diagnosis.

Reference Files

| File | Contents | Load When | |---|---|---| | `references/commit-planning.md` | Inventory, logical commit plans and local gate packets | Creating commits or requesting local/per-commit validation | | `references/lifecycle-contract.md` | Explicit policy, assurance, publication, stack packets, journals and recovery | Supplying `--policy` or `--stack-plan`, resuming, or interpreting a blocker | | `references/project-detection.md` | Repository gate-source detection | Locating local test commands; version/changelog tables do not authorize release work |

Workflow

1. Resolve scope

Choose exactly one target: `--pr N`, `--branch NAME`, an explicit stack, a saved run, or the current branch when it identifies exactly one target. Resolve ambiguous targets or bases from provider/Git facts; ask only when those facts cannot decide. `--repo [HOST/]OWNER/REPO` names the PR base repository, and `--head-repo OWNER/REPO` names a fork head namespace.

| Request | Endpoint | |---|---| | "Ship it", `/ship`, "finish PR 12 and clean up" | `clean` (default) | | "Merge it", "land PR 12 but keep the branch" | `--until merged` | | "Open a PR", "push and PR" | `--until pr` | | "Check CI", "what blocks PR 12" | `--until pr --dry-run` (inspection only) | | Version, changelog, tag, release, package publication or deployment | Separate release authority, not this skill |

State the target, endpoint and cleanup scope before mutation. A resume preserves the saved authority. `pr` confirms publication only; `merged` adds confirmed landing and applicable post-merge acceptance; `clean` adds proof-based cleanup. Keep active, dirty, protected/default/release, unmerged, open-PR-dependent and unknown work. Never widen a stack selection or resume endpoint implicitly.

2. Inspect through the executable

Resolve `<skill-dir>` from the loaded skill's absolute client-reported directory. Run from a checkout of the target repository:

uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --pr 12 --dry-run
uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --inventory

Python 3.12+, Git and authenticated `gh` are required. Missing prerequisites are `BLOCKED`; there is no hand-run lifecycle fallback. Inspection writes no objects, refs, hooks, locks or journals and does not fetch or prune. Use literal argv lists, quote paths and repository-controlled values, and place packets and PR bodies in a private temporary directory outside the repository.

3. Execute routine shipping

For an existing PR with unambiguous provider merge policy:

uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --pr 12 --until merged

Provider-required checks/publishers, repository mandates, current-head human approvals and protections remain blocking. Unclassified observed jobs also stay strict: pending or failed evidence stops landing. Only exact, source-backed `advisory_checks` identities in `--policy` or a stack node's decision may report pending/failure without veto; the controller surfaces their state separately. Never infer advisory status from slowness, inherited failure, bot identity or a display-name pattern. Missing/inaccessible required evidence is not GREEN, and advisory declarations never weaken strict current-base gates. Repeated display names are normal: workflow, event, publisher, job and current attempt identify evidence; push results do not substitute for PR merge-context results. Provider-current job IDs preserve distinct carried jobs in partial reruns. Do not rename jobs or change workflows to satisfy this controller.

An explicit `--policy` resolves actual ambiguity: repository merge-method conventions, blocking expected-job inventory, exact advisory CI classification, justified skips/head-only checks, documented post-merge commands, protected refs, or a deliberately CI-free repository. Bind it to the current head/base (schema 1) or publication (schema 2), as specified in the lifecycle reference. Empty CI requires a sourced `ci_free` decision; it is never inferred from absent jobs.

Routine assurance does not require checkout-log attestation or immutable action pins. Use `assurance: "high"` in an explicit policy, or a selected stack node's decision, only when requested. That option requires the stronger checkout/commit-parent evidence described in the lifecycle reference. Never silently lower a saved run's assurance; a legacy run or incompatible source update must stop for an explicit migration/policy decision.

Use one primary review per PR. A stack receives one cumulative integration check, not another full review of every slice. After fixes, re-review changed code and affected boundaries; after three unsuccess