Orchestrata Ultimate › Gates › ruff

Gate: ruff

At a glance

What it refuses

A ruff lint violation anywhere in src/, tests/, or scripts/ under the [tool.ruff] configuration in pyproject.toml.

Why it exists

Ruff is the standard linter (CLAUDE.md commands: uv run ruff check src/ tests/); its presence in the battery needs no incident. What is recorded is why the battery pairs it with an autoformat pass (scripts/gates.py docstring, self-healing behavior):

"lint: ruff --fix + black run BEFORE the gates. The user-level autoformat hook only fires on Write/Edit tool calls, so any file written by a script (heredoc, codemod, generator) skipped it and failed the lint gate later."

So the battery's autoformat() runs uv run ruff check --fix -q src/ tests/ scripts/ and uv run black -q src/ tests/ scripts/ first (skippable with --no-fix), and the gate then verifies what remains.

How it runs

• Command (battery argv): uv run ruff check src/ tests/ scripts/
• When it fires: the scripts/gates.py battery (registered as ruff); the same check is CI's lint job and part of the everyday dev loop.
• Inputs: fingerprint roots _SRC = ("src", "scripts", "tests", "pyproject.toml") — pyproject carries the [tool.ruff] select/ignore config, so a rule toggled off re-runs the gate.
• Caching: the verdict is cached in .cache/gates.json against _fingerprint(roots): a sha256 over the relative path and bytes of every file under those roots whose suffix is .py, .toml, .pl, .json, .md or .sh (_interesting(), read through the AST toolkit on 2026-10-23). There is no per-gate suffix mask: this page previously quoted a GATE_MASKS comment, and git log --all -S GATE_MASKS -- scripts/gates.py finds no commit that ever contained one. A .pyi stub change therefore does not invalidate the cached verdict (derived from the code, not measured).

The two commit-time ruff layers

• Auto-fix, never blocking. scripts/hooks/pre-commit runs ruff check --fix on each staged .py file and re-stages it (|| true: a ruff failure here never blocks). On origin/master (a4cbc2bdf) the line is a plain uv run ruff check --fix "$FILE" (line 166). Commit 8a2cb42ad (2026-10-23, branch feat/maps-via-codetools, not pushed) changes it to uv run --no-sync ruff check --fix.
• The blocking check. scripts/gate.py review-staged runs code-review.py, whose RuffChecker calls <interpreter> -m ruff check --exit-zero --output-format=concise <file> with a 30 s timeout (read through the AST toolkit). It reports RUFF_NOT_FOUND (no ruff module for that interpreter), RUFF_CHECK_ERROR (non-zero exit with no parseable output) and RUFF_TIMEOUT, all at ERROR, so a review in which ruff never ran cannot look clean.

Typical failures and how to fix them

• Exit code: ruff's own — non-zero on violations, 0 clean.
• What a PASS looks like (real recorded battery output, .cache/gates.json):

  0.1s | All checks passed!
  

• What a failure looks like (representative): standard ruff findings — path:line:col CODE message — for whatever survived the auto-fix pass.
• Un-blocking: most cases fix themselves on the next battery run (the --fix+black pass); the rest are real findings to fix by hand. Rule-level configuration changes belong in pyproject.toml, where they also invalidate the prolog-gate cache (its tool_rule_status facts read the same tables).
• RUFF_NOT_FOUND in the commit review. The interpreter running the reviewers has no ruff. The pre-commit hook's comment records the earlier form of this: "a PATH without it made code-review.py report RUFF_NOT_FOUND as its only ERROR". Fix: run from the checkout's own .venv (the hook and ~/bin/precommit-check both put .venv/bin first on PATH).
• Trap: a plain uv run re-syncs the venv editable. The battery's argv is uv run ruff ... without --no-sync. Memory uv-run-flips-venv-editable (measured 2026-10-22) records that a plain uv run in an orchestrata checkout re-syncs the project venv as an editable install, after which the pre-push source-provenance gate refuses every push. .envrc line 47 exports UV_NO_EDITABLE=1, which only a direnv shell gets; hooks and direnv-less worktrees do not. Whether the battery's uv run ruff flips the venv was not measured. If .venv/.../orchestrata_ultimate-*.dist-info/direct_url.json shows "editable": true, re-sync with env -u PYTHONPATH -u PYTEST_ADDOPTS uv sync --dev --no-editable --frozen before pushing.

Wiring

• Invokers: scripts/gates.py (battery), CI's lint job, deploy/ship.sh (verify stage), code-review.py via gate.py review-staged (commit), uv run ruff check in the dev loop.
• Tests: exercised through the battery's own tests (tests/scripts/test_gates.py, test_gates_coverage.py) — ruff itself is an external tool, not project code.

Related

• Gates master index
• Development workflow
• review-staged — the commit review that runs ruff per file
• commit-precheck — the same review without committing
• ship-verify — ship's ruff and black checks
• ci-pipeline — CI's lint job
• source-provenance — the gate an editable venv trips
• mypy — the other imported-tool gate, with its own false-green history
• prolog-gate — reads the ruff select/ignore lists as facts
• RUL-008 — Review before every commit
• ADR-0089 — bare toolchain names fail the gate