chore: engineering hygiene — version sync, lint/type/coverage/matrix CI, supply-chain, OSS scaffolding

[abrichr]

Summary

Raises the engineering system to match the code/test quality (per an external review that flagged it as narrow). No runtime logic changes — everything here is config, CI, docs, formatting, and one real one-line version-drift fix. Two commits:

1. style: — mechanical ruff format + import sort across the package (isolated so the rest stays reviewable; drop it if you'd rather not adopt the formatter).
2. chore: — the actual hygiene work below.

What's in it

1. Version-drift bug (real)

openadapt_flow.__version__ was 0.1.0 while pyproject/PyPI are 0.4.0. Synced to 0.4.0 and added version_variables = ["openadapt_flow/__init__.py:__version__"] to [tool.semantic_release] so releases keep them in lockstep. The clean-wheel CI job asserts __version__ == importlib.metadata.version(...) so this can't silently drift again.

2. Lint / format / type gates (green, not aspirational)

• ruff lint + format config ([tool.ruff]). Selects pyflakes/pycodestyle-safe/warnings/isort; opinionated rewrite families deferred so it's green today and tightenable.
• mypy config ([tool.mypy]) scoped to the core package, not tests, ignore_missing_imports for optional extras. Lenient to start; ~53 modules are gated, and 18 modules with pre-existing type debt are listed under [[tool.mypy.overrides]] ignore_errors with a "tighten incrementally" note.
• Added py.typed (PEP 561) + a wheel force-include so downstream type-checkers honor our annotations.
• All three gates are green locally: ruff check ✔, ruff format --check ✔ (71 files), mypy ✔ (Success, 71 source files).

3. CI matrix (.github/workflows/ci.yml)

• Python 3.10 / 3.11 / 3.12 / 3.13 on Linux (was 3.12-only) + a macOS leg (3.12). fail-fast: false for visibility.
• New lint + type-check job (ruff check, ruff format --check, mypy).
• New clean-wheel install job: python -m build, install the wheel in a fresh venv, import from outside the source tree, assert version parity + py.typed presence.
• New Windows job running the mock WindowsBackend + RDP suites (no live VM, no browser).
• Coverage via pytest-cov reported for visibility (no hard floor yet).

4. README staleness

• Corrected the stale "Desktop and RDP backends are adapters to come" — both exist now: WindowsBackend (desktop, experimental) and FreeRDPBackend (pixel-only RDP, frame decode proven against a real captured frame). Browser is the production path; desktop/RDP are real but earlier on the curve.
• Added a "When to use something else" section (vs Playwright codegen / Selenium IDE / UiPath) answering why vision anchors instead of selectors when a DOM is available — determinism + cross-substrate + the identity/safety layer — with the honest caveat that where a DOM/UIA tree exists selectors are often the better signal (and we ship a DOM-selector benchmark arm precisely to test that).

5. Supply chain

• Pinned every GitHub Action by commit SHA (both ci.yml and release.yml), version recorded in a trailing comment.
• Added Dependabot (.github/dependabot.yml) for github-actions + pip; it understands the # vX comment and proposes SHA bumps, so pinning doesn't freeze us on stale releases.
• ⚠️ Action item (settings, not code): release.yml uses secrets.ADMIN_TOKEN, an org-level secret with visibility "all" — every repo in the org can read it. It should be replaced with a repo-scoped fine-grained PAT (or a GitHub App installation token) limited to this repo's contents: write. Flagged inline in release.yml; changing the secret is a repo/org settings action that can't be done in this PR.

6. OSS scaffolding

CONTRIBUTING.md, SECURITY.md (PHI-aware private reporting via GitHub Security Advisories — important for a PHI-adjacent tool), CODE_OF_CONDUCT.md (Contributor Covenant 2.1), .github/ISSUE_TEMPLATE/ (bug/feature/config), PULL_REQUEST_TEMPLATE.md, and CODEOWNERS.

Verification (local)

• ruff check / ruff format --check / mypy — all green.
• Clean wheel build + install in a fresh venv + import + version/py.typed assertions — pass.
• All 70 importable modules import with zero syntax/format breakage.
• Core test subset: 342 passed, 6 skipped, 0 failures (compiler, vision, resolver, identity, windows/rdp backends, volatility, privacy, report, emit, interop, heal, dom-arm, desktop-benchmark). The full browser/OCR/benchmark E2E suite is left to CI (slow locally under concurrent load); the changes are formatting-only + one version string, so behavior is unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CKrVJJy5jWVCkXAqgUqtqZ

[abrichr]

Superseded by #77, which regenerates this content cleanly on current main (this branch's 42-file reformat was generated on old main and conflicts with everything merged since #72/#74/#75/#76 + auto-releases). Closing in favor of #77.