agents: document Bzlmod cycle, BUILD macro, lockfile, and PR rules (#4468) Loading `@rules_python_internal` from files transitively loaded by `config.bzl` triggers a Bzlmod Skyframe cycle, top-level ternary target instantiations in `BUILD` files break `buildifier` and `buildozer` processing, and unpinned or conflicted `MODULE.bazel.lock` updates fail Bazel 9 lockfile checks. In addition, `gh pr merge --auto` exits `0` on conflicting PRs without entering the merge queue, and single-choice PR review prompts prevented combining comments, approvals, and fixes. Document `@rules_python_internal` cycle avoidance, canonical toolchain type paths, `.bzl` helper macros for conditional targets, and `USE_BAZEL_VERSION`-pinned lockfile regeneration and conflict recovery in the agent rules and Starlark review prompt. Update the merge and review skills to check PR mergeability before enabling auto-merge and offer multi-select review actions with review thread resolution.
diff --git a/.agents/rules/rules_python.md b/.agents/rules/rules_python.md index eb58f70..5b12fad 100644 --- a/.agents/rules/rules_python.md +++ b/.agents/rules/rules_python.md
@@ -24,8 +24,14 @@ ## Internal Labels & Helpers * **Toolchain Type Labels**: Define toolchain type constants in - `//python/private/toolchain_types:toolchain_types.bzl` and targets in + `//python/private:toolchain_types.bzl` and internal toolchain type targets in `//python/private/toolchain_types:BUILD.bazel`. +* **`@rules_python_internal` Cycle Avoidance**: Never load + `@rules_python_internal//...` in `.bzl` files transitively loaded by + `//python/extensions:config.bzl` (such as + `//python/private:toolchain_types.bzl` or + `//python/private/toolchains:repo.bzl`), because `config.bzl` generates + `@rules_python_internal` and will trigger a Bzlmod Skyframe cycle. * **`render` Helpers (`//python/private:text_util.bzl`)**: Use `render.*` (`render.string`, `render.toolchain`, `render.call`, `render.list`) instead of `repr()` for Starlark calls; use `json.encode_indent()` for data constants.
diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md index 4b2239e..e9bbfe0 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md
@@ -100,7 +100,12 @@ `$(execpaths ...)`. * Do not define overlapping `filegroup` targets or `exports_files` globs in the same `BUILD` package; reconcile or compose them. -* Move complex loops and branching out of `BUILD` files into `.bzl` macros. +* Move loops and conditional target definitions out of `BUILD` files into `.bzl` + helper macros using `if`/`else` statements. Never instantiate targets via + top-level `rule_a(...) if cond else rule_b(...)` ternaries (or suppress + `no-effect` / `duplicated-name` buildifier warnings in `BUILD` files). + * **Why**: Keeping `BUILD` files declarative ensures they remain processable + by tools like `buildifier` and `buildozer`. * When exposing data files across packages, define a named `filegroup` in the owning package rather than referencing raw source files in caller `data`.
diff --git a/.agents/rules/testing.md b/.agents/rules/testing.md index c141507..df023fc 100644 --- a/.agents/rules/testing.md +++ b/.agents/rules/testing.md
@@ -22,14 +22,18 @@ targets built! ## Lockfile Testing (`MODULE.bazel.lock`) -* Changes to transitive module extension dependencies or `.bzl` files loaded by - extensions update Bazel 9 lockfile hashes, requiring `bazel mod deps - --lockfile_mode=update` in integration test workspaces. -* When requirements files (e.g., in `//tools/publish` or root pip parses) are - modified or bumped by Dependabot, update the integration lockfile by running - `bazel mod deps --lockfile_mode=update` in `tests/integration/bzlmod_lockfile` - and verify with - `bazel test //tests/integration:bzlmod_lockfile_test_bazel_9.3.1`. +* When changing transitive module extension dependencies, `.bzl` files loaded + by extensions, or requirements files (in `//tools/publish` or root pip + parses), update the Bazel 9 integration lockfile by running + `USE_BAZEL_VERSION=<ver> bazel mod deps --lockfile_mode=update` in + `tests/integration/bzlmod_lockfile` (matching `bazel_versions` on + `bzlmod_lockfile_test` in `tests/integration/BUILD.bazel`) and verify with + `bazel test //tests/integration:bzlmod_lockfile_test_bazel_<ver>`. +* When `MODULE.bazel.lock` has Git merge conflicts (`<<<<<<<`), Bazel fails to + parse it (`MalformedJsonException`); run + `git checkout --theirs tests/integration/bzlmod_lockfile/MODULE.bazel.lock` + first, then regenerate in `tests/integration/bzlmod_lockfile` with + `USE_BAZEL_VERSION=<ver> bazel mod deps --lockfile_mode=update`. ## Documentation Flake Handling * When building `//docs:docs` fails with exit code 2, treat it as a known
diff --git a/.agents/skills/merge-pr/SKILL.md b/.agents/skills/merge-pr/SKILL.md index 231d790..b7dd3a9 100644 --- a/.agents/skills/merge-pr/SKILL.md +++ b/.agents/skills/merge-pr/SKILL.md
@@ -7,8 +7,15 @@ When the user asks to merge a pull request (e.g., "merge PR <number>", "merge this PR", or monitor its merge): -1. **Enqueue for Merge**: Run - `gh pr merge <pr_number> --repo bazel-contrib/rules_python --auto --squash`. +1. **Check Mergeability & Enqueue for Merge**: + - First check `gh pr view <pr_number> --repo bazel-contrib/rules_python + --json isDraft,mergeable,mergeStateStatus`. `gh pr merge --auto` exits `0` + even when `mergeable` is `"CONFLICTING"` (`mergeStateStatus: "DIRTY"`), + which prevents the PR from ever entering the merge queue. If conflicting, + either merge `upstream/main` and push (if authorized) or report the + conflict immediately. + - Run `gh pr merge <pr_number> --repo bazel-contrib/rules_python --auto + --squash`. - **Draft PRs**: If the PR is a draft (`isDraft: true`), mark it ready for review first via `gh pr ready <pr_number> --repo bazel-contrib/rules_python` (otherwise `gh pr merge` fails with
diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 06b89f0..a5682bb 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md
@@ -211,14 +211,19 @@ concise summary with the overall verdict and a clickable markdown link to `code-review-results.md` in the response. - If reviewing a PR belonging to another user and at least one net-new candidate - comment remains after the Anti-Noise Gate, prompt the user via `ask_question` - (including a clickable `[code-review-results.md](file:///...)` link in the - `question` prompt text) to choose whether to: - 1. Post the feedback as non-draft comments - 2. Approve PR and post non-draft comments - 3. Post the feedback as draft comments - 4. Review the feedback - 5. Do not post comments + comment remains after the Anti-Noise Gate, prompt the user via a single + multi-select (`is_multi_select: true`) `ask_question` question (including a + clickable `[code-review-results.md](file:///...)` link in the `question` + prompt text) with the following options: + 1. Post non-draft comments + 2. Post draft comments + 3. Review feedback further + 4. Also approve PR + 5. Also fix issues + 6. Also push fixes to PR +- When fixing and pushing open issues that also had non-draft review comments + posted, reply to each fixed review thread with the commit SHA (and disclosure + line) and resolve the thread. - If reviewing or re-reviewing a PR belonging to another user and the verdict is `PASS` (0 open issues and 0 net-new candidate comments) while the PR is not yet approved by the user, prompt the user via `ask_question` (including a @@ -226,6 +231,7 @@ prompt text) to choose whether to: 1. Approve PR 2. Do nothing + 3. Re-review - Immediately before posting comments (after `ask_question` returns), re-fetch the latest PR description, commits, and review comments (`gh pr view`), move any issues addressed in the interim to `## Resolved Issues` in
diff --git a/.agents/skills/review-code/review-starlark-prompt.md b/.agents/skills/review-code/review-starlark-prompt.md index d5688d5..c728e55 100644 --- a/.agents/skills/review-code/review-starlark-prompt.md +++ b/.agents/skills/review-code/review-starlark-prompt.md
@@ -27,7 +27,10 @@ 11. Verify no compatibility logic or feature guards target Bazel versions older than `MINIMUM_BAZEL_VERSION` in `//:version.bzl`. 12. Inspect the full `BUILD` file (not just the diff hunk) to flag overlapping - or redundant `filegroup`, `exports_files`, or `glob(...)` definitions. + or redundant `filegroup`, `exports_files`, or `glob(...)` definitions, and + flag top-level target-instantiation ternaries (`rule_a(...) if cond else + rule_b(...)`) that belong in a `.bzl` helper macro so `BUILD` files remain + processable by `buildifier` and `buildozer`. 13. Check macro and rule hygiene: forward unused wrapper arguments via `**kwargs`, silence unused variables with `_ = a, b # @unused`, require comments above each field when returning a `struct(...)` of fields, prefer