build: Go floor and toolchain at 1.26.6, the version every builder of the module supports (#12)

Signed-off-by: Vuong Nguyen <vuong@contexing.com>

Author: ContexingVN

.github/workflows/ci.yml

@@ -279,8 +279,18 @@ jobs:
           submodules: recursive
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: "1.27.0"
+          go-version: "1.26.6"
           cache-dependency-path: packages/sdk-go/go.sum
+      # The toolchain the module declares is the toolchain this job runs. A
+      # setup-go that resolved to anything else is a failure, not a footnote.
+      - name: The Go toolchain is the pinned one (scripts/release-pins.env)
+        run: |
+          set -euo pipefail
+          . scripts/lib/release-pins.sh
+          load_release_pins scripts/release-pins.env
+          INSTALLED="$(go env GOVERSION)"
+          test "$INSTALLED" = "go${GO_VERSION}" || { echo "::error::Go $INSTALLED is not the pinned go${GO_VERSION}"; exit 1; }
+          echo "Go $INSTALLED"
       - name: gofmt
         working-directory: packages/sdk-go
         run: test -z "$(gofmt -l .)" || (gofmt -l . && exit 1)
@@ -311,11 +321,20 @@ jobs:
           node-version: 24
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: "1.27.0"
+          go-version: "1.26.6"
           cache-dependency-path: packages/sdk-go/go.sum
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
+      # Parity compares three CLIs; the Go one must be built by the pinned toolchain.
+      - name: The Go toolchain is the pinned one (scripts/release-pins.env)
+        run: |
+          set -euo pipefail
+          . scripts/lib/release-pins.sh
+          load_release_pins scripts/release-pins.env
+          INSTALLED="$(go env GOVERSION)"
+          test "$INSTALLED" = "go${GO_VERSION}" || { echo "::error::Go $INSTALLED is not the pinned go${GO_VERSION}"; exit 1; }
+          echo "Go $INSTALLED"
       - run: npm ci
       # Node, Go, Python CLIs on identical inputs; asserts byte-identical output.
       - run: npm run parity
@@ -332,11 +351,21 @@ jobs:
           node-version: 24
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: "1.27.0"
+          go-version: "1.26.6"
           cache-dependency-path: packages/sdk-go/go.sum
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
+      # The binary compiled below is the one the offline leg runs, so the
+      # toolchain that compiles it is checked while the network still exists.
+      - name: The Go toolchain is the pinned one (scripts/release-pins.env)
+        run: |
+          set -euo pipefail
+          . scripts/lib/release-pins.sh
+          load_release_pins scripts/release-pins.env
+          INSTALLED="$(go env GOVERSION)"
+          test "$INSTALLED" = "go${GO_VERSION}" || { echo "::error::Go $INSTALLED is not the pinned go${GO_VERSION}"; exit 1; }
+          echo "Go $INSTALLED"
       - run: npm ci
       - run: npm run build -w packages/sdk
       - name: Install the Python SDK

.github/workflows/dependency-audit.yml

@@ -85,8 +85,18 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: "1.27.0"
+          go-version: "1.26.6"
           cache-dependency-path: packages/sdk-go/go.sum
+      # The standard library govulncheck reports on is the toolchain's own, so a
+      # scan on an unpinned Go audits a standard library the module never ships.
+      - name: The Go toolchain is the pinned one (scripts/release-pins.env)
+        run: |
+          set -euo pipefail
+          . scripts/lib/release-pins.sh
+          load_release_pins scripts/release-pins.env
+          INSTALLED="$(go env GOVERSION)"
+          test "$INSTALLED" = "go${GO_VERSION}" || { echo "::error::Go $INSTALLED is not the pinned go${GO_VERSION}"; exit 1; }
+          echo "Go $INSTALLED"
       # govulncheck reports the vulnerabilities this code can actually reach, so
       # a finding here is a call path, not an inventory entry.
       - name: govulncheck

.github/workflows/release-checks.yml

@@ -55,7 +55,7 @@ jobs:
           python-version: "3.12"
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: "1.27.0"
+          go-version: "1.26.6"
           cache-dependency-path: packages/sdk-go/go.sum
       # The npm the publish jobs run through, installed here for the same reason
       # the Python and Go versions are pinned here: a rehearsal on a different
@@ -69,6 +69,16 @@ jobs:
           INSTALLED="$(npm --version)"
           test "$INSTALLED" = "$NPM_VERSION" || { echo "::error::npm $INSTALLED is not the pinned $NPM_VERSION"; exit 1; }
           echo "npm $INSTALLED"
+      # And the Go the runner actually resolved is asserted here, rather than
+      # only appearing in the smoke's prerequisites line.
+      - name: The Go toolchain is the pinned one (scripts/release-pins.env)
+        run: |
+          set -euo pipefail
+          . scripts/lib/release-pins.sh
+          load_release_pins scripts/release-pins.env
+          INSTALLED="$(go env GOVERSION)"
+          test "$INSTALLED" = "go${GO_VERSION}" || { echo "::error::Go $INSTALLED is not the pinned go${GO_VERSION}"; exit 1; }
+          echo "Go $INSTALLED"
       - run: npm ci
       - name: Build artifacts, cold-install each, assert CLI battery + cross-SDK parity
         run: npm run smoke:prepublish
@@ -145,8 +155,18 @@ jobs:
           fetch-depth: 0 # full history so goreleaser sees tags
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: "1.27.0"
+          go-version: "1.26.6"
           cache-dependency-path: packages/sdk-go/go.sum
+      # The six published binaries are compiled here; the toolchain that compiles
+      # them is the one the module declares.
+      - name: The Go toolchain is the pinned one (scripts/release-pins.env)
+        run: |
+          set -euo pipefail
+          . scripts/lib/release-pins.sh
+          load_release_pins scripts/release-pins.env
+          INSTALLED="$(go env GOVERSION)"
+          test "$INSTALLED" = "go${GO_VERSION}" || { echo "::error::Go $INSTALLED is not the pinned go${GO_VERSION}"; exit 1; }
+          echo "Go $INSTALLED"
       # goreleaser cannot parse a path-prefixed tag as a version, so the run gets
       # a LOCAL bare tag (never pushed; no repo-wide vX.Y.Z ref exists).
       - name: Prepare the goreleaser version tag (local only)

.github/workflows/release.yml

@@ -222,8 +222,18 @@ jobs:
           fetch-depth: 0 # full history so goreleaser sees tags
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: "1.27.0"
+          go-version: "1.26.6"
           cache-dependency-path: packages/sdk-go/go.sum
+      # The binaries this job publishes are compiled here, so the toolchain that
+      # compiles them is asserted before anything irreversible happens.
+      - name: The Go toolchain is the pinned one (scripts/release-pins.env)
+        run: |
+          set -euo pipefail
+          . scripts/lib/release-pins.sh
+          load_release_pins scripts/release-pins.env
+          INSTALLED="$(go env GOVERSION)"
+          test "$INSTALLED" = "go${GO_VERSION}" || { echo "::error::Go $INSTALLED is not the pinned go${GO_VERSION}"; exit 1; }
+          echo "Go $INSTALLED"
       # goreleaser can't parse the path-prefixed tag as a version, so create a
       # LOCAL bare tag for the run (never pushed; no repo-wide vX.Y.Z ref).
       - name: Prepare goreleaser version tag (local only)

CHANGELOG.md

@@ -23,13 +23,14 @@ the frozen v1.0 line and all reference packages move to 1.4.1 together.
   Go SDK. The scanners are pinned like everything else on the release path.
 - **A pin check for the release path**, `scripts/check-release-pins.sh`: it refuses `@latest`,
   `--upgrade`, a `pip install` or `npm install -g` without an exact version, a `go-version`
-  without a patch component, and a `uses:` without a 40-hex SHA. Contributors get it as a stage
-  of the pre-push hook; CI runs it as its own job, with a self-test that proves each rule still
-  fires, and the pre-publish smoke runs it in layer 0. Alongside it, the PyPI upload's own
-  `twine check --strict` now runs on the gates that come before a tag: in the pre-publish
-  smoke, in CI on every pull request, and in the pre-push hook when a `release/*` or `rc/*`
-  ref is pushed. The tag-triggered release workflow runs the same check once more on the
-  distribution it built, so the upload action is never the first thing to see a rejection.
+  that lacks a patch component or disagrees with the module's own `go` directive, and a
+  `uses:` without a 40-hex SHA. Contributors get it as a stage of the pre-push hook; CI runs
+  it as its own job, with a self-test that proves each rule still fires, and the pre-publish
+  smoke runs it in layer 0. Alongside it, the PyPI upload's own `twine check --strict` now
+  runs on the gates that come before a tag: in the pre-publish smoke, in CI on every pull
+  request, and in the pre-push hook when a `release/*` or `rc/*` ref is pushed. The
+  tag-triggered release workflow runs the same check once more on the distribution it built,
+  so the upload action is never the first thing to see a rejection.
 - **A browser smoke suite** at `packages/e2e` (Playwright on Chromium) over the served viewer,
   an exported tree, and the site, so the live and static renderings are checked against one
   set of assertions: `npm run e2e` locally, a `ui-smoke` job in CI that keeps traces and
@@ -82,13 +83,15 @@ the frozen v1.0 line and all reference packages move to 1.4.1 together.
   MCP server on Node 22 and 24, the floor its `engines.node` declares. The pre-publish smoke
   installs the SDK, `create-leji`, and the MCP server tarballs into a Node 22 container and
   drives all three there, and its result line says so when Docker is absent and the leg is
-  skipped. The Go SDK is built and tested at Go 1.27.0, which is now also the floor its
+  skipped. The Go SDK is built and tested at Go 1.26.6, which is now also the floor its
   `go.mod` declares, so every floor named here is a floor CI exercises.
-- **The Go floor moves to 1.27.0.** `packages/sdk-go/go.mod` declares `go 1.27.0` (up from
+- **The Go floor moves to 1.26.6.** `packages/sdk-go/go.mod` declares `go 1.26.6` (up from
   `go 1.23`), and `golang.org/x/text` moves to v0.41.0 with it. Building the Go SDK, or
-  `go install`ing the `leji` binary from source, now needs Go 1.27.0 or newer; the published
-  release binaries are unaffected, since they carry no toolchain requirement. `CONTRIBUTING.md`
-  and the Go setup script state the new floor.
+  `go install`ing the `leji` binary from source, now needs Go 1.26.6 or newer: it is a strict
+  minimum, so an older 1.26 patch downloads the matching toolchain automatically under Go's
+  default `GOTOOLCHAIN=auto` and fails under `GOTOOLCHAIN=local`. The published release
+  binaries are unaffected, since they carry no toolchain requirement. `CONTRIBUTING.md` and the
+  Go setup script state the new floor.
 - **The test suites pin what they used to sample**: the badge and canary suites in all three
   SDKs share one directory-snapshot helper held to a golden fixture, the capture-cap test
   asserts bytes and termination rather than elapsed time, and the homepage's hero transcript is

CONTRIBUTING.md

@@ -11,7 +11,7 @@ npm run setup:go # Go: installs goreleaser (the only Go dev tool not bundled wit
 npm test         # runs the Node, Python, and Go suites
 ```
 
-Prerequisites: Node 24+, a Python >=3.10 (the Python SDK pins 3.12 via `packages/sdk-py/.python-version`), and Go 1.27+. The `setup:*` scripts detect each toolchain and print install hints if it is missing. Both are idempotent and machine-local (the Python `.venv` is git-ignored), so re-run them after cloning or switching machines.
+Prerequisites: Node 24+, a Python >=3.10 (the Python SDK pins 3.12 via `packages/sdk-py/.python-version`), and Go 1.26.6+. The `setup:*` scripts detect each toolchain and print install hints if it is missing. Both are idempotent and machine-local (the Python `.venv` is git-ignored), so re-run them after cloning or switching machines.
 
 **Running your work-in-progress CLI**, two channels, one machine-wide at a time:
 
@@ -25,7 +25,7 @@ Prerequisites: Node 24+, a Python >=3.10 (the Python SDK pins 3.12 via `packages
 - **Spec proposals.** Open an issue first: the problem, the intent, and the lived case behind it. Leji specifies proven practice; proposals grounded in something a real team does carry more weight than ideas in the abstract.
 - **Pull requests.** Normative changes (anything under `spec/` or `schemas/`) ride PR review and require a `CHANGELOG.md` entry plus a machine-readable `CHANGELOG.json` entry. Yes, the spec dogfoods itself.
 - **Contributor terms.** Every commit needs a DCO sign-off (`git commit -s`); contributions ship under the license for their content type. See [Contributor terms](#contributor-terms).
-- **Tooling.** SDK changes need tests and must keep `leji validate` passing against `examples/`. The Node, Python, and Go SDKs (`packages/sdk`, `packages/sdk-py`, `packages/sdk-go`) are behaviorally identical: a behavior change in one rides into all three, pinned by the shared `fixtures/` suite. Behavior develops and proves out fully in the TypeScript SDK first, the canonical implementation, against the LIVE channel ([testing-cli-adoptions](docs/practice/testing-cli-adoptions.md)); the Go and Python ports are made only from settled TypeScript behavior, pinned by the shared fixtures at port time. The Go SDK builds with Go 1.27+; `gofmt`, `go vet ./...`, and `go test ./...` must pass.
+- **Tooling.** SDK changes need tests and must keep `leji validate` passing against `examples/`. The Node, Python, and Go SDKs (`packages/sdk`, `packages/sdk-py`, `packages/sdk-go`) are behaviorally identical: a behavior change in one rides into all three, pinned by the shared `fixtures/` suite. Behavior develops and proves out fully in the TypeScript SDK first, the canonical implementation, against the LIVE channel ([testing-cli-adoptions](docs/practice/testing-cli-adoptions.md)); the Go and Python ports are made only from settled TypeScript behavior, pinned by the shared fixtures at port time. The Go SDK builds with Go 1.26.6+; `gofmt`, `go vet ./...`, and `go test ./...` must pass.
 - **Language policy (Node side).** TypeScript + ESM everywhere: SDK source and tests, the site (`astro.config.ts` included), and repo scripts (run natively by Node's type stripping; develop on Node 24+). The one deliberate exception is `packages/create-leji/index.js`, a zero-build published shim. No `.mjs`: every package declares `"type": "module"`.
 - **Style.** Spec prose is plain English, normative keywords per RFC 2119 (MUST/SHOULD/MAY), human-readable first.
 

fixtures/release-path/pins/bad/10-go-mod/packages/sdk-go/go.mod

@@ -0,0 +1,5 @@
+module example.com/bad
+
+// Rule 10, the other half: the module declares a floor the tuple does not name,
+// so the workflows and go.mod have drifted apart.
+go 1.26.5

fixtures/release-path/pins/bad/10-go-version/.github/workflows/go-version.yml

@@ -0,0 +1,14 @@
+name: Go patch drift
+# Rule 10: a patch-level go-version that is not the GO_VERSION the tuple names.
+# It satisfies rule 5, so the job looks pinned while running a toolchain the
+# module never declared.
+
+on: [push]
+
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version: "1.26.5"

fixtures/release-path/pins/good/.github/workflows/pinned.yml

@@ -16,7 +16,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: "1.27.0"
+          go-version: "1.26.6"
       - run: npm install -g npm@12.0.2 && npm --version
       # The same install written the other accepted way: the version comes from
       # the tuple itself, so there is no literal here that could drift from it.

fixtures/release-path/pins/good/packages/sdk-go/go.mod

@@ -0,0 +1,4 @@
+module example.com/good
+
+// The `go` directive the tuple names, so rule 10 has a passing shape to read.
+go 1.26.6