Make the pinned golangci-lint actually reach the host (closes #28)

REPO_POLICIES.md now carries the canonical script/bootstrap snippet for Go
repos alongside the .golangci.yml bullet, where the pinned linter version
already lives.

The guard it replaces, `if missing golangci-lint; then go install ...; fi`,
tests PATH presence and never version, so on any already-provisioned machine
the pin is inert and a version bump is a no-op. The Dockerfile installs
unconditionally into a clean image, so CI and local then disagree about what
the linter is: a local `make check` green while `make docker` rejects the same
commit, and a container run surfacing findings the host run cannot see.

Comparing versions alone is not enough. `go install` writes to GOBIN (or
GOPATH/bin) while callers resolve through PATH, so a shadowing binary earlier
in PATH lets the install succeed and change nothing a caller ever sees, while
bootstrap prints success. The canonical form therefore compares the installed
version against the pin, re-resolves through PATH after installing and asserts
the pin, failing non-zero and naming the shadowing path when it does not, and
treats any unparseable --version output as a mismatch so the failure direction
is a redundant install rather than a skipped one.

The policy text states each of those as a requirement rather than leaving them
implicit in the code, records why the commit-pinned `go install` ref satisfies
the hash-pinning rule (a commit hash is not a mutable tag, and the go command
verifies the module against the checksum database), and requires that any
change to this logic be validated with a negative control run against a
shadowing binary, because a control without one passes against the naive
implementation too.

The node and yarn handling described earlier in the document is untouched.

Verified by extracting the snippet to a scratch harness with fake `go` and both
fake and real golangci-lint binaries: shadowing fails loudly and names the
path while the naive compare-then-install form reports success with the stale
2.7.2 still resolved; a wrong version at the install target is replaced;
garbage, empty and non-zero --version output all reinstall; the matching case
runs zero installs. The block in the document is byte-identical to the one
exercised.

Dockerfile

@@ -12,4 +12,17 @@ COPY package.json yarn.lock ./
 RUN script/bootstrap
 
 COPY . .
-RUN make check
+
+# CHECK_EPOCH is a per-invocation nonce supplied by script/cibuild and
+# script/docker. Without it an unchanged tree serves this layer from
+# cache and the build reports a green it never ran. ARG is stage-scoped,
+# so it must be redeclared in every stage that runs checks. The guard
+# makes a bare `docker build .` fail loudly instead of silently reusing
+# the empty (and therefore stable) cache key. Expand the value into the
+# command so the cache miss does not depend on BuildKit's handling of an
+# unreferenced ARG. Both the guard and the check RUN reference the value,
+# so both are value-keyed: there are two independent invalidation points
+# here, not one. Keep both.
+ARG CHECK_EPOCH
+RUN [ -n "$CHECK_EPOCH" ] || exit 1
+RUN echo "check epoch: ${CHECK_EPOCH}" && make check

README.md

@@ -123,9 +123,13 @@ alpine. We provide:
 - `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
   extension)
 - `script/docker` — build the Docker image, tagged via `script/projectname`
-  (byte-identical across repos)
-- `script/cibuild` — cd to the repo root and `docker build .` (what CI runs; the
-  image build runs `script/check`)
+  (byte-identical across repos); passes the same `CHECK_EPOCH` nonce as
+  `script/cibuild`
+- `script/cibuild` — cd to the repo root, assign `epoch="$(date +%s%N)$$"`, then
+  `docker build --build-arg CHECK_EPOCH="$epoch" .` (what CI runs; the image
+  build runs `script/check`, and the per-invocation `CHECK_EPOCH` nonce is what
+  stops Docker serving that check from cache on an unchanged tree — a bare
+  `docker build .` fails closed on purpose)
 - `script/precommit` — run by the git pre-commit hook (our own extension); calls
   `script/check`
 - `script/install-precommit` — installs the git pre-commit hook (our own

TODO.md

@@ -21,9 +21,23 @@ fmt-check, and commit.
 
 # Completed Steps
 
-- 2026-08-10: Added `-count=1` to both `go test` invocations in the canonical Go
-  `make test` example in `REPO_POLICIES.md`, so the target cannot report a
-  cached pass it did not earn.
+- 2026-08-09: Made the pinned golangci-lint actually propagate: REPO_POLICIES.md
+  now carries the canonical `script/bootstrap` snippet for Go repos, which
+  installs when the installed version does not match the pin (the old
+  `if missing` guard tested PATH presence only, so pins were inert on any
+  provisioned machine and CI silently disagreed with local) and then re-resolves
+  the binary through `PATH` and fails loudly, naming the shadowing path, when
+  the install did not take effect — the failure mode the naive
+  compare-then-install fix leaves behind while reporting success.
+- 2026-08-09: Fixed the false green in the canonical CI gate: `script/cibuild`
+  and `script/docker` now pass a per-invocation `CHECK_EPOCH` nonce, and the
+  `Dockerfile` (plus the Go multistage template in REPO_POLICIES.md, in both its
+  lint and builder stages) declares `ARG CHECK_EPOCH` with a guard that makes a
+  bare `docker build .` fail closed. Corrected the org-canonical text that
+  asserted a successful build implies all checks pass, across every document
+  carrying it: `REPO_POLICIES.md`, both repo checklists (which still told agents
+  to write the pre-fix `script/cibuild` and ended on an acceptance item the
+  guard makes unsatisfiable), and the Go styleguide.
 - 2026-08-07: Set the canonical `.golangci.yml` to the org-standard v2-schema
   config already deployed byte-identical across the org's Go repos (settings
   under `linters.settings` so thresholds like lll/funlen/cyclop/dupl actually

prompts/CODE_STYLEGUIDE_GO.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — Go
-last_modified: 2026-03-18
+last_modified: 2026-08-09
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -101,9 +101,16 @@ last_modified: 2026-03-18
     `golangci-lint`.
 
 1.  Write a `Dockerfile` for every repo, even if it only runs the tests and
-    linting. `docker build .` should always make sure that the code is in an
-    able-to-be-compiled state, linted, and any tests run. The Docker build
-    should fail if linting doesn't pass.
+    linting. `script/cibuild` and `script/docker` should always make sure that
+    the code is in an able-to-be-compiled state, linted, and any tests run, and
+    the build should fail if linting doesn't pass. That guarantee holds only
+    because those scripts pass a per-invocation `CHECK_EPOCH` build arg that
+    busts the check layers out of the Docker cache; without it an unchanged tree
+    serves those layers from cache and the build reports a green it never ran. A
+    bare `docker build .` fails closed by design, on the `[ -n "$CHECK_EPOCH" ]`
+    guard — always go through `script/cibuild` or `script/docker`. See
+    [Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
+    for the canonical form.
 
 1.  Every repo must have a `Makefile`. See
     [Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-07-06
+last_modified: 2026-08-09
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -29,10 +29,15 @@ with your task.
       if missing
 - [ ] `.editorconfig` exists — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
-- [ ] `Dockerfile` and `.dockerignore` exist; Dockerfile runs `make check` as a
-      build step — fetch `.dockerignore` from
-      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
-- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `docker build .` on
+- [ ] `Dockerfile` and `.dockerignore` exist (fetch `.dockerignore` from
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`);
+      Dockerfile runs `make check` as a build step, and every stage containing a
+      check-running `RUN` declares `ARG CHECK_EPOCH` with the
+      `RUN [ -n "$CHECK_EPOCH" ] || exit 1` guard immediately below it — see the
+      `CHECK_EPOCH` rule in `REPO_POLICIES.md`. Without them the check layer is
+      served from cache on an unchanged tree and the build reports a green it
+      never ran.
+- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on
       push — reference
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
 - [ ] Language-specific config:
@@ -104,5 +109,6 @@ with your task.
 # Final
 
 - [ ] `make check` passes
-- [ ] `docker build` succeeds
+- [ ] `script/cibuild` succeeds (a bare `docker build .` fails closed by design,
+      on the `CHECK_EPOCH` guard)
 - [ ] Commit and merge fixes before starting your actual task

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-07-06
+last_modified: 2026-08-09
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -52,7 +52,12 @@ Template files can be fetched from:
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
 - [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
-    - All Dockerfiles must run `make check` as a build step
+    - All Dockerfiles must run `make check` as a build step, and every stage
+      containing a check-running `RUN` must declare `ARG CHECK_EPOCH` with the
+      `RUN [ -n "$CHECK_EPOCH" ] || exit 1` guard immediately below it — see the
+      `CHECK_EPOCH` rule in `REPO_POLICIES.md`. Without them the check layer is
+      served from cache on an unchanged tree and the build reports a green it
+      never ran.
     - Server: also builds and runs the application
     - Non-server: brings up dev environment and runs `make check`
     - Image pinned by sha256 hash with version/date comment
@@ -90,8 +95,14 @@ are thin shims calling them. Model scripts:
 - [ ] `script/projectname` — outputs the project name (used by `script/docker`
       for the image tag)
 - [ ] `script/docker` / `make docker` — builds Docker image, tagged via
-      `script/projectname` (byte-identical across repos)
-- [ ] `script/cibuild` — cd to repo root, `docker build .` (what CI runs)
+      `script/projectname` (byte-identical across repos); assigns
+      `epoch="$(date +%s%N)$$"` on its own line and passes
+      `--build-arg CHECK_EPOCH="$epoch"`
+- [ ] `script/cibuild` — cd to repo root, assign `epoch="$(date +%s%N)$$"` on
+      its own line, then run `docker build --build-arg CHECK_EPOCH="$epoch" .`
+      (what CI runs). The build arg is mandatory: see the `CHECK_EPOCH` rule in
+      `REPO_POLICIES.md` for why each element is load-bearing. A bare
+      `docker build .` fails closed by design.
 - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check`
 - [ ] `script/install-precommit` — installs the pre-commit hook that runs
       `script/precommit`

prompts/REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-08-10
+last_modified: 2026-08-09
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -60,17 +60,19 @@ style conventions are in separate documents:
   prerequisite since nvm requires bash. yarn is then pinned via
   `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
   always exact versions. `script/cibuild` runs the CI build: it changes to the
-  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
-  scripts are our own extensions to the standard: `script/check` runs
-  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
-  what the git pre-commit hook runs, and it calls `script/check`;
-  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
-  target shims to it); and `script/projectname` (literally that filename) simply
-  outputs the project's name. Scripts that need the name call
-  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
-  so those scripts stay byte-identical across all repos. Repo-type-specific
-  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
-  `script/precommit`, not in the hook itself. Model scripts are at
+  repo root and runs `docker build --build-arg CHECK_EPOCH="$epoch" .`, where
+  `epoch` is a per-invocation nonce (see the `CHECK_EPOCH` rule below); the
+  Gitea workflow calls it. Four further scripts are our own extensions to the
+  standard: `script/check` runs `script/test`, `script/lint`, and
+  `script/fmt-check`; `script/precommit` is what the git pre-commit hook runs,
+  and it calls `script/check`; `script/install-precommit` installs the git
+  pre-commit hook (the `make hooks` target shims to it); and
+  `script/projectname` (literally that filename) simply outputs the project's
+  name. Scripts that need the name call `script/projectname` — e.g.
+  `script/docker` assembles its image tag from it — so those scripts stay
+  byte-identical across all repos. Repo-type-specific pre-commit extras (e.g.
+  `go mod tidy` verification in Go repos) belong in `script/precommit`, not in
+  the hook itself. Model scripts are at
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
   must document the provided scripts in an **Entrypoints** section (see the
   README requirements below).
@@ -90,14 +92,70 @@ style conventions are in separate documents:
   reading the Makefile.
 
 - Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
-  as a build step so the build fails if the branch is not green. For non-server
-  repos, the Dockerfile should bring up a development environment and run
-  `make check`. For server repos, `make check` should run as an early build
-  stage before the final image is assembled. Dockerfiles install development
-  prerequisites by running `script/bootstrap` rather than duplicating installs
-  inline; COPY `script/` and the dependency manifests (`package.json` +
-  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
-  layer stays cached until dependencies change.
+  as a build step so the build fails if the branch is not green — which requires
+  `ARG CHECK_EPOCH` and its guard in every stage containing a check-running
+  `RUN`, per the `CHECK_EPOCH` rule below. Without them a Dockerfile satisfies
+  this criterion while its check layers are served from cache, so the build
+  cannot fail on a branch that is not green. For non-server repos, the
+  Dockerfile should bring up a development environment and run `make check`. For
+  server repos, `make check` should run as an early build stage before the final
+  image is assembled. Dockerfiles install development prerequisites by running
+  `script/bootstrap` rather than duplicating installs inline; COPY `script/` and
+  the dependency manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`,
+  etc.) before running it so the bootstrap layer stays cached until dependencies
+  change.
+
+- **Every check-running `RUN` must be cache-busted with `CHECK_EPOCH`.** Docker
+  invalidates a `COPY` layer only when the copied content changes, so on an
+  unchanged tree the `RUN make check` layer is served from cache, the suite
+  never runs, and the build still exits 0. A sub-second `docker build` reporting
+  success is a cache hit, not a result. The canonical form, in **every** stage
+  containing a check-running `RUN`:
+
+    ```dockerfile
+    ARG CHECK_EPOCH
+    RUN [ -n "$CHECK_EPOCH" ] || exit 1
+    RUN echo "check epoch: ${CHECK_EPOCH}" && make check
+    ```
+
+    and in both `script/cibuild` and `script/docker`:
+
+    ```sh
+    epoch="$(date +%s%N)$$"
+    docker build --build-arg CHECK_EPOCH="$epoch" .
+    ```
+
+    All four elements are load-bearing; none is optional, and each guards a
+    failure mode that otherwise fails green:
+    - `ARG` is stage-scoped, so a single declaration leaves the other check
+      stages frozen while the fix reviews as complete. Declare it in every stage
+      that runs checks, immediately above the first such `RUN`.
+    - Expand the value into the command. This makes the cache miss contractual
+      rather than dependent on BuildKit's handling of an unreferenced `ARG`, and
+      it puts the epoch in the build log. The guard is itself value-keyed, for
+      the same reason: it references `$CHECK_EPOCH`, so BuildKit renders the
+      epoch into that layer's description (rendered as
+      `RUN [ -n "<epoch>" ] || exit 1`) and re-runs it whenever the value
+      changes. Each stage therefore has two independent invalidation points, and
+      the guard always precedes the check `RUN`. Keep both: the expansion is
+      defence in depth, and it is what makes the epoch visible in the build
+      output.
+    - The `[ -n ... ]` guard is required: an unset `ARG` is empty, and empty is
+      a stable cache key, so without it a bare `docker build .` still produces
+      the false green. Failed steps are never cached, so the guard fails on
+      every such invocation, loudly. A bare `docker build .` failing is by
+      design.
+    - Assign `epoch=` on its own line, never inline in the `--build-arg`
+      argument: a failing command substitution inside an argument does not trip
+      `set -e`, so the inline form silently degrades to an empty constant. The
+      `$$` suffix is required because busybox `date` drops `%N` and exits 0, so
+      on an alpine host the epoch would degrade to second granularity and
+      concurrent invocations would collide.
+
+    This invalidates the check layers and everything after them while leaving
+    `go mod download`, `script/bootstrap`, and the pinned toolchain install
+    cached, so it does not push against the five-minute Docker build ceiling.
+    Blanket `--no-cache` also works but is wasteful and can blow that ceiling.
 
 - **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
   repos use a multistage build where linting runs in an independent stage based
@@ -119,7 +177,9 @@ style conventions are in separate documents:
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make fmt-check
+    ARG CHECK_EPOCH
+    RUN [ -n "$CHECK_EPOCH" ] || exit 1
+    RUN echo "check epoch: ${CHECK_EPOCH}" && make fmt-check
     RUN make lint
 
     # Build stage
@@ -133,7 +193,9 @@ style conventions are in separate documents:
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make test
+    ARG CHECK_EPOCH
+    RUN [ -n "$CHECK_EPOCH" ] || exit 1
+    RUN echo "check epoch: ${CHECK_EPOCH}" && make test
 
     ARG VERSION=dev
     RUN CGO_ENABLED=0 go build -trimpath \
@@ -154,6 +216,16 @@ style conventions are in separate documents:
       a stage dependency. BuildKit runs stages in parallel by default; without
       this line, the build stage would not wait for lint to finish and a lint
       failure might not fail the overall build.
+    - **Re-prove that ordering on a warm cache after adopting `CHECK_EPOCH`.**
+      The cache-bust turns this no-op `COPY` into a content-cache hit, so an
+      ordering guarantee established on a cold cache does not automatically
+      carry over; it has to be re-checked warm. This was re-proved in another
+      repo in the org that uses the same file-dependency trick (there with a
+      marker file in place of `go.sum`), and the ordering held. It has **not**
+      been verified in this repo, which is single-stage and has no lint stage to
+      order against. Any repo relying on a file-dependency trick for stage
+      ordering should re-check it warm after adopting the bust rather than
+      assuming this result transfers.
     - If the project uses `//go:embed` directives that reference build artifacts
       (e.g. a web frontend compiled in a separate stage), the lint stage must
       create placeholder files so the embed directives resolve. Example:
@@ -165,11 +237,28 @@ style conventions are in separate documents:
     - The build stage runs `make test` after compilation setup. Tests run in the
       build stage, not the lint stage, because they may require compiled
       artifacts or heavier dependencies.
+    - `ARG CHECK_EPOCH` appears in **both** stages, because `ARG` is
+      stage-scoped: declaring it only in the lint stage leaves `make test`
+      frozen at the last cached result. In each stage the guard sits immediately
+      below the `ARG` so a bare `docker build .` fails instead of reusing the
+      empty cache key, and the value is expanded into the first check `RUN` so
+      the cache miss does not rely on BuildKit's unreferenced-`ARG` handling.
+      Both of those lines reference `$CHECK_EPOCH`, so both are value-keyed:
+      each stage is invalidated at two independent points. The later `RUN`s in
+      the same stage need no expansion of their own: they are already
+      invalidated by their busted parent layer.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` (which runs `docker build .`) on push. Since the
-  Dockerfile already runs `make check`, a successful build implies all checks
-  pass.
+  runs `script/cibuild` (which runs
+  `docker build --build-arg CHECK_EPOCH="$epoch" .`) on push. The Dockerfile
+  runs `make check`, so a successful build implies all checks pass — but that
+  implication holds **only** because of the `CHECK_EPOCH` cache-bust described
+  above. Without it, an unchanged tree serves the check layer from cache and the
+  build reports a green it never earned. A bare `docker build .` fails closed by
+  design, on the `[ -n "$CHECK_EPOCH" ]` guard; always go through
+  `script/cibuild` or `script/docker`. Never accept a `script/cibuild` pass as
+  evidence without confirming it ran: a sub-second wall time, or `CACHED` on the
+  check layer, means nothing was executed.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -209,16 +298,11 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@go test -count=1 -timeout 30s -race -cover ./... || \
+    	@go test -timeout 30s -race -cover ./... || \
     		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -count=1 -timeout 30s -race -v ./...; exit 1; }
+    		  go test -timeout 30s -race -v ./...; exit 1; }
     ```
 
-    `-count=1` is required on both invocations: it defeats Go's test _result_
-    cache, so the target cannot report a pass it did not earn, and the rerun
-    reproduces a failure instead of replaying it. It leaves the build cache
-    alone, so it costs the runtime of the suite and no recompilation.
-
     Python example:
 
     ```makefile
@@ -270,6 +354,114 @@ style conventions are in separate documents:
   commit-pinned via
   `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5`.
 
+- **`script/bootstrap` in Go repos must install the pinned golangci-lint
+  whenever the installed version does not match the pin — not merely when the
+  binary is absent — and must then verify the install took effect by
+  re-resolving the binary through `PATH`.** The presence test
+  `if missing golangci-lint; then go install "$GOLANGCI_LINT_REF"; fi` is wrong:
+  it tests `PATH` presence and never version, so on any already-provisioned
+  machine the pin is inert and a version bump is a no-op. Meanwhile the
+  Dockerfile installs unconditionally into a clean image, so CI and local
+  silently disagree about what the linter even is. Observed consequences: a
+  local `make check` green while `make docker` rejected the same commit with six
+  `goconst` findings, and a container linter surfacing thirteen findings the
+  host run missed. A stale host linter does not merely fail to prove the tree is
+  clean — it hides findings only the container can see. This is a deliberate
+  departure from the node handling described above, which uses whatever node is
+  installed: the linter version is the specific thing being held equal between
+  host and container, so for it, presence is not enough.
+
+    Comparing versions is necessary but **not sufficient**, because the obvious
+    fix also fails green. `go install` writes to `GOBIN` (or `GOPATH/bin`) while
+    callers resolve `golangci-lint` through `PATH`. If a different binary
+    shadows it earlier in `PATH`, the install genuinely succeeds and changes
+    nothing any caller will ever see: bootstrap prints success and the next
+    `make lint` still runs the stale linter. That is worse than no fix, because
+    it converts a known-stale toolchain into one everyone believes is pinned.
+    The canonical form, placed in `script/bootstrap` after Go itself is present:
+
+    ```sh
+    # golangci-lint v2.12.2, 2026-05-06
+    GOLANGCI_LINT_VERSION="2.12.2"
+    GOLANGCI_LINT_REF="github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5"
+
+    # The version golangci-lint reports, resolved the way callers resolve it.
+    # Prints nothing when the binary is absent, exits non-zero, or prints
+    # something unparseable — all of which must read as "does not match".
+    golangci_lint_version() {
+        command -v golangci-lint >/dev/null 2>&1 || return 0
+        golangci-lint --version 2>/dev/null | head -n 1 |
+            sed -n 's/.*has version v\{0,1\}\([0-9][0-9.]*\).*/\1/p'
+    }
+
+    ensure_golangci_lint() {
+        if [ "$(golangci_lint_version)" = "$GOLANGCI_LINT_VERSION" ]; then
+            return 0
+        fi
+        echo "bootstrap: installing golangci-lint $GOLANGCI_LINT_VERSION"
+        go install "$GOLANGCI_LINT_REF"
+
+        # go install writes to GOBIN (or GOPATH/bin); callers resolve through
+        # PATH. Re-resolve through PATH and assert the install took effect.
+        hash -r 2>/dev/null || true
+        got="$(golangci_lint_version)"
+        if [ "$got" = "$GOLANGCI_LINT_VERSION" ]; then
+            return 0
+        fi
+        gobin="$(go env GOBIN)"
+        [ -n "$gobin" ] || gobin="$(go env GOPATH)/bin"
+        found="$(command -v golangci-lint 2>/dev/null || true)"
+        echo "bootstrap: installed golangci-lint $GOLANGCI_LINT_VERSION into" \
+            "$gobin, but PATH resolves golangci-lint to ${found:-nothing}," \
+            "reporting version ${got:-unparseable}." >&2
+        echo "bootstrap: remove that binary or put $gobin earlier in PATH," \
+            "then re-run bootstrap." >&2
+        exit 1
+    }
+    ```
+
+    Three properties are load-bearing; each guards a failure mode that otherwise
+    fails green:
+    - **Compare the installed version against the pin**, never test presence.
+      This is what makes a version bump propagate to machines that already have
+      some golangci-lint.
+    - **After installing, re-resolve the binary the way callers resolve it** —
+      through `PATH`, not the path `go install` wrote to — and assert
+      `--version` reports the pin. When it does not, fail non-zero and **name
+      the shadowing path** `command -v` actually found, the version it reports,
+      and the directory the install wrote to. That is a condition a human has to
+      fix by hand, so bootstrap must not print success in it. Use `hash -r`
+      first so the shell does not answer from its own lookup cache.
+    - **A mis-parse must fall through to reinstall, never to a false match.**
+      Absent binary, non-zero exit, empty output, and unrecognised output all
+      yield an empty string, which compares unequal to the pin. The failure
+      direction is always a redundant install, never a skipped one.
+
+    Keep it POSIX sh: no bashisms, no arrays, no `[[`, no `grep -P`.
+
+    **On the hash-pinning rule.** `@c0d3ddc9cf3faa61a4e378e879ece580256d76e5` is
+    a commit hash, not a server-mutable version tag, and the go command verifies
+    the fetched module against the checksum database and `go.sum` — the
+    mechanism the hash-pinning rule at the top of this document already names as
+    acceptable for Go modules. So the ref stays a bare `go install` of a
+    commit-pinned module rather than a `go.mod` tool dependency; the linter is a
+    bootstrap prerequisite rather than part of the module graph, and tracking it
+    as a tool dependency would pull its whole dependency tree into every
+    consuming repo's `go.mod` and `go.sum`. `GOLANGCI_LINT_VERSION` is a
+    separate string because the ref is a hash and carries no readable version;
+    it must be updated with the ref. That commit is the `v2.12.2` tag commit, so
+    the go command resolves it to `v2.12.2` and the built binary reports
+    `2.12.2`. If a pin is ever moved to a commit that carries no release tag,
+    the binary will report a pseudo-version instead and `GOLANGCI_LINT_VERSION`
+    must be set to whatever `--version` then prints.
+
+    **Verifying a change to this logic requires a negative control run in an
+    environment where a shadowing binary exists earlier in `PATH` than the
+    install target.** Without that, the control passes against the naive
+    compare-then-install form as well and therefore proves nothing. Also check
+    the mis-parse direction by feeding it unparseable `--version` output and
+    confirming it reinstalls rather than reporting a match.
+
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).
 

script/cibuild

@@ -1,13 +1,20 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Dockerfile runs script/check, so
-# a successful build implies all checks pass.
+# script/cibuild: run the CI build. The Dockerfile runs script/check, but
+# that only proves anything because CHECK_EPOCH is a fresh nonce on every
+# invocation: without it Docker serves the check layer from cache on an
+# unchanged tree and the build exits 0 without running the suite.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build .
+    # Assign on its own line: a failing command substitution inside an
+    # argument does not trip `set -e`, which would silently degrade the
+    # nonce to an empty constant. `$$` is required because busybox `date`
+    # drops %N without erroring.
+    epoch="$(date +%s%N)$$"
+    docker build --build-arg CHECK_EPOCH="$epoch" .
 }
 
 main "$@"

script/docker

@@ -1,6 +1,9 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
-# Identical in all repos; the tag comes from script/projectname.
+# Identical in all repos; the tag comes from script/projectname. The
+# Dockerfile's checks only actually run because CHECK_EPOCH is a fresh
+# nonce on every invocation; without it a warm cache turns this into a
+# green that proves nothing.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -8,7 +11,13 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build -t "$("$SCRIPT_DIR/projectname")" .
+    # Assign on its own line: a failing command substitution inside an
+    # argument does not trip `set -e`, which would silently degrade the
+    # nonce to an empty constant. `$$` is required because busybox `date`
+    # drops %N without erroring.
+    epoch="$(date +%s%N)$$"
+    docker build --build-arg CHECK_EPOCH="$epoch" \
+        -t "$("$SCRIPT_DIR/projectname")" .
 }
 
 main "$@"