Run every lint in a container via Dockerfile.lint (closes #40)

The linter is no longer installed on the host and no longer invoked
there. script/lint is now `docker build -f Dockerfile.lint .` and
nothing else, with the linter running as a build step, so a successful
build of that file is a clean lint — and it works unchanged where the
docker daemon is remote and bind mounts are impossible.

That removes three host-only failure mechanisms rather than mitigating
them: the result cache keyed on file content rather than location, which
produced a confirmed false green and a string of findings reported
against other checkouts; the host-global $TMPDIR/golangci-lint.lock,
which fails a run with `parallel golangci-lint is running` in a way no
caller can distinguish from findings; and host/container version skew,
which hid thirteen findings on one repo. A container per run has its own
cache, its own lock and a binary pinned by digest.

Resolving the recursion this creates. script/lint is a docker build, so
a Dockerfile that runs `make check` would nest a build inside a build
step where there is no daemon. Fixed by direction, not detection: the
main Dockerfile runs script/test and script/fmt-check individually, with
a comment saying why `make check` must not come back, and script/cibuild
runs script/lint first for fail-fast feedback. script/check still runs
all three, so developers and the pre-commit hook are unaffected.

Dockerfile.lint carries the same CHECK_EPOCH guard as the main image,
with the ARG placed below the dependency layer so only the lint steps
re-run. Blanket --no-cache was rejected: it re-runs the dependency
install on every lint and makes linting network-dependent.

golangci-lint config verify is kept, on measurement rather than
preference. Under the pinned v2.12.2, a bogus top-level key and a bogus
key nested under linters.settings.lll both pass `golangci-lint run` with
exit 0 and `0 issues` while config verify exits 3 and names them; an
unknown linter name fails run and passes config verify. The two catch
disjoint classes, and `run` alone silently ignores the class where a
threshold reads as configured and is not applied. The concern that
config verify fetches its JSON schema over live HTTPS does not hold for
this version: every case reproduced byte-identically under
`docker run --network none`, in a container where `getent hosts
golangci-lint.run` exits 2. The schema is embedded in the pinned binary.

Two canonical forms are superseded and deleted rather than left standing
beside the new one, because consuming repos read these documents
literally and two contradictory canonical script/lint forms is worse
than either. The script/bootstrap golangci-lint install landed for
#28 is removed: nothing invokes
a host linter now, so it can only reintroduce the skew it was written to
close. Its version-enforcement principle — compare version not presence,
re-resolve through PATH after installing, let a mis-parse fall through
to reinstall, and call it — stays documented for any other pinned host
tool. The per-checkout GOLANGCI_LINT_CACHE/TMPDIR wrapper is removed
with it; its entire subject was making a host run trustworthy. Adopting
repos delete .lint-cache/ from .gitignore and .dockerignore too. The Go
multistage lint stage and its COPY --from=lint ordering trick go the
same way: that stage ran `make lint`, which is now a docker build.

Corrected everywhere the claim that a successful docker build implies
lint passed — REPO_POLICIES.md, both repo checklists, the Go styleguide
and the README. The guarantee now belongs to script/cibuild, which runs
both container builds; a bare `docker build .` never lints at all.

Verified in this repo, not only documented: two consecutive script/lint
runs on a byte-identical tree both executed prettier (4.556s and 3.738s,
lint layers DONE with a fresh epoch printed, dependency layers CACHED as
intended); a planted violation failed the build naming the file, and
reverting it went green; a bare `docker build -f Dockerfile.lint .`
failed on the guard; make check, script/docker and script/cibuild all
green with the check layers demonstrably executing; and the main image
build completed without attempting a nested build.

prompts/CODE_STYLEGUIDE_GO.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — Go
-last_modified: 2026-08-09
+last_modified: 2026-08-10
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -111,17 +111,24 @@ last_modified: 2026-08-09
 
 1.  For anything beyond a simple script or tool, or anything that is going to
     run in any sort of "production" anywhere, make sure it passes
-    `golangci-lint`.
+    `golangci-lint`. Run it with `make lint`, which builds `Dockerfile.lint`:
+    the linter runs in a container, always, and is never installed on the host.
+    A `golangci-lint` invoked directly on a shared host reads a result cache
+    keyed on file content rather than location and a host-global lock, so its
+    answer may belong to another checkout entirely.
 
-1.  Write a `Dockerfile` for every repo, even if it only runs the tests and
-    linting. `script/cibuild` and `script/docker` should always make sure that
-    the code is in an able-to-be-compiled state, linted, and any tests run, and
-    the build should fail if linting doesn't pass. That guarantee holds only
-    because those scripts pass a per-invocation `CHECK_EPOCH` build arg that
-    busts the check layers out of the Docker cache; without it an unchanged tree
-    serves those layers from cache and the build reports a green it never ran. A
-    bare `docker build .` fails closed by design, on the `[ -n "$CHECK_EPOCH" ]`
-    guard — always go through `script/cibuild` or `script/docker`. See
+1.  Write a `Dockerfile` for every repo, even if it only runs the tests. It runs
+    the non-lint checks; linting lives in `Dockerfile.lint` and is run by
+    `script/cibuild` before the main build, because `script/lint` is itself a
+    `docker build` and cannot run inside one. So `script/cibuild` is what
+    guarantees the code is in an able-to-be-compiled state, linted, and tested —
+    **a successful `docker build .` on its own does not, because it never
+    lints.** That guarantee holds only because each build passes a
+    per-invocation `CHECK_EPOCH` build arg that busts its check layers out of
+    the Docker cache; without it an unchanged tree serves those layers from
+    cache and the build reports a green it never ran. A bare `docker build .`
+    fails closed by design, on the `[ -n "$CHECK_EPOCH" ]` guard — always go
+    through `script/cibuild`, `script/docker` or `script/lint`. See
     [Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
     for the canonical form.
 

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-08-09
+last_modified: 2026-08-10
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -36,12 +36,23 @@ with your task.
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
 - [ ] `Dockerfile` and `.dockerignore` exist (fetch `.dockerignore` from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`);
-      Dockerfile runs `make check` as a build step, and every stage containing a
-      check-running `RUN` declares `ARG CHECK_EPOCH` with the
-      `RUN [ -n "$CHECK_EPOCH" ] || exit 1` guard immediately below it — see the
-      `CHECK_EPOCH` rule in `REPO_POLICIES.md`. Without them the check layer is
-      served from cache on an unchanged tree and the build reports a green it
-      never ran.
+      Dockerfile runs the **non-lint** checks as build steps (`script/test`,
+      `script/fmt-check`), and every stage containing a check-running `RUN`
+      declares `ARG CHECK_EPOCH` with the `RUN [ -n "$CHECK_EPOCH" ] || exit 1`
+      guard immediately below it — see the `CHECK_EPOCH` rule in
+      `REPO_POLICIES.md`. Without them the check layer is served from cache on
+      an unchanged tree and the build reports a green it never ran.
+- [ ] The `Dockerfile` no longer runs `make check`, and no longer has a `lint`
+      stage or a `COPY --from=lint ... /dev/null` ordering line. This is the
+      item an existing repo most often fails: `script/lint` is now a
+      `docker build`, so both of those nest a docker build inside a build step.
+      Delete the stage; `script/cibuild` running `script/lint` first is what
+      replaces its fail-fast purpose.
+- [ ] `Dockerfile.lint` exists and `script/lint` builds it — see the
+      containerised-lint rule in `REPO_POLICIES.md` for the canonical file. Its
+      base image is pinned by sha256 with a version/date comment, it carries
+      `ARG CHECK_EPOCH` **after** the dependency layer with the guard below it,
+      and it invokes the linter directly rather than through `make lint`.
 - [ ] `.dockerignore` excludes the repo's own host-built artifacts (compiled
       binaries, test binaries, coverage output), written root-anchored —
       `/myapp`, never `**/myapp`, which would also match `cmd/myapp/`. An
@@ -100,13 +111,24 @@ with your task.
       `script/install-precommit`, shimmed by `make hooks`) runs it
 - [ ] README has an **Entrypoints** section documenting the `script/`
       entrypoints and linking the standard
-- [ ] Go: `script/lint` isolates golangci-lint per checkout —
-      `GOLANGCI_LINT_CACHE` and `TMPDIR` both exported into `.lint-cache/`
-      (which is in `.gitignore` and `.dockerignore`), `--allow-serial-runners`
-      passed, and the lock error retried rather than reported as findings. Copy
-      the canonical block from `REPO_POLICIES.md`. Setting only the cache is the
-      common half-fix and leaves `parallel golangci-lint is running` failing
-      runs red.
+- [ ] `script/lint` is the canonical container build and nothing else. No host
+      linter invocation survives anywhere in the repo — grep for the linter's
+      own name in `script/`, the `Makefile` and CI config, not just in
+      `script/lint`. An existing repo is where a second path to the linter is
+      likeliest to exist: a `make lint-fast`, a container-versus-host branch, or
+      a CI step that calls the binary directly.
+- [ ] `script/bootstrap` installs no linter. Delete the golangci-lint install
+      block, its version and ref variables, and its call site: nothing invokes a
+      host linter any more, so all it can still do is put a differently
+      versioned binary where somebody runs it by hand and believes the result.
+- [ ] The per-checkout lint state is gone: no `GOLANGCI_LINT_CACHE` or `TMPDIR`
+      exports, no `--allow-serial-runners`, and `.lint-cache/` removed from
+      `.gitignore` and `.dockerignore`. A container has its own cache and its
+      own lock, so keeping the wrapper leaves two contradictory `script/lint`
+      forms in the fleet.
+- [ ] `script/cibuild` runs `script/lint` before the main `docker build`.
+      Without that line CI never lints at all, because the main image
+      deliberately does not.
 - [ ] `make check` does not modify any files in the repo
 - [ ] `make test` has a 30-second timeout
 - [ ] `make test` runs real tests, not a no-op (at minimum, import/compile
@@ -153,6 +175,9 @@ with your task.
 # Final
 
 - [ ] `make check` passes
-- [ ] `script/cibuild` succeeds (a bare `docker build .` fails closed by design,
-      on the `CHECK_EPOCH` guard)
+- [ ] `make lint` runs twice on an unchanged tree with the lint layer `DONE`
+      both times, never `CACHED` and never sub-second
+- [ ] `script/cibuild` succeeds and runs both container builds (a bare
+      `docker build .` or `docker build -f Dockerfile.lint .` fails closed by
+      design, on the `CHECK_EPOCH` guard)
 - [ ] Commit and merge fixes before starting your actual task

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-08-09
+last_modified: 2026-08-10
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -73,15 +73,27 @@ Template files can be fetched from:
       declared in the stage that compiles, and **no stage calls `git describe`**
       — `.dockerignore` excludes `.git`, so it yields an empty version without
       failing the build.
-    - All Dockerfiles must run `make check` as a build step, and every stage
-      containing a check-running `RUN` must declare `ARG CHECK_EPOCH` with the
-      `RUN [ -n "$CHECK_EPOCH" ] || exit 1` guard immediately below it — see the
-      `CHECK_EPOCH` rule in `REPO_POLICIES.md`. Without them the check layer is
-      served from cache on an unchanged tree and the build reports a green it
-      never ran.
+    - The `Dockerfile` runs the **non-lint** checks as build steps —
+      `script/test` and `script/fmt-check`, never `make check`. `script/lint` is
+      a `docker build` of `Dockerfile.lint`, so `make check` here nests a build
+      inside a build step, where there is no daemon. Put a comment above those
+      `RUN` lines saying so. Every stage containing a check-running `RUN` must
+      declare `ARG CHECK_EPOCH` with the `RUN [ -n "$CHECK_EPOCH" ] || exit 1`
+      guard immediately below it — see the `CHECK_EPOCH` rule in
+      `REPO_POLICIES.md`. Without them the check layer is served from cache on
+      an unchanged tree and the build reports a green it never ran.
     - Server: also builds and runs the application
-    - Non-server: brings up dev environment and runs `make check`
+    - Non-server: brings up dev environment and runs those checks
     - Image pinned by sha256 hash with version/date comment
+- [ ] `Dockerfile.lint` — the lint-only image that `script/lint` builds. Same
+      `ARG CHECK_EPOCH` + guard + expanded-value discipline as above, with the
+      `ARG` placed **after** the dependency layer so only the lint steps re-run.
+      Base image pinned by sha256 with a version/date comment. Go repos use
+      `golangci/golangci-lint` and run both `golangci-lint config verify` and
+      `golangci-lint run`; other repos use the same pattern around their own
+      linter (eslint, ruff, prettier). Copy the canonical file from
+      `REPO_POLICIES.md`. The linter is invoked directly there, never via
+      `make lint`, which would recurse.
 - [ ] Gitea Actions workflow at `.gitea/workflows/check.yml` that runs
       `script/cibuild` on push — reference
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
@@ -108,29 +120,26 @@ are thin shims calling them. Model scripts:
       then `install-precommit`, plus repo-specific init
 - [ ] `script/test` / `make test` — runs real tests, not a no-op (30-second
       timeout)
-- [ ] `script/lint` / `make lint` — runs linter
-    - [ ] Go: exports `GOLANGCI_LINT_CACHE` **and** `TMPDIR` into a
-          `.lint-cache/` directory inside the checkout, above any
-          container-versus-host branch so every path that reaches the linter
-          gets them; passes `--allow-serial-runners` (never
-          `--allow-parallel-runners`); retries on
-          `parallel golangci-lint is running` detected on **stderr** and exits
-          75 with a VOID message on exhaustion. Copy the canonical block from
-          `REPO_POLICIES.md` rather than writing your own: a version that sets
-          only the cache leaves the false-red half live, and one that detects
-          the collision by exit status can retry a real finding away.
-    - [ ] Go: `.lint-cache/` is in both `.gitignore` and `.dockerignore`
+- [ ] `script/lint` / `make lint` — builds `Dockerfile.lint` and nothing else:
+      `epoch="$(date +%s%N)$$"` on its own line, then
+      `docker build --build-arg CHECK_EPOCH="$epoch" -f Dockerfile.lint .`. The
+      linter is never installed on the host and never invoked there. Copy the
+      canonical script from `REPO_POLICIES.md`; it is byte-identical across
+      repos. Without the nonce this script exits 0 on an unchanged tree having
+      linted nothing.
 - [ ] `script/fmt` / `make fmt` — formats code (writes)
 - [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only)
 - [ ] `script/check` / `make check` — runs `test`, `lint`, `fmt-check`; must not
-      modify files
+      modify files. It needs a docker daemon, because `script/lint` is a
+      container build, and it must never be called from inside a build stage
 - [ ] `script/projectname` — outputs the project name (used by `script/docker`
       for the image tag)
 - [ ] `script/docker` / `make docker` — builds Docker image, tagged via
       `script/projectname` (byte-identical across repos); carries the same three
       version lines as `script/cibuild` below, and passes
       `--build-arg CHECK_EPOCH="$epoch"` and `--build-arg VERSION="$version"`
-- [ ] `script/cibuild` — cd to repo root, then, each on its own line:
+- [ ] `script/cibuild` — cd to repo root, run `script/lint` **first** for
+      fail-fast feedback, then, each on its own line:
 
     ```sh
     epoch="$(date +%s%N)$$"
@@ -142,14 +151,17 @@ are thin shims calling them. Model scripts:
         .
     ```
 
-    (what CI runs). Both build args are mandatory, and both assignments must be
-    on their 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 `[ -n "$version" ]` line is a live check that fires on an
-    export with no `.git` and on a repo with no commits — keep it, and do not
-    collapse it into `|| echo unknown`, which makes it unreachable. See the
-    `CHECK_EPOCH` and git-describe rules in `REPO_POLICIES.md` for why each
-    element is load-bearing. A bare `docker build .` fails closed by design.
+    (what CI runs). The `script/lint` call is not optional: the main image does
+    not lint, so without it CI never lints. Both build args are mandatory, and
+    both assignments must be on their 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 `[ -n "$version" ]` line is a live check
+    that fires on an export with no `.git` and on a repo with no commits — keep
+    it, and do not collapse it into `|| echo unknown`, which makes it
+    unreachable. See the `CHECK_EPOCH` and git-describe rules in
+    `REPO_POLICIES.md` for why each element is load-bearing. A bare
+    `docker build .` fails closed by design, and so does a bare
+    `docker build -f Dockerfile.lint .`.
 
 - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check`
 - [ ] `script/install-precommit` — installs the pre-commit hook that runs
@@ -161,7 +173,11 @@ are thin shims calling them. Model scripts:
 # 4. Verify
 
 - [ ] `make check` passes
+- [ ] `make lint` demonstrably runs the linter rather than returning a cached
+      build: run it twice on an unchanged tree and confirm the lint layer says
+      `DONE`, never `CACHED`, both times
 - [ ] `make docker` succeeds
+- [ ] `script/cibuild` succeeds and runs both container builds
 - [ ] No secrets in repo
 - [ ] No mutable image/package references
 - [ ] No unnecessary files in repo root