agents: clarify purpose and comment handling in AI disclosure rule (#4348) A bare human oversight label (such as `semi-autonomous` or `autonomous`) does not tell maintainers who or what they are interacting with on a pull request or how their review comments will be handled. Update `AGENTS.md`, `CONTRIBUTING.md`, `.github/PULL_REQUEST_TEMPLATE.md`, and `.agents/rules/pr.md` to state that the AI disclosure comment exists so maintainers understand who or what they are interacting with, and require it to explain how PR review comments will be handled (whether an agent automatically monitors and replies, whether a human reviews/approves agent responses before posting, or whether the human author responds directly).
diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index 3c51c8a..a1332ac 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md
@@ -41,10 +41,14 @@ 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. + as the merge commit message. After creating a PR, post a separate comment so + maintainers understand who/what they are interacting with: state the level of + human oversight and explain how comments on the PR will be handled (whether + an agent autonomously monitors and replies, whether a human reviews/approves + agent responses before posting, or whether the human responds directly). + 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,
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c478ff1..79fd794 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -16,8 +16,12 @@ * 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). + * After creating the PR, post a separate comment so maintainers understand + who/what they are interacting with: state the level of human oversight + (e.g., human-reviewed, semi-autonomous, or autonomous) and explain how + comments on the PR will be handled (e.g., whether an agent automatically + monitors and replies, whether a human reviews/approves agent replies before + posting, or whether the human responds directly). * 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.
diff --git a/AGENTS.md b/AGENTS.md index a3e4fd2..4851f2d 100644 --- a/AGENTS.md +++ b/AGENTS.md
@@ -57,8 +57,12 @@ 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`). + created so maintainers understand who/what they are interacting with. State + the level of human oversight (e.g., `human-reviewed`, `semi-autonomous`, or + `autonomous`) and explain how comments on the PR will be handled (e.g., + whether an agent automatically monitors and replies to review comments, + whether a human reviews and approves agent responses/changes before posting, + or whether the human author handles comments directly). * **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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index feee2ba..54190bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md
@@ -380,10 +380,15 @@ * **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. -* **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). +* **Disclosing AI usage and comment handling in a PR comment:** Keep the PR + description clean for use as the merge commit message. After creating the + PR, post a comment so maintainers understand who or what they are + interacting with: disclose the level of human oversight (e.g., closely + human-directed/reviewed, semi-autonomous, or fully autonomous) and explain + how comments on the PR will be handled (e.g., whether an agent + automatically monitors and replies to comments, whether a human reviews and + approves agent responses before posting, or whether the human author + responds directly). * **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