Code review agent: clarify deprecation policy (#18117)

Author: trask

.github/agents/code-review-and-fix.agent.md

@@ -305,6 +305,12 @@ Auto-fix boundaries:
     add the correctly named/shaped method with the implementation, deprecate the old method
     to delegate to the new one, and add a `@deprecated` Javadoc tag naming the replacement.
     For stable modules, annotate instead: the fix requires a broader compatibility decision.
+    **Exception — javaagent modules**: javaagent modules (Gradle path ends with `:javaagent`,
+    including shared `-common` javaagent modules) are bundled into the agent jar and are not
+    a public API. Do **not** apply a deprecation cycle; rename or change the API directly
+    and update all in-repo callers in the same commit. A deprecation cycle is only required
+    for non-stable modules whose artifacts are published for external consumption (e.g.,
+    `:library`, `:testing`, `instrumentation-api*`).
 - Do not auto-fix (report in the final output instead):
   - missing `testExperimental` task — when experimental flags are set unconditionally
     on all test tasks instead of being isolated in a dedicated task

.github/agents/knowledge/api-deprecation-policy.md

@@ -18,6 +18,15 @@ The CHANGELOG uses distinct headings to distinguish:
 - `⚠️ Breaking changes to non-stable APIs` — alpha/non-stable modules (routine)
 - `⚠️ Breaking Changes` — stable module changes (rare, requires strong justification)
 
+### Javaagent modules are not a public API
+
+Javaagent modules (Gradle path ends with `:javaagent`, including shared `-common` javaagent
+modules) are bundled into the agent jar and are **not** published for external consumption.
+Do **not** apply a deprecation cycle to symbols in javaagent modules — rename or change the
+API directly and update all in-repo callers in the same commit. The deprecate-then-remove
+cycle described below applies only to non-stable modules whose artifacts are published
+(e.g., `:library`, `:testing`, `instrumentation-api*`).
+
 ## The Deprecate-Then-Remove Cycle
 
 ### Alpha (non-stable) modules