Move the canonical golangci-lint to v2.15.0 and bring back canonicalheader

v2.15.0 (released 2026-10-16, built with go1.27.0 like v2.14.0) bundles
canonicalheader with its upstream fix for non-deterministic results, the
defect behind issue 105. Linted 20 times each on a scratch package with
two planted findings beside a ResponseWriter.Header() call, v2.14.0
reported them on 8 runs and nothing on 12; v2.15.0 reported them on all
20. REPO_POLICIES.md names the new digest; .golangci.yml no longer
disables canonicalheader and is otherwise unchanged, since it verifies
against v2.15.0 as it was and default: all switches on no new linter.

.golangci.yml

@@ -3,9 +3,6 @@ version: "2"
 # Config schema uses the golangci-lint v2 layout (settings live under
 # linters.settings, not top-level linters-settings) so that the
 # thresholds below are actually applied by golangci-lint >= v2.
-#
-# This file has no formatters section, so golangci-lint run does not run
-# gofmt. A repository's script/fmt-check runs it, on the host.
 
 run:
   timeout: 5m
@@ -19,13 +16,13 @@ linters:
     - gomodguard_v2
   disable:
     # Genuinely incompatible with project patterns
-    - exhaustruct_v5   # Requires all struct fields
+    - exhaustruct      # Requires all struct fields
+    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
     - godot            # Requires comments to end with periods
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
     # Deprecated: the warning is attached to the old name, so it is
     # silenced by disabling that name, not by enabling the successor.
-    - exhaustruct      # Deprecated, replaced by exhaustruct_v5
     - wsl              # Deprecated, replaced by wsl_v5
     - gomodguard       # Deprecated, replaced by gomodguard_v2
   settings:
@@ -43,10 +40,7 @@ linters:
       # test-support package exists to hand a test privileges the program
       # itself must never have, so a file that is not a test must not import
       # one. Test files, and the files inside a package whose directory name
-      # ends in `test`, are where that code belongs, and are exempt. A package
-      # in a subdirectory of that directory is not exempt. `${base-path}` is
-      # the directory holding this file, so the name of the directory a
-      # repository is cloned into does not count.
+      # ends in `test`, are where that code belongs, and are exempt.
       #
       # The deny list below is the one part of this file a repository is
       # expected to extend, and the only part it may. depguard matches an
@@ -61,25 +55,24 @@ linters:
           files:
             - "$all"
             - "!$test"
-            - "!${base-path}**/*test/*"
+            - "!**/*test/**"
           deny:
             - pkg: net/http/httptest
               desc: >-
                 Test-support code belongs in test files and in packages whose
                 directory name ends in test, not in the shipped binary.
-    # Each entry names a module not to use and what to use instead. Every
-    # entry matches the module path exactly.
+    # Only decisions already recorded in the Go package defaults are
+    # listed here. Every entry matches the module path exactly.
     gomodguard_v2:
       blocked:
         - module: github.com/rs/zerolog
           recommendations:
             - log/slog
           reason: "Structured logging is stdlib log/slog."
-        # These entries cover only the github.com/go-redis/redis module paths,
-        # one entry per path, because the later releases are separate paths.
-        # A prefix match would be shorter but would also reach
-        # github.com/go-redis/redismock/v9, the test double for the successor
-        # these entries recommend.
+        # One entry per pre-fork module path, because the later releases
+        # are separate paths. A prefix match would be shorter but would
+        # also reach github.com/go-redis/redismock, the test double for
+        # the successor these entries recommend.
         - module: github.com/go-redis/redis
           recommendations:
             - github.com/redis/go-redis/v9
@@ -92,10 +85,6 @@ linters:
           recommendations:
             - github.com/redis/go-redis/v9
           reason: "Pre-fork module; use the maintained go-redis v9."
-        - module: github.com/go-redis/redis/v9
-          recommendations:
-            - github.com/redis/go-redis/v9
-          reason: "Pre-fork module; use the maintained go-redis v9."
         - module: github.com/sergi/go-diff
           recommendations:
             - github.com/aymanbagabas/go-udiff
@@ -119,4 +108,3 @@ linters:
 issues:
   max-issues-per-linter: 0
   max-same-issues: 0
-  uniq-by-line: false

TODO.md

@@ -21,53 +21,15 @@ fmt-check, and commit.
 
 # Completed Steps
 
-- 2026-11-03: Rewrote `prompts/REPO_POLICIES.md` sentence by sentence
-  (https://git.eeqj.de/sneak/prompts/issues/136), on sneak's yes at
-  https://git.eeqj.de/sneak/prompts/issues/136#issuecomment-165193. Every rule
-  keeps its meaning and its place, and `must` and `should` stay as they were.
-  Long sentences are split, comma-chained lists are now bulleted lists, and
-  every reason stays. Code blocks, digests, URLs, file names, commands and
-  quoted strings are unchanged.
-- 2026-11-03: The canonical golangci-lint is now v2.15.0, still built with
-  go1.27.0, so the `go` directive rule is unchanged (issue 142). Repositories
-  pick this up on their next re-vendor. Each item in the canonical
-  `.golangci.yml` was tried on a scratch module. These changed:
-    - `canonicalheader` is enabled again, because v2.15.0 fixes the random
-      misses behind issue 105.
-    - The `depguard` exemption covers only the files directly inside a directory
-      whose name ends in `test`. It used to reach every directory below that one
-      too. The name of the directory a repository is cloned into no longer
-      counts.
-    - `gomodguard_v2` also blocks `github.com/go-redis/redis/v9`, whose
-      pre-releases can still be imported under that path.
-    - `uniq-by-line` is now `false`, so a line that trips two linters reports
-      both findings.
-    - Three comments are corrected:
-        - `exhaustruct` is listed as deprecated.
-        - The test double is named `github.com/go-redis/redismock/v9`.
-        - The claim that every blocked module is in the Go package defaults is
-          gone.
-    - A comment says the file has no `formatters` section, so
-      `golangci-lint run` does not run `gofmt`.
-- 2026-11-03: A package from the distribution's own package index now needs no
-  version and no hash, and pulling that index is allowed
-  (https://git.eeqj.de/sneak/prompts/issues/72), on sneak's answer at
-  https://git.eeqj.de/sneak/prompts/issues/72#issuecomment-165196. The
-  distribution is the pinned base image's in a `Dockerfile` and the host's on a
-  host. It is trusted, and everything else stays pinned by hash. A package
-  source that a `Dockerfile` adds itself does not get the exception. The pinning
-  rule of `REPO_POLICIES.md` and both checklists say so, and the canonical Go
-  `Dockerfile`'s `apk add` line has a comment saying why it is allowed.
-- 2026-11-03: A first test run that timed out now gets no verbose rerun
-  (https://git.eeqj.de/sneak/prompts/issues/61), on sneak's approval at
-  https://git.eeqj.de/sneak/prompts/issues/61#issuecomment-165195. The Go recipe
-  in `REPO_POLICIES.md` looks in the first run's output for
-  `panic: test timed out` or `*** Test killed`, and exits 1 when either is
-  there. The Python `make test` example takes the same `timeout 90 sh -c`
-  wrapper as its `Dockerfile` example. The 60 and 90 second rule and the
-  5-minute rule now say a hung package uses the backstop once. The Go item in
-  both repo checklists now asks for this, so a repository with the old recipe
-  fails it.
+- 2026-11-01: Moved the canonical golangci-lint to v2.15.0 (released
+  2026-10-16), still built with go1.27.0, so the `go` directive rule is
+  unchanged. The canonical `.golangci.yml` passes `golangci-lint config verify`
+  on v2.15.0, and `default: all` switches on no new linter. `canonicalheader` is
+  enabled again (issue 105): v2.15.0 carries the upstream commit "fix:
+  non-deterministic results", and on a scratch package with two planted findings
+  beside a `ResponseWriter.Header()` call, linted 20 times with each pinned
+  image, v2.14.0 reported them on 8 runs and nothing on 12, while v2.15.0
+  reported them on all 20.
 - 2026-10-27: Added `prompts/API_POLICIES.md`
   (https://git.eeqj.de/sneak/prompts/issues/137). It holds sneak's rule from
   https://git.eeqj.de/sneak/routewatch/issues/199 that a value in an API

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-11-03
+last_modified: 2026-10-26
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -70,9 +70,8 @@ with your task.
       (`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
       also mounts golangci-lint's
       (`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step
-      mounts anything else; both `go test` runs carry `-count=1`; a first run
-      that timed out gets no rerun, as in the canonical Go `Dockerfile` in
-      `REPO_POLICIES.md`
+      mounts anything else; both `go test` runs carry `-count=1`, as in the
+      canonical Go `Dockerfile` in `REPO_POLICIES.md`
 - [ ] Python: a `test` phase that installs its packages from `Pipfile.lock` does
       it above `ARG CACHEBUST`, with `COPY script/ script/`,
       `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
@@ -105,42 +104,37 @@ with your task.
       `services/api/.claude/`: add anchored entries for those directories.
 - [ ] If the repo embeds a version in a binary: `.dockerignore` lets `.git` into
       the build context. It keeps out every git `config` at any depth
-      (`**/.git/config`, `**/.git/modules/**/config`):
-    - the repository's own
-    - each submodule's under `.git/modules/`
-    - that of a submodule keeping its own `.git` directory
-
-    `git describe` does not need them, and each can hold a credential: a
-    password in a remote URL, or the token the CI checkout step stores there. A
-    submodule whose name has a `config` segment (`config`, `deploy/config`,
-    `config/lib`) loses its whole git directory to `**/.git/modules/**/config`,
-    and Go's version stamping then fails the build. Give it a name without that
-    segment (`git submodule add --name`). The stage that compiles has `git`: the
-    Debian Go image has it, and an alpine one needs `apk add --no-cache git`. It
-    takes the version from the `VERSION` build argument when one is given,
-    otherwise from `git describe --tags --always`. That gives:
-    - the tag, on a tagged commit
-    - the tag, the number of commits since it and the short commit
-      (`v1.2.3-4-gabc1234`), on a later commit
-    - the short commit, when no tag is reachable
-
-    The stage that compiles also marks its working directory safe for git
-    (`git config --system --add safe.directory /src`). A context sent as a tar
-    stream keeps the sender's file owners, and git refuses a checkout owned by
-    another user, so the version would come out empty. `ARG VERSION` has no
-    default. The build fails if the context carries `.git` and the version still
-    comes out empty, `dev` or `unknown`. A plain `docker build .` with no build
-    arguments must succeed; a Dockerfile that refuses an empty build argument
-    drops that refusal and keeps the argument. A checkout whose `.git` is a file
-    is the exception: a linked worktree, or a repository checked out as a
-    submodule. That file points to a git directory outside the build context, so
-    the build cannot read the version and a plain `docker build .` fails. Pass
-    the version with `--build-arg VERSION=...`. `script/docker` and
-    `script/cibuild` already pass the version they compute on the host; it takes
-    precedence. The canonical `.gitea/workflows/check.yml` sets `fetch-depth: 0`
-    on its checkout step, which otherwise clones shallow and fetches no tags, so
-    a CI build finds the tag too.
-
+      (`**/.git/config`, `**/.git/modules/**/config`): the repository's own,
+      each submodule's under `.git/modules/`, and that of a submodule keeping
+      its own `.git` directory. `git describe` does not need them, and each can
+      hold a credential: a password in a remote URL, or the token the CI
+      checkout step stores there. A submodule whose name has a `config` segment
+      (`config`, `deploy/config`, `config/lib`) loses its whole git directory to
+      `**/.git/modules/**/config`, and Go's version stamping then fails the
+      build: give it a name without that segment (`git submodule add --name`).
+      The stage that compiles has `git` (the Debian Go image has it; an alpine
+      one needs `apk add --no-cache git`) and takes the version from the
+      `VERSION` build argument when one is given, otherwise from
+      `git describe --tags --always`. That gives the tag on a tagged commit; on
+      a later commit, the tag, the number of commits since it and the short
+      commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
+      reachable. The stage that compiles also marks its working directory safe
+      for git (`git config --system --add safe.directory /src`): a context sent
+      as a tar stream keeps the sender's file owners, and git refuses a checkout
+      owned by another user, so the version would come out empty. `ARG VERSION`
+      has no default, and the build fails if the context carries `.git` and the
+      version still comes out empty, `dev` or `unknown`. A plain
+      `docker build .` with no build arguments must succeed; a Dockerfile that
+      refuses an empty build argument drops that refusal and keeps the argument.
+      A checkout whose `.git` is a file (a linked worktree, or a repository
+      checked out as a submodule) is the exception: that file points to a git
+      directory outside the build context, so the build cannot read the version
+      and a plain `docker build .` fails; pass the version with
+      `--build-arg VERSION=...`. `script/docker` and `script/cibuild` already
+      pass the version they compute on the host; it takes precedence. The
+      canonical `.gitea/workflows/check.yml` sets `fetch-depth: 0` on its
+      checkout step, which otherwise clones shallow and fetches no tags, so a CI
+      build finds the tag too.
 - [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on
       push, checks out with `persist-credentials: false` and with
       `fetch-depth: 0` (which fetches the tags `git describe` needs), carries
@@ -221,12 +215,7 @@ with your task.
 - [ ] Pre-commit hook is installed (`make hooks`)
 - [ ] No secrets in the repo (`.env`, keys, credentials)
 - [ ] No mutable references in Dockerfiles or scripts (tags, `@latest`) — all
-      pinned by cryptographic hash with version/date comment. The one exception
-      is a package from the distribution's own package index, which needs no
-      version and no hash. Pulling that index is also allowed. In a
-      `Dockerfile`, the distribution is the pinned base image's. On a host, it
-      is the host's. A package source that a `Dockerfile` adds itself does not
-      get this exception
+      pinned by cryptographic hash with version/date comment
 - [ ] Using `yarn`, not `npm` (JS projects)
 
 # Directory Structure

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-11-03
+last_modified: 2026-10-26
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -75,41 +75,34 @@ Template files can be fetched from:
       anchored entry.
     - If the image embeds a version in a binary: `.dockerignore` lets `.git`
       into the build context. It keeps out every git `config` at any depth
-      (`**/.git/config`, `**/.git/modules/**/config`):
-        - the repository's own
-        - each submodule's under `.git/modules/`
-        - that of a submodule keeping its own `.git` directory
-
-        `git describe` does not need them, and each can hold a credential: a
-        password in a remote URL, or the token the CI checkout step stores
-        there. A submodule whose name has a `config` segment (`config`,
-        `deploy/config`, `config/lib`) loses its whole git directory to
-        `**/.git/modules/**/config`, and Go's version stamping then fails the
-        build. Give it a name without that segment (`git submodule add --name`).
-        The stage that compiles has `git`: the Debian Go image has it, and an
-        alpine one needs `apk add --no-cache git`. It takes the version from the
-        `VERSION` build argument when one is given, otherwise from
-        `git describe --tags --always`. That gives:
-        - the tag, on a tagged commit
-        - the tag, the number of commits since it and the short commit
-          (`v1.2.3-4-gabc1234`), on a later commit
-        - the short commit, when no tag is reachable
-
-        The stage that compiles also marks its working directory safe for git
-        (`git config --system --add safe.directory /src`). A context sent as a
-        tar stream keeps the sender's file owners, and git refuses a checkout
-        owned by another user, so the version would come out empty.
-        `ARG VERSION` has no default. The build fails if the context carries
-        `.git` and the version still comes out empty, `dev` or `unknown`. A
-        plain `docker build .` with no build arguments must succeed; a
-        Dockerfile that refuses an empty build argument drops that refusal and
-        keeps the argument. A checkout whose `.git` is a file is the exception:
-        a linked worktree, or a repository checked out as a submodule. That file
-        points to a git directory outside the build context, so the build cannot
-        read the version and a plain `docker build .` fails. Pass the version
-        with `--build-arg VERSION=...`, as `script/docker` and `script/cibuild`
-        already do.
-
+      (`**/.git/config`, `**/.git/modules/**/config`): the repository's own,
+      each submodule's under `.git/modules/`, and that of a submodule keeping
+      its own `.git` directory. `git describe` does not need them, and each can
+      hold a credential: a password in a remote URL, or the token the CI
+      checkout step stores there. A submodule whose name has a `config` segment
+      (`config`, `deploy/config`, `config/lib`) loses its whole git directory to
+      `**/.git/modules/**/config`, and Go's version stamping then fails the
+      build: give it a name without that segment (`git submodule add --name`).
+      The stage that compiles has `git` (the Debian Go image has it; an alpine
+      one needs `apk add --no-cache git`) and takes the version from the
+      `VERSION` build argument when one is given, otherwise from
+      `git describe --tags --always`. That gives the tag on a tagged commit; on
+      a later commit, the tag, the number of commits since it and the short
+      commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
+      reachable. The stage that compiles also marks its working directory safe
+      for git (`git config --system --add safe.directory /src`): a context sent
+      as a tar stream keeps the sender's file owners, and git refuses a checkout
+      owned by another user, so the version would come out empty. `ARG VERSION`
+      has no default, and the build fails if the context carries `.git` and the
+      version still comes out empty, `dev` or `unknown`. A plain
+      `docker build .` with no build arguments must succeed; a Dockerfile that
+      refuses an empty build argument drops that refusal and keeps the argument.
+      A checkout whose `.git` is a file (a linked worktree, or a repository
+      checked out as a submodule) is the exception: that file points to a git
+      directory outside the build context, so the build cannot read the version
+      and a plain `docker build .` fails; pass the version with
+      `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already
+      do.
     - The Dockerfile carries a `lint` phase and a `test` phase, each invoking
       its tool directly rather than through `make` or `script/`, and the final
       stage carries a `COPY --from=` of a harmless file from each so the image
@@ -136,9 +129,8 @@ Template files can be fetched from:
       (`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
       also mounts golangci-lint's
       (`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step
-      mounts anything else; both `go test` runs carry `-count=1`; a first run
-      that timed out gets no rerun, as in the canonical Go `Dockerfile` in
-      `REPO_POLICIES.md`
+      mounts anything else; both `go test` runs carry `-count=1`, as in the
+      canonical Go `Dockerfile` in `REPO_POLICIES.md`
     - Python: a `test` phase that installs its packages from `Pipfile.lock` does
       it above `ARG CACHEBUST`, with `COPY script/ script/`,
       `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
@@ -154,7 +146,6 @@ Template files can be fetched from:
     - Server: the final stage builds and runs the application
     - Non-server: the final stage brings up the dev environment
     - Image pinned by sha256 hash with version/date comment
-
 - [ ] Gitea Actions workflow at `.gitea/workflows/check.yml` that runs
       `script/cibuild` on push, checks out with `persist-credentials: false` and
       with `fetch-depth: 0` (which fetches the tags `git describe` needs),
@@ -251,11 +242,7 @@ are thin shims calling them. Model scripts:
       final stage is missing its `COPY --from=` edge to the gate phases.
 - [ ] No secrets in repo, and none in the build context: enumerate a probe image
       rather than reading `.dockerignore`
-- [ ] No mutable image/package references. The one exception is a package from
-      the distribution's own package index, which needs no version and no hash.
-      Pulling that index is also allowed. In a `Dockerfile`, the distribution is
-      the pinned base image's. On a host, it is the host's. A package source
-      that a `Dockerfile` adds itself does not get this exception
+- [ ] No mutable image/package references
 - [ ] No unnecessary files in repo root
 - [ ] All dates written as YYYY-MM-DD