Ship

Ship Skill — Autonomous Merge Loop

Drive the current lane from "work is ready" to "merged on main" without manual shepherding. Pure loop: /ship assumes you already ran /quality and /test — it does not bundle them. /quality opened the PR when it started, and /quality and /test each harvested and fixed whatever CI and the bots reported (playbook: Early PR and harvests). So /ship normally adopts an open PR in state prepping, skips PR creation and re-review, and closes the PR out. It polls, fixes CI + review, rebases only when there's a real conflict, and merges. It does not exit until the PR is merged or the merge is genuinely blocked by repo policy.

Print a compact status line each iteration (no banner):

ship · iter 2/5 · PR #184 · POLL → DECIDE → FIX → MERGE · FIXING CI (test-desktop 3) + 2 comments

Stack mode prints the layer and its terminal instead of MERGE:

ship · stack 12 layer 2/5 · iter 2/5 · PR #1007 · POLL → DECIDE → FIX → READY · FIXING CI (windows-foundation) + 1 comment

Invocation: /ship (auto-detect state), /ship <pr-number>, or the opt-in /ship --stack-ready [<pr-number>] --base <direct-parent-branch>.

Stack-ready mode (opt-in only)

--stack-ready drives one layer of a coordinator-owned stack to ready, not to merged. It is the same loop — Phase 0 through Phase 5, the same poll/fix machinery, the same 5-iteration budget — with merging and every stack-wide operation removed. Resolve the direct parent from --base, an existing PR's baseRefName, then non-interactive gh stack view --json; normalize it with the /quality rules. Persist mode: "stack" plus the complete stack binding: stack number, size, position, expected parent branch, validated head SHA, base SHA, content-tree SHA, test-evidence SHA, required and deferred proof scenarios, proof links, and quality/test status.

The lane owns its layer; the coordinator owns the stack. The lane commits and pushes its own layer branch, opens its PR against the resolved direct parent when none exists, polls CI and review bots, fixes red CI and verified findings on its own layer, reruns commit-bound quality revalidation against the exact resulting head, and repeats until the layer is genuinely clean. A red check on its own code is work to do, not a reason to stop.

The lane never merges, never enables auto-merge, never deletes a branch, never rebases or restacks (git rebase, gh stack sync --remote origin, gh stack rebase --upstack --remote origin, gh stack push --remote origin, and gh stack submit --auto --remote origin are all coordinator-only), never retargets a PR base, never touches another layer's branch or files, and never enters force-finalize or any bypass-review path. Before any cap, force-finalize, rebase, merge, or branch-deletion decision, branch on mode == "stack".

Escalate only what the lane genuinely cannot do, with exact evidence: stack-coordinator-sync-required (a restack or base retarget is needed — the parent moved, a lower layer changed, or the PR base is not the direct parent), stack-coordinator-fix-required (the fix belongs to a lower layer, or the iteration budget is spent and the layer is still red), stack-coordinator-pr-required (the parent branch is missing on origin, or PR creation failed on auth or an unusable base ref), and stack-coordinator-merged (the coordinator already landed it). The playbook's Stack escalation states table is authoritative. None of them is a general stop at the first red check.

Write status: "ready-stacked" only when the exact head is green, review-terminal, quality-clean, test-clean, and every mandatory proof scenario either has a current evidence link bound to the validated head or is recorded in deferredProofScenarios against a named higher layer that exists in this stack. The top layer defers nothing, and cumulative clean-host/cross-client/release scenarios never masquerade as lower-layer evidence. A known-missing mandatory scenario is blocked with the scenario ids listed — never ready-stacked with a caveat. Missing or ambiguous stack metadata is blocked, not a fallback to main.

Without --stack-ready, every existing /ship default and merge behavior is unchanged: the base is main, green work proceeds through Phase 3c, and the terminal success state is done-clean only after merge confirmation.

Source of truth

Follow docs/playbooks/ship-lane.md — all phase logic, the state schema, commands, decision rules, and bot-ping rules live there. This skill is the runtime-neutral entrypoint and the ADE-specific deltas below. If re-invoked by a scheduled wake, read the state file first; if status == running, skip Phase 0 and go to Phase 1. If status == ready-stacked, revalidate the complete binding first: when it holds, print the persisted coordinator handoff and exit without scheduling or mutating anything; when it is stale, external movement exits stack-coordinator-sync-required and this lane's own newer head re-enters the loop at Phase 1.

The playbook's Phase 0 is checkpoint → commit-bound quality revalidation → push → open PR when no early PR exists. With state prepping, it runs only 0.6 Adopt the early PR: keep a current binding, mark held commits as fix work, and go to Phase 1. Every revalidation reviews only the delta since qualityReviewedSha; the full review ran once, in /quality. Baseline test generation and the local-CI gate are NOT part of ship — that's /test (and optionally /finalize) before you reach this skill.

Precondition: /quality must be empty and bound to the final tree

Before Phase 0, require a completed /quality result with an empty gate. Before Phase 3c, run the playbook's single canonical Validate the current quality binding procedure. It binds the reviewed head, content tree, and base so GitHub's squash/merge/rebase result has the reviewed tree. Green CI on a later head or base does not preserve this binding.

A non-empty gate blocks the merge — every row in it is a finding that was verified as real and left unfixed, and by /quality's contract the only three things that may be there are a product decision the author owes, a behavior change this branch was not asked to make, or a capability whose Windows parity is not achievable. All three need the author.

• Gate rows exist → do not merge. Surface them, state the decision needed, and stop with blocked. Do not merge and mention them afterwards.
• If /quality was never run on this lane, or its final gate result is not available in the lane handoff, stop with blocked; unknown is not empty.
• Any base movement, rebase, conflict resolution, Phase 3b edit, or force-finalize edit clears all three quality binding fields. In stack mode, this lane's own Phase 3b edit clears them and is rebound by revalidation on the head it then pushes; external movement of the parent, base, or head instead clears the complete stack binding and returns stack-coordinator-sync-required without rebasing. Run the playbook's single canonical Commit-bound quality revalidation procedure before pushing that mutation.
• Never enter Phase 3c with a missing or mismatched binding. Revalidate first; do not merge and disclose stale quality evidence afterwards.
• Bind every normal or admin merge attempt with --match-head-commit "$QUALITY_VALIDATED_SHA". Persistent auto-merge is not allowed because a later push can replace the validated head while it remains armed.
• GitHub creates a new commit for squash/merge/rebase. The validation claim is deliberately about its exact content tree, not its not-yet-created commit OID. After merge, run the playbook's canonical Confirm the validated merge result procedure; a mismatch is never done-clean.

Severity is irrelevant here: a Medium in the gate blocks exactly as hard as a Blocker, because presence in the gate means it needed a human, not that it was minor.

Execution Mode: Autonomous

Runs end-to-end without user interaction. Do NOT ask to confirm/choose/approve, pause between phases, or ask whether to apply a fix — apply, verify, commit. The only user-visible output is the per-iteration status line and the final summary.

Repo facts (ADE)

• Package manager: npm; each app under apps/ has its own node_modules + package-lock.json (no workspaces). Node 22 (.nvmrc).
• CI: .github/workflows/ci.yml — desktop tests shard 8-way (npx vitest run --shard=<n>/8) plus test-ade-cli; a ci-pass/ci-status gate aggregates required jobs. Discover the required-check list live via gh pr checks / the ade-pr-workflows skill — do not hardcode.
• PR creation: prefer the ade CLI (registers the PR in ADE's tracking — lane ↔ PR link, check/comment inventory). gh pr create --base main --head <branch> --fill is the ordinary fallback; stack mode substitutes the persisted direct parent for main. See the playbook's discovery protocol.
• State file: .ade/shipLane/<branch-with-slashes-as-__>.json. status: prepping (early PR open, before ship) | running | ready-stacked | done-clean | done-max | blocked; it also records mode and the complete stack binding. Rebase rebates the iteration counter by 2 (floor 0).

Windows parity gate. Windows parity is a default requirement for all new code, so this gate runs on every lane, not only Windows-labelled ones. Before Phase 3c (or ready-stacked), confirm the branch's behavior works on the Windows build. If any capability on this branch cannot work on Windows and the human has not already chosen what to do about it, stop with blocked — this is the one product decision /ship never makes for itself, and force-finalize does not clear it. /ship is autonomous, so "ask" here means exit blocked with the question stated, not pause mid-loop. The blocked summary must give, per capability:

1. the exact capability that cannot work and the OS-level reason;
2. whether macOS/Linux keep it;
3. hidden (absent on Windows) vs disabled with a reason shown (visible, inert, explained) vs removed (deleted from the Windows build), with your recommendation.

Hidden and disabled are different user experiences; the author picks per item. A /quality gate row with reason three carries this content already — surface it verbatim rather than re-deriving it. Never merge a lane whose Windows behavior is unknown; unknown is not parity. Failure classes and the canonical helpers: ../quality/references/windows-quirks.md.

Windows proof gate. For a Windows-relevant stack entry, require the native Windows foundation check to be terminal-green on the bound head. Require the packaged Windows check when packaging or native bundle contents changed. Computer Use evidence is capability-specific: native OS capture/control may be explicitly blocked while App Control and proof ingestion remain supported and tested. Clean-host Stable/Beta coexistence, second-account pipe denial, restart/reboot, installed-update, and GUI artifacts remain named external proof blockers until captured; never mark them proven from simulated tests. A stack entry cannot reach ready-stacked while any of them is required at its position and still uncaptured — record it as blocked with the scenario id, or defer it to a named higher layer in deferredProofScenarios.