Add prek-based pre-commit lint hook

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+ignore = E501,W291,W293,D401,D400,E402,E302,D200,D202,D205,W503,E203,D204,D403
+extend-exclude = .venv,.uv-cache

.github/workflows/python_checks.yml

@@ -18,5 +18,5 @@ jobs:
         uses: reviewdog/action-flake8@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          flake8_args: --ignore E501,W291,W293,D401,D400,E402,E302,D200,D202,D205,W503,E203,D204,D403
+          flake8_args: .
           level: warning

.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.3.0
+    hooks:
+      - id: flake8
+        additional_dependencies:
+          - flake8-docstrings
+          - flake8-simplify
+          - flake8-unused-arguments
+          - flake8-annotations
+

README.md

@@ -59,6 +59,16 @@ Thank you for your interest in contributing to this project! Please follow these
 
 ## Code Quality
 
-Docstrings and type hints are checked via a GitHub Action (`python_checks.yml`) using [pydocstyle](https://www.pydocstyle.org/en/stable/) and [mypy](https://mypy-lang.org/). These produce advisory PR comments and do *not* block merges.
+Linting runs via flake8 in GitHub Actions (`python_checks.yml`) and posts advisory review comments (non-blocking).
+
+To run the same lint checks before committing, install and use the `prek` pre-commit hook runner:
+
+```bash
+uv sync --group dev
+uv run prek install
+
+# run hooks on all files
+uv run prek run --all-files
+```
 
 Note: `python_checks.yml` only runs on pull requests from within the repo, not from forks.

docs/testing.md

@@ -74,6 +74,16 @@ The pipeline has a 20-minute timeout.
 
 A separate workflow (`.github/workflows/python_checks.yml`) runs flake8 linting via reviewdog on pull requests. These are advisory warnings and do not block merges.
 
+For local lint checks before commit, use `prek`:
+
+```bash
+uv sync --group dev
+uv run prek install
+uv run prek run --all-files
+```
+
+The hook and CI use the same flake8 configuration from `.flake8`.
+
 ## Test Structure
 
 ```

pyproject.toml

@@ -46,12 +46,17 @@ dependencies = [
 dev = [
     "deepdiff>=8.5.0",
     "docker>=7.1.0",
+    "flake8>=7.3.0",
+    "flake8-annotations>=3.2.0",
+    "flake8-docstrings>=1.7.0",
+    "flake8-simplify>=0.22.0",
+    "flake8-unused-arguments>=0.0.13",
     "pendulum>=3.1.0",
+    "prek>=0.3.1",
     "pytest>=7.2.2",
     "pytest-asyncio~=0.25.2",
     "pytest-mock==3.12.0",
     "pytest-timeout~=2.3.1",
     "vulture>=2.14",
 ]
 
-