# Contributor handoff — golang/go

> Canonical page: https://codevetter.com/unpack/go/agent-handoff

# Contributor handoff — golang/go

Scanned commit 12c76d447f576e6c14c566c8524c13a0c0d476b9 (2026-09-22). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

Working rules: never build inside a pristine checkout without a bootstrap Go; run tests via the built tree's ../bin/go, not a system go. The safe edit boundary is: stdlib packages are ordinary Go code, but runtime, compiler SSA tables, api/ manifests, and cmd/go internals have hard invariants and generated files. Always read the file's package comment first — cmd/dist, runtime/proc.go, mgc.go and gc/main.go carry long design comments that encode the actual contract. After edits, run the package's own tests plus cmd/internal/testdir for anything touching the toolchain.
- Build: 'cd src && ./make.bash' (needs GOROOT_BOOTSTRAP >= Go 1.26.0); full validation: ./all.bash which runs make.bash + run.bash; test-only: 'cd src && ./run.bash' or '../bin/go test cmd/internal/testdir -run=Test/<file>'. — [src/make.bash](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/make.bash) [src/all.bash](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/all.bash) [src/run.bash](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/run.bash) [test/README.md](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/test/README.md)
- Read first for any toolchain change: src/cmd/go/main.go (command wiring), src/cmd/go/internal/base/base.go (Command contract), src/cmd/go/internal/work/exec.go (build engine), src/cmd/go/internal/load/pkg.go (Package model), src/cmd/go/internal/modload/init.go (module state). — [src/cmd/go/main.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/main.go) [src/cmd/go/internal/base/base.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/internal/base/base.go) [src/cmd/go/internal/work/exec.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/internal/work/exec.go) [src/cmd/go/internal/load/pkg.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/internal/load/pkg.go) [src/cmd/go/internal/modload/init.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/internal/modload/init.go)
- Read first for compiler work: src/cmd/compile/main.go, src/cmd/compile/internal/gc/main.go (the phase ordering is the file), src/cmd/compile/internal/ssacompile/compile.go (pass table); for runtime work: src/runtime/proc.go and src/runtime/mgc.go headers are mandatory. — [src/cmd/compile/main.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/compile/main.go) [src/cmd/compile/internal/gc/main.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/compile/internal/gc/main.go) [src/cmd/compile/internal/ssacompile/compile.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/compile/internal/ssacompile/compile.go) [src/runtime/proc.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/runtime/proc.go) [src/runtime/mgc.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/runtime/mgc.go)
- make.bash explicitly forbids new code after the bootstrap call — additions belong in cmd/dist's cmdbootstrap so all three shell variants (make.bash/make.bat/make.rc) stay minimal. — [src/make.bash#L222-226](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/make.bash#L222-L226)
- api/go1*.txt files are frozen once shipped; only api/next/* is mutable and each new line needs a '#nnnnn' proposal issue annotation; except.txt lists permitted exceptions. — [api/README](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/api/README)
- PackagePublic in load/pkg.go is a public API surface ('okay to add fields, but not to change or remove existing ones. Keep in sync with ../list/list.go') — renaming a field breaks 'go list -json' consumers. — [src/cmd/go/internal/load/pkg.go#L63-80](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/internal/load/pkg.go#L63-L80)
- Generated-code traps: cmd/go/internal/test/flagdefs.go is produced by genflags.go; ssacompile/opGen.go and rewrite tables are generated; dist's writeGeneratedFiles produces version/config files — regenerate rather than hand-editing. — [src/cmd/go/internal/test/genflags.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/internal/test/genflags.go) [src/cmd/go/internal/test/flagdefs.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/internal/test/flagdefs.go) [src/cmd/compile/internal/ssacompile/opGen.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/compile/internal/ssacompile/opGen.go) [src/cmd/dist/build.go#L995](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/dist/build.go#L995)
- Error conventions: go-command code uses base.Fatalf/base.Errorf (exit status via base.SetExitStatus + base.Exit with atExitFuncs); runtime code uses throw() for invariant violations and fatal() for startup failures — do not mix. — [src/cmd/go/internal/base/base.go#L127-140](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/internal/base/base.go#L127-L140) [src/runtime/proc.go#L191-200](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/runtime/proc.go#L191-L200)
- GOPATH/GOROOT hygiene: go command fatals on GOPATH entries starting with '~' or relative paths and warns when GOPATH==GOROOT; tests run with GOPATH=/nonexist-gopath so code must not depend on a real GOPATH. — [src/cmd/go/main.go#L151-182](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/main.go#L151-L182) [src/run.bash#L59](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/run.bash#L59)
- The -C flag must be first on the command line and is stripped by handleChdirFlag before dispatch; toolchain re-exec relies on this — new pre-dispatch logic must not break the ordering. — [src/cmd/go/main.go#L371-411](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/main.go#L371-L411)
- Vendored deps: std module vendors golang.org/x/{crypto,net,sys,text} under src/vendor; cmd module has its own vendor tree incl. x/tools and x/mod — update via normal module workflow then re-vendor; go.mod 'go 1.28' means only language features ≤1.28 are usable. — [src/go.mod](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/go.mod) [src/cmd/go.mod](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go.mod) [src/vendor/modules.txt](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/vendor/modules.txt) [src/cmd/vendor/modules.txt](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/vendor/modules.txt)
- Contributions go through Gerrit (codereview.cfg), not GitHub PRs; security issues go to security@golang.org per CONTRIBUTING.md; 'go bug' is the recommended issue-filing path. — [codereview.cfg](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/codereview.cfg) [CONTRIBUTING.md#L13-27](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/CONTRIBUTING.md#L13-L27)
- internal/ packages are import-restricted by the compiler itself (enforced in load/internal), so new shared helpers for cmd tools belong under src/cmd/internal; std internals under src/internal. (inferred) — [src/cmd/go/internal/load/pkg.go](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/go/internal/load/pkg.go) [src/cmd/internal](https://github.com/golang/go/blob/12c76d447f576e6c14c566c8524c13a0c0d476b9/src/cmd/internal)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)