From 1b4f62d50141f0e3e8439fdeee881283cf66147e Mon Sep 17 00:00:00 2001
From: cxymds <cxymds@gmail.com>
Date: Fri, 21 Aug 2026 10:10:56 +0800
Subject: [PATCH] docs(agents): run adversarial review before pre-pr (#6325)

docs(agents): order adversarial review before pre-pr
---
 AGENTS.md       | 15 +++++++++------
 CONTRIBUTING.md | 10 ++++++----
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index d2c915c16..2004c597d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -127,8 +127,9 @@ the broadest gate. Inspect only the final task-owned diff, classify it by
 behavioral impact rather than line count or path alone, and run the smallest
 set of checks that provides meaningful coverage. Do not let unrelated
 worktree changes or a generic contributor checklist expand the scope.
-Non-exempt changes must also pass Adversarial Validation (next section) before
-the checks below count as completion.
+For non-exempt changes, complete the applicable multi-role adversarial review
+before running `make pre-pr` (or an equivalent full gate). Resolve or rebut
+every finding first, then run the gate against the reviewed final diff.
 
 ### Validation floor
 
@@ -166,8 +167,9 @@ the checks below count as completion.
    dependency set is identifiable, validate those packages and known
    dependents instead of the whole workspace. Use `make pre-commit` only when
    a repository-wide fast gate adds useful confidence beyond those checks.
-4. **Broad or high-risk change:** Run `make pre-pr` only when targeted coverage
-   cannot bound the impact, including:
+4. **Broad or high-risk change:** After the applicable adversarial review has
+   completed, run `make pre-pr` only when targeted coverage cannot bound the
+   impact, including:
    - dependency, feature, build-script, procedural-macro, code-generation,
      toolchain, or CI changes that alter compilation or the test matrix;
    - cross-crate public APIs, shared foundational code, or broad refactors with
@@ -287,8 +289,9 @@ High risk: all seven roles.
 - Every testable behavior change has a focused regression check. Exceptions
   follow the validation floor and state why a check is impractical and what
   risk remains.
-- The Verification Before PR gates pass — adversarial review supplements
-  those gates, never replaces them.
+- After the applicable adversarial review has completed, the Verification
+  Before PR gates pass; adversarial review supplements those gates, never
+  replaces them.
 - High risk only: record a one-line verdict per role in the PR description.
 
 ## Git and PR Baseline
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6414fa9d7..7882a486e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -91,8 +91,9 @@ A green `make pre-commit` is not enough to open a pull request.
 `make pre-pr` is the **full** gate: it runs all of the guard checks above,
 then `clippy-check` (`cargo clippy --all-targets --all-features -- -D warnings`)
 and `test` (shell script tests, workspace tests excluding `e2e_test`, and doc
-tests). Run `make pre-pr` before opening or updating a pull request — this is
-what CI enforces.
+tests). Complete the applicable multi-role adversarial review described in
+`AGENTS.md` before running `make pre-pr`; then run the gate before opening or
+updating a pull request. This is what CI enforces.
 
 ### 🔒 Git Pre-commit Hooks (optional)
 
@@ -150,8 +151,9 @@ Example output when formatting fails:
 2. **Format your code**: `make fmt` or `cargo fmt --all`
 3. **Run the fast gate**: `make pre-commit` (no clippy, no tests)
 4. **Commit your changes**: `git commit -m "your message"`
-5. **Run the full gate before opening/updating a PR**: `make pre-pr` (clippy + tests)
-6. **Push to your branch**: `git push`
+5. **Complete the applicable multi-role adversarial review** for non-exempt changes (see `AGENTS.md`)
+6. **Run the full gate before opening/updating a PR**: `make pre-pr` (clippy + tests)
+7. **Push to your branch**: `git push`
 
 ### 🛠️ IDE Integration