Run the tests under the race detector with make test-race (closes #18 )

script/test-race runs go test -race in a digest-pinned Debian golang image that has gcc, since the detector needs cgo and the build keeps it off. The checkout is mounted read-only and the container is removed afterwards. The tests run as the calling user, or as nobody when that is root, so the tests that make a file unreadable still see the read fail. It is not part of make check. The detector found no races. Model: opus-5-5
2026-10-04 17:31:36 +00:00
19 changed files with 889 additions and 781 deletions
@@ -0,0 +1,5 @@
+{
+    "worktree": {
+        "bgIsolation": "none"
+    }
+}
@@ -1,79 +1,12 @@
-# .dockerignore does NOT use .gitignore semantics. Docker matches with
-# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
-# `/` and an unprefixed pattern is anchored at the context root. Every
-# depth-independent pattern therefore needs `**/`, or `config/.env` and
-# `certs/server.key` still ship while this file reads as solved. Only
-# genuinely root-anchored entries go unprefixed. Never transplant these
-# into .gitignore, where `**/` is wrong.
-#
-# Matching is case-sensitive, so secrets use character ranges rather
-# than an ALL-CAPS twin, which would still miss `Server.Key`.
-#
-# Extend with this repo's own host-built artifacts, written anchored:
-# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
-# deletes the package directory from the context.
-
 # .git is sent without its config. Without a VERSION build argument the
 # stage that compiles runs `git describe --tags --always` on .git, which
 # does not need .git/config; that file can hold a credential, such as a
 # password in a remote URL or the token the CI checkout step stores there.
-# Each submodule keeps a config with the same exposure in its git directory
-# under .git/modules/, nested again for a submodule's own submodules, or in
-# its own .git directory when it keeps one.
-# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
-# `deploy/config`, `config/lib`) loses its whole git directory, because
-# `**/.git/modules/**/config` also matches that segment's directory
-# under .git/modules/. Go's version stamping then fails the build;
-# nothing leaks. Name such a submodule without that segment:
-# `git submodule add --name`.
-**/.git/config
-**/.git/modules/**/config
+.git/config

-# Agent scratch: one full checkout of the repo per in-flight agent.
-# Anchored because it occurs once where agents run at the repo root.
-# KNOWN GAP: a repo running agents in subdirectories still ships
-# `services/api/.claude/` and must add its own anchored entry.
 .claude
-
-# Environment files. `*.env` covers bare `.env` and the `prod.env`
-# convention. Re-include a committed template with a negation if the
-# build needs one: `!docs/example.env`.
-**/*.[eE][nN][vV]
-**/.[eE][nN][vV].*
-**/.[eE][nN][vV][rR][cC]
-
-# Private keys and the bundles carrying them. Public certificates
-# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
-**/*.[pP][eE][mM]
-**/*.[kK][eE][yY]
-**/*.[pP]12
-**/*.[pP][fF][xX]
-**/[iI][dD]_[rR][sS][aA]
-**/[iI][dD]_[dD][sS][aA]
-**/[iI][dD]_[eE][cC][dD][sS][aA]
-**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
-**/[iI][dD]_[eE][dD]25519
-**/[iI][dD]_[eE][dD]25519_[sS][kK]
-
-# Dependencies: restored inside the image, never copied in.
-**/node_modules
-
-# OS metadata.
-**/.DS_Store
-**/Thumbs.db
-
-# Editor state: never a build input, and it churns COPY.
-**/*.swp
-**/*.swo
-**/*~
-**/*.bak
-**/.idea
-**/.vscode
-**/*.sublime-*
-
-# This repository's host-built artifacts: the binary `make build` writes,
-# and test binaries, coverage output and logs.
-/sfdupes
-/*.test
-/*.out
-/*.log
+.DS_Store
+sfdupes
+*.log
+*.out
+*.test
@@ -11,48 +11,25 @@ Thumbs.db
 .vscode/
 *.sublime-*

-# Agent scratch (worktrees of this repo, created and destroyed by
-# in-flight tooling). Unanchored: .gitignore patterns already match at
-# every depth, so no prefix is wanted here. This is not a .dockerignore
-# entry and must not be given a `**/` prefix on the way into one.
-.claude/
-
 # Node
 node_modules/

-# Secrets. Unanchored like every entry above, so each matches at every
-# depth. Matching is case-sensitive on Linux, so names use character
-# ranges rather than a lowercase form that misses `Server.Key`.
+# Environment / secrets
+.env
+.env.*
+*.pem
+*.key

-# Environment files. `*.env` covers bare `.env` and the `prod.env`
-# convention. Only the templates `example.env` and `sample.env` are
-# re-included below. A repository that commits any other template adds
-# its own negation after these lines, for example `!.env.example`.
-*.[eE][nN][vV]
-.[eE][nN][vV].*
-.[eE][nN][vV][rR][cC]
-!example.env
-!sample.env
-
-# Private keys and the bundles carrying them.
-*.[pP][eE][mM]
-*.[kK][eE][yY]
-*.[pP]12
-*.[pP][fF][xX]
-[iI][dD]_[rR][sS][aA]
-[iI][dD]_[dD][sS][aA]
-[iI][dD]_[eE][cC][dD][sS][aA]
-[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
-[iI][dD]_[eE][dD]25519
-[iI][dD]_[eE][dD]25519_[sS][kK]
-
-# This repository's own entries, kept after the canonical content above.
-*.log
-*.out
-*.test
+# Go build artifacts
 /sfdupes
+*.test
+*.out
+*.log

-# A scan database lists every path it scanned.
+# Local scan data
 *.sqlite
 *.sqlite-shm
 *.sqlite-wal
+
+# Agent worktrees
+.claude/worktrees/
@@ -17,7 +17,6 @@ linters:
  disable:
    # Genuinely incompatible with project patterns
    - exhaustruct      # Requires all struct fields
-    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
    - godot            # Requires comments to end with periods
    - wrapcheck        # Too verbose for internal packages
    - varnamelen       # Short names like db, id are idiomatic Go
@@ -1,42 +1,63 @@
-# Lint phase, built alone by script/lint. The tools are invoked directly
-# rather than through `make lint` or `make fmt-check`, which run docker
-# themselves and so cannot run inside a build step.
-# golangci/golangci-lint:v2.14.0, 2026-10-07
-FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
+# Lint stage — fast feedback on formatting and lint issues
+# golangci/golangci-lint:v2.12.2, 2026-08-07
+FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .

-# The gofmt half of `make fmt-check`; the markdown stage is its prettier
-# half. gofmt's output is assigned to a variable first so that its own
-# exit status, as when it cannot parse a file, still fails the step.
-RUN files="$(gofmt -s -l .)" && \
+# Cache-buster for the gate layers, and only for them. Docker
+# invalidates COPY only when the copied content changes, so on an
+# unchanged tree the gates below would be served from cache and the
+# build would exit 0 having run nothing. script/cibuild and
+# script/docker pass a fresh CHECK_EPOCH on every invocation. A build
+# that passes none, such as a bare `docker build .`, fails at the check
+# right after the ARG instead of quietly serving the gates from cache.
+#
+# Two properties this depends on. ARG is per-stage, so the markdown and
+# build stages below declare it again; one declaration here would leave
+# their gates cacheable. And each gate RUN must reference the value,
+# because BuildKit hashes the expanded command: a declared but
+# unreferenced ARG invalidates nothing.
+#
+# It sits below the dependency layers deliberately. Everything above it
+# (the pinned base image, go mod download) keeps its cache; only the
+# gates go cold.
+ARG CHECK_EPOCH
+RUN if [ -z "${CHECK_EPOCH}" ]; then \
+        echo "CHECK_EPOCH is unset; build via script/cibuild or script/docker" >&2; \
+        exit 1; \
+    fi
+
+# The linter is invoked directly here, not through `make lint`. That
+# target now runs `docker build -f Dockerfile.lint`, and a docker build
+# cannot run a docker build: routing the gate through make would mean
+# nesting docker inside this image. Same reason `make check` is gone
+# from the build stage below, and `make fmt-check` from both stages: it
+# runs prettier through docker too. Its gofmt half is the step below,
+# its Markdown half the markdown stage further down. gofmt's output is
+# assigned to a variable first so that its own exit status, as when it
+# cannot parse a file, still fails the step.
+RUN echo "gate gofmt, epoch ${CHECK_EPOCH}" && \
+    files="$(gofmt -s -l .)" && \
    if [ -n "$files" ]; then \
        echo "gofmt: files not formatted:" >&2; echo "$files" >&2; exit 1; \
    fi

-# Validates .golangci.yml against the schema the pinned binary embeds.
-RUN golangci-lint config verify --config .golangci.yml
-RUN golangci-lint run --config .golangci.yml ./...
+# The FROM above and the one in Dockerfile.lint pin the same linter
+# twice, and nothing else keeps them in sync; this fails the build when
+# they disagree. See the script for why it restates neither pin.
+RUN echo "gate lint-image-pin, epoch ${CHECK_EPOCH}" && \
+    script/verify-lint-image-pin

-# Test phase, built alone by script/test. -race needs cgo and so a C
-# compiler, which the Debian Go image ships and the alpine one does not.
-#
-# The tests run as nobody: several of them make a file unreadable and
-# expect reading it to fail, and root reads it anyway. nobody has no home
-# directory, so HOME is /tmp, where Go puts its build cache.
-# golang:1.25-trixie, 2026-10-04
-FROM golang@sha256:2c4c60ef415fbfa5e90300722293bef36c5e63fae17570ce18f580af933dbd73 AS test
-USER nobody
-ENV HOME=/tmp
-WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
-COPY . .
-RUN go test -timeout 90s -race -cover ./... || \
-    { echo "--- Rerunning with -v for details ---"; \
-      go test -timeout 90s -race -v ./...; exit 1; }
+# Same config-schema check Dockerfile.lint runs, kept here so this build
+# gates on exactly what script/lint gates on. It validates against a
+# schema the pinned binary embeds, so it needs no network.
+RUN echo "gate config verify, epoch ${CHECK_EPOCH}" && \
+    golangci-lint config verify --config .golangci.yml
+
+RUN echo "gate lint, epoch ${CHECK_EPOCH}" && \
+    golangci-lint run --config .golangci.yml ./...

 # Prettier stage: the prettier that formats this repository's Markdown,
 # never installed on a host. script/fmt and script/fmt-check build this
@@ -56,33 +77,108 @@ WORKDIR /src
 # Markdown stage: the Markdown half of `make fmt-check`, as a gate.
 FROM prettier AS markdown
 COPY . .
-RUN prettier --check '**/*.md' --tab-width 4 --prose-wrap always
+# Second per-stage declaration of the gate cache-buster and its check;
+# see the lint stage above.
+ARG CHECK_EPOCH
+RUN if [ -z "${CHECK_EPOCH}" ]; then \
+        echo "CHECK_EPOCH is unset; build via script/cibuild or script/docker" >&2; \
+        exit 1; \
+    fi
+RUN echo "gate prettier, epoch ${CHECK_EPOCH}" && \
+    prettier --check '**/*.md' --tab-width 4 --prose-wrap always

-# Build stage. Nothing is wanted from the lint, test and markdown stages;
-# the copies are what make BuildKit build them first, so this stage
-# cannot run unless all three passed.
+# Build stage
 # golang:1.25-alpine, 2026-07-23
 FROM golang@sha256:56961d79ea8129efddcc0b8643fd8a5416b4e6228cfd477e3fd61deb2672c587 AS builder
-COPY --from=lint /src/go.sum /dev/null
-COPY --from=test /src/go.sum /dev/null
-COPY --from=markdown /src/go.sum /dev/null
+
+# We never build or run as root. Create an unprivileged user and point
+# HOME and the build cache at its home so go build and go test can write
+# it when we drop to it below. $GOPATH/bin is deliberately not on PATH:
+# script/bootstrap no longer `go install`s anything (the linter runs
+# from a pinned image, never from a host install), so nothing lands
+# there and adding it would only widen what this image resolves.
+#
+# The module cache is kept outside that home, at the base image's
+# default /go/pkg/mod, and belongs to root: script/bootstrap fills it as
+# root. Do not move it into the home and hand it over with `chown -R`:
+# that walks every file in it, which took from about 80 s to over ten
+# minutes on a shared host, depending on load.
+RUN adduser -D -u 1000 builder
+ENV HOME=/home/builder
+ENV GOPATH=/home/builder/go
+ENV GOMODCACHE=/go/pkg/mod
+ENV GOCACHE=/home/builder/.cache/go-build
+
 WORKDIR /src

-# script/bootstrap installs the git and make this image lacks, and ends
-# in `go mod download`.
+# No-op file copies whose only purpose is the build-graph edge: they are
+# what make this stage depend on the lint and markdown stages, and so
+# what forces BuildKit to finish gofmt, the pin guard, lint and prettier
+# before compilation and tests start. Remove one and the fail-fast
+# design dies silently — the build stops gating on that stage and still
+# exits 0. The first replaces a copy of the linter binary itself, which
+# is no longer wanted here: nothing in this stage runs the linter,
+# because `make lint` is now a docker build and a docker build cannot
+# run inside one.
+COPY --from=lint /src/go.sum /dev/null
+COPY --from=markdown /src/go.sum /dev/null
+
+# Install development prerequisites the same way a developer does,
+# rather than duplicating the installs inline. Only script/ and the
+# dependency manifests are copied first, nothing else, so this layer
+# stays cached until the scripts or the dependencies change — bootstrap
+# ends in `go mod download`, which is why there is no separate
+# invocation of it here.
 COPY script/ script/
 COPY go.mod go.sum ./
 RUN script/bootstrap
-# A tar-stream context keeps the sender's file owners, which git refuses.
-RUN git config --system --add safe.directory /src
-COPY . .
+
+# Hand builder only what it writes to, without walking the module cache.
+# This layer stays cached with bootstrap.
+# - /src itself: make build writes the binary into it, and git refuses
+#   a repository whose top directory belongs to another user.
+# - the module cache's cache/download directory itself, not what is in
+#   it: Go only reads the downloaded modules, but make build saves its
+#   lookup of this module's own version from git there, in a new
+#   directory named after the module path.
+# - builder's home: the go commands bootstrap ran as root left Go's
+#   telemetry files there, a few small files.
+RUN chown builder:builder /src /go/pkg/mod/cache/download && \
+    chown -R builder:builder /home/builder
+
+# The sources are handed to builder as they are copied, so no layer has
+# to walk them. Then drop root before running any checks or builds.
+COPY --chown=builder:builder . .
+USER builder
+
+# Fail the build unless the branch is green. Runs as non-root so the
+# permission-denied test paths are exercised legitimately (root would
+# bypass the chmod(0) the tests rely on).
+#
+# The gate is `make test`, not `make check`: that aggregate runs
+# `script/lint` and `script/fmt-check`, which both run docker, and
+# nothing inside an image build may shell out to docker. Lint and the
+# format checks are not skipped by this — they ran in the lint and
+# markdown stages above, which this stage's COPY --from lines make
+# prerequisites. `make`, not the script directly, because the Makefile's
+# `export CGO_ENABLED = 0` applies only to what it invokes.
+#
+# Third per-stage declaration of the gate cache-buster and its check;
+# see the lint stage above for why one is not enough. It is placed after
+# USER so the drop to the unprivileged user still happens before the
+# checks run.
+ARG CHECK_EPOCH
+RUN if [ -z "${CHECK_EPOCH}" ]; then \
+        echo "CHECK_EPOCH is unset; build via script/cibuild or script/docker" >&2; \
+        exit 1; \
+    fi
+RUN echo "gate test, epoch ${CHECK_EPOCH}" && make test

 # The version stamped into the binary: the VERSION build argument when
 # one is given, otherwise `git describe --tags --always` of the .git in
-# the build context. A context that carries .git and still yields no
-# version fails the build; with neither, as from a source tarball, it is
-# "dev". `make build` rather than `go build`, so the image and a host
-# build share one compile recipe, cgo disabled included.
+# the build context (git is installed by script/bootstrap above). A
+# context that carries .git and still yields no version fails the build;
+# with neither, as from a source tarball, it is "dev".
 ARG VERSION
 RUN version="${VERSION:-$(git describe --tags --always || echo dev)}"; \
    if [ -e .git ] && { [ -z "$version" ] || [ "$version" = dev ] || \
@@ -92,8 +188,7 @@ RUN version="${VERSION:-$(git describe --tags --always || echo dev)}"; \
    fi; \
    make build VERSION="$version"

-# Runtime stage, and the last one: a plain `docker build .` builds this
-# stage's chain and nothing else.
+# Runtime stage
 # alpine:3.22, 2026-07-23
 FROM alpine@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce

@@ -0,0 +1,59 @@
+# Lint-only image: this is how the linter runs, everywhere. The repo is
+# COPYed into the pinned golangci-lint image and the linter runs as a
+# build step, so a successful build IS a clean lint. golangci-lint is
+# never installed on a host — one toolchain, pinned by digest, identical
+# on a laptop and in CI — and this works even when the docker daemon is
+# remote and bind mounts are impossible.
+#
+# script/lint builds this file. It is a separate image from the lint
+# stage of the main Dockerfile because script/lint must not depend on
+# the rest of that build; the two FROM lines are kept identical by
+# script/verify-lint-image-pin, run as a gate below.
+# golangci/golangci-lint:v2.12.2, 2026-08-07
+FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240
+
+WORKDIR /src
+
+# Dependency layers first, so they stay cached across lint runs.
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+# Cache-buster for the gate layers, and only for them. Caching of the
+# lint run is waived by ruling: COPY is invalidated only by changed
+# content, so on an unchanged tree the gates below would be served from
+# cache and this build would exit 0 in under a second having run no
+# linter at all. That exact false green has bitten this repo twice
+# already (#32, #39). script/lint passes a fresh value on every
+# invocation.
+#
+# Each gate RUN must reference the value, because BuildKit hashes the
+# expanded command and not the ARG declaration: a declared but
+# unreferenced ARG invalidates nothing. The ARG sits below the
+# dependency layers deliberately — everything above it keeps its cache,
+# only the gates go cold.
+ARG CHECK_EPOCH
+
+# The linter version is pinned in two places, here and in the main
+# Dockerfile's lint stage. Nothing else keeps them in sync, so a
+# half-applied bump is a build failure; see the script.
+RUN echo "gate lint-image-pin, epoch ${CHECK_EPOCH}" && \
+    script/verify-lint-image-pin
+
+# Validates .golangci.yml against golangci-lint's JSON schema. The
+# concern about this step was that it fetches that schema over a live,
+# unpinned HTTPS call; measured on the pinned image, it does not. The
+# binary carries the schema for its own version, so under
+# `--network none` this both passes on a valid config and still rejects
+# an invalid one with the jsonschema error. That holds for the gate
+# steps generally — none of them makes a network call — but not for
+# this build as a whole: `go mod download` above needs the network on a
+# cold cache, and under `--network none` a first build fails there
+# before reaching any gate. That layer stays cached, so only a warm
+# cache lints offline, until go.mod or go.sum changes.
+RUN echo "gate config verify, epoch ${CHECK_EPOCH}" && \
+    golangci-lint config verify --config .golangci.yml
+
+RUN echo "gate lint, epoch ${CHECK_EPOCH}" && \
+    golangci-lint run --config .golangci.yml ./...
@@ -6,7 +6,7 @@ BINARY := sfdupes
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
 LDFLAGS := -X main.Version=$(VERSION)

-.PHONY: sfdupes build bootstrap setup test lint fmt fmt-check check docker hooks clean
+.PHONY: sfdupes build bootstrap setup test test-race lint fmt fmt-check check docker hooks clean

 # Standard targets are thin shims; the implementations live in script/
 # per the scripts-to-rule-them-all pattern.
@@ -27,6 +27,9 @@ setup:
 test:
 	@script/test

+test-race:
+	@script/test-race
+
 lint:
 	@script/lint

@@ -741,26 +741,44 @@ entrypoints are:
  presence-checked only. `golangci-lint` and prettier are deliberately **not**
  installed: they run in Docker (see `script/lint` and `script/fmt`) and never
  from a host install, so there is no host copy to drift from the pin. A missing
-  `docker` is warned about rather than installed or treated as fatal:
-  `make build` works without it, and testing, linting, formatting and the image
-  build need it. Ends with `go mod download`.
+  `docker` is warned about rather than installed or treated as fatal —
+  everything except linting, formatting and `make test-race` works without it.
+  Ends with `go mod download`.
 - `script/setup` — make a fresh clone ready for development: runs
  `script/bootstrap`, then `script/install-precommit`.
 - `script/projectname` — print this project's name (`sfdupes`). Scripts that
  need the name call it, so they stay identical across repositories.
- `script/test` — run the test suite under the race detector, with a 90-second
-  timeout and coverage enabled, rerunning verbosely on failure so the logs show
-  which test failed. It builds the `Dockerfile`'s `test` phase alone, tagged
-  `sfdupes-test`. The race detector needs cgo and a C compiler, which the build
-  never uses, so the phase starts from a digest-pinned Debian `golang` image,
-  which has `gcc`. The tests run as `nobody`, because several of them make a
-  file unreadable and root reads it anyway.
- `script/lint` — run the linter. It builds the `Dockerfile`'s `lint` phase
-  alone, tagged `sfdupes-lint`: in the digest-pinned `golangci/golangci-lint`
-  image, the gofmt check, `golangci-lint config verify` and `golangci-lint run`
-  run as build steps, so a successful build is a clean lint. The linter is never
-  run on the host, which makes a working `docker` the one prerequisite for
-  linting.
+- `script/test` — run the test suite with a 30-second timeout and coverage
+  enabled, rerunning verbosely on failure so the logs show which test failed.
+- `script/test-race` — run the test suite under the race detector with a
+  60-second timeout. The detector needs cgo and a C compiler, which the build
+  never uses, so the tests run in a digest-pinned Debian `golang` image that has
+  `gcc`, with the checkout mounted read-only; the container is removed when it
+  exits. They run as the calling user, or as `nobody` when that is root, because
+  several tests make a file unreadable and root reads it anyway; only then must
+  the checkout be readable by other users. Not part of `script/check`. Every run
+  starts with empty caches, so it needs the network and takes minutes, and the
+  mount needs a local docker daemon.
+- `script/lint` — run the linter. It builds `Dockerfile.lint`, which copies the
+  repository into the digest-pinned `golangci/golangci-lint` image and runs
+  `golangci-lint config verify` and `golangci-lint run` as build steps, so a
+  successful build is a clean lint. That exit status is all it produces, so it
+  runs with `--output=type=cacheonly` and writes no image; a run leaves only
+  build cache. The linter is never run on the host, which makes a working
+  `docker` the one prerequisite for linting — and therefore for `make check` and
+  the pre-commit hook. Offline machines: the gate steps themselves make no
+  network calls. `golangci-lint run` does not, and neither does
+  `golangci-lint config verify` — it validates against a schema the pinned
+  binary embeds, measured under `--network none` to both pass a valid config and
+  reject an invalid one. The build around them does. `Dockerfile.lint` runs
+  `go mod download` before the gates and this module has external dependencies,
+  so a first lint on a machine with a cold BuildKit cache reaches the network
+  there (as well as pulling the pinned image); under `--network none` it fails
+  at that step, before any gate. That layer sits above the gates and stays
+  cached, so once it is warm `script/lint` — and with it `make check` — runs
+  entirely offline, until `go.mod` or `go.sum` changes and the download layer
+  goes cold again. Because the daemon only ever sees a build context, this works
+  when the docker daemon is remote and bind mounts are impossible.
 - `script/fmt` — format in place: the Go sources with `gofmt -s -w`, and every
  Markdown file with prettier, at the settings in `.prettierrc` (4-space
  indents, prose wrapped at 80 columns). prettier is pinned by hash through
@@ -773,32 +791,51 @@ entrypoints are:
  repository mounted read-only: prints any unformatted file and exits non-zero
  instead of writing. gofmt and prettier both run every time, and each names
  itself when it fails. The `Dockerfile` runs the same two checks as gates: the
-  gofmt check in its `lint` phase, prettier in its `markdown` stage.
+  gofmt check in its lint stage, prettier in its `markdown` stage.
 - `script/check` — run `script/test`, `script/lint`, and `script/fmt-check`, in
-  that order. Modifies nothing. Needs `docker`, because all three do.
+  that order. Modifies nothing. Needs `docker`, because `script/lint` and
+  `script/fmt-check` do.
 - `script/docker` — build the Docker image, tagged with the name from
-  `script/projectname`, passing the output of
-  `git describe --tags --always --dirty` (or `unknown` when that is empty) as
-  the `VERSION` build argument. The `Dockerfile`'s build stage depends on its
-  `lint`, `test` and `markdown` stages, so this is also the check a developer or
-  reviewer runs by hand.
- `script/cibuild` — run `script/bootstrap`, then `script/check`, then build the
-  image as `script/docker` does. This is what the Gitea workflow runs on push; a
-  successful run means every check passed. The tests and the linter run twice:
-  once in `script/check`, and again as stages of the image build.
+  `script/projectname`. The `Dockerfile` runs the gates as build steps, so this
+  is also the check a developer or reviewer runs by hand.
+- `script/cibuild` — build the Docker image untagged. This is what the Gitea
+  workflow runs on push; because the gates run as build steps, a successful
+  build implies the repository is green.
 - `script/precommit` — run by the git pre-commit hook: `go mod tidy` must be a
  no-op (a resulting change to `go.mod` or `go.sum` fails the commit), then
  `script/check`.
 - `script/install-precommit` — install the git pre-commit hook that runs
  `script/precommit`. The hook is written to the common git directory, so the
  main checkout and every worktree share it.
+- `script/verify-lint-image-pin` — fail unless the `golangci/golangci-lint`
+  reference in `Dockerfile.lint` and the one in the `Dockerfile` lint stage are
+  the same image at the same digest, naming both if not. The linter is pinned in
+  those two files and nothing else keeps them in sync, so a bump applied to one
+  alone would leave `make lint` and the `Dockerfile`'s fail-fast lint stage
+  checking the same tree against different rulesets, both green. The guard
+  restates neither pin — a third copy would be the same drift one file further
+  out — and runs as a gate in both files, so `make lint`, `make check` and
+  `make docker` all catch it.

-Every `docker build` in `script/` passes `--no-cache`. On an unchanged tree
-Docker would serve the gate steps from its cache, and the build would pass
-having run no test and no linter. Every run therefore downloads the Go modules
-again and needs the network. `script/test` and `script/lint` send the daemon
-only a build context, so they work against a remote docker daemon; `script/fmt`
-and `script/fmt-check` mount the repository and need a local one.
+`script/verify-linter-pin` used to live here. It compared a linter binary
+against a version pin in `script/bootstrap`, and both of its subjects are gone:
+no linter binary is copied between build stages any more, and bootstrap pins no
+version because it installs no linter. The drift it existed to catch has moved
+from binary-versus-pin to pin-versus-pin, which is what
+`script/verify-lint-image-pin` above checks.
+
+`script/lint`, `script/docker` and `script/cibuild` all pass a freshly computed
+`CHECK_EPOCH` build argument, and the gate steps in `Dockerfile.lint` and
+`Dockerfile` reference it. Without that, an unchanged tree lets Docker serve the
+gate layers from cache and the build exits 0 having executed no tests and no
+lint — a green it never earned, and one this repository has produced twice.
+`CHECK_EPOCH` invalidates the gate layers on every run while leaving the pinned
+base images and the dependency layers cached. Each script's value carries the
+process id as well as the epoch, because two runs land inside the same second
+easily and a bare epoch would cache the second one. Each `Dockerfile` stage with
+gates fails when the value is empty, so a bare `docker build .` stops with
+`CHECK_EPOCH is unset; build via script/cibuild or script/docker` instead of
+serving the gates from cache.

 ## Build

@@ -810,15 +847,17 @@ compile recipe:
  the default target.
 - `make bootstrap` — install the build and development dependencies.
 - `make setup` — prepare a fresh clone: `bootstrap` plus the pre-commit hook.
- `make test` — run the test suite under the race detector, in Docker (90-second
-  timeout; reruns with `-v` on failure; see `script/test`); requires `docker`.
- `make lint` — run `golangci-lint` with the repo config and the gofmt check, in
-  Docker (see `script/lint`); requires `docker`.
+- `make test` — run the test suite (30-second timeout; reruns with `-v` on
+  failure).
+- `make test-race` — run the test suite under the race detector, in Docker (see
+  `script/test-race`); requires `docker`. Not part of `make check`.
+- `make lint` — run `golangci-lint` with the repo config, in Docker (see
+  `script/lint`); requires `docker`.
 - `make fmt` / `make fmt-check` — format the Go sources and the Markdown /
  verify formatting without writing; requires `docker`, for prettier (see
  `script/fmt`).
 - `make check` — `test`, `lint`, and `fmt-check`; modifies nothing. Requires
-  `docker`.
+  `docker`, via `lint` and `fmt-check`.
 - `make docker` — build the Docker image, which runs the gates as build stages.
 - `make hooks` — install the pre-commit hook.
 - `make clean` — remove the binary.
@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-10-04
+last_modified: 2026-07-06
 ---

 This document covers repository structure, tooling, and workflow standards. Code
@@ -60,28 +60,17 @@ 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, runs `script/bootstrap`, runs `script/check`, and builds the image
-  with the version; the Gitea workflow calls it. **`script/cibuild` runs
-  `script/bootstrap` first**, because the workflow checks out the repo and runs
-  nothing else, while `script/fmt-check` runs the formatter on the host: on a
-  pristine checkout with nothing installed the run dies there, after the
-  containerised gates have passed. **The bootstrap alone is not enough**:
-  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
-  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
-  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
-  source nvm for the pinned node version before invoking it, exactly as
-  `script/bootstrap`'s own install step does. A runner carrying nothing but
-  docker and git then gets through `script/check`. 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 .`; 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).
@@ -100,198 +89,87 @@ style conventions are in separate documents:
  contributor should be able to understand the entire development workflow by
  reading the Makefile.

- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
-  `lint` phase and a `test` phase, with the final stage depending on both so the
-  image cannot be built unless they pass. For non-server repos the final stage
-  brings up a development environment; for server repos it is the runtime image.
-  The gate phases and the build stage start from their pinned base images and
-  install what those images lack either inline, as the canonical Go `Dockerfile`
-  below does for `git`, or by running `script/bootstrap`, as the `prompts`
-  repo's own `Dockerfile` does for its yarn packages. The development
-  environment stage installs development prerequisites by running
-  `script/bootstrap` rather than duplicating its installs inline. A stage that
-  runs `script/bootstrap` COPYs `script/` and the dependency manifests
-  (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it.
+- 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.

- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
-  no separate lint file. `script/lint` and `script/test` each build one phase
-  and nothing else:
+- **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
+  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
+  `make fmt-check` and `make lint` before the full build begins. The build stage
+  then declares an explicit dependency on the lint stage via
+  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
+  linting before proceeding to compilation and tests. This ensures lint failures
+  surface in seconds rather than minutes, without blocking on dependency
+  download or compilation in the build stage.

-    ```sh
-    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
-    docker build --no-cache --target test -t "$(script/projectname)-test" .
-    ```
-
-    **A stage that is not the last one in the file is built only when the final
-    stage's chain depends on it, or when `--target` names it.** That is why the
-    two gates are always invoked by name here, and why the final stage carries a
-    `COPY --from=` of a harmless file from each of them: without that edge a
-    plain `docker build .` builds the last stage alone and exits 0 having linted
-    and tested nothing.
-
-    **Every `docker build` in `script/` is tagged**, here and in
-    `script/cibuild` and `script/docker`. An untagged build leaves a dangling
-    image behind on every invocation, on every developer host and every CI
-    runner; a tagged one replaces the previous image.
-
-    Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
-    `eslint`, `prettier` — never through `make lint` or `script/test`, which are
-    themselves a `docker build` and would recurse into a daemon that does not
-    exist in a build step. Formatting is the exception and stays on the host:
-    `script/fmt` writes the working tree, and `script/fmt-check` is its
-    read-only twin.
-
-    **No lint verdict may come from a host invocation of the linter.** On a
-    shared host golangci-lint reads a result cache keyed on file content rather
-    than location, so a second checkout of the same content is served the first
-    one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
-    exit non-zero with `parallel golangci-lint is running` — a status a caller
-    cannot tell from real findings. Both have produced wrong verdicts in this
-    org, in both directions. A container has its own cache, its own `TMPDIR` and
-    a digest-pinned binary, so neither is reachable.
-
- **Any build that runs checks is built with `--no-cache`.** Docker invalidates
-  a `COPY` layer only when the copied content changes, so on an unchanged tree
-  the check `RUN` is served from cache, nothing executes, and the build still
-  exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
-  `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
-  four, and there is no fifth — `script/check` runs the two gate phases and
-  `script/fmt-check`, and builds no image of its own. A bare `docker build .` is
-  not evidence that anything ran: a sub-second build reporting success is a
-  cache hit, not a result. Never invalidate by pruning — `docker builder prune`
-  and friends destroy a build cache shared with every other build on the host.
-  When a check is added or changed, prove it works by planting a defect it must
-  catch and watching the run fail on it, then revert the defect. A green run
-  alone shows neither that the check ran nor that it covers what it should.
-
- **The gate phases are separate stages, and the build stage depends on both.**
-  The lint phase is based on the `golangci/golangci-lint` image (pinned by
-  hash), so lint failures surface in seconds rather than after a full compile,
-  and the test phase is based on the Debian Go image. The canonical Go repo
-  `Dockerfile`:
+    The standard pattern for a Go repo Dockerfile is:

    ```dockerfile
-    # Lint phase
+    # Lint stage — fast feedback on formatting and lint issues
    # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
    FROM golangci/golangci-lint@sha256:... AS lint
    WORKDIR /src
    COPY go.mod go.sum ./
    RUN go mod download
    COPY . .
-    RUN golangci-lint run --config .golangci.yml ./...
+    RUN make fmt-check
+    RUN make lint

-    # Test phase. -race needs cgo and so a C compiler, which the Debian Go
-    # image ships and the alpine one does not.
-    # golang:1.x, YYYY-MM-DD
-    FROM golang@sha256:... AS test
-    WORKDIR /src
-    COPY go.mod go.sum ./
-    RUN go mod download
-    COPY . .
-    RUN go test -timeout 90s -race -cover ./... || \
-        { echo "--- Rerunning with -v for details ---"; \
-          go test -timeout 90s -race -v ./...; exit 1; }
-
-    # Build stage. Nothing is wanted from either phase above; the copies
-    # are what make BuildKit build them first, so this stage cannot run
-    # unless lint and test passed.
+    # Build stage
    # golang:1.x-alpine, YYYY-MM-DD
    FROM golang@sha256:... AS builder
-    COPY --from=lint /src/go.sum /dev/null
-    COPY --from=test /src/go.sum /dev/null
-    RUN apk add --no-cache git
-    # A tar-stream context keeps the sender's file owners, which git refuses.
-    RUN git config --system --add safe.directory /src
    WORKDIR /src
+
+    # Force BuildKit to run the lint stage before proceeding
+    COPY --from=lint /src/go.sum /dev/null
+
    COPY go.mod go.sum ./
    RUN go mod download
    COPY . .
+    RUN make test

-    # The VERSION build arg when one is given, otherwise
-    # `git describe --tags --always` on the .git in the build context. With
-    # .git present, a version that is still empty, dev or unknown fails the
-    # build: git is missing or could not read the checkout.
-    ARG VERSION
-    RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
-        if [ -e .git ]; then \
-            case "$VERSION" in ""|dev|unknown) \
-                echo "version is '$VERSION' although .git is present" >&2; \
-                exit 1 ;; \
-            esac; \
-        fi; \
-        CGO_ENABLED=0 go build -trimpath \
-            -ldflags="-s -w -X main.Version=${VERSION}" \
-            -o /app ./cmd/app/
+    ARG VERSION=dev
+    RUN CGO_ENABLED=0 go build -trimpath \
+        -ldflags="-s -w -X main.Version=${VERSION}" \
+        -o /app ./cmd/app/

-    # Runtime stage, and the last one
+    # Runtime stage
    FROM alpine@sha256:...
    COPY --from=builder /app /usr/local/bin/app
    ENTRYPOINT ["app"]
    ```

    Key points:
-    - The lint phase uses the `golangci/golangci-lint` image directly (it has
-      both Go and the linter), so nothing needs installing.
-    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
-      purpose is the ordering edge. BuildKit runs stages in parallel by default,
-      and a stage nothing depends on is not built at all, so without these two
-      lines a red gate would not fail the build.
-    - Keep the runtime stage last, and if you add a stage after it, give it the
-      same two copies. A plain `docker build .` builds the last stage's chain
-      and nothing else.
+    - The lint stage uses the `golangci/golangci-lint` image directly (it
+      includes both Go and the linter), so there is no need to install the
+      linter separately.
+    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
+      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.
    - If the project uses `//go:embed` directives that reference build artifacts
-      (e.g. a web frontend compiled in a separate stage), the lint phase must
+      (e.g. a web frontend compiled in a separate stage), the lint stage must
      create placeholder files so the embed directives resolve. Example:
      `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
-    - If the project requires CGO or system libraries for linting, install them
-      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
-      has no `apk`, so install with `apt-get` under the Debian package name
-      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
-      lists in the same `RUN`, so the layer does not keep them:
-
-        ```dockerfile
-        RUN apt-get update \
-            && apt-get install -y --no-install-recommends libvips-dev \
-            && rm -rf /var/lib/apt/lists/*
-        ```
-
-    - `.dockerignore` lets `.git` into the build context. It keeps out every git
-      `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the
-      repository's own, each submodule's under `.git/modules/`, and that of a
-      submodule keeping its own `.git` directory. `git describe` does not need
-      them, and each can hold a credential: a password in a remote URL, or the
-      token the CI checkout step stores there. A submodule whose name has a
-      `config` segment (`config`, `deploy/config`, `config/lib`) loses its whole
-      git directory to `**/.git/modules/**/config`, and Go's version stamping
-      then fails the build: give it a name without that segment
-      (`git submodule add --name`). The stage that compiles has `git` (the
-      Debian Go image has it; an alpine one needs `apk add --no-cache git`) and
-      takes the version from the `VERSION` build argument when one is given,
-      otherwise from `git describe --tags --always`. That gives the tag on a
-      tagged commit; on a later commit, the tag, the number of commits since it
-      and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no
-      tag is reachable. The stage that compiles also marks its working directory
-      safe for git (`git config --system --add safe.directory /src`): a context
-      sent as a tar stream keeps the sender's file owners, and git refuses a
-      checkout owned by another user, so the version would come out empty.
-      `ARG VERSION` has no default, and the build fails if the context carries
-      `.git` and the version still comes out empty, `dev` or `unknown`. A plain
-      `docker build .` with no build arguments must succeed; a Dockerfile that
-      refuses an empty build argument drops that refusal and keeps the argument.
+      The lint stage should not depend on the actual build output — it exists to
+      fail fast.
+    - If the project requires CGO or system libraries for linting (e.g.
+      `vips-dev`), install them in the lint stage with `apk add`.
+    - 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.

 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` on push, and checks out the repo as its only other step.
-  That script bootstraps, runs the gate phases, and then builds the image, so a
-  successful run means every check passed; a bare `docker build .` does not
-  carry the same guarantee, because its gate phases may come from the cache. The
-  image build is uncached and so runs the gate phases a second time. That is the
-  price of the rule above, and it is worth paying: the image that ships is built
-  from a run of its own gates rather than from a cache entry. A separate
-  workflow limited to `main` by a `branches` list under `on: push` cannot be
-  checked by review: to try a change to it, add the feature branch to that list
-  and push, then remove the branch from the list again before merging. Keep any
-  job in it that publishes behind `if: github.ref_name == 'main'`, so the run
-  from the feature branch publishes nothing.
+  runs `script/cibuild` (which runs `docker build .`) on push. Since the
+  Dockerfile already runs `make check`, a successful build implies all checks
+  pass.

 - Use platform-standard formatters: `black` for Python, `prettier` for
  JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -311,21 +189,14 @@ 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
-  suite that exceeds it fails. Under 20 seconds is the target. A suite between
-  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 (`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` must complete in under 20 seconds. Add a 30-second timeout in the
+  Makefile.

- **The test command should use the conditional verbose rerun pattern.** Run
-  tests without `-v` (verbose) first. If tests fail, automatically rerun with
-  `-v` to show full output. This keeps CI logs and `docker build` output clean
-  on success (just package/suite summaries) while providing full diagnostic
-  detail on failure (every test case, every assertion). The command lives in the
-  `test` phase of the `Dockerfile`, since `script/test` builds that phase; the
-  Makefile form below is the same pattern for any repo-local invocation:
+- **`make test` should use the conditional verbose rerun pattern.** Run tests
+  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
+  show full output. This keeps CI logs and `docker build` output clean on
+  success (just package/suite summaries) while providing full diagnostic detail
+  on failure (every test case, every assertion). The general shell pattern:

    ```makefile
    test:
@@ -338,26 +209,11 @@ style conventions are in separate documents:

    ```makefile
    test:
-    	@go test -count=1 -timeout 90s -race -cover ./... || \
+    	@go test -timeout 30s -race -cover ./... || \
    		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -count=1 -timeout 90s -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 neither run can report a stored pass in place of running the
-    tests. It leaves the build cache alone, so it costs the runtime of the suite
-    and no recompilation.
-
-    That cache is Go's own, separate from Docker's layer cache. Go stores a
-    passing result in its cache directory (`GOCACHE`), and when the same tests
-    run again on unchanged code it prints that result, marked `(cached)`,
-    without running them. That matters on a developer's machine, where this
-    target runs and the directory lasts from one run to the next. The `test`
-    phase of the `Dockerfile` needs no `-count=1`: its base image holds no
-    result for this repo's tests and nothing before its `go test` step runs a
-    test, so there is nothing to replay. `--no-cache` (above) is what makes that
-    step run on an unchanged tree.
-
    Python example:

    ```makefile
@@ -383,84 +239,10 @@ style conventions are in separate documents:
  must be in `.gitignore`. No exceptions.

 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
-  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
-  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
-  setting up a new repo. These patterns are written to `.gitignore`'s own
-  semantics, in which an unanchored pattern already matches at every depth; they
-  are not a `.dockerignore` and must not be transplanted into one unmodified.
-
- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
-  across unmodified leaves secrets in the build context.** Docker matches with
-  `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
-  `*` does not cross `/` and a pattern without a leading `**/` is anchored at
-  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
-  therefore excludes only the copies at the repository root, while `config/.env`
-  and `certs/server.key` still reach the context and can land in an image layer
-  — which is more dangerous than a short file with no secret patterns at all,
-  because it reads as solved and stops anyone looking. Give every
-  depth-independent pattern the `**/` prefix and leave only genuinely
-  root-anchored entries unprefixed: `.claude`, and the repo's own host-built
-  binary, written `/myapp` and never `**/myapp`, which would also match
-  `cmd/myapp/` and delete the package directory from the context. Matching is
-  case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so
-  secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`,
-  and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern
-  also catches something the build needs, re-include it with a negation
-  (`!docs/example.env`); deleting the pattern reopens the exposure for every
-  other file it covers. Fetch the standard `.dockerignore` from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
-  it with the repo's own artifacts.
-
- **In-repo agent scratch belongs in both files, written to each file's own
-  semantics.** `.claude/` holds one worktree per in-flight agent — an entire
-  additional checkout of the repo — so under `COPY . .` the build context
-  inflates by a multiple of the repo and another session's unreviewed work can
-  be copied into an image layer. In `.gitignore` the entry is `.claude/`,
-  unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
-  prefix, because the prefixed form would also delete any nested directory of
-  that name from the build. Anchoring carries a known gap that the canonical
-  `.dockerignore` states in its own comment, since consuming repos receive the
-  file and not the tracker: the directory is created in the agent's working
-  directory, so a repo running agents in subdirectories still ships
-  `services/api/.claude/` and must add its own anchored entry there.
-
- **A plain `docker build .` of a clone stamps the version that
-  `git describe --tags --always` gives**, derived from the `.git` in the build
-  context as the canonical `Dockerfile` above shows. Without its failure check,
-  a missing `git` or an unreadable checkout would leave `-X main.Version=` empty
-  and the build would still exit 0. `script/docker` and `script/cibuild` pass
-  the version they compute on the host; it takes precedence. They do this
-  byte-identically across repos:
-
-    ```sh
-    # Own line: a failing command substitution inside an argument does not
-    # trip `set -e`, so the inline form degrades to an empty constant.
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
-    [ -n "$version" ] || version="unknown"
-    docker build --no-cache \
-        --build-arg VERSION="$version" \
-        -t "$(script/projectname)" .
-    ```
-
-    `--always` makes an untagged repo yield an abbreviated commit hash rather
-    than failing, and the `[ -n "$version" ]` line is the single place the
-    fallback is applied — a live check that fires on a build from an export with
-    no `.git` and on a repository with no commits yet. Do not fold it into the
-    substitution as `|| echo unknown`, which makes the guard unreachable. The
-    Dockerfile's side is `ARG VERSION` in the stage that compiles, declared
-    there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
-    Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
-    the scripts stay byte-identical. One consequence for CI: the standard
-    checkout action clones shallow and fetches no tags, so a repo that embeds a
-    tag-derived version must set `fetch-depth: 0` on its checkout step.
-
- **Verify `.dockerignore` by enumerating the image, not by reading the
-  patterns.** Plant files at the root _and_ at least two directories deep, build
-  a probe image that does `COPY . .`, and list what actually landed
-  (`docker run --rm --entrypoint find IMAGE /app`). The `transferring context`
-  size is not a substitute: a nested secret is a few bytes, and BuildKit
-  transfers only the delta from the previous build.
+  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
+  Fetch the standard `.gitignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  a new repo.

 - **No build artifacts in version control.** Code-derived data (compiled
  bundles, minified output, generated assets) must never be committed to the
@@ -476,56 +258,9 @@ style conventions are in separate documents:
 - Make all changes on a feature branch. You can do whatever you want on a
  feature branch.

- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
-  _NEVER_ be modified by an agent: fetch it from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
-  byte-identical, so that no repo can quietly loosen its own linting. Linter
-  configuration changes are made to the canonical copy in the `prompts` repo and
-  reach consuming repos by re-vendoring; an agent may open a PR against
-  canonical, which only the user merges. One list is exempt from byte-identity,
-  because it cannot be written once for every repo: the `deny` list of the
-  `test-support` depguard rule, where a repo names its own test-support packages
-  by full import path. A repo adds entries there and changes nothing else, and a
-  re-vendor carries its entries forward. The canonical golangci-lint version is
-  v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
-  image
-  (`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
-  which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go`
-  directive must not name a newer Go minor version than the one golangci-lint
-  was built with, or golangci-lint refuses to lint it: this release lints
-  `go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo
-  installs golangci-lint on the host. A repo sets the lint phase digest to the
-  one named here and re-vendors `.golangci.yml` in the same commit, whichever of
-  the two prompted the change: the canonical copy can name linters that an older
-  golangci-lint rejects, and a newer golangci-lint can add linters that
-  `default: all` switches on until the canonical copy disables them.
-
- **`script/bootstrap` installs a pinned tool by comparing versions, never by
-  testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
-  `PATH` only, so on an already-provisioned machine the pin is inert and a
-  version bump is a silent no-op — while the Dockerfile, installing into a clean
-  image, gets the pinned version, so a local `make check` and `make docker` can
-  disagree about what the tool even is. The canonical form:
-    - compares the installed version against the pin over the **whole** version
-      token; a parser that stops at the first `-` reports `2.12.2` for a host
-      running `2.12.2-rc1` and skips the install;
-    - treats absent, non-zero, empty or unrecognised `--version` output as a
-      mismatch, so the failure direction is a redundant install and never a
-      skipped one;
-    - after installing, re-resolves the binary the way callers do — `hash -r`,
-      then through `PATH`, not through the directory the installer wrote to —
-      and fails naming the resolved path, since an install that a shadowing
-      binary hides succeeds while changing nothing any caller sees;
-    - is actually called, and prints the version on both success paths: a
-      function defined and never invoked has the same exit status and the same
-      empty output as one that worked.
-
-    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
-
-    A Go tool a repo needs on the host is installed with `go install` pinned to
-    a commit hash (`go install <package>@<commit hash>`). It is never tracked as
-    a `go.mod` tool dependency or through a `tools.go` file, either of which
-    pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
+- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
+  manually by the user. Fetch from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.

 - When pinning images or packages by hash, add a comment above the reference
  with the version and date (YYYY-MM-DD).
@@ -639,14 +374,12 @@ style conventions are in separate documents:
  settings.

 - Avoid putting files in the repo root unless necessary. Root should contain
-  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
-  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
-  and language-specific config). Everything else goes in a subdirectory.
-  Canonical subdirectory names:
+  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
+  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
+  language-specific config). Everything else goes in a subdirectory. Canonical
+  subdirectory names:
    - `bin/` — executable scripts and tools
-    - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
-      body is a single call into `internal/` or `pkg/`, no project logic in
-      `cmd/`
+    - `cmd/` — Go command entrypoints
    - `configs/` — configuration templates and examples
    - `deploy/` — deployment manifests (k8s, compose, terraform)
    - `docs/` — documentation and markdown (README.md stays in root)
@@ -673,7 +406,3 @@ style conventions are in separate documents:
    - Go: `go.mod`, `go.sum`, `.golangci.yml`
    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
    - Python: `pyproject.toml`
-
- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
-  is never committed under a file or directory named after one agent tool, such
-  as `CLAUDE.md` or `.claude/`, and never split into separate memory files.
@@ -2,15 +2,14 @@

 - take an issue from the `1.0.0` milestone on the tracker; work not yet on the
  tracker gets filed as an issue first
- branch from `next`
+- branch (from `main`)
 - do the work, with tests, in small focused commits
 - record it at the top of Completed Steps (`TODO.md` changes in the same commit
  as the work)
- push the branch and open a PR against `next` whose title ends with
-  ` (closes #N)`
- an independent review gates each merge to `next`; every finding is addressed
-  or explicitly rebutted on the PR
- only the owner merges `next` to `main`
+- push the branch and open a PR whose title ends with ` (closes #N)`
+- an independent review gates the merge; every finding is addressed or
+  explicitly rebutted on the PR
+- merge to `main` once the review passes

 # Status

@@ -29,17 +28,6 @@

 # Completed Steps

- re-vendor the canonical files from `sneak/prompts` commit `dd4027b`:
-  golangci-lint v2.14.0; lint and test are phases of the `Dockerfile`, and
-  `make test` runs the suite under the race detector, so `Dockerfile.lint`,
-  `script/verify-lint-image-pin` and `make test-race` are gone; every
-  `docker build` in `script/` passes `--no-cache`; `.claude/settings.json` is
-  deleted (2026-10-07, https://git.eeqj.de/sneak/sfdupes/issues/95)
-
- cut the narration from `TODO.md` Completed Steps and from the comments in
-  `script/` and both Dockerfiles; §Workflow now branches from and merges to
-  `next` (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/49)
-
 - `make test-race` runs the test suite under the race detector in a cgo-enabled
  container, outside `make check` (2026-10-04,
  https://git.eeqj.de/sneak/sfdupes/issues/18)
@@ -133,24 +121,29 @@

 - stamp the git tag or short commit in a plain `docker build .` instead of `dev`
  (2026-10-02, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/67): `.dockerignore` sends `.git`
-  without `.git/config`; the build stage stamps the `VERSION` build argument,
-  else `git describe --tags --always`, and fails if the context carries `.git`
-  and the version is still empty, `dev` or `unknown`. CI checks out the full
-  history (`fetch-depth: 0`) so it stamps the same value as `make build`.
+  https://git.eeqj.de/sneak/sfdupes/issues/67): `.dockerignore` now sends
+  `.git`, without `.git/config`, and the `Dockerfile` build stage takes the
+  `VERSION` build argument when one is given, otherwise
+  `git describe --tags --always` of that `.git`. The build fails if the context
+  carries `.git` and the version still comes out empty, `dev` or `unknown`. The
+  CI checkout step fetches the full history (`fetch-depth: 0`) so CI sees the
+  tag and stamps the same value as `make build`.

 - replace the 1 KiB end-window sampling with the head/tail plus content-hash
  ladder (2026-09-22, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/61); README "Duplicate detection"
-  documents every rung. A file under 10 MiB is hashed in full, and its `head`,
-  `tail` and `content` all hold that hash. A larger file gets only its 64 KiB
-  `head` and `tail` in the hash phase; the content phase, after the update
-  phase, reads it for `content` (the whole file below 50 MiB, gigabyte-spaced 1
-  MiB samples at or above) only when its size, `head` and `tail` match another
-  record's from this scan or an earlier one, and never reads a file gone or
-  changed since its record was written. `report` and `trees` leave out any
-  record without a `content` hash. The `content` column is part of the version 1
-  schema.
+  https://git.eeqj.de/sneak/sfdupes/issues/61): a file under 10 MiB is hashed in
+  full and compared directly, with no end-window step — its `head`, `tail`, and
+  `content` all hold the whole-file hash. A file at 10 MiB or above gets only
+  the 64 KiB `head` and `tail` in the hash phase; a new content phase, after the
+  update phase, reads it for its `content` hash — the whole file below 50 MiB,
+  gigabyte-spaced 1 MiB samples at or above — only when its size, `head`, and
+  `tail` match another record's, from the same scan or stored by an earlier one,
+  so a stored file gains its content hash when it gains a match. A file that is
+  gone or has changed since its record was written is not read. The `content`
+  column is part of the version 1 schema. `report` and `trees` group by the
+  extended signature and leave out any record without a `content` hash, so the
+  ladder is applied across the whole database. README "Duplicate detection"
+  documents every rung including the probabilistic large-file path.

 - remove the dead `files.dat` references from `Makefile`, `.gitignore` and
  `.dockerignore` (2026-09-21, branch `next`, closes
@@ -158,147 +151,265 @@

 - fix the lint-image pin comments and `FROM` form in `Dockerfile` and
  `Dockerfile.lint` (2026-08-10, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/25): both pins are now the policy
-  `# image:vX.Y.Z, YYYY-MM-DD` comment over a bare `FROM image@sha256:...`,
-  without the false `(Debian-based)` note or the tag; digest unchanged.
-  `script/verify-lint-image-pin` still matches the tagless form, and a tag on
-  one side only is caught as a plain mismatch.
+  https://git.eeqj.de/sneak/sfdupes/issues/25): dropped the false
+  `(Debian-based)` parenthetical (v2.12.1 was Debian too) and the redundant tag,
+  so both pins are the policy `# image:vX.Y.Z, YYYY-MM-DD` comment over a bare
+  `FROM image@sha256:...`. Digest unchanged. `script/verify-lint-image-pin`
+  parses those `FROM` lines and still matches the tagless form; its advice line
+  lost the now meaningless "tag and digest". With no tag in either reference, a
+  tag-only disagreement no longer exists — a one-sided tag is caught as a plain
+  mismatch.

 - run all linting in Docker via `Dockerfile.lint` and `script/lint` (2026-08-10,
  branch `next`, closes https://git.eeqj.de/sneak/sfdupes/issues/46): per the
-  owner ruling the linter is never installed on a host. `Dockerfile.lint` copies
+  owner ruling, the linter runs inside a container invoked through the `script/`
+  entrypoint and is never installed on a host. New root `Dockerfile.lint` COPYs
  the repo into the digest-pinned `golangci/golangci-lint:v2.12.2` image and
-  runs `golangci-lint config verify` and `golangci-lint run` as build steps;
-  `script/lint` builds it. `script/bootstrap` no longer installs or pins the
-  linter, and warns rather than fails when `docker` is absent;
-  `ENV PATH=/home/builder/go/bin:$PATH` went with its `go install`.
-  `script/verify-linter-pin` is retired; `script/verify-lint-image-pin`, a gate
-  in both files, compares their two `FROM` lines and restates neither pin.
-  Traps: nothing inside an image build may shell out to docker, so the
-  `Dockerfile` lint stage calls `golangci-lint` directly and the build stage
-  runs `make test` and `make fmt-check` instead of `make check`, through `make`
-  because the Makefile's `export CGO_ENABLED = 0` only reaches what it invokes.
-  `COPY --from=lint /src/go.sum /dev/null` replaces the copied linter binary as
-  the only edge making the build stage wait for lint; dropping it would end
-  fail-fast linting under a still-green build. `golangci-lint config verify`,
-  included per the ruling, validates from an embedded schema with no network
-  call, but `go mod download` above the gates still needs the network on a cold
-  cache. Verified: `make lint` green with no `golangci-lint` on `PATH`; two
-  back-to-back `script/lint` runs on an untouched tree both ran the linter
-  (27.7s and 28.7s in the lint step, `COPY . .` `CACHED` above); a planted
-  unused variable failed `script/lint`, and failed `make docker` at `[lint 9/9]`
-  with the build stage stopped at `[builder 3/12]`; the drift guard fails on a
-  tag-only, a digest-only and an unreadable reference, naming both sides; under
-  `--network none` config verify passes a valid config and rejects an invalid
-  one; `make docker` green in 5m35s with all six gates run (lint 37.6s, test
-  25.2s reporting `ok sneak.berlin/go/sfdupes 1.938s coverage: 88.5%`, not
-  `(cached)`); in the builder image with the Go test cache off, `--user 0:0`
-  still fails `TestScanHardlinkRunFailsTogether` where the unprivileged user
-  passes. Noted for follow-up, not fixed here: `golangci-lint` warns that
-  `gomodguard` is deprecated since v2.12.0 in favour of `gomodguard_v2`.
+  runs `golangci-lint config verify` and `golangci-lint run` as build steps, so
+  a successful build IS a clean lint; `script/lint` is reduced to building it.
+  `script/bootstrap` loses the `go install`, the pin constants, the version
+  parser and `verify_golangci_lint` outright rather than hardening them — with
+  nothing linting on the host, the `$GOPATH/bin` versus `PATH` problem that
+  motivated them has no subject — and now warns rather than fails when `docker`
+  is absent. Two traps handled. A lint build on an unchanged tree returns
+  success in well under a second having run no linter, which is
+  https://git.eeqj.de/sneak/sfdupes/issues/32 and
+  https://git.eeqj.de/sneak/sfdupes/issues/39 again, so `Dockerfile.lint`
+  carries `ARG CHECK_EPOCH` referenced inside every gate `RUN` (BuildKit hashes
+  the expanded command, not the declaration) and `script/lint` passes
+  `"$(date +%s)-$$"` — the PID matters because two lint runs land inside the
+  same second easily. And nothing inside an image build may shell out to docker,
+  so the main `Dockerfile`'s lint stage now invokes `golangci-lint` directly
+  instead of `make lint`, and its build stage runs `make test` and
+  `make fmt-check` instead of the `make check` aggregate (`make`, not the
+  scripts bare, because the Makefile's `export CGO_ENABLED = 0` only reaches
+  what it invokes). `COPY --from=lint` `/usr/bin/golangci-lint` is replaced by
+  `COPY --from=lint /src/go.sum /dev/null`: the copied binary was the only edge
+  forcing BuildKit to finish linting before the build stage starts, and dropping
+  it without replacing the edge would have ended fail-fast linting silently
+  under a still-green build. That is canonical `REPO_POLICIES.md:107`'s ordering
+  edge, restored. `ENV PATH=/home/builder/go/bin:$PATH` is gone with the
+  `go install` that justified it. `script/verify-linter-pin` is retired, deleted
+  along with its README entry, because both of its subjects ceased to exist in
+  the same change: it compared a linter binary against `GOLANGCI_LINT_VERSION`
+  in `script/bootstrap`, and there is now neither a binary crossing between
+  stages nor a version pin in bootstrap. The drift it guarded has not gone away,
+  it has moved — the linter is still pinned twice, now as the `FROM` line of
+  `Dockerfile.lint` and the `FROM` line of the `Dockerfile` lint stage, with
+  nothing syncing them, which is exactly what
+  https://git.eeqj.de/sneak/sfdupes/issues/42 made a build failure. Its
+  replacement is one new `script/verify-lint-image-pin`, run as a gate in both
+  files, which compares the two references to each other and deliberately
+  restates neither: a hardcoded expected digest would be a third copy and the
+  same drift one file further out. `golangci-lint config verify` is included per
+  the ruling, and the concern about its unpinned live HTTPS schema fetch was
+  measured rather than assumed — under `--network none` the pinned binary both
+  passes a valid config and rejects an invalid one with the jsonschema error, so
+  it validates from an embedded schema and makes no network call of its own. The
+  README scopes that to the gate steps rather than to linting as a whole:
+  `Dockerfile.lint` runs `go mod download` above them, so a cold cache still
+  needs the network and only a warm one lints offline. Verified: `make lint`
+  green with every `PATH` directory containing a `golangci-lint` removed
+  (`/home/user/go/bin`, `/home/user/.local/bin`, `/usr/local/bin`;
+  `command -v golangci-lint` empty); two consecutive `script/lint` runs on an
+  untouched tree both executed the linter, 27.7s and 28.7s in the lint step
+  under distinct epochs with the `COPY . .` layer `CACHED` above them, at 42.2s
+  and 41.8s wall clock — the no-cache rule was not weakened to shorten that.
+  Negative control: a planted `var unusedIssue46Sentinel = 1` failed
+  `script/lint` with
+  `report.go:173:5: var unusedIssue46Sentinel is unused (unused)`, and failed
+  `make docker` at `[lint 9/9]` with the build stage stopped at `[builder 3/12]`
+  — `COPY --from=lint`, `script/bootstrap`, the test gate and `make build` all
+  zero occurrences — then reverted clean. The drift guard fails on a tag-only
+  disagreement, on a digest-only disagreement, and on an unreadable reference,
+  naming both sides. `make docker` green in 5m35s with all six gates executing
+  under one epoch (lint 37.6s, test 25.2s reporting
+  `ok sneak.berlin/go/sfdupes 1.938s coverage: 88.5%`, not `(cached)`). The
+  non-root quirk still holds: in the builder image with the Go test cache off,
+  `--user 0:0` fails `TestScanHardlinkRunFailsTogether` (exit 1) where the
+  unprivileged user passes (exit 0). Noted for follow-up, not fixed here:
+  `golangci-lint` warns that the `gomodguard` linter is deprecated since v2.12.0
+  in favour of `gomodguard_v2`.

 - install the Docker build stage's prerequisites by running `script/bootstrap`
  instead of `apk add --no-cache make` inline (2026-08-09, branch
-  `dockerfile-bootstrap`, closes https://git.eeqj.de/sneak/sfdupes/issues/42):
-  the stage copies `script/` plus `go.mod`/`go.sum` and runs `script/bootstrap`,
-  which ends in `go mod download`, so the separate call to it is gone.
-  `COPY --from=lint /usr/bin/golangci-lint` stays and moves above the bootstrap
-  layer: it is the only edge making this stage depend on the lint stage, so
-  deleting it would end fail-fast linting silently. A new
-  `script/verify-linter-pin`, run in the build stage before bootstrap, fails the
-  build naming both versions unless that copied binary is the version
-  `script/bootstrap` pins; a pin it cannot read is a hard failure, not a skip.
-  `$GOPATH/bin` joins `PATH`, where bootstrap's `go install` lands. The `chown`
-  and `USER builder` still precede `make check`. Verified: the guard fails the
-  build with both versions named when the lint stage's linter is faked to
-  another version, and passes an unmodified build; bootstrap runs clean under
-  Alpine's `sh` and `apk`, finding the copied linter already at the pin; a
-  second build served the bootstrap and dependency layers `CACHED` while both
-  gates ran; a planted `unused` finding failed the build at the lint gate in
-  48.9s with the build stage's `make check` never starting; and the suite run in
-  the image as `--user 0:0` fails `TestScanHardlinkRunFailsTogether`, so the
-  drop to the unprivileged user is still needed. That last check needs the Go
-  test cache off: as root it first reported `ok ... (cached)`, reusing the
-  build-time result. Build times on a noisy shared host: 2m13s on an unchanged
-  tree, 2m17s and 4m29s after a source change, 5m14s cold, which breaches the
-  policy ceiling; `chown -R builder:builder /src /home/builder` walks the module
-  cache and alone varied from 77s to 210s across those builds, and `main`
-  measured 5m03s cold with a 209s `chown`. Filed as
-  https://git.eeqj.de/sneak/sfdupes/issues/43
+  `dockerfile-bootstrap`, closes #42): canonical `REPO_POLICIES.md:97` requires
+  it, and the inline install left the build stage maintaining its own notion of
+  the toolchain — exactly the divergence #24 exists to close, one layer down.
+  The stage now copies `script/` plus `go.mod`/`go.sum` and runs
+  `script/bootstrap`, which ends in `go mod download`, so the separate
+  invocation of that is gone. `COPY --from=lint /usr/bin/golangci-lint` stays,
+  and moves above the bootstrap layer. It is the only edge making this stage
+  depend on the lint stage, so deleting it as redundant would end fail-fast
+  linting silently. Letting bootstrap install its own linter here would have
+  reintroduced the second toolchain and paid for a from-source build of it. What
+  makes the two stages provably one toolchain rather than two that happen to
+  agree is a new `script/verify-linter-pin`, run in the build stage on the
+  binary that arrives from the lint stage, before bootstrap: it fails the build
+  naming both versions unless that binary is the version `script/bootstrap`
+  pins. Bootstrap's own check could not serve that purpose — it reinstalls its
+  pin from source and then verifies whatever `PATH` resolves, so drift
+  self-heals silently and a lint stage image bumped on its own would lint at the
+  new version while `make check` ran at the old one, green. The linter version
+  is pinned in two independent places (the lint stage image digest and
+  `GOLANGCI_LINT_VERSION`) and nothing else keeps them in sync, so a
+  half-applied bump is now a build failure. The pin is read out of
+  `script/bootstrap`, which stays the single source of truth; a pin that cannot
+  be read is a hard failure, not a skip. The check needs no `CHECK_EPOCH`: its
+  only inputs are the copied binary and `script/`, so Docker invalidates the
+  layer exactly when a cached result would stop being true, and it is documented
+  with the other entrypoints in the README. `$GOPATH/bin` joins `PATH` because
+  that is where bootstrap's `go install` lands and bootstrap verifies its
+  installs against what `PATH` resolves — nothing in the image is shadowed by
+  it, the directory does not exist until bootstrap runs. Everything added sits
+  above `ARG CHECK_EPOCH`, and the `chown` and `USER builder` still precede
+  `make check`. Verified: the guard fails the build with both versions named
+  when the lint stage's linter is faked to a different version, and an
+  unmodified build still passes it; bootstrap runs clean under Alpine's `sh` and
+  its `apk` branch, installing `git` and `make` and finding the copied linter
+  already at the pin; a second build served the bootstrap and dependency layers
+  `CACHED` while both gates ran with a fresh epoch; a planted `unused` finding
+  failed the build at the lint gate in 48.9s with the build stage's `make check`
+  never starting; and the suite run in the image as `--user 0:0` fails
+  `TestScanHardlinkRunFailsTogether`, so the drop to the unprivileged user is
+  still load-bearing. That last check needs the Go test cache disabled — the
+  first attempt reported `ok ... (cached)` as root, reusing the result the
+  build-time run had left in the shared cache, which would have read as a pass.
+  Build wall time, on a shared host running many concurrent builds and so noisy:
+  2m13s on an unchanged tree, 2m17s and 4m29s for two builds after a source
+  change, 5m14s cold. Only the cold one breaches the policy ceiling, and not
+  because of this change — `chown -R builder:builder /src /home/builder` walks
+  the module cache and re-runs on every source change, and it alone varied
+  between 77s and 210s across those four builds, which is also the whole spread
+  in the totals. The same cold measurement against `main` is 5m03s with a 209s
+  `chown`. Filed as #43
 - bust the Docker layer cache for the gate steps, so `script/cibuild` and
  `script/docker` cannot report a green they did not earn (2026-08-09, branch
-  `cibuild-cache-bust`, closes https://git.eeqj.de/sneak/sfdupes/issues/32): the
-  `Dockerfile` copies the tree before its gates, so on an unchanged tree Docker
-  served them from cache and the build exited 0 having run nothing. Every
-  `docker build` in `script/` now passes `--no-cache` instead
-  (https://git.eeqj.de/sneak/sfdupes/issues/95). Run as root, the tests fail
-  `TestScanHardlinkRunFailsTogether`, because root reads through the `chmod(0)`
-  the test relies on, so they run as an unprivileged user
+  `cibuild-cache-bust`, closes #32): both scripts were bare `docker build`
+  invocations with no cache control, and the `Dockerfile` copies the tree before
+  running its gates, so on an unchanged tree Docker served those layers from
+  cache and the build exited 0 having executed nothing. That is not hypothetical
+  here — every merge this repo has done is a non-fast-forward merge of an
+  undiverged branch, so each merge commit's tree is byte-identical to the branch
+  head's and each merge CI run was almost certainly a full cache hit; and PR
+  #31's reviewer found `make docker` returning success as a 17-layer cache hit,
+  catching it only by being suspicious. The fix is `ARG CHECK_EPOCH` with the
+  scripts passing `--build-arg CHECK_EPOCH="$(date +%s)"`. Two details make or
+  break it. `ARG` is scoped per stage and this `Dockerfile` has three gates
+  across two — `make fmt-check` and `make lint` in the lint stage, `make check`
+  in the build stage — so a single declaration would have left one stage
+  silently cacheable; it is declared in both. And BuildKit hashes the expanded
+  command, not the declaration, so a declared-but-unreferenced `ARG` invalidates
+  nothing: each gate `RUN` echoes the epoch, which also puts the value in the
+  build log as evidence the layer really ran. Placement is below the dependency
+  layers on purpose — a build that goes cold every time would be a different
+  bug, not a fix. Verified by running each script twice back to back on an
+  unchanged tree under `BUILDKIT_PROGRESS=plain`: all three gates executed on
+  all four runs, each with a fresh epoch in the log (`script/cibuild` 78.8s then
+  61.1s; `script/docker` 61.1s then 53.4s), and thirteen steps were still served
+  `CACHED` in the steady state — the lint stage's `WORKDIR /src`, both
+  `go mod download`s, `apk add`, `adduser`, the `chown`, every `go.mod`/`go.sum`
+  and source copy, the linter copy out of the lint stage, and the binary copy
+  into the runtime stage. The lint stage still gates the build stage: with a
+  deliberate `unused` finding planted in the tree, the build failed at
+  `make lint` in 36.1s and the build-stage `make check` never started. The build
+  stage also still drops to the unprivileged `builder` user before `make check`,
+  which the suite depends on rather than merely prefers: forcing the same image
+  to run the tests as root fails `TestScanHardlinkRunFailsTogether`, because
+  root reads straight through the `chmod(0)` the test uses to prove hard links
+  are read once. This is the local fix only; propagating it to the canonical
+  templates is `prompts` #26
 - check the installed golangci-lint version in `script/bootstrap` instead of
-  only its presence (2026-08-09, branch `bootstrap-version-check`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/24): the version lives only in
-  `GOLANGCI_LINT_VERSION`, with the `go install` module ref derived from it, and
-  any installed version that is not the pin — older, newer, absent or
-  unparseable — is reinstalled. `go install` writes into `GOBIN` (or
-  `GOPATH/bin`) while `make lint` runs the first `golangci-lint` on `PATH`, so
-  bootstrap re-reads the effective version after installing and, on a mismatch,
-  prints both paths and both versions and exits non-zero; it does not reorder
-  `PATH` or delete anyone's binary. The `--version` call keeps its stderr and is
-  bounded by `timeout(1)` where that exists. `git`, `make` and `go` keep
-  presence-only checks. Verified by bootstrapping this host from v2.10.1 to
-  v2.12.2 and again to a no-op, and by stub runs of the script under `dash`
-  covering a thirteen-input version-parse matrix, a shadowed install that must
-  exit non-zero, an install destination not on `PATH`, `GOBIN` set, and a wedged
-  binary that must hit the timeout; `make check` and `make lint` are clean at
-  v2.12.2, so v2.10.1 was not hiding any findings on `main`
+  only its presence (2026-08-09, branch `bootstrap-version-check`, closes #24):
+  `missing golangci-lint` meant any linter already on `PATH` satisfied the
+  check, so the pin was never consulted and the v2.12.2 bump from #3 was inert
+  on every host that already had one — this host ran v2.10.1 against a v2.12.2
+  pin, `make check` went green, and `make docker` then rejected the same commit
+  with findings the local gate never saw. The version now lives in one place,
+  `GOLANGCI_LINT_VERSION`, with the `go install` module ref derived from it so a
+  bump cannot half-apply; a `golangci_lint_version` helper parses
+  `golangci-lint --version` (taking the field after the word `version` and
+  tolerating an optional leading `v`, which the module ref carries and the
+  binary's output does not), and any version that is not the pin — older, newer,
+  absent or unparseable — is reinstalled. The install is then verified against
+  the binary `PATH` actually resolves: `go install` writes into `GOBIN` (or
+  `GOPATH/bin`) while `make lint` runs whichever `golangci-lint` comes first on
+  `PATH`, so a wrong-version one sitting ahead of it — nix, apt, brew, apk, or
+  the `/usr/local/bin` copy the `Dockerfile` builder stage makes — would swallow
+  the install and leave the local gate disagreeing with CI under an affirmative
+  `bootstrap complete`. Bootstrap now re-reads the effective version after
+  installing and, on a mismatch, prints both paths and both versions to stderr
+  and exits non-zero instead of claiming success; it does not reorder anyone's
+  `PATH` or delete their binary. The `--version` call keeps its stderr
+  connected, so a present-but-broken binary says why rather than reinstalling
+  forever in silence, and is bounded by `timeout(1)` where that exists, so a
+  wedged binary cannot hang bootstrap. `git`, `make` and `go` keep their
+  presence-only checks and now say why in a comment: they are host
+  package-manager tools the repo deliberately does not pin, with `go.mod`
+  governing the language version and the digest-pinned images covering
+  reproducible builds. Verified on this host by bootstrapping from v2.10.1 to
+  v2.12.2 and running it again to a no-op, plus stub runs of the real script
+  under `dash` covering a thirteen-input parse matrix (absent, older, newer,
+  host-style, image-style, leading-`v`, stderr-only, empty, non-zero exit,
+  impostor binary, `(devel)`, trailing `version`), a shadowed install that must
+  exit non-zero, an install destination not on `PATH` at all, `GOBIN` set, and a
+  wedged binary that must hit the timeout; `make check` and `make lint` are
+  clean at v2.12.2, so v2.10.1 was not hiding any findings on `main`
 - unwind the hash worker pool on the error path (2026-08-09, branch
-  `hash-pool-cleanup`, closes https://git.eeqj.de/sneak/sfdupes/issues/6): the
-  pool is now an owned, context-aware `hashPool`: every blocking send in the
-  feeder and the workers selects on `ctx.Done()`, `jobs` is closed on every path
-  out, and `hashPhase` defers `pool.stop()`, which cancels and then drains
-  `results` until the last goroutine has exited — draining is what frees a
-  worker already parked on a send. `ctx` is threaded from `cmd.Context()`
-  through `runScan`, `syncScan`, both worker pools and the whole database layer,
-  as the first parameter everywhere. The walk pool gets the same treatment plus
-  a `ctx.Err()` guard after the walk: a cancelled walk yields a partial size
-  census, and every file it never reached looks vanished to the update phase.
-  That phase's own `BeginTx` also fails on the cancelled context before deleting
-  anything, but the guard is the barrier that still holds once an interrupted
-  scan may commit what it has. Tests drive `run(scan)` against a database whose
-  insert trigger aborts and assert that the scan fails instead of hanging and
-  that `runtime.NumGoroutine()` polls back to its pre-scan baseline; others
-  cancel a scan part-way through the walk, deterministically, by counting its
-  own consultations of `ctx.Done()`, and assert that it stops at the guard
-  holding a partial census and a still-populated record index, with every record
-  intact. Direct tests of `sendEvent`, the walk workers, `dispatchDirs`,
-  `feedHashJobs`, `hashWorker` and `hashPhase` cover the remaining cancellation
-  branches of both pools
+  `hash-pool-cleanup`, closes #6): `hashPhase` used to return the moment
+  `recordRun` failed and abandon the pool — the feeder parked forever on a full
+  `jobs` channel and every worker on a full `results` channel. That only stopped
+  being invisible when #4 landed and `runScan` began unwinding instead of
+  calling `os.Exit`. The pool is now an owned, context-aware `hashPool`: every
+  blocking send in the feeder and the workers selects on `ctx.Done()`, `jobs` is
+  closed on every path out, and `hashPhase` defers `pool.stop()`, which cancels
+  and then drains `results` until the last goroutine has exited — draining is
+  what frees a worker already parked on a send. `ctx` is threaded from
+  `cmd.Context()` through `runScan`, `syncScan`, both worker pools and the whole
+  database layer (it is the first parameter everywhere), so #5 can hand this
+  path a signal and needs to add nothing else. The walk pool never leaked,
+  because `walkPhase` always drains its events to close, but it has the same
+  unbounded-send shape and #5 will give it an early return, so it gets the same
+  treatment plus a `ctx.Err()` guard after the walk: a cancelled walk yields a
+  partial size census, and every file it never reached looks vanished to the
+  update phase. That phase's own `BeginTx` fails on the same cancelled context
+  before deleting anything, so the guard is defence in depth rather than the
+  only barrier — but it is the one that survives #5 deciding an interrupted scan
+  may commit what it has. Tests drive `run(scan)` against a database whose
+  insert trigger aborts, and assert both that the scan fails instead of hanging
+  and that `runtime.NumGoroutine()` polls back to its pre-scan baseline; a
+  second set cancels a scan part-way through the walk — deterministically, by
+  counting the scan's own consultations of `ctx.Done()` rather than racing a
+  timer — and asserts that it stops at the guard holding a partial census and a
+  still-populated record index, with every record intact. The remaining
+  cancellation branches of both pools are covered by direct tests of
+  `sendEvent`, the walk workers, `dispatchDirs`, `feedHashJobs`, `hashWorker`
+  and `hashPhase`
 - guarantee the database is closed on every fatal exit path (2026-08-09, branch
-  `db-close-on-fatal`, closes https://git.eeqj.de/sneak/sfdupes/issues/4):
-  `fatalf` and its `os.Exit(1)` are gone, so the deferred `db.Close()` — and
-  with it the SQLite WAL checkpoint — now actually runs when a subcommand fails;
-  `runScan`, `runReport`, `runTrees`, `loadRecords` and `resolveRoots` return
-  errors instead. The single exit point is `run` in `main.go`: it maps a
-  `fatalError` (anything a subcommand returned) to exit 1 and cobra's own
-  argument and flag errors to exit 2, which keeps a runtime failure from being
-  reported as a usage error or printing the usage text. New `main_test.go`
-  drives the CLI in-process and asserts the exit codes from README §Error
-  handling plus the stdout/stderr split, including that a fatal error raised
-  after the database is open leaves no `-wal`/`-shm` sidecar behind for `scan`,
-  `report` or `trees`
+  `db-close-on-fatal`, closes #4): `fatalf` and its `os.Exit(1)` are gone, so
+  the deferred `db.Close()` — and with it the SQLite WAL checkpoint — now
+  actually runs when a subcommand fails; `runScan`, `runReport`, `runTrees`,
+  `loadRecords` and `resolveRoots` return errors instead. The single exit point
+  is `run` in `main.go`: it maps a `fatalError` (anything a subcommand returned)
+  to exit 1 and cobra's own argument and flag errors to exit 2, which keeps a
+  runtime failure from being reported as a usage error or printing the usage
+  text. New `main_test.go` drives the CLI in-process and asserts the exit codes
+  from README §Error handling plus the stdout/stderr split, including that a
+  fatal error raised after the database is open leaves no `-wal`/`-shm` sidecar
+  behind for `scan`, `report` or `trees`
 - update golangci-lint to v2.12.2 with the canonical config (2026-08-09, branch
-  `golangci-v2.12.2`, merged as `38a01bd`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/3): bumped the pinned linter in the
-  `Dockerfile` lint stage and `script/bootstrap` from v2.12.1 to v2.12.2, and
-  replaced `.golangci.yml` with the canonical file — the linter settings (`lll`,
-  `funlen`, `cyclop`, `dupl` thresholds) now live under `linters.settings` per
-  the v2 schema, so they are actually applied; no new lint findings surfaced
+  `golangci-v2.12.2`, merged as `38a01bd`, closes #3): bumped the pinned linter
+  in the `Dockerfile` lint stage and `script/bootstrap` from v2.12.1 to v2.12.2,
+  and replaced `.golangci.yml` with the canonical file — the linter settings
+  (`lll`, `funlen`, `cyclop`, `dupl` thresholds) now live under
+  `linters.settings` per the v2 schema, so they are actually applied; no new
+  lint findings surfaced
 - convert Makefile targets to scripts-to-rule-them-all `script/` entrypoints
-  like the other managed repos (2026-07-26, commit `3abeacf`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/1): all 12 `script/` entrypoints
-  exist (`bootstrap`, `setup`, `projectname`, `test`, `lint`, `fmt`,
-  `fmt-check`, `check`, `docker`, `cibuild`, `precommit`, `install-precommit`)
-  and every Makefile target is now a thin shim over them
+  like the other managed repos (2026-07-26, commit `3abeacf`, closes #1): all 12
+  `script/` entrypoints exist (`bootstrap`, `setup`, `projectname`, `test`,
+  `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
+  `install-precommit`) and every Makefile target is now a thin shim over them,
+  matching the other managed repos
 - make the binary the default Make target (2026-07-24, branch
  `make-default-target`): plain `make` now builds `sfdupes` (previously it ran
  `check` plus `build`); `make build` remains as an alias
@@ -317,7 +428,8 @@
 - announce each operand on stderr before its passes (2026-07-24, branch
  `scan-operand-progress`): with per-operand walk/hash/update cycles, a
  multi-operand run (e.g. `scan /srv/*`) showed pass totals that looked like the
-  whole run's
+  whole run's — an operator watching operand 3 of 14 hash 300k files concluded
+  20M files were being skipped
 - parallel walk (2026-07-24, branch `parallel-walk`): the walk pass was a single
  goroutine and took hours at ~20M files on a busy pool (observed: 22M files in
  4h on a ZFS server); it is now a per-directory worker-pool traversal that
@@ -389,3 +501,6 @@ Accepted divergences (no action):

 - flat single-package layout with `.go` files in the repo root — fine for a
  small single-binary tool per the Go styleguide; the tracker audit agrees
+- `make test` runs without `-race` — the repo mandates `CGO_ENABLED=0` (pure-Go
+  builds) and the race detector requires cgo, so the detector runs in a separate
+  cgo-enabled container, `make test-race`, which is not part of `make check`
@@ -1,9 +1,14 @@
 #!/bin/sh
 # script/bootstrap: install all dependencies needed to build and develop
-# this repo. Idempotent; assumes nothing is present (not git, make, or
-# go). Base tooling comes from nix, apt, brew, or apk (detected in that
-# order). golangci-lint and prettier are never installed: they run via
-# docker only (script/lint, script/fmt, script/fmt-check).
+# this repo. Idempotent: every install is guarded by a check so already
+# installed tools are skipped. Base tooling comes from nix, apt, brew,
+# or apk (detected in that order); assumes nothing is present (not git,
+# make, or go). Neither the linter nor the Markdown formatter is
+# installed: golangci-lint (script/lint) and prettier (script/fmt,
+# script/fmt-check) run via docker only, pinned by hash, so their only
+# prerequisite is a working docker — which is warned about, not
+# installed, because everything except linting, formatting and
+# make test-race works without it.
 set -eu

 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -58,19 +63,26 @@ missing() {
 main() {
    cd "$ROOT"

-    # Deliberately unpinned, so presence is the whole check: go.mod
-    # governs the Go version, and reproducible builds run in the
-    # digest-pinned Docker images.
+    # System tooling, deliberately unpinned: these come from the host
+    # package manager and whatever version it ships is what the host
+    # gets, so a presence check is the right check. The repo pins no
+    # system toolchain versions — the Go language version is governed by
+    # go.mod, and builds that must be reproducible run in the Docker
+    # image, whose base images are pinned by digest.
    if missing git; then pkg_install git git git git; fi
    if missing make; then pkg_install gnumake make make make; fi
    if missing go; then pkg_install go golang go go; fi

-    # Warn, do not fail: only the targets named below, and the
-    # pre-commit hook, need docker.
+    # Linting and Markdown formatting run via docker only, so docker is
+    # their prerequisite rather than something bootstrap installs. Warn,
+    # do not fail: everything except `make lint`, `make fmt`,
+    # `make fmt-check` and `make test-race` — and, through them,
+    # `make check`, `make docker` and the pre-commit hook — works
+    # without it.
    if missing docker; then
-        echo "bootstrap: WARNING: docker not found; make test, make lint," >&2
-        echo "bootstrap: make fmt, make fmt-check, make check and" >&2
-        echo "bootstrap: make docker require it." >&2
+        echo "bootstrap: WARNING: docker not found; make lint, make fmt," >&2
+        echo "bootstrap: make fmt-check, make check, make docker and" >&2
+        echo "bootstrap: make test-race require it." >&2
    fi

    go mod download
@@ -1,28 +1,37 @@
 #!/bin/sh
-# script/cibuild: run the CI build. It bootstraps first: a CI runner
-# checks out and runs this and nothing else, and script/fmt-check runs
-# the formatter on the host, which a pristine checkout cannot do.
-# --no-cache for the same reason as script/docker: the gate phases the
-# final stage depends on are RUN steps, and a cached one is a check that
-# did not run.
+# script/cibuild: run the CI build. The Gitea workflow runs this on
+# push.
+#
+# The Dockerfile runs the gates individually as build steps, not the
+# make check aggregate: the lint stage runs the gofmt check,
+# script/verify-lint-image-pin, golangci-lint config verify and
+# golangci-lint run; the markdown stage runs the prettier check; the
+# build stage, dropped to an unprivileged user, runs make test. None of
+# make lint, make fmt-check or make check appears, because each runs
+# docker, and docker cannot run inside a docker build. Nothing is
+# skipped by that — the linter, gofmt and prettier are invoked directly
+# in their stages, and the build stage's COPY --from lines make those
+# stages prerequisites, so BuildKit must finish them first. Between the
+# three stages everything make check would run has run, which is why a
+# successful build here implies the repo is green.
+#
+# That implication holds only because of CHECK_EPOCH. A COPY layer is
+# invalidated only by changed content, and a rebuild of an unchanged
+# checkout sends the same content, so without a fresh value here Docker
+# serves the gate layers from cache and the build reports a green it
+# never earned. Passing the current epoch invalidates the gate
+# layers on every run while leaving the pinned base images and
+# go mod download cached; see the Dockerfile for the placement. The
+# process id goes in with the epoch so that two runs started in the
+# same second still get different values, the same form script/lint
+# uses.
 set -eu

-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
-ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

 main() {
    cd "$ROOT"
-    "$SCRIPT_DIR/bootstrap"
-    "$SCRIPT_DIR/check"
-    # Own line: a failing command substitution inside an argument does
-    # not trip `set -e`, so the inline form degrades silently to an
-    # empty constant. The VERSION build argument takes precedence over
-    # the version a build stage derives from the .git in the context.
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
-    [ -n "$version" ] || version="unknown"
-    docker build --no-cache \
-        --build-arg VERSION="$version" \
-        -t "$("$SCRIPT_DIR/projectname")" .
+    docker build --build-arg CHECK_EPOCH="$(date +%s)-$$" .
 }

 main "$@"
@@ -1,8 +1,14 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
-# Identical in all repos; the tag comes from script/projectname.
-# --no-cache because the gate phases the final stage depends on are RUN
-# steps, and a cached one is a check that did not run.
+# The tag comes from script/projectname.
+#
+# CHECK_EPOCH is passed for the same reason script/cibuild passes it:
+# without a fresh value Docker serves the gate layers from cache on an
+# unchanged tree and this exits 0 having run none of the lint stage's
+# gates, the markdown stage's prettier gate or the builder stage's test
+# gate. This is the set of gates a developer or reviewer runs by hand,
+# so a cached pass here is the most misleading result the repo can
+# produce. Dependency layers sit above the ARG and stay cached.
 set -eu

 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -10,15 +16,10 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"

 main() {
    cd "$ROOT"
-    # Own line: a failing command substitution inside an argument does
-    # not trip `set -e`, so the inline form degrades silently to an
-    # empty constant. The VERSION build argument takes precedence over
-    # the version a build stage derives from the .git in the context.
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
-    [ -n "$version" ] || version="unknown"
-    docker build --no-cache \
-        --build-arg VERSION="$version" \
-        -t "$("$SCRIPT_DIR/projectname")" .
+    docker build \
+        --build-arg CHECK_EPOCH="$(date +%s)-$$" \
+        -t "$("$SCRIPT_DIR/projectname")" \
+        .
 }

 main "$@"
@@ -2,8 +2,7 @@
 # script/fmt: format all files (writes): the Go sources with gofmt, the
 # Markdown with prettier. prettier is never installed on the host: it
 # runs from the Dockerfile's prettier stage with the repository mounted,
-# as the calling user so the files it rewrites keep their owner. The
-# build passes --no-cache, as every docker build in script/ does. The tag
+# as the calling user so the files it rewrites keep their owner. The tag
 # makes each build replace the previous image instead of leaving another
 # one behind.
 set -eu
@@ -15,7 +14,7 @@ main() {
    cd "$ROOT"
    gofmt -s -w .
    image="$("$SCRIPT_DIR/projectname")-prettier"
-    docker build -q --no-cache --target prettier -t "$image" . >/dev/null
+    docker build -q --target prettier -t "$image" . >/dev/null
    docker run --rm --user "$(id -u):$(id -g)" -v "$ROOT:/src" "$image" \
        prettier --write '**/*.md' --tab-width 4 --prose-wrap always
 }
@@ -26,7 +26,7 @@ main() {

    # Same image as script/fmt; see there.
    image="$("$SCRIPT_DIR/projectname")-prettier"
-    docker build -q --no-cache --target prettier -t "$image" . >/dev/null
+    docker build -q --target prettier -t "$image" . >/dev/null
    if ! docker run --rm -v "$ROOT:/src:ro" "$image" \
        prettier --check '**/*.md' --tab-width 4 --prose-wrap always; then
        echo "prettier: Markdown not formatted; run make fmt" >&2
@@ -1,23 +1,34 @@
 #!/bin/sh
-# script/lint: run the linter. Linting is a phase of the Dockerfile and
-# this builds that phase alone; the linter is never installed or run on
-# a developer host, where a shared result cache and a host-global lock
-# make its answer untrustworthy.
+# script/lint: run the linter. golangci-lint is never installed on a
+# host: it runs via docker only, one way, everywhere — this builds
+# Dockerfile.lint, which COPYs the repo into the digest-pinned
+# golangci-lint image and lints as a build step, so a successful build
+# is a clean lint. The only prerequisite is a working docker. The gate
+# steps make no network calls of their own, but Dockerfile.lint runs
+# `go mod download` above them, so a cold cache does reach the network
+# (as does pulling the pinned image); that layer stays cached, and once
+# it is warm this runs offline until go.mod or go.sum changes.
 #
-# The phase is not the last stage in the file, so it is built only when
-# --target names it. --no-cache because a cached lint layer is a lint
-# that did not run. The tag makes each build replace the previous image
-# instead of leaving a dangling one behind.
+# CHECK_EPOCH is what makes the result mean anything. Without it docker
+# serves the gate layers from cache on an unchanged tree and this exits
+# 0 in well under a second having run no linter. The PID is in the value
+# as well as the epoch because two lint runs land inside the same second
+# easily, and `date +%s` alone would cache the second one.
+#
+# The result is the build's exit status and the image is never used, so
+# --output=type=cacheonly writes none. Without it every run spends
+# seconds exporting an image and leaves it behind untagged.
 set -eu

-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
-ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

 main() {
    cd "$ROOT"
-    docker build --no-cache \
-        --target lint \
-        -t "$("$SCRIPT_DIR/projectname")-lint" .
+    docker build \
+        --build-arg CHECK_EPOCH="$(date +%s)-$$" \
+        --output=type=cacheonly \
+        -f Dockerfile.lint \
+        .
 }

 main "$@"
@@ -1,19 +1,17 @@
 #!/bin/sh
-# script/test: run the test suite. Testing is a phase of the Dockerfile
-# 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, --no-cache because a cached test layer is a test that did not
-# run, and a tag so each build replaces the previous image.
+# script/test: run the test suite. Reruns verbosely on failure so CI
+# logs show which test failed.
 set -eu

-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
-ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

 main() {
    cd "$ROOT"
-    docker build --no-cache \
-        --target test \
-        -t "$("$SCRIPT_DIR/projectname")-test" .
+    go test -timeout 30s -cover ./... || {
+        echo "--- Rerunning with -v for details ---"
+        go test -timeout 30s -v ./...
+        exit 1
+    }
 }

 main "$@"
@@ -0,0 +1,40 @@
+#!/bin/sh
+# script/test-race: run the test suite under the race detector. Not part
+# of script/check.
+#
+# The race detector needs cgo and a C compiler, which the host build
+# never uses, so the tests run in a golang image that has gcc. The
+# checkout is mounted read-only, so the docker daemon must be local. The
+# container starts with empty caches every time: each run downloads the
+# dependencies and compiles them with the detector, which needs the
+# network and takes minutes.
+#
+# The tests run as the calling user, never as root: several of them make
+# a file unreadable and expect reading it to fail, and root reads it
+# anyway. When the caller is root they run as nobody, and then the
+# checkout must be readable by other users. Neither user has a home
+# directory in the image, so HOME is /tmp, where Go puts its build cache.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# golang:1.25-trixie, 2026-10-04. Debian rather than the Alpine image the
+# Dockerfile builds with, because this one includes gcc.
+IMAGE="golang@sha256:2c4c60ef415fbfa5e90300722293bef36c5e63fae17570ce18f580af933dbd73"
+
+main() {
+    user="$(id -u):$(id -g)"
+    if [ "$(id -u)" -eq 0 ]; then
+        user=65534:65534
+    fi
+    docker run --rm \
+        --user "$user" \
+        --env HOME=/tmp \
+        --env CGO_ENABLED=1 \
+        --volume "$ROOT:/src:ro" \
+        --workdir /src \
+        "$IMAGE" \
+        go test -race -timeout 60s ./...
+}
+
+main "$@"
@@ -0,0 +1,84 @@
+#!/bin/sh
+# script/verify-lint-image-pin: fail unless the golangci-lint image
+# referenced by Dockerfile.lint and the one referenced by the main
+# Dockerfile's lint stage are the same image at the same digest. Our own
+# extension to scripts-to-rule-them-all, not one of its entrypoints.
+#
+# The linter version is pinned in two independent files. That is the
+# shape #42 turned into a build failure rather than tolerate: nothing
+# else keeps the two in sync, and a bump applied to one file alone would
+# leave `make lint` and the fail-fast lint stage of `make docker`
+# linting the same tree against different rulesets, both green. This is
+# the single guard that stops it, run as a gate in both files.
+#
+# It deliberately restates neither pin. A hardcoded expected digest here
+# would be a third copy — one more thing to bump, and the same drift one
+# file further out. It compares the two files to each other and knows
+# nothing about which version is correct.
+#
+# A reference that cannot be read is a hard failure, not a skip: a
+# comparison of two empty strings succeeds, which would turn this guard
+# into exactly the unearned green it exists to prevent.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+LINT_DOCKERFILE="Dockerfile.lint"
+MAIN_DOCKERFILE="Dockerfile"
+
+# Echo the single golangci-lint image reference in the named Dockerfile.
+# Scans every argument of every FROM instruction rather than assuming a
+# field position, so `FROM --platform=... img AS stage` reads correctly.
+# Exits non-zero, with a diagnosis, unless there is exactly one.
+lint_image_ref() {
+    file="$1"
+
+    if [ ! -f "$file" ]; then
+        echo "verify-lint-image-pin: $file: not found" >&2
+        return 1
+    fi
+
+    refs="$(
+        awk '
+            toupper($1) == "FROM" {
+                for (i = 2; i <= NF; i++) {
+                    if ($i ~ /^golangci\/golangci-lint[:@]/) {
+                        print $i
+                    }
+                }
+            }
+        ' "$file"
+    )"
+
+    count="$(printf '%s' "$refs" | grep -c . || true)"
+    if [ "$count" -ne 1 ]; then
+        echo "verify-lint-image-pin: $file: expected exactly one" \
+            "golangci/golangci-lint FROM reference, found $count" >&2
+        return 1
+    fi
+
+    printf '%s\n' "$refs"
+}
+
+main() {
+    cd "$ROOT"
+
+    lint_ref="$(lint_image_ref "$LINT_DOCKERFILE")"
+    main_ref="$(lint_image_ref "$MAIN_DOCKERFILE")"
+
+    if [ "$lint_ref" != "$main_ref" ]; then
+        echo "verify-lint-image-pin: the linter image is pinned twice and" \
+            "the two pins disagree:" >&2
+        echo "verify-lint-image-pin:   $LINT_DOCKERFILE: $lint_ref" >&2
+        echo "verify-lint-image-pin:   $MAIN_DOCKERFILE: $main_ref" >&2
+        echo "verify-lint-image-pin: bump both FROM lines together so" \
+            "script/lint and the Dockerfile lint stage keep running the" \
+            "same linter" >&2
+        exit 1
+    fi
+
+    echo "verify-lint-image-pin: $LINT_DOCKERFILE and $MAIN_DOCKERFILE" \
+        "agree on $lint_ref"
+}
+
+main "$@"