docs: trim the lint-gate comments to the traps (closes #44)

Comments and documentation only; the docker build invocation and its three
flags are byte-identical and .dockerignore's effective rules are unchanged.

script/lint and Dockerfile.lint stated how the shape was derived — why two
stages, why `golangci-lint config verify` was omitted, what earlier drafts
of the comments claimed. That is in the history. What survives is the three
traps, each of which yields a green run over an unlinted or partly linted
tree: --target and --no-cache-filter must both stay with $stage matching the
stage name in Dockerfile.lint; --target checks that the stage exists, not
that it runs golangci-lint, and halts the build there; and .dockerignore
decides what reaches the container, so excluding a self-contained Go file
drops it from the lint silently.

The TODO.md entry loses its "Hardened" and "Corrected" paragraphs, which
argued with earlier versions of themselves, and keeps the flags, the durable
property, the three unguarded seams, and the evidence that the gate was
verified rather than assumed.

script/lint

@@ -1,51 +1,23 @@
 #!/bin/sh
-# script/lint: run the linter. golangci-lint is never installed locally:
-# it runs via docker only, one way, everywhere — script/lint builds
-# Dockerfile.lint, which COPYs the repo into the pinned golangci-lint
-# image and lints as a build step. This works even when the docker daemon
-# is remote and bind mounts are impossible.
+# script/lint: lint in docker. golangci-lint is never installed on the host.
 #
-# --no-cache-filter forces the lint stage to re-execute every run, so an
-# unchanged tree is still actually linted; the deps stage keeps its cache,
-# so the module download is not repeated. It and --target must both stay,
-# for the reason in the next paragraph: do not "simplify" either of those
-# two away.
+# Traps, each of which yields a green run over an unlinted or partly linted
+# tree:
 #
-# The stage name is written ONCE, in $stage, and passed to both --target
-# and --no-cache-filter, so the two flags cannot come to name different
-# stages. That is the whole point of the variable. BuildKit silently
-# ignores --no-cache-filter when no stage matches its argument: a filter
-# naming a stage that does not exist is a no-op, the lint layer is served
-# from cache, and script/lint reports green having linted nothing — the
-# false green this setup exists to prevent. --target, by contrast, fails
-# loudly on a name that is not in the file. With a single shared name, a
-# typo or a stale rename therefore becomes a hard error instead of a
-# silent skip, because the one name reaches both flags.
+# 1. --target and --no-cache-filter must both stay, and $stage must match
+#    the stage name in Dockerfile.lint. BuildKit ignores --no-cache-filter
+#    when no stage matches its argument, serving the lint layer from cache
+#    without a word; --target rejects a name that is not in the file, which
+#    is what makes the single $stage safe.
 #
-# What the tooling does NOT check, and is left to whoever edits this:
+# 2. --target checks that the stage exists, not that it is the stage
+#    running golangci-lint, and it halts the build there. Moving the lint
+#    step to another stage, or adding a stage after it, is not caught.
 #
-# 1. $stage must name the stage in Dockerfile.lint that actually runs
-#    golangci-lint. --target verifies that the name exists, not that it is
-#    the right stage, and it stops the build at that stage — so moving the
-#    lint step into a different stage, or adding a stage after this one,
-#    would not be caught here. Keep this file and Dockerfile.lint in sync.
-#
-# 2. .dockerignore decides what reaches the container, and only what
-#    reaches it gets linted. Excluding a Go file there removes it from the
-#    lint with no warning: verified by planting a real violation and adding
-#    just that file's path to .dockerignore, which produced `0 issues.` at
-#    exit 0 with the violation still sitting in the working tree. It shows
-#    up only if the rest of the package still references the excluded file,
-#    in which case the build fails loudly on `undefined:` typecheck errors;
-#    a self-contained file drops out silently. So .dockerignore is part of
-#    this gate, not housekeeping — keep it to build inputs the lint does
-#    not read, and never exclude Go sources, go.mod/go.sum or
+# 3. .dockerignore decides what reaches the container, and only what
+#    reaches it is linted. Excluding a self-contained Go file drops it from
+#    the lint silently. Never exclude Go sources, go.mod/go.sum or
 #    .golangci.yml.
-#
-# --output=type=cacheonly skips the image export. Nothing consumes the
-# image — the deliverable of this build is an exit code — and exporting it
-# costs seconds per run and leaves a dangling image behind every time. The
-# lint stage still executes and a lint failure still exits non-zero.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"