From e59471aaa88ad50e123afe0cabcc31c6f3807a19 Mon Sep 17 00:00:00 2001
From: clawbot <clawbot@noreply.example.org>
Date: Mon, 31 Aug 2026 01:54:40 +0000
Subject: [PATCH] Migrate canonical .golangci.yml to gomodguard_v2 with a block
 list (closes #25)

golangci-lint v2.12.0 deprecated gomodguard, and `linters.default: all`
enables it, so every lint run in every consuming Go repo prints a
deprecation warning. Disable the old name, which is what silences the
warning; name gomodguard_v2 in linters.enable so the settings block has
a visible owner; give it a blocked module list.

The list restates only decisions already recorded in the Go package
defaults: zerolog, the pre-fork go-redis/redis, sergi/go-diff and
hexops/gotextdiff. The pre-fork go-redis gets one exact entry per module
path (unversioned, /v7, /v8), because its later releases are separate
paths; a prefix match would be shorter but would also block
go-redis/redismock, the test double for the successor recommended here.
Recorded rejections that vendoring repos still require are deliberately
absent, so a re-vendor cannot redden a repo that has done nothing wrong.

Model: opus-5
---
 .golangci.yml | 41 ++++++++++++++++++++++++++++++++++++++++-
 TODO.md       |  5 +++++
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/.golangci.yml b/.golangci.yml
index 270cd99..a7a74c2 100644
--- a/.golangci.yml
+++ b/.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
diff --git a/TODO.md b/TODO.md
index 721e9ab..0770b40 100644
--- a/TODO.md
+++ b/TODO.md
@@ -25,6 +25,11 @@ fmt-check, and commit.
   `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