Cache-bust the make check layer via CHECK_EPOCH (closes #23)
All checks were successful
check / check (push) Successful in 56s

script/cibuild was a bare `docker build .`, and the Dockerfile did
`COPY . .` then `RUN make check`. COPY is keyed on content, so on an
unchanged tree Docker served the check layer from cache: the checks
never executed, no Hugo or prettier output appeared, and the build still
exited 0. A gate that reports success without running is worse than no
gate, because it is trusted -- three separate reviewers in this repo
have been fooled by it.

The Dockerfile now declares `ARG CHECK_EPOCH` immediately below
`COPY . .`, guards it, and expands it into the check command:

    ARG CHECK_EPOCH
    RUN [ -n "$CHECK_EPOCH" ] || exit 1
    RUN echo "check epoch: ${CHECK_EPOCH}" && make check

script/cibuild and script/docker both generate the value identically and
pass it. Every element is load-bearing:

- No default value. A default is a constant, and a constant is a stable
  cache key -- the defect unchanged.
- Placed below `COPY . .`. Everything above keeps caching, so the
  script/bootstrap layer, which compiles Hugo from source, is not
  rebuilt. Whole-build `--no-cache` would have discarded it and blown
  the five-minute budget for no benefit.
- The guard. An unset ARG is the empty string, which is also a stable
  cache key, so without it a bare `docker build .` still collects the
  false green. Failed steps are never cached, so it fails on every such
  invocation rather than only the first. This is why script/docker had
  to be updated too: the guard makes passing the argument mandatory for
  every entrypoint that builds the image.
- The value expanded into the RUN. Hardening rather than the fix: the
  bare unreferenced-ARG form does work, but expansion makes the cache
  miss contractual rather than dependent on BuildKit's handling of an
  unreferenced ARG, and puts the epoch in the build log. The guard also
  references the value, so there are two independent invalidation
  points, not one.
- `epoch="$(date +%s%N)$$"` on its own line rather than inlined into the
  argument list. A command substitution that fails inside an argument
  does not trip `set -e`, so the inline form would quietly pass an empty
  string and restore the cached false green. `%N` keeps concurrent
  invocations distinct; `$$` covers busybox date, which drops `%N`
  silently and still exits 0.

ARG is stage-scoped and must be redeclared in every stage that runs
checks. This image is single-stage, so one declaration is complete.

This is the shape settled upstream in the prompts repo, where it has not
merged to main yet, so it may need re-syncing later.

Verified: two consecutive script/cibuild runs on an unchanged tree both
executed the checks (two Hugo builds and the prettier line in each,
15s then 6s) with `RUN script/bootstrap` and `COPY . .` both CACHED in
the second -- the validity control that rules out a cache eviction
between them. A constant-epoch counterfactual restored the cached false
green, confirming the varying value is what does the work. A bare
`docker build .` now fails on the guard, and fails again on immediate
repeat. A planted prettier failure failed the build with exit 1. `make
docker` and `make check` both pass.
This commit is contained in:
2026-08-09 15:51:09 +00:00
parent 8034fd8192
commit 223c520110
5 changed files with 71 additions and 5 deletions

16
TODO.md
View File

@@ -27,6 +27,22 @@ Update `README.md` accordingly.
# Completed Steps
- 2026-08-09: stopped `script/cibuild` reporting a green it never earned (closes
#23). `COPY . .` is keyed on content, so on an unchanged tree Docker served
`RUN make check` from cache: the checks never executed and the build still
exited 0. Three separate reviewers had already been fooled by it here. The
`Dockerfile` now declares `ARG CHECK_EPOCH` below `COPY . .` with no default
(a default is a constant, and a constant is a stable cache key), guards it
with `RUN [ -n "$CHECK_EPOCH" ] || exit 1`, and expands it into the check
command; `script/cibuild` and `script/docker` both pass
`epoch="$(date +%s%N)$$"` — assigned on its own line, because a failing
command substitution inside an argument does not trip `set -e`, and with `$$`
because busybox `date` drops `%N` silently. This is the canonical shape
settled upstream in `prompts` #26, which has not merged there yet, so it may
need re-syncing. Verified with two consecutive runs on an unchanged tree that
both executed the checks while `RUN script/bootstrap` stayed `CACHED`, a
constant-epoch counterfactual that restored the false green, and a planted
prettier failure that failed the build
- 2026-08-09: disabled the unused `taxonomy` and `term` page kinds in
`hugo.toml` (closes #13). Hugo enables the `tags` and `categories` taxonomies
by default; this single-page site has no taxonomy terms and no taxonomy