Keep in-repo agent scratch out of the build context and out of git (closes #27)

The canonical .dockerignore and .gitignore both omitted the in-repo agent
scratch directory. On this fleet that directory holds one worktree per
in-flight agent -- an entire additional checkout of the repo each -- so under
`COPY . .` all of it reached the build context and the image. Measured on this
repo before the change: five planted scratch files, at every depth beneath the
directory, all present inside a probe image built from the real context.

Three consequences, only the first of which is about size. The context inflates
by a multiple of the repo. Another session's unreviewed and sometimes
uncommitted work is copied into a build artifact. And the directory is created
and destroyed constantly by tooling, so it invalidates `COPY . .` for reasons
that have nothing to do with this repo's content -- which is the accidental
cache protection described at length in the issue thread, and the reason this
change was sequenced behind the CHECK_EPOCH bust rather than landed alongside
the rest of the .dockerignore work.

The two entries are deliberately different shapes, because the two files have
different semantics and neither is derived from the other. In .dockerignore the
entry is anchored, `.claude`, with no `**/` prefix: the directory occurs exactly
once, at the context root, and the prefixed form additionally matches any nested
directory of that name. Measured rather than argued -- the `**/`-prefixed
control was built and enumerated too, and it removes prompts/.claude/ from the
context as well, which in a repo with a legitimately named nested directory
would silently delete it from the build. In .gitignore the entry is unanchored,
`.claude/`, because a .gitignore pattern already matches at every depth;
`git check-ignore -v` confirms it covering both .claude/ and prompts/.claude/,
so a `**/` prefix there would be redundant at best, and on an anchored pattern
it would be actively wrong.

It is not case-folded the way the neighbouring secret patterns are. Tooling
creates the directory in exactly one spelling, and a miss costs context bloat
rather than exposure, so the character-class treatment that the secret names
require would be noise here. The file says so, since the header comment is the
only part of this guidance a consuming repo actually receives.

The second half of this change is the consequence that ships broken silently.
Excluding .git means `git describe` cannot run in any build stage, and it fails
quietly there rather than erroring: `-X main.Version=` comes out empty, the
binary reports no version, and the build still exits 0. The Go template in
REPO_POLICIES.md had `ARG VERSION=dev` and never said where VERSION came from,
which is precisely the gap a reader fills in with `git describe` inside the
build. It now says: computed on the host, threaded in with `--build-arg
VERSION=...`, shown as a complete command rather than as two rules each
documenting half of one. script/docker and script/cibuild do it, with the same
discipline the epoch already has -- assignment on its own line, because a
failing command substitution inside an argument does not trip `set -e`, plus a
non-empty fallback so a build from an export with no .git reports `unknown`
rather than an empty string that reads as a successful version.

The scripts pass VERSION unconditionally rather than growing a per-repo variant.
This repo's Dockerfile declares no `ARG VERSION`, and BuildKit was measured
accepting the unconsumed arg silently -- no warning, no cache effect, confirmed
by the paired runs below in which the bootstrap layer still caches. The
alternative, leaving it to each repo, reintroduces the trap: a repo that needs a
version and finds no VERSION in its scripts writes `git describe` into the
Dockerfile, which is the failure being closed.

The same correction reaches the two Go documents that carry the GOLDFLAGS
pattern, since a `$(shell git describe)` evaluated inside a build stage is
exactly this empty version. Both are now `?=`, so an `ARG VERSION` in the
compiling stage arrives through the environment and wins. Leaving them as `:=`
would have left the corpus telling a reader one thing in the policy and the
opposite in the styleguide.

Both repo checklists gain the entries too. They are what an agent reads while
writing these files, so they are where the wrong shape actually gets written:
the .gitignore item is the one an existing repo never re-fetches, and it now
names `.claude/` explicitly along with the warning not to prefix it.

Verification, by enumerating a probe image rather than by reading the patterns.
Standalone minimal Dockerfile held outside the context, `--no-cache` scoped to
that one image, no prune of any kind. Before: all five planted scratch files in
the image, 42 files total. After: zero, 37 files total, with README.md,
script/check, prompts/NEW_REPO_CHECKLIST.md and a planted probe_src/app.md all
still present as positive controls, so the exclusion is a real exclusion and not
a COPY that stopped copying. Transferred context fell from 161.86kB to 68.82kB,
recorded as corroboration only: BuildKit reports a delta, not a total, and an
earlier run in this repo transferred 2.18kB while shipping 43 files.

The CHECK_EPOCH verification was re-run under the changed context, because the
context moved underneath the earlier measurement. Two consecutive script/cibuild
runs on an unchanged tree: run 1 in 17.07s, run 2 in 5.73s, both executing the
check layer with a distinct epoch and real prettier output from both lint and
fmt-check. The `RUN script/bootstrap` layer is CACHED in run 2, which is the
validity control -- it proves no concurrent prune landed between the runs and
that no --no-cache path was taken, so the check layer executing is the bust
working rather than a cold cache.

Planted files were removed afterwards and their absence confirmed against the
filesystem with `find`, not against `git status`, which cannot see them once
.gitignore covers the directory -- the same blind spot that made the earlier
secret exposure invisible.

.dockerignore

@@ -1,37 +1,60 @@
-# .dockerignore does NOT use .gitignore semantics. Docker matches with
+# Docker matches this file with moby/patternmatcher: Go filepath.Match
-# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
+# semantics plus a `**` extension, compiled to a regexp. Plain
-# `/` and an unprefixed pattern is anchored at the context root. Every
+# filepath.Match has no `**` at all. What follows from that: `*` does not
-# depth-independent pattern therefore needs `**/`, or `config/.env` and
+# cross `/`, and a pattern without a leading `**/` is anchored at the
-# `certs/server.key` still ship while the file reads as solved. Only
+# build-context root. Every depth-independent pattern therefore needs the
-# genuinely root-anchored entries go unprefixed. Never transplant these
+# `**/` prefix — without it `config/.env` and `certs/server.key` still
-# into .gitignore, where `**/` is wrong.
+# ship while the file reads as solved.
 #
-# Matching is case-sensitive, so secrets use character ranges rather
+# Root-anchored entries are for paths that occur exactly once, at the
-# than an ALL-CAPS twin, which would still miss `Server.Key`.
+# context root. A host-built binary is the usual case, and it must be
+# written anchored: `/myapp`, never `**/myapp`. The prefixed form also
+# matches `cmd/myapp/`, which deletes the package directory from the
+# context. In-repo agent scratch is the other case, for the same reason.
 #
-# Extend with this repo's own host-built artifacts, written anchored:
+# Matching is case-sensitive, so `**/*.key` does not match
-# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
+# `certs/SERVER.KEY`, which is reachable on the case-insensitive
-# deletes the package directory from the context.
+# filesystems most laptops use. Adding an ALL-CAPS twin per pattern is
+# not the fix: it still misses `Server.Key` while reading as though case
+# were handled. Character ranges cover every spelling in one line, so
+# every secret name below is written that way — including the
+# extensionless SSH keys and `.envrc`, because on those same
+# case-insensitive filesystems direnv reads `.ENVRC` and ssh reads
+# `ID_RSA`.
+#
+# `**/*.[eE][nN][vV]` also excludes a committed env template such as
+# `example.env`. If the build genuinely needs one, re-include it with a
+# negation after the pattern: `!docs/example.env`.
+#
+# Extend this file with the repo's own host-built artifacts (compiled
+# binaries, test binaries, coverage output); those are per-repo and
+# belong here because a host build otherwise drops them into the
+# context.
 
-# Excluding .git means `git describe` cannot run in any build stage and
+# Repository metadata: exactly one, at the context root. Excluding it
-# fails quietly there; pass the version in with --build-arg VERSION.
+# means `git describe` cannot run in any build stage, and it fails
+# quietly there rather than erroring, so a version embedded that way
+# comes out empty. Compute the version on the host and pass it in with
+# `--build-arg VERSION=...`; see the version rule in REPO_POLICIES.md.
 .git
 
-# Agent scratch: one full checkout of the repo per in-flight agent.
+# In-repo agent scratch: one directory at the context root, holding a
-# Anchored because it occurs once where agents run at the repo root.
+# full additional checkout of the repo for each in-flight agent. Written
-# KNOWN GAP: a repo running agents in subdirectories still ships
+# anchored because it occurs exactly once — the `**/` form would also
-# `services/api/.claude/` and must add its own anchored entry.
+# match a nested directory of that name. Not case-folded, unlike the
+# secret patterns below: tooling creates this in exactly one spelling,
+# and a miss costs build-context bloat rather than exposure.
 .claude
 
-# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# Environment files. `*.env` covers both the bare `.env` name (`*` matches
-# convention. Re-include a committed template with a negation if the
+# the empty string) and the `prod.env` convention.
-# build needs one: `!docs/example.env`.
 **/*.[eE][nN][vV]
 **/.[eE][nN][vV].*
 **/.[eE][nN][vV][rR][cC]
 
-# Private keys and the bundles carrying them. Public certificates
+# Private keys and the bundles that carry them. Public certificates
-# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
+# (*.crt, *.cer) are deliberately absent: they are not secrets and are
+# sometimes a legitimate build input.
 **/*.[pP][eE][mM]
 **/*.[kK][eE][yY]
 **/*.[pP]12
@@ -48,7 +71,8 @@
 **/.DS_Store
 **/Thumbs.db
 
-# Editor state: never a build input, and it churns COPY.
+# Editor state. Never a build input, and it churns under a developer's
+# hands, so it invalidates COPY for reasons unrelated to the source.
 **/*.swp
 **/*.swo
 **/*~

Dockerfile

@@ -3,26 +3,26 @@ FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e3
 
 WORKDIR /app
 
-# Makes script/lint run the linter directly rather than building
+# script/bootstrap installs all prerequisites (make via apk here; node
-# Dockerfile.lint, which would need a docker daemon here.
+# and yarn are already in the base image, so those steps are skipped).
-ENV LINT_IN_CONTAINER=1
+# Dependency manifests are copied first so the bootstrap layer is
-
+# cached until they change.
-# script/bootstrap installs all prerequisites. Manifests are copied
-# first so that layer stays cached until dependencies change.
 COPY script/ script/
 COPY package.json yarn.lock ./
 RUN script/bootstrap
 
 COPY . .
 
-# CHECK_EPOCH is a per-invocation nonce from script/cibuild and
+# CHECK_EPOCH is a per-invocation nonce supplied by script/cibuild and
-# script/docker; without it an unchanged tree serves this layer from
+# script/docker. Without it an unchanged tree serves this layer from
 # cache and the build reports a green it never ran. ARG is stage-scoped,
-# so declare it in every stage that runs checks. The guard fails a bare
+# so it must be redeclared in every stage that runs checks. The guard
-# `docker build .`, which would otherwise reuse the empty (and therefore
+# makes a bare `docker build .` fail loudly instead of silently reusing
-# stable) cache key. The value is also expanded into the check command,
+# the empty (and therefore stable) cache key. Expand the value into the
-# so the cache miss does not depend on BuildKit's handling of an
+# command so the cache miss does not depend on BuildKit's handling of an
-# unreferenced ARG; keep both references.
+# unreferenced ARG. Both the guard and the check RUN reference the value,
+# so both are value-keyed: there are two independent invalidation points
+# here, not one. Keep both.
 ARG CHECK_EPOCH
 RUN [ -n "$CHECK_EPOCH" ] || exit 1
 RUN echo "check epoch: ${CHECK_EPOCH}" && make check

Dockerfile.lint

@@ -1,27 +0,0 @@
-# Lint-only image, built by script/lint when it is not already inside a
-# container. Linting is a build step, so a successful build is a clean
-# lint, and nothing is bind-mounted, which matters when the daemon is
-# remote.
-#
-# node 22-alpine, 2026-02-22
-FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
-
-WORKDIR /app
-
-# Makes script/lint run the linter directly instead of recursing into
-# another docker build, which has no daemon here.
-ENV LINT_IN_CONTAINER=1
-
-COPY script/ script/
-COPY package.json yarn.lock ./
-RUN script/bootstrap
-
-COPY . .
-
-# ARG sits after the dependency layer so that layer stays cached and
-# only the lint re-runs. The guard fails a bare `docker build
-# -f Dockerfile.lint .`, which would otherwise reuse the empty (stable)
-# cache key and report a lint it never ran.
-ARG CHECK_EPOCH
-RUN [ -n "$CHECK_EPOCH" ] || exit 1
-RUN echo "lint epoch: ${CHECK_EPOCH}" && make lint

README.md

@@ -117,9 +117,7 @@ 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. Inside a container
+- `script/lint` — lint the markdown files with prettier
-  (`LINT_IN_CONTAINER=1`, set by both Dockerfiles) it runs prettier directly; on
-  a host it builds `Dockerfile.lint` so the linter still runs in a container
 - `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

TODO.md

@@ -21,82 +21,27 @@ fmt-check, and commit.
 
 # Completed Steps
 
-- 2026-08-10: Moved every lint run into a container. `script/lint` now runs the
-  linter directly when `LINT_IN_CONTAINER=1` and otherwise builds
-  `Dockerfile.lint`, so the linter never runs on a developer host — closing the
-  content-keyed result cache that produced a confirmed false green, the
-  host-global `$TMPDIR/golangci-lint.lock`, and host/container version skew.
-  Detection is on that marker alone: a false negative inside a container fails
-  loudly on the missing daemon, while a false positive on a host would silently
-  restore host linting, so `/.dockerenv` is rejected outright — measured absent
-  inside BuildKit `RUN` steps and present on hosts that are themselves
-  containers. Everything else keeps its existing shape: `make check` still runs
-  in the image, `script/cibuild` is still one build, and the Go multistage lint
-  stage survives with `ENV LINT_IN_CONTAINER=1`. `Dockerfile.lint` carries the
-  same `CHECK_EPOCH` guard, with the `ARG` below the dependency layer so only
-  the lint re-runs. The `script/bootstrap` golangci-lint install and the
-  per-checkout cache/lock/`.lint-cache` wrapper are deleted as superseded; a JS
-  repo's `yarn install` stays, since the rule is about where a verdict comes
-  from, not about which binaries exist. `golangci-lint config verify` was kept
-  on measurement: a bogus config key passes `golangci-lint run` with `0 issues`
-  and fails `config verify`, and every case reproduced byte-identically under
-  `--network none`, so the schema is embedded and the line costs no network.
-  Comment blocks across the touched files were cut hard in the same pass.
-- 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
-  are separate defects and the second is the one that gets dropped: the result
-  cache is keyed on file content rather than location, so checkouts holding
-  identical files serve each other's findings under the other's path, while the
-  concurrency lock is `$TMPDIR/golangci-lint.lock` — host-global, independent of
-  the cache, and unaffected by isolating it. Moving workers from worktrees to
-  their own clones does not help either half; it only removes the foreign-path
-  artefact that made the defect visible. The lock error is retried rather than
-  surfaced, because it is not a result: it exits non-zero exactly as findings
-  do, and reporting it as findings sends a correct branch back for rework.
-  Detection is on the stderr stream and never on exit status, so a finding
-  quoting the lock message in source cannot be retried away, and exhaustion
-  exits 75 with a VOID message rather than passing or failing quietly.
-  `--allow-serial-runners` (which keeps the guard and queues) covers the
-  same-checkout overlap that `TMPDIR` scoping cannot; `--allow-parallel-runners`
-  is rejected outright. The stdout and stderr capture files are per invocation
-  rather than per checkout, because serialising the linter does not serialise
-  the shell's redirections: two runs in one checkout — the overlap the flag
-  exists to support — would otherwise truncate and read each other's output,
-  which is the same defect one layer above where it was fixed. Both checklists
-  gained the corresponding items, since a half-fix that sets only the cache
-  reads as complete. `GOCACHE` was measured and does not need isolating.
-  Verified with the snippet extracted from the committed document and executed
-  as a consuming repo would adopt it, against paired controls: contamination
-  reproduced on the pre-fix form and absent on the adopted one, retry engaged,
-  exhaustion loud, a genuine finding still reported, and a held host lock
-  failing the pre-fix script while leaving the adopted one untouched.
 - 2026-08-09: Kept in-repo agent scratch out of the Docker build context and out
   of version control. `.claude/` holds one worktree — an entire additional
   checkout of the repo — per in-flight agent, and under `COPY . .` all of it was
   reaching the image: another session's unreviewed, sometimes uncommitted work,
   inflating the context by a multiple of the repo and invalidating `COPY` for
   reasons unrelated to the repo's own content. The `.dockerignore` entry is
-  root-anchored, because the directory occurs exactly once where agents run at
+  root-anchored, because the directory occurs exactly once and the `**/` form
-  the repo root and the `**/` form additionally deletes any nested directory of
+  additionally deletes any nested directory of that name; the `.gitignore` entry
-  that name — with the residual gap that follows from anchoring (a monorepo
+  is unanchored, because `.gitignore` patterns already match at every depth, and
-  running agents in subdirectories still ships `services/api/.claude/`) stated
+  each file is written to its own semantics rather than derived from the other.
-  in the canonical `.dockerignore`, the policy and the existing-repo checklist,
+  Also closed the consequence that ships broken silently: excluding `.git` means
-  since consuming repos receive the files rather than the tracker; the
+  `git describe` cannot run in any build stage and yields an empty version
-  `.gitignore` entry is unanchored, because `.gitignore` patterns already match
+  without erroring, so `script/docker` and `script/cibuild` now compute the
-  at every depth, and each file is written to its own semantics rather than
+  version on the host and pass `--build-arg VERSION`, and `REPO_POLICIES.md`
-  derived from the other. Also closed the consequence that ships broken
+  states where `VERSION` comes from instead of leaving the reader to fill the
-  silently: excluding `.git` means `git describe` cannot run in any build stage
+  gap with `git describe` inside the build. The two Go documents that carry the
-  and yields an empty version without erroring, so `script/docker` and
+  `GOLDFLAGS` pattern were corrected in the same pass, from `:=` to `?=`, since
-  `script/cibuild` now compute the version on the host and pass
+  a `$(shell git describe)` evaluated inside a build stage is exactly the empty
-  `--build-arg VERSION`, and `REPO_POLICIES.md` states where `VERSION` comes
+  version this closes. Verified by enumerating a probe image before, after, and
-  from instead of leaving the reader to fill the gap with `git describe` inside
+  against the `**/`-prefixed form, with a positive control and the `CHECK_EPOCH`
-  the build. The two Go documents that carry the `GOLDFLAGS` pattern were
+  cache verification re-run under the changed build context.
-  corrected in the same pass, from `:=` to `?=`, since a `$(shell git describe)`
-  evaluated inside a build stage is exactly the empty version this closes.
-  Verified by enumerating a probe image before, after, and against the
-  `**/`-prefixed form, with a positive control and the `CHECK_EPOCH` cache
-  verification re-run under the changed build context.
 - 2026-08-09: Closed the secret exposure in the canonical `.dockerignore`: a
   developer's local `.env`, `*.pem` or `*.key` was reaching the Docker build
   context under `COPY . .`, invisible to every git-based check because

prompts/CODE_STYLEGUIDE_GO.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — Go
-last_modified: 2026-08-10
+last_modified: 2026-08-09
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -49,19 +49,13 @@ last_modified: 2026-08-10
     ```
 
     ```make
-    # ?= rather than := because this `$(shell git describe ...)` is only
+    # ?= so a Docker build can supply the value. `.dockerignore` excludes
-    # correct on the host. `.dockerignore` excludes `.git`, so evaluated
+    # `.git`, so inside a build stage `$(shell git describe ...)` expands to
-    # inside a build stage it expands to the empty string without failing
+    # the empty string without failing and the binary reports no version at
-    # and the binary reports no version at all. The version is computed on
+    # all. The Dockerfile declares `ARG VERSION` in the stage that compiles,
-    # the host by `script/docker` / `script/cibuild` and passed with
+    # which puts it in the environment where this `?=` defers to it, and
-    # `--build-arg VERSION=...`. If this repo's Dockerfile compiles by
+    # `script/docker` / `script/cibuild` compute it on the host. See the
-    # invoking make (`RUN make build`), `ARG VERSION` in that stage puts the
+    # git-describe rule in REPO_POLICIES.md.
-    # value in the environment and `?=` defers to it. The canonical Go
-    # template in REPO_POLICIES.md instead runs `go build` directly with
-    # `-ldflags "... -X main.Version=${VERSION}"`, so there this Makefile is
-    # a host-only path — but it is still `?=`, because a repo that later
-    # moves the build behind make must not silently start shipping an empty
-    # version. See the git-describe rule in REPO_POLICIES.md.
     VERSION ?= $(shell git describe --always --dirty)
     BUILDARCH := $(shell uname -m)
 
@@ -111,11 +105,7 @@ last_modified: 2026-08-10
 
 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`. Run it with `make lint`, never by invoking the binary: the
+    `golangci-lint`.
-    linter always runs in a container, and `golangci-lint` is not installed on
-    the host by any repo. Invoked directly on a shared host it 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

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-08-10
+last_modified: 2026-08-09
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -42,15 +42,6 @@ with your task.
       `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.
-- [ ] **Every stage that runs checks sets `ENV LINT_IN_CONTAINER=1`** — the lint
-      stage and the build stage both. This is the item an existing repo most
-      often fails after adopting the containerised lint: without it
-      `script/lint` tries to build `Dockerfile.lint` from inside a build step,
-      where there is no daemon.
-- [ ] `Dockerfile.lint` exists and `script/lint` builds it when not already in a
-      container — see the containerised-lint rule in `REPO_POLICIES.md`. Base
-      image pinned by sha256 with a version/date comment, `ARG CHECK_EPOCH`
-      **after** the dependency layer with the guard below it.
 - [ ] `.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
@@ -61,15 +52,6 @@ with your task.
       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.
-- [ ] **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
-      a per-service agent — it still reaches the build context and the image. An
-      existing repo is where such a layout already exists, so check it here
-      rather than assuming the canonical entry covers you: add anchored entries
-      for the subdirectories that have one (`/services/api/.claude`), or
-      `**/.claude` once you have confirmed no legitimately named nested
-      directory would be caught.
 - [ ] If the repo embeds a version in a binary, that version is computed on the
       host and passed with `--build-arg VERSION=...` by `script/docker` and
       `script/cibuild`. No stage calls `git describe`: `.dockerignore` excludes
@@ -109,24 +91,6 @@ 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
-- [ ] `script/lint` is the canonical detect-and-branch form, and no host
-      invocation anywhere in the repo can produce a lint **verdict** — grep for
-      the linter's own name across `script/`, the `Makefile` and CI config, not
-      just `script/lint`. A second path is likeliest here: a `make lint-fast`,
-      an older container-versus-host branch, or a CI step calling the binary
-      directly. **Expected hits that are not the defect**: `script/fmt`, and in
-      a repo whose formatter is also its linter, `script/fmt-check`. Everything
-      else the grep finds is a real second path and goes.
-- [ ] Detection is on `LINT_IN_CONTAINER` alone. Reject any `/.dockerenv` or
-      cgroup heuristic: absent in BuildKit `RUN` steps, present on hosts that
-      are themselves containers, and a false positive lints on the host.
-- [ ] `script/bootstrap` installs no golangci-lint. Delete the block, its
-      version and ref variables, and its call site. A JS repo's `yarn install`
-      stays — it brings a linter along with every other dependency, which is
-      fine as long as no verdict is taken from it.
-- [ ] 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`.
 - [ ] `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
@@ -173,9 +137,6 @@ with your task.
 # Final
 
 - [ ] `make check` passes
-- [ ] `make lint` runs twice on an unchanged tree with the lint layer `DONE`
+- [ ] `script/cibuild` succeeds (a bare `docker build .` fails closed by design,
-      both times, never `CACHED` and never sub-second
+      on the `CHECK_EPOCH` guard)
-- [ ] `script/cibuild` succeeds (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/GO_HTTP_SERVER_CONVENTIONS.md

@@ -991,13 +991,11 @@ func main() {
 Use ldflags to inject version information at build time:
 
 ```makefile
-# ?= rather than := because this `$(shell git describe ...)` is only correct
+# ?= so a Docker build can supply the value. `.dockerignore` excludes `.git`,
-# on the host: `.dockerignore` excludes `.git`, so evaluated inside a build
+# so inside a build stage `$(shell git describe ...)` expands to the empty
-# stage it expands to the empty string without failing and the binary reports
+# string without failing and the binary reports no version. The Dockerfile
-# no version. The version is computed on the host by `script/docker` /
+# declares `ARG VERSION` in the stage that compiles, and `script/docker` /
-# `script/cibuild` and passed with `--build-arg VERSION=...`; where the build
+# `script/cibuild` compute it on the host — see REPO_POLICIES.md.
-# stage invokes make, `ARG VERSION` puts it in the environment and `?=` defers
-# to it. See the git-describe rule in REPO_POLICIES.md.
 VERSION ?= $(shell git describe --tags --always)
 BUILDARCH := $(shell go env GOARCH)
 

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-08-10
+last_modified: 2026-08-09
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -64,10 +64,7 @@ Template files can be fetched from:
       the context root, so the copied form leaves `config/.env` in the build
       context while reading as solved. See the `.dockerignore` rule in
       `REPO_POLICIES.md`. The canonical file's `.claude` entry is anchored for
-      the same reason as a repo-root binary; leave it that way, but note it only
+      the same reason as a repo-root binary; leave it that way.
-      covers agents running at the repo root — if this repo will run them in
-      subdirectories, `services/api/.claude/` is not excluded and needs its own
-      anchored entry.
     - If the image embeds a version in a binary, the version is computed on the
       host and passed with `--build-arg VERSION=...`. `ARG VERSION=dev` is
       declared in the stage that compiles, and **no stage calls `git describe`**
@@ -79,21 +76,9 @@ Template files can be fetched from:
       `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.
-    - Every stage that runs checks sets `ENV LINT_IN_CONTAINER=1`, so
-      `script/lint` runs the linter natively instead of trying to build
-      `Dockerfile.lint` where there is no daemon.
-    - Go repos: separate `lint` stage on the `golangci/golangci-lint` image,
-      with `COPY --from=lint /src/go.sum /dev/null` in the build stage to force
-      the ordering. Re-prove that ordering warm after adopting `CHECK_EPOCH`.
     - Server: also builds and runs the application
     - Non-server: brings up dev environment and runs `make check`
     - Image pinned by sha256 hash with version/date comment
-- [ ] `Dockerfile.lint` — the lint-only image `script/lint` builds when it is
-      not already inside a container. Sets `ENV LINT_IN_CONTAINER=1`; same
-      `ARG CHECK_EPOCH` + guard + expanded-value discipline as above, with the
-      `ARG` **after** the dependency layer so only the lint re-runs. Base image
-      pinned by sha256 with a version/date comment. Copy from
-      `REPO_POLICIES.md`.
 - [ ] 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`
@@ -120,15 +105,7 @@ 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 the linter directly when
+- [ ] `script/lint` / `make lint` — runs linter
-      `LINT_IN_CONTAINER=1`, otherwise `epoch="$(date +%s%N)$$"` on its own line
-      then `docker build --build-arg CHECK_EPOCH="$epoch" -f Dockerfile.lint .`.
-      No lint verdict may come from a host invocation. Copy from
-      `REPO_POLICIES.md`. Detect on `LINT_IN_CONTAINER` only — never
-      `/.dockerenv`, which is absent in BuildKit `RUN` steps and present on
-      hosts that are themselves containers. Without the nonce this exits 0 on an
-      unchanged tree having linted nothing; without `-f Dockerfile.lint` it
-      builds the main image and lints nothing at all.
 - [ ] `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
@@ -136,33 +113,20 @@ are thin shims calling them. Model scripts:
 - [ ] `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
+      `script/projectname` (byte-identical across repos); assigns
-      version lines as `script/cibuild` below, and passes
+      `epoch="$(date +%s%N)$$"` and the `git describe` version on their own
-      `--build-arg CHECK_EPOCH="$epoch"` and `--build-arg VERSION="$version"`
+      lines, and passes `--build-arg CHECK_EPOCH="$epoch"` and
-- [ ] `script/cibuild` — cd to repo root, then, each on its own line:
+      `--build-arg VERSION="$version"`
-
+- [ ] `script/cibuild` — cd to repo root, assign `epoch="$(date +%s%N)$$"` and
-    ```sh
+      `version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"`
-    epoch="$(date +%s%N)$$"
+      on their own lines, then run
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+      `docker build --build-arg CHECK_EPOCH="$epoch" --build-arg VERSION="$version" .`
-    [ -n "$version" ] || version="unknown"
+      (what CI runs). Both build args are mandatory, and both assignments must
-    docker build \
+      be on their own line: a failing command substitution inside an argument
-        --build-arg CHECK_EPOCH="$epoch" \
+      does not trip `set -e`, so the inline form degrades silently to an empty
-        --build-arg VERSION="$version" \
+      constant. 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). 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 .`. The image runs
-    `make check`, which includes lint, so `script/cibuild` needs no separate
-    lint step.
-
 - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check`
 - [ ] `script/install-precommit` — installs the pre-commit hook that runs
       `script/precommit`
@@ -173,11 +137,7 @@ 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 demonstrably executes
 - [ ] No secrets in repo
 - [ ] No mutable image/package references
 - [ ] No unnecessary files in repo root

prompts/REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-08-10
+last_modified: 2026-08-09
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -94,54 +94,37 @@ style conventions are in separate documents:
   reading the Makefile.
 
 - Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
-  as a build step so the build fails if the branch is not green — the one
+  as a build step so the build fails if the branch is not green — which requires
-  exception being `Dockerfile.lint`, which runs `make lint` alone because that
+  `ARG CHECK_EPOCH` and its guard in every stage containing a check-running
-  is its entire purpose — which requires `ARG CHECK_EPOCH` and its guard in
+  `RUN`, per the `CHECK_EPOCH` rule below. Without them a Dockerfile satisfies
-  every stage containing a check-running `RUN`, per the `CHECK_EPOCH` rule
+  this criterion while its check layers are served from cache, so the build
-  below. Without them a Dockerfile satisfies this criterion while its check
+  cannot fail on a branch that is not green. For non-server repos, the
-  layers are served from cache, so the build cannot fail on a branch that is not
+  Dockerfile should bring up a development environment and run `make check`. For
-  green.
+  server repos, `make check` should run as an early build stage before the final
-
+  image is assembled. Dockerfiles install development prerequisites by running
-    **Every Dockerfile must also set `ENV LINT_IN_CONTAINER=1`**, above the
+  `script/bootstrap` rather than duplicating installs inline; COPY `script/` and
-    checks. `script/lint` builds `Dockerfile.lint` when it is not already in a
+  the dependency manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`,
-    container; without the marker it would try that from inside a build step,
+  etc.) before running it so the bootstrap layer stays cached until dependencies
-    where there is no daemon. See the containerised-lint rule below.
+  change.
-
-    For non-server repos, the Dockerfile should bring up a development
-    environment and run `make check`. For server repos, `make check` should run
-    as an early build stage before the final image is assembled. Dockerfiles
-    install development prerequisites by running `script/bootstrap` rather than
-    duplicating installs inline; COPY `script/` and the dependency manifests
-    (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it
-    so the bootstrap layer stays cached until dependencies change.
 
 - **Every check-running `RUN` must be cache-busted with `CHECK_EPOCH`.** Docker
   invalidates a `COPY` layer only when the copied content changes, so on an
-  unchanged tree the check layer is served from cache, the suite never runs, and
+  unchanged tree the `RUN make check` layer is served from cache, the suite
-  the build still exits 0. A sub-second `docker build` reporting success is a
+  never runs, and the build still exits 0. A sub-second `docker build` reporting
-  cache hit, not a result. This applies to **every** file that runs checks in a
+  success is a cache hit, not a result. The canonical form, in **every** stage
-  build step — `Dockerfile` and `Dockerfile.lint` alike; a `Dockerfile.lint`
+  containing a check-running `RUN`:
-  without the cache-bust is a lint that never ran, reported as a pass. The
-  canonical form, in **every** stage containing a check-running `RUN`, placed
-  **after** the dependency-install layer so that layer stays cached:
 
     ```dockerfile
-    ENV LINT_IN_CONTAINER=1
     ARG CHECK_EPOCH
     RUN [ -n "$CHECK_EPOCH" ] || exit 1
     RUN echo "check epoch: ${CHECK_EPOCH}" && make check
     ```
 
-    `ENV LINT_IN_CONTAINER=1` belongs in every such stage too, and is the line
-    most often missed: without it `make check` reaches `script/lint`, which
-    tries to build `Dockerfile.lint` from inside a build step where there is no
-    daemon. See the containerised-lint rule below.
-
     and in both `script/cibuild` and `script/docker`:
 
     ```sh
     epoch="$(date +%s%N)$$"
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \
@@ -149,11 +132,6 @@ style conventions are in separate documents:
         .
     ```
 
-    `script/lint` needs the same nonce but is **not** this command: it builds a
-    different file with `-f Dockerfile.lint` and passes no version. Copy its
-    form from the containerised-lint rule below, not this block — a
-    `docker build` with no `-f` builds the main image and lints nothing.
-
     The `VERSION` lines are there for a different reason, covered by the
     git-describe rule below; they are shown here so the two rules do not each
     document half a command. All four `CHECK_EPOCH` elements are load-bearing;
@@ -184,189 +162,27 @@ style conventions are in separate documents:
       concurrent invocations would collide.
 
     This invalidates the check layers and everything after them while leaving
-    `go mod download` and `script/bootstrap` cached, so it does not push against
+    `go mod download`, `script/bootstrap`, and the pinned toolchain install
-    the five-minute Docker build ceiling. Blanket `--no-cache` is not an
+    cached, so it does not push against the five-minute Docker build ceiling.
-    acceptable substitute: it also busts the dependency layer, so every run
+    Blanket `--no-cache` also works but is wasteful and can blow that ceiling.
-    reinstalls dependencies over the network instead of only the first and those
-    after a manifest change. Never reach for `docker builder prune` — the build
-    cache is shared with every other build on the host.
-
-- **Every lint run happens in a container.** `script/lint` runs the linter
-  directly when it is already inside one, and otherwise builds `Dockerfile.lint`
-  so that it is. Either way the linter never runs on a developer host, where its
-  answer is not trustworthy:
-    - **Confirmed false green.** golangci-lint keys cached results on file
-      **content, not location**, so a second checkout of the same commit serves
-      its findings. One implementer reported `0 issues` on a branch genuinely
-      red with a `goconst` finding. Own-clones-instead-of-worktrees does not
-      help; two clones are byte-identical exactly as two worktrees were.
-    - **False reds**: findings reported against other checkouts and against
-      worktrees already deleted; in one case 399 issues returned to a clean
-      clone that genuinely lints 0.
-    - **Lock contention indistinguishable from findings.** golangci-lint flocks
-      `$TMPDIR/golangci-lint.lock` (`pkg/commands/run.go`, `acquireFileLock()`),
-      host-global and independent of `GOLANGCI_LINT_CACHE`, 5-second timeout. It
-      prints `parallel golangci-lint is running`, analyzes nothing, exits
-      non-zero. Not fixed by per-cache isolation — measured.
-    - **Version skew**: a host linter differing from the pinned one, with the
-      container surfacing thirteen findings the host missed.
-
-    A container has its own cache, its own `TMPDIR` and a binary pinned by
-    digest, so none of it is reachable. This supersedes the per-checkout
-    `GOLANGCI_LINT_CACHE`/`TMPDIR` wrapper, which existed only to make a host
-    run trustworthy; delete it on adoption.
-
-    The canonical `script/lint`, whose executable lines are the same in every
-    repo apart from the native lint command:
-
-    ```sh
-    #!/bin/sh
-    # script/lint: run the linter. Inside a container, run it directly; on a
-    # host, build Dockerfile.lint so it runs in one anyway.
-    #
-    # LINT_IN_CONTAINER is set by this repo's Dockerfiles and is the ONLY
-    # accepted signal. Do not add a /.dockerenv fallback: it is absent inside
-    # BuildKit RUN steps and present on hosts that are themselves containers,
-    # so it both misses and false-positives — and a false positive silently
-    # restores host linting.
-    set -eu
-
-    ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-    main() {
-        cd "$ROOT"
-
-        if [ "${LINT_IN_CONTAINER:-}" = "1" ]; then
-            # config verify lives here, not in a Dockerfile, so every path
-            # that lints inherits it — the lint stage of the main image as
-            # well as Dockerfile.lint. Duplicating it into each Dockerfile
-            # is how one of them silently loses it.
-            golangci-lint config verify --config .golangci.yml
-            exec golangci-lint run --config .golangci.yml ./...
-        fi
-
-        # Own line, and `$$` because busybox `date` drops %N silently.
-        # Without a fresh nonce the lint layer is cached and this exits 0
-        # having linted nothing.
-        epoch="$(date +%s%N)$$"
-        docker build \
-            --build-arg CHECK_EPOCH="$epoch" \
-            -f Dockerfile.lint \
-            .
-    }
-
-    main "$@"
-    ```
-
-    and `Dockerfile.lint`, the standalone path for a developer host:
-
-    ```dockerfile
-    # Lint-only image, built by script/lint when not already in a container.
-    # golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-07
-    FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240
-
-    WORKDIR /src
-    ENV LINT_IN_CONTAINER=1
-
-    COPY go.mod go.sum ./
-    RUN go mod download
-
-    COPY . .
-
-    # ARG after the dependency layer so only the lint re-runs.
-    ARG CHECK_EPOCH
-    RUN [ -n "$CHECK_EPOCH" ] || exit 1
-    RUN echo "lint epoch: ${CHECK_EPOCH}" && make lint
-    ```
-
-    Load-bearing properties:
-    - **Detection rests on `LINT_IN_CONTAINER=1` and nothing else.** Every
-      Dockerfile in the repo sets it; a host does not. The asymmetry is the
-      whole design: a **false negative** inside a container tries a nested
-      `docker build`, finds no daemon and fails loudly, while a **false
-      positive** on a host silently lints there — the exact defect this rule
-      exists to kill. So the signal must be one only our own images can produce.
-      `/.dockerenv` is not such a signal and must not be used, even as a
-      fallback: measured, it is **absent** inside BuildKit `RUN` steps and
-      **present** on any host that is itself a container, which is the common
-      case for CI runners and agent sandboxes. It fails in both directions, and
-      one of them is the dangerous one.
-    - **`CHECK_EPOCH`, not `--no-cache`.** `docker build -f Dockerfile.lint .`
-      on an unchanged tree returns a sub-second cached success having linted
-      nothing. The `ARG` goes **after** the dependency layer so only the lint
-      re-runs; `--no-cache` would also reinstall dependencies on every lint.
-    - **Non-Go repos get the same pattern around their own linter** — `eslint`,
-      `ruff`, `prettier`, `shellcheck`. Only the base image and the native lint
-      command change.
-    - **Keep `golangci-lint config verify`, put it in `script/lint`, and it
-      costs no network.** It goes in the native branch, not in a Dockerfile, so
-      the lint stage of the main image inherits it along with `Dockerfile.lint`;
-      putting it in one Dockerfile leaves the other path unverified. The two
-      commands catch disjoint classes, measured under the pinned v2.12.2: a
-      bogus top-level key and a bogus key under `linters.settings.lll` both pass
-      `golangci-lint run` with **exit 0 and `0 issues`** while `config verify`
-      exits 3 and names them; an invalid value type fails both; an unknown
-      linter name fails `run` and passes `config verify`. So `run` alone
-      silently ignores an unknown key — the mode where a threshold reads as
-      configured and is not applied. It needs no network: 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. Re-run that control when bumping the pin.
-    - **A failed `script/lint` that names no finding is not a lint result.** On
-      the host path `docker build` exits 1 both for findings and for a build
-      that never got there (daemon down, image unpullable, disk full). BuildKit
-      names the failing step; read it, fix the environment, re-run. Do not
-      record a verdict from a run that did not lint.
-
-    **Scope: this rule is about linters, and a formatter is not one.**
-    `script/fmt` writes your working tree, so it can only run on the host, and
-    `script/fmt-check` is its read-only twin. In a repo whose formatter **is**
-    its linter (prettier over markdown; this repo), `script/bootstrap` therefore
-    installs the linter on the host as an ordinary dependency and
-    `script/fmt-check` runs it there. That is accepted: the version is pinned in
-    `package.json` and installed into the repo's own `node_modules`, so there is
-    no shared content-keyed cache, no host-global lock and nothing to skew
-    against. What is forbidden is taking a **lint verdict** from it —
-    `script/lint` stays the only source of one. A repo auditing itself will see
-    those hits and should leave them; anything else the grep finds is a real
-    second path to the linter and goes.
-
-    **What a consuming repo does to adopt this**, in order:
-    1. Add `Dockerfile.lint`.
-    2. Replace `script/lint` with the form above, with its own native lint
-       command.
-    3. Add `ENV LINT_IN_CONTAINER=1` to **every** stage of every Dockerfile that
-       runs checks — the lint stage and the build stage both.
-    4. Delete any golangci-lint install from `script/bootstrap`, with its
-       version and ref variables and its call site. No lint verdict comes from
-       the host any more, so it can only reintroduce version skew. A JS repo's
-       `yarn install` stays.
-    5. Delete the per-checkout lint state: `GOLANGCI_LINT_CACHE` and `TMPDIR`
-       exports, `--allow-serial-runners`, the retry/VOID wrapper, and
-       `.lint-cache/` from both `.gitignore` and `.dockerignore`.
-    6. Verify by running `make lint` twice on an unchanged tree: the lint layer
-       must be `DONE` both times, never `CACHED`. Then plant a violation,
-       confirm it fails naming the finding, revert. A bare
-       `docker build -f Dockerfile.lint .` must fail on the guard.
-
-    `script/check`, `script/cibuild`, `script/docker` and the `Dockerfile` are
-    unchanged by this: `make check` still runs inside the image, and
-    `script/lint` there takes the native path.
 
 - **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
   repos use a multistage build where linting runs in an independent stage based
-  on the `golangci/golangci-lint` image (pinned by hash), so lint failures
+  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
-  surface in seconds rather than after a full compile. The build stage declares
+  `make fmt-check` and `make lint` before the full build begins. The build stage
-  an explicit dependency on it via `COPY --from=lint /src/go.sum /dev/null`,
+  then declares an explicit dependency on the lint stage via
-  which forces BuildKit — which runs stages in parallel by default — to finish
+  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
-  linting first. The canonical Go repo `Dockerfile`:
+  linting before proceeding to compilation and tests. This ensures lint failures
+  surface in seconds rather than minutes, without blocking on dependency
+  download or compilation in the build stage.
+
+    The standard pattern for a Go repo Dockerfile is:
 
     ```dockerfile
     # Lint stage — fast feedback on formatting and lint issues
     # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
     FROM golangci/golangci-lint@sha256:... AS lint
     WORKDIR /src
-    ENV LINT_IN_CONTAINER=1
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
@@ -379,7 +195,6 @@ style conventions are in separate documents:
     # golang:1.x-alpine, YYYY-MM-DD
     FROM golang@sha256:... AS builder
     WORKDIR /src
-    ENV LINT_IN_CONTAINER=1
 
     # Force BuildKit to run the lint stage before proceeding
     COPY --from=lint /src/go.sum /dev/null
@@ -406,36 +221,50 @@ style conventions are in separate documents:
     ```
 
     Key points:
-    - The lint stage uses the `golangci/golangci-lint` image directly (it has
+    - The lint stage uses the `golangci/golangci-lint` image directly (it
-      both Go and the linter), so nothing needs installing. `make lint` there
+      includes both Go and the linter), so there is no need to install the
-      runs `script/lint`, which sees `LINT_IN_CONTAINER=1` and invokes
+      linter separately.
-      `golangci-lint` natively instead of building `Dockerfile.lint`. Without
+    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
-      that `ENV` the stage would attempt a nested build and fail.
+      a stage dependency. BuildKit runs stages in parallel by default; without
-    - `COPY --from=lint /src/go.sum /dev/null` is a no-op copy that exists only
+      this line, the build stage would not wait for lint to finish and a lint
-      to create the stage dependency; without it a lint failure might not fail
+      failure might not fail the overall build.
-      the overall build.
     - **Re-prove that ordering on a warm cache after adopting `CHECK_EPOCH`.**
-      The cache-bust turns the no-op `COPY` into a content-cache hit, so an
+      The cache-bust turns this no-op `COPY` into a content-cache hit, so an
-      ordering guarantee established cold does not automatically carry over. It
+      ordering guarantee established on a cold cache does not automatically
-      was re-proved in another org repo using the same trick and held, but that
+      carry over; it has to be re-checked warm. This was re-proved in another
-      result does not transfer by assumption — re-check it warm.
+      repo in the org that uses the same file-dependency trick (there with a
-    - If the project uses `//go:embed` referencing build artifacts, the lint
+      marker file in place of `go.sum`), and the ordering held. It has **not**
-      stage must create placeholders so the directives resolve:
+      been verified in this repo, which is single-stage and has no lint stage to
-      `RUN mkdir -p web/dist && touch web/dist/index.html`.
+      order against. Any repo relying on a file-dependency trick for stage
-    - If linting needs CGO or system libraries (e.g. `vips-dev`), `apk add` them
+      ordering should re-check it warm after adopting the bust rather than
-      in the lint stage.
+      assuming this result transfers.
-    - Tests run in the build stage, not the lint stage: they may need compiled
+    - If the project uses `//go:embed` directives that reference build artifacts
+      (e.g. a web frontend compiled in a separate stage), the lint stage must
+      create placeholder files so the embed directives resolve. Example:
+      `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
+      The lint stage should not depend on the actual build output — it exists to
+      fail fast.
+    - If the project requires CGO or system libraries for linting (e.g.
+      `vips-dev`), install them in the lint stage with `apk add`.
+    - The build stage runs `make test` after compilation setup. Tests run in the
+      build stage, not the lint stage, because they may require compiled
       artifacts or heavier dependencies.
     - `ARG CHECK_EPOCH` appears in **both** stages, because `ARG` is
       stage-scoped: declaring it only in the lint stage leaves `make test`
-      frozen at its last cached result. In each stage the guard sits immediately
+      frozen at the last cached result. In each stage the guard sits immediately
-      below the `ARG` and the value is expanded into the first check `RUN`.
+      below the `ARG` so a bare `docker build .` fails instead of reusing the
-      Later `RUN`s in the same stage need no expansion; their parent layer is
+      empty cache key, and the value is expanded into the first check `RUN` so
-      already busted.
+      the cache miss does not rely on BuildKit's unreferenced-`ARG` handling.
-    - `ARG VERSION=dev` is declared in the build stage and supplied by
+      Both of those lines reference `$CHECK_EPOCH`, so both are value-keyed:
-      `script/docker` and `script/cibuild`. **No stage may call
+      each stage is invalidated at two independent points. The later `RUN`s in
-      `git describe`**: `.dockerignore` excludes `.git`, so it yields an empty
+      the same stage need no expansion of their own: they are already
-      version without failing. See the git-describe rule further down.
+      invalidated by their busted parent layer.
+    - `ARG VERSION=dev` is declared in the build stage, and its value is
+      supplied on the host by `script/docker` and `script/cibuild` via
+      `--build-arg VERSION=...`. The `dev` default is a placeholder for a local
+      build, not a source of truth. **No stage may call `git describe`**:
+      `.dockerignore` excludes `.git`, so it yields an empty version without
+      failing. See the git-describe rule further down.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
   runs `script/cibuild` (which runs
@@ -445,9 +274,9 @@ style conventions are in separate documents:
   cache-bust described above. Without it, an unchanged tree serves the check
   layer from cache and the build reports a green it never earned. A bare
   `docker build .` fails closed by design, on the `[ -n "$CHECK_EPOCH" ]` guard;
-  always go through `script/cibuild` or `script/docker`. Never accept a pass as
+  always go through `script/cibuild` or `script/docker`. Never accept a
-  evidence without confirming it ran: a sub-second wall time, or `CACHED` on the
+  `script/cibuild` pass as evidence without confirming it ran: a sub-second wall
-  check layer, means nothing was executed.
+  time, or `CACHED` on the check layer, means nothing was executed.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -562,23 +391,10 @@ style conventions are in separate documents:
   reasons that have nothing to do with the repo's own content. In `.gitignore`
   the entry is `.claude/`, unanchored, which already matches at every depth. In
   `.dockerignore` it is `.claude`, anchored and with **no** `**/` prefix: the
-  directory occurs exactly once **where agents run at the repo root**, and the
+  directory occurs exactly once, at the context root, and the prefixed form
-  prefixed form would also match any nested directory of that name and delete it
+  would also match any nested directory of that name. It is not case-folded the
-  from the build. It is not case-folded the way the secret patterns are, because
+  way the secret patterns are, because tooling creates it in exactly one
-  tooling creates it in exactly one spelling, so a folded pattern would add no
+  spelling and a miss costs context bloat rather than exposure.
-  coverage.
-
-    **Known gap that comes with the anchored form.** The directory is created in
-    the agent's working directory, so the "exactly once, at the root" premise is
-    a property of how agents are run and not of the tooling. Where agents run in
-    subdirectories — a monorepo with a per-service agent is the ordinary case —
-    `services/api/.claude/` is **not** excluded by the canonical entry and still
-    reaches the build context and the image, which is the exposure the entry
-    exists to close. A repo in that shape adds its own anchored entries
-    (`/services/api/.claude`), or `**/.claude` once it has confirmed no
-    legitimately named nested directory would be caught. This is stated in the
-    canonical `.dockerignore` itself, since that file is what consuming repos
-    receive.
 
 - **`.dockerignore` matching is case-sensitive, so cover capitalisation with
   character classes rather than by doubling patterns.** `**/*.key` does not
@@ -622,7 +438,7 @@ style conventions are in separate documents:
     # Assign on its own line: a failing command substitution inside an
     # argument does not trip `set -e`, so the inline form degrades to an
     # empty constant — the same silent-empty failure this rule is about.
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \
@@ -631,21 +447,14 @@ style conventions are in separate documents:
     ```
 
     `--always` makes an untagged repo yield the abbreviated commit hash instead
-    of failing. `|| true` keeps a failing `git describe` from tripping `set -e`
+    of failing, and the `unknown` fallback covers a build from an export with no
-    and leaves the value empty, so the `[ -n "$version" ]` line is the single
+    `.git` at all. Both are non-empty by construction: an empty version reads as
-    place the fallback is applied — and it is a **live** check, not defence in
+    a successful one, which is precisely the failure being closed. The
-    depth: it fires on a build from an export with no `.git`, and on a
+    Dockerfile's side is `ARG VERSION=dev` in the stage that compiles, declared
-    repository with no commits yet. Do not fold the fallback into the
+    there and not inherited, because `ARG` is stage-scoped exactly as
-    substitution as `|| echo unknown`; that makes the guard unreachable, and a
+    `CHECK_EPOCH` is. Passing `VERSION` to a repo whose Dockerfile declares no
-    guard that cannot fire is indistinguishable from one that works to everyone
+    such `ARG` is silently ignored by BuildKit and costs nothing, which is why
-    who copies it. The result is non-empty by construction either way, which is
+    the scripts stay byte-identical rather than growing a per-repo variant.
-    the point: an empty version reads as a successful one, while `unknown` is
-    visibly wrong. The Dockerfile's side is `ARG VERSION=dev` in the stage that
-    compiles, declared there and not inherited, because `ARG` is stage-scoped
-    exactly as `CHECK_EPOCH` is. Passing `VERSION` to a repo whose Dockerfile
-    declares no such `ARG` is silently ignored by BuildKit and costs nothing,
-    which is why the scripts stay byte-identical rather than growing a per-repo
-    variant.
 
     One consequence for CI: the standard checkout action clones shallow and
     fetches no tags, so `git describe --tags` there falls back to a bare commit
@@ -669,111 +478,198 @@ style conventions are in separate documents:
 - `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
   manually by the user. Fetch from
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`. The
-  canonical golangci-lint version is v2.12.2 (released 2026-05-06), pinned as
+  canonical golangci-lint version is v2.12.2 (released 2026-05-06), installed
-  the image digest in `Dockerfile.lint`
+  commit-pinned via
-  (`golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240`,
+  `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5`.
-  which reports
-  `golangci-lint has version 2.12.2 built with go1.26.2 from c0d3ddc9`). That
-  digest is the only pin: golangci-lint is not installed on the host by any
-  repo. Bumping the version means changing that one digest.
 
-- **`script/bootstrap` must not install golangci-lint.** This supersedes the
+- **`script/bootstrap` in Go repos must install the pinned golangci-lint
-  pinned host install that used to be canonical here. `script/lint` never runs
+  whenever the installed version does not match the pin — not merely when the
-  it on the host — it either builds `Dockerfile.lint` or is already in a
+  binary is absent — and must then verify the install took effect by
-  container that ships the binary — so a host install has no caller, and its
+  re-resolving the binary through `PATH`.** The presence test
-  only remaining effect is to put a second, independently-versioned linter where
+  `if missing golangci-lint; then go install "$GOLANGCI_LINT_REF"; fi` is wrong:
-  somebody eventually runs it by hand and believes the result. Delete the block,
+  it tests `PATH` presence and never version, so on any already-provisioned
-  its version and ref variables, and its call site.
+  machine the pin is inert and a version bump is a no-op. Meanwhile the
+  Dockerfile installs unconditionally into a clean image, so CI and local
+  silently disagree about what the linter even is. Observed consequences: a
+  local `make check` green while `make docker` rejected the same commit with six
+  `goconst` findings, and a container linter surfacing thirteen findings the
+  host run missed. A stale host linter does not merely fail to prove the tree is
+  clean — it hides findings only the container can see. This is a deliberate
+  departure from the node handling described above, which uses whatever node is
+  installed: the linter version is the specific thing being held equal between
+  host and container, so for it, presence is not enough.
 
-    This is not a ban on host dependency installs generally. A JS or docs repo's
+    Comparing versions is necessary but **not sufficient**, because the obvious
-    `script/bootstrap` runs `yarn install`, which brings its linter along with
+    fix also fails green. `go install` writes to `GOBIN` (or `GOPATH/bin`) while
-    every other dependency; that is unavoidable and fine. The rule is about a
+    callers resolve `golangci-lint` through `PATH`. If a different binary
-    **dedicated** linter install, and about where a verdict may come from.
+    shadows it earlier in `PATH`, the install genuinely succeeds and changes
+    nothing any caller will ever see: bootstrap prints success and the next
+    `make lint` still runs the stale linter. That is worse than no fix, because
+    it converts a known-stale toolchain into one everyone believes is pinned.
+    The canonical form, placed in `script/bootstrap` after Go itself is present:
 
-    **The version-enforcement principle it established still applies to any
+    ```sh
-    other tool a repo pins and installs on the host**, and it is the part worth
+    # golangci-lint v2.12.2, 2026-05-06. GOLANGCI_LINT_VERSION must be exactly
-    keeping, because each of its four properties guards a failure that otherwise
+    # what `golangci-lint --version` prints for this ref; update both together.
-    reports success:
+    GOLANGCI_LINT_VERSION="2.12.2"
-    - **Compare the installed version against the pin, never test presence.** A
+    GOLANGCI_LINT_REF="github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5"
-      `if missing <tool>; then install; fi` guard tests `PATH` presence and
+
-      never version, so on any already-provisioned machine the pin is inert and
+    # The version golangci-lint reports, resolved the way callers resolve it.
-      a version bump is a silent no-op. Compare the **whole** version token,
+    # Prints nothing when the binary is absent, exits non-zero, or prints
-      exactly: a parser that stops at the first `-` reports `2.12.2` for a host
+    # something unparseable: all of those must read as "does not match".
-      running `2.12.2-rc1` and skips the install — the original defect,
+    # The capture is the whole version token, not just its numeric prefix.
-      reintroduced through the comparison meant to fix it.
+    # Stopping at the first `-` would make 2.12.2-rc1 compare equal to 2.12.2
+    # and skip the install, which is the defect this whole rule exists to close.
+    # The trailing `|| true` is required, not tidiness. Under `set -o pipefail`
+    # a non-zero --version would otherwise propagate out of the pipeline and
+    # kill the script through `set -e` before the diagnostic below is printed.
+    golangci_lint_version() {
+        command -v golangci-lint >/dev/null 2>&1 || return 0
+        golangci-lint --version 2>/dev/null | head -n 1 |
+            sed -n 's/.*has version v\{0,1\}\([0-9][^ ]*\).*/\1/p' || true
+    }
+
+    ensure_golangci_lint() {
+        if [ "$(golangci_lint_version)" = "$GOLANGCI_LINT_VERSION" ]; then
+            echo "bootstrap: golangci-lint $GOLANGCI_LINT_VERSION already installed"
+            return 0
+        fi
+        echo "bootstrap: installing golangci-lint $GOLANGCI_LINT_VERSION"
+        go install "$GOLANGCI_LINT_REF"
+
+        # go install writes to GOBIN (or GOPATH/bin); callers resolve through
+        # PATH. Re-resolve through PATH and assert the install took effect.
+        # `hash -r` is load-bearing: without it a shell that already resolved
+        # a stale golangci-lint answers from its own lookup cache, and this
+        # check false-fails with the shadowing message below.
+        hash -r 2>/dev/null || true
+        gcl_got="$(golangci_lint_version)"
+        if [ "$gcl_got" = "$GOLANGCI_LINT_VERSION" ]; then
+            echo "bootstrap: golangci-lint $GOLANGCI_LINT_VERSION installed," \
+                "and PATH resolves it"
+            return 0
+        fi
+        gcl_bin="$(go env GOBIN)"
+        [ -n "$gcl_bin" ] || gcl_bin="$(go env GOPATH)/bin"
+        # Strip a trailing slash: GOBIN=/x/ would otherwise make the
+        # "$gcl_bin"/* test below miss and misreport shadowing.
+        while :; do
+            case "$gcl_bin" in
+                */) gcl_bin="${gcl_bin%/}" ;;
+                *) break ;;
+            esac
+        done
+        gcl_found="$(command -v golangci-lint 2>/dev/null || true)"
+        echo "bootstrap: installed golangci-lint $GOLANGCI_LINT_VERSION into" \
+            "$gcl_bin, but that is not what callers will get." >&2
+        case "$gcl_found" in
+            "")
+                echo "bootstrap: PATH resolves no golangci-lint at all." \
+                    "Add $gcl_bin to PATH, then re-run bootstrap." >&2
+                ;;
+            "$gcl_bin"/*)
+                echo "bootstrap: PATH resolves $gcl_found, inside that same" \
+                    "directory, reporting version ${gcl_got:-unparseable}." \
+                    "Nothing is shadowing it, so the install itself did not" \
+                    "produce the pinned version: check that" \
+                    "GOLANGCI_LINT_VERSION matches GOLANGCI_LINT_REF." >&2
+                ;;
+            *)
+                echo "bootstrap: PATH resolves $gcl_found instead, reporting" \
+                    "version ${gcl_got:-unparseable}. Remove that binary or" \
+                    "put $gcl_bin earlier in PATH, then re-run bootstrap." >&2
+                ;;
+        esac
+        exit 1
+    }
+
+    # The definitions above are inert on their own; the call site is part of
+    # the canonical form. In a script/bootstrap that follows the "define all
+    # functions, then call main" convention, this line belongs inside main()
+    # next to the other ensure_* steps.
+    ensure_golangci_lint
+    ```
+
+    Four properties are load-bearing; each guards a failure mode that otherwise
+    fails green:
+    - **Compare the installed version against the pin**, never test presence.
+      This is what makes a version bump propagate to machines that already have
+      some golangci-lint. Compare the **whole** version token, exactly: a parser
+      that stops at the first `-` reports `2.12.2` for a host running
+      `2.12.2-rc1`, which compares equal to a `2.12.2` pin and skips the install
+      — the original defect, reintroduced through the comparison meant to fix
+      it.
     - **After installing, re-resolve the binary the way callers resolve it** —
-      through `PATH`, not the directory the installer wrote to — and assert the
+      through `PATH`, not the path `go install` wrote to — and assert
-      reported version is the pin. An installer that writes to `GOBIN` while a
+      `--version` reports the pin. When it does not, fail non-zero and name the
-      different binary shadows it earlier in `PATH` genuinely succeeds and
+      path `command -v` actually found, the version it reports, and the
-      changes nothing any caller sees, which is worse than no fix: it converts a
+      directory the install wrote to. That is a condition a human has to fix by
-      known-stale tool into one everyone believes is pinned. Run `hash -r` first
+      hand, so bootstrap must not print success in it. Use `hash -r` first so
-      so the shell does not answer from its own lookup cache, and when the
+      the shell does not answer from its own lookup cache. Diagnose the cause
-      assertion fails, name the path `command -v` found, the version it reports,
+      from the resolved path rather than asserting one: only a path **outside**
-      and the directory the install wrote to. Diagnose from the resolved path
+      the install directory is shadowing. When the resolved path is inside it,
-      rather than asserting a cause: only a path **outside** the install
+      nothing is shadowing and telling the operator to delete that binary or
-      directory is shadowing.
+      reorder `PATH` sends them after a fault that does not exist.
     - **A mis-parse must fall through to reinstall, never to a false match.**
-      Absent binary, non-zero exit, empty output and unrecognised output should
+      Absent binary, non-zero exit, empty output, and unrecognised output all
-      all yield an empty string, which compares unequal to the pin. The failure
+      yield an empty string, which compares unequal to the pin. The failure
       direction is always a redundant install, never a skipped one.
-    - **Call it, and say so on success.** A function defined and never called is
+    - **Call it, and say so on success.** Two function definitions with no call
-      a silent no-op indistinguishable from success: exit 0, nothing installed,
+      site are a silent no-op that reproduces the original defect exactly: exit
-      no output. Both success branches must print a line naming the version.
+      0, nothing installed, no output, stale linter still resolved. A success
-
+      path that prints nothing is byte-identical to that no-op — same exit
-    Verifying such logic requires a negative control in an environment where a
+      status, same empty output — so both success branches must print a
-    shadowing binary exists earlier in `PATH` than the install target — without
+      confirmation naming the version. In a change about undetectable no-ops,
-    it the control passes against the naive compare-then-install form too and
+      "it printed nothing and exited 0" must not be the healthy signal.
-    proves nothing — plus a mis-parse control that feeds unparseable `--version`
-    output and confirms a reinstall. Run those controls against the block as a
-    consuming repo would adopt it: pasted into a `script/bootstrap`-shaped file
-    that is then executed, never by sourcing it and invoking the function
-    yourself. Driving the function directly tests something the artifact does
-    not do, and it is exactly how a missing call site passes every control while
-    the adopted snippet does nothing.
 
     Keep it POSIX sh: no bashisms, no arrays, no `[[`, no `grep -P`.
 
-- **Superseded: the per-checkout `GOLANGCI_LINT_CACHE`/`TMPDIR` wrapper for
+    **On the hash-pinning rule.** `@c0d3ddc9cf3faa61a4e378e879ece580256d76e5` is
-  `script/lint`.** It existed only to make a host lint run trustworthy, and the
+    a commit hash, not a server-mutable version tag, and the go command verifies
-  containerised-lint rule above removes the host run. Delete the wrapper, the
+    the fetched module against the checksum database — the mechanism the
-  `--allow-serial-runners` flag, and `.lint-cache/` from both `.gitignore` and
+    hash-pinning rule at the top of this document already names as acceptable
-  `.dockerignore`. Two of its conclusions outlive it: **`GOCACHE` does not need
+    for Go modules. Note that `go install pkg@version` runs in module-aware mode
-  isolating** (measured — content-addressed, no foreign paths in its entries, no
+    ignoring the `go.mod` in the current directory or any parent, so no repo
-  global lock), and **verifying lint plumbing requires paired controls** run
+    `go.sum` is consulted for this install; the checksum database is what
-  against the artifact as a consuming repo would adopt it, since a control that
+    verifies it. The linter is a bootstrap prerequisite rather than part of any
-  passes against the broken form proves nothing.
+    repo's module graph, which is why the canonical form installs it by
+    commit-pinned ref instead of declaring it in `go.mod`. Whether a `go.mod`
+    tool dependency — which would pin the hash in a committed, reviewable file
+    instead — should replace this is an open decision, tracked at
+    [prompts#37](https://git.eeqj.de/sneak/prompts/issues/37).
 
-- **Interim rule for reading a lint result produced on the host, in a repo that
+    **Keep `GOLANGCI_LINT_VERSION` and the ref in sync.** The ref is a hash and
-  has not yet adopted the containerised lint above.** A lint run is **VOID**
+    carries no readable version, so the expected version is a separate string,
-  unless both hold:
+    and it must be exactly what `--version` prints for that ref — the comparison
-    - the output contains no `parallel golangci-lint is running`, and
+    is an exact match on the whole version token. When the pinned commit carries
-    - no reported file path begins with `../`, and none is an absolute path
+    a release tag the go command resolves the hash to that tag, so the string is
-      outside the tree the run was launched from.
+    simply the release number, `2.12.2` here. When it does not, the go command
+    falls back to a pseudo-version and the binary reports something like
+    `2.12.3-0.20260506110758-c0d3ddc9cf3f`; that compares exactly like any other
+    string, so it works, but it cannot be known without building the binary once
+    and reading `--version` off it. Prefer pins on tagged releases for that
+    reason — the expected string is then derivable from the ref — not because
+    the comparison cannot handle the alternative.
 
-    Do not record a verdict from a void run, and do not "fix" findings in files
+    Because the comparison covers the whole token, a pre-release is never
-    the change does not touch — chasing phantom findings across untouched files
+    confused with its release: a host carrying `2.12.2-rc1` against a `2.12.2`
-    puts unrelated edits into a reviewed diff, which is more expensive than the
+    pin compares unequal and gets reinstalled. This matters more than it looks,
-    wasted rework.
+    because a pre-release tag is still a tag, so a rule requiring merely that
+    the pin be tagged would not catch it.
 
-    The `../` clause is the one that actually bites, and it is why a filter
+    **Verifying a change to this logic requires a negative control run in an
-    keyed on `/tmp` or on absolute prefixes is not enough: golangci-lint reports
+    environment where a shadowing binary exists earlier in `PATH` than the
-    paths relative to its own resolved root rather than yours, and three of the
+    install target.** Without that, the control passes against the naive
-    org's reported sightings had relative paths and would have passed such a
+    compare-then-install form as well and therefore proves nothing. Also check
-    filter. Both clauses are needed and neither alone is sufficient — one
+    the mis-parse direction by feeding it unparseable `--version` output and
-    reproduction exited non-zero with the lock error and no foreign paths at
+    confirming it reinstalls rather than reporting a match.
-    all, and another reported 34 well-formed findings, every one of them against
-    another checkout.
 
-    **State the limit of these tests rather than treating them as a guarantee.**
+    **Run those controls against the block as a consuming repo would adopt it**
-    They catch contamination that **names** foreign files. They cannot catch
+    — pasted into a `script/bootstrap`-shaped file that is then executed — not
-    contamination that **suppresses** findings through a poisoned entry for
+    by sourcing it and invoking the function yourself. Driving the function
-    colliding content, which has no wall-clock tell either — **no evidence of
+    directly tests something the artifact does not do, and it is exactly how a
-    that mode has been observed, and nobody should go chasing it**; the point is
+    missing call site passes every control while the adopted snippet does
-    the reach of the tests, not a claim that the mode exists. They are a filter
+    nothing.
-    for the loud mode, not a proof of soundness — which is the whole argument
-    for containerising the linter instead of documenting a discipline that
-    depends on every agent remembering to apply it. Adopt the rule above and
-    this one stops applying to the repo entirely.
 
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).

script/cibuild

@@ -1,23 +1,26 @@
 #!/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 and the
+# invocation: without it Docker serves the check layer from cache on an
-# build exits 0 without running the suite.
+# unchanged tree and the build exits 0 without running the suite.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    # Both assignments on their own line: a failing command substitution
+    # Assign on its own line: a failing command substitution inside an
-    # inside an argument does not trip `set -e`, so the inline form
+    # argument does not trip `set -e`, which would silently degrade the
-    # degrades silently to an empty constant. `$$` because busybox `date`
+    # nonce to an empty constant. `$$` is required because busybox `date`
-    # drops %N without erroring. VERSION is computed here because
+    # drops %N without erroring.
-    # .dockerignore excludes .git, so `git describe` in a build stage
-    # yields an empty version without failing; the guard below is the
-    # single place the fallback is applied.
     epoch="$(date +%s%N)$$"
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    # VERSION must be computed here, on the host: .dockerignore excludes
+    # .git, so `git describe` cannot run in any build stage and fails
+    # quietly there rather than erroring. Same own-line discipline as the
+    # epoch, plus a non-empty fallback, so a repo built from an export
+    # with no .git reports `unknown` rather than an empty version that
+    # reads as a successful one.
+    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \

script/docker

@@ -11,14 +11,18 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    # Both assignments on their own line: a failing command substitution
+    # Assign on its own line: a failing command substitution inside an
-    # inside an argument does not trip `set -e`, so the inline form
+    # argument does not trip `set -e`, which would silently degrade the
-    # degrades silently to an empty constant. `$$` because busybox `date`
+    # nonce to an empty constant. `$$` is required because busybox `date`
-    # drops %N without erroring. VERSION is computed here because
+    # drops %N without erroring.
-    # .dockerignore excludes .git, so `git describe` in a build stage
-    # yields an empty version without failing.
     epoch="$(date +%s%N)$$"
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    # VERSION must be computed here, on the host: .dockerignore excludes
+    # .git, so `git describe` cannot run in any build stage and fails
+    # quietly there rather than erroring. Same own-line discipline as the
+    # epoch, plus a non-empty fallback, so a repo built from an export
+    # with no .git reports `unknown` rather than an empty version that
+    # reads as a successful one.
+    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \

script/lint

@@ -1,34 +1,13 @@
 #!/bin/sh
-# script/lint: run the linter. Inside a container, run it directly;
+# script/lint: run the linter.
-# on a host, build Dockerfile.lint so it runs in one anyway. The linter
-# is never run on a developer host, where a shared result cache, a
-# host-global lock and a stale toolchain make its answer untrustworthy.
-#
-# LINT_IN_CONTAINER is set by this repo's Dockerfiles and is the ONLY
-# accepted signal. Do not add a /.dockerenv fallback: it is absent
-# inside BuildKit RUN steps and present on hosts that are themselves
-# containers, so it both misses and false-positives — and a false
-# positive silently restores host linting.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-
+    echo "Linting markdown files..."
-    if [ "${LINT_IN_CONTAINER:-}" = "1" ]; then
+    yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
-        exec yarn run prettier --check '**/*.md' \
-            --tab-width 4 --prose-wrap always
-    fi
-
-    # Own line, and `$$` because busybox `date` drops %N silently.
-    # Without a fresh nonce the lint layer is cached and this exits 0
-    # having linted nothing.
-    epoch="$(date +%s%N)$$"
-    docker build \
-        --build-arg CHECK_EPOCH="$epoch" \
-        -f Dockerfile.lint \
-        .
 }
 
 main "$@"