Ship

Overview

Commit (if needed), push, and watch Mechatron Prime CI until green. On failure, investigate and fix automatically.

SCM is direct git. The main branch is yolo. Keep commits focused, never force-push unless Peter explicitly requests it, and independently verify that origin/yolo equals the local commit after every push.

<when_to_use>

• User says "push", "ship", "push it", "commit and push", "check CI"
• You just finished a bugfix, feature, or refactor and the user hasn't said NOT to push
• User asks "you push it yet?" (you should have already done this) </when_to_use>

<when_not_to_use>

• User explicitly says "don't push yet" or "hold off on pushing"
• You're in the middle of multi-step work that isn't ready
• Working in a worktree that hasn't been merged yet </when_not_to_use>

Workflow

digraph ship {
  "Work complete" -> "Uncommitted changes?";
  "Uncommitted changes?" -> "git commit" [label="yes"];
  "Uncommitted changes?" -> "Unpushed commits?" [label="no"];
  "git commit" -> "Push yolo";
  "Unpushed commits?" -> "Push yolo" [label="yes"];
  "Unpushed commits?" -> "Already pushed, check CI" [label="no"];
  "Push yolo" -> "Verify origin/yolo";
  "Verify origin/yolo" -> "Find exact commit in CI";
  "Already pushed, check CI" -> "Find exact commit in CI";
  "Find exact commit in CI" -> "Watch CI in background";
  "Watch CI in background" -> "CI passed?" [label="wait"];
  "CI passed?" -> "Report green" [label="yes"];
  "CI passed?" -> "Investigate failure" [label="no"];
  "Investigate failure" -> "Fix + commit" -> "Set yolo + push" [label="retry"];
}

Step 1: Commit (if needed)

Inspect the branch and worktree first:

git status --short --branch
git diff --check

Stage only the intended paths, review the staged diff, and commit:

git add -- <path> <path>
git diff --cached --check
git diff --cached --stat
git commit -m "<message>"

Follow the repo's commit message conventions. Keep messages concise and focused on why. Preserve unrelated worktree edits and never commit .env, credentials, generated release binaries, or other out-of-scope files.

Step 2: Push and verify

branch="$(git branch --show-current)"
[ "$branch" = "yolo" ] || { echo "expected yolo, found $branch" >&2; exit 1; }
git push origin yolo
git fetch origin yolo

local_rev="$(git rev-parse HEAD)"
remote_rev="$(git rev-parse refs/remotes/origin/yolo)"
[ "$local_rev" = "$remote_rev" ] || {
  echo "push verification failed: HEAD=$local_rev origin/yolo=$remote_rev" >&2
  exit 1
}

If the push is rejected because the remote advanced, fetch and inspect the new commits. Integrate them without rewriting published history, rerun tests, and push again.

Step 3: Find the Exact Commit in CI

Use the operator CLI to inspect the worker and recent results:

mechatron-ci status
mechatron-ci log --limit 50

Match the repository and exact pushed commit. Do not mistake another repository's single-queue build for this shipment.

Step 4: Watch CI in Background

mechatron-ci status
mechatron-ci log --limit 50

Poll without blocking Peter's terminal. Report the result when that exact commit completes.

Step 5: Handle Result

If green: Report "CI passed" and move on.

If red: Do NOT just report the failure. Investigate:

1. Use mechatron-ci log --limit 100 and the project's local build/test commands to reproduce what failed
2. Diagnose the root cause
3. Fix it
4. Loop back to Step 1 (commit, push, watch again)

Red Flags

Common CI Failure Patterns

• Nix hash mismatch -- Zig deps changed. See fix-zig-deps-hash skill.
• Test timeout -- Tests hanging. Check for infinite loops or missing test termination.
• macOS build failure -- Missing unset NIX_CFLAGS_COMPILE NIX_LDFLAGS in flake.nix.
• Missing file in Nix sandbox -- Flake sources include Git-tracked files; an untracked or ignored source file is absent. Check git status --short, add the intended source, commit it, and rerun the build.

Cutting a Release (optional)

After CI is green, publish a tagged release so downstream users see a human-readable changelog on github.com/OWNER/REPO/releases. Do this when:

• The user says "release", "cut release", "publish", "tag it"
• A shipped commit is meaningfully user-visible (fix/feature), not purely internal (docs, tests, refactor). Ask the user if unsure.

Tag format

CalVer + short SHA: YYYYMMDD.<7-char-commit-hash> (e.g. 20260424.a028026).

• No version-number decisions ever — date + hash is unambiguous.
• Multiple releases same day are unique by hash.
• git rev-parse --short=7 HEAD gives the short hash of the committed work.

Commands

Normal release: auto-bulleted commit subjects since the last tag.

No prior tag (first release): RANGE collapses to HEAD; hand-curate instead.

RANGE="${PREV_TAG:+${PREV_TAG}..}HEAD" git log --format='- %s' "$RANGE" > /tmp/release-body.md gh release create "$TAG" --target yolo
--title "$TAG" --notes-file /tmp/release-body.md

For a major release with many commits — hand-curate /tmp/release-body.md

(grouped by theme: Features / Fixes / Under the hood), then same command.

</template>

<important>
`gh release create --generate-notes` (GitHub's auto-generator) only produces useful output when the repo uses PRs. For direct-to-`yolo` workflows, it emits just a compare link. Use `--notes-file` with `git log` output instead.
</important>

### After publishing

- Report the release URL to the user.
- For a hand-curated release, consider a trailing `**Full commit log:** https://github.com/OWNER/REPO/compare/PREV_TAG...TAG` line so readers can drill in.

---

## CI Setup (one-time per repo)

If the repo is missing CI infrastructure, set it up before the first ship. Check for these and create any that are missing:

### Mechatron Prime

<remember>
Invoke the `$mechatron-ci` skill. It is the single source of truth for the
exact-commit `.mechatron-prime/targets` manifest, webhook provisioning, dynamic
README badge, and live verification. Do not duplicate its commands or badge
template here.
</remember>

### Target Platforms

For CLI-only projects and UI-less system-level libraries, target **5 platforms**:

| OS      | aarch64              | x86_64              |
|---------|----------------------|---------------------|
| macOS   | `aarch64-macos`      | --                  |
| Linux   | `aarch64-linux-musl` | `x86_64-linux-musl` |
| Windows | `aarch64-windows-gnu`| `x86_64-windows-gnu`|

<important>
- macOS Intel (x86_64-darwin) is NOT supported — Apple dropped it and GitHub Actions no longer offers Intel Mac runners.
- Linux builds MUST use musl (`-musl` suffix) for fully static binaries with no glibc dependency.
- Windows uses `-gnu` (MinGW) for Zig cross-compilation compatibility.
</important>

Ensure the `flake.nix` exposes intentional `packages.*` and `checks.*` outputs
for supported systems. For Zig cross-compilation, use `-Dtarget=` in the flake
build phase and expose each as a separate flake output (for example,
`packages.x86_64-linux` and `packages.aarch64-windows`). Add the outputs that
Mechatron should build to `.mechatron-prime/targets` by following
`$mechatron-ci`; never guess attribute names.