chore(lint): adopt golangci-lint

[prorochestvo]

Context

golangci-lint v2.12.2 was run against this repository using the shared
configuration from the stack-go:lint skill. Nothing in the repository was
changed — this issue records the measurement and the work needed to adopt the
linter permanently.

The run covered the standard linter set only. The custom ruleguard rules were not
included, because they need files inside the repository; expect a few more
findings once they are in place.

Current state

Metric	Value
Go files, excluding vendor	74
Total findings	229
Correctness class	87
Style and convention class	142

Most frequent: govet 57, tparallel 46, gocritic 25, paralleltest 24, errcheck 18

What to look at first

The densest correctness bucket in the sweep: 87 of 229 findings. govet
dominates with 57, mostly shadowed err declarations — cmd/yarddog/main.go:64
and :93 both shadow the declaration at line 52. errcheck adds 18.

errorlint reports 8 places formatting an error with %v where %w was
probably meant, which silently breaks errors.Is matching for every caller.

Adoption

1. Copy .golangci.yml from the stack-go:lint skill assets and fill in the two
   blocks marked PROJECT: forbidden dependencies, and layer boundaries if this
   repository has layers.
2. Copy gorules/rules.go and run go get github.com/quasilyte/go-ruleguard/dsl.
   The file carries a //go:build ruleguard tag so it never enters a binary, but
   the dependency must be present or the rules fail to typecheck.
3. Copy scripts/lint-checks.sh for the comment and test-scaffolding rules that
   AST tooling cannot see.
4. Wire make lint to run golangci-lint run ./... followed by
   scripts/lint-checks.sh.
5. Add a CI job with the version pinned to v2.12.2. An unpinned linter turns
   someone else's release into a red build on an untouched branch.
6. Adopt a baseline. With 229 standing findings, a blocking gate on day one
   is a gate that gets switched off in a week. Use --new-from-rev so only new
   code is checked, then clear the backlog by class in separate commits.

Not covered by the linter

These stay manual review items and are documented in the stack-go:lint skill:

• A jackc/pgx repository layer gets no SQL coverage at all — rowserrcheck and
  sqlclosecheck understand database/sql only.
• Goroutine ownership: who waits for it, how it is told to stop, where its error
  goes.
• Whether fan-out is bounded, and whether a channel buffer size has a stated
  reason.
• Placement of code by actual consumption, and whether two similar blocks share
  an invariant or merely look alike.

[prorochestvo]

Re-measured on current main (2026-08-13), plus two blockers

Blocker 1 — the stack-go:lint skill does not exist

Adoption steps 1-3 say to copy .golangci.yml, gorules/rules.go and
scripts/lint-checks.sh from the stack-go:lint skill assets. The installed
stack-go plugin (v1.1.0) ships four skills — concurrency, conventions,
mistakes, performance — and no lint skill, in either the marketplace copy or
the cache. Those assets cannot be copied from where the plan says they are.

They are recoverable: another local repository already carries the full canonical
set — a 205-line .golangci.yml that describes itself as the shared standard, plus
the companion gorules/rules.go and scripts/lint-checks.sh. Whether that copy is
the blessed source to propagate from is a call to make before adopting.

Blocker 2 — ruleguard conflicts with the stdlib-only rule

The canonical config enables gocritic with settings.ruleguard.rules: gorules/rules.go and failOn: all. That rules file needs
github.com/quasilyte/go-ruleguard/dsl in go.mod — the reference repository
carries it as an indirect dependency. CLAUDE.md states that modernc.org/sqlite is
the only permitted third-party dependency. The //go:build ruleguard tag keeps
it out of the binary but not out of go.mod, so adopting the standard unchanged
needs that rule amended to carve out lint-only tooling. The alternative is dropping
the ruleguard check and losing the custom rules.

Current findings: 217, not 229

Measured with the canonical config, ruleguard block stripped (its rules file is
absent here, and failOn: all would otherwise hard-error), limits removed —
--max-issues-per-linter=0 --max-same-issues=0, without which repeats of one message
are capped at three and the total is understated:

linter	count		linter	count
govet	59		noctx	6
tparallel	47		intrange	5
gocritic	26		prealloc	3
paralleltest	24		contextcheck	2
perfsprint	12		dupword	2
funcorder	9		durationcheck	2
errorlint	8		forbidigo	2
revive	7		nilnil	2
			interfacebloat	1

errcheck is now 0 — the 18 recorded in the original sweep were cleared in #13.

Correction: the errorlint findings are not a correctness problem

This issue states that errorlint reports 8 places using %v where %w was meant,
"which silently breaks errors.Is matching for every caller". That is not what these
8 are. Every one has the shape:

return nil, fmt.Errorf("%w (also failed to close db: %v)", err, closeErr)

The primary error is already wrapped with %w; the %v carries a secondary
cleanup failure. errors.Is against the meaningful error works correctly at all
eight sites — verified individually. Nothing is silently broken.

They are still worth resolving, but as a deliberate style choice rather than a bug
fix: Go 1.20+ accepts multiple %w verbs, so the secondary error could join the
chain instead of being flattened to text. That changes error semantics slightly (the
close failure becomes matchable) and should be an explicit decision, not a linter
appeasement.

Consequence for the plan: "the densest correctness bucket" is overstated. Of the 87
originally filed under correctness, errcheck's 18 are gone and errorlint's 8 are
not defects, which leaves govet's shadowed-err reports as the substantive
correctness work.