build: bound ruff to >=0.16,<0.17 and make lint config explicit

[abrichr]

Why

openadapt-ml declared ruff>=0.1.0 in dev deps and had no [tool.ruff] section at all — no line-length, no target-version, no select, no include. Every lint decision was inherited from whatever ruff version a runner happened to resolve.

ruff 0.16.0 (published 2026-07-23) then changed both halves of that implicit contract at once:

	0.14.9	0.16.0
default rules	59	413
ruff check openadapt_ml/	0 findings	1035 findings
default include	no *.md	*.md added
ruff format --check openadapt_ml/	109 files clean	3 .md files + 1 .py file would reformat

Neither change needed a commit in this repository to take effect. main is green today only because uv.lock happens to pin ruff 0.14.9 — I confirmed against the most recent main run (30316173438, job log shows + ruff==0.14.9) that CI would otherwise already be red.

This follows the same fix already merged in openadapt-consilium (#11, 0→54) and OmniMCP (#34, 0→375).

The rule-set decision

An explicit bounded select, not ruff's defaults. 1035 findings in openadapt_ml/ is not a set anyone can review honestly in one change, and it is overwhelmingly not defect-finding:

family	count	why not now
UP	581	Optional[X]→X | None, List→list. Pure typing churn.
BLE001	156	Blind except Exception on best-effort dashboard/VM-status probes that are deliberately blind.
PLW1510	73	subprocess.run without check=. Every fix is a behaviour change needing per-call judgement.
I001	82	Real — adopted.

Adopting 413 rules by accident is the opposite of the predictability this PR is for. Each of those families can be adopted later, deliberately, on its own merits.

Chosen: select = ["B", "E", "F", "I", "W"], ignore = ["E501"].

• E,F,I,W is the OpenAdapt house selection (openadapt-capture, -privacy, -telemetry, -crier, -herald, -desktop, OpenAdapt). Note this is wider than what this repo actually enforced before — ruff's old default was effectively E4,E7,E9,F, so I and the rest of E/W are net new coverage, not a retreat.
• B (flake8-bugbear) is added on top because it is the one extra family that pays for itself here: 36 findings repo-wide, all real defect shapes rather than style. It guards code paths that pair model outputs against ground truth, where a silent length mismatch is exactly the class of quiet wrong answer this project cares about.

[tool.ruff] is now explicit: line-length = 88 (what the tree already uses — the house value of 100 would rewrap 70 of 112 files for no behavioural gain and bury this change), target-version = "py310", and include pinned to 0.16's default list minus *.md, so a future addition to either default list is inert until someone edits this file.

Reasons are written inline in pyproject.toml, not just here.

Defects fixed

Real behavioural defects:

• scripts/generate_vm_screenshots_simple.py:84,88 — two bare except: around PIL font loading. These also caught KeyboardInterrupt and SystemExit, so pressing Ctrl-C while a font was loading was silently swallowed and fell through to the fallback font instead of exiting. Narrowed to except OSError (what ImageFont.truetype actually raises).
• openadapt_ml/training/grpo/config.py:81,94 — task_dir declared twice in the same dataclass, the documented declaration shadowed by a later bare one. Both defaulted to None, so behaviour is unchanged today, but editing the documented default would silently have had no effect. This is the same shape as the config constant shadowing found in the consilium work.
• scripts/p0_validate_demo_persistence.py:95,124,184 — three "Episode" annotations naming a symbol the module never imports. Honest caveat: from __future__ import annotations is in effect, so these were not runtime NameErrors — but they were unresolvable to typing.get_type_hints() or any runtime introspection. Now imported under TYPE_CHECKING.
• 10 × B904 — exception chaining restored (from e), so a friendly "install pyarrow" / "install sentence-transformers" ImportError no longer hides the underlying cause. A broken transitive install surfacing as an ImportError deep inside a package is usually the actually-useful part of the message.

B905 — 16 × zip() now declares its intent, with no behaviour change:

• strict=True only where equality is already guaranteed by an adjacent len() guard or by construction, so it can never fire.
• strict=False with an inline reason where truncation is genuinely tolerated (frame_describer._load_recording has four backends and none guarantees one action per frame; grpo_e2e_report renders arbitrary on-disk JSON and must not crash on it; CanonicalEpisode.source_recordings / source_episode_ids are documented as related but not declared parallel — flagged as a latent smell, not changed).
• The one substantive case is representation_shootout/evaluator.py:527, where a short model_outputs could silently shrink the sample set the aggregated metrics are computed over. Its docstring already declared the correspondence as a precondition; that precondition is now enforced.

Mechanical (cosmetic, no behaviour change): 130 × I001 import sorting, 54 × F541 f-strings without placeholders, 37 × F401 unused imports, 5 × F811 redundant import os shadowing the module-level import, 4 × F841 dead bindings, 3 × E712 == True/False in assertions, 10 × B007 unused loop variables.

No import removal touched openadapt_ml/. I diffed the imported-name set of every changed file: all 21 removals are in scripts/, tests/ and examples/. The __init__.py changes are pure reordering — nothing was dropped, and re-exports including the TextEmbedder/TFIDFEmbedder backward-compat alias were verified importable.

Rules deliberately disabled

Exactly one, at config level:

• E501 (line too long) — line length is left to the formatter. ruff format already wraps what it can; the residue is long string literals, URLs and comments that E501 would only push into worse line breaks. Every OpenAdapt repository ignores it for this reason. Reason is inline in pyproject.toml.

Two narrow # noqa: F401, each with an inline reason, on optional-dependency availability probes (tests/test_api_adapter.py, tests/test_trl_trainer.py) where the import is the test. importlib.util.find_spec — the rule's own suggestion — only proves a module is locatable, not that it imports, which is exactly what these guards need on a partial --all-extras install. Preferred over a whole-file per-file-ignore.

Reviewed and deliberately not changed

• 33 × S110/S112 (try/except/pass and /continue). I read every one. All are best-effort dashboard, telemetry, VM-status and cache-read probes that degrade to a documented default. None swallows a credential or decision-path failure — i.e. nothing of the shape found in the consilium work.
• 7 × RUF012 mutable class defaults — all read-only class-level registries (SUPPORTED_MODELS, DEFAULT_TUNNELS, RELEVANT_EVENT_TYPES). No mutation bug.
• B006 mutable argument defaults — none exist in this tree.
• 3 × PLW0603 global statements — benign lazy singletons.

CI gate

ruff check widened from openadapt_ml/ to the whole repository. Every genuine defect above was in scripts/ or tests/ — outside the old gate — so fixing them without widening would let them regress immediately. Ruff runs in well under a second; this costs no measurable CI time.

ruff format --check deliberately stays scoped to openadapt_ml/: 37 files under scripts/, tests/ and examples/ have never been formatted, and normalising them is a separate, purely cosmetic change.

Lockfile

uv.lock relocked so CI genuinely exercises the new bound (a bound CI never runs proves nothing). The relock also repairs a lockfile that predated the build and openadapt-types dependencies. Despite the line count, the semantic diff is small and safe:

• version changes: ruff 0.14.9 → 0.16.0, and this package's own stale self-version 0.9.0 → 0.16.1
• 21 additions (the previously-unlocked build, openadapt-types, and openadapt-capture[share]'s chain)
• zero removals, zero downgrades

The remaining churn is a lockfile format bump (revision = 3) adding upload-time metadata.

Release

build:, not fix: — patch_tags = ["fix", "perf"], so this deliberately does not trigger a release. Nothing in the shipped openadapt_ml package changes behaviour for a user: the bare-except and undefined-name defects are both in scripts/, which is not packaged, and the duplicate dataclass field had identical defaults on both declarations. Burning a release and a 4-leg matrix on that is not warranted; the B904 chaining will ride along with the next real release.

Verification

Run locally against ruff 0.16.0 installed from the updated lock, using CI's exact commands:

uv sync --all-extras                        # + ruff==0.16.0, uv.lock unchanged
uv run ruff check .                          # All checks passed!
uv run ruff format --check openadapt_ml/     # 109 files already formatted
uv run pytest tests/ -v --ignore=tests/integration
                                             # 454 passed, 2 skipped

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM