Migrate canonical .golangci.yml to gomodguard_v2, with a block list (#55)

Option-2 answer to sneak's ruling of 2026-08-19 on
sneak/homoicon#4: migrate to the successor, with
settings. Closes #25.

## The change

`golangci-lint` v2.12.0 deprecated `gomodguard`, and this config sets
`linters.default: all`, so it is enabled everywhere and warns on every run.

- `gomodguard` joins `wsl` in `linters.disable` under a shared "deprecated"
  comment. The warning is attached to the old name, so disabling it is what
  silences it.
- `gomodguard_v2` is named in `linters.enable`, a no-op under `default: all`
  that gives the settings block a visible owner.
- Blocked, each restating a decision already recorded in the Go package
  defaults: `rs/zerolog` → `log/slog`; the pre-fork `go-redis/redis` →
  `redis/go-redis/v9`; `sergi/go-diff` and `hexops/gotextdiff` → `go-udiff`.
  Every entry matches the module path exactly, so the pre-fork go-redis takes
  three: `go-redis/redis`, `/v7`, `/v8`. A prefix would also cover
  `go-redis/redismock`, the test double for the successor recommended here.

Deliberately absent: recorded rejections that vendoring repos still require
(`mattn/go-sqlite3`, `gorm.io/gorm`, `pmezard/go-difflib`), plus `urfave/cli`
and unversioned `go-chi/chi`. Blocking those would redden repos mid-migration
on their next re-vendor.

## After merge

The file's sha256 moves from
`d10f47ef5e0d8620efd62275b016a7de8fd5abedf333922eec86fe4abc06176e` to
`a79b63a254602a5318db5d0e9a06bc71b84bf0c1d896305229d8bfed1d1b1776`, so every
vendoring repo mismatches. #60 is the
propagation brief; it and the record on
#25 carry this value.

## Disclosures

- Judgement call: `wsl` moved two lines down to share the "deprecated" comment.
  No behaviour change, but it widens the diff.
- The `go.mod` survey and the settings-block probe are on
  #25.
- Unverified: the linter was not run against each vendoring repo; the per-repo
  claim rests on reading their `go.mod` files.
- `make check` exit 0.

Model: opus-5
Co-authored-by: Jeffrey Paul <sneak@noreply.example.org>
Reviewed-on: #55
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

.golangci.yml

@@ -10,13 +10,20 @@ run:
 
 linters:
   default: all
+  enable:
+    # Successor to the deprecated gomodguard. Named explicitly, rather than
+    # left to `default: all`, because it carries the module policy below.
+    - gomodguard_v2
   disable:
     # Genuinely incompatible with project patterns
     - exhaustruct      # Requires all struct fields
     - godot            # Requires comments to end with periods
-    - wsl              # Deprecated, replaced by wsl_v5
     - 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.
+    - wsl              # Deprecated, replaced by wsl_v5
+    - gomodguard       # Deprecated, replaced by gomodguard_v2
   settings:
     lll:
       line-length: 88
@@ -53,6 +60,38 @@ linters:
               desc: >-
                 Test-support code belongs in test files and in packages whose
                 directory name ends in test, not in the shipped binary.
+    # 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."
+        # 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
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v7
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v8
+          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
+          reason: "No unified diff output; use go-udiff."
+        - module: github.com/hexops/gotextdiff
+          recommendations:
+            - github.com/aymanbagabas/go-udiff
+          reason: "Unmaintained fork; use go-udiff."
 
 issues:
   max-issues-per-linter: 0

README.md

@@ -124,7 +124,7 @@ alpine. We provide:
   a container)
 - `script/fmt-check` — check formatting (read-only; native)
 - `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
-  extension); builds no image
+  extension); builds no image of its own
 - `script/docker` —
   `docker build --no-cache --build-arg VERSION="$version" -t prompts .`, the tag
   coming from `script/projectname` (byte-identical across repos)

TODO.md

@@ -53,6 +53,15 @@ fmt-check, and commit.
   layers cannot be served from cache on an unchanged tree, and the text claiming
   a bare `docker build .` proves the checks ran is corrected in
   `REPO_POLICIES.md`, both checklists and the Go styleguide.
+- 2026-09-03: Added `-count=1` to both `go test` invocations in the canonical Go
+  `make test` example in `REPO_POLICIES.md`, so the target cannot report a
+  cached pass it did not earn, and documented that Go's test-result cache is a
+  second, independent cache stacked below the Docker layer cache.
+- 2026-08-31: Migrated the canonical `.golangci.yml` from the deprecated
+  `gomodguard` to `gomodguard_v2`: the old linter is disabled by name (which is
+  what silences the deprecation warning), the successor is named explicitly in
+  `linters.enable`, and it carries a `blocked` module list drawn only from
+  decisions already recorded in the Go package defaults.
 - 2026-08-07: Set the canonical `.golangci.yml` to the org-standard v2-schema
   config already deployed byte-identical across the org's Go repos (settings
   under `linters.settings` so thresholds like lll/funlen/cyclop/dupl actually

prompts/EXISTING_REPO_CHECKLIST.md

@@ -103,6 +103,11 @@ with your task.
       the image with `--no-cache`. Without the bootstrap the CI run dies in
       `script/fmt-check`, which runs the formatter on the host and finds nothing
       installed.
+- [ ] `script/fmt` and `script/fmt-check` source nvm for the pinned node version
+      before invoking `yarn`, as `script/bootstrap`'s own install step does.
+      `script/bootstrap` leaves the node and yarn it installs off the `PATH` of
+      the shell that called it, so a bare `yarn` exits 127 on a runner carrying
+      nothing but docker and git.
 - [ ] `script/bootstrap` installs no linter of its own — delete the block, its
       version variables and its call site. A JS repo's `yarn install` stays; it
       brings a linter along with every other dependency, and no verdict is taken
@@ -155,9 +160,10 @@ with your task.
 # Final
 
 - [ ] `make check` passes
-- [ ] `script/cibuild` succeeds in a fresh clone with nothing installed, which
-      is what CI has, and demonstrably executed the checks — a sub-second build,
-      or `CACHED` on a gate layer, means nothing ran
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but
+      docker and git, with no node or yarn on `PATH`, which is what CI has, and
+      demonstrably executed the checks — a sub-second build, or `CACHED` on a
+      gate layer, means nothing ran
 - [ ] A planted lint violation fails both `make lint` and a plain
       `docker build .`; revert it afterwards
 - [ ] Commit and merge fixes before starting your actual task

prompts/NEW_REPO_CHECKLIST.md

@@ -125,6 +125,11 @@ are thin shims calling them. Model scripts:
       `docker build --no-cache --build-arg VERSION="$version" .` (what CI runs).
       The bootstrap is required: CI checks out and runs this alone, and
       `script/fmt-check` runs the formatter on the host.
+- [ ] `script/fmt` and `script/fmt-check` source nvm for the pinned node version
+      before invoking `yarn`, as `script/bootstrap`'s own install step does.
+      `script/bootstrap` leaves the node and yarn it installs off the `PATH` of
+      the shell that called it, so a bare `yarn` exits 127 on a runner carrying
+      nothing but docker and git.
 - [ ] Every `docker build` in `script/` is tagged, so no invocation leaves a
       dangling image behind
 - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check`
@@ -138,9 +143,10 @@ are thin shims calling them. Model scripts:
 
 - [ ] `make check` passes
 - [ ] `make docker` succeeds
-- [ ] `script/cibuild` succeeds in a fresh clone with nothing installed, which
-      is what CI has, and demonstrably executed the checks — a sub-second build,
-      or `CACHED` on a gate layer, means nothing ran
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but
+      docker and git, with no node or yarn on `PATH`, which is what CI has, and
+      demonstrably executed the checks — a sub-second build, or `CACHED` on a
+      gate layer, means nothing ran
 - [ ] Plant a lint violation and confirm both `make lint` and a plain
       `docker build .` fail on it; revert. A plain build that passes proves the
       final stage is missing its `COPY --from=` edge to the gate phases.

prompts/REPO_POLICIES.md

@@ -65,11 +65,17 @@ style conventions are in separate documents:
   `script/bootstrap` first**, because the workflow checks out the repo and runs
   nothing else, while `script/fmt-check` runs the formatter on the host: on a
   pristine checkout with nothing installed the run dies there, after the
-  containerised gates have passed. Four further scripts are our own extensions
-  to the standard: `script/check` runs `script/test`, `script/lint` and
-  `script/fmt-check`; `script/precommit` is what the git pre-commit hook runs,
-  and it calls `script/check`; `script/install-precommit` installs the git
-  pre-commit hook (the `make hooks` target shims to it); and
+  containerised gates have passed. **The bootstrap alone is not enough**:
+  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
+  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
+  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
+  source nvm for the pinned node version before invoking it, exactly as
+  `script/bootstrap`'s own install step does. A runner carrying nothing but
+  docker and git then gets through `script/check`. Four further scripts are our
+  own extensions to the standard: `script/check` runs `script/test`,
+  `script/lint` and `script/fmt-check`; `script/precommit` is what the git
+  pre-commit hook runs, and it calls `script/check`; `script/install-precommit`
+  installs the git pre-commit hook (the `make hooks` target shims to it); and
   `script/projectname` (literally that filename) simply outputs the project's
   name. Scripts that need the name call `script/projectname` — e.g.
   `script/docker` assembles its image tag from it — so those scripts stay
@@ -274,11 +280,24 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@go test -timeout 90s -race -cover ./... || \
+    	@go test -count=1 -timeout 90s -race -cover ./... || \
     		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -timeout 90s -race -v ./...; exit 1; }
+    		  go test -count=1 -timeout 90s -race -v ./...; exit 1; }
     ```
 
+    `-count=1` is required on both invocations: it defeats Go's test _result_
+    cache, so the target cannot report a pass it did not earn, and the rerun
+    reproduces a failure instead of replaying it. It leaves the build cache
+    alone, so it costs the runtime of the suite and no recompilation.
+
+    Note that this is a second, independent cache, stacked below the Docker
+    layer cache that [issue #26](https://git.eeqj.de/sneak/prompts/issues/26)
+    addresses. `CHECK_EPOCH` guarantees the `RUN make test` _step_ re-executes;
+    it does not guarantee `go test` inside that step does any work, because the
+    `GOCACHE` baked into earlier image layers survives into the re-executed
+    step. They are two separate defects requiring two separate fixes, and a fix
+    for one must not be recorded as covering the other.
+
     Python example:
 
     ```makefile

script/fmt

@@ -4,9 +4,28 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# Must match the pin in script/bootstrap.
+NODE_VERSION="22.17.0"
+
+# script/bootstrap installs node and yarn under nvm and leaves neither
+# on the PATH of the shell that called it, so resolve the pinned
+# toolchain here the way bootstrap's own install step does. nvm is a
+# bash script, hence the subshell.
+run_yarn() {
+    if command -v yarn >/dev/null 2>&1; then
+        exec yarn "$@"
+    fi
+    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        echo "fmt: no yarn; run script/bootstrap first" >&2
+        exit 1
+    fi
+    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
+}
+
 main() {
     cd "$ROOT"
-    yarn run prettier --write '**/*.md' --tab-width 4 --prose-wrap always
+    run_yarn run prettier --write '**/*.md' --tab-width 4 --prose-wrap always
 }
 
 main "$@"

script/fmt-check

@@ -4,9 +4,28 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# Must match the pin in script/bootstrap.
+NODE_VERSION="22.17.0"
+
+# script/bootstrap installs node and yarn under nvm and leaves neither
+# on the PATH of the shell that called it, so resolve the pinned
+# toolchain here the way bootstrap's own install step does. nvm is a
+# bash script, hence the subshell.
+run_yarn() {
+    if command -v yarn >/dev/null 2>&1; then
+        exec yarn "$@"
+    fi
+    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        echo "fmt-check: no yarn; run script/bootstrap first" >&2
+        exit 1
+    fi
+    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
+}
+
 main() {
     cd "$ROOT"
-    yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
+    run_yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
 }
 
 main "$@"