From 68f351ee8e1873d4fde5c3d903ef2562a9b55611 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Sun, 30 Aug 2026 21:12:10 +0000
Subject: [PATCH 1/2] docs(#6785): add text/template sorted map iteration to Go
 review guidance

The review agent repeatedly flagged `range` over a map inside
`text/template` as non-deterministic output, applying the general Go
heuristic that map iteration order is unspecified. However, Go's
`text/template` package documents that `range` visits map keys of
basic types (string, int, float) in sorted order.

Add a "Template map iteration" subsection to the Go pitfalls section
of `docs/contributing/go-code.md` with a "When reviewing PRs"
directive, following the established pattern of the `Timeout() bool`
and suite-timeout directives already in the file. This prevents the
review agent from re-raising this false positive.

Closes #6785
---
 docs/contributing/go-code.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/contributing/go-code.md b/docs/contributing/go-code.md
index 5411643ad..fa6e55e4a 100644
--- a/docs/contributing/go-code.md
+++ b/docs/contributing/go-code.md
@@ -309,6 +309,21 @@ See [`forge.IsTransient`](../../internal/forge/forge.go) for the canonical examp
 
 **When reviewing PRs:** Flag any `Timeout() bool` interface assertion without a preceding `errors.Is(err, context.DeadlineExceeded)` guard as a medium-severity finding. The fix is to add the context-error check before the `Timeout()` check.
 
+### Template map iteration
+
+Go's `text/template` `range` action visits map keys of basic types (string,
+int, float) in **sorted order** — unlike bare `range` over a map in Go code.
+Do **not** flag `{{ range $k, $v := .SomeMap }}` in templates as
+non-deterministic when the key type is a basic type. See
+[text/template documentation](https://pkg.go.dev/text/template) (search
+"sorted key order").
+
+**When reviewing PRs:** Do not flag `range` over a basic-type-keyed map
+inside a `text/template` as non-deterministic output. The `text/template`
+package guarantees sorted iteration for string, int, and float keys. This
+is a well-documented exception to Go's general rule that map iteration
+order is unspecified.
+
 ## Injectable function variables (test seams)
 
 Package-level variables that hold function values for test overriding must:

From 1cd5370ff93e2f5867318cca13f171e1516ff2b2 Mon Sep 17 00:00:00 2001
From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Sun, 30 Aug 2026 21:34:32 +0000
Subject: [PATCH 2/2] fix: include uint in template map iteration type list
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add uint to the parenthetical list of basic types that receive sorted
iteration in text/template, and update the "When reviewing PRs"
directive to match. The Go text/template documentation specifies
"basic type with a defined order" which includes unsigned integer
types — omitting them could mislead reviewers into flagging
map[uint64]T iteration as non-deterministic.

Addresses review feedback on #6786
---
 docs/contributing/go-code.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/go-code.md b/docs/contributing/go-code.md
index fa6e55e4a..eaae101c5 100644
--- a/docs/contributing/go-code.md
+++ b/docs/contributing/go-code.md
@@ -312,7 +312,7 @@ See [`forge.IsTransient`](../../internal/forge/forge.go) for the canonical examp
 ### Template map iteration
 
 Go's `text/template` `range` action visits map keys of basic types (string,
-int, float) in **sorted order** — unlike bare `range` over a map in Go code.
+int, uint, float) in **sorted order** — unlike bare `range` over a map in Go code.
 Do **not** flag `{{ range $k, $v := .SomeMap }}` in templates as
 non-deterministic when the key type is a basic type. See
 [text/template documentation](https://pkg.go.dev/text/template) (search
@@ -320,7 +320,7 @@ non-deterministic when the key type is a basic type. See
 
 **When reviewing PRs:** Do not flag `range` over a basic-type-keyed map
 inside a `text/template` as non-deterministic output. The `text/template`
-package guarantees sorted iteration for string, int, and float keys. This
+package guarantees sorted iteration for string, int, uint, and float keys. This
 is a well-documented exception to Go's general rule that map iteration
 order is unspecified.