Make script/cibuild unable to report an unearned green (closes #85)

script/cibuild was a bare `docker build .` with no cache control. The
Dockerfile does `COPY . .` and then `RUN make fmt-check` / `RUN make
lint` in the lint stage and `COPY . .` / `RUN make test` in the builder
stage. On an unchanged tree Docker served those RUN layers from cache,
so the checks never executed, and the build still exited 0 -- the exit
code, which is the one signal automation trusts, was wrong, and wrong
in the direction that matters: the longer a branch sits unchanged, the
more likely its "verification" is a replay, which is exactly its state
just before a merge.

Reproduced on this branch's base at 3bcdbcf. A changed-tree run took
162132ms and produced 14 `ok` lines and `0 issues.`; the immediately
following run, with nothing touched, took 221ms and produced 0 `ok`
lines and no `0 issues.` line at all, with 19 CACHED layers including
`RUN make fmt-check`, `RUN make lint`, and `RUN make test`. Both
exited 0.

The fix matches the upstream one in sneak/prompts #26 rather than
inventing a local variant: an `ARG CHECK_EPOCH` declared immediately
above the check RUNs, with script/cibuild passing a fresh
`--build-arg CHECK_EPOCH="$(date +%s)"` on every invocation. ARG scope
is per-stage in Docker, so the lint stage and the builder stage each
declare their own; covering only one would leave half the gate fake.

Placement is the substance of the change. The ARG sits below the
`apk add`, `COPY go.mod go.sum`, and `go mod download` layers in both
stages, so only the check layers are invalidated: earlier and every
build would be cold, later and the checks would stay cached. Confirmed
by measurement -- on a post-fix build every `apk add` and `go mod
download` layer is still reported CACHED, and a changed-tree build went
from 162132ms to 176221ms rather than to a cold build's 242727ms.

Verified against the original failure mode, not by trusting an exit
code: two back-to-back script/cibuild runs on an unchanged tree now
take 166745ms and 174025ms, each with 14 `ok` lines and `0 issues.`,
and neither reports CACHED on any of the three check layers.
Cross-checked host-side with `GOFLAGS=-count=1 make check`: exit 0, 14
`ok` lines, `0 issues.`, with no `parallel golangci-lint is running`
and no file paths from outside this worktree, so the lint result is a
real one and not a void or contaminated run.

.golangci.yml is unchanged (sha256 021cc83f4e6f...643346bcb), as is the
lint-stage FROM line that is the single source of truth for the linter
version, script/lint's pinned-image logic, and
.gitea/workflows/check.yml, whose only step is script/cibuild.

Dockerfile

@@ -21,31 +21,14 @@ COPY . .
 
 # Run formatting check and linter.
 #
-# CHECK_EPOCH must stay immediately above these RUNs. These layers are
+# CHECK_EPOCH must stay immediately above these RUNs. script/cibuild
-# keyed on its value, so they are cache-eligible only for a value
+# passes a fresh value on every build so the check layers can never be
-# already built against this same tree. script/cibuild passes a fresh
+# served from the layer cache: without it an unchanged tree replays
-# value on every invocation, which is what makes its green mean the
+# cached layers, the checks never execute, and the build still exits 0:
-# checks really executed.
+# a green nothing earned. ARG scope is per-stage, so the builder
-#
+# stage declares its own. Everything above this line (apk, go.mod,
-# The guarantee is conditional on that fresh value, not absolute. A
+# `go mod download`) is deliberately outside the busted range and keeps
-# build that omits --build-arg -- a bare `docker build .` -- gets an
+# caching.
-# empty CHECK_EPOCH, and an empty string is a constant: the first such
-# build runs the checks, and every one after it on an unchanged tree
-# replays these layers from cache, never executing a check and still
-# exiting 0, a green nothing earned. Gate through script/cibuild.
-# Making the missing-arg case fail loudly instead is tracked in #91.
-#
-# CHECK_EPOCH is deliberately not referenced by the commands below: a
-# declared-but-unreferenced ARG does enter BuildKit's cache key, which
-# is measured on this host rather than assumed (PR #89). Upstream
-# sneak/prompts #26 prefers expanding the value into the command so
-# that the miss is contractual rather than dependent on that behavior
-# staying as it is; adopting that here is tracked in #91. Do not delete
-# this ARG as dead code -- the gate depends on it.
-#
-# ARG scope is per-stage, so the builder stage declares its own.
-# Everything above this line (apk, go.mod, `go mod download`) is
-# deliberately outside the busted range and keeps caching.
 ARG CHECK_EPOCH
 RUN make fmt-check
 RUN make lint
@@ -71,10 +54,9 @@ RUN go mod download
 # Copy source code
 COPY . .
 
-# Run tests. See the CHECK_EPOCH comment in the lint stage, including
+# Run tests. See the CHECK_EPOCH comment in the lint stage; ARG scope
-# the conditions the guarantee depends on; ARG scope is per-stage, so
+# is per-stage, so this stage needs its own declaration, and it must
-# this stage needs its own declaration, and it must stay immediately
+# stay immediately above the check RUN.
-# above the check RUN.
 ARG CHECK_EPOCH
 RUN make test
 

README.md

@@ -617,24 +617,16 @@ them. We provide:
   lint findings.
 * `script/docker` — build the Docker image tagged via
   `script/projectname`
-* `script/cibuild` — CI entrypoint: `docker build` (the `Dockerfile`
+* `script/cibuild` — CI entrypoint: `docker build` (the Dockerfile runs
-  runs `make fmt-check` and `make lint` in its lint stage and `make
+  the checks). This is the full CI-equivalent gate — it runs the checks
-  test` in its builder stage). This is the full CI-equivalent gate — it
+  in the same containers CI does, from a clean copy of the tree, so it
-  runs the checks in the same containers CI does, from a clean copy of
+  also catches anything that depends on host state. It passes a fresh
-  the tree, so it also catches anything that depends on host state. It
+  `--build-arg CHECK_EPOCH`, which the `Dockerfile` declares
-  passes a fresh `--build-arg CHECK_EPOCH`, which the `Dockerfile`
+  immediately above the check `RUN`s in both the lint and builder
-  declares immediately above the check `RUN`s in both stages. Those
+  stages, so those layers can never be served from the Docker layer
-  layers are keyed on that value, so a new value re-runs them even on a
+  cache: a green from this script always means the checks actually
-  byte-identical tree, and a green from this script means the checks
   executed. Dependency and module layers sit above the `ARG` and still
   cache, so a build is not cold.
-
-  That guarantee is conditional on the fresh value, so **run the gate
-  through `script/cibuild`, not by invoking `docker build` yourself**. A
-  bare `docker build .` supplies no `CHECK_EPOCH`; the empty default is
-  a constant, so the second and every later build on an unchanged tree
-  serves all three check layers from cache, executes nothing, and still
-  exits 0. Issue #91 tracks making that case fail loudly instead.
 * `script/precommit` — pre-commit gate: `go mod tidy` + `go fmt` (must
   not change files), then `script/check`
 * `script/install-precommit` — install the git pre-commit hook that

TODO.md

@@ -22,27 +22,25 @@ or delete the branch.
 - 2026-08-09: Stopped `script/cibuild` from reporting a green it did
   not earn (issue #85). A bare `docker build .` let Docker serve the
   check layers from the layer cache whenever the tree had not changed:
-  the checks never executed and the build still exited 0. The fix is an
+  the checks never executed and the build still exited 0. Reproduced on
-  `ARG CHECK_EPOCH` declared immediately above the check `RUN`s in both
+  this branch's base — a genuine changed-tree run took 162s with 14
-  the lint stage and the builder stage (`ARG` scope is per-stage, so
+  `ok` lines, and the immediately following unchanged-tree run took
-  each declares its own), with `script/cibuild` assigning
+  221ms with 0 `ok` lines, 19 cached layers, and the same exit 0, with
-  `epoch="$(date +%s)"` and passing `--build-arg CHECK_EPOCH="$epoch"`.
+  `RUN make fmt-check`, `RUN make lint`, and `RUN make test` all
-  The assignment is separate on purpose: under `set -eu` a command
+  reported `CACHED`. The fix matches the upstream one in
-  substitution that fails inside an argument does not abort the script,
+  `sneak/prompts` #26: an `ARG CHECK_EPOCH` declared immediately above
-  which would leave an empty constant `CHECK_EPOCH` and restore the
+  the check `RUN`s in both the lint stage and the builder stage (`ARG`
-  very false green being fixed. Placement is the rest of the point —
+  scope is per-stage, so each declares its own), with `script/cibuild`
-  the `ARG` sits below the `apk add`, `COPY go.mod go.sum`, and `go mod
+  passing `--build-arg CHECK_EPOCH="$(date +%s)"`. Placement is the
-  download` layers, so only the checks are invalidated and the
+  whole point — the `ARG` sits below the `apk add`, `COPY go.mod
-  dependency layers still cache. The guarantee is conditional on a
+  go.sum`, and `go mod download` layers, so only the checks are
-  fresh value rather than absolute: a bare `docker build .` gets an
+  invalidated and the dependency layers still cache. Verified by
-  empty `CHECK_EPOCH` and can still serve the check layers from cache,
+  re-running the reproduction: two back-to-back runs on an unchanged
-  which `README.md` and the `Dockerfile` now say plainly, with issue
+  tree took 167s and 174s, each with 14 `ok` lines and `0 issues.`, no
-  #91 tracking the upstream hardening (expanded `ARG` form, unset
+  `CACHED` on any of the three check layers, while every `apk add` and
-  guard, per-invocation epoch, `script/docker`) that would close it.
+  `go mod download` layer stayed `CACHED` in both. A changed-tree build
-  Verified by re-running the reproduction plus the withheld-`--build-arg`
+  went from 162s to 176s, so this is not a cold build. `.golangci.yml`,
-  counterfactual; the measurements are recorded once, in the PR #89
+  the lint-stage `FROM` line and its digest, `script/lint`, and
-  verification comment, rather than restated here. `.golangci.yml`, the
-  lint-stage `FROM` line and its digest, `script/lint`, and
   `.gitea/workflows/check.yml` are all untouched.
 - 2026-08-09: Corrected the `Vaultik.UI` doc comment (issue #84). It
   claimed the cli layer replaces the writer with a discarding one in

script/cibuild

@@ -1,9 +1,6 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Dockerfile does not run
+# script/cibuild: run the CI build. The Dockerfile runs script/check
-# script/check; it runs `make fmt-check` and `make lint` in its lint
+# (via make check), so a successful build implies all checks pass.
-# stage and `make test` in its builder stage. A successful build
-# implies those three passed, provided they actually ran -- which is
-# what the CHECK_EPOCH below is for.
 # Generic: needs no adaptation. The Gitea workflow runs this on push.
 set -eu
 
@@ -11,22 +8,12 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    # The Dockerfile's check layers are keyed on CHECK_EPOCH, so a
+    # CHECK_EPOCH changes on every invocation, which invalidates the
-    # fresh value here is what forces them to re-run: without it an
+    # Dockerfile layers that run the checks. Without it an unchanged
-    # unchanged tree replays them from cache, the checks never execute,
+    # tree replays those layers from cache, the checks never execute,
     # and the build still exits 0. The ARG sits immediately above the
     # check RUNs, so dependency and module layers still cache.
-    #
+    docker build --build-arg CHECK_EPOCH="$(date +%s)" .
-    # Assign the epoch on its own line rather than inline in the
-    # argument. Under `set -eu` a command substitution that fails
-    # inside an argument does NOT abort the script: CHECK_EPOCH would
-    # become an empty string, an empty string is a constant, and a
-    # constant CHECK_EPOCH is exactly the cached-check false green this
-    # script exists to prevent -- so the guard would disarm itself and
-    # still exit 0. As a bare assignment, `set -e` catches a failing
-    # `date` and no build starts.
-    epoch="$(date +%s)"
-    docker build --build-arg CHECK_EPOCH="$epoch" .
 }
 
 main "$@"