Close three gaps between the containerised-lint rule and its first adopters

The rule landed in 12e8db8 is right; these are the three places where the
canonical text and the repos implementing it can diverge without either
side looking wrong.

1. `.dockerignore` excluding the agent scratch directory is now stated as a
   correctness precondition of containerised linting rather than a
   context-size measure. `Dockerfile.lint` lints whatever `COPY . .` copies,
   and language toolchains discover files by walking the tree instead of
   reading `.gitignore`, so a nested worktree in the context puts the
   foreign-tree false reds back inside the container — in the convincing
   form, where the findings are real but belong to another checkout.
   sneak/quak measured the same discovery mechanism taking a test count
   from 210 to 1050.

2. The cache-bust build arg is fixed at `CHECK_EPOCH` in `Dockerfile.lint`
   as well as in `Dockerfile`. A per-file name is invisible to the grep that
   proves every build is busted, which makes a renamed guard and a missing
   guard read identically. sneak/quak's lint file currently names it
   `LINT_EPOCH`.

3. The formatting check must run in exactly one of the two images, and
   either placement is allowed. Splitting lint out of the `Dockerfile` is
   precisely the moment `fmt-check` gets dropped from both, and running the
   formatter beside the linters is the better shape wherever it is the same
   pinned dependency — it takes the last host toolchain off the checked
   path for the reason the linter came off it.

Both checklists carry the matching items, since a repo that satisfies the
policy prose but not the checklist is the drift this is meant to stop.

Refs #40

Dockerfile

@@ -25,4 +25,13 @@ COPY . .
 # here, not one. Keep both.
 ARG CHECK_EPOCH
 RUN [ -n "$CHECK_EPOCH" ] || exit 1
-RUN echo "check epoch: ${CHECK_EPOCH}" && make check
+
+# The individual non-lint checks, NOT `make check`. Lint is deliberately
+# absent here: `script/lint` is itself a `docker build` (of
+# Dockerfile.lint), so running `make check` in this image would attempt
+# a docker build inside a build step, where there is no daemon. Putting
+# `make check` back reintroduces exactly that recursion. Lint is not
+# skipped — script/cibuild runs script/lint first, in its own container,
+# before this build starts.
+RUN echo "check epoch: ${CHECK_EPOCH}" && script/test
+RUN script/fmt-check

Dockerfile.lint

@@ -0,0 +1,41 @@
+# Lint-only image. `script/lint` builds this file and nothing else: the
+# linter runs as a build step, so a successful build IS a clean lint.
+# Building rather than bind-mounting is what makes it work where the
+# docker daemon is remote and bind mounts are impossible.
+#
+# The linter is invoked directly below rather than through `make lint`.
+# That is not a style choice: `script/lint` IS this build, so calling it
+# from inside would recurse into a docker build with no daemon.
+#
+# This repo's linter is prettier over markdown. A Go repo's version of
+# this file differs only in the base image and the two lint commands;
+# see the containerised-lint rule in prompts/REPO_POLICIES.md.
+#
+# node 22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
+
+WORKDIR /app
+
+# Dependency layer first, and deliberately above the ARG below, so it
+# stays cached and only the lint steps re-run on every invocation.
+# Without that ordering the cache-bust would reinstall dependencies on
+# every lint and make linting network-dependent.
+COPY script/ script/
+COPY package.json yarn.lock ./
+RUN script/bootstrap
+
+COPY . .
+
+# CHECK_EPOCH is a per-invocation nonce supplied by script/lint. Without
+# it an unchanged tree serves the lint layer from cache and the build
+# reports a lint it never ran — a green that proves nothing, which is
+# the whole failure mode this file exists to avoid reintroducing. The
+# guard makes a bare `docker build -f Dockerfile.lint .` fail loudly
+# instead of silently reusing the empty (and therefore stable) cache
+# key. The value is expanded into the lint command as well, so the cache
+# miss does not depend on BuildKit's handling of an unreferenced ARG and
+# the epoch is visible in the build log. Keep both references.
+ARG CHECK_EPOCH
+RUN [ -n "$CHECK_EPOCH" ] || exit 1
+RUN echo "lint epoch: ${CHECK_EPOCH}" && \
+    yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always

README.md

@@ -117,19 +117,25 @@ alpine. We provide:
 - `script/projectname` — output the project name (our own extension); used by
   `script/docker` for the image tag
 - `script/test` — run the test suite (no tests defined here)
-- `script/lint` — lint the markdown files with prettier
+- `script/lint` — lint the markdown files, by building `Dockerfile.lint`. The
+  linter runs in a container, always: it is never installed on the host and
+  never invoked there. Linting happens as a build step, so a successful build is
+  a clean lint, and the same per-invocation `CHECK_EPOCH` nonce used elsewhere
+  is what stops Docker serving that lint from cache on an unchanged tree
 - `script/fmt` — format all markdown files with prettier (writes)
 - `script/fmt-check` — check formatting (read-only)
 - `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
-  extension)
+  extension). Needs a docker daemon, since `script/lint` is a container build
 - `script/docker` — build the Docker image, tagged via `script/projectname`
   (byte-identical across repos); passes the same `CHECK_EPOCH` nonce as
   `script/cibuild`
-- `script/cibuild` — cd to the repo root, assign `epoch="$(date +%s%N)$$"`, then
-  `docker build --build-arg CHECK_EPOCH="$epoch" .` (what CI runs; the image
-  build runs `script/check`, and the per-invocation `CHECK_EPOCH` nonce is what
-  stops Docker serving that check from cache on an unchanged tree — a bare
-  `docker build .` fails closed on purpose)
+- `script/cibuild` — cd to the repo root, run `script/lint` first, then assign
+  `epoch="$(date +%s%N)$$"` and
+  `docker build --build-arg CHECK_EPOCH="$epoch" .` (what CI runs). Two
+  container builds: the lint image, then the main image, which runs
+  `script/test` and `script/fmt-check` but deliberately not `make check` — that
+  would nest a docker build inside a build step. A bare `docker build .` fails
+  closed on purpose
 - `script/precommit` — run by the git pre-commit hook (our own extension); calls
   `script/check`
 - `script/install-precommit` — installs the git pre-commit hook (our own

TODO.md

@@ -21,6 +21,53 @@ fmt-check, and commit.
 
 # Completed Steps
 
+- 2026-08-10: Closed three gaps the containerised-lint rule left between the
+  canonical text and the first repos to implement it. `.dockerignore` excluding
+  the agent scratch directory is now stated as a correctness precondition of
+  that rule rather than a context-size measure: the lint image lints whatever
+  `COPY . .` copies, and toolchains discover files by walking the tree instead
+  of reading `.gitignore`, so a nested worktree puts the foreign-tree false reds
+  back inside the container — `sneak/quak` measured the same discovery mechanism
+  taking a test count from 210 to 1050. The cache-bust arg is fixed at
+  `CHECK_EPOCH` in `Dockerfile.lint` as well, because a per-file name is
+  invisible to the grep that proves every build is busted, making a renamed
+  guard indistinguishable from a missing one. And the formatting check is now
+  required to run in exactly one of the two images, with either placement
+  allowed: splitting lint out of the `Dockerfile` is precisely when `fmt-check`
+  gets dropped from both, and running the formatter beside the linters is the
+  better shape where it is the same pinned dependency.
+- 2026-08-10: Moved every lint run into a container, on the owner's ruling, and
+  made this repo do it rather than merely document it. `script/lint` is now
+  `docker build -f Dockerfile.lint .` and nothing else; the linter is never
+  installed on the host and never invoked there, so a run cannot inherit another
+  checkout's content-keyed result cache, the host-global
+  `$TMPDIR/golangci-lint.lock`, or a host toolchain that differs from the pinned
+  one — the three mechanisms behind a confirmed false green, a string of
+  findings reported against other agents' checkouts, and a container that saw
+  thirteen findings the host missed. Linting runs as a build step, so a
+  successful build is a clean lint, which also works where the docker daemon is
+  remote and bind mounts are impossible. The recursion this creates is resolved
+  by direction rather than by detection: the main `Dockerfile` runs the
+  individual non-lint checks instead of `make check`, and `script/cibuild` runs
+  `script/lint` first, so no build ever nests a build. `Dockerfile.lint` carries
+  the same `CHECK_EPOCH` guard as the main image, with the `ARG` below the
+  dependency layer so only the lint steps re-run — blanket `--no-cache` was
+  rejected because it makes every lint reinstall its dependencies over the
+  network. Two canonical forms were superseded rather than left standing beside
+  the new one, since consuming repos read this document literally: the
+  `script/bootstrap` golangci-lint install (nothing runs a host linter now, so
+  it can only reintroduce skew; the version-enforcement principle stays
+  documented for other pinned host tools) and the per-checkout
+  cache/lock/`.lint-cache` wrapper (its whole subject was making a host run
+  trustworthy). The Go multistage lint stage goes with them: it ran `make lint`,
+  which is now a docker build. `golangci-lint config verify` was kept on
+  measurement, not preference — a bogus config key passes `golangci-lint run`
+  with `0 issues` and fails `config verify`, and every case reproduced
+  byte-identically under `docker run --network none`, so the schema is embedded
+  in the pinned binary and the line costs no network. Verified with two
+  consecutive runs on an unchanged tree both executing the linter, a planted
+  violation caught and reverted, the bare-build guard firing, and the main image
+  building without attempting a nested build.
 - 2026-08-09: Made a golangci-lint result belong to the tree that asked for it.
   REPO_POLICIES.md now carries the canonical Go `script/lint`, which gives the
   linter per-checkout `GOLANGCI_LINT_CACHE` and per-checkout `TMPDIR`. The two

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,31 @@ 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`. The
+      arg is named `CHECK_EPOCH` in this file too — a repo that calls it
+      `LINT_EPOCH` here is missed by the grep that checks every build is
+      cache-busted.
+- [ ] The formatting check runs in exactly one of the two images — either
+      `script/fmt-check` in the `Dockerfile` or the formatter beside the linters
+      in `Dockerfile.lint`, whichever puts it on the pinned toolchain. Neither
+      image running it is the failure to look for here, since moving lint out of
+      the `Dockerfile` is exactly when it gets dropped.
 - [ ] `.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
@@ -50,8 +69,11 @@ with your task.
 - [ ] `.dockerignore` excludes `.claude`, root-anchored and with no `**/`
       prefix. Agent worktrees are entire checkouts of the repo, so they inflate
       the context by a multiple of it and can copy another session's unreviewed
-      work into an image layer. Confirm by enumerating the image, not by reading
-      the file — `.gitignore` hides these from `git status` too.
+      work into an image layer — and `Dockerfile.lint` then lints that checkout
+      as though it were this one, because toolchains discover files by walking
+      the tree and never read `.gitignore` (`sneak/quak`: 210 discovered tests
+      became 1050). Confirm by enumerating the image, not by reading the file —
+      `.gitignore` hides these from `git status` too.
 - [ ] **Do agents in this repo run anywhere other than the repo root?** The
       scratch directory is created in the agent's working directory, so the
       canonical anchored entry misses `services/api/.claude/` in a monorepo with
@@ -100,13 +122,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 +186,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,36 @@ 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. The arg keeps the name `CHECK_EPOCH` in
+      this file as well, so one grep covers both builds.
+    - The formatting check runs in exactly one of the two images: either
+      `script/fmt-check` in the `Dockerfile`, or the formatter beside the
+      linters in `Dockerfile.lint` where that is the same pinned dependency.
+      Never neither, never both.
+    - `.dockerignore` must exclude the agent scratch directory before this image
+      is trusted: it lints whatever is in the build context, and toolchains walk
+      the tree rather than reading `.gitignore`, so an agent worktree that
+      reaches the context is linted as though it were the repo.
 - [ ] 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 +129,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 +160,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 +182,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

script/check

@@ -1,6 +1,13 @@
 #!/bin/sh
 # script/check: run all checks (test, lint, fmt-check). Our own
 # extension to scripts-to-rule-them-all. Must not modify any files.
+#
+# script/lint is a docker build (see Dockerfile.lint), so this script
+# requires a docker daemon. That is deliberate: it is the only way a
+# developer and the pre-commit hook get the same linter CI gets. It also
+# means this script must never be run from inside a build stage — see
+# the comment in Dockerfile, which runs the individual non-lint checks
+# for exactly that reason.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/cibuild

@@ -1,14 +1,21 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Dockerfile runs script/check, but
-# that only proves anything because CHECK_EPOCH is a fresh nonce on every
-# invocation: without it Docker serves the check layer from cache on an
-# unchanged tree and the build exits 0 without running the suite.
+# script/cibuild: run the CI build. Two container builds, in order:
+# script/lint (Dockerfile.lint) and then the main image, which runs the
+# non-lint checks. Both only prove anything because each passes its own
+# fresh CHECK_EPOCH nonce: without it Docker serves the check layers
+# from cache on an unchanged tree and the build exits 0 without running
+# anything.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
+    # Lint first, for fail-fast feedback: it is its own container build
+    # and computes its own CHECK_EPOCH. It runs here rather than inside
+    # the main image because a docker build cannot run a docker build.
+    "$SCRIPT_DIR/lint"
     # Assign on its own line: a failing command substitution inside an
     # argument does not trip `set -e`, which would silently degrade the
     # nonce to an empty constant. `$$` is required because busybox `date`

script/lint

@@ -1,13 +1,27 @@
 #!/bin/sh
-# script/lint: run the linter.
+# script/lint: run the linter. The linter is never installed on the host
+# and never invoked there — it runs in a container, one way, everywhere,
+# so a run cannot inherit another checkout's cache, another process's
+# lock, or a host toolchain that differs from the pinned one. Linting
+# happens as a build step (see Dockerfile.lint), so a successful build
+# is a clean lint, and it works where the docker daemon is remote and
+# bind mounts are impossible.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    echo "Linting markdown files..."
-    yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
+    # Assign on its own line: a failing command substitution inside an
+    # argument does not trip `set -e`, which would silently degrade the
+    # nonce to an empty constant. `$$` is required because busybox `date`
+    # drops %N without erroring. Without a fresh nonce the lint layer is
+    # served from cache and this script exits 0 having linted nothing.
+    epoch="$(date +%s%N)$$"
+    docker build \
+        --build-arg CHECK_EPOCH="$epoch" \
+        -f Dockerfile.lint \
+        .
 }
 
 main "$@"