chore: add uv-lock --check pre-commit hook and dependency-update guidance

.pre-commit-config.yaml

@@ -14,3 +14,9 @@ repos:
     hooks:
       - id: mypy
         additional_dependencies: [types-requests]
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.11.6
+    hooks:
+      - id: uv-lock
+        args: [--check]

AGENTS.md

@@ -362,6 +362,20 @@ Models can be configured with Databricks-specific options:
 3. Add validation logic if needed
 4. Write tests for both valid and invalid configurations
 
+### Updating Dependencies (`pyproject.toml` / `uv.lock`)
+
+`uv.lock` pins the exact version CI tests against. Version bounds in `pyproject.toml` are independent of the pinned version — a loosened upper bound does NOT auto-bump the pinned version.
+
+**When changing a version bound in `pyproject.toml`:**
+
+1. Run `uv lock --upgrade-package <name>` to pick up the newest allowed version of that package (targeted, not a full resolve).
+2. Inspect the `uv.lock` diff — confirm the pinned version now matches the version you actually want to test against.
+3. Commit both `pyproject.toml` and `uv.lock` in the same commit.
+
+**Why this matters:** a pre-commit hook runs `uv lock --check` and catches pyproject↔lock *inconsistency*, but it does NOT force pinned versions forward. If the previously pinned version still satisfies the new bound (e.g. raised `<4.1.4` to `<4.1.6` while `4.1.3` is already pinned), the lock stays consistent and CI keeps testing the old version — the whole point of the bound change is lost. Always run the targeted upgrade explicitly.
+
+**Adding a new dependency:** `uv add <name>` updates both files; no separate lock step needed.
+
 ## 🐛 Debugging Guide
 
 ### Common Issues