docs(agents): add first-pass review-readiness checklist (mined from ~300 PRs)

[vibegui]

Summary

Refactors AGENTS.md (the file CLAUDE.md symlinks to) with a new "Ship it review-ready — the first-pass checklist" section, derived from analyzing what actually changes between a PR's first proposal and its merged state.

How this was built

Mined the last ~300 merged PRs, looking specifically at the diff between the first commit and the merged result — the "review/hardening work." Findings, using the graph as a map of where churn concentrates (decopilot, sandbox, chat, sections-editor — the same hotspots the audit flagged):

• Inline code review is ~absent (0 inline comments across 97 recent PRs) — review here is self-review + a cross-user handoff: a first draft ships, then a hardening pass adds fixes before merge.
• The vibecoder→engineer pattern is real but role-by-context, not by-person. Across 591 PRs, 22 cross-user merges: pedrofrxncx is the primary hardener (closes PRs from vibegui, 0xcucumbersalad, guitavano), tlgimenes gatekeeps the app/deco-cms agent's commerce PRs. Clean examples where an engineer took over the branch and added commits: feat(sidebar): separate team threads, my threads, and agents #4230 (vibegui → rafavalls+pedrofrxncx: rewrote the impl, deleted 297 lines of dead components, fixed a teammates'-threads-read-only permission bug, added tests), fix(cms-studio): fix block-ref schema resolution for @decocms/start >=6.10 loaders #4008 (JonasJesus42 → guitavano, 11 commits: every schema variant + a test per fix + URL validation + reverted an over-clever "infer from runtime data"), feat(decopilot): split web research into web_search + deep_research #4134 (cecilia → viktormarinho added the missing tests), chore(lint): enforce web ↔ server import boundary (ban-web-server-imports) #4469 (the earlier lint PR: ban-list → allowlist hardening). Notably, clean security PRs (fix(security): prevent admin-to-owner privilege escalation in member tools #4022/fix(security): block STDIO command injection — RCE at connection creation #4023) were merged as-is — engineers don't touch what's already right.

The hardening pass adds the same 9 categories every time. The checklist encodes them so a coding agent does them on the first pass, each citing the PR it came from:

1. Handle the variants, not the happy path (empty/null/oversized/every schema shape)
2. Scope by tenant & permission; gate the complete payload; no key/id collisions
3. Concurrency — no silent data loss (non-retriable side effects, claim fences at dispatch, coalesce fire-and-forget)
4. Test each behavior in the right tier — invert bug-encoding tests, grep all tiers, real-Postgres for storage, provider-independent e2e
5. Leave no dead code (narrow exports, delete orphans, run knip)
6. Complete the lifecycle & reset state (create+update+delete together, idempotent clear-then-write)
7. Make risky/infra changes reversible & bounded (own default-off flag, TTL+cap GC, health-gated publish, git-exclude, idle reaper over fixed timeouts)
8. Validate external input; don't over-engineer (schema-driven > runtime inference; DS tokens; fmt)
9. Keep type-safety at compile time (no as-cast on unions; noUncheckedIndexedAccess)

It's cross-linked with the existing "Common Gotchas" list (which stays as the always-load-bearing set).

Testing

Docs-only change to AGENTS.md. No code touched.

Notes

• CLAUDE.md is a symlink to AGENTS.md, so this covers both.
• Companion to the codebase audit in Codebase↔strategy audit: simplify the MCP-mesh machinery, converge deploy previews with sandboxes-as-production (agent-ready work items) #4468 and the lint-boundary PR chore(lint): enforce web ↔ server import boundary (ban-web-server-imports) #4469.

🤖 Generated with Claude Code

---

Summary by cubic

Adds a “Ship it review‑ready” first‑pass checklist to AGENTS.md to help authors ship PRs that need fewer hardening passes. The checklist distills nine recurring fix areas from ~300 merged PRs and links to real examples.

• New Features
  • 9-point checklist covering: edge-case/variant handling; tenant/permission scoping; concurrency/idempotency; test-per-fix in the right tier; dead code cleanup; lifecycle symmetry/state reset; reversible infra via flags/GC; input validation/DS tokens; compile-time type safety.
  • Cross-linked with “Common Gotchas”. Docs-only; CLAUDE.md (symlink) reflects the change.

^{Written for commit e3fb43a. Summary will update on new commits.}