test(docstrings): skip pydoclint gate when its env is broken

pydoclint depends on docstring-parser-fork while vgi-rpc depends on the
upstream docstring-parser; both own the `docstring_parser` import namespace,
so on some interpreter/OS combinations (seen on 3.14 + Windows) pydoclint
crashes on import. Distinguish that "tool failed to run" case (skip) from real
docstring violations (fail), so a broken tool env doesn't red CI while the
gate still runs on healthy matrix cells.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

tests/test_docstrings.py

@@ -10,6 +10,7 @@
 test invokes the same CLI, so there is no duplicated rule set.
 """
 
+import re
 import shutil
 import subprocess
 from pathlib import Path
@@ -18,6 +19,11 @@
 
 _REPO_ROOT = Path(__file__).resolve().parents[1]
 
+# A real violation line looks like ``    42: DOC101: ...``. If pydoclint exits
+# non-zero without emitting any such code, it failed to *run* (e.g. import
+# error) rather than finding violations — see the environment note below.
+_VIOLATION_RE = re.compile(r"\bDOC\d{3}\b")
+
 
 def test_pydoclint_clean() -> None:
     """``vgi/`` must pass the pydoclint docstring gate (config in pyproject.toml)."""
@@ -31,10 +37,23 @@ def test_pydoclint_clean() -> None:
         capture_output=True,
         text=True,
     )
+    output = result.stdout + result.stderr
+
+    if result.returncode == 0:
+        return
+
+    # pydoclint depends on ``docstring-parser-fork`` while ``vgi-rpc`` depends on
+    # the upstream ``docstring-parser``; both claim the ``docstring_parser``
+    # import namespace, so on some interpreter/OS combinations the wrong files
+    # win and pydoclint crashes on import. That's a broken tool environment, not
+    # a docstring problem — skip rather than fail (the gate still runs on every
+    # other matrix cell where the tool is healthy).
+    if not _VIOLATION_RE.search(output):  # pragma: no cover - env-dependent
+        pytest.skip(f"pydoclint could not run in this environment:\n{output}")
 
-    assert result.returncode == 0, (
+    pytest.fail(
         "pydoclint found docstring violations:\n\n"
-        f"{result.stdout}{result.stderr}\n"
+        f"{output}\n"
         "Fix the docstrings, or run "
         "`uv run pydoclint --generate-baseline=True --baseline=.pydoclint-baseline vgi/` "
         "to defer them (see [tool.pydoclint] in pyproject.toml)."