docs(ci): record what actually narrows the overlay key branch

Two comments credited the trailing colon with keeping imagePullPolicy and
imagePullSecrets out of the key branch. It does not: the branch requires a
letter before image, which a key beginning with image has nothing to supply, so
neither matches with the colon or without it, even when the value carries a
slash. The colon earns its place elsewhere, as the point the value scan starts
from, and removing it reddens the suffixed-key test rather than the pull-policy
one.

A reader acts on the recorded reason, so a wrong one costs more than none.

Refer to that test by name rather than by ordinal: the number comes from the
runner's output order and moves when anything is inserted above it.

While here, give the pull-policy test a failure message about pull policies:
it read 'a PR-edited package was overlaid', which belongs to a different case.

Assisted-by: LLM
Signed-off-by: IvanHunters <xorokhotnikov@gmail.com>

hack/overlay-main-images.sh

@@ -90,10 +90,14 @@ skip=" packages/core/talos packages/core/installer $(echo "$BUILT_JSON" | tr -d
 # backupstrategy-controller kept serving a release image two months older than
 # the tree in every lane that did not rebuild it (#4257).
 #
-# Two things keep that branch narrow. The key has to END at `image`, so
-# `imagePullPolicy:` and `imagePullSecrets:` still do not match. And the value
-# has to contain a `/`, which a repository path always does and an
-# operator-settable knob named after an image does not: `vddkImage: ""`
+# Two things keep that branch narrow, and neither is the trailing `:`. The
+# `[A-Za-z]+` demands a letter BEFORE `image`, which a key that begins with it
+# has nothing to put there — that, not the colon, is why `imagePullPolicy:` and
+# `imagePullSecrets:` do not match, with the colon or without it. The colon
+# earns its place on the other side: it is where the value scan starts, so
+# `clientImage: "ghcr.io/…"` stops matching if it goes, which is what the test
+# named "a suffixed image key is a ref, not a config change" holds. And the value has to contain a `/`, which a repository path always
+# does and an operator-settable knob named after an image does not: `vddkImage: ""`
 # (core/platform, migration-controller) is configuration the build never
 # stamps, and taking it from the artifact in silence is the opposite of what
 # this script is for. The exact-key branch keeps no such requirement, because

hack/overlay-main-images_test.bats

@@ -240,11 +240,12 @@
   rm -rf "$w"
 }
 
-# imagePullPolicy and imagePullSecrets END in something else, and the classifier
-# accepts a prefix before `image` only up to a colon for exactly that reason. A
-# file differing on one of them differs on CONFIG, so it must keep its committed
-# ref rather than be overlaid: drop the colon from the key branch and this file
-# is overlaid on a policy change, silently replacing the ref the PR asked for.
+# A file differing on imagePullPolicy differs on CONFIG, so it must keep its
+# committed ref rather than be overlaid. What keeps both pull-policy keys out is
+# the letter the key branch demands BEFORE `image`, which a key beginning with
+# `image` has nothing to supply: neither matches with the trailing colon or
+# without it, even when the value carries a slash. The colon belongs to the
+# other side of the branch and is held by "a suffixed image key is a ref".
 @test "a key merely STARTING with image is config, not a ref" {
   root=$(pwd)
   w=$(mktemp -d)
@@ -254,7 +255,7 @@
   ( cd "$w" && "$root/hack/overlay-main-images.sh" main '[]' ) > "$w/out.txt"
   grep -q 'drift (non-ref change) in packages/system/delta/values.yaml' "$w/out.txt"
   if grep -q 'overlay: packages/system/delta/values.yaml' "$w/out.txt"; then
-    echo "FAIL: a PR-edited package was overlaid from the artifact" >&2
+    echo "FAIL: a changed imagePullPolicy was read as a ref and the file overlaid" >&2
     cat "$w/out.txt" >&2
     exit 1
   fi