Migrate canonical .golangci.yml to golangci-lint v2 config layout

Move linter settings from the broken v1-style top-level linters-settings
key to linters.settings so golangci-lint >= v2 actually applies the
thresholds, and drop issues.exclude-use-default, which no longer exists
in the v2 schema. Add a comment documenting the v2 layout requirement.

Record the change in TODO.md Completed Steps.

.golangci.yml

@@ -1,5 +1,9 @@
 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.
+
 run:
   timeout: 5m
   modules-download-mode: readonly
@@ -14,19 +18,17 @@ linters:
     - wsl              # Deprecated, replaced by wsl_v5
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
-
-linters-settings:
-  lll:
-    line-length: 88
-  funlen:
-    lines: 80
-    statements: 50
-  cyclop:
-    max-complexity: 15
-  dupl:
-    threshold: 100
+  settings:
+    lll:
+      line-length: 88
+    funlen:
+      lines: 80
+      statements: 50
+    cyclop:
+      max-complexity: 15
+    dupl:
+      threshold: 100
 
 issues:
-  exclude-use-default: false
   max-issues-per-linter: 0
   max-same-issues: 0

TODO.md

@@ -21,6 +21,9 @@ fmt-check, and commit.
 
 # Completed Steps
 
+- 2026-08-07: Migrated the canonical `.golangci.yml` to the golangci-lint v2
+  config layout (settings under `linters.settings`, dropped
+  `exclude-use-default`).
 - 2026-03-20: Strengthened constructor naming and Params struct rules in the Go
   styleguide.
 - 2026-03-18: Documented fail-fast Dockerfile lint stage and conditional -v test