diff --git a/AGENTS.md b/AGENTS.md index b8d974730..db2447834 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,3 +67,39 @@ requirements. If a related check fails, fix it. If a required check cannot run because of the environment or fails for an unrelated external reason, report the exact failure and obtain maintainer direction rather than silently ignoring it. + +## 4. Common Review Blockers + +These classes drive multi-round reviews. Fix them before requesting review: + +- **Fresh base:** Rebase onto the current PR base (`main` or stacked target) + before review. A stale head that rolls back mainline commits is a hard + blocker, not a merge-time detail. Resolve conflicts by keeping upstream + behavior unless the PR intentionally changes it. +- **Platform truth:** Code and tests must pass on Linux, macOS, and Windows. + Compare paths after canonicalization (physical/`EvalSymlinks` form); never + assert raw `t.TempDir()` spellings (`/var` vs `/private/var` on macOS, short + paths on Windows). Prefer one cross-platform function with small `GOOS` + checks over duplicated helpers that drift. +- **Security edges:** Keep secrets out of argv, env dumps, and logs. Redact + success and error paths (including stderr). Fail closed on ownership, lease, + and permission checks. Do not rely on pre-open path resolution + (`EvalSymlinks` then open) for containment: that is a check-to-use race. + Bind containment at open/use time with rooted or handle-relative, + traversal-resistant APIs. If a no-follow API is used, apply it to every + traversed component and enforce the platform's reparse-point protections; + final-component-only no-follow is insufficient. On multi-step setup, roll back + only what this run created; never destroy pre-existing resources you did + not create; never report success when cleanup or unlock failed. +- **Atomic shared state:** Write a complete temporary file, then atomically + replace the destination so concurrent readers never see a partial write. + Exclusive create or a write lock alone is not enough for readers. Serialize + the full read-modify-write sequence for lockfiles and shared stores. +- **Tests match the claim:** Every behavior or security-boundary change needs a + regression test, including the failure path. Path-sensitive logic needs at + least one non-Linux path case (or a hermetic fake that exercises the same + normalization). +- **Honest scope:** PR description, help text, and comments must match what + shipped. Wire advertised entry points or shrink the claim. Do not bundle + unrelated fixes. Do not widen security allowlists by name alone; check + classification and side effects too.