🤖 docs: add pre-PR checklist and review guidance to AGENTS.md

AGENTS.md

@@ -25,6 +25,48 @@ and runtime evidence answer different questions.
 
 ---
 
+## Before opening a PR
+
+Open work in progress as a draft PR. Mark it ready for review only when this
+checklist holds for the current change. Scale it to what changed:
+documentation-only changes need content, link, and diff checks plus human
+confirmation, not app runs.
+
+1. **Agent review ran** under [Reviewing](#reviewing), and its recommended
+   blockers were fixed or explicitly declined by the human author. Optional
+   suggestions do not gate readiness.
+2. **An agent exercised the changed behavior.** Client changes: the affected flow
+   in the app, using the native app or a device when the behavior needs it
+   (browser or headless Playwright counts only for what it can exercise). Relay
+   changes: a local relay, exercising the changed events or endpoints. CLI or
+   tooling changes: the affected command or workflow. The human may skip this
+   step, for example for a small change or while iterating.
+3. **A human then tested it themselves**: in the app, against the local relay
+   (through the app or `curl`), or by running the changed command. Agent testing
+   does not substitute. Agents give the human exact steps and what working looks
+   like, then wait for explicit confirmation. Never mark this step done yourself.
+4. **Add `buzz-review-completed` to the PR description** once steps 1–3 hold. It
+   attests the checklist, and automated reviewers may skip review because of it.
+   If later edits change behavior, remove it and return the PR to draft until the
+   affected steps are redone.
+
+## Reviewing
+
+- Before reviewing, read [VISION.md](VISION.md), the `VISION_*.md` docs for the affected surface, and the PR's stated goal and linked
+  issue. Review the change against what it is trying to do.
+- Check the change against the [Review-Proven Rules](#review-proven-rules): the defects reviewers here find most often.
+- Judge minimalism, elegance, and correctness, aiming for 9/10 on each. A score
+  below 9 names the concrete defect and the fix.
+- Recommend blocking only for concrete correctness, security, or agreed-contract
+  defects with a realistic failure scenario: state the defect, how it fails, and
+  the fix. Label everything else (nits, wording, speculative hardening,
+  out-of-scope improvements) as optional.
+- Put all findings in the first review. Later reviews check prior blockers and
+  defects the fixes introduced; reopen other areas only on new evidence of a
+  material defect.
+- Agents post reviews as comments, never Request Changes. Humans decide which
+  findings must be fixed.
+
 ## Ecosystem
 
 Buzz spans five repos. This one (`block/buzz`) is the OSS source for the relay, desktop, mobile, and CLI. The others handle internal builds and deployment:
@@ -165,8 +207,8 @@ the same clusters and measured how often authors actually fix each class
 once flagged: test-seam binding and unbounded-resource findings were fixed
 **100%** of the time, swallowed-error findings **90%**, stale-state races
 **70%** — these are not style opinions, they are defects authors agree
-with on sight. Apply the rules **before writing code**; each cites the
-PRs where reviewers litigated it.
+with on sight. Authors apply them **before writing code**, and reviewers check
+against them; each cites the PRs where reviewers litigated it.
 
 1. **Every caught failure must leave a durable retry record or propagate.**
    Never catch-log-and-return-success (opt-out revocation permanently