docs(agents): test-failure triage discipline — suspect the test first, but test edits stay asymmetric

2026-10-17 lessons from the hardening session: most test/bruno failures
were harness/schema/environment drift (drifted body keys, truncated
payloads, container-only paths), found by triaging the test before the
server. Codified as: triage order (test schema -> environment -> cheap
probe), with the guard against "writing tests to work" — test/contract
edits are asymmetric with code fixes: only harness plumbing fixes,
additive pin widenings with a changelog entry, or deletions of tests of
removed behavior. Pins were green at a known commit; git history
arbitrates stale-vs-changed. A right-looking test that fails is prima
facie a server bug: stop and flag.

contract_pins.md rule 4: narrowing/removing a pinned key requires the
user's explicit sign-off — a pin freezing buggy behavior is a ledger,
not a license.

docs/contract_pins.md

@@ -15,6 +15,9 @@ These are the response SHAPES (JSON key sets, not values) frozen by the
 3. KOReader / Kobo / progress surfaces are the hard freeze: the KOReader
    plugin is an external client whose handlers keep response shapes
    byte-identical (only their internals may route through shared funnels).
+4. A behavior fix that would require narrowing or REMOVING a pinned key
+   needs the user's explicit sign-off before the pin is touched — a pin
+   freezing buggy behavior is a known-bugs ledger, not a license.
 
 ## Pinned surfaces