Dockerfile.lint

@@ -6,7 +6,9 @@
 #
 # `golangci-lint config verify` is deliberately NOT run here: it
 # fetches its JSON schema over a live, unpinned HTTPS call, which would
-# make linting network-dependent and defeat hash-pinning.
+# make linting network-dependent and defeat hash-pinning. The cost of
+# that: unknown top-level keys in .golangci.yml are silently ignored,
+# so a mistyped or wrong-schema key lints clean while applying nothing.
 #
 # golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-10
 FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS deps

TODO.md

@@ -23,6 +23,20 @@ Rationale, Design, TODO, License, Author) if any are still missing.
 
 # Completed Steps
 
+- 2026-08-10: comment-only corrections to `script/bootstrap`,
+  `script/cibuild`, and `Dockerfile.lint`. The `goimports` pin in
+  `script/bootstrap` was justified by a claim that `script/fmt-check`
+  runs it on the host; it does not (it runs `gofmt -l .` only), so the
+  header now credits `script/fmt` alone. `script/cibuild` still claimed
+  the `Dockerfile` runs `make check`, which stopped being true when
+  linting moved to its own stage; it now describes the lint stage
+  (`make fmt-check` plus `golangci-lint`) and the builder stage
+  (`make test`, `make build`). The `docker`-missing warning in
+  `script/bootstrap` reads as one sentence instead of three fragments
+  each re-prefixed with `bootstrap:`. `Dockerfile.lint` now records the
+  residual risk of omitting `golangci-lint config verify`: unknown
+  top-level keys in `.golangci.yml` are silently ignored, so a mistyped
+  key lints clean while applying nothing. No behaviour changed
 - 2026-08-10: MIT `LICENSE` added at the repository root, closing the
   last gap in `REPO_POLICIES.md`'s required-minimum file list and
   removing the all-rights-reserved default that would otherwise have

script/bootstrap

@@ -4,7 +4,8 @@
 # installed tools are skipped. Base tooling comes from nix, apt, brew,
 # or apk (detected in that order); assumes nothing is present.
 # goimports is installed via `go install` at a pinned commit (never
-# "latest") because script/fmt and script/fmt-check run it on the host.
+# "latest") because script/fmt runs it on the host; script/fmt-check
+# does not (it runs gofmt only).
 # The linter is NOT installed here: golangci-lint runs via docker only
 # (script/lint), pinned by image digest, so its only prerequisite is a
 # working docker.
@@ -77,9 +78,8 @@ main() {
     # Linting runs via docker only (script/lint). Warn, don't fail:
     # everything except `make lint` works without it.
     if missing docker; then
-        echo "bootstrap: WARNING: docker not found; make lint and" >&2
-        echo "bootstrap: make docker require it. Install docker to" >&2
-        echo "bootstrap: run the linter." >&2
+        echo "bootstrap: WARNING: docker not found; install it to" \
+            "run make lint and make docker." >&2
     fi
 
     go mod download

script/cibuild

@@ -1,6 +1,7 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Dockerfile runs make check, so
-# a successful build implies all checks pass.
+# script/cibuild: run the CI build. The Dockerfile's lint stage runs
+# make fmt-check and golangci-lint; its builder stage runs make test
+# and make build. A successful build implies all of those passed.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"