feat: enforce pull request readiness reviews

CONTRIBUTING.md

@@ -133,10 +133,94 @@ bun run docs:validate
 
 ## Pull Requests
 
-1. Fork and create a branch
-2. Make changes
-3. Run the validation commands above
-4. Submit PR with clear description of what and why
+Pull requests are review handoffs, not just diffs. A reviewer must be able to
+understand the intended behavior, assess the risk, and verify the result
+without reconstructing the contributor's work.
+
+Before opening a pull request:
+
+1. Read [`AGENTS.md`](./AGENTS.md), every project skill matching the character
+   of the change, and the nearest package README and module `DOCUMENTATION.md`.
+2. Keep the change focused. Separate unrelated cleanup or refactors.
+3. Run the validation required by the applicable project guidance, not only
+   the broad commands above.
+4. Complete the pull request template with concrete, current evidence.
+
+### Pull Request Contract
+
+Every pull request must explain:
+
+- **Intent:** the user or maintainer problem being solved and the resulting
+  behavior.
+- **Non-goals:** nearby behavior intentionally left unchanged when the scope
+  could otherwise be ambiguous.
+- **Affected surfaces:** packages, runtimes, persisted/external contracts, and
+  user-visible states affected by the change.
+- **Repository guidance:** the skills and owning documentation that were
+  applicable, why they applied, and how the implementation satisfies their
+  important constraints.
+- **Validation:** exact automated and manual checks performed, their result,
+  and anything that was not verified. A command name without a result is not
+  evidence.
+- **Risk and failure behavior:** meaningful failure, rollback, cleanup,
+  compatibility, security, performance, or cross-runtime considerations.
+
+Do not claim a runtime, platform, relay path, performance characteristic, or
+interaction is correct based only on type-checking or linting. If required
+validation could not be performed, state that explicitly and explain why.
+
+### Visual Evidence
+
+User-visible changes require evidence that lets a reviewer compare the
+behavior before and after the change. Attach screenshots for static states and
+a short recording for motion, gestures, drag-and-drop, focus, or multi-step
+interactions.
+
+Choose evidence based on the affected behavior:
+
+- Include before and after states. If a meaningful before state cannot be
+  captured, explain why.
+- Include narrow/mobile and desktop states when shared or responsive UI is
+  affected.
+- Include light and dark states when colors, styling, surfaces, or visual
+  states change.
+- Include relevant loading, empty, error, disabled, long-content, or
+  high-contrast states when the change affects them.
+- For Settings changes, show the relevant narrow and wide settings pane states.
+
+Evidence must represent the current pull request HEAD. After implementation
+changes that can affect the demonstrated behavior, refresh the evidence or
+state why it remains valid. If there is genuinely no user-visible change, say
+so and provide a concrete reason; deleting the evidence section is not an
+exemption.
+
+### Review Enforcement
+
+The automated reviewer performs one unified review of correctness, repository
+guidance compliance, pull request quality, and evidence. It independently
+determines which project skills apply from the character of the current diff,
+reads those skills and their required references, and checks the implementation
+against them.
+
+The reviewer records the exact HEAD it inspected and returns one verdict:
+
+- `PASS`: no blocking correctness, compliance, or evidence issue was found.
+- `NEEDS_EVIDENCE`: the change may be correct, but required proof is missing,
+  stale, or too weak to review responsibly.
+- `BLOCKED`: a concrete correctness, security, repository-rule, or contribution
+  contract violation must be fixed.
+- `HUMAN_REVIEW_REQUIRED`: the change affects review policy or another boundary
+  that automation must not approve on its own.
+
+The workflow exposes the current state as exactly one readiness label:
+`review:pending`, `review:ready`, `review:needs-evidence`, `review:blocked`,
+`review:human-required`, or `review:automation-failed`. A new review removes
+the previous readiness label before it starts, and only `review:ready` means
+the pull request is ready to enter the maintainer review queue. Draft pull
+requests have no readiness label.
+
+Each completed review creates a new comment tied to its reviewed HEAD so the
+conversation remains chronological. Previous review comments are not rewritten.
 
 ## Project Structure