From fc61c8ab1c08c015d9f3cb17747261fb1cd8e3de Mon Sep 17 00:00:00 2001
From: David Elner <david.elner@braintrust.com>
Date: Wed, 17 Jun 2026 15:01:50 +0000
Subject: [PATCH] WIP: Plan

---
 PLAN.md | 458 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 458 insertions(+)
 create mode 100644 PLAN.md

diff --git a/PLAN.md b/PLAN.md
new file mode 100644
index 0000000..de6ad27
--- /dev/null
+++ b/PLAN.md
@@ -0,0 +1,458 @@
+# Plan: Generate release workflows from templates
+
+## Context
+
+`.github/workflows/release-ruby.yml` is doing double duty: our **CI-test harness** (releases the
+throwaway `bt-fake` gem, auto-dry-runs on PRs) **and** the de-facto **canonical workflow** other
+Ruby SDK repos are told to copy. Those have diverged — a consumer copying it inherits CI-only and
+bt-fake-only cruft (an extra `bump` job, `./actions` + per-job `checkout`, version patching, PR/Slack/
+notes plumbing).
+
+This extends the existing template system (`templates/` → generated output) to **workflows**: a
+clean, parameterized **consumer** release-workflow template plus a CLI an agent calls to render it
+into a repo (and re-render to diff for updates). It disambiguates the canonical template from our CI
+harness and gives a low-magic update story (regenerate → diff → agentically apply), anchored by a
+provenance header.
+
+**Scope:** Stage 1 ships the consumer template + the public CLI + validation + a committed reference
+rendering. Driving our own `release-ruby.yml` from the same template (so it can't drift) is a planned
+**Stage 2** — designed for now, decided from the real diff, optionally landed in this PR.
+
+## Interface model (settled)
+
+- **Public** = one binstub with subcommands: **`bin/workflow generate`** (scaffold / re-render),
+  **`bin/workflow validate`** (check a workflow before committing), **`bin/workflow compare`** (diff a
+  workflow against a freshly-rendered baseline), and **`bin/workflow update`** (3-way merge upstream
+  changes in — see *Update story*). `generate`/`validate`/`compare` land in Stage 1; `update` is a
+  designed-for fast-follow. Stdlib OptionParser subcommand dispatch — no Thor. The public tool is
+  workflow-scoped and mirrors the private `rake workflows:<verb>` namespace.
+- **Action generation is internal**, not public — you only regenerate `actions/` when modifying
+  sdk-actions itself. It stays `scripts/generate.rb`, invoked by the private Rake tasks + CI.
+- **Rake = private** (contributor/CI tasks), subject-first: `actions:generate`, `actions:validate`,
+  `actions:ci`, `workflows:validate`, `workflows:ci`, `ci`. The `workflows:*` validate tasks
+  **delegate to `bin/workflow validate`**, so the schema check lives in one place (the public tool).
+
+## Worked example (user story) — exercising the vision
+
+**Goal:** an agent sets up releases for gem `braintrust` in repo `braintrustdata/braintrust-ruby`.
+
+The binstub lives in **sdk-actions**, and it writes into the *consumer* repo — so the agent runs it
+from an sdk-actions checkout. By default `--ref` resolves to the SHA of sdk-actions `origin/main` (the
+latest released line), so it's usually omitted — you pin the released ref you generated against.
+
+**Scaffold (initial setup):**
+```sh
+# in an sdk-actions checkout
+bin/workflow generate release/ruby \
+  --gem-name braintrust \
+  --version-module Braintrust \
+  --dest ../braintrust-ruby/.github/workflows/release.yml
+# smart defaults fill the rest:
+#   --ref (→ SHA of sdk-actions origin/main, the latest released line)
+#   --version-file (→ derived from --version-module: Braintrust → lib/braintrust/version.rb)
+#   --working-directory (.), --ruby-version (4.0), --emoji (:gem:), env/slack names
+```
+
+**Output** — `../braintrust-ruby/.github/workflows/release.yml`:
+```yaml
+# GENERATED by sdk-actions `bin/workflow` — update via `bin/workflow update`, not by hand.
+# >>> sdk-actions >>>                  # sentinel-fenced; compare/update locate this, strip `# `, YAML.load it
+#   template: release/ruby
+#   ref: 9f3c1ab…
+#   params:                            # resolved params (non-secret: names only)
+#     gem_name: braintrust
+#     version_module: Braintrust
+#     version_file: lib/braintrust/version.rb
+#     working_directory: "."
+#     ruby_version: "4.0"
+#     emoji: ":gem:"
+#     publish_environment: publish
+#     dry_run_environment: publish-dry-run
+# <<< sdk-actions <<<
+name: Release Ruby
+on:
+  workflow_dispatch:
+    inputs:
+      sha: { required: true }
+      prev_release: { required: false }
+      dry_run: { type: boolean, default: false }
+jobs:
+  validate:
+    steps:
+      - uses: braintrustdata/sdk-actions/actions/release/lang/ruby/validate@9f3c1ab…
+        with:
+          sha: ${{ inputs.sha }}
+          version_file: lib/braintrust/version.rb
+          version_module: Braintrust
+          working_directory: .
+  prepare:        # → braintrustdata/sdk-actions/actions/release/prepare@9f3c1ab…
+  notify-pending: # → …/release/notify-pending@9f3c1ab… (slack_token: ${{ secrets.SLACK_BOT_TOKEN }})
+  publish:
+    environment: ${{ inputs.dry_run && 'publish-dry-run' || 'publish' }}
+    permissions: { contents: write, id-token: write }
+    steps:
+      - uses: braintrustdata/sdk-actions/actions/release/lang/ruby/publish@9f3c1ab…  # checks out inputs.sha internally
+        with: { sha: ${{ inputs.sha }}, gem_name: braintrust, github_release: 'true', … }
+```
+No `bump` job, no per-job `actions/checkout` (validate/publish check out internally), version from the file.
+
+**The binstub then prints a next-steps checklist** (generation ≠ full setup):
+```
+✓ Wrote ../braintrust-ruby/.github/workflows/release.yml  (release/ruby @ 9f3c1ab…)
+Next, in braintrustdata/braintrust-ruby:
+  1. Create environments: `publish` (required reviewers) and `publish-dry-run`.
+  2. RubyGems trusted publisher for `braintrust`: repo=braintrustdata/braintrust-ruby,
+     workflow=release.yml, environment=publish.   ← workflow filename must match your --dest
+  3. (optional) Secrets/vars: SLACK_BOT_TOKEN (secret), SLACK_SDK_RELEASE_CHANNEL (var).
+  4. Confirm lib/braintrust/version.rb defines Braintrust::VERSION.
+```
+
+**Validate before committing** (consumer-facing; works on a generated *or* hand-edited workflow):
+```sh
+bin/workflow validate ../braintrust-ruby/.github/workflows/release.yml
+# → YAML parse + check-jsonschema against the vendored github-workflow schema; reports file:line errors or "ok"
+```
+
+**Compare / update (later, on a newer sdk-actions release):** first-class verbs instead of manual
+`diff`-piping — the file's provenance header supplies the ref it was generated from:
+```sh
+# both read template + ref + params from the file's header — nothing to re-supply
+# show what UPSTREAM changed since this file was generated (isolates upstream delta from your edits)
+bin/workflow compare ../braintrust-ruby/.github/workflows/release.yml
+
+# apply that upstream delta via a 3-way merge (git merge-file), leaving conflict markers where you'd
+# customized the same lines for the agent to resolve; rewrites the header ref to the new one
+bin/workflow update  ../braintrust-ruby/.github/workflows/release.yml
+```
+Both read the header for template + ref + params, then re-render two baselines — the **old** ref
+(`git show <ref>:templates/…`) and the **current** ref — so the diff/merge reflects only upstream
+changes. `generate | diff` stays as the zero-dependency fallback.
+
+### Gaps the example surfaces (folded into the design)
+- **Distribution:** the tool lives in sdk-actions and writes into the consumer repo → the agent needs
+  an sdk-actions checkout; `--ref` defaults to `origin/main`'s SHA (the released line you pin against).
+- **Output target:** default to **stdout** (pipe/diff-friendly); `--dest FILE` writes to a file
+  (`mkdir -p`, and refuse to overwrite an existing file without `--force` so the update-diff flow
+  never clobbers a customized workflow). One binstub cleanly serves both scaffold (`--dest`) and
+  update (stdout | diff).
+- **`version_file` derives from `version_module`** (`::`→`/`, CamelCase→snake_case) — mirrors Ruby's
+  layout (`Braintrust::OpenAI` → `lib/braintrust/open_ai/version.rb`), more reliable than from the gem
+  name; overridable for non-standard layouts.
+- **`version_module` is required** (not derivable from the gem name).
+- **Repo settings are NOT generated** (environments, RubyGems trusted publisher, secrets/vars) → the
+  binstub prints the checklist above; the workflow **filename** matters because the trusted publisher
+  pins it.
+- **`publish` env** is the real-release gate — the consumer must add required reviewers.
+
+## Reuse (don't rebuild)
+- **`Template` engine** (`render`/`render_step`/`with_if`/`indent_lines`) in `scripts/generate.rb` —
+  already supports `**locals` / `locals.fetch(:x){ default }`. Extract so the binstub shares it.
+  Workflows use it as a flat parameterized ERB (no `render_step` composition — keep them diffable).
+- **check-jsonschema + the "not found → mise install" guard** from today's `validate:schema`.
+- **`GENERATED_HEADER`** convention.
+
+## Approach (staged)
+
+### Stage 0 — Extract the render engine (no behavior change)
+- New `scripts/lib/template.rb`: move `Template` + the `STEPS_DIR` it needs into a neutral module
+  (e.g. `Templating`). `scripts/generate.rb` `require_relative 'lib/template'`; keep action
+  orchestration/constants. **Gate:** `rake actions:generate` → `git diff --exit-code actions/` clean.
+
+### Stage 1 — Consumer template + public binstub + validation + rake reorg + docs
+1. **`templates/workflows/release/ruby.yml.erb`** — category-A consumer workflow. **Opens with a
+   `<%# params: … -%>` frontmatter block** (YAML param schema: `required`/`default`/`desc` per param;
+   `desc` doubles as docs) that the binstub reads to build its CLI — so language/registry specifics
+   live in the template, not the binstub. ERB renders the block to nothing. Body parameterized via
+   `locals.fetch`; **derived defaults computed in-body** (e.g. `version_file` from `version_module`).
+   Lean on smart defaults so the typical call is just `--gem-name` + `--version-module` (+ `--dest`).
+   Declared params: `gem_name` (req), `version_module` (req), `version_file`
+   (default derived from `version_module`: `::`→`/`, CamelCase→snake_case, e.g. `Braintrust::OpenAI` →
+   `lib/braintrust/open_ai/version.rb`), `working_directory` (`.`), `ruby_version` (`4.0`),
+   `emoji` (`:gem:`), `ref` (default = SHA of sdk-actions `origin/main`, the latest released line),
+   `publish_environment` (`publish`),
+   `dry_run_environment` (`publish-dry-run`), `slack_token_secret` (`SLACK_BOT_TOKEN`),
+   `slack_channel_var` (`SLACK_SDK_RELEASE_CHANNEL`), `workflow_name` (`Release Ruby`). Emits external
+   `…/actions/release/…@<ref>` refs, no per-job checkout, no `bump` job, `workflow_dispatch` only,
+   plain `environment` ternary, plain secrets/vars. Header = `GENERATED_HEADER` + a **sentinel-fenced**
+   YAML metadata block (`# >>> sdk-actions >>>` … `# <<<`) capturing `template`, `ref`, and the
+   **resolved** non-secret `params`; read back by locate-via-sentinels + strip `# ` + `YAML.safe_load`
+   (so compare/update regenerate the exact baseline). Cohesive sections so a `profile: ci` (Stage 2)
+   layers cleanly.
+2. **`bin/workflow`** — public binstub, stdlib `OptionParser` with manual subcommand dispatch
+   (`ARGV.shift`), executable. **Template-agnostic:** it reads the target template's frontmatter param
+   schema (grab the leading `<%# … -%>` block → `YAML.safe_load`) and **builds its `--<param>` flags
+   dynamically** from it (so `bin/workflow generate release/python --help` lists *that* template's
+   params). Universal flags (`--dest`, `--ref`, `--force`) are binstub-level. Subcommands:
+   - `generate <template>` — parse the schema-derived flags (+ universal), validate required, apply
+     static defaults; output to **stdout** by default, `--dest FILE` to write (`mkdir -p`, no-clobber
+     without `--force`); prints the next-steps checklist after writing; cheap stdlib YAML parse of its
+     own output as a sanity check. Renders via `Templating::Template.new(src).render(**params)` +
+     header. `--ref` defaults to `origin/main`'s SHA; derived params (e.g. `version_file`) resolve in
+     the template body.
+   - `validate <file>` — YAML parse (stdlib) + check-jsonschema against the vendored workflow schema,
+     with the "not found → mise install" guard; reports `file:line` errors or "ok".
+   - `compare <file>` (Stage 1) — read the header, re-render the baseline, diff vs `<file>` (no args).
+   - `update <file>` (fast-follow) — read the header, 3-way merge (see *Update story*).
+3. **`examples/workflows/release-ruby.yml`** — committed reference rendering via a fixed example arg
+   set (`ref` = a clear placeholder); concrete canonical artifact + drift anchor.
+4. **`scripts/github-workflow.schema.json`** — vendor SchemaStore `github-workflow.json`.
+5. **`Rakefile`** reorg — private, subject-first, flat:
+   ```
+   default            → ci
+   ci                 → [actions:ci, workflows:ci]
+   actions:generate   → ruby scripts/generate.rb
+   actions:validate   → YAML parse + check-jsonschema (action schema)
+   actions:ci         → actions:generate + actions:validate + git diff --exit-code actions/
+   workflows:generate → bin/workflow generate release/ruby --dest examples/... <example args>
+   workflows:validate → YAML parse + check-jsonschema (workflow schema) on examples/
+   workflows:ci       → workflows:generate + workflows:validate + git diff --exit-code examples/
+   ```
+   Update `.github/workflows/ci.yml`: `rake ci:actions` → `rake ci`.
+6. **Docs:** `README.md` (repoint "copy the canonical template" → `bin/workflow generate` + the worked
+   example + provenance/diff update flow + the manual-setup checklist); `CONTRIBUTING.md` (the
+   public-binstub vs private-Rake split, subject-first names, `templates/workflows/`, vendored schema).
+
+### Stage 1.5 — Discovery (read-only)
+Generate the consumer workflow and `git diff` against `.github/workflows/release-ruby.yml`; the diff is
+the exact CI(B)+bt-fake(C) surface — evidence for the Stage-2 decision and a validation of update-by-diff.
+
+### Stage 2 — Drive our CI workflow from the template (planned; optionally this PR)
+Add `profile: ci | consumer`; the `ci` profile re-adds the B+C content (bump job, local `./actions` +
+checkouts, version-direct + `working_directory: test/release/ruby` + patch step + `checkout:'false'` +
+`github_release:'false'`, PR trigger+paths, sha/dry_run fallbacks, empty-on-PR env, Slack suppression,
+notes anchor, `_instructions`, `gem_name: bt-fake`, `:ruby:`). Regenerate `release-ruby.yml`; add its
+drift guard. Go/no-go from the Stage-1.5 diff.
+
+## Update story
+
+The in-file header records `template`, `ref`, and resolved `params`. Three levels, increasingly automated:
+- **Fallback (always works):** `bin/workflow generate … | diff` against the copy. Zero deps.
+- **`bin/workflow compare <file>`** (Stage 1): read the header, re-render the baseline, show the diff
+  vs the file — formalizes the manual diff into a verb (no args).
+- **`bin/workflow update <file>`** (designed-for fast-follow): a real **3-way merge** — read the
+  header's `ref` + `params`, render the old baseline A (`git show <ref>:templates/…`) and the current
+  baseline B with those params, then `git merge-file <file> A B` to apply only the upstream delta,
+  leaving conflict markers on customized lines for an agent to resolve; rewrite the header `ref`.
+  - **Enabler (resolved):** the in-file header captures the resolved params, so A regenerates exactly
+    — no sidecar manifest, no re-supplied args. `update` stays a fast-follow only because of the
+    `git show` + `git merge-file` machinery, not a data-availability gap.
+
+This is the README's "record the upstream ref / diff against a newer template" guidance made mechanical.
+
+## Files
+**Create:** `scripts/lib/template.rb`, `bin/workflow` (generate/validate/compare subcommands; update fast-follow), `templates/workflows/release/ruby.yml.erb`,
+`examples/workflows/release-ruby.yml`, `scripts/github-workflow.schema.json`.
+**Modify:** `scripts/generate.rb`, `Rakefile`, `.github/workflows/ci.yml`, `README.md`, `CONTRIBUTING.md`.
+**Stage 2:** `.github/workflows/release-ruby.yml` + add `profile:` to the template.
+
+## Testing & evaluation
+
+We don't unit-test the binstub logic heavily right now — confidence comes from one cheap **automated
+CI guard**, a few **manual smoke checks**, and **one real end-to-end run**. (The generator is
+deterministic and the generated workflow reuses actions already e2e-tested by bt-fake, so the payoff of
+a unit suite is low for now; revisit if `bin/workflow` grows.)
+
+**Automated (CI, cheap):**
+- `rake actions:ci` — Stage-0 guard: regenerating actions/ is a no-op (`git diff --exit-code actions/`).
+- `rake workflows:ci` — regenerate the committed `examples/workflows/release-ruby.yml`, YAML- and
+  schema-validate it, and `git diff --exit-code examples/`. This is the standing guard that the
+  template + generator + schema stay healthy and the reference rendering never drifts.
+
+**Manual smoke (run locally when changing the template/binstub):**
+- `bin/workflow generate release/ruby --gem-name foo --version-module Foo --dest /tmp/r.yml --ref deadbeef`
+  → writes the file (header carries template/ref/resolved params) + prints the next-steps checklist;
+  `bin/workflow validate /tmp/r.yml` passes (YAML + schema).
+- Without `--dest` it prints to stdout (pipe to `diff`); re-running with `--dest` over an existing file
+  refuses without `--force`.
+- `bin/workflow generate release/ruby --help` lists exactly the template's frontmatter params; an
+  undeclared `--flag` errors. (A second template with a different `params:` exposes different flags,
+  no binstub change — the agnosticism check.)
+- `bin/workflow compare <file>` (no args) reads the header, re-renders, shows an empty diff at the same
+  ref and only the upstream delta at a bumped ref.
+
+**End-to-end (the real proof, once):** generate a *consumer-style* workflow that releases **bt-fake**
+through the external `@<sha>` actions, and dispatch a dry run:
+```sh
+bin/workflow generate release/ruby --gem-name bt-fake --version-module BtFake \
+  --version-file test/release/ruby/lib/bt_fake/version.rb --working-directory test/release/ruby \
+  --ref <sdk-actions-sha> --dest .github/workflows/release-consumer-test.yml
+# push branch → gh workflow run release-consumer-test.yml --ref <branch> -f sha=<sha> -f dry_run=true
+```
+A green dry run proves the *generated consumer wiring* (external refs, no checkout steps, version-from-file,
+the `publish`/`publish-dry-run` env) actually runs against the real actions — not just that it's
+schema-valid. Delete the throwaway workflow after. (If we do Stage 2, driving `release-ruby.yml` itself
+from the template makes the existing bt-fake CI dry-run the *standing* e2e test of template output.)
+
+**Contract diff (Stage 1.5, read-only):** generated consumer workflow vs `release-ruby.yml` = exactly
+the catalogued B+C surface — proves the consumer template dropped only A-category content.
+
+## Documentation
+
+- **`README.md`** (consumer-facing): replace "copy the canonical template" with **generate it** —
+  `bin/workflow generate` (the worked example + smart defaults), the **next-steps checklist** (create
+  `publish`/`publish-dry-run` envs, RubyGems trusted publisher keyed to the workflow filename, Slack
+  secret/var), `bin/workflow validate` before committing, and the `compare`/`update` flow for staying
+  current. Frame the binstub as *the* public entrypoint.
+- **`CONTRIBUTING.md`** (contributor-facing): the **public binstub vs private Rake** split; the
+  subject-first task names (`actions:*` / `workflows:*` / `ci`); `templates/workflows/` and the
+  **frontmatter param-schema convention** (how to add a new workflow template = declare `params:` +
+  write the body, derivations in-body); the engine in `scripts/lib/template.rb`; the vendored
+  `github-workflow.json` schema; and how to regenerate/validate the `examples/` reference.
+- **Self-documenting by construction (no extra prose needed):** each template's `params:` `desc:`
+  fields power `--help`; the generated workflow's sentinel header tells a consumer how it was made and
+  to update via `bin/workflow update`.
+- **Stage 2 only:** note in `CONTRIBUTING.md` that `release-ruby.yml` is generated (`profile: ci`) and
+  guarded by `ci:workflows`.
+
+## Settled decisions
+- Public interface = `bin/workflow` (subcommands `generate`/`validate`/`compare`; `update` fast-follow); action regen is internal (no public binstub).
+- Generated workflows carry a **sentinel-fenced YAML** metadata block (`# >>> sdk-actions >>>` … `# <<<`; read via strip-`# ` + `YAML.safe_load`) recording `template`, `ref`, resolved non-secret `params` — so `compare`/`update` regenerate the baseline faithfully with no re-supplied args.
+- Rake = private, subject-first (`actions:*` / `workflows:*`); invert `generate:actions` → `actions:generate`.
+- CLI = stdlib `OptionParser` subcommands (`generate`/`validate`/`compare`; `update` fast-follow);
+  output stdout by default, `--dest` to write. Smart defaults: `--ref` = `origin/main` SHA,
+  `--version-file` derived (in-template) from `--version-module` — typical call is just `--gem-name` + `--version-module`.
+- **Language- & template-agnostic:** each template declares its params in a `<%# params: … -%>`
+  frontmatter block; the binstub builds `--<param>` flags from it (universal flags: `--dest`/`--ref`/
+  `--force`). Adding a `release/python` template is a drop-in — no binstub change. Sidecar manifest is
+  the fallback if frontmatter extraction proves fragile. Derived defaults live in the template body.
+- Workflow validation = vendored SchemaStore `github-workflow.json` + reuse check-jsonschema (no actionlint).
+- Engine extracted to `scripts/lib/template.rb` (`Templating` module).
+- Scope = consumer template + CLI now; CI unification = designed-for Stage 2, optional this PR.
+
+## Appendix — `templates/workflows/release/ruby.yml.erb` (illustrative)
+
+Two distinct headers: the **`<%# params: -%>` frontmatter** is the *input* schema (read by the binstub,
+stripped from output by ERB); the **sentinel provenance block** is *prepended to the output by the
+binstub* (it knows the resolved template/ref/params) and is **not** in the template. Note the consumer
+form needs **no `actions/checkout` steps** — `validate` and `publish` check out `inputs.sha` internally
+(`fetch-depth: 0`), and `prepare`/`notify-pending` need no repo content. Derivation (`version_file` from
+`version_module`) lives in the template body, keeping the engine generic.
+
+```erb
+<%#
+params:
+  gem_name:            { required: true,  desc: "RubyGems gem name, e.g. braintrust" }
+  version_module:      { required: true,  desc: "Module holding VERSION, e.g. Braintrust" }
+  version_file:        { desc: "Version file path (default: lib/<module path>/version.rb)" }
+  working_directory:   { default: ".",    desc: "Gem root (where the gemspec lives)" }
+  ruby_version:        { default: "4.0",  desc: "Ruby version" }
+  emoji:               { default: ":gem:", desc: "Slack emoji prefix" }
+  publish_environment: { default: "publish", desc: "Gated environment for real publishes" }
+  dry_run_environment: { default: "publish-dry-run", desc: "Environment for dry-run dispatches" }
+  slack_token_secret:  { default: "SLACK_BOT_TOKEN", desc: "Secret name for the Slack bot token" }
+  slack_channel_var:   { default: "SLACK_SDK_RELEASE_CHANNEL", desc: "Var name for the Slack channel" }
+  workflow_name:       { default: "Release Ruby", desc: "Workflow display name" }
+-%>
+<%- ref = locals.fetch(:ref)                                          # universal (binstub default: origin/main SHA) -%>
+<%- wd  = locals.fetch(:working_directory) { "." } -%>
+<%- version_file = locals.fetch(:version_file) do                     # derive lib/<module path>/version.rb
+      "lib/#{locals.fetch(:version_module).gsub('::', '/').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase}/version.rb"
+    end -%>
+name: <%= locals.fetch(:workflow_name) { "Release Ruby" } %>
+
+on:
+  workflow_dispatch:
+    inputs:
+      sha:          { description: "Commit SHA to release", required: true, type: string }
+      prev_release: { description: "Notes anchor: tag or SHA (SHA → empty notes)", required: false, type: string }
+      dry_run:      { description: "Dry run: build without tagging or publishing", type: boolean, default: false }
+
+jobs:
+  validate:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions: { contents: read }
+    outputs:
+      release_tag:       ${{ steps.validate.outputs.release_tag }}
+      prev_release:      ${{ steps.validate.outputs.prev_release }}
+      branch:            ${{ steps.validate.outputs.branch }}
+      on_release_branch: ${{ steps.validate.outputs.on_release_branch }}
+      commit_message:    ${{ steps.validate.outputs.commit_message }}
+    steps:
+      - name: Validate release
+        id: validate
+        uses: braintrustdata/sdk-actions/actions/release/lang/ruby/validate@<%= ref %>
+        with:
+          sha: ${{ inputs.sha }}
+          dry_run: ${{ inputs.dry_run }}
+          version_file: <%= version_file %>
+          version_module: <%= locals.fetch(:version_module) %>
+          working_directory: <%= wd %>
+          ruby_version: "<%= locals.fetch(:ruby_version) { "4.0" } %>"
+
+  prepare:
+    needs: validate
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions: { contents: write }   # releases/generate-notes API
+    outputs:
+      pr_list: ${{ steps.prepare.outputs.pr_list }}
+      notes:   ${{ steps.prepare.outputs.notes }}
+    steps:
+      - name: Prepare release
+        id: prepare
+        uses: braintrustdata/sdk-actions/actions/release/prepare@<%= ref %>
+        with:
+          release_tag: ${{ needs.validate.outputs.release_tag }}
+          sha: ${{ inputs.sha }}
+          prev_release: ${{ inputs.prev_release || needs.validate.outputs.prev_release }}
+
+  notify-pending:
+    needs: [validate, prepare]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions: {}
+    steps:
+      - name: Notify release pending
+        uses: braintrustdata/sdk-actions/actions/release/notify-pending@<%= ref %>
+        with:
+          sha: ${{ inputs.sha }}
+          release_tag:       ${{ needs.validate.outputs.release_tag }}
+          prev_release:      ${{ needs.validate.outputs.prev_release }}
+          branch:            ${{ needs.validate.outputs.branch }}
+          on_release_branch: ${{ needs.validate.outputs.on_release_branch }}
+          commit_message:    ${{ needs.validate.outputs.commit_message }}
+          pr_list:           ${{ needs.prepare.outputs.pr_list }}
+          notes:             ${{ needs.prepare.outputs.notes }}
+          dry_run:           ${{ inputs.dry_run }}
+          slack_token:   ${{ secrets.<%= locals.fetch(:slack_token_secret) { "SLACK_BOT_TOKEN" } %> }}
+          slack_channel: ${{ vars.<%= locals.fetch(:slack_channel_var) { "SLACK_SDK_RELEASE_CHANNEL" } %> }}
+          emoji: '<%= locals.fetch(:emoji) { ":gem:" } %>'
+
+  publish:
+    needs: [validate, prepare, notify-pending]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment: ${{ inputs.dry_run && '<%= locals.fetch(:dry_run_environment) { "publish-dry-run" } %>' || '<%= locals.fetch(:publish_environment) { "publish" } %>' }}
+    permissions: { contents: write, id-token: write }
+    steps:
+      - name: Publish                       # the publish action checks out inputs.sha internally
+        uses: braintrustdata/sdk-actions/actions/release/lang/ruby/publish@<%= ref %>
+        with:
+          sha: ${{ inputs.sha }}
+          working_directory: <%= wd %>
+          ruby_version: "<%= locals.fetch(:ruby_version) { "4.0" } %>"
+          dry_run: ${{ inputs.dry_run }}
+          release_tag:       ${{ needs.validate.outputs.release_tag }}
+          notes:             ${{ needs.prepare.outputs.notes }}
+          prev_release:      ${{ needs.validate.outputs.prev_release }}
+          branch:            ${{ needs.validate.outputs.branch }}
+          on_release_branch: ${{ needs.validate.outputs.on_release_branch }}
+          pr_list:           ${{ needs.prepare.outputs.pr_list }}
+          gem_name: <%= locals.fetch(:gem_name) %>
+          slack_token:   ${{ secrets.<%= locals.fetch(:slack_token_secret) { "SLACK_BOT_TOKEN" } %> }}
+          slack_channel: ${{ vars.<%= locals.fetch(:slack_channel_var) { "SLACK_SDK_RELEASE_CHANNEL" } %> }}
+          emoji: '<%= locals.fetch(:emoji) { ":gem:" } %>'
+```
+
+Rendered (for `--gem-name braintrust --version-module Braintrust`), the binstub prepends:
+```yaml
+# GENERATED by sdk-actions `bin/workflow` — update via `bin/workflow update`, not by hand.
+# >>> sdk-actions >>>
+#   template: release/ruby
+#   ref: 9f3c1ab…
+#   params: { gem_name: braintrust, version_module: Braintrust, version_file: lib/braintrust/version.rb, … }
+# <<< sdk-actions <<<
+name: Release Ruby
+…
+```