chore(dev): add pre-commit config mirroring the CI gates (#1129)

Create .pre-commit-config.yaml with ruff (lint + format), mypy and basic
hygiene hooks so local commits fail for the same reasons PRs would.

- Ruff lint (--fix for local convenience, no drift vs CI's ruff check .)
- Ruff format check (not yet gated in CI but zero drift — same tool)
- Mypy via language:system/uv to match CI's uv run python -m mypy .
- Hygiene: large files, merge conflicts, YAML/TOML syntax, trailing
  whitespace, EOF newlines
- Updated development-setup.md with install/run/skip/update docs

Closes #940

Co-authored-by: dyzur <dyzur@users.noreply.github.com>
Co-authored-by: Luis Novo <lfnovo@gmail.com>

.pre-commit-config.yaml

@@ -0,0 +1,52 @@
+# Pre-commit hooks mirroring the CI gates so local commits fail for the same
+# reasons PRs would. See .github/workflows/test.yml for the CI equivalents.
+#
+# Install: uv run pre-commit install
+# Run on all files: uv run pre-commit run --all-files
+# Update hook versions: uv run pre-commit autoupdate
+
+repos:
+  # ── Basic hygiene ──────────────────────────────────────────────────
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-added-large-files   # blocks >500 KB binaries
+      - id: check-merge-conflict      # catches unresolved conflict markers
+      - id: check-yaml                # validates YAML syntax
+      - id: check-toml                # validates TOML syntax
+      - id: end-of-file-fixer         # ensures files end with a newline
+      - id: trailing-whitespace       # removes stray trailing whitespace
+        args: [--markdown-linebreak-ext=md]
+
+  # ── Ruff: Python lint & format (mirrors CI backend-lint job) ──────
+  # Version kept in sync with pyproject.toml [dependency-groups] dev.
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.13
+    hooks:
+      # `ruff check --fix` — applies safe auto-fixes (e.g. import sorting)
+      # and reports remaining violations. CI runs `ruff check .` without
+      # --fix; the local auto-fix saves iteration with no drift risk.
+      - id: ruff
+        args: [--fix]
+      # `ruff format --check` — fails if files don't match ruff's formatter.
+      # Run `ruff format .` to fix. Not yet gated in CI but uses the exact
+      # same tool config, so there is no drift.
+      - id: ruff-format
+
+  # ── Mypy: Python type check (mirrors CI backend-typecheck job) ────
+  # Uses language: system so mypy runs through `uv` in the project's own
+  # virtualenv (the same way CI and `make lint` run it). Pre-commit's
+  # isolated mirror-mypy would miss errors from missing project deps like
+  # langgraph and langchain — that breaks the "no drift" rule.
+  #
+  # Note: type-checking the full project on every commit is slower than
+  # the per-file hooks above. Skip it with `SKIP=mypy git commit`.
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run python -m mypy .
+        language: system
+        types: [python]
+        pass_filenames: false
+        verbose: true

docs/7-DEVELOPMENT/development-setup.md

@@ -256,13 +256,52 @@ cd frontend && npm run dev
 
 ### Pre-commit Hooks (Optional but Recommended)
 
-Install git hooks to automatically check code quality:
+Pre-commit hooks run configured checks automatically before each commit,
+mirroring the CI gates so local commits fail for the same reasons PRs
+would. The config at `.pre-commit-config.yaml` wires up:
+
+| Tool | What it checks | CI equivalent |
+|------|----------------|---------------|
+| **ruff** (lint) | Python lint rules (`E`, `F`, `I`) | `ruff check .` |
+| **ruff** (format) | Python formatting (line-length 88) | Not yet gated |
+| **mypy** | Python type correctness | `python -m mypy .` |
+| **pre-commit-hooks** | Large files, merge conflicts, YAML/TOML syntax, trailing whitespace, EOF newlines | — |
+
+Pre-commit is already included in the project's dev dependencies. Install
+the hooks and they'll run on every `git commit`:
 
 ```bash
 uv run pre-commit install
 ```
 
-Now your commits will be checked before they're made.
+**Running manually:**
+
+```bash
+# Check all files (useful after changing hook config)
+uv run pre-commit run --all-files
+
+# Run a specific hook only
+uv run pre-commit run ruff --all-files
+```
+
+**Skipping hooks temporarily:**
+
+```bash
+# Skip all hooks for a single commit
+git commit --no-verify
+
+# Skip a specific hook (e.g. slow mypy run)
+SKIP=mypy git commit
+```
+
+**Updating hook versions:**
+
+```bash
+uv run pre-commit autoupdate
+```
+
+Keep the `rev:` pins in `.pre-commit-config.yaml` in sync with the
+versions listed in `pyproject.toml` under `[dependency-groups] dev`.
 
 ### Code Quality Commands