Agent harness: AGENTS.md, bin/check and bin/t, Ruff 0.17.1

[bencap]

Sets the repo up so coding agents (and new contributors) get the facts they can't derive from the code, plus checks fast enough to run after every edit.

Changes

• Ruff 0.17.1, pinned once.
  • poetry.lock is now the only place Ruff's version is pinned. The pre-commit hooks run poetry run ruff instead of their own copy, which was stuck at 0.6.8.
  • The lint rule set is written out (select = ["E4", "E7", "E9", "F"], Ruff's pre-0.16 defaults), so upgrading Ruff no longer changes which rules apply. Wider rules can come later, one commit each.
• One formatting commit (dcf4e382) brings the tree in line with 0.17.1. It's listed in .git-blame-ignore-revs, so git blame skips it.
• bin/check runs Ruff lint, the Ruff format check and mypy in about 3 s warm, and reports every failure in one pass.
• bin/t wraps pytest and refuses to run without a target, so the ~20-minute full suite only runs when asked for.
• CI runs the same scripts. The separate lint and mypy jobs merge into one bin/check job, which adds the format check CI didn't have. Neither main nor release-2026.4.0 requires status checks, so the renamed job doesn't affect branch protection.
• AGENTS.md (~37 lines; CLAUDE.md imports it) holds only what applies in every api session: setup, commands, and the rules that apply whatever file is open, including one-line forms of the permission and async (API handlers block the event loop, and database calls have no timeout #881) rules. There's no glossary, because the model docstrings already define the domain terms.
• .claude/rules/ holds path-scoped detail (permissions, database, routes, migrations, tests, worker), loaded only when matching files are touched. One-time contributor setup moves to the README.
• Removed:
  • .github/instructions/: Claude Code never loaded these files, and they had drifted from the code (a wrong permissions import, and a visibility example that leaks).
  • The Makefile: bin/ replaces it.
• .claude/settings.json holds shared permission rules for Claude Code sessions. It blocks --no-verify and reading ~/.aws, ~/.ssh or ~/.pgpass; sets AWS_PROFILE to the read-only agent role (VariantEffect/mavedb-deployment#54); and asks only before hard-to-undo actions: force pushes, pushes to main, mavedb-main, mavedb-dev or release-*, AWS with an explicit profile, eb, the prod-API dev server, adding a dependency, and edits to settings.json itself. Identical copies live in each repo and the workspace, because Claude Code reads settings only from the folder a session starts in. They catch honest mistakes; they aren't a security boundary.

Review notes

• Ruff 0.17 also formats Python code blocks in Markdown. That's why some .md docs changed in the formatting commit, and why the format hook now covers Markdown.

• Cross-repo rules have moved out of this repo. Test integrity, credentials, treating issue text as data, dependency changes and comment style now live in the workspace-level AGENTS.md in VariantEffect/mavedb-workspace, which sits above the repo checkouts. That repo is private for now, so someone with only this repo doesn't get those rules.

• Merge with a merge commit, not a squash. Squashing changes the formatting commit's hash, and .git-blame-ignore-revs would stop matching it.

• Expect a conflict when this reaches main: main pins Ruff ~0.15. Resolve it to ~0.17.1.

• After pulling, once per clone:

  poetry install --with dev --extras server
  poetry run pre-commit install
  git config blame.ignoreRevsFile .git-blame-ignore-revs

Testing

• bin/check passes.
• 750 targeted tests in the modules the formatting commit touched pass, run with bin/t.
• pre-commit run --all-files passes.
• CI runs the full suite.

[coveralls]

Coverage Report for CI Build 38980701648

Coverage decreased (-0.06%) to 90.343%

Details

• Coverage decreased (-0.06%) from the base build.
• Patch coverage: 2 of 2 lines across 2 files are fully covered (100%).
• 12 coverage regressions across 3 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

12 previously-covered lines in 3 files lost coverage.

File	Lines Losing Coverage	Coverage
src/mavedb/lib/clinvar/utils.py	6	90.91%
src/mavedb/worker/jobs/external_services/clinvar.py	4	96.97%
src/mavedb/lib/mondo_ols.py	2	96.92%

---

Coverage Stats

Relevant Lines:	19157
Covered Lines:	17307
Line Coverage:	90.34%
Coverage Strength:	0.9 hits per line

---

💛 - Coveralls