Deploy guard

Deploy Guard — Stale-Branch Production Deploy Preventer

Why this exists

The classic incident: the working folder sits on a stale branch (origin/main is dozens of commits ahead), a production deploy runs from it by accident → old content goes live. This skill puts that sync-check in front of EVERY production deploy as a mandatory gate.

When it is MANDATORY (triggers)

When the user asks for any of the following, pass through this gate BEFORE running the deploy command:

• vercel --prod, vercel deploy --prod, or the platform equivalent (netlify deploy --prod, flyctl deploy, …)
• "deploy", "production deploy", "prod deploy", "ship it", "push it live"

Not mandatory for preview deploys — but running it is harmless.

Steps

1. Determine the project's canonical folder and branch

If the project keeps a registry or a Canonical branch: line in its CLAUDE.md/AGENTS.md, read it. Otherwise use the folder being deployed and default the canonical branch to main (if unsure, ask the user — don't guess on a prod deploy).

2. Run the sync-check (MANDATORY before deploy)

git -C <ABS_PROJECT_PATH> fetch -q origin <canonical_branch> && \
git -C <ABS_PROJECT_PATH> branch --show-current && \
git -C <ABS_PROJECT_PATH> rev-list --left-right --count origin/<canonical_branch>...HEAD && \
git -C <ABS_PROJECT_PATH> status --porcelain | wc -l

Output to read: current branch, behind ahead counts against origin, and the number of uncommitted changes.

3. Interpret the output and DECIDE

• behind=0, branch=canonical, clean tree → deploy is allowed. Continue (step 4).
• behind>0 or divergent → DEPLOY FORBIDDEN. STOP. Flag to the user: "Working copy is N commits behind/divergent from origin/<branch> — deploying prod from a stale branch repeats the classic incident. NOT deploying." Sync first, don't deploy:

  git -C <ABS_PROJECT_PATH> pull --ff-only origin <canonical_branch>
  

  If ff-only fails (true divergence) → report to the user, leave the rebase/merge decision to them. NEVER deploy autonomously over divergence.
• Mirror branch (behind=0 but branch name differs from canonical, in sync with origin/<branch>) → even on success, leave the user a one-line note ("branch is <cur>, canonical is <branch> — in sync with origin, deploy is safe"). If it looks risky, ask for approval.
• Uncommitted changes > 0 → clean the working tree before deploying (commit/stash) or report to the user; deploying prod from a dirty tree violates the precondition.

4. Run the deploy only if CLEAN

If the sync-check is clean, run the requested prod deploy command in the project folder. Because a production deploy has real-world impact, a final explicit user approval still applies: even after the gate passes, confirm with the user before executing.

Fallback

• Not a git repo / no git → the deploy target is suspicious; ask the user.

Principles behind the gate

• A project has ONE canonical branch; deploy preconditions are 0 behind/ahead + clean tree.
• "The model says it deployed" ≠ evidence; verification = the sync-check, run now, not quoted from memory.