# Compatibility and support

> Understand quality's stable contracts, exit codes, supported platforms, and upgrade policy.

## Stable contracts

`quality.yml` has its own integer `version`. A release rejects configuration
versions it cannot interpret instead of silently changing their meaning.

The native JSON produced by `check`, `format`, `fix`, `doctor`, `repositories`,
`ci plan`, `ci local`, `ci history`, `ci show`, `ci compare`, `impact plan`, and
`impact verify` includes `schema_version: 1`. Consumers should require a schema
version they understand. Published schemas validate the exact current producer
contract. Forward-compatible report readers should validate the fields they
consume and tolerate newly added report fields. Configuration and impact
verification inputs reject unknown fields.

Published schemas describe the current contract:

- [`check`, `format`, and `fix` reports](/quality-report.schema.json)
- [`doctor` reports](/quality-doctor.schema.json)
- [`repositories` reports](/quality-repositories.schema.json)
- [`local CI plans`](/quality-ci-plan.schema.json)
- [`local CI run reports`](/quality-local-ci.schema.json)
- [`local CI history`](/quality-local-ci-history.schema.json)
- [`local CI comparisons`](/quality-local-ci-comparison.schema.json)
- [`impact configuration`](/quality-impact.schema.json)
- [`impact plans`](/quality-impact-plan.schema.json)
- [`impact execution results`](/quality-impact-results.schema.json)
- [`impact verification reports`](/quality-impact-verification.schema.json)
- [`quality.yml`](/quality.schema.json)

Impact configuration and execution results also use `schema_version: 1`. Their
schemas validate the JSON structure and value constraints. `impact verify`
additionally checks the committed source, complete dependency graph, plan
identity, and one result per selected node. A schema-valid result file alone
does not prove that its checks ran. Plans must be verified by the same Quality
version that generated them; regenerate plans after upgrading.

Within a stable CLI major release, existing command names, flags, built-in
adapter IDs, GitHub Action input and output names, and fields required by the
published report schemas remain compatible. New optional fields, adapters, and
flags may be added. Removing or changing the meaning or type of an existing
contract requires a new CLI major release or report schema version.

The `agent` format is a bounded human- and model-readable Markdown presentation,
not a versioned machine contract. Its headings and limits may evolve within a
major release. Integrations that require stable fields or complete diagnostics
must use JSON or SARIF.

Preset output is intentionally upgradeable. A minor release may update pinned
analyzer versions or generated policy, but `quality preset diff` and
`quality preset update --dry-run` expose the change before files are replaced.

## Exit codes

| Code | Meaning |
| ---: | --- |
| `0` | The command completed and its selected policy was satisfied. |
| `1` | The command completed but found diagnostics, missing required tools, failed configured checks, preset drift, or selected repository-audit conditions. |
| `2` | The command could not complete because its invocation, configuration, project discovery, or I/O was invalid. |

Do not parse human-readable output to distinguish results. Use JSON or SARIF
and inspect normalized statuses, `failure_kind`, diagnostics, and summaries.

## Supported platforms

Prebuilt releases support:

- macOS on Apple Silicon and Intel
- Linux on ARM64 and x86-64 with glibc
- Windows on x86-64

The CLI and GitHub Action are tested on Linux, macOS, and Windows. Individual
analyzers retain their own platform requirements; for example, Swift checks
normally require macOS and Android checks require a compatible JDK and Android
toolchain.

The latest stable major release receives fixes. Older major releases may receive
critical security fixes when explicitly announced. Analyzer compatibility is exercised by
the repository's real-adapter CI using pinned representative versions, while
repository-local command and argument overrides remain available when an
upstream analyzer requires a different invocation.

## Upgrade and rollback

Pin exact release tags in CI for reproducibility. Review the changelog and
Changesets, update the pinned version, then run `quality doctor` and the full
repository gate. Keep the previous binary or Action tag available so rollback
only requires restoring that pin; configuration and baseline formats are
rejected explicitly when unsupported rather than migrated destructively.
