From 25b600a64ecbc55d64cefa2e5302029ed86297cb Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Wed, 19 Aug 2026 15:01:20 +0000
Subject: [PATCH] docs(#3510): add AGENTS.md guidance for review conventions

Add two sections to AGENTS.md to prevent false-positive review
findings:

1. Go file header convention: documents the repo-wide pattern
of placing SPDX license headers before //go:build tags, so
review agents do not flag this as a style violation.

2. Security fix review expectations: instructs review agents
to flag documentation gaps as informational comments rather
than blocking change requests on security-fix PRs.

Both patterns were identified from PR #3489 where review agents
issued miscalibrated findings. This follows the established
pattern of adding AGENTS.md guidance to improve agent review
accuracy (similar to #3503, #3508, #3451, #3389, #3458).

Note: pre-commit could not run in sandbox (network restriction).
The post-script runs it authoritatively.

Closes #3510
---
 AGENTS.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 1d1cbbd6a..5e9e8a8f7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,6 +48,24 @@ Tests use build tags with different timeouts:
   compatibility (e.g., `quay.io/enterprise-contract/ec-cli`, Tekton parameter names) must be
   preserved as-is.
 
+## Go file header convention
+
+Go source files in this repository place the SPDX license header comment
+before the `//go:build` tag. This is the established convention across
+all Go files — do not flag build tag placement as a style violation.
+
+## Security fix review expectations
+
+Security bug fixes and vulnerability mitigations (PRs labeled `bug` +
+`Possible security concern`, or referencing security-related Jira tickets
+like EC-1842) should not be blocked on documentation updates.
+
+Documentation gaps in files like `THREAT_MODEL.md`, `DESIGN.md`, and
+user-facing docs should be flagged as informational comments (not
+blocking change requests) when the PR's primary purpose is a security
+fix. Authors are expected to create follow-up issues or PRs for
+documentation updates after the security fix is merged.
+
 ## CGO and DNS Resolution
 
 Binaries are built with `CGO_ENABLED=0` for portability. This uses Go's native DNS resolver,