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