From b8662b8a9c03cb79ea7a5d68e2a3609086cede85 Mon Sep 17 00:00:00 2001
From: sneak <sneak@sneak.berlin>
Date: Mon, 10 Aug 2026 14:09:20 +0000
Subject: [PATCH] docs: correct stale script headers and record the
 config-verify cost (closes #137)

script/bootstrap credited the goimports pin to script/fmt-check, which
runs gofmt only; the header now credits script/fmt. script/cibuild
still described the Dockerfile as running make check, which stopped
being true once linting moved to its own stage. The docker-missing
warning in script/bootstrap is one sentence instead of three fragments
each carrying the bootstrap: prefix. Dockerfile.lint now states the
residual risk of skipping golangci-lint config verify: unknown
top-level keys in .golangci.yml are ignored silently, so a mistyped key
lints clean and applies nothing.

Comment and message text only; no behaviour changes.
---
 Dockerfile.lint  |  4 +++-
 TODO.md          | 14 ++++++++++++++
 script/bootstrap |  8 ++++----
 script/cibuild   |  5 +++--
 4 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/Dockerfile.lint b/Dockerfile.lint
index 5c236de..4dcb14e 100644
--- a/Dockerfile.lint
+++ b/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
diff --git a/TODO.md b/TODO.md
index b44e872..7bf50f3 100644
--- a/TODO.md
+++ b/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
diff --git a/script/bootstrap b/script/bootstrap
index 0901c87..06da5d0 100755
--- a/script/bootstrap
+++ b/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
diff --git a/script/cibuild b/script/cibuild
index 966f51d..1b9e57d 100755
--- a/script/cibuild
+++ b/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)"