Centralize Go validation and build environments

docs/internal/gotool.md

@@ -0,0 +1,42 @@
+# Go command environments
+
+`internal/gotool` resolves effective Go settings once for a validation or build
+operation and applies the shared environment to its Go commands. It uses
+`internal/process` for cancellation, the working directory, output, and wrapped
+errors.
+
+## Configuration discovery
+
+The owner asks the installed `go` command for `GOHOSTOS` and `GOHOSTARCH`, then
+queries effective operational settings with that host selected. Both queries
+use `GOTOOLCHAIN=local` and controlled `GOFLAGS`. Discovery sets
+`GOEXPERIMENT=none` and clears architecture feature variables so an invalid or
+nonbaseline tuning value cannot prevent settings from being read. The
+experiment override is discovery-only.
+
+The persistent Go environment remains active during discovery. The owner copies
+the effective cache and module-cache locations, Go root, temporary directory,
+and native cgo/C-tool configuration into its settings. This captures values
+supplied by either the process environment or the persistent Go environment
+file.
+
+## Command environments
+
+Every Go command receives `GOENV=off`, so removed persistent values cannot
+return. ReleaseKit owns `GOFLAGS=-mod=readonly`, `GOWORK=off`,
+`GOTOOLCHAIN=local`, `GOPROXY=off`, `GONOPROXY=none`, and `GOSUMDB=off`.
+Native commands use `GOHOSTOS` and `GOHOSTARCH` and retain the effective
+`CGO_ENABLED`, `CC`, `CXX`, `PKG_CONFIG`, and `CGO_CFLAGS`, `CGO_CPPFLAGS`,
+`CGO_CXXFLAGS`, and `CGO_LDFLAGS`. Static commands use the selected target and
+`CGO_ENABLED=0`.
+
+Both modes clear `GOEXPERIMENT` and the Go architecture feature variables
+`GOAMD64`, `GOARM`, `GOARM64`, `GO386`, `GOMIPS`, `GOMIPS64`, `GOPPC64`,
+`GORISCV64`, and `GOWASM`. The selected Go toolchain supplies its ordinary
+baseline values. Effective `GOCACHE`, `GOCACHEPROG`, `GOMODCACHE`, `GOPATH`,
+`GOROOT`, and `GOTMPDIR` values are retained. Other process variables remain
+available to child commands.
+
+Candidate validation uses native mode for the offline `go test` suite. Builds
+use static mode for selected-target compilation and the native version-check
+build. The native version executable itself runs as a normal child process.