## Use case

`pr_ci.yaml` runs `flake8 datastore --count --show-source --statistics`
as the only PR gate that blocks merge. The configuration in `setup.cfg`
deliberately limits flake8 to critical errors (`E9, F63, F7, F82`).

flake8 here works, but it's a tool we install at PR time, run, and
discard. Migrating to ruff gets us:

- **Speed**: ruff 0.15 scans 43 `datastore/*.py` files in ~7 ms; flake8
  6.x is multi-second on the same set
- **Single Rust binary** vs flake8's plugin ecosystem (no pinning
  drama, no surprise behaviour change from a transitive plugin update)
- **Same rule codes** (`E9`, `F63`, `F7`, `F82`) — true drop-in, no
  policy change implied
- **Standard `pyproject.toml` config** — consolidates with the
  existing `[tool.pyright]` and `[tool.pytest.ini_options]` sections
- **Future capacity** to enable formatting / import-sorting via
  `ruff format` if we ever want to (separate decision)

Most major Python projects (pandas, polars, FastAPI, Jupyter) have
already migrated. Recent chDB CI is the kind of place this lift is
both cheap and visible.

## Proposed solution

**Path 1 (drop-in parity, recommended)** — replace flake8 with ruff,
preserving exact behaviour:

```toml
# pyproject.toml — replaces setup.cfg [flake8]
[tool.ruff]
line-length = 120
target-version = "py39"
extend-exclude = [".tox", "build", "dist", ".eggs", "docs/conf.py", "datastore/tests"]

[tool.ruff.lint]
select = ["E9", "F63", "F7", "F82"]
ignore = ["F811"]

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]

# .github/workflows/pr_ci.yaml
- name: Install ruff
  run: python -m pip install ruff

- name: Lint datastore with ruff
  run: ruff check datastore --statistics

I have this on a local branch (feat/lint-migrate-to-ruff) — one
commit on top of main. Verified locally with ruff 0.15.12 on the
current codebase: scans 43 datastore/*.py files (excluding
tests/) in 6.7 ms, zero findings — exact behavioural parity with
the current flake8 setup.

If this proposal gets a thumbs-up, I'll open the corresponding PR.

Alternatives considered

1. Stay on flake8. Works fine today; the cost of "if it ain't
   broke, don't fix it" is real. The migration is justified by
   speed + tooling consolidation, not by a current pain point.
2. Migrate AND enable ruff format (formatting check). Tempting
   — would replace currently-unenforced black in
   requirements-dev.txt. But formatting policy is its own decision
   (existing diffs would all need formatting; ruff format ≠ black
   in a few edge cases). Suggest splitting into a follow-up.
3. Migrate AND enable broader rule set. E.g. add E5
   (line-length), W (warnings), I (isort), B (bugbear). Higher
   signal but unknown findings on the 1.5 MB existing codebase. Out
   of scope for this proposal; this is pure drop-in.

Additional context

• AGENTS.md §2.9
  explicitly defers this decision to maintainer discussion:
  "Adding a new gate (e.g. enforcing black, turning on
  mypy --strict, migrating flake8 → ruff) is a project-wide
  decision; open an issue and let maintainers weigh in." — this
  issue is that step.
• Migration affects only the lint gate — no .py source files change.
• setup.cfg becomes empty after removing [flake8] (no other tool
  reads it in this repo), so the proposed change deletes it. If you'd
  prefer keeping an empty setup.cfg for future tools, easy to revert.
• Adjacent docs (AGENTS.md §2.9 / §6.3 / §11, the new PR-template
  checklist) reference flake8 by name. Once both this PR and the
  AGENTS.md PR (#NNN) merge, a small follow-up commit can update the
  doc references to ruff. Keeping the change small and targeted here.