Add honest test coverage rule to AGENTS.md

Codify the principles that drove the 5.16.2 cleanup so future
contributors (human or agent) pick them up the same way.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: seanthegeek

AGENTS.md

@@ -95,3 +95,9 @@ These rules apply to anyone — human or agent — making changes to this repo.
 - **Read official documentation in full before implementing against an unfamiliar API.** Fetch the relevant pages and read them end-to-end, not just the headings. When the docs offer both a quick-reference and a detail page on the same topic, read the detail page — quick-references omit aliases, edge cases, and secondary functions you will need.
 - **SDK research order: installed source, then vendor docs, then GitHub issues.** When figuring out how a vendor SDK behaves, the installed SDK's source is the source of truth, vendor documentation is second, GitHub issues are third (for known bugs and undocumented behavior). Third-party blogs, Stack Overflow answers, and AI-generated explainers are not primary evidence — at best they are pointers to one of the three primary sources.
 - **Don't catch `Exception` broadly.** Catch only the specific exception types you have a recovery path for. A bare `except Exception:` (or `except:`) hides programming errors that should be loud, makes debugging harder, and disguises broken assumptions as transient failures. Let unexpected exceptions propagate.
+- **Honest test coverage.** The number on the badge is a means, not the goal — every test must earn its place by exercising real behavior. Concretely:
+  - Tests must assert on observable behavior, not on whether a mock was called. A test that mocks every dependency and only asserts the mocks were invoked is testing the test, not the code. The mock is allowed to provide the *trigger* (a synthetic network failure, a forced exception type) as long as the assertion is on the function's contract — its return value, the warning it surfaces, the state it leaves behind.
+  - No `# pragma: no cover` to dodge ugly branches. If a branch is unreachable, delete it. If it's reachable but hard to test, write the test.
+  - No expanding the coverage `omit` list to chase a number. Legitimate reasons (e.g. maintainer scripts that ship outside the wheel) are fine; "hard to test" is not.
+  - No trivial passthrough tests. Calling a getter and asserting it returns the value just set isn't a test.
+  - If hitting a coverage target requires faking it, ship the honest lower number and flag the modules where the effort stopped. 85% honest beats 90% performative.