Clarify singleton static import guidance

Author: trask

.github/agents/knowledge/README.md

@@ -14,7 +14,7 @@ Load only files relevant to the current scope to reduce noise and avoid over-con
 | `gradle-conventions.md` | `build.gradle.kts` or `settings.gradle.kts` changes, custom test task registration or wiring |
 | `javaagent-advice-patterns.md` | ByteBuddy `@Advice` class or advice-method changes |
 | `javaagent-module-patterns.md` | `InstrumentationModule`, `TypeInstrumentation`, `VirtualField`, `CallDepth` |
-| `javaagent-singletons-patterns.md` | `*Singletons` holder classes, singleton accessors, static-imported singleton callers |
+| `javaagent-singletons-patterns.md` | `*Singletons` holder classes, singleton accessors, callers of singleton accessors/fields |
 | `library-patterns.md` | Library instrumentation telemetry, builder, getter, or setter pattern changes |
 | `module-naming.md` | New or renamed modules or packages; settings includes |
 | `testing-general-patterns.md` | Test files in scope — assertion style, resource cleanup patterns, attribute assertion patterns, `satisfies()` lambda usage |

.github/agents/knowledge/general-rules.md

@@ -21,7 +21,7 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
 | Naming | Module/package naming | New or renamed modules/packages | `module-naming.md` |
 | Javaagent | Advice patterns | `@Advice` classes | `javaagent-advice-patterns.md` |
 | Javaagent | Module structure patterns | `InstrumentationModule`, `TypeInstrumentation` | `javaagent-module-patterns.md` |
-| Javaagent | Singletons patterns | `*Singletons` holder classes, singleton accessors, static-imported singleton callers | `javaagent-singletons-patterns.md` |
+| Javaagent | Singletons patterns | `*Singletons` holder classes, singleton accessors, callers of singleton accessors/fields | `javaagent-singletons-patterns.md` |
 | Javaagent | Incorrect `classLoaderMatcher()` | `classLoaderMatcher()` override that is redundant (muzzle already handles it) or missing when needed (muzzle cannot distinguish version range) | `javaagent-module-patterns.md` |
 | Semconv | Library vs javaagent semconv constant usage | Semconv constants/assertions | — |
 | Semconv | Dual semconv testing | `SemconvStability`, `maybeStable`, semconv Gradle tasks | `testing-semconv-stability.md` |

.github/agents/knowledge/javaagent-singletons-patterns.md

@@ -3,7 +3,7 @@
 ## Quick Reference
 
 - Use when: reviewing `*Singletons` holder classes and their callers
-- Review focus: field/accessor naming, eager initialization, static-import call sites
+- Review focus: field/accessor naming, eager initialization, singleton accessor call sites
 
 Javaagent modules keep shared `Instrumenter` instances and related collaborators in a dedicated
 `Singletons` holder class such as `MyLibrarySingletons`.
@@ -28,10 +28,12 @@ Javaagent modules keep shared `Instrumenter` instances and related collaborators
   - `CONTEXT` stays `CONTEXT`
   - `REQUEST_INFO` stays `REQUEST_INFO`
   - `RESPONSE_STATUS` stays `RESPONSE_STATUS`
-- Callers should static import the exported singleton member and use it unqualified:
-  accessor methods for lower camel collaborators, fields for uppercase constant-like members.
+- Callers should static import only exported singleton accessors and uppercase constant-like
+  fields, and use those members unqualified: accessors for lower camel collaborators, fields for
+  uppercase constant-like members.
 - Keep verb-named helper methods as verbs when they perform work instead of returning a stored
-  field. This naming rule applies to field accessors.
+  field. These methods are not singleton accessors and should not be static imported under this
+  rule.
 
 ## Preferred Pattern
 
@@ -102,7 +104,9 @@ class MyInstrumentation implements TypeInstrumentation {
   and immutable value constants.
 - Accessor methods named `getInstrumenter()`, `getHelper()`, `getSetter()`, and similar when they
   simply return a backing field.
-- Call sites that qualify singleton member usage with the holder class instead of static importing
-  the accessor or field.
+- Call sites that qualify singleton accessor or uppercase constant-like field usage with the holder
+  class instead of static importing the accessor or field.
+- Static imports of non-accessor helper methods on a `*Singletons` class when the method performs
+  work instead of returning a stored singleton or constant.
 - Mismatches between a field name and its accessor, such as `private static final Helper helper;`
   with `public static Helper getHelper()`.