Add public Go onboarding and release proof

.changeset/go-public-onboarding.md

@@ -0,0 +1,5 @@
+---
+"@operatorstack/yield": patch
+---
+
+Add a Go-first onboarding guide, pkg.go.dev discovery links, and release-time verification through the public Go module proxy.

.github/workflows/release-finalize.yml

@@ -78,6 +78,10 @@ jobs:
           node-version: "24"
           registry-url: https://registry.npmjs.org
           package-manager-cache: false
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version-file: go.mod
+          cache: false
       - name: Require matching successful publisher receipts
         env:
           GH_TOKEN: ${{ github.token }}
@@ -113,5 +117,10 @@ jobs:
             --archives "$RUNNER_TEMP/crates-receipt" \
             --attempts 3 \
             --delay-ms 10000
+          node packaging/go-release.mjs \
+            --version "$version" \
+            --source-sha "$SOURCE_SHA" \
+            --attempts 3 \
+            --delay-ms 10000
           test "$(git rev-list -n 1 "$TAG")" = "$SOURCE_SHA"
           gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --draft=false

README.md

@@ -17,6 +17,7 @@
   <!-- npm-exclude:start -->
   <a href="https://pypi.org/project/yieldskill/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/yieldskill?style=flat-square" /></a>
   <a href="https://crates.io/crates/yieldskill"><img alt="crates.io version" src="https://img.shields.io/crates/v/yieldskill?style=flat-square" /></a>
+  <a href="https://pkg.go.dev/github.com/operatorstack/yield/sdk/yield"><img alt="Go reference" src="https://pkg.go.dev/badge/github.com/operatorstack/yield/sdk/yield.svg" /></a>
   <!-- npm-exclude:end -->
   <a href="https://github.com/operatorstack/yield/actions/workflows/verify.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/operatorstack/yield/verify.yml?branch=main&amp;style=flat-square&amp;label=build" /></a>
   <a href="https://github.com/operatorstack/yield/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/@operatorstack/yield?style=flat-square" /></a>
@@ -29,6 +30,7 @@
   <!-- npm-exclude:start -->
   <a href="https://pypi.org/project/yieldskill/">PyPI</a> ·
   <a href="https://crates.io/crates/yieldskill">crates.io</a> ·
+  <a href="https://pkg.go.dev/github.com/operatorstack/yield/sdk/yield">pkg.go.dev</a> ·
   <!-- npm-exclude:end -->
   <a href="https://github.com/operatorstack/yield">GitHub</a>
 </p>
@@ -231,7 +233,7 @@ the same program in every language and compares observable behavior.
 |---|---|---|
 | TypeScript | [`@operatorstack/yield`](https://github.com/operatorstack/yield/tree/main/sdk/typescript/) | [`release-checklist`](https://github.com/operatorstack/yield/tree/main/examples/release-checklist/) |
 | Python | [`yieldskill`](https://github.com/operatorstack/yield/tree/main/sdk/python/) | [`env-doctor`](https://github.com/operatorstack/yield/tree/main/examples/env-doctor/) |
-| Go | [`sdk/yield`](https://github.com/operatorstack/yield/tree/main/sdk/yield/) | [`investigate`](https://github.com/operatorstack/yield/tree/main/examples/investigate/) |
+| Go | [`github.com/operatorstack/yield/sdk/yield`](https://pkg.go.dev/github.com/operatorstack/yield/sdk/yield) | [`investigate`](https://github.com/operatorstack/yield/tree/main/examples/investigate/) |
 | Rust | [`yieldskill`](https://github.com/operatorstack/yield/tree/main/sdk/rust/) | [`data-migration`](https://github.com/operatorstack/yield/tree/main/examples/data-migration/) |
 
 Cursor, Codex, and Claude Code are verified integrations. Yield also includes

evals/results/latest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": 2,
   "methodology_version": "1.1",
-  "generated_at": "2026-08-07T22:52:34.977Z",
-  "source_digest": "b5c66a96530cc9d100c388a4df9bbbc8d0aea6e78ef0fe2cfa0009b8aa1da778",
+  "generated_at": "2026-08-08T01:20:38.016Z",
+  "source_digest": "eb20ae102ae5de056d91ad3a9b8cbfc77284185050c3e3639d93c111b78ed6db",
   "status": "passed",
   "workflow_conformance": {
     "passed": 40,

packaging/go-release.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+import { pathToFileURL } from "node:url";
+
+export const modulePath = "github.com/operatorstack/yield";
+const stableVersion = /^\d+\.\d+\.\d+$/;
+const commit = /^[0-9a-f]{40}$/;
+const execFile = promisify(execFileCallback);
+
+function goPlatform() {
+  const operatingSystem = process.platform === "win32" ? "windows" : process.platform;
+  const architecture = process.arch === "x64" ? "amd64" : process.arch;
+  return `${operatingSystem}/${architecture}`;
+}
+
+function expect(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+export function validateModuleReceipt(receipt, { version, sourceSha }) {
+  expect(stableVersion.test(version), `invalid stable version ${version}`);
+  expect(commit.test(sourceSha), `invalid source SHA ${sourceSha}`);
+  expect(receipt?.Path === modulePath, `unexpected Go module ${receipt?.Path ?? "missing"}`);
+  expect(receipt?.Version === `v${version}`, `unexpected Go module version ${receipt?.Version ?? "missing"}`);
+  expect(receipt?.Origin?.VCS === "git", "Go module origin must use git");
+  expect(receipt?.Origin?.URL === `https://${modulePath}`, `unexpected Go module origin ${receipt?.Origin?.URL ?? "missing"}`);
+  expect(receipt?.Origin?.Hash === sourceSha, "Go module source does not match the release tag");
+  return receipt;
+}
+
+export async function verifyGoRelease({
+  version,
+  sourceSha,
+  attempts = 1,
+  delayMs = 0,
+  execImpl = execFile,
+  delay = (milliseconds) => new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds)),
+}) {
+  expect(Number.isInteger(attempts) && attempts > 0, "attempts must be a positive integer");
+  const bin = await mkdtemp(join(tmpdir(), "yield-go-release-"));
+  const environment = {
+    ...process.env,
+    GOBIN: bin,
+    GOSUMDB: "sum.golang.org",
+    GOPROXY: "https://proxy.golang.org",
+    GOWORK: "off",
+  };
+  let lastError;
+  try {
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      try {
+        const listed = await execImpl("go", ["list", "-m", "-json", `${modulePath}@v${version}`], { env: environment });
+        validateModuleReceipt(JSON.parse(listed.stdout), { version, sourceSha });
+        await execImpl("go", ["install", `${modulePath}/cmd/yskill@v${version}`], { env: environment });
+        const executable = join(bin, process.platform === "win32" ? "yskill.exe" : "yskill");
+        const installed = await execImpl(executable, ["--version"], { env: environment });
+        expect(installed.stdout.trim() === `yskill ${version} ${goPlatform()}`, `unexpected yskill version: ${installed.stdout.trim()}`);
+        return { module: modulePath, version, sourceSha };
+      } catch (error) {
+        lastError = error;
+        if (attempt < attempts) await delay(delayMs);
+      }
+    }
+  } finally {
+    await rm(bin, { recursive: true, force: true });
+  }
+  throw lastError;
+}
+
+function parseArgs(argv) {
+  const values = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index];
+    if (!key?.startsWith("--") || argv[index + 1] === undefined) throw new Error(`invalid argument ${key ?? ""}`);
+    values[key.slice(2)] = argv[index + 1];
+  }
+  expect(stableVersion.test(values.version ?? ""), "--version must be stable semver");
+  expect(commit.test(values["source-sha"] ?? ""), "--source-sha must be a full commit SHA");
+  return values;
+}
+
+async function main() {
+  const values = parseArgs(process.argv.slice(2));
+  const result = await verifyGoRelease({
+    version: values.version,
+    sourceSha: values["source-sha"],
+    attempts: Number(values.attempts ?? "1"),
+    delayMs: Number(values["delay-ms"] ?? "0"),
+  });
+  process.stdout.write(`${JSON.stringify({ ...result, verified: true })}\n`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  main().catch((error) => { console.error(`go-release: ${error.message}`); process.exit(1); });
+}

packaging/go-release.test.mjs

@@ -0,0 +1,65 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { modulePath, validateModuleReceipt, verifyGoRelease } from "./go-release.mjs";
+
+const sourceSha = "a".repeat(40);
+const goPlatform = `${process.platform === "win32" ? "windows" : process.platform}/${process.arch === "x64" ? "amd64" : process.arch}`;
+
+function receipt(version = "1.2.3") {
+  return {
+    Path: modulePath,
+    Version: `v${version}`,
+    Origin: { VCS: "git", URL: `https://${modulePath}`, Hash: sourceSha },
+  };
+}
+
+test("binds the public Go module to its immutable tag source", () => {
+  assert.equal(validateModuleReceipt(receipt(), { version: "1.2.3", sourceSha }).Version, "v1.2.3");
+  assert.throws(
+    () => validateModuleReceipt({ ...receipt(), Origin: { ...receipt().Origin, Hash: "b".repeat(40) } }, { version: "1.2.3", sourceSha }),
+    /does not match the release tag/,
+  );
+});
+
+test("verifies proxy discovery and a fresh command install", async () => {
+  const calls = [];
+  const result = await verifyGoRelease({
+    version: "1.2.3",
+    sourceSha,
+    execImpl: async (file, args, options) => {
+      calls.push({ file, args, options });
+      if (args[0] === "list") return { stdout: JSON.stringify(receipt()) };
+      if (file === "go") return { stdout: "" };
+      return { stdout: `yskill 1.2.3 ${goPlatform}\n` };
+    },
+  });
+  assert.equal(result.module, modulePath);
+  assert.deepEqual(calls[0].args, ["list", "-m", "-json", `${modulePath}@v1.2.3`]);
+  assert.deepEqual(calls[1].args, ["install", `${modulePath}/cmd/yskill@v1.2.3`]);
+  assert.equal(calls[0].options.env.GOPROXY, "https://proxy.golang.org");
+  assert.equal(calls[0].options.env.GOSUMDB, "sum.golang.org");
+  assert.equal(calls[0].options.env.GOWORK, "off");
+});
+
+test("retries a proxy miss without accepting a partial release", async () => {
+  let lists = 0;
+  let delays = 0;
+  await verifyGoRelease({
+    version: "1.2.3",
+    sourceSha,
+    attempts: 2,
+    delayMs: 1,
+    delay: async () => { delays += 1; },
+    execImpl: async (file, args) => {
+      if (args[0] === "list") {
+        lists += 1;
+        if (lists === 1) throw new Error("module not found");
+        return { stdout: JSON.stringify(receipt()) };
+      }
+      if (file === "go") return { stdout: "" };
+      return { stdout: `yskill 1.2.3 ${goPlatform}\n` };
+    },
+  });
+  assert.equal(lists, 2);
+  assert.equal(delays, 1);
+});

scripts/check-release-control.mjs

@@ -99,6 +99,8 @@ export async function checkReleaseControl(root = resolve(import.meta.dirname, ".
   expect(raw["release-finalize.yml"].includes("npm-publish.yml"), "finalization must bind the combined publisher receipt");
   expect(raw["release-finalize.yml"].includes("pypi-release.mjs verify"), "finalization must verify the PyPI wheel hashes");
   expect(raw["release-finalize.yml"].includes("crates-release.mjs verify"), "finalization must verify the crates.io package hashes");
+  expect(raw["release-finalize.yml"].includes("go-release.mjs"), "finalization must verify the public Go module and command install");
+  expect(raw["release-finalize.yml"].includes("--source-sha \"$SOURCE_SHA\""), "Go finalization must bind the module to the release source");
   expect(raw["release-finalize.yml"].includes("--name \"crates-${version}-${SOURCE_SHA}\""), "finalization must consume the publisher-produced crates receipt");
   expect(raw["release.yml"].includes("gh workflow run npm-publish.yml"), "the release controller must dispatch the trusted-publishing event after tagging");
   expect(!Object.values(raw).some((text) => text.includes("CRATES_BOOTSTRAP_TOKEN")), "crates.io publishing must not use a bootstrap token");

scripts/readme.test.mjs

@@ -78,6 +78,54 @@ test("Rust README example matches the tested data migration", async () => {
   assert.deepEqual(JSON.parse(fixtureMatch[1]), JSON.parse(fixture));
 });
 
+test("Go README example matches the tested investigation workflow", async () => {
+  const [readme, source, fixture] = await Promise.all([
+    text("sdk/yield/README.md"),
+    text("examples/investigate/main.go"),
+    text("examples/investigate/fixtures/responses.json"),
+  ]);
+
+  const readmeMatch = readme.match(
+    /<!-- go-example:start -->\s*```go\n([\s\S]*?)\n```\s*<!-- go-example:end -->/,
+  );
+  assert.ok(readmeMatch, "Go README example markers are missing");
+  const sourceMatch = source.match(/^(package main[\s\S]*)$/m);
+  assert.ok(sourceMatch, "Go source program is missing");
+  assert.equal(readmeMatch[1].trim(), sourceMatch[1].trim());
+
+  const fixtureMatch = readme.match(
+    /<!-- go-fixture:start -->\s*```json\n([\s\S]*?)\n```\s*<!-- go-fixture:end -->/,
+  );
+  assert.ok(fixtureMatch, "Go README fixture markers are missing");
+  assert.deepEqual(JSON.parse(fixtureMatch[1]), JSON.parse(fixture));
+});
+
+test("Go README presents a public five-step workflow", async () => {
+  const readme = await text("sdk/yield/README.md");
+  const headings = [
+    "### 1. Install Yield",
+    "### 2. Create the workflow",
+    "### 3. Test the workflow",
+    "### 4. Register the skill",
+    "### 5. Run the skill",
+  ];
+  let previous = -1;
+  for (const heading of headings) {
+    const current = readme.indexOf(heading);
+    assert.ok(current > previous, `${heading} is missing or out of order`);
+    previous = current;
+  }
+  assert.match(readme, /go install github\.com\/operatorstack\/yield\/cmd\/yskill@latest/);
+  assert.match(readme, /yskill init skills\/investigate/);
+  assert.match(readme, /yskill doctor skills\/investigate --test/);
+  assert.match(readme, /yskill register skills\/investigate/);
+  assert.match(readme, /^\/investigate$/m);
+  assert.match(readme, /https:\/\/pkg\.go\.dev\/github\.com\/operatorstack\/yield\/sdk\/yield/);
+  assert.match(readme, /https:\/\/proxy\.golang\.org/);
+  assert.doesNotMatch(readme, /npmjs\.com|pypi\.org|crates\.io/);
+  assert.doesNotMatch(readme, /(?:href|src)="(?!https:\/\/)/);
+});
+
 test("Rust README presents a public five-step workflow", async () => {
   const readme = await text("sdk/rust/README.md");
   const headings = [
@@ -215,10 +263,11 @@ test("README uses the borderless Yield mark", async () => {
 });
 
 test("README and quickstart use the public documentation and package registries", async () => {
-  const [readme, pythonReadme, rustReadme, docsIndex, quickstart, agentSetup] = await Promise.all([
+  const [readme, pythonReadme, rustReadme, goReadme, docsIndex, quickstart, agentSetup] = await Promise.all([
     text("README.md"),
     text("sdk/python/README.md"),
     text("sdk/rust/README.md"),
+    text("sdk/yield/README.md"),
     text("docs/README.md"),
     text("docs/quickstart.md"),
     text("docs/agent-setup.md"),
@@ -227,11 +276,13 @@ test("README and quickstart use the public documentation and package registries"
   assert.match(readme, /href="https:\/\/yield\.operatorstack\.systems\/docs\/">Documentation<\/a>/);
   assert.match(readme, /href="https:\/\/pypi\.org\/project\/yieldskill\/">PyPI<\/a>/);
   assert.match(readme, /href="https:\/\/crates\.io\/crates\/yieldskill">crates\.io<\/a>/);
+  assert.match(readme, /href="https:\/\/pkg\.go\.dev\/github\.com\/operatorstack\/yield\/sdk\/yield">pkg\.go\.dev<\/a>/);
   assert.match(pythonReadme, /python -m pip install yieldskill/);
   assert.match(pythonReadme, /https:\/\/pypi\.org\/project\/yieldskill\//);
   assert.doesNotMatch(pythonReadme, /get\.operatorstack\.systems\/pip/);
   assert.match(rustReadme, /cargo install yieldskill --locked/);
   assert.doesNotMatch(rustReadme, /get\.operatorstack\.systems\/cargo/);
+  assert.match(goReadme, /go install github\.com\/operatorstack\/yield\/cmd\/yskill@latest/);
   assert.match(docsIndex, /\[public documentation\]\(https:\/\/yield\.operatorstack\.systems\/docs\/\)/);
   assert.match(quickstart, /npm install --save-exact @operatorstack\/yield/);
   assert.doesNotMatch(quickstart, /get\.operatorstack\.systems\/npm|@operatorstack\/yield@0\./);