From 886afdc896da9e865da01a993849e864b8fda5b1 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Thu, 3 Sep 2026 15:25:43 +0000
Subject: [PATCH] docs(#3542): add Go version consistency guidance to AGENTS.md

Add a new "Go Version Consistency" section listing the seven files
that must declare the same Go version (go.mod files, .tool-versions,
Dockerfile, Dockerfile.dist) and reviewer guidance for detecting
mismatches on Go version bump PRs. This enables the review agent to
flag cross-file version inconsistencies that can cause build failures
when GOTOOLCHAIN=local is set.

Motivated by PR #3538 where go.mod was bumped to a different version
than the Dockerfile base images. Complements #3360 (Renovate atomic
updates) by providing review-time detection for manual bumps.

Note: pre-commit hooks were not run. pre-commit could not complete
(infrastructure failure fetching remote hook repos). The only
configured hook (check-commit-message) checks commit messages, not
file content.

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

diff --git a/AGENTS.md b/AGENTS.md
index 5e9e8a8f7..f72f0a109 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 Version Consistency
+
+These files must all declare the same Go version:
+
+1. `go.mod` (line 3: `go X.Y.Z`)
+2. `acceptance/go.mod` (`go X.Y.Z`)
+3. `tools/go.mod` (`go X.Y.Z`)
+4. `tools/kubectl/go.mod` (`go X.Y.Z`)
+5. `.tool-versions` (`golang X.Y.Z`)
+6. `Dockerfile` (`FROM golang:X.Y.Z@sha256:...`)
+7. `Dockerfile.dist` (`FROM go-toolset:X.Y.Z@sha256:...`)
+
+**Reviewer guidance:** When any PR modifies a Go version in one of these files,
+verify all seven files declare the same version. Mismatches between `go.mod` and
+Dockerfile base images can cause build failures when `GOTOOLCHAIN=local` is set.
+Dockerfile image tags also require updated `@sha256:` digests — a version bump
+without a corresponding digest update will pull a stale or incorrect image.
+
 ## Go file header convention
 
 Go source files in this repository place the SPDX license header comment