docs: add AGENTS.md as the agent-facing engineering source of truth

[devops-thiago]

Problem Statement

AI-assisted contributions (and new human contributors) currently reconstruct the project's load-bearing conventions from scattered sources: ARCHITECTURE.md, prompt-content test javadocs, issue history, and the code itself. Several rules are easy to violate without knowing they exist — every AI call must go through ReviewTokenLedger; prompt constants are concatenated into budget-overhead estimates in three places; PrReviewPromptsContentTest pins guidance that specific issues fought for; @UserMessage placement is guarded by dedicated tests. Violations surface late, as review findings or broken budgets, instead of never happening.

This matters more during the #669 refactor, where prompts, budgeting, and the call graph are all being restructured at once.

Proposed Solution

Add an AGENTS.md at the repo root as the single agent-facing engineering doc, and keep any assistant-specific files (e.g. CLAUDE.md) as one-line pointers to it. Content:

• The invariants: token-ledger gating, REVIEW_MAX_AI_CALLS accounting, the three prompt-overhead estimation sites, prompt-content pinning tests, the eval corpus (-Peval) as the recall gate, the lockstep rule for prompt constant + @V param + inputs record + assembler.
• The map: package responsibilities, where each pipeline stage lives, which test doubles exist for streaming (FakeTokenStream and friends).
• The why-nots: decisions with the reason the alternative failed (e.g. chat memory disabled because of Review calls carry a chat-memory window of prior prompts, inflating requests ~7x and breaking the budget #584's 7× request inflation; no retry on finish_reason=length per fix(ai): stop retrying a response truncated at the length cap #495). Recording the failure reason is what stops the alternative from being re-proposed.
• Kept current by convention: a PR that changes an invariant updates AGENTS.md in the same diff.

Alternatives Considered

• Keep relying on ARCHITECTURE.md + test javadocs — describes structure well, but the invariants and why-nots stay implicit and get rediscovered the hard way.

Priority

Nice to have — but cheapest right before the v0.7 refactor, which is when the invariants will be under the most pressure.