diff --git a/.golangci.yml b/.golangci.yml
index 34a8e31..26b1610 100644
--- a/.golangci.yml
+++ b/.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
diff --git a/TODO.md b/TODO.md
index 3e872ce..4f82be5 100644
--- a/TODO.md
+++ b/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