quality

quality is the one door for the fleet's quality checks: repository rules, secret and advisory scans, the SonarCloud findings, and the fail-closed pull request verdict. It is for the engineer who adds the gate to a repository and for the operator who merges past it.

quality check [AREA ...] [--staged] [--fix] [--dry-run] [-v]
quality sonar properties [-v]
quality sonar findings [-v]
quality verdict [-v]
quality report
quality merge OWNER/REPO#N [--dry-run]

Exit codes: 0 clean, 1 findings, 2 cannot judge (never clean), 130 interrupted (Ctrl-C).

Install

uv tool install --python 3.14 "overnightworks-quality @ git+https://github.com/overnightworks/quality@<tag or commit sha>"

--python 3.14 matters because uv tool install --force keeps an existing tool environment's older interpreter, which then refuses v0.3.0 or later.

The gitleaks paths (check, check secrets --staged) need git 2.41 or newer; with an older git they exit 2.

gitleaks, actionlint and osv-scanner come through mise, from the manifest and lock inside quality's installation; a scanner that is missing exits 2 and names the command that installs it:

mise --cd <quality's installation>/quality/mise install --locked

Quick start

A repository adopts the gate with one caller job of gate.yml and a quality/config.toml that names the mandatory jobs; docs/gate.md has the snippet and the reason for each line. The gate's sonar job also needs a SonarCloud project with automatic analysis off, a root sonar-project.properties and the SONAR_TOKEN secret (a missing token is red), unless quality/config.toml sets [gate] sonar = false; see docs/sonar.md.

Locally, quality check runs every rule the gate runs, the secret, workflow and advisory scans included; quality check <area> runs only that area.

Read on

• docs/VISION.md: what quality is, who uses it and what it deliberately does not do.
• docs/ARCHITECTURE.md: the parts, who talks to whom, the trust boundaries and the reasons behind the constraints.
• docs/rules.md: the check rules, the secret and advisory scans.
• docs/output.md: the output contract: what every command prints and why it may.
• docs/commands.md: check secrets --staged, the scanners, report and merge.
• docs/gate.md: the gate.yml caller contract, the verdict, declared loosenings, startup failures.
• docs/codeql.md: the codeql.yml caller contract.
• docs/release.md: the release path (release-gate.yml, release-tag.yml, image.yml), its caller contract, how quality releases itself and the standard.
• docs/sonar.md: sonar findings, coverage on new code, new and legacy findings, the quality gate, the Dependabot exception.
• docs/runbooks/merge.md: the operator's door past a red gate.
• AGENTS.md: the contract for agents working in this repository.