From 2e7b53f2746d2889db4d2e65842e83a5c8b4605d Mon Sep 17 00:00:00 2001 From: euxaristia <25621994+euxaristia@users.noreply.github.com> Date: Fri, 31 Jul 2026 18:27:39 -0400 Subject: [PATCH 1/3] docs(agents): codify recurring review blockers in AGENTS.md Capture the high-frequency classes that drive multi-round maintainer reviews (stale bases, path canonicalization, secret handling, partial setup, missing regression tests, scope honesty) so coding agents fix them before first review. Refs #856 --- AGENTS.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index b8d974730..7adab2ddb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,3 +67,35 @@ 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. Lexical path checks alone do not stop symlink or + reparse escape: resolve and re-validate containment before use. 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:** Use an atomic replace (or equivalent exclusive + write) for files concurrent readers may observe. Serialize read-modify-write + of 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. From f19a9a2a02ce74953468f354a2a19ba3be5b496a Mon Sep 17 00:00:00 2001 From: euxaristia <25621994+euxaristia@users.noreply.github.com> Date: Fri, 31 Jul 2026 18:45:04 -0400 Subject: [PATCH 2/3] docs(agents): tighten security and atomic-write review guidance Require open-time containment binding instead of pre-open EvalSymlinks, and require temp-file then atomic replace rather than exclusive create alone. Refs #856 --- AGENTS.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7adab2ddb..5873b1e5a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,14 +83,16 @@ These classes drive multi-round reviews. Fix them before requesting review: 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. Lexical path checks alone do not stop symlink or - reparse escape: resolve and re-validate containment before use. 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:** Use an atomic replace (or equivalent exclusive - write) for files concurrent readers may observe. Serialize read-modify-write - of lockfiles and shared stores. + 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 (no-follow or handle-relative APIs, and + platform equivalents for reparse points). 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 From 1bfe6cbc107f1889ed1b7e69db14cc1b464cb68c Mon Sep 17 00:00:00 2001 From: euxaristia <25621994+euxaristia@users.noreply.github.com> Date: Sat, 1 Aug 2026 03:32:31 -0400 Subject: [PATCH 3/3] docs(agents): require traversal-wide containment for no-follow APIs Final-component-only O_NOFOLLOW is insufficient on Linux and reparse points need platform protections. Align the Security edges guidance with the full-path containment requirement from review. --- AGENTS.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5873b1e5a..db2447834 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,8 +85,10 @@ These classes drive multi-round reviews. Fix them before requesting review: 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 (no-follow or handle-relative APIs, and - platform equivalents for reparse points). On multi-step setup, roll back + 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