docs: document the automated PR review and fix the decision count

.changeset/document-argus-review.md

@@ -0,0 +1,8 @@
+---
+---
+
+docs: document the automated PR review in `CONTRIBUTING.md` and correct the
+confirmed-decision count (21 → 24) in `CONTRIBUTING.md` and `CLAUDE.md`.
+
+Empty changeset because this only affects contributor documentation, not the
+published Java SDK artifacts.

CLAUDE.md

@@ -12,7 +12,7 @@ Status: harness phase. Eight Gradle modules wired and green; most surfaces are p
 
 In order of precedence:
 
-1. **[`ROADMAP.md`](ROADMAP.md) §Confirmed decisions** — 21 numbered decisions (D1–D21) that lock in architecture, build, conventions. **These override the RFC where they differ.**
+1. **[`ROADMAP.md`](ROADMAP.md) §Confirmed decisions** — 24 numbered decisions (D1–D24) that lock in architecture, build, conventions. **These override the RFC where they differ.**
 2. **[`docs/rfc/java-sdk-rfc.md`](docs/rfc/java-sdk-rfc.md)** — the merged RFC.
 3. **[`ROADMAP.md`](ROADMAP.md) §Tracks** — what each module is supposed to contain, in track-claim form.
 4. **[`ROADMAP.md`](ROADMAP.md) §7.x deltas** — what changed in the TS SDK between the RFC's 6.x baseline and the current 7.2.0.
@@ -75,6 +75,13 @@ The SDK generates Java types from JSON Schemas at `https://adcontextprotocol.org
 
 JUnit 5. Conventional test layout (`src/test/java/...`). Tests run with `./gradlew test`. Storyboard CI lives in `adcp-testing` and hits the `@adcp/sdk/mock-server` sidecar in CI (D8).
 
+## AI PR review (Argus)
+
+`.github/workflows/ai-review.yml` runs an LLM reviewer on every non-draft, non-dependabot PR. Two things to know before you touch it:
+
+- Its invariants are enforced by `scripts/check-ai-review-workflow.cjs`, run by the `Validate Argus review config` workflow on every PR. Run it locally with `node scripts/check-ai-review-workflow.cjs`. If it fails, read the message — each check exists because that failure mode already shipped once.
+- The workflow, `.github/workflows/validate-ai-review-config.yml`, the prompt under `.github/ai-review/`, the validator, `.claude/agents/`, `.agents/roles/` and `.github/CODEOWNERS` are **self-modification guarded**: a PR touching any of them pauses Argus and requires a human reviewer. Expect no bot review on those PRs.
+
 ## Picking up work
 
 The contributor onboarding path is in [`CONTRIBUTING.md`](CONTRIBUTING.md): claim a track via issue, work on a feature branch, PR to `main`. The 14 tracks live in [`ROADMAP.md`](ROADMAP.md#tracks).

CONTRIBUTING.md

@@ -22,7 +22,7 @@ Read [`ROADMAP.md`](ROADMAP.md) first. It divides v0.1 → v1.0 into 14 claimabl
 
 A single contributor can claim multiple non-conflicting tracks. High-coupling tracks (`async-l3` + `lifecycle`) benefit from a single owner pair.
 
-Before designing anything new, read the [21 confirmed post-RFC decisions](ROADMAP.md#confirmed-decisions). They override the RFC where they differ.
+Before designing anything new, read the [24 confirmed post-RFC decisions](ROADMAP.md#confirmed-decisions). They override the RFC where they differ. D1–D21 are fully locked; D22's shape is detailed in [`specs/signing-context.md`](specs/signing-context.md), D23 pins the parity target at `3.1.0-beta.5` with the GA bump deferred to the codegen PR, and D24 has shipped.
 
 ## Dev setup
 
@@ -60,6 +60,22 @@ rm settings-gradle.lockfile && ./gradlew help --write-locks
 
 CI verifies lockfiles are up to date on every PR — the `Verify lockfiles are up to date` step will fail if you forget. Commit all updated lockfiles alongside your dependency change.
 
+## Automated PR review
+
+Every non-draft pull request gets an automated review from **Argus**, an LLM reviewer that reads your diff and posts an approve / comment / request-changes review. (Dependabot PRs are skipped.) Two things usually surprise first-time contributors:
+
+- **The review arrives from `aao-ipr-bot[bot]`** — the same GitHub App that handles the IPR signature check. One App covers both, which is why the "IPR bot" appears to be reviewing your Java.
+- **Argus cannot change your branch.** It runs read-only: no shell, no file writes, no network fetches. It reads the diff and repository files and returns a review.
+
+What its verdict does and does not mean:
+
+- An Argus approval **does not** satisfy branch protection. `main` still requires a review from a human code owner (D21), and the bot is not one.
+- If Argus cannot complete — a crash, a timeout, output that fails validation — the check **fails**, and in most cases it posts a comment saying so (the comment needs an App token, so a token-minting failure leaves a red build with no comment). A missing review is a red build, never a silent pass. Re-running the job is worth one try if the log shows a transient API error; if it fails the same way twice, ask a maintainer to review instead.
+
+Argus deliberately skips PRs that change the review system itself (`.github/workflows/ai-review.yml`, `.github/workflows/validate-ai-review-config.yml`, `.github/ai-review/`, `scripts/check-ai-review-workflow.cjs`, `.claude/agents/`, `.agents/roles/`, `.github/CODEOWNERS`). Each of those gates the review in some way — the workflow, prompt and agent definitions are the ones Argus itself loads from the base branch, so it would be judging a change to its own gates using the version that change replaces. Those PRs get a "paused" notice and need a human reviewer.
+
+You can also get that notice on a PR touching none of those paths: the gate fails closed, so if the changed-file list can't be read at all — `gh pr diff` rejects very large diffs — it pauses rather than guess.
+
 ## Code conventions
 
 - **Java 21 baseline** (D2). Use records, sealed types, pattern matching, virtual threads. No `Optional<T>` returns — use `@Nullable T` (JSpecify) instead.