From 4b51722440e26809e7a76e287bb1e4e772f043c2 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 19 Sep 2026 18:52:10 +1000 Subject: [PATCH] fix(build): pin gofumpt and golangci-lint as one matched pair `task fmt` formats with the standalone gofumpt and `task lint` re-checks that formatting with the gofumpt golangci-lint vendors. `task check` runs `fmt` then `lint` without diffing the tree, so `lint` is the only hard failure for formatting -- and when the two versions differ, any construct they disagree on makes the gate unsatisfiable: the standalone formatter rewrites a file one way and lint rejects it, with nothing a contributor can run to satisfy both. The surfaces had drifted onto three different pairs. This machine ran gofumpt v0.7.0 against golangci-lint 2.13.2 (vendors v0.11.0), the image pinned golangci-lint 2.12.2 (vendors v0.9.2) next to gofumpt v0.11.0, and CI installed gofumpt@latest. `any((Trees)(nil))` in changes_test.go is the construct that surfaced it: gofumpt <= v0.9.2 keeps the redundant parens, >= v0.10.0 removes them. - Dockerfile: golangci-lint 2.13.2, whose vendored gofumpt v0.11.0 now equals the pinned GOFUMPT_VERSION, so the image's two formatters agree. - Dockerfile: fail the build if the pins ever diverge, rather than ship an image whose gate cannot pass. - deploy.yml: gofumpt@v0.11.0 instead of @latest, which drifts ahead of whatever golangci-lint vendors. - Record the invariant where an agent will meet it: AGENTS.md (CLAUDE.md) and the build-and-env skill, whose snapshots now name the pinned pair instead of calling both unpinned. --- .agents/skills/archie-build-and-env/SKILL.md | 19 ++++++++++++++----- .github/workflows/deploy.yml | 6 +++++- CLAUDE.md | 4 ++++ Dockerfile | 17 ++++++++++++++++- 4 files changed, 39 insertions(+), 7 deletions(-) diff --git a/.agents/skills/archie-build-and-env/SKILL.md b/.agents/skills/archie-build-and-env/SKILL.md index 33034224e..17e5c319d 100644 --- a/.agents/skills/archie-build-and-env/SKILL.md +++ b/.agents/skills/archie-build-and-env/SKILL.md @@ -42,17 +42,26 @@ git --version; gpg --version ``` Classify a missing command as an environment prerequisite. Bootstrap (verified -2026-09-18): Go ≥ 1.27.0, Task ≥ 3.x, gofumpt (unpinned), golangci-lint v2 -(unpinned), Node 24.x for the `ui/` frontend. +2026-09-19): Go ≥ 1.27.0, Task ≥ 3.x, gofumpt v0.11.0, golangci-lint 2.13.2, +Node 24.x for the `ui/` frontend. + +`gofumpt` and `golangci-lint` are one pair, not two independent tools. +`task fmt` formats with the standalone gofumpt; `task lint` re-checks that +formatting with the gofumpt golangci-lint vendors, and `task check` runs +`fmt` then `lint` without diffing the tree, so `lint` is the only hard +failure for formatting. Install the pair from `Dockerfile` +(`GOLANGCI_LINT_VERSION` 2.13.2 -> gofumpt `GOFUMPT_VERSION` 0.11.0) rather +than `@latest` for either: on a construct the two versions disagree on, +`task fmt` cannot converge `task lint`, and the gate is unsatisfiable. | Surface | Repository declaration | Installed snapshot | Interpretation | |---|---|---|---| | Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. | | Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. | | Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. | -| gofumpt | Used by `task fmt`; `@latest` install | v0.7.0 (built with go1.26.5) | Unpinned. | -| golangci-lint | v2 config in `.golangci.yml`; `@latest` install | 2.13.2 | Use v2 CLI; exact release unpinned. | -| Node | `ui/` frontend build | 24.18.1 / npm 11.8.0 | No `engines`/`packageManager` field. Docs need no Node. | +| gofumpt | `task fmt`; pinned in `Dockerfile` (`GOFUMPT_VERSION`) | v0.11.0 | Must equal the gofumpt golangci-lint vendors. | +| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Vendors gofumpt v0.11.0; `golangci-lint run` enables the formatters. | +| Node | `ui/` frontend build | 26.9.0 / npm 11.19.1 | No `engines`/`packageManager` field. Docs need no Node. | | Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. | ## Prepare writable caches in a restricted sandbox diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index f32c30ca2..04a0194b1 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -64,8 +64,12 @@ jobs: with: node-version: "22" + # Pinned, not @latest: this gate rewrites formatting with the standalone + # gofumpt, and the agent image that gates PRs re-checks it with the + # gofumpt bundled in its golangci-lint. Those two versions must agree + # (see Dockerfile), or a PR passes here and fails there unfixably. - name: Install gofumpt - run: go install mvdan.cc/gofumpt@latest + run: go install mvdan.cc/gofumpt@v0.11.0 - name: Install protobuf tools run: bash tools/proto.sh install diff --git a/CLAUDE.md b/CLAUDE.md index 21998ea9d..80bf6c7d0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -85,6 +85,10 @@ automatically and note it in the handoff. Commands are defined in `Taskfile.yml` (requires Go 1.27.0, [Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, and Node/npm). +Install `gofumpt` and `golangci-lint` as the pinned pair from `Dockerfile`, +never `@latest` for either: `task fmt` formats with the standalone gofumpt +while `task lint` re-checks it with the gofumpt golangci-lint vendors, so a +version mismatch makes `task check` unsatisfiable. ```bash task build # build archied and archie-agent binaries into bin/ diff --git a/Dockerfile b/Dockerfile index d8e91a561..bcc8a3d6a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -61,9 +61,24 @@ ENV PATH="/usr/local/go/bin:/go/bin:${PATH}" # Pinned release binaries. Building these with `go install` pulled ~2GB of # module and build cache into the image. delve is omitted because it ships no # prebuilt binary; `go install ...@latest` at runtime if an agent needs it. -ARG GOLANGCI_LINT_VERSION=2.12.2 +# +# `task fmt` formats with this gofumpt and `task lint` then re-checks +# formatting with the gofumpt golangci-lint vendors. Any construct the two +# versions disagree on makes the gate unsatisfiable -- `task fmt` cannot +# converge a check run by a different formatter. So GOFUMPT_VERSION must equal +# the mvdan.cc/gofumpt version in golangci-lint v${GOLANGCI_LINT_VERSION}'s +# go.mod (2.13.2 -> v0.11.0). Bump the two together, never separately. +ARG GOLANGCI_LINT_VERSION=2.13.2 ARG GOFUMPT_VERSION=0.11.0 ARG BUF_VERSION=1.72.0 + +# Fail the build rather than ship an image whose two formatters disagree. +RUN want="$(curl -fsSL "https://raw.githubusercontent.com/golangci/golangci-lint/v${GOLANGCI_LINT_VERSION}/go.mod" | awk '$1 == "mvdan.cc/gofumpt" { sub(/^v/, "", $2); print $2 }')" && \ + if [ "$want" != "${GOFUMPT_VERSION}" ]; then \ + echo "golangci-lint v${GOLANGCI_LINT_VERSION} vendors gofumpt v${want}, but GOFUMPT_VERSION=${GOFUMPT_VERSION}: task fmt and task lint would disagree." >&2; \ + exit 1; \ + fi + RUN curl -fsSL "https://github.com/golangci/golangci-lint/releases/download/v${GOLANGCI_LINT_VERSION}/golangci-lint-${GOLANGCI_LINT_VERSION}-linux-amd64.tar.gz" \ | tar -xz -C /usr/local/bin --strip-components=1 \ "golangci-lint-${GOLANGCI_LINT_VERSION}-linux-amd64/golangci-lint" && \