[infra] Follow-up improvements to AGENTS.md and code_review.md

[weiqingy]

Background

AGENTS.md and code_review.md were introduced in #878 and already iterated on in #890. Both PRs frame the guides as living documents meant to be refined continuously. This issue tracks a few concrete, self-contained follow-ups, so they can be discussed and picked up as small independent PRs.

I'm happy to take these on if a committer is supportive. Splitting into the two well-scoped changes below to keep each PR small and reviewable.

Proposed changes (high confidence, ready to implement)

1. Freshness check for the version facts in AGENTS.md

AGENTS.md hard-codes facts that can silently drift from their real source: Python 3.10 through 3.12, Ruff line length 88, Java 11. This is not hypothetical — the source of truth for these already lives in python/pyproject.toml and the root pom.xml, and comparable version strings elsewhere in the repo have drifted before.

Proposal: a small script under tools/, wired into the existing lint/CI lane, that asserts the versions quoted in AGENTS.md match python/pyproject.toml and pom.xml. This makes the guide un-rottable and is mechanical to review.

Shape: one [ci] / [infra] PR.

2. Worked-examples appendix for code_review.md

#890 added the "Review Lenses" section and a dedicated design-focused pass, but the passes are still described in the abstract. A short appendix that maps a few already-merged bugs to the exact pass that would catch them would make the checklist more tangible without changing any of its policy.

Candidate cases, all from merged PRs in this repo:

• Durable-serde type loss where a byte[] value returned as a base64 String after replay ([runtime] Binary serde for MemoryUpdate values via versioned Kryo envelope #874) — illustrates "does the root cause still exist through the serialization path?".
• A compatibility fallback that could fail during Pemja init, removed in favor of explicit config ([python] Remove PyFlink gateway fallback from AgentConfigOptions #867) — illustrates the beta "don't preserve compatibility by default" policy.
• A memory-value contract that rejected a safe bytes type ([python] Admit bytes in the Python memory value contract #846) — illustrates the Java/Python parity and reject-at-boundary passes.
• An Error swallowed in a Future instead of failing the task ([hotfix] Propagate action task Errors from mailbox #880) — illustrates "test the actual runtime path where the bug occurred".

Each case would be 3-5 lines: the symptom, the pass/lens that catches it, and the fix pattern.

Shape: one docs-only PR appended to code_review.md.

Items worth discussing before implementing

These are more opinionated, so raising them here first rather than opening a PR:

• A change-type review matrix (e.g. api/ contract changes, runtime/ state or recovery changes, Python-Java bridge changes, dist/dependency changes, docs-only changes) mapping each PR type to the passes that matter most, as an on-ramp into the existing full checklist.
• Whether module-scoped AGENTS.md files (e.g. under python/, runtime/python/, dist/) would help, given how differently those sub-domains behave.
• Whether CLAUDE.md and AGENTS.md should converge toward one source of truth with a thin pointer from the other, to avoid the two guides drifting.

Feedback on scope and priority welcome.

[weiqingy]

@wenjin272 — following up on the AGENTS.md / code_review.md iteration you've been driving (#878, #890). I've drafted the two follow-ups above and verified both locally. Before opening PRs I wanted to check the direction is welcome, per the issue-first guideline.

1. Freshness check — a small dependency-free tools/check-agents-md.py wired into the lint CI job. It derives the Python range, Ruff line length, and Java version from python/pyproject.toml and pom.xml and asserts AGENTS.md still quotes them, so the guide can't silently drift. Verified green on current main, and red when I simulated a Python-3.11 or Java-17 bump.

2. Worked-examples appendix — a short ## Worked Examples section in code_review.md mapping four merged bugs (#874, #867, #846, #880) to the specific passes that surface them, to ground the checklist in concrete cases.

Happy to open these as PRs once we're aligned on the direction, or to adjust scope/shape first if you'd prefer.