docs: record four testing practices the v2.6.0 release earned

[leggetter]

Four practices that cost real time during the v2.6.0 release and were written down nowhere. Docs only — no code, no behaviour change.

No new TESTING.md: AGENTS.md §9 and test/acceptance/README.md already own this ground, and a third file would split the guidance three ways.

AGENTS.md §9 — Testing Guidelines

A fix is not done until you have reverted it and watched the test fail.

A post-merge audit of #392 reverted each fix in turn and re-ran the suite. Eight fixes could be deleted with the board still green. It also found two tests that failed for the wrong reason — a listen status-bar regression reported itself as a colour bug — and one test that had been rewritten to assert the regression it was written to catch.

This was the only technique applied during that release with no false negatives, and it takes about a minute per fix.

Prove a filter with a negative control. "No error" is not evidence.

The API answers 200 and returns a full result set for a query parameter it does not support, so a silently dropped filter looks identical to a working one. Assert both directions: a real value narrows the result, a bogus value returns zero.

This was the most repeated defect class in the release — --connection-id on metrics attempts, delivery_group on hookdeck_requests list, comma-separated --id on three commands. One negative control catches all of them, and nothing else did.

When a fix has several call sites, test each separately.

The delivery-group data loss existed in four code paths. The third was found only after the first two were considered fixed — by writing an acceptance test, after two code reviews had passed over it.

AGENTS.md — CLI authentication keys

The CLI writes single-quoted TOML, so a redaction pattern matching only "..." prints the key verbatim. Two separate agents did exactly this within one day, both believing they had redacted correctly.

test/acceptance/README.md — new "Rate limits" section

The API allows 240 requests/minute and a full slice makes thousands of calls.

Two concurrent runs against the same projects exhaust it: every job hits its timeout with 429s, and zero assertion failures. That reads as a code failure and is not — it cost an hour of misdirected diagnosis. The section also notes that a direct push triggers a pull_request run, so pushing and dispatching together produces precisely this collision.

Deliberately not included

• A rule that the CLI and MCP layers must not drift. There is already a comment asserting it, and it was violated three times in one release. That needs a shared constant, not a doc line.
• "Search before filing an issue." Generic good practice, not specific to this repo.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01BnrKWZQASV7bFJ4oGWwmo9