agents: add PR comment etiquette and AI oversight disclosure rules

.agents/rules/agent-config.md

@@ -1,7 +1,7 @@
 ---
 trigger: glob
 description: Prose style rules for agent configs, rules, and skills
-globs: ".agents/**/*.md,AGENTS.md,GEMINI.md"
+globs: ".agents/**/*.md,AGENTS.md,CLAUDE.md,GEMINI.md"
 ---
 
 # Agent Configuration Style

.agents/rules/pr.md

@@ -37,8 +37,14 @@ Before drafting any pull request description, strictly adhere to the rules in
 * **PR Metadata Discrepancies**: If a PR title or description diverges from
   the branch's actual scope, notify the user of the discrepancy and ask for
   confirmation before updating GitHub.
-* **NEVER** include a list of per-file edits or changelog bullet points of
-  individual file modifications in PR descriptions or commit messages.
+* **NEVER** include a list of per-file edits, changelog bullet points of
+  individual file modifications, test execution logs/checklists, or AI
+  disclosure metadata in PR descriptions or commit messages.
+* **AI Disclosure & Comment Etiquette**: Keep the PR description clean for use
+  as the merge commit message. Disclose human oversight level in a separate PR
+  comment after creation. Never post comments for every CI run or narrate build
+  IDs, commit SHAs, line counts, or trivial diff details (e.g.,
+  "comment-only"); comment `PTAL` only when ready for re-review.
 * High-level overview only: state *why* the change is made and *how* at a
   conceptual level. Link related issues (e.g. `Work towards #<issue>`).
 * **Conciseness & Style (Strunk & White)**: Omit needless words. Use clear,

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,13 +1,24 @@
 PR Instructions/requirements
 * Title uses `type: description` format. See CONTRIBUTING.md for types.
   * Common types are: build, docs, feat, fix, refactor, revert, test
-  * Update `CHANGELOG.md` as applicable
-* Breaking changes include "!" after the type and a "BREAKING CHANGES:"
+  * Add a news entry file in `news/` as applicable (do not edit `CHANGELOG.md`
+    directly)
+* Breaking changes include "!" after the type and a "BREAKING CHANGE:"
   section at the bottom.
   See CONTRIBUTING.md for our breaking changes process.
-* Body text describes:
-  * Why this change is being made, briefly.
-  * Before and after behavior, as applicable
-  * References issue number, as applicable
-* Update docs and tests, as applicable
+* Body text becomes the commit message upon merge and should be clean and
+  concise:
+  * Briefly describe *why* this change is being made.
+  * Briefly give a high-level overview of *how* the code is changed.
+  * Reference issue number, as applicable.
+  * Do not include per-file changelogs, test run logs/checklists, or AI
+    disclosure metadata in the PR description.
+* Update docs and tests, and run `bazel test` and `buildifier` locally prior
+  to pushing.
+* AI-assisted PRs:
+  * After creating the PR, post a separate comment disclosing the level of
+    human oversight (e.g., human-reviewed, semi-autonomous, or autonomous).
+  * Do not post comments for every CI run or narrate build IDs, commit SHAs,
+    or trivial diff details. Reply `PTAL` once CI is passing and ready for
+    review.
 * Delete these instructions prior to sending the PR

AGENTS.md

@@ -47,7 +47,25 @@ because it interferes with code review comments.
 ### PR descriptions
 
 Follow the advice in `CONTRIBUTING.md` for PR descriptions. PR descriptions
-become the commit message upon merge.
+become the commit message upon merge. Keep the PR description clean and
+suitable for use as the commit message; do not put AI disclosures, test
+execution logs, or check checklists in the PR description.
+
+### GitHub PR interaction and AI disclosure
+
+* **Run local checks before pushing:** Run `bazel test --config=fast-tests`
+  and `buildifier` locally before opening or updating a PR.
+* **Post AI disclosure as a PR comment (not in the PR description):** When an
+  AI agent creates or interacts on a PR, post a single comment after the PR is
+  created disclosing the level of human oversight (e.g., `human-reviewed`,
+  `semi-autonomous`, or `autonomous`).
+* **No CI status spam or commit narration:** Do not post comments for every CI
+  run, and do not narrate build IDs, commit SHAs, patch line/file counts, or
+  trivial diff details (e.g., stating a push is "comment-only"). GitHub
+  already displays commits and check statuses.
+* **Comment only when actionable:** Only post a PR comment to answer a
+  reviewer's question, ask a clarifying question, or briefly indicate the PR
+  is ready for re-review (e.g., `PTAL`) once CI is passing.
 
 ### Python pytest conventions
 

CLAUDE.md

@@ -0,0 +1 @@
+@./AGENTS.md

CONTRIBUTING.md

@@ -375,16 +375,27 @@ had written it entirely themselves. This means:
 
 *   **Understanding the code:** You must be able to explain what the code does
     and why it's implemented that way. This includes discussing its
-    implications, and any trade-offs made during its development, just as if you
-    had written it entirely yourself.
+    implications, and any trade-offs made during its development, just as if
+    you had written it entirely yourself.
 *   **Vetting the correctness and functionality:** You are responsible for
     thoroughly testing and verifying that the code is correct, functional, and
     meets all project requirements and standards.
-
-If the human PR author cannot fulfill these responsibilities, the `rules_python`
-maintainers will not spend time reviewing or merging the PR. The goal is to
-ensure that all contributions, regardless of their origin, maintain the quality
-and integrity of the project and do not place an undue burden on maintainers.
+*   **Disclosing human oversight in a PR comment:** Keep the PR description
+    clean for use as the merge commit message. After creating the PR, post a
+    comment disclosing the level of human oversight (e.g., closely
+    human-directed/reviewed, semi-autonomous, or fully autonomous).
+*   **Avoiding bot comment spam:** Do not post comments for every CI run or
+    commit push, and do not narrate build IDs, commit SHAs, line counts, or
+    trivial diff details (such as noting a push is "comment-only"). Only post
+    a comment to ask or answer a substantive question, or reply `PTAL`
+    ("Please take another look") once CI is passing and the code is ready for
+    review again.
+
+If the human PR author cannot fulfill these responsibilities, the
+`rules_python` maintainers will not spend time reviewing or merging the PR. The
+goal is to ensure that all contributions, regardless of their origin, maintain
+the quality and integrity of the project and do not place an undue burden on
+maintainers.
 
 ## FAQ