diff --git a/.changeset/document-argus-review.md b/.changeset/document-argus-review.md new file mode 100644 index 0000000..28304dd --- /dev/null +++ b/.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. diff --git a/CLAUDE.md b/CLAUDE.md index 12494c4..d29446f 100644 --- a/CLAUDE.md +++ b/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). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9821dae..3378960 100644 --- a/CONTRIBUTING.md +++ b/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` returns — use `@Nullable T` (JSpecify) instead.