ship

Ship

Purpose

Publish validated work through a concise, non-destructive proof trail. $ship may create, update, or promote a pull request, or read-only observe and adopt an exact already-public default-branch subject that no current PR tuple can truthfully represent. It never merges.

Ship is the sole public-effect and publication-evidence owner. Actuating supplies current Git and validation facts; Ship does not require an Actuating closure receipt, Construction reference, Evidence head, or Ledger event.

validated complete work -> ready PR
incomplete work with explicit warrant -> draft PR

Activation

Use Ship when the user asks to create, update, finalize, or promote a PR, or when Actuating supplies a current publication handoff.

Only an explicit Actuating handoff may select observe-existing or adopt-existing. Direct Ship requests use the pull-request route.

Do not use Ship when the user wants merge/landing, implementation is incomplete without an accepted draft reason, validation failure lacks an accepted caveat, or no publication/readback was requested.

Selected guidance

For pull-request, read pull-request.md before any push or PR effect. It owns readiness, managed-body preservation, mutation order, and readback. For an explicit Actuating observe-existing or adopt-existing handoff, read existing-publication.md; these routes remain read-only. All routes retain Input, Receipts, Guardrails, and Output below. Do not load the other route's procedure just because it shares this package.

Pull-request route: pull-request.md. Managed body: pull-request.md. Public mutation and readback: pull-request.md. Existing-publication observation: existing-publication.md. Existing-publication adoption: existing-publication.md.

Input

ship_input:
  source: direct | actuation
  publication_route: pull-request | observe-existing | adopt-existing
  repository:
  base:
    branch:
    sha:
  head:
    branch:
    sha:
  existing_pr:
    exists:
    url:
    draft:
  existing_publication:
    branch:
    head_sha:
    comparison_base_sha:
    publication_observation_ref: null | sha256-digest
    release: null | { provider, repository, publication_state, draft, tag, url, target_sha, assets: [] }
  validation:
    build: pass | fail | missing | not-run
    lint: pass | fail | missing | not-run
    tests: pass | fail | missing | not-run
    language_specific: pass | fail | missing | not-run
    acceptance: pass | fail | missing | not-run
  task_state:
    complete:
    blocked:
    deferred:
    open:
  proof_summary:
  actuation:
    goal_context_digest:
    review_contract_digest:
    review_context_digest: null | sha256-digest
    publication_required: true | false
  user_requested_pr_mode: ready | draft | update-existing | promote-draft | none
  repo_policy_pr_mode: ready | draft | unknown

Direct shipping omits actuation. For Actuating input, exact repository, base/head, validation, task state, and Goal context are mandatory. Ship copies the Actuating binding into its receipt but never interprets it as architecture, review, mutation, or closure authority.

Receipts

Read ship-record.md.

For Actuating routes, return the complete canonical receipt bytes and SHA-256 digest. Actuating compares the owner-issued receipt directly with the current Git and review context. It does not copy the receipt into a workflow event log.

Guardrails

• Never publish without validation evidence or an explicit reported limitation.
• Never create a draft by default after complete validation.
• Never create a duplicate exact-tuple PR.
• Never use adoption to disguise mutation or avoid fresh review.
• Never overwrite human-authored body content outside the managed block.
• Never promote before updating proof.
• Never claim publication without matching live readback.
• Never require or synthesize an Actuating closure receipt.
• Never select architecture, classify findings, count review credit, decide closure, or choose Actuating's next action.
• Never merge or land.
• Never stage or commit unrelated work.

Output

Report the PR link, resulting public state, head, and relevant validation or limitations concisely. Include receipt identity and the next owner when an enclosing workflow needs that handoff. Preserve the full immutable publication evidence in the Ship receipt; do not repeat its fields as a mandatory chat form.