chore(dev): add pre-commit hooks mirroring the CI lint gate

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# Pre-commit hooks mirroring the CI lint job (.github/workflows/ci.yml).
+#
+# Local hooks call `uv run ruff` rather than pinning a separate ruff via
+# astral-sh/ruff-pre-commit, so the hook, CI, and the project's dev
+# dependency all resolve to the SAME ruff — no version drift, which is the
+# whole point of catching `ruff format` before it reaches CI.
+#
+# One-time setup (after `uv sync --extra dev`):
+#     uv run pre-commit install
+#
+# Run against everything on demand:
+#     uv run pre-commit run --all-files
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true

README.md

@@ -48,9 +48,15 @@ can't reach.
 ```bash
 git clone https://github.com/thomas-villani/docx-plus.git
 cd docx-plus
-uv sync --extra dev      # or: pip install -e ".[dev]"
+uv sync --extra dev          # or: pip install -e ".[dev]"
+uv run pre-commit install    # run ruff check + ruff format on every commit
 ```
 
+The pre-commit hooks mirror the CI lint gate (`ruff check` and
+`ruff format`), so formatting issues are caught locally instead of on CI.
+Run them against the whole tree any time with
+`uv run pre-commit run --all-files`.
+
 ## 60-second quickstart
 
 ### Inspect: why does this paragraph look the way it does?

SPEC.md

@@ -873,8 +873,11 @@ The library is "done" when all of these pass:
 
 - All tests pass (`pytest`)
 - `mypy --strict docx_plus/` passes
-- `ruff check docx_plus/` passes (config: default rules + `D` docstring rules
-  on public API, ignore on tests)
+- `ruff check docx_plus/ tests/` passes (config: default rules + `D` docstring
+  rules on public API, ignore on tests)
+- `ruff format --check docx_plus/ tests/` passes (formatting is a separate CI
+  gate from `ruff check`; the local pre-commit hook runs both — see below)
+- `mkdocs build --strict` passes (enforced by the docs workflow)
 - Coverage ≥ 90% on `core/`, `styles/`, `controls/`
 - All four `examples/` scripts run without error
 - Layer 3 smoke tests pass on a runner with LibreOffice installed
@@ -885,6 +888,12 @@ The library is "done" when all of these pass:
 A PR that lights up CI on all of these is mergeable. A PR that doesn't is
 not, regardless of how good the code looks.
 
+**Run the lint gate locally before pushing.** `.pre-commit-config.yaml`
+wires `ruff check` and `ruff format` as local hooks that shell out to
+`uv run ruff`, so they use the exact ruff CI resolves — no version drift.
+Install once with `uv run pre-commit install`; thereafter both run on every
+commit. To check everything on demand: `uv run pre-commit run --all-files`.
+
 ---
 
 ## 14. Build & Packaging
@@ -896,7 +905,7 @@ not, regardless of how good the code looks.
 - **Runtime deps**: `python-docx>=1.0.0`, `lxml>=4.9` (transitive via
   python-docx but pin explicitly).
 - **Dev deps**: `pytest`, `pytest-cov`, `mypy`, `ruff`,
-  `mkdocs-material`, `mkdocstrings`, `lxml-stubs`.
+  `mkdocs-material`, `mkdocstrings`, `lxml-stubs`, `pre-commit`.
 - **Build system**: `hatchling` via `pyproject.toml`. No `setup.py`.
 - **Typing marker**: `docx_plus/py.typed` is shipped (PEP 561) so
   downstream `mypy` users see the type hints.

pyproject.toml

@@ -46,6 +46,7 @@ dev = [
     "mkdocs-material>=9.5",
     "mkdocstrings[python]>=0.26",
     "lxml-stubs>=0.5",
+    "pre-commit>=3.5",
 ]
 
 [build-system]