fix(lint): isolate pydoclint to end docstring-parser-fork collision

.github/workflows/ci.yml

@@ -76,8 +76,12 @@ jobs:
       # Docstring consistency: documented args/attributes must match the code.
       # Config lives in pyproject.toml ([tool.pydoclint]); vgi_rpc/ is fully
       # clean with no baseline, so any new violation fails immediately.
+      # Run isolated via uvx: pydoclint pulls docstring-parser-fork, which
+      # collides with the canonical docstring-parser in the project venv, so it
+      # is deliberately not a project dependency (see pyproject.toml). --python
+      # 3.13 is required so the parser understands the package's 3.13 syntax.
       - name: Docstring lint (pydoclint)
-        run: uv run pydoclint vgi_rpc/
+        run: uvx --python 3.13 --from pydoclint==0.8.7 pydoclint vgi_rpc/
 
       - name: Type check (mypy)
         run: uv run mypy vgi_rpc/ --any-exprs-report mypy-type-report

CLAUDE.md

@@ -42,7 +42,7 @@ The full process before committing code is
 
 1. Run `uv run ruff format .` on all files
 2. Run `uv run ruff check .` and resolve all errors
-3. Run `uv run pydoclint vgi_rpc/` and resolve all errors (docstring args/attributes must match the code; config in `[tool.pydoclint]`, no baseline — the tree is fully clean)
+3. Run `uvx --python 3.13 --from pydoclint==0.8.7 pydoclint vgi_rpc/` and resolve all errors (docstring args/attributes must match the code; config in `[tool.pydoclint]`, no baseline — the tree is fully clean). pydoclint runs isolated via `uvx` because its `docstring-parser-fork` dep collides with the canonical `docstring-parser` in the project venv — so it is intentionally not a project dependency.
 4. Run `uv run mypy vgi_rpc/` and resolve all errors
 5. Run `uv run ty check vgi_rpc/` and resolve all errors
 6. Run `uv run pytest` for all tests

pyproject.toml

@@ -237,15 +237,25 @@ dev = [
     "sentry-sdk>=2.0",
     "cryptography>=41.0",
     "pynacl>=1.5",
-    "pydoclint>=0.8",
     "hypothesis>=6.155.3",
 ]
+# pydoclint is intentionally NOT a project dependency. It depends on
+# `docstring-parser-fork`, which installs into the same `docstring_parser/`
+# import namespace as the canonical `docstring-parser` this package needs at
+# runtime (vgi_rpc/rpc/_types.py). When both land in one venv, whichever uv
+# installs last wins non-deterministically — and the fork-vs-canonical race
+# made docstring symbols (e.g. DocstringYields) appear/disappear across
+# unrelated dependency bumps, flaking the lint gate. Run pydoclint isolated:
+#   uvx --python 3.13 --from pydoclint==0.8.7 pydoclint vgi_rpc/
+# (CI uses the same invocation; --python 3.13 is required so the parser
+# understands this package's 3.13 syntax.)
 
 [tool.pydoclint]
 # Docstring consistency gate (complements ruff's `D` rules, which only check
 # docstring *shape*, not whether documented args/attributes match the code).
 # Enforced families: DOC001 (parse), DOC101/102/103 (arg<->signature), DOC4xx
-# (yields), DOC60x (dataclass attributes). Run via `uv run pydoclint vgi_rpc/`.
+# (yields), DOC60x (dataclass attributes). Run isolated (see note by the dev
+# group above): `uvx --python 3.13 --from pydoclint==0.8.7 pydoclint vgi_rpc/`.
 style = "google"
 # We keep types in signatures, not docstrings (Google style) — so don't ask for
 # them in docstrings, and don't try to match return/yield *types* against prose.