From 7f6222879d46ba02a8da13c44d9d127701a80ca6 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Wed, 19 Aug 2026 09:09:04 +0000
Subject: [PATCH] docs(#3508): add hack/ directory conventions to AGENTS.md

Document that scripts in hack/ are attended developer utilities
targeting RHEL 8+ / Fedora (Bash 4.4+), not production code.
Add reviewer guidance to suppress low-severity robustness and
portability findings (e.g., Bash <4.4 compatibility, regex dot
escaping, broad git staging) and focus on correctness, data loss,
git safety, and security concerns.

This gives review agents the context signal needed to calibrate
severity for hack/ scripts, preventing repeated low-value findings
like those seen on PR #3430.

Closes #3508
---
 AGENTS.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 1d1cbbd6a..b63bf910d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,6 +48,35 @@ Tests use build tags with different timeouts:
   compatibility (e.g., `quay.io/enterprise-contract/ec-cli`, Tekton parameter names) must be
   preserved as-is.
 
+## hack/ Directory Conventions
+
+Scripts in `hack/` are **attended developer utilities** intended for the development team, not
+production runtime code. They automate tasks like dependency bumps, release branch management,
+environment setup, and demo workflows. Developers run them interactively at a terminal.
+
+**Target environment:** RHEL 8+ / Fedora workstations (Bash 4.4+ guaranteed). Backward
+compatibility with older Bash versions (e.g., Bash 3.x on macOS default shell) is explicitly
+not required.
+
+**Accepted trade-offs for attended usage:**
+
+- Unescaped dots in sed/grep patterns operating on controlled, predictable inputs
+- Hardcoded branch lists that change infrequently and are updated manually
+- `git add -A` or broad staging when the script controls the entire working tree context
+- Reliance on modern Bash features (associative arrays, `readarray`, `${var,,}`, etc.)
+
+**Reviewer guidance:** Robustness and portability findings at Low severity should be suppressed
+for `hack/` scripts unless they affect correctness in the target environment (RHEL 8+ / Fedora).
+Focus review on:
+
+- **Logic errors** that produce wrong results
+- **Data loss risks** (e.g., unsafe `rm -rf`, force-pushing to protected branches)
+- **Git safety issues** (e.g., destructive operations without confirmation)
+- **Security concerns** (e.g., credential handling, injection vulnerabilities)
+
+Do not flag: Bash <4.4 compatibility, regex dot escaping on controlled inputs, broad `git add`
+in scripts that manage their own working tree, or hardcoded values that are intentionally static.
+
 ## CGO and DNS Resolution
 
 Binaries are built with `CGO_ENABLED=0` for portability. This uses Go's native DNS resolver,