docs(repo): capture rewrite and independent review practices

[jgoux]

Adds tool-independent review checkpoints with bounded rounds and evidence-based consensus.

Strengthens existing guidance to design from consumer requirements, justify complexity with current needs, exercise shared contracts across implementations, and verify contract-required cleanup. Effect coding practices remain owned by the repository-local skill.

[github-actions]

🤖 AI Review

Both independent reviews completed; Codex reported no findings. Of Claude's four documentation nits, two are confirmed formatting/content regressions and two are refuted by the surrounding text and the distinct scope of the existing AI-review documentation.

Findings

Severity	Location	Category	Sources	Claim
⚪ NIT	AGENTS.md:172	docs-style	claude	The new flake-resistance bullet is hard-wrapped while every other bullet in the same list is unwrapped, making the list formatting inconsistent.
⚪ NIT	AGENTS.md:140	docs-content	claude	The Refactoring rewrite removes explicit general guidance to move responsibility to the correct owner and to delete obsolete helpers, shims, and parallel paths, replacing it with narrower wording.

Refuted findings (kept for transparency, not posted as review comments)

• AGENTS.md:78 (docs-maintenance): The new Independent review section duplicates the repository's maintained AI-review mechanism without linking to it.
  Refuted: The documents cover materially different workflows. AGENTS.md:80-91 specifies iterative reviews at design and implementation checkpoints, potentially with several rounds; .github/ai-review/README.md:3-7 explicitly documents a GitHub Actions review that runs exactly once per PR. The new section is not copied documentation of that mechanism.
• AGENTS.md:82 (docs-clarity): The authorization sentence can be read as blanket permission to invoke review tooling without asking the user.
  Refuted: AGENTS.md:81-83 expressly scopes the permission rule by first requiring adherence to the user's reviewer choice and that reviewer's authorization requirements, then limiting non-repetition to an already authorized workflow. The surrounding text therefore does not grant blanket authorization.

Stats

Claude findings: 4 · Codex findings: 0 · Confirmed: 2 · Refuted: 2 · Uncertain: 0

---

Models: claude-opus-5 + gpt-5.6-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.