agents: clarify PR disclosure trigger and field/path documentation rules (#4400) The phrase "creates or interacts on a PR" caused agents to post standalone AI disclosure comments when pushing commits to existing PRs (such as Dependabot PRs), and code style rules lacked explicit guidance for documenting dataclass fields, Starlark `struct()` fields, and relative path bases. Update `AGENTS.md`, `CONTRIBUTING.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `.agents/rules/pr.md`, and `.agents/skills/create-pr/SKILL.md` to require a standalone AI disclosure comment (explaining how PR comments will be handled) only when initially creating a PR, while using the per-comment italicized footer when posting comments or replies. Add rules and `review-code` checks in `.agents/rules/` (`python.md`, `code-style.md`, and `starlark.md`) requiring field comments above dataclass and returned `struct()` fields and documenting what relative paths are relative to.
diff --git a/.agents/rules/code-style.md b/.agents/rules/code-style.md index 52be2ac..494ef36 100644 --- a/.agents/rules/code-style.md +++ b/.agents/rules/code-style.md
@@ -34,6 +34,8 @@ * Avoid long or complex inline expressions (e.g. multi-condition ternaries, compound boolean chains, or dense one-liners). Break them into named intermediate variables, prior preparation steps, or explicit statements. +* When an object, field, or return value contains relative paths, document what + each path is relative to. ## CLI & Flags * Comment non-obvious flags (`--force`), non-default schemes, subtle arguments
diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index 49495e7..eab1577 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md
@@ -41,14 +41,16 @@ 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. 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. + as the merge commit message. Only when initially creating a new PR, post a + separate comment so maintainers understand who/what they are interacting + with: 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). Do not + post a standalone AI disclosure comment when merely pushing commits to an + existing PR (such as a Dependabot PR); instead, disclose AI authorship only + on comments you actually post (see below). 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/.agents/rules/python.md b/.agents/rules/python.md index 312fb42..789d3c8 100644 --- a/.agents/rules/python.md +++ b/.agents/rules/python.md
@@ -72,7 +72,9 @@ `==================== STDOUT BEGIN ====================` / `==================== STDOUT END ====================` (same for STDERR). -## TypedDict +## Data Classes & TypedDict +* In dataclasses (`@dataclasses.dataclass`), add a comment above each field + describing its value. * **External Objects**: When defining a `TypedDict` for an external object, link to its definition in the docstring.
diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md index 167a908..f9bdcda 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md
@@ -141,6 +141,8 @@ * **Concise API Docstrings**: Keep docstrings brief: state purpose and arguments, link to shared symbols (`{obj}`) or guides (`{ref}`) instead of repeating rules, and put extended examples in `docs/`. +* When returning a `struct(...)` of fields, add a comment above each field + describing its value. * **Workaround Comments**: Comment non-obvious workarounds with the intent, why the direct approach fails, and why the workaround works. * **No Bazel Copyright Headers**: Do not add Bazel copyright headers to new or
diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index 25c15ae..af25932 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md
@@ -21,9 +21,9 @@ - **PR Body**: Explain *why* and conceptual *how*. Wrap strictly at 72 columns max. Use concise, active phrasing (Strunk & White). - **AI Disclosure Comment**: Draft (and post via `gh pr comment` if creating - the PR) the AI disclosure comment stating the level of human oversight and - how PR comments will be handled. When posted automatically during `create - pr` without prior user review of the comment text, end it with: + the PR) the AI disclosure comment explaining how PR comments will be + handled. When posted automatically during `create pr` without prior user + review of the comment text, end it with: `*This is an automatically generated agent comment.*` Only use `*This is an agent-generated comment reviewed and approved by the user.*` if the user previously reviewed `pr_info.md` and approved the
diff --git a/.agents/skills/review-code/review-code-style-prompt.md b/.agents/skills/review-code/review-code-style-prompt.md index 6ec8c2f..656a87b 100644 --- a/.agents/skills/review-code/review-code-style-prompt.md +++ b/.agents/skills/review-code/review-code-style-prompt.md
@@ -17,5 +17,7 @@ 5. Rule-Exception Justifications: If the author provides a justification for an environment fallback, suppression, or style exception, ensure the `Justification & Exception Auditor` evaluates it for human sign-off. +6. Relative Paths: When an object, field, or return value holds relative paths, + verify comments or docstrings document what those paths are relative to. @.agents/skills/review-code/review-report-format.md
diff --git a/.agents/skills/review-code/review-python-prompt.md b/.agents/skills/review-code/review-python-prompt.md index 672aeed..1484697 100644 --- a/.agents/skills/review-code/review-python-prompt.md +++ b/.agents/skills/review-code/review-python-prompt.md
@@ -40,5 +40,7 @@ names (`mock_token`) and explicit CodeQL annotations (`# codeql[py/clear-text-logging-sensitive-data]`) for intentional mock outputs. +11. Data Classes: Verify `@dataclasses.dataclass` definitions include comments + above each field describing its value. @.agents/skills/review-code/review-report-format.md
diff --git a/.agents/skills/review-code/review-starlark-prompt.md b/.agents/skills/review-code/review-starlark-prompt.md index 5dfc5dd..d5688d5 100644 --- a/.agents/skills/review-code/review-starlark-prompt.md +++ b/.agents/skills/review-code/review-starlark-prompt.md
@@ -29,7 +29,8 @@ 12. Inspect the full `BUILD` file (not just the diff hunk) to flag overlapping or redundant `filegroup`, `exports_files`, or `glob(...)` definitions. 13. Check macro and rule hygiene: forward unused wrapper arguments via - `**kwargs`, silence unused variables with `_ = a, b # @unused`, prefer + `**kwargs`, silence unused variables with `_ = a, b # @unused`, require + comments above each field when returning a `struct(...)` of fields, prefer analysis-time validation over loading-time checks, prefer `ctx.actions.write` over subprocesses for small static strings, use `$(execpath ...)` / `$(execpaths ...)` instead of `$(location)` /
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 79fd794..292e656 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -16,12 +16,11 @@ * 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 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). + * When initially creating the PR, post a separate comment so maintainers + understand who/what they are interacting with: 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 4851f2d..91e1a2d 100644 --- a/AGENTS.md +++ b/AGENTS.md
@@ -55,14 +55,18 @@ * **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 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). +* **Post AI disclosure when creating a PR or posting comments:** + * When initially creating a new PR, post a single comment right after + creation so maintainers understand who/what they are interacting with: + 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). Do not post a standalone AI + disclosure comment merely for pushing commits to an existing PR (such as + updating a Dependabot PR). + * When posting a PR comment or review reply, end the comment with an + italicized line identifying it as an agent-generated comment and stating + whether it was automatically generated or reviewed/approved by the user. * **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 54190bf..e035967 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md
@@ -381,14 +381,12 @@ thoroughly testing and verifying that the code is correct, functional, and meets all project requirements and standards. * **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). + description clean for use as the merge commit message. When initially + creating the PR, post a comment so maintainers understand who or what they + are interacting with: 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