From ad7b6e4a4855279cf82f91057ea5e41a39dd0058 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Sun, 25 Oct 2026 19:06:02 -0700 Subject: [PATCH] agents: clarify purpose and comment handling in AI disclosure rule 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). --- .agents/rules/pr.md | 12 ++++++++---- .github/PULL_REQUEST_TEMPLATE.md | 8 ++++++-- AGENTS.md | 8 ++++++-- CONTRIBUTING.md | 13 +++++++++---- 4 files changed, 29 insertions(+), 12 deletions(-) diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index 3c51c8ad4c..a1332ac6b7 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md @@ -41,10 +41,14 @@ Before drafting any pull request description, strictly adhere to the rules in 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 #`). * **Conciseness & Style (Strunk & White)**: Omit needless words. Use clear, diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c478ff1e8b..79fd794ed6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -16,8 +16,12 @@ PR Instructions/requirements * 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 a3e4fd2619..4851f2db49 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,8 +57,12 @@ execution logs, or check checklists in the PR description. 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 feee2bad5f..54190bf814 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -380,10 +380,15 @@ had written it entirely themselves. This means: * **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