[dmccoystephenson]

Stage A documentation accuracy sweep. Every README section, the class and method Javadoc, the pom.xml description and version, and the build.yml matrix comment were checked against TraceClient.java. Two gaps were found, both in the README:

• "What report promises" → Bounded. The row sits directly under "Drops are logged at FINE if you gave a logger". A report dropped by a full queue goes through ThreadPoolExecutor.DiscardPolicy and is never logged, at any level. The row now says so. queue_isBoundedAndDropsRatherThanGrows now attaches a RecordingHandler and asserts that no record is logged across the flood. Every delivered report gets a 201, so any record would have to come from a drop.
• "Server-wide tags". The first bullet now also says that a line indented differently from the block's first entry is skipped, and that an enabled: line inside the block is a tag, not the switch. Both behaviours were already stated in parseServerWideConfig's Javadoc and pinned by serverWideTags_blockEndsAtTheNextUnindentedLineOrEndOfFile and serverWideTags_aHashIsACommentOnlyAfterWhitespace.

No production code changed. The "Opting out" and "Keys" sections were left untouched.

No tracking issue: both gaps were found during the sweep.

Test plan

• mvn -B verify locally (Java 21): Tests run: 78, Failures: 0, Errors: 0, Skipped: 0
• CI matrix build (8), build (17), build (21) green on the PR head

Deferred issues

• withVersion pushes an event already at MAX_TAGS over the server's tag limit #13 (withVersion exceeds MAX_TAGS): skipped. It changes what is sent on the wire and is marked as needing a maintainer decision.
• A quoted enabled: "false" in the server-wide config does not turn reporting off #15 (quoted enabled: does not disable): reopened this cycle. It had been auto-closed by a GitHub closing keyword ("resolves" followed by the issue number) in PR Cover the line reader's escapes, comments and quoted switch #16's body, although the behaviour is unchanged. It is skipped for the same reason as withVersion pushes an event already at MAX_TAGS over the server's tag limit #13, since it touches the opt-out contract. Nothing about quoting was added to the README "Opting out" row, so as not to pre-empt either of the options the issue lists.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric (anchor: CI run 39114275033 on the PR head, build (8), build (17) and build (21) all pass):

• Scope: PASS. Only README.md (two passages) and one existing test are touched, and both serve the two documented gaps. No formatting churn.
• Tests-new: PASS (n/a). No new public members.
• Tests-fix: PASS (characterization, verified empirically). No production fix is in scope. To show the new assertion can fail, DiscardPolicy was temporarily replaced locally with (r, e) -> log("dropped"). queue_isBoundedAndDropsRatherThanGrows then failed with a full queue drops without logging, but logged: 511. Once TraceClient.java was restored, it passes.
• Sibling structure: PASS. No new files. The test reuses the RecordingHandler and uniquely named Logger pattern from report_doesNotThrowWhenNothingIsListening.
• Sibling renames: PASS (n/a). Nothing renamed. The test name was kept because the skill's flake list refers to it by name.
• Docs: PASS.
  • The "Bounded" row now matches the DiscardPolicy in the constructor.
  • The tags bullet now matches the entryIndent check in parseServerWideConfig and the enabled:-inside-the-block case in serverWideTags_blockEndsAtTheNextUnindentedLineOrEndOfFile.
  • The class Javadoc ("new reports are dropped rather than accumulated") does not contradict either change.
  • The version strings agree in all four places (0.6.1).
• Issue resolution: PASS (n/a). No Closes reference, and closingIssuesReferences is empty. The quoted closing keyword in the first draft of the body was reworded, so A quoted enabled: "false" in the server-wide config does not turn reporting off #15 is not closed again on merge.
• CI: PASS. All three matrix legs are green.

Repo-specific:

• No dependencies / Single file / Java 8 / Environment seam / Opt-out contract: PASS. src/main is unchanged, pom.xml is untouched, and build (8) is green.
• Never throws / Non-blocking & bounded: PASS (n/a). There are no production changes.

Observations:

• README.md:139: "Drops are logged at FINE" still reads as covering every drop when the row is read on its own. The "Bounded" row now gives the exception explicitly. Rewording the row was not considered necessary.
• The do-not-auto-merge paths were checked: no .github/workflows, pom.xml, version strings, wire format, or README "Opting out"/"Keys" sections are touched.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson