Correct the build cache wording after review

REPO_POLICIES.md no longer says a Go test phase's image holds every
compiled package; with Go's build cache mounted, those stay in the
mount. The comments in script/lint, script/test, script/cibuild and
script/docker now say that a new CACHEBUST value reruns the RUN steps
only because every stage of the Dockerfile declares ARG CACHEBUST
first, and that a stage without the line is served from cache with no
warning. NEW_REPO_CHECKLIST.md tells a new repository to add the
scripts and every stage's ARG CACHEBUST line in the same commit, in
place of re-vendoring them.

Model: opus-5-5

script/cibuild

@@ -4,6 +4,9 @@
 # the formatter on the host, which a pristine checkout cannot do.
 # A new CACHEBUST value reruns every RUN step, since a cached gate phase
 # is a check that did not run; unlike --no-cache, it keeps Go's build cache.
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
+# first; a stage without that line is served from cache on an unchanged
+# tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/docker

@@ -3,6 +3,9 @@
 # Identical in all repos; the tag comes from script/projectname.
 # A new CACHEBUST value reruns every RUN step, since a cached gate phase
 # is a check that did not run; unlike --no-cache, it keeps Go's build cache.
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
+# first; a stage without that line is served from cache on an unchanged
+# tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/lint

@@ -7,8 +7,10 @@
 # The phase is not the last stage in the file, so it is built only when
 # --target names it. A new CACHEBUST value reruns every RUN step, since
 # a cached lint layer is a lint that did not run; unlike --no-cache, it
-# keeps Go's build cache. --output type=cacheonly writes no image, since
-# nothing uses one.
+# keeps Go's build cache. This relies on every stage of the Dockerfile
+# declaring ARG CACHEBUST first; a stage without that line is served
+# from cache on an unchanged tree, with no warning.
+# --output type=cacheonly writes no image, since nothing uses one.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/test

@@ -3,8 +3,11 @@
 # and this builds that phase alone, on the same terms as script/lint:
 # --target because a phase that is not the last stage is built only when
 # named, and a new CACHEBUST value because a cached test layer is a test
-# that did not run; unlike --no-cache, it keeps Go's build cache.
-# --output type=cacheonly writes no image, since nothing uses one.
+# that did not run; unlike --no-cache, it keeps Go's build cache. This
+# relies on every stage of the Dockerfile declaring ARG CACHEBUST first;
+# a stage without that line is served from cache on an unchanged tree,
+# with no warning. --output type=cacheonly writes no image, since
+# nothing uses one.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"