gatewayapi-certificates-operator/docs/plans-executions/2026-10-08-2028-house-conventions.md

Execution: Bring gateway-helper-operator up to house conventions

Plan: docs/plans/2026-10-08-2028-house-conventions.md

• Step 0 — Save and commit the plan
• Step 1 — CLAUDE.md
• Step 2 — .claude/ and docs scaffolding
• Step 3 — Makefile, lint, formatting
• Step 4 — Module path and version identity
• Step 5 — Baseline tests
• Step 6 — CI build workflow
• Step 7 — Close out

Step 1 — CLAUDE.md

Rewrote CLAUDE.md in the five-section shape. The Go, Testing, Changelog and Branching text comes from the go-project-bootstrap skill references; the plan ordering and execution-summary rules come from egress-proxies-operator/CLAUDE.md, condensed from prose into bullets.

Deviations from the plan:

• The house container rules about Ubuntu dev images and separate dev/prod Dockerfiles were left out: this repo has one production Dockerfile and no dev image, and listing rules nobody follows only adds noise.
• The listener-port row was removed from the annotation table and moved to Gotchas, so the table lists only what works.
• Added a short Reviews subsection so the reviewer agents and docs/reviews/ have a documented trigger.
• README.md also claimed that deleting a certificate removes its listeners "instantly". Reworded and added the known limitation.

Worth noting: Commands and CI/CD describe the repo as it is at this commit; Steps 3, 4 and 6 update them. docs/flows.md cites main.go line numbers that Step 4 shifts.

Step 2 — .claude/ and docs scaffolding

Copied the two reviewer agents and /ship from egress-proxies-operator/.claude/. /release was rewritten for the semver rule instead of copied, because the egress text says "no tagging scheme is documented" and this repo now has one.

Deviations from the plan:

• /ship names "a Co-Authored-By: trailer for Claude" instead of the fixed Claude <noreply@anthropic.com> string, matching CLAUDE.md.
• .gitignore already covered /bin/ and *.out, so only .claude/settings.local.json was added.
• settings.json also allows kubectl kustomize, which the Commands section uses.

Worth noting: .claude/settings.json leaves out git commit, git push and git tag on purpose, but ~/.claude/settings.json allows git commit and git push globally, so on this machine the push confirmation rests on CLAUDE.md, not on the permission system.

Step 3 — Makefile, lint, formatting

Added Makefile (uh-cli's shape plus run, docker-build and -race on test), .golangci.yml (v2 defaults) and .dockerignore (egress's allowlist).

make lint failed on first run, before reaching this repo's code:

$ golangci-lint run ./...
.../go/1.27.1/libexec/src/crypto/internal/randutil/randutil.go:11:2: could not import math/rand/v2
(.../math/rand/v2/rand.go:213:17: method must have no type parameters) (typecheck)

The installed golangci-lint 2.12.2 was built with go1.26.4 and cannot type-check the Go 1.27 standard library. The lint target now runs under the go.mod toolchain, which is also what CI uses:

GO_MOD_VERSION := $(shell awk '$$1 == "go" {print $$2}' go.mod)
lint:
	GOTOOLCHAIN=go$(GO_MOD_VERSION) golangci-lint run ./...

With that, lint reported the two expected dead variables (gatewayGroup, gatewayKind in patch.go), which were removed. make fmt reformatted main.go (import order) and the patch.go var block.

Worth noting: this is likely the same failure the egress changelog records as "make lint is blocked by a Go 1.27 toolchain/staticcheck panic"; the same GOTOOLCHAIN pin should unblock it there. Rebuilding golangci-lint with Go 1.27 is the other fix. .golangci.yml carries no settings yet: uh-cli's errcheck exclusions are CLI-specific and nothing here needed one.