/ship-gate

name: ship-gate
description: Turn the /ship scorecard into a blocking, config-as-code quality gate. Sets per-category score thresholds, hard-fails on leaked secrets or critical findings, and wires the gate into a pre-push hook and CI so nothing below the bar merges. Use when the user wants a merge gate, CI quality gate, pre-push check, or to enforce ship-readiness.
argument-hint: "[init|run|ci|hook] [directory]"
allowed-tools: Bash, Read, Edit, Grep, Glob

Ship-Gate — Deterministic Quality Gate

The 2026 consensus on AI-written code is "did it pass the gates," not "did a senior read every line." This skill promotes the `/ship` scorecard from advisory to a **blocking, deterministic gate**: same scoring as `/ship` (shared `tools/lib/ship-scoring.mjs`), compared against thresholds in `.ultraship/ship-gate.json`, exiting non-zero so it can fail a push or a CI job.

When to use

The user wants a merge gate, a CI quality check, a pre-push guard, or to enforce a minimum ship-readiness score before code goes out.

Process

Phase 1: Initialize the config

node ${CLAUDE_PLUGIN_ROOT}/tools/ship-gate.mjs init <project-directory>

Writes `.ultraship/ship-gate.json`:

{
  "thresholds": { "overall": 80, "seo": 70, "a11y": 80, "security": 90, "quality": 70, "bundle": 70 },
  "hardFail": { "onLeakedSecrets": true, "onCriticalFindings": true },
  "skipMissing": true
}

• **thresholds** — minimum score (0–100) per category and overall. Below it = fail.
• **hardFail.onLeakedSecrets** — any secret finding fails the gate regardless of score.
• **hardFail.onCriticalFindings** — any `critical`-severity finding (any audit) fails the gate.
• **skipMissing** — categories that didn't run (e.g. no HTML → SEO/a11y skipped) are ignored rather than failing. Set `false` to require every category.

Tune thresholds to the project. Sensible starting points: backend API → drop `seo`/`a11y`/`bundle` or rely on `skipMissing`; marketing site → raise `seo`/`a11y`; pre-revenue MVP → lower `overall` to 70.

Phase 2: Run the gate

node ${CLAUDE_PLUGIN_ROOT}/tools/ship-gate.mjs run <project-directory>
# or, installed: npx ultraship ship-gate .
# machine-readable: ... run <dir> --json

It runs all six auditors (seo, a11y, secrets, code-profiler, deps, bundle), scores them, and prints a PASS/FAIL table with a **merge-confidence** number (the overall score). **Exit 0 = pass, exit 1 = fail.**

Phase 3: Explain and fix failures

When the gate fails, report exactly which checks were below the bar, then fix:

• Score below a category threshold → run that category's fixer: `/a11y`, `/secure`, `/seo`, `/profile` apply fixes.
• Leaked secret → remove it, rotate the key, move it to an env var (`/secure`).
• Critical finding → resolve it before anything else.

Re-run the gate to confirm it now passes. Never lower a threshold just to pass — fix the issue, or change the threshold only with the user's explicit agreement and a reason.

Phase 4: Enforce it (CI + pre-push)

Wire the gate in so it runs automatically:

# GitHub Actions workflow at .github/workflows/ship-gate.yml
node ${CLAUDE_PLUGIN_ROOT}/tools/ship-gate.mjs ci <project-directory>

# Local git pre-push hook (.git/hooks/pre-push) — blocks a push that fails the gate
node ${CLAUDE_PLUGIN_ROOT}/tools/ship-gate.mjs hook <project-directory>

Tell the user how to bypass the local hook in an emergency: `git push --no-verify`. The CI gate has no bypass by design.

Key Principles

• **One source of truth.** The gate and `/ship` share the same scoring module — the gate can never disagree with the scorecard.
• **Deterministic.** Same input → same verdict. Auditable for SOC2/ISO/HIPAA, unlike an LLM-only "looks fine."
• **Fix, don't dodge.** Failing the gate means fixing the code, not weakening the threshold.
• **Never block on a missing tool.** A tool that can't run leaves its category skipped (or fails only if `skipMissing:false`), never crashes the gate.