/ship — Quality Gates → Commit → Push → PR

Runs all quality checks, commits staged/unstaged changes, pushes the branch, and creates or updates a PR.

Usage

/ship                        # Auto-generate commit message
/ship "add login redirect"   # Use provided commit message
/ship --amend                # Amend previous commit (use sparingly)

---

Step 1 — Pre-flight Check

git status                   # Show what will be committed
git diff --stat              # Show changed files summary

If working tree is clean (nothing to commit): report "Nothing to ship. Working tree is clean."

---

Step 2 — Quality Gates

Run all checks. All must pass before committing.

bun run typecheck            # TypeScript — 0 errors required
bun run lint                 # Lint (skip if no lint script in package.json)
bun test                     # Tests (skip if no test files exist)

Strict evaluator verdict (optional): If AGENT_FORGE_EVAL_VERDICT=strict is set in the environment where hooks run, the task is shippable only once its run's evaluator verdict is on file and the gate has read it. The quality gate enforces this on TaskCompleted, and only for a run it can tie to that Beads issue through a run correlation; without one the strict check fails. Three steps, with one pointer for all of them: (1) the run's correlation: a Forge run has one from forge:phase-gate … --write --bead <TASK-ID>; otherwise create it once with bun run forge:correlate --bead <TASK-ID>. Either prints a pointer. (2) File the verdict with that pointer: bun run forge:verdict --correlation <pointer> … (schema 2, written once at the path that run declares: .claude/protocols/evaluation-verdict.md). (3) Run the gate with the same pointer: bun run quality-gate --correlation <pointer>. Running forge:correlate --bead again mints a new run, whose verdict has not been filed.

If any check fails:

1. Report which check failed and the exact error
2. Fix the issue
3. Re-run the failing check
4. Maximum 2 auto-fix attempts; escalate to user if still failing after 2

---

Step 3 — Security Scan

Scan the diff for security issues before committing:

git diff HEAD

Check for:

• Hardcoded secrets, API keys, passwords, tokens
• SQL string concatenation
• eval() or unsafe dynamic code execution
• Auth checks being bypassed (commented out, if (true))
• Unescaped user input in HTML templates

If any security issue is found: stop, fix, do not ship. Never commit secrets.

---

Step 4 — Commit

Stage all changes:

git add -A
git status --short           # Confirm staged files look right

Commit with the provided or generated message:

# Format: type(scope): description\n\nRefs: <TASK-ID>
git commit -m "<message>"

If --amend flag: git commit --amend --no-edit

Generating commit messages

If no message was provided, infer from:

1. The Beads task title (if a task is active)
2. The diff summary (most-changed files and purpose)
3. Format: <type>(<scope>): <description>\n\nRefs: <TASK-ID>

Types: feat, fix, refactor, test, docs, chore, build

---

Step 5 — PR Stack Detection

Check if the current branch has a stack relationship:

gh pr list --state open --json number,headRefName,baseRefName
git log --oneline master..HEAD

• If current branch is based off another feature branch: set --base <that-branch> in PR creation
• If current branch is based off master: set --base master

---

Step 6 — Push

git pull --rebase origin <base-branch>   # Rebase on latest before pushing
git push origin <current-branch>

If push fails due to diverged history:

• git pull --rebase and retry once
• If still failing: report the conflict; do NOT force push

---

Step 7 — Create or Update PR

The PR body MUST follow the canonical template — see .claude/skills/pr-description/SKILL.md. Do not hand-roll an ad-hoc body; start from the template, fill every required section with real content, and validate before posting.

Check if PR already exists

gh pr list --head <current-branch> --json number,url

Build the body from the template

mkdir -p .tmp/work
cp .claude/skills/pr-description/references/pr-template.md .tmp/work/pr-body.md
# Fill every section in .tmp/work/pr-body.md:
#   What Changed · Why It's Needed · How It Was Tested · Test Evidence
#   (paste real `bun test` / typecheck output) · Risk & Rollback · Linked Issues & AC Trace.
# Pull AC from: bd show <TASK-ID>
bun run .claude/skills/pr-description/scripts/check-pr-body.ts .tmp/work/pr-body.md
# Must print "ok": true before continuing.

Create new PR

gh pr create \
  --title "<TASK-ID>: <task title>" \
  --base <base-branch> \
  --body "$(cat .tmp/work/pr-body.md)"

Update existing PR

gh pr edit <number> --body "$(cat .tmp/work/pr-body.md)"

---

Step 8 — Post-Ship

# Close Beads task
bd close <TASK-ID> 2>/dev/null || true
bd comments add <TASK-ID> "worklog: shipped — PR #<n>" 2>/dev/null || true

# Beads is local-only here: nothing to push (see "Tracker is local-only" in CLAUDE.md)

# Deploy dashboard
bun run build-pages 2>/dev/null || true

# Final status
git status
echo "✓ Shipped: <branch> → PR #<n>"

---

Output

Quality gates: PASS (tsc, lint, tests)
Security scan: PASS
Committed: abc1234 — feat(auth): add refresh token rotation
Pushed: origin/feat/T-42-refresh-tokens
PR: https://github.com/org/repo/pull/17 (created)
Beads: T-42 closed