Reliability contract

This page describes the reliability contract for the ShipGate CLI and documented CI workflows. It is a product honesty document: we optimize for what we can support consistently, not for the widest feature list.

• Which commands are Tier-1 (contract-backed): Tier-1 supported surface
• Exit codes for CI: Exit codes (Tier-1)

For implementation details of specific commands, see the CLI reference and linked pages.

What we guarantee

Within the Tier-1 supported surface (explicitly listed in each release’s command matrix and changelog):

• Deterministic exit codes for Tier-1 commands, as documented per command (e.g. gate, next); we are aligning all Tier-1 commands to a single published matrix over time.
• Stable machine-readable artifacts where we publish a schema — for example, Next.js golden-path evidence ships with a JSON Schema in the @shipgate.dev/cli npm package under schemas/, and evidence JSON includes a schemaVersion field (see monorepo docs/output-contracts.md).
• Documented flags for Tier-1 commands behave as described in this documentation site for the matching semver of the CLI you installed.

What we do not guarantee

• Every subcommand visible in shipgate --help is equally tested, stable, or suitable for production CI. Commands outside the Tier-1 matrix are best-effort unless marked otherwise in the release notes.
• AI-assisted flows (keys required, network calls, model variability) are not deterministic in the same sense as parse/check/verify on static files. Treat AI outputs as drafts until verified by a deterministic gate.
• Green CI in the ShipGate open-source monorepo does not imply your repository passes; your stack, config, and paths may differ.
• Scores and thresholds are tools for judgment, not certifications of legal or regulatory compliance by themselves.

How we classify findings

Findings generally fall into:

Class	Meaning
Blocker	Contributes to NO_SHIP for the command’s verdict rules (e.g. empty route handlers, failing specless gate thresholds, spec verification failure).
Warning	Reported but may not fail the command depending on flags (e.g. env hygiene without --strict-env / strict_env in .shipgate/next.yml).
Informational	Context only; does not change exit code.

Exact behavior is defined per command in its CLI reference page.

Unsupported repositories

If the project does not meet the documented prerequisites for a command (for example, shipgate next requires a Next.js App Router layout), we return NO_SHIP with explicit findings (e.g. setup / unsupported codes in golden-path evidence when evidence export is enabled).

We do not claim support for every framework or monorepo layout. Use the narrowest command that matches your stack, or contribute a fixture + contract test if you need first-class support.

Golden-path evidence

When you pass --evidence-out and --summary-out to shipgate next, you receive:

• JSON aligned with golden-path-evidence.schema.json (see npm package schemas/).
• Markdown summary including blockers and non-blocking warnings.
• Optional: --compare-evidence <prior.json> adds a deterministic findingsDelta (new / resolved / unchanged stable keys) to JSON and the Markdown summary.

Evidence is written even when setup fails (wrong directory, missing package.json, or not a Next app), so CI and PR automation can always attach a machine-readable reason.

Canonical maintainer copy (pins, CI guards, claim registry): docs/reliability-contract.md in the ShipGate monorepo.

Organization policy (.shipgate.policy.yml)

For shipgate gate, if the policy subsystem throws (for example unreadable custom policy path), the CLI fails closed (NO_SHIP) by default so CI cannot silently skip enforcement. Use --policy-lenient only for legacy workflows that explicitly accept skipping enforcement on errors — not for production gates.

Changes to this contract

We treat Tier-1 behavior as semver-sensitive:

• Patch: Bug fixes, clearer errors, docs corrections.
• Minor: New optional flags, new non-breaking schema fields (with schemaVersion policy documented in changelog).
• Major: Removed commands, changed exit codes, or stricter default enforcement.

---

Related (internal to maintainers): docs/internal/TRUST_CRACK_REGISTER.md — trust crack register, remediation roadmap, and release gates.