From 480b0757ce67ee037912606a516ede847069f285 Mon Sep 17 00:00:00 2001
From: Richard Levasseur <richardlev@gmail.com>
Date: Sun, 23 Aug 2026 15:47:35 -0700
Subject: [PATCH] agents: document runtime version checks and multi-version
 pytest_test bzlmod rules

WORKSPACE mode resolves pip dependencies for only the host Python version, causing multi-version pytest targets to fail when executed against non-host interpreters. Additionally, relying on static type ignore comments in version-dependent code obscures actual runtime compatibility requirements across supported Python releases.

To address this, agent guidelines are updated to require explicit runtime Python version checks instead of static type ignores, and to restrict multi-version pytest_test targets to Bzlmod mode using SUPPORTS_BZLMOD. The allowed PR commit prefixes are also updated to include agents: for changes to agent rules and prompts.
---
 .agents/rules/pr.md         | 2 ++
 .agents/rules/python.md     | 3 +++
 .agents/rules/testing.md    | 4 ++++
 python/runfiles/runfiles.py | 2 ++
 4 files changed, 11 insertions(+)

diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md
index ae75aa34fe..bc6f87f44b 100644
--- a/.agents/rules/pr.md
+++ b/.agents/rules/pr.md
@@ -25,6 +25,8 @@ Before drafting any pull request description, strictly adhere to the rules in
   (`.github/workflows/`).
 * `tests:`: Test-only changes and test-helper fixes (never `fix:` or
   `fix(tests):`).
+* `agents:` / `agents(<scope>):`: Agent rules, skills, and prompts
+  (`.agents/`).
 
 ## PR Commit Workflow Invariant
 * Once a Pull Request is created, always make new commits or merge commits.
diff --git a/.agents/rules/python.md b/.agents/rules/python.md
index 0c4fd69da8..fd7aef7cb7 100644
--- a/.agents/rules/python.md
+++ b/.agents/rules/python.md
@@ -26,6 +26,9 @@
   link to its definition in the docstring.
 
 ## Type Checking & Annotations
+* **Version differences**: Guard version-specific arguments or APIs with runtime
+  checks (e.g. `if sys.version_info >= (3, 13):`) instead of
+  `# pyrefly: ignore[...]` comments.
 * **`importlib.metadata` `PackagePath`**: `f.locate()` is typed as `PathLike`.
   Wrap with `pathlib.Path(f.locate())` to call `.exists()`, `.is_file()`, etc.
 * **In-file disables vs target skipping**: Prefer
diff --git a/.agents/rules/testing.md b/.agents/rules/testing.md
index dceb91d24e..cd56f69105 100644
--- a/.agents/rules/testing.md
+++ b/.agents/rules/testing.md
@@ -37,3 +37,7 @@
 * **Platform Constraints**: Restrict OS-specific targets with
   `target_compatible_with` (e.g., `["@platforms//os:windows"]`) to skip on
   incompatible platforms.
+* **Multi-version `pytest_test`**: Restrict targets using `python_versions` to
+  Bzlmod with `target_compatible_with = SUPPORTS_BZLMOD`
+  (`//tests/support:support.bzl`). WORKSPACE mode resolves pip dependencies for
+  only the host Python version.
diff --git a/python/runfiles/runfiles.py b/python/runfiles/runfiles.py
index 0c56702216..9650563830 100644
--- a/python/runfiles/runfiles.py
+++ b/python/runfiles/runfiles.py
@@ -385,6 +385,7 @@ def iterdir(self) -> Generator[Self, None, None]:
         for p in resolved.iterdir():
             yield self / p.name
 
+    # Return types and keyword arguments vary across Python versions in typeshed.
     @override
     def glob(  # pyrefly: ignore[bad-override]
         self,
@@ -407,6 +408,7 @@ def glob(  # pyrefly: ignore[bad-override]
         for p in it:
             yield self / p.relative_to(resolved)
 
+    # Return types and keyword arguments vary across Python versions in typeshed.
     @override
     def rglob(  # pyrefly: ignore[bad-override]
         self,