agents: add rules_python usage auditor and open-question label rule (#4249) Ensure Bzlmod `pip.dep()` invariants and open questions in pull requests are systematically checked during agent workflows. Add a `.agents/rules/rules_python.md` rule and a corresponding `rules_python` Usage Auditor subagent to `review-code` to verify that `@pypi` targets referenced under `python/**` have `pip.dep()` declarations in `MODULE.bazel`. Update `pr.md`, `create-pr`, and `review-code` to require the `do-not-merge` label when PR descriptions contain open questions and to audit open questions or follow-up items during code review.
diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index 5770597..cc85c66 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md
@@ -45,3 +45,12 @@ active, and direct phrasing for *why* and *how*. * **Preserve Existing Descriptions**: Preserve the author's wording unless instructed to change it. Wrap bodies at 72 columns. +* **Open Questions & Follow-Up Items**: + * Add the `"do not merge"` label to the PR when the PR description contains + open questions (e.g., `gh pr edit <pr> --repo bazel-contrib/rules_python + --add-label "do not merge"`). + * During code review, inspect the PR description and comments for open + questions, `TODO` items, or "Things we could do / follow-up" notes. + Evaluate each item against the diff and project rules, flag unresolved + items with `ACTION_REQUIRED` or `USER_DECISION_REQUIRED`, and verify the + `"do not merge"` label is applied if open questions remain.
diff --git a/.agents/rules/rules_python.md b/.agents/rules/rules_python.md new file mode 100644 index 0000000..2bf4c2b --- /dev/null +++ b/.agents/rules/rules_python.md
@@ -0,0 +1,17 @@ +--- +trigger: model_decision +description: rules_python-specific Bzlmod, PyPI, and rule usage invariants +--- + +# `rules_python` Bzlmod & Rule Invariants + +## Unified `@pypi` Hub & `pip.dep()` Declarations (`MODULE.bazel`) +* Declare `pip.dep(name = "<pkg>")` on the non-dev `pip` extension in + `MODULE.bazel` (with `"pypi"` in `use_repo(pip, "pypi", ...)`) for every + `@pypi//<pkg>` target referenced by non-test rules, macros, or `BUILD` files + under `python/**` (directly or via `alias`). +* **Why**: `pip.dep()` registers abstract PyPI package targets in the unified + `@pypi` hub so downstream Bzlmod consumers do not fail during loading or + analysis when `<pkg>` is absent from their `pip.parse()` lockfiles. Package + names in `pip.dep(name = "...")` are normalized (hyphens and underscores map + to the same name).
diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index b4bcec7..273ace1 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md
@@ -34,6 +34,8 @@ `gh pr create` when explicitly requested to create the PR. - **Targeting Upstream Repo**: When creating, target upstream using `--repo bazel-contrib/rules_python` and `--head <fork_owner>:<branch>`. + - **Open Questions Label**: If the PR description contains open questions, + apply the `"do not merge"` label (`--label "do not merge"`). 4. **Return Status**: Direct subagent to report the PR number/draft status and the absolute file path to its `pr_info.md` artifact back to the caller. 5. **Publish and Link Artifact in Main Agent**: Upon subagent completion, read
diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 7589752..c995eaa 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md
@@ -50,7 +50,9 @@ - Prompt file: `.agents/skills/review-code/review-pr-standards-prompt.md` - Focus: Audits PR titles and descriptions against Conventional Commits - formatting and PR update rules in `CONTRIBUTING.md`. + formatting, PR update rules in `CONTRIBUTING.md`, and open questions or + "TODO / Things we could do" items in the PR description (ensuring the + `"do not merge"` label is applied when open questions exist). 7. **GitHub Workflows Sub-Agent** (`Role: "GitHub Workflows Auditor"`): - Prompt file: @@ -59,6 +61,14 @@ `.agents/rules/github_actions_workflows.md` (e.g. `chmod +x` executable permissions, shebangs, action versions, fallback jobs). +8. **`rules_python` Usage Sub-Agent** (`Role: "rules_python Usage Auditor"`): + - Prompt file: + `.agents/skills/review-code/review-rules-python-prompt.md` + - Focus: Audits changes against `.agents/rules/rules_python.md` and + `rules_python`-specific Bzlmod and rule usage invariants (e.g., `pip.dep()` + declarations in `MODULE.bazel` for `@pypi//<pkg>` references under + `python/**`). + ### Action Instructions - Immediately create a user-facing review artifact named `code-review-results.md` in the conversation artifact directory so progress
diff --git a/.agents/skills/review-code/review-pr-standards-prompt.md b/.agents/skills/review-code/review-pr-standards-prompt.md index d415f0e..c389e30 100644 --- a/.agents/skills/review-code/review-pr-standards-prompt.md +++ b/.agents/skills/review-code/review-pr-standards-prompt.md
@@ -12,5 +12,11 @@ 4. If a PR has already been created, enforce PR update rules: do NOT amend or rebase existing commits (create new commits and merges instead, to preserve code review comment threads). +5. Inspect the PR description and comments for open questions, `TODO` items, + or "Things we could do / follow-ups" sections. Evaluate each item against + the diff and project rules, flag items requiring resolution or user input + with `ACTION_REQUIRED` or `USER_DECISION_REQUIRED`, and verify the PR has + the `"do not merge"` label when open questions are present (add it or flag + as `ACTION_REQUIRED` if missing). @.agents/skills/review-code/review-report-format.md
diff --git a/.agents/skills/review-code/review-rules-python-prompt.md b/.agents/skills/review-code/review-rules-python-prompt.md new file mode 100644 index 0000000..60c7f2c --- /dev/null +++ b/.agents/skills/review-code/review-rules-python-prompt.md
@@ -0,0 +1,12 @@ +You are a specialized `rules_python` Usage Auditor sub-agent. +Your sole task is to audit all changes in `git diff` against `rules_python` +Bzlmod and rule usage invariants: + +1. Read and strictly enforce `.agents/rules/rules_python.md` and `AGENTS.md`. +2. Verify that every `@pypi//<pkg>` target referenced by non-test rules, + macros, or `BUILD` files under `python/**` (including default attribute + values and `alias` targets) has a corresponding `pip.dep(name = "<pkg>")` + declaration on the non-dev `pip` extension in `MODULE.bazel` (with `"pypi"` + in `use_repo(pip, ...)`). + +@.agents/skills/review-code/review-report-format.md