diff --git a/AGENTS.md b/AGENTS.md index e4e8dad459..7cdec80512 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,6 +72,16 @@ pnpm exec turbo run supabase#build pnpm run test:live ``` +## Independent review + +For substantial redesigns, use an available independent reviewer at the design stage, after a +meaningful implementation boundary, and for the final code and tests. Usually run two or three +focused rounds per checkpoint and stop at consensus. The reviewer should assess how findings were +fixed and verified, refuted with evidence, or accepted within the authorized tradeoff, with no +material objections remaining; do not force agreement. Report unresolved decisions and continue +only work that does not depend on them. A user-requested further round takes precedence; +an authorized workflow needs no repeated permission, and review never replaces execution evidence. + ## Comments Comments exist for the next reader, not as the author's audit trail. Code states what happens; a @@ -117,11 +127,14 @@ Internal unreleased APIs may be simplified or reshaped; move responsibility to t and delete obsolete helpers, shims, and parallel paths instead of preserving compatibility scaffolding. Protect shipped interfaces and valuable persistent data; update consumers, tests, and docs when interfaces, ownership, or lifecycle changes. +Base designs on consumer requirements and documented invariants rather than inherited code +structure. Justify additional complexity with a current need or documented contract; prefer explicit +limitations over speculative machinery while preserving required safeguards. ## Test quality - Write focused tests that read as stories: arrange, act, assert. -- Assert behavior that matters to consumers, not implementation details. Prefer real parsers and observable outcomes over source-text or registry checks. +- Assert behavior that matters to consumers, not implementation details. Prefer real parsers and observable outcomes over source-text or registry checks. Exercise shared contracts across supported implementations. - Make assertions meaningful: establish prerequisites, check specific failures, and choose matchers that express the intended contract. - Keep setup concise with small fixtures. Accept some duplication rather than introducing unnecessary test abstractions. - Remove redundant coverage. Push back on review suggestions that add assertions without protecting meaningful behavior. @@ -140,7 +153,7 @@ Keep tests flake-resistant: - Subscribe before triggering a transition; use observable readiness/completion, never sleeps or polling delays for propagation, startup, cancellation, cleanup, or port release. Timeouts are guards; use controlled clocks or fake timers for timing semantics. - Assume file-level parallelism: use unique IDs, roots, process markers, and derived resources; never disable parallelism globally. - Never release and reuse an ephemeral port or assume a released endpoint is a dead backend; own a refusal listener or inject the failure. -- Require subprocess readiness and stdout/stderr diagnostics; clean up only exact owned resources. Reproduce and stress flake fixes, then repeat the green case. +- Require subprocess readiness and stdout/stderr diagnostics; clean up only exact owned resources and verify the cleanup required by the contract. Reproduce and stress flake fixes, then repeat the green case. ## Maintaining instructions