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, and treats any unparseable --version output as a mismatch so the
failure direction is a redundant install rather than a skipped one.

The comparison is exact over the whole version token. A parser that stops at
the first `-` reports 2.12.2 for a host running 2.12.2-rc1, which compares
equal to a 2.12.2 pin and skips the install -- the original defect, reachable
through the comparison meant to close it, and not caught by requiring the pin
to be tagged, since a pre-release is tagged too.

When the assert fails the diagnosis is derived from the resolved path rather
than asserted: a path outside the install directory is shadowing and the
operator is told to remove it or reorder PATH; a path inside it is not, and
saying so would send them after a fault that does not exist; no resolution at
all means the install directory is simply absent from PATH. A trailing slash
on GOBIN is normalised away, since it would otherwise make the inside-the-
directory test miss and misreport shadowing.

The snippet ends with a call site, and both success paths print a confirmation
naming the version. Two definitions with no invocation are a silent no-op with
exactly the shape this change exists to close, and a success path that prints
nothing is byte-identical to that no-op: same exit status, same empty output.

The version helper ends in `|| true` so a --version that exits non-zero cannot
kill the script through `set -e` under `set -o pipefail` before the diagnostic
is printed, which the styleguide's bash form would otherwise do.

The policy text states each of those as a requirement rather than leaving them
implicit in the code, and records why the commit-pinned `go install` ref
satisfies the hash-pinning rule: a commit hash is not a mutable tag, and the
checksum database verifies the fetch, with no repo go.sum consulted, since
`go install pkg@version` ignores the go.mod in the current directory or any
parent. Whether a go.mod tool dependency should replace that is an open
decision and is linked rather than settled here. The two version strings must
be kept in sync and must match exactly what --version prints; tagged pins are
preferred because the expected string is then derivable from the ref, rather
than because the comparison cannot handle a pseudo-version.

Verification runs the controls against the block as a consuming repo would
adopt it, pasted into a script/bootstrap-shaped file and executed, rather than
sourcing it and calling the function directly.

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

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)
+  (byte-identical across repos); passes the same `CHECK_EPOCH` nonce as
-- `script/cibuild` — cd to the repo root and `docker build .` (what CI runs; the
+  `script/cibuild`
-  image build runs `script/check`)
+- `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,6 +21,23 @@ fmt-check, and commit.
 
 # Completed Steps
 
+- 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
+    linting. `script/cibuild` and `script/docker` should always make sure that
-    able-to-be-compiled state, linted, and any tests run. The Docker build
+    the code is in an able-to-be-compiled state, linted, and any tests run, and
-    should fail if linting doesn't pass.
+    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
+- [ ] `Dockerfile` and `.dockerignore` exist (fetch `.dockerignore` from
-      build step — fetch `.dockerignore` from
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`);
-      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
+      Dockerfile runs `make check` as a build step, and every stage containing a
-- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `docker build .` on
+      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:
@@ -59,9 +64,7 @@ with your task.
 - [ ] README has an **Entrypoints** section documenting the `script/`
       entrypoints and linking the standard
 - [ ] `make check` does not modify any files in the repo
-- [ ] `make test` has a 90-second timeout and completes within the 60-second
+- [ ] `make test` has a 30-second timeout
-      hard cap (over 20 seconds is green but must be filed as an improvement
-      bug)
 - [ ] `make test` runs real tests, not a no-op (at minimum, import/compile
       check)
 - [ ] `make check` passes on current branch
@@ -106,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
@@ -80,8 +85,8 @@ are thin shims calling them. Model scripts:
       installs
 - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
       then `install-precommit`, plus repo-specific init
-- [ ] `script/test` / `make test` — runs real tests, not a no-op (90-second
+- [ ] `script/test` / `make test` — runs real tests, not a no-op (30-second
-      timeout, 60-second hard cap on wall time)
+      timeout)
 - [ ] `script/lint` / `make lint` — runs linter
 - [ ] `script/fmt` / `make fmt` — formats code (writes)
 - [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only)
@@ -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/projectname` (byte-identical across repos); assigns
-- [ ] `script/cibuild` — cd to repo root, `docker build .` (what CI runs)
+      `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-07
+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
+  repo root and runs `docker build --build-arg CHECK_EPOCH="$epoch" .`, where
-  scripts are our own extensions to the standard: `script/check` runs
+  `epoch` is a per-invocation nonce (see the `CHECK_EPOCH` rule below); the
-  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
+  Gitea workflow calls it. Four further scripts are our own extensions to the
-  what the git pre-commit hook runs, and it calls `script/check`;
+  standard: `script/check` runs `script/test`, `script/lint`, and
-  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
+  `script/fmt-check`; `script/precommit` is what the git pre-commit hook runs,
-  target shims to it); and `script/projectname` (literally that filename) simply
+  and it calls `script/check`; `script/install-precommit` installs the git
-  outputs the project's name. Scripts that need the name call
+  pre-commit hook (the `make hooks` target shims to it); and
-  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
+  `script/projectname` (literally that filename) simply outputs the project's
-  so those scripts stay byte-identical across all repos. Repo-type-specific
+  name. Scripts that need the name call `script/projectname` — e.g.
-  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
+  `script/docker` assembles its image tag from it — so those scripts stay
-  `script/precommit`, not in the hook itself. Model scripts are at
+  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
+  as a build step so the build fails if the branch is not green — which requires
-  repos, the Dockerfile should bring up a development environment and run
+  `ARG CHECK_EPOCH` and its guard in every stage containing a check-running
-  `make check`. For server repos, `make check` should run as an early build
+  `RUN`, per the `CHECK_EPOCH` rule below. Without them a Dockerfile satisfies
-  stage before the final image is assembled. Dockerfiles install development
+  this criterion while its check layers are served from cache, so the build
-  prerequisites by running `script/bootstrap` rather than duplicating installs
+  cannot fail on a branch that is not green. For non-server repos, the
-  inline; COPY `script/` and the dependency manifests (`package.json` +
+  Dockerfile should bring up a development environment and run `make check`. For
-  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
+  server repos, `make check` should run as an early build stage before the final
-  layer stays cached until dependencies change.
+  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
+  runs `script/cibuild` (which runs
-  Dockerfile already runs `make check`, a successful build implies all checks
+  `docker build --build-arg CHECK_EPOCH="$epoch" .`) on push. The Dockerfile
-  pass.
+  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
@@ -189,13 +278,8 @@ style conventions are in separate documents:
   module under test to verify it compiles/parses. There is no excuse for
   `make test` to be a no-op.
 
-- `make test` must complete in under 60 seconds. That is the hard cap, and a
+- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
-  suite that exceeds it fails. Under 20 seconds is the target. A suite between
+  Makefile.
-  20 and 60 seconds is still green, but the overage must be filed as an
-  improvement bug against that repo. Add a 90-second timeout to the test
-  invocation in the Makefile (`go test -timeout 90s`). The backstop deliberately
-  sits above the hard cap so that it catches a genuinely hung test rather than a
-  merely slow one.
 
 - **`make test` should use the conditional verbose rerun pattern.** Run tests
   without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
@@ -214,9 +298,9 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@go test -timeout 90s -race -cover ./... || \
+    	@go test -timeout 30s -race -cover ./... || \
     		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -timeout 90s -race -v ./...; exit 1; }
+    		  go test -timeout 30s -race -v ./...; exit 1; }
     ```
 
     Python example:
@@ -270,6 +354,195 @@ 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 must be exactly
+    # what `golangci-lint --version` prints for this ref; update both together.
+    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 those must read as "does not match".
+    # The capture is the whole version token, not just its numeric prefix.
+    # Stopping at the first `-` would make 2.12.2-rc1 compare equal to 2.12.2
+    # and skip the install, which is the defect this whole rule exists to close.
+    # The trailing `|| true` is required, not tidiness. Under `set -o pipefail`
+    # a non-zero --version would otherwise propagate out of the pipeline and
+    # kill the script through `set -e` before the diagnostic below is printed.
+    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][^ ]*\).*/\1/p' || true
+    }
+
+    ensure_golangci_lint() {
+        if [ "$(golangci_lint_version)" = "$GOLANGCI_LINT_VERSION" ]; then
+            echo "bootstrap: golangci-lint $GOLANGCI_LINT_VERSION already installed"
+            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` is load-bearing: without it a shell that already resolved
+        # a stale golangci-lint answers from its own lookup cache, and this
+        # check false-fails with the shadowing message below.
+        hash -r 2>/dev/null || true
+        gcl_got="$(golangci_lint_version)"
+        if [ "$gcl_got" = "$GOLANGCI_LINT_VERSION" ]; then
+            echo "bootstrap: golangci-lint $GOLANGCI_LINT_VERSION installed," \
+                "and PATH resolves it"
+            return 0
+        fi
+        gcl_bin="$(go env GOBIN)"
+        [ -n "$gcl_bin" ] || gcl_bin="$(go env GOPATH)/bin"
+        # Strip a trailing slash: GOBIN=/x/ would otherwise make the
+        # "$gcl_bin"/* test below miss and misreport shadowing.
+        while :; do
+            case "$gcl_bin" in
+                */) gcl_bin="${gcl_bin%/}" ;;
+                *) break ;;
+            esac
+        done
+        gcl_found="$(command -v golangci-lint 2>/dev/null || true)"
+        echo "bootstrap: installed golangci-lint $GOLANGCI_LINT_VERSION into" \
+            "$gcl_bin, but that is not what callers will get." >&2
+        case "$gcl_found" in
+            "")
+                echo "bootstrap: PATH resolves no golangci-lint at all." \
+                    "Add $gcl_bin to PATH, then re-run bootstrap." >&2
+                ;;
+            "$gcl_bin"/*)
+                echo "bootstrap: PATH resolves $gcl_found, inside that same" \
+                    "directory, reporting version ${gcl_got:-unparseable}." \
+                    "Nothing is shadowing it, so the install itself did not" \
+                    "produce the pinned version: check that" \
+                    "GOLANGCI_LINT_VERSION matches GOLANGCI_LINT_REF." >&2
+                ;;
+            *)
+                echo "bootstrap: PATH resolves $gcl_found instead, reporting" \
+                    "version ${gcl_got:-unparseable}. Remove that binary or" \
+                    "put $gcl_bin earlier in PATH, then re-run bootstrap." >&2
+                ;;
+        esac
+        exit 1
+    }
+
+    # The definitions above are inert on their own; the call site is part of
+    # the canonical form. In a script/bootstrap that follows the "define all
+    # functions, then call main" convention, this line belongs inside main()
+    # next to the other ensure_* steps.
+    ensure_golangci_lint
+    ```
+
+    Four 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. Compare the **whole** version token, exactly: a parser
+      that stops at the first `-` reports `2.12.2` for a host running
+      `2.12.2-rc1`, which compares equal to a `2.12.2` pin and skips the install
+      — the original defect, reintroduced through the comparison meant to fix
+      it.
+    - **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
+      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. Diagnose the cause
+      from the resolved path rather than asserting one: only a path **outside**
+      the install directory is shadowing. When the resolved path is inside it,
+      nothing is shadowing and telling the operator to delete that binary or
+      reorder `PATH` sends them after a fault that does not exist.
+    - **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.
+    - **Call it, and say so on success.** Two function definitions with no call
+      site are a silent no-op that reproduces the original defect exactly: exit
+      0, nothing installed, no output, stale linter still resolved. A success
+      path that prints nothing is byte-identical to that no-op — same exit
+      status, same empty output — so both success branches must print a
+      confirmation naming the version. In a change about undetectable no-ops,
+      "it printed nothing and exited 0" must not be the healthy signal.
+
+    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 — the mechanism the
+    hash-pinning rule at the top of this document already names as acceptable
+    for Go modules. Note that `go install pkg@version` runs in module-aware mode
+    ignoring the `go.mod` in the current directory or any parent, so no repo
+    `go.sum` is consulted for this install; the checksum database is what
+    verifies it. The linter is a bootstrap prerequisite rather than part of any
+    repo's module graph, which is why the canonical form installs it by
+    commit-pinned ref instead of declaring it in `go.mod`. Whether a `go.mod`
+    tool dependency — which would pin the hash in a committed, reviewable file
+    instead — should replace this is an open decision, tracked at
+    [prompts#37](https://git.eeqj.de/sneak/prompts/issues/37).
+
+    **Keep `GOLANGCI_LINT_VERSION` and the ref in sync.** The ref is a hash and
+    carries no readable version, so the expected version is a separate string,
+    and it must be exactly what `--version` prints for that ref — the comparison
+    is an exact match on the whole version token. When the pinned commit carries
+    a release tag the go command resolves the hash to that tag, so the string is
+    simply the release number, `2.12.2` here. When it does not, the go command
+    falls back to a pseudo-version and the binary reports something like
+    `2.12.3-0.20260506110758-c0d3ddc9cf3f`; that compares exactly like any other
+    string, so it works, but it cannot be known without building the binary once
+    and reading `--version` off it. Prefer pins on tagged releases for that
+    reason — the expected string is then derivable from the ref — not because
+    the comparison cannot handle the alternative.
+
+    Because the comparison covers the whole token, a pre-release is never
+    confused with its release: a host carrying `2.12.2-rc1` against a `2.12.2`
+    pin compares unequal and gets reinstalled. This matters more than it looks,
+    because a pre-release tag is still a tag, so a rule requiring merely that
+    the pin be tagged would not catch it.
+
+    **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.
+
+    **Run those controls against the block as a consuming repo would adopt it**
+    — pasted into a `script/bootstrap`-shaped file that is then executed — not
+    by sourcing it and invoking the function yourself. Driving the function
+    directly tests something the artifact does not do, and it is exactly how a
+    missing call site passes every control while the adopted snippet does
+    nothing.
+
 - 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
+# script/cibuild: run the CI build. The Dockerfile runs script/check, but
-# a successful build implies all checks pass.
+# 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 "$@"