@@ -0,0 +1,52 @@
+# ADR-68718: Prefer Root `go.mod` for Generated Go Setup Steps
+
+**Date**: 2026-10-14
+**Status**: Draft
+**Deciders**: Pending maintainer review (originating PR [#68718](https://github.com/github/gh-aw/pull/68718), fixes #68678)
+
+---
+
+### Context
+
+The compiler emits an `actions/setup-go` step whenever a workflow needs the Go runtime. Until now that step always carried a hard-coded default (`go-version: '1.26'`) unless the workflow author set `runtimes.go.version` explicitly. That constant is independent of the Go version declared in the consuming repository's root `go.mod`, so a repository requiring a newer toolchain would get a mismatched Go installation. Combined with `GOTOOLCHAIN=local`, which forbids on-demand toolchain downloads, Go commands failed outright instead of silently upgrading. The compiler needs a version source that tracks the repository, but it can only do so when the generated job actually checks out that repository at the workspace root before the setup step runs.
+
+### Decision
+
+We will have the compiler emit `go-version-file: go.mod` instead of a pinned `go-version` when three conditions all hold: the workflow does not set `runtimes.go.version`, a regular `go.mod` file exists at the compiler's detected git root, and the generated job performs a root checkout of the workflow's own repository before runtime setup. The primary driver is correctness of the toolchain selection: the repository's own module file is the authoritative statement of its minimum Go version. In every other case the compiler keeps emitting the existing default version, so no workflow loses a working setup step.
+
+The "root checkout" predicate reads the emitted default and additional checkout steps, including trial-mode repository overrides, or the first custom checkout before runtime setup is inserted. It accepts only an unconditional, same-repository checkout with an empty or `.` path and no explicit ref. The current-repository expression is normalized for whitespace. Sparse checkouts qualify in cone mode, which retains root files, or when non-cone patterns include `go.mod`. Unverified refs, repositories, conditions, and sparse layouts retain the default version.
+
+### Alternatives Considered
+
+#### Alternative 1: Read `go.mod` at compile time and inline the parsed version
+
+The compiler could parse the `go` directive from the root `go.mod` and emit `go-version: '<parsed>'`. This keeps the generated YAML self-contained and works even without a checkout, since the version is resolved at compile time. It was rejected because the pinned value immediately goes stale: bumping `go.mod` would silently leave every previously compiled `.lock.yml` on the old toolchain until recompiled, reintroducing the exact drift this change is meant to remove. `go-version-file` defers resolution to run time, where the checked-out module file is always current.
+
+#### Alternative 2: Always emit `go-version-file: go.mod` unconditionally
+
+Dropping the checkout and file-existence guards would make the compiler simpler and remove the new helper entirely. It was rejected because `actions/setup-go` hard-fails when the referenced file is absent, which would break workflows that intentionally skip checkout (`checkout: false`), check out a different repository, check out into a subdirectory, use a wiki checkout, or run in repositories with no root module. The guard logic is the cost of preserving those cases, and the new test matrix enumerates each of them.
+
+#### Alternative 3: Raise the hard-coded default to the repository's current Go version
+
+A one-line constant bump would unblock the immediate failure reported in #68678. It was rejected as a non-fix: it resolves one snapshot of the mismatch while guaranteeing the same class of breakage on the next toolchain bump, and it still ignores the Go version of any other repository consuming gh-aw-generated workflows.
+
+### Consequences
+
+#### Positive
+- Generated Go setup tracks the repository's declared minimum Go version automatically, so `GOTOOLCHAIN=local` jobs stop failing after a `go.mod` bump without requiring workflow edits.
+- Recompiling is no longer required to pick up a Go version change; the existing `.lock.yml` resolves the version at run time from the checked-out module file.
+- Explicit `runtimes.go.version` still wins, preserving the escape hatch for workflows that deliberately pin a different toolchain.
+
+#### Negative
+- The compiler now has a compile-time dependency on filesystem state (`c.gitRoot/go.mod`), so the generated output of the same workflow source differs between repositories and between environments where the git root is or is not detected — making lock files less reproducible from source alone.
+- The "root checkout" predicate duplicates checkout reasoning across configured checkouts and raw custom-step YAML; `customCheckoutHasRootGoMod` must stay in sync with checkout semantics (path, repository, `if`, sparse-checkout) or it will silently emit a setup step that fails at run time.
+- A workflow that reorders steps so that checkout no longer precedes runtime setup, or that adds a conditional to its checkout, will change the emitted Go version source in a way that is not obvious from the workflow source.
+
+#### Neutral
+- Two in-repo lock files (`architecture-guardian.lock.yml`, `dead-code-remover.lock.yml`) changed as generated output; the diff for Go-using workflows is a one-line `with:` key swap.
+- The documented default for the `go` runtime becomes conditional ("root `go.mod`, or 1.26 if absent") rather than a single constant, which the frontmatter reference now spells out.
+- `constants.DefaultGoVersion` remains the fallback and is still exercised by the majority of the new test cases, so the constant continues to need maintenance.
+
+---
+
+*ADR created by [adr-writer agent]. Review and finalize before changing status from Draft to Accepted.*
@@ -661,7 +661,7 @@ Each runtime takes a required `version` string plus optional `action-repo` and `
 |---------|----------------|---------------------|
 | `node` | 24 | `actions/setup-node@v7` |
 | `python` | 3.12 | `actions/setup-python@v5` |
-| `go` | 1.25 | `actions/setup-go@v5` |
+| `go` | Root `go.mod`, or 1.26 if absent | `actions/setup-go@v7` |
 | `uv` | latest | `astral-sh/setup-uv@v5` |
 | `bun` | 1.1 | `oven-sh/setup-bun@v2` |
 | `deno` | 2.x | `denoland/setup-deno@v2` |
@@ -685,6 +685,8 @@ runtimes:
 
 Omitted runtimes use the defaults above. Runtimes from imported shared workflows are merged with your workflow's configuration.
 
+When Go is required and `runtimes.go.version` is omitted, the generated setup step uses `go-version-file: go.mod` if the repository root contains that file and the workflow checks out the same repository at workspace root before setup without an explicit ref. Sparse checkouts qualify when they retain root files (cone mode) or include `go.mod` (non-cone mode). Unverified checkout refs, repositories, or layouts use the default version. An explicit `runtimes.go.version` takes precedence.
+
 ### `run-install-scripts`
 
 Controls whether npm pre/post-install scripts are allowed during package installation. Configure this under `runtimes.node.run-install-scripts`. The default is `false`.
 
@@ -1,7 +1,9 @@
 package workflow
 
 import (
+	"path"
 	"path/filepath"
+	"strconv"
 	"strings"
 
 	"github.com/goccy/go-yaml"
@@ -17,6 +19,93 @@ func ContainsCheckout(customSteps string) bool {
 	return found
 }
 
+// customCheckoutHasRootGoMod checks the first checkout, where runtime setup is inserted.
+func customCheckoutHasRootGoMod(customSteps string) bool {
+	return checkoutStepsHaveRootGoMod(customSteps, true)
+}
+
+func checkoutStepsHaveRootGoMod(checkoutSteps string, firstCheckoutOnly bool) bool {
+	var wrapper struct {
+		Steps []struct {
+			Uses string `yaml:"uses"`
+			If   any    `yaml:"if"`
+			With struct {
+				Path           string `yaml:"path"`
+				Repository     string `yaml:"repository"`
+				Ref            string `yaml:"ref"`
+				SparseCheckout string `yaml:"sparse-checkout"`
+				ConeMode       string `yaml:"sparse-checkout-cone-mode"`
+			} `yaml:"with"`
+		} `yaml:"steps"`
+	}
+	if err := yaml.Unmarshal([]byte(checkoutSteps), &wrapper); err != nil || len(wrapper.Steps) == 0 {
+		if err := yaml.Unmarshal([]byte(checkoutSteps), &wrapper.Steps); err != nil {
+			return false
+		}
+	}
+	hasRootGoMod := false
+	for _, step := range wrapper.Steps {
+		if !isCheckoutActionReference(step.Uses) {
+			continue
+		}
+		atRoot := step.With.Path == "" || filepath.Clean(step.With.Path) == "."
+		if atRoot || firstCheckoutOnly {
+			repository := strings.Join(strings.Fields(step.With.Repository), "")
+			hasRootGoMod = atRoot &&
+				(repository == "" || repository == "${{github.repository}}") &&
+				step.If == nil && step.With.Ref == "" &&
+				sparseCheckoutIncludesRootGoMod(step.With.SparseCheckout, step.With.ConeMode)
+		}
+		if firstCheckoutOnly {
+			break
+		}
+	}
+	return hasRootGoMod
+}
+
+func sparseCheckoutIncludesRootGoMod(patterns, coneMode string) bool {
+	if coneMode == "" {
+		return true
+	}
+	cone, err := strconv.ParseBool(coneMode)
+	if err != nil {
+		return false
+	}
+	if cone {
+		return true
+	}
+	if strings.Contains(patterns, "${{") {
+		return false
+	}
+	if patterns == "" {
+		return true
+	}
+	included := false
+	for pattern := range strings.SplitSeq(patterns, "\n") {
+		pattern = strings.TrimSpace(pattern)
+		if pattern == "" || strings.HasPrefix(pattern, "#") {
+			continue
+		}
+		// Git supports character classes that path.Match cannot interpret.
+		if strings.Contains(pattern, "[:") || strings.Contains(pattern, "[!") {
+			return false
+		}
+		excluded := strings.HasPrefix(pattern, "!")
+		pattern = strings.TrimPrefix(strings.TrimPrefix(pattern, "!"), "/")
+		for strings.HasPrefix(pattern, "**/") {
+			pattern = strings.TrimPrefix(pattern, "**/")
+		}
+		matches, err := path.Match(pattern, "go.mod")
+		if err != nil {
+			return false
+		}
+		if matches {
+			included = !excluded
+		}
+	}
+	return included
+}
+
 // findLastCheckoutStepIndex returns the zero-based index of the last
 // actions/checkout step in customSteps and true, or (0, false) if none is found.
 // It uses the same parsing strategy as findFirstCheckoutStepIndex.
 
@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/github/gh-aw/pkg/console"
@@ -118,6 +119,30 @@ func (c *Compiler) prepareRuntimeSetupAndCheckoutInfo(data *WorkflowData) ([]Git
 		return nil, false, err
 	}
 
+	// Prefer the repository's Go version unless the workflow specifies one.
+	checkoutMgr := NewCheckoutManager(data.CheckoutConfigs)
+	var checkoutSteps strings.Builder
+	if c.shouldAddCheckoutStep(data) {
+		for _, step := range checkoutMgr.GenerateDefaultCheckoutStep(c.trialMode, c.trialLogicalRepoSlug, c.getActionPin) {
+			checkoutSteps.WriteString(step)
+		}
+	}
+	for _, step := range checkoutMgr.GenerateAdditionalCheckoutSteps(c.getActionPin) {
+		checkoutSteps.WriteString(step)
+	}
+	hasCheckout := checkoutStepsHaveRootGoMod(checkoutSteps.String(), false)
+	if ContainsCheckout(data.CustomSteps) && !c.shouldAddCheckoutStep(data) {
+		hasCheckout = customCheckoutHasRootGoMod(data.CustomSteps)
+	}
+	for i := range runtimeRequirements {
+		req := &runtimeRequirements[i]
+		if req.Runtime.ID == "go" && req.Version == "" && req.GoModFile == "" && c.gitRoot != "" && hasCheckout {
+			if info, err := os.Stat(filepath.Join(c.gitRoot, "go.mod")); err == nil && info.Mode().IsRegular() {
+				req.GoModFile = "go.mod"
+			}
+		}
+	}
+
 	// Generate runtime setup steps (after filtering out user-customized ones)
 	runtimeSetupSteps := GenerateRuntimeSetupSteps(runtimeRequirements, data)
 	compilerYamlLog.Printf("Detected runtime requirements: %d runtimes, %d setup steps", len(runtimeRequirements), len(runtimeSetupSteps))