ship · diff
git:20261011.29bb9e2 to git:20261016.5abfc14
2 added, 2 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: ship
description: Goal-oriented workflow for landing a requested change safely. Use when the user asks to ship, fix and ship, take a change through validation, or drive PR/CI/merge to completion.
metadata:
internal: true
user-invocable: true
---
# Ship
Land the requested change with evidence, and merge only after CI is green.
Read [`knowledge/project/shipping.md`](../../../knowledge/project/shipping.md) first — it owns the success bar, the
constraints, the CI opt-out labels, and the reporting standard. This skill owns execution only.
Start from the goal and the changed risk surface, then take the shortest path that proves the
change is ready; do not walk this file as a fixed checklist.
## Sequence
1. **Check the branch.** Never ship from `main`. Clean tree before the final push.
2. **Review the delta.** `git diff origin/main...HEAD` and `git log origin/main..HEAD`. Confirm the
requested behavior is actually implemented, then simplify avoidable complexity you introduced.
3. **Validate to the risk.** Pick from the evidence commands below; deepen only where signal is
weak. Bug fixes prefer a failing test before the fix.
4. **Security review.** Mandatory for any change touching code, config, or infrastructure. Follow
[`references/security-review.md`](references/security-review.md).
5. **Sync artifacts** the change actually affects: `knowledge/`, `knowledge/security/threat-model.md`, `AGENTS.md`,
`knowledge/test-cases/`, `apps/docs/`, OpenAPI exports. When the PR completes a user-facing
- feature or fix, its changelog entry with screenshots is part of the change; when it changes an
- older entry's behavior, that entry is updated. See
+ change that meets the public changelog's impact criteria, its entry with screenshots is part
+ of the change; when it changes an older entry's behavior, that entry is updated. See
[`references/changelog-entry.md`](references/changelog-entry.md).
6. **Smoke test the affected flows** end to end. For a coding-agent stack, follow the canonical
startup contract in the root `AGENTS.md`; it includes the DB-backed infrastructure required for
database, migration, infra, or API integration risk.
Stop anything you started. Docs- or config-only changes may skip this with a stated reason.
7. **Decide follow-ups explicitly.** Prefer implementing in-scope work now. List anything deferred
under **Follow-ups** in the PR body with a one-line rationale, or state "No follow-ups." — a
reader must be able to tell "nothing left" from "agent forgot". File Linear issues (OSS/EVE) for
non-trivial deferrals.
8. **Open the PR and merge** — see [`references/pr-and-merge.md`](references/pr-and-merge.md).
## Migrations
Migrations are named by UTC timestamp (`just new-migration <name>`), so parallel branches do not
collide and nothing needs renumbering after a rebase. `bash scripts/lib/check-migration-ordering.sh`
rejects a retired `NNN_` name or a shared version; CI runs it on the PR and on main after merge.
## Evidence commands
Pick only what matches the changed surface:
- `just pre-push` / `just pre-pr`
- `cargo fmt --check`, `cargo clippy --all-targets --all-features -- -D warnings`,
`cargo test --all-features`, `cargo fetch --locked`
- `cd apps/ui && pnpm run format:check && pnpm run lint && pnpm run build`
- `cd apps/docs && pnpm run check && pnpm run build`
- `./scripts/export-openapi.sh`, then `cd apps/ui && pnpm run api-types:generate` —
the UI's generated types are derived from the exported spec and CI fails on
drift, so exporting without regenerating them is a guaranteed red build
- `bash scripts/lib/check-migration-ordering.sh` (migration names and unique versions)
If `just fmt` can auto-fix a failing format check, use it once and retry.
## Stopping
Stop and report only for blockers you cannot resolve safely alone: merge conflicts you cannot
adjudicate, missing credentials, ambiguous product intent, or CI failures you cannot reproduce.