From bfd3cead9113c8540ab4a3f5b28b0965e31d7462 Mon Sep 17 00:00:00 2001
From: James Wiesebron <jameswiesebron@khanacademy.org>
Date: Thu, 9 Jul 2026 14:22:34 -0700
Subject: [PATCH 1/2] [jwies/review-version-sync] review: keep the pinned
 review.md ref in sync with the released version

The pre-agent-steps checkout ref in review.md is supposed to name the
release the file ships in, but changesets only bumps package.json, so
every tag since review-v1.2.2 shipped with a stale ref (and v1.4.0's
prompt invokes lib/provenance.ts, which a v1.2.2 checkout lacks).

The release flow's version command now runs utils/sync-review-version.ts
after changeset version, rewriting every review-v<semver> literal in
review.md to the version being released so the bump lands in the same
Version Packages commit that gets tagged. version-sync.test.ts is the CI
backstop: it fails any PR where the ref diverges from the review package
version. Also bumps the currently stale ref to review-v1.4.0.
---
 .changeset/review-version-sync.md     |   5 +
 .github/workflows/release.yml         |   5 +
 package.json                          |   1 +
 utils/sync-review-version-lib.test.ts | 133 ++++++++++++++++++++++++++
 utils/sync-review-version-lib.ts      |  79 +++++++++++++++
 utils/sync-review-version.ts          |  13 +++
 workflows/review/README.md            |  19 +++-
 workflows/review/review.md            |  14 ++-
 workflows/review/version-sync.test.ts |  37 +++++++
 9 files changed, 299 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/review-version-sync.md
 create mode 100644 utils/sync-review-version-lib.test.ts
 create mode 100644 utils/sync-review-version-lib.ts
 create mode 100644 utils/sync-review-version.ts
 create mode 100644 workflows/review/version-sync.test.ts

diff --git a/.changeset/review-version-sync.md b/.changeset/review-version-sync.md
new file mode 100644
index 00000000..7778646a
--- /dev/null
+++ b/.changeset/review-version-sync.md
@@ -0,0 +1,5 @@
+---
+"review": patch
+---
+
+Keep the pinned `ref:` inside review.md in sync with the released version. The release flow's version command now runs `utils/sync-review-version.ts` after `changeset version`, rewriting every `review-v<semver>` literal in review.md to the version being released so the bump lands in the same Version Packages commit that gets tagged; `workflows/review/version-sync.test.ts` fails CI whenever the ref and the `review` package version diverge. Also bumps the currently stale ref from review-v1.2.2 to review-v1.4.0 (v1.3.0 through v1.4.0 shipped with the lagging ref, so an un-overridden consumer checked out a lib without `lib/provenance.ts`).
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 3ddf0bb3..5b737ff3 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -30,6 +30,11 @@ jobs:
         if: steps.has-changesets.outputs.result == 'true'
         uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1
         with:
+          # Not the default `changeset version`: version-packages also syncs
+          # the pinned `ref:` inside workflows/review/review.md to the version
+          # being released, so the bump lands in the same Version Packages
+          # commit that gets tagged (see utils/sync-review-version.ts).
+          version: pnpm run version-packages
           publish: exit 1
         env:
           GITHUB_TOKEN: ${{ secrets.KHAN_ACTIONS_BOT_TOKEN }}
diff --git a/package.json b/package.json
index f81bb81a..ae9c0cc6 100644
--- a/package.json
+++ b/package.json
@@ -2,6 +2,7 @@
     "repository": "git@github.com:Khan/actions.git",
     "private": true,
     "scripts": {
+        "version-packages": "changeset version && node -r @swc-node/register utils/sync-review-version.ts",
         "lint": "eslint --ext .js,.mjs,.ts .",
         "fix": "pnpm run lint --fix",
         "test": "vitest",
diff --git a/utils/sync-review-version-lib.test.ts b/utils/sync-review-version-lib.test.ts
new file mode 100644
index 00000000..15126940
--- /dev/null
+++ b/utils/sync-review-version-lib.test.ts
@@ -0,0 +1,133 @@
+import {describe, expect, it, vi} from "vitest";
+import {
+    syncReviewVersion,
+    syncReviewVersionContent,
+} from "./sync-review-version-lib.ts";
+
+describe("syncReviewVersionContent", () => {
+    it("rewrites the pinned checkout ref to the given version", () => {
+        // Arrange: a stale ref, as shipped in review-v1.3.0 through v1.4.0.
+        const content = [
+            "pre-agent-steps:",
+            "  - uses: actions/checkout@abc # v5",
+            "    with:",
+            "      repository: Khan/actions",
+            "      ref: review-v1.2.2",
+        ].join("\n");
+
+        // Act
+        const result = syncReviewVersionContent(content, "9.9.9");
+
+        // Assert
+        expect(result.replaced).toBe(1);
+        expect(result.content).toContain("ref: review-v9.9.9");
+        expect(result.content).not.toContain("review-v1.2.2");
+    });
+
+    it("rewrites every semver literal but leaves templates alone", () => {
+        // Arrange
+        const content =
+            "ref: review-v1.2.2\n" +
+            "the marker is `v=review-v<version>` (a template)\n" +
+            "released as review-v1.3.0\n";
+
+        // Act
+        const result = syncReviewVersionContent(content, "2.0.0");
+
+        // Assert
+        expect(result.replaced).toBe(2);
+        expect(result.content).toBe(
+            "ref: review-v2.0.0\n" +
+                "the marker is `v=review-v<version>` (a template)\n" +
+                "released as review-v2.0.0\n",
+        );
+    });
+
+    it("returns unchanged content when already at the version", () => {
+        // Act
+        const result = syncReviewVersionContent("ref: review-v1.4.0", "1.4.0");
+
+        // Assert
+        expect(result.replaced).toBe(1);
+        expect(result.content).toBe("ref: review-v1.4.0");
+    });
+});
+
+describe("syncReviewVersion", () => {
+    const makeDeps = (files: Record<string, string>) => {
+        const writes: Record<string, string> = {};
+        return {
+            writes,
+            deps: {
+                readFileSyncImpl: ((p: string) => {
+                    const content = files[p];
+                    if (content === undefined) {
+                        throw new Error(`unexpected read: ${p}`);
+                    }
+                    return content;
+                }) as never,
+                writeFileSyncImpl: ((p: string, data: string) => {
+                    writes[p] = data;
+                }) as never,
+                log: vi.fn(),
+            },
+        };
+    };
+
+    it("writes review.md with the package version substituted", () => {
+        // Arrange
+        const {writes, deps} = makeDeps({
+            "workflows/review/package.json":
+                '{"name": "review", "version": "1.5.0"}',
+            "workflows/review/review.md": "      ref: review-v1.2.2\n",
+        });
+
+        // Act
+        syncReviewVersion(deps);
+
+        // Assert
+        expect(writes["workflows/review/review.md"]).toBe(
+            "      ref: review-v1.5.0\n",
+        );
+    });
+
+    it("does not write when the ref is already current", () => {
+        // Arrange
+        const {writes, deps} = makeDeps({
+            "workflows/review/package.json":
+                '{"name": "review", "version": "1.5.0"}',
+            "workflows/review/review.md": "      ref: review-v1.5.0\n",
+        });
+
+        // Act
+        syncReviewVersion(deps);
+
+        // Assert
+        expect(writes).toEqual({});
+    });
+
+    it("throws when review.md has no review-v literal to sync", () => {
+        // Arrange
+        const {deps} = makeDeps({
+            "workflows/review/package.json":
+                '{"name": "review", "version": "1.5.0"}',
+            "workflows/review/review.md": "no pinned ref here\n",
+        });
+
+        // Act + Assert
+        expect(() => syncReviewVersion(deps)).toThrow(
+            /No review-v<semver> literals/,
+        );
+    });
+
+    it("throws when package.json has no version", () => {
+        // Arrange
+        const {deps} = makeDeps({
+            "workflows/review/package.json": '{"name": "review"}',
+            "workflows/review/review.md": "ref: review-v1.2.2\n",
+        });
+
+        // Act + Assert
+        expect(() => syncReviewVersion(deps)).toThrow(/No version found/);
+    });
+});
diff --git a/utils/sync-review-version-lib.ts b/utils/sync-review-version-lib.ts
new file mode 100644
index 00000000..fe999f1f
--- /dev/null
+++ b/utils/sync-review-version-lib.ts
@@ -0,0 +1,79 @@
+import * as fs from "fs";
+
+/**
+ * Keep the released-version literals inside workflows/review/review.md in
+ * sync with the "review" package version.
+ *
+ * review.md checks out Khan/actions at a pinned `ref: review-v<version>` tag
+ * to fetch the deterministic lib the prompt invokes at runtime; that ref is
+ * supposed to name the release the file ships in. Changesets bumps
+ * package.json but knows nothing about prose in a markdown file, so this
+ * script runs alongside `changeset version` (see the root package.json
+ * "version-packages" script, used by .github/workflows/release.yml) to
+ * rewrite every review-v<semver> literal in review.md to the version being
+ * released. That way the bump lands in the same Version Packages commit that
+ * gets tagged, and the tag's review.md pins its own release.
+ *
+ * workflows/review/version-sync.test.ts is the CI backstop: it fails when
+ * the literals and the package version diverge.
+ */
+
+export const REVIEW_MD_PATH = "workflows/review/review.md";
+export const REVIEW_PKG_PATH = "workflows/review/package.json";
+
+export const REVIEW_VERSION_RE = /review-v\d+\.\d+\.\d+/g;
+
+export const syncReviewVersionContent = (
+    content: string,
+    version: string,
+): {content: string; replaced: number} => {
+    let replaced = 0;
+    const next = content.replace(REVIEW_VERSION_RE, () => {
+        replaced += 1;
+        return `review-v${version}`;
+    });
+    return {content: next, replaced};
+};
+
+export type SyncReviewVersionDeps = {
+    readFileSyncImpl?: typeof fs.readFileSync;
+    writeFileSyncImpl?: typeof fs.writeFileSync;
+    log?: (message: string) => void;
+};
+
+export const syncReviewVersion = (deps: SyncReviewVersionDeps = {}): void => {
+    const readFileSyncImpl = deps.readFileSyncImpl ?? fs.readFileSync;
+    const writeFileSyncImpl = deps.writeFileSyncImpl ?? fs.writeFileSync;
+    const log = deps.log ?? console.log;
+
+    const pkg = JSON.parse(readFileSyncImpl(REVIEW_PKG_PATH, "utf-8"));
+    if (!pkg.version) {
+        throw new Error(`No version found in ${REVIEW_PKG_PATH}`);
+    }
+
+    const content = readFileSyncImpl(REVIEW_MD_PATH, "utf-8");
+    const {content: synced, replaced} = syncReviewVersionContent(
+        content,
+        pkg.version,
+    );
+
+    if (replaced === 0) {
+        // At minimum the pinned-checkout `ref:` line must match; finding
+        // nothing means the file was restructured and the sync went blind.
+        throw new Error(
+            `No review-v<semver> literals found in ${REVIEW_MD_PATH}; ` +
+                `expected at least the pinned checkout ref line.`,
+        );
+    }
+
+    if (synced === content) {
+        log(`${REVIEW_MD_PATH}: already at review-v${pkg.version}`);
+        return;
+    }
+
+    writeFileSyncImpl(REVIEW_MD_PATH, synced);
+    log(
+        `${REVIEW_MD_PATH}: synced ${replaced} review-v literal(s) ` +
+            `to review-v${pkg.version}`,
+    );
+};
diff --git a/utils/sync-review-version.ts b/utils/sync-review-version.ts
new file mode 100644
index 00000000..6c09a9dd
--- /dev/null
+++ b/utils/sync-review-version.ts
@@ -0,0 +1,13 @@
+/**
+ * Rewrite the review-v<version> literals in workflows/review/review.md (the
+ * pinned Khan/actions checkout ref) to the current "review" package version.
+ *
+ * Runs as part of the changesets version command (root package.json
+ * "version-packages", wired into .github/workflows/release.yml) so the bump
+ * lands in the same Version Packages commit that gets tagged.
+ *
+ * Usage: node -r @swc-node/register utils/sync-review-version.ts
+ */
+import {syncReviewVersion} from "./sync-review-version-lib.ts";
+
+syncReviewVersion();
diff --git a/workflows/review/README.md b/workflows/review/README.md
index da755173..793cec30 100644
--- a/workflows/review/README.md
+++ b/workflows/review/README.md
@@ -67,8 +67,8 @@ ceiling with everything spent and nothing posted.
 gh aw add Khan/actions/workflows/review/review.md
 
 # Or pin to a published version (recommended for stability):
-gh aw add Khan/actions/workflows/review/review.md@review-v0
-gh aw add Khan/actions/workflows/review/review.md@review-v0.1.0
+gh aw add Khan/actions/workflows/review/review.md@review-v<major>
+gh aw add Khan/actions/workflows/review/review.md@review-v<major>.<minor>.<patch>
 ```
 
 This copies `review.md` into the consuming repo's `.github/workflows/`, records a
@@ -76,6 +76,12 @@ This copies `review.md` into the consuming repo's `.github/workflows/`, records
 plus the consumer config files below. Pull future updates with `gh aw update`
 (a 3-way merge that preserves your local edits).
 
+The tag is self-consistent: the `review.md` inside each `review-v<version>` tag
+pins its own `pre-agent-steps` checkout `ref:` to that same version (the release
+flow rewrites it; see [Versioning](#versioning)), so after `gh aw add` or
+`gh aw update` the imported file already fetches the matching lib code and needs
+no manual fix-up of the ref.
+
 ## Consumer configuration
 
 The workflow imports the following files **from the consuming repo** (they resolve
@@ -213,6 +219,15 @@ tag) is cut **at the real commit tree** (not the rewritten-subtree bare tags tha
 the `actions/` packages use), so the nested `workflows/review/review.md@<ref>` path
 resolves for `gh aw add`.
 
+The pinned checkout `ref:` inside `review.md` is part of the release: the version
+command (`pnpm run version-packages`, wired into `release.yml`) runs
+`utils/sync-review-version.ts` after `changeset version`, rewriting every
+`review-v<semver>` literal in `review.md` to the version being released, so the
+bump lands in the same Version Packages commit that gets tagged.
+`version-sync.test.ts` here is the CI backstop: it fails any PR where those
+literals do not match the `review` package version (releases v1.3.0 through
+v1.4.0 shipped still pointing at v1.2.2, before the sync existed).
+
 ### Version attribution
 
 Semver is the behavior contract: a release that changes the reviewer's behavior bumps
diff --git a/workflows/review/review.md b/workflows/review/review.md
index ce516974..86dd4e60 100644
--- a/workflows/review/review.md
+++ b/workflows/review/review.md
@@ -196,16 +196,20 @@ models:
 # repo, so the job fetches the code itself: check out Khan/actions at the pinned
 # release below. The `ref` is the single version
 # surface for prompt + code: it names the Khan/actions release this file ships in
-# (changesets tag, `review-v<version>`), and any release that changes the prompt or
-# the lib bumps it. Steps that run lib scripts invoke them from `gh-aw-review-lib/`
-# via `npx -y tsx <script>`; npx fetches the runner on first use, so the checkout
-# needs no install step.
+# (changesets tag, `review-v<version>`). The bump is automated, not manual: the
+# release flow's version step (utils/sync-review-version.ts, run alongside
+# `changeset version` by release.yml) rewrites this ref to the version being
+# released, in the same Version Packages commit that gets tagged, and
+# workflows/review/version-sync.test.ts fails CI if the ref ever diverges from
+# the `review` package version. Steps that run lib scripts invoke them from
+# `gh-aw-review-lib/` via `npx -y tsx <script>`; npx fetches the runner on first
+# use, so the checkout needs no install step.
 pre-agent-steps:
   - name: Check out shared review lib (Khan/actions)
     uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
     with:
       repository: Khan/actions
-      ref: review-v1.2.2
+      ref: review-v1.4.0
       path: gh-aw-review-lib
       persist-credentials: false
 
diff --git a/workflows/review/version-sync.test.ts b/workflows/review/version-sync.test.ts
new file mode 100644
index 00000000..dfd64612
--- /dev/null
+++ b/workflows/review/version-sync.test.ts
@@ -0,0 +1,37 @@
+/**
+ * CI backstop for the review.md version surface.
+ *
+ * review.md checks out Khan/actions at a pinned `ref: review-v<version>` tag
+ * to fetch the lib code the prompt invokes at runtime; that ref must name the
+ * release the file ships in, or consumers get a prompt from one version
+ * running code from another (review-v1.3.0 through v1.4.0 shipped this way,
+ * still pointing at v1.2.2). The release flow keeps the ref true by running
+ * utils/sync-review-version.ts alongside `changeset version`; this test fails
+ * any PR (the Version Packages PR included) where the literals in review.md
+ * do not match the "review" package version.
+ */
+import * as fs from "fs";
+import {describe, expect, it} from "vitest";
+
+const reviewMd = fs.readFileSync(
+    new URL("./review.md", import.meta.url),
+    "utf-8",
+);
+const pkg = JSON.parse(
+    fs.readFileSync(new URL("./package.json", import.meta.url), "utf-8"),
+);
+
+describe("review.md version surface", () => {
+    it("pins the Khan/actions checkout ref to this release's version", () => {
+        const refs = [...reviewMd.matchAll(/^\s*ref:\s*(\S+)\s*$/gm)].map(
+            (m) => m[1],
+        );
+        expect(refs).toEqual([`review-v${pkg.version}`]);
+    });
+
+    it("matches every review-v<semver> literal to the package version", () => {
+        const literals = reviewMd.match(/review-v\d+\.\d+\.\d+/g) ?? [];
+        expect(literals.length).toBeGreaterThan(0);
+        expect(new Set(literals)).toEqual(new Set([`review-v${pkg.version}`]));
+    });
+});

From 3eafaabd2ffd2aba25b3ca3f5f1b5754ef14151e Mon Sep 17 00:00:00 2001
From: James Wiesebron <jameswiesebron@khanacademy.org>
Date: Fri, 10 Jul 2026 11:19:34 -0700
Subject: [PATCH 2/2] [jwies/review-version-sync] review: make the release
 version sync generic across workflows

Review feedback on #242: instead of a review-only script, discover every
workflow under workflows/ and rewrite its <name>-v<semver> literals (tag
names come from the directory name, matching publishWorkflow) in its
markdown files, skipping CHANGELOG.md. A workflow with no literals is a
no-op; per-workflow contract tests (workflows/review/version-sync.test.ts)
remain the CI backstop.
---
 .changeset/review-version-sync.md        |   2 +-
 .github/workflows/release.yml            |   9 +-
 package.json                             |   2 +-
 utils/sync-review-version-lib.test.ts    | 133 --------------
 utils/sync-review-version-lib.ts         |  79 ---------
 utils/sync-review-version.ts             |  13 --
 utils/sync-workflow-versions-lib.test.ts | 214 +++++++++++++++++++++++
 utils/sync-workflow-versions-lib.ts      | 122 +++++++++++++
 utils/sync-workflow-versions.ts          |  14 ++
 workflows/review/README.md               |   5 +-
 workflows/review/review.md               |   5 +-
 workflows/review/version-sync.test.ts    |   2 +-
 12 files changed, 364 insertions(+), 236 deletions(-)
 delete mode 100644 utils/sync-review-version-lib.test.ts
 delete mode 100644 utils/sync-review-version-lib.ts
 delete mode 100644 utils/sync-review-version.ts
 create mode 100644 utils/sync-workflow-versions-lib.test.ts
 create mode 100644 utils/sync-workflow-versions-lib.ts
 create mode 100644 utils/sync-workflow-versions.ts

diff --git a/.changeset/review-version-sync.md b/.changeset/review-version-sync.md
index 7778646a..5c4862e2 100644
--- a/.changeset/review-version-sync.md
+++ b/.changeset/review-version-sync.md
@@ -2,4 +2,4 @@
 "review": patch
 ---
 
-Keep the pinned `ref:` inside review.md in sync with the released version. The release flow's version command now runs `utils/sync-review-version.ts` after `changeset version`, rewriting every `review-v<semver>` literal in review.md to the version being released so the bump lands in the same Version Packages commit that gets tagged; `workflows/review/version-sync.test.ts` fails CI whenever the ref and the `review` package version diverge. Also bumps the currently stale ref from review-v1.2.2 to review-v1.4.0 (v1.3.0 through v1.4.0 shipped with the lagging ref, so an un-overridden consumer checked out a lib without `lib/provenance.ts`).
+Keep the pinned `ref:` inside review.md in sync with the released version. The release flow's version command now runs `utils/sync-workflow-versions.ts` after `changeset version`, rewriting every workflow's pinned `<name>-v<semver>` literals (for this workflow, the `ref:` inside review.md) to the version being released so the bump lands in the same Version Packages commit that gets tagged; `workflows/review/version-sync.test.ts` fails CI whenever the ref and the `review` package version diverge. Also bumps the currently stale ref from review-v1.2.2 to review-v1.4.0 (v1.3.0 through v1.4.0 shipped with the lagging ref, so an un-overridden consumer checked out a lib without `lib/provenance.ts`).
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 5b737ff3..f0a6b502 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -30,10 +30,11 @@ jobs:
         if: steps.has-changesets.outputs.result == 'true'
         uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1
         with:
-          # Not the default `changeset version`: version-packages also syncs
-          # the pinned `ref:` inside workflows/review/review.md to the version
-          # being released, so the bump lands in the same Version Packages
-          # commit that gets tagged (see utils/sync-review-version.ts).
+          # `version-packages` runs `changeset version` and then syncs each
+          # workflow's pinned `<name>-v<semver>` literals (e.g. the checkout
+          # ref inside workflows/review/review.md) to the version being
+          # released, so the bump lands in the same Version Packages commit
+          # that gets tagged (see utils/sync-workflow-versions.ts).
           version: pnpm run version-packages
           publish: exit 1
         env:
diff --git a/package.json b/package.json
index ae9c0cc6..3d5bed5e 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
     "repository": "git@github.com:Khan/actions.git",
     "private": true,
     "scripts": {
-        "version-packages": "changeset version && node -r @swc-node/register utils/sync-review-version.ts",
+        "version-packages": "changeset version && node -r @swc-node/register utils/sync-workflow-versions.ts",
         "lint": "eslint --ext .js,.mjs,.ts .",
         "fix": "pnpm run lint --fix",
         "test": "vitest",
diff --git a/utils/sync-review-version-lib.test.ts b/utils/sync-review-version-lib.test.ts
deleted file mode 100644
index 15126940..00000000
--- a/utils/sync-review-version-lib.test.ts
+++ /dev/null
@@ -1,133 +0,0 @@
-import {describe, expect, it, vi} from "vitest";
-import {
-    syncReviewVersion,
-    syncReviewVersionContent,
-} from "./sync-review-version-lib.ts";
-
-describe("syncReviewVersionContent", () => {
-    it("rewrites the pinned checkout ref to the given version", () => {
-        // Arrange: a stale ref, as shipped in review-v1.3.0 through v1.4.0.
-        const content = [
-            "pre-agent-steps:",
-            "  - uses: actions/checkout@abc # v5",
-            "    with:",
-            "      repository: Khan/actions",
-            "      ref: review-v1.2.2",
-        ].join("\n");
-
-        // Act
-        const result = syncReviewVersionContent(content, "9.9.9");
-
-        // Assert
-        expect(result.replaced).toBe(1);
-        expect(result.content).toContain("ref: review-v9.9.9");
-        expect(result.content).not.toContain("review-v1.2.2");
-    });
-
-    it("rewrites every semver literal but leaves templates alone", () => {
-        // Arrange
-        const content =
-            "ref: review-v1.2.2\n" +
-            "the marker is `v=review-v<version>` (a template)\n" +
-            "released as review-v1.3.0\n";
-
-        // Act
-        const result = syncReviewVersionContent(content, "2.0.0");
-
-        // Assert
-        expect(result.replaced).toBe(2);
-        expect(result.content).toBe(
-            "ref: review-v2.0.0\n" +
-                "the marker is `v=review-v<version>` (a template)\n" +
-                "released as review-v2.0.0\n",
-        );
-    });
-
-    it("returns unchanged content when already at the version", () => {
-        // Act
-        const result = syncReviewVersionContent("ref: review-v1.4.0", "1.4.0");
-
-        // Assert
-        expect(result.replaced).toBe(1);
-        expect(result.content).toBe("ref: review-v1.4.0");
-    });
-});
-
-describe("syncReviewVersion", () => {
-    const makeDeps = (files: Record<string, string>) => {
-        const writes: Record<string, string> = {};
-        return {
-            writes,
-            deps: {
-                readFileSyncImpl: ((p: string) => {
-                    const content = files[p];
-                    if (content === undefined) {
-                        throw new Error(`unexpected read: ${p}`);
-                    }
-                    return content;
-                }) as never,
-                writeFileSyncImpl: ((p: string, data: string) => {
-                    writes[p] = data;
-                }) as never,
-                log: vi.fn(),
-            },
-        };
-    };
-
-    it("writes review.md with the package version substituted", () => {
-        // Arrange
-        const {writes, deps} = makeDeps({
-            "workflows/review/package.json":
-                '{"name": "review", "version": "1.5.0"}',
-            "workflows/review/review.md": "      ref: review-v1.2.2\n",
-        });
-
-        // Act
-        syncReviewVersion(deps);
-
-        // Assert
-        expect(writes["workflows/review/review.md"]).toBe(
-            "      ref: review-v1.5.0\n",
-        );
-    });
-
-    it("does not write when the ref is already current", () => {
-        // Arrange
-        const {writes, deps} = makeDeps({
-            "workflows/review/package.json":
-                '{"name": "review", "version": "1.5.0"}',
-            "workflows/review/review.md": "      ref: review-v1.5.0\n",
-        });
-
-        // Act
-        syncReviewVersion(deps);
-
-        // Assert
-        expect(writes).toEqual({});
-    });
-
-    it("throws when review.md has no review-v literal to sync", () => {
-        // Arrange
-        const {deps} = makeDeps({
-            "workflows/review/package.json":
-                '{"name": "review", "version": "1.5.0"}',
-            "workflows/review/review.md": "no pinned ref here\n",
-        });
-
-        // Act + Assert
-        expect(() => syncReviewVersion(deps)).toThrow(
-            /No review-v<semver> literals/,
-        );
-    });
-
-    it("throws when package.json has no version", () => {
-        // Arrange
-        const {deps} = makeDeps({
-            "workflows/review/package.json": '{"name": "review"}',
-            "workflows/review/review.md": "ref: review-v1.2.2\n",
-        });
-
-        // Act + Assert
-        expect(() => syncReviewVersion(deps)).toThrow(/No version found/);
-    });
-});
diff --git a/utils/sync-review-version-lib.ts b/utils/sync-review-version-lib.ts
deleted file mode 100644
index fe999f1f..00000000
--- a/utils/sync-review-version-lib.ts
+++ /dev/null
@@ -1,79 +0,0 @@
-import * as fs from "fs";
-
-/**
- * Keep the released-version literals inside workflows/review/review.md in
- * sync with the "review" package version.
- *
- * review.md checks out Khan/actions at a pinned `ref: review-v<version>` tag
- * to fetch the deterministic lib the prompt invokes at runtime; that ref is
- * supposed to name the release the file ships in. Changesets bumps
- * package.json but knows nothing about prose in a markdown file, so this
- * script runs alongside `changeset version` (see the root package.json
- * "version-packages" script, used by .github/workflows/release.yml) to
- * rewrite every review-v<semver> literal in review.md to the version being
- * released. That way the bump lands in the same Version Packages commit that
- * gets tagged, and the tag's review.md pins its own release.
- *
- * workflows/review/version-sync.test.ts is the CI backstop: it fails when
- * the literals and the package version diverge.
- */
-
-export const REVIEW_MD_PATH = "workflows/review/review.md";
-export const REVIEW_PKG_PATH = "workflows/review/package.json";
-
-export const REVIEW_VERSION_RE = /review-v\d+\.\d+\.\d+/g;
-
-export const syncReviewVersionContent = (
-    content: string,
-    version: string,
-): {content: string; replaced: number} => {
-    let replaced = 0;
-    const next = content.replace(REVIEW_VERSION_RE, () => {
-        replaced += 1;
-        return `review-v${version}`;
-    });
-    return {content: next, replaced};
-};
-
-export type SyncReviewVersionDeps = {
-    readFileSyncImpl?: typeof fs.readFileSync;
-    writeFileSyncImpl?: typeof fs.writeFileSync;
-    log?: (message: string) => void;
-};
-
-export const syncReviewVersion = (deps: SyncReviewVersionDeps = {}): void => {
-    const readFileSyncImpl = deps.readFileSyncImpl ?? fs.readFileSync;
-    const writeFileSyncImpl = deps.writeFileSyncImpl ?? fs.writeFileSync;
-    const log = deps.log ?? console.log;
-
-    const pkg = JSON.parse(readFileSyncImpl(REVIEW_PKG_PATH, "utf-8"));
-    if (!pkg.version) {
-        throw new Error(`No version found in ${REVIEW_PKG_PATH}`);
-    }
-
-    const content = readFileSyncImpl(REVIEW_MD_PATH, "utf-8");
-    const {content: synced, replaced} = syncReviewVersionContent(
-        content,
-        pkg.version,
-    );
-
-    if (replaced === 0) {
-        // At minimum the pinned-checkout `ref:` line must match; finding
-        // nothing means the file was restructured and the sync went blind.
-        throw new Error(
-            `No review-v<semver> literals found in ${REVIEW_MD_PATH}; ` +
-                `expected at least the pinned checkout ref line.`,
-        );
-    }
-
-    if (synced === content) {
-        log(`${REVIEW_MD_PATH}: already at review-v${pkg.version}`);
-        return;
-    }
-
-    writeFileSyncImpl(REVIEW_MD_PATH, synced);
-    log(
-        `${REVIEW_MD_PATH}: synced ${replaced} review-v literal(s) ` +
-            `to review-v${pkg.version}`,
-    );
-};
diff --git a/utils/sync-review-version.ts b/utils/sync-review-version.ts
deleted file mode 100644
index 6c09a9dd..00000000
--- a/utils/sync-review-version.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-/**
- * Rewrite the review-v<version> literals in workflows/review/review.md (the
- * pinned Khan/actions checkout ref) to the current "review" package version.
- *
- * Runs as part of the changesets version command (root package.json
- * "version-packages", wired into .github/workflows/release.yml) so the bump
- * lands in the same Version Packages commit that gets tagged.
- *
- * Usage: node -r @swc-node/register utils/sync-review-version.ts
- */
-import {syncReviewVersion} from "./sync-review-version-lib.ts";
-
-syncReviewVersion();
diff --git a/utils/sync-workflow-versions-lib.test.ts b/utils/sync-workflow-versions-lib.test.ts
new file mode 100644
index 00000000..dfa607af
--- /dev/null
+++ b/utils/sync-workflow-versions-lib.test.ts
@@ -0,0 +1,214 @@
+import {describe, expect, it, vi} from "vitest";
+import {
+    syncWorkflowVersionContent,
+    syncWorkflowVersions,
+    type DirEntryLike,
+} from "./sync-workflow-versions-lib.ts";
+
+describe("syncWorkflowVersionContent", () => {
+    it("rewrites the pinned checkout ref to the given version", () => {
+        // Arrange: a stale ref, as shipped in review-v1.3.0 through v1.4.0.
+        const content = [
+            "pre-agent-steps:",
+            "  - uses: actions/checkout@abc # v5",
+            "    with:",
+            "      repository: Khan/actions",
+            "      ref: review-v1.2.2",
+        ].join("\n");
+
+        // Act
+        const result = syncWorkflowVersionContent(content, "review", "9.9.9");
+
+        // Assert
+        expect(result.replaced).toBe(1);
+        expect(result.content).toContain("ref: review-v9.9.9");
+        expect(result.content).not.toContain("review-v1.2.2");
+    });
+
+    it("rewrites every semver literal but leaves templates alone", () => {
+        // Arrange
+        const content =
+            "ref: review-v1.2.2\n" +
+            "the marker is `v=review-v<version>` (a template)\n" +
+            "released as review-v1.3.0\n";
+
+        // Act
+        const result = syncWorkflowVersionContent(content, "review", "2.0.0");
+
+        // Assert
+        expect(result.replaced).toBe(2);
+        expect(result.content).toBe(
+            "ref: review-v2.0.0\n" +
+                "the marker is `v=review-v<version>` (a template)\n" +
+                "released as review-v2.0.0\n",
+        );
+    });
+
+    it("leaves other workflows' literals alone", () => {
+        // Arrange
+        const content = "ref: review-v1.2.2\nsee also triage-v3.0.0\n";
+
+        // Act
+        const result = syncWorkflowVersionContent(content, "review", "2.0.0");
+
+        // Assert
+        expect(result.replaced).toBe(1);
+        expect(result.content).toBe(
+            "ref: review-v2.0.0\nsee also triage-v3.0.0\n",
+        );
+    });
+
+    it("returns unchanged content when already at the version", () => {
+        // Act
+        const result = syncWorkflowVersionContent(
+            "ref: review-v1.4.0",
+            "review",
+            "1.4.0",
+        );
+
+        // Assert
+        expect(result.replaced).toBe(1);
+        expect(result.content).toBe("ref: review-v1.4.0");
+    });
+});
+
+describe("syncWorkflowVersions", () => {
+    const makeDeps = (files: Record<string, string>) => {
+        const writes: Record<string, string> = {};
+        const readdirSyncImpl = (dir: string): DirEntryLike[] => {
+            const children = new Map<string, boolean>();
+            for (const path of Object.keys(files)) {
+                if (!path.startsWith(`${dir}/`)) {
+                    continue;
+                }
+                const rest = path.slice(dir.length + 1);
+                const slash = rest.indexOf("/");
+                children.set(
+                    slash === -1 ? rest : rest.slice(0, slash),
+                    slash !== -1,
+                );
+            }
+            return [...children].map(([name, isDir]) => ({
+                name,
+                isDirectory: () => isDir,
+                isFile: () => !isDir,
+            }));
+        };
+        return {
+            writes,
+            deps: {
+                readFileSyncImpl: (path: string) => {
+                    const content = files[path];
+                    if (content === undefined) {
+                        throw new Error(`unexpected read: ${path}`);
+                    }
+                    return content;
+                },
+                writeFileSyncImpl: (path: string, data: string) => {
+                    writes[path] = data;
+                },
+                readdirSyncImpl,
+                log: vi.fn(),
+            },
+        };
+    };
+
+    it("writes review.md with the package version substituted", () => {
+        // Arrange
+        const {writes, deps} = makeDeps({
+            "workflows/review/package.json":
+                '{"name": "review", "version": "1.5.0"}',
+            "workflows/review/review.md": "      ref: review-v1.2.2\n",
+        });
+
+        // Act
+        syncWorkflowVersions(deps);
+
+        // Assert
+        expect(writes["workflows/review/review.md"]).toBe(
+            "      ref: review-v1.5.0\n",
+        );
+    });
+
+    it("syncs every workflow to its own version", () => {
+        // Arrange
+        const {writes, deps} = makeDeps({
+            "workflows/review/package.json":
+                '{"name": "review", "version": "1.5.0"}',
+            "workflows/review/review.md": "ref: review-v1.2.2\n",
+            "workflows/triage/package.json":
+                '{"name": "triage", "version": "2.1.0"}',
+            "workflows/triage/triage.md":
+                "ref: triage-v2.0.0\nsee review-v1.2.2\n",
+        });
+
+        // Act
+        syncWorkflowVersions(deps);
+
+        // Assert: each workflow gets its own version, and a mention of
+        // another workflow's tag is not rewritten.
+        expect(writes["workflows/review/review.md"]).toBe(
+            "ref: review-v1.5.0\n",
+        );
+        expect(writes["workflows/triage/triage.md"]).toBe(
+            "ref: triage-v2.1.0\nsee review-v1.2.2\n",
+        );
+    });
+
+    it("never rewrites CHANGELOG.md", () => {
+        // Arrange: the changelog holds historic versions on purpose.
+        const {writes, deps} = makeDeps({
+            "workflows/review/package.json":
+                '{"name": "review", "version": "1.5.0"}',
+            "workflows/review/review.md": "ref: review-v1.5.0\n",
+            "workflows/review/CHANGELOG.md": "## review-v1.2.2 notes\n",
+        });
+
+        // Act
+        syncWorkflowVersions(deps);
+
+        // Assert
+        expect(writes).toEqual({});
+    });
+
+    it("is a no-op for a workflow with no version literals", () => {
+        // Arrange
+        const {writes, deps} = makeDeps({
+            "workflows/triage/package.json":
+                '{"name": "triage", "version": "2.0.0"}',
+            "workflows/triage/triage.md": "no pinned ref here\n",
+        });
+
+        // Act
+        syncWorkflowVersions(deps);
+
+        // Assert
+        expect(writes).toEqual({});
+    });
+
+    it("does not write when the ref is already current", () => {
+        // Arrange
+        const {writes, deps} = makeDeps({
+            "workflows/review/package.json":
+                '{"name": "review", "version": "1.5.0"}',
+            "workflows/review/review.md": "      ref: review-v1.5.0\n",
+        });
+
+        // Act
+        syncWorkflowVersions(deps);
+
+        // Assert
+        expect(writes).toEqual({});
+    });
+
+    it("throws when a workflow's package.json has no version", () => {
+        // Arrange
+        const {deps} = makeDeps({
+            "workflows/review/package.json": '{"name": "review"}',
+            "workflows/review/review.md": "ref: review-v1.2.2\n",
+        });
+
+        // Act + Assert
+        expect(() => syncWorkflowVersions(deps)).toThrow(/No version found/);
+    });
+});
diff --git a/utils/sync-workflow-versions-lib.ts b/utils/sync-workflow-versions-lib.ts
new file mode 100644
index 00000000..d113788d
--- /dev/null
+++ b/utils/sync-workflow-versions-lib.ts
@@ -0,0 +1,122 @@
+import * as fs from "fs";
+
+/**
+ * Keep released-version literals inside each workflow's markdown in sync
+ * with that workflow's package version.
+ *
+ * A workflow under `workflows/<name>/` is released as a `<name>-v<version>`
+ * git tag named after the directory (see publishWorkflow in
+ * utils/publish.ts), and its markdown may embed that tag as a literal:
+ * review.md, for example, checks out Khan/actions at a pinned
+ * `ref: review-v<version>` tag to fetch the deterministic lib the prompt
+ * invokes at runtime. Changesets bumps package.json but knows nothing about
+ * prose in a markdown file, so this script runs alongside `changeset version`
+ * (see the root package.json "version-packages" script, used by
+ * .github/workflows/release.yml) to rewrite every `<name>-v<semver>` literal
+ * in each workflow's markdown to the version being released. That way the
+ * bump lands in the same Version Packages commit that gets tagged, and each
+ * tag's markdown pins its own release.
+ *
+ * CHANGELOG.md is skipped (changesets writes historic versions there on
+ * purpose), and a workflow whose markdown embeds no literal is a no-op. A
+ * workflow that must embed one enforces that with its own contract test;
+ * workflows/review/version-sync.test.ts is the CI backstop that fails when
+ * review.md's literals and the `review` package version diverge.
+ */
+
+export const WORKFLOWS_DIR = "workflows";
+
+const escapeRegExp = (value: string): string =>
+    value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export const workflowVersionRe = (name: string): RegExp =>
+    new RegExp(`${escapeRegExp(name)}-v\\d+\\.\\d+\\.\\d+`, "g");
+
+export const syncWorkflowVersionContent = (
+    content: string,
+    name: string,
+    version: string,
+): {content: string; replaced: number} => {
+    let replaced = 0;
+    const next = content.replace(workflowVersionRe(name), () => {
+        replaced += 1;
+        return `${name}-v${version}`;
+    });
+    return {content: next, replaced};
+};
+
+export type DirEntryLike = {
+    name: string;
+    isDirectory: () => boolean;
+    isFile: () => boolean;
+};
+
+export type SyncWorkflowVersionsDeps = {
+    readFileSyncImpl?: (path: string, encoding: "utf-8") => string;
+    writeFileSyncImpl?: (path: string, data: string) => void;
+    readdirSyncImpl?: (path: string) => DirEntryLike[];
+    log?: (message: string) => void;
+};
+
+export const syncWorkflowVersions = (
+    deps: SyncWorkflowVersionsDeps = {},
+): void => {
+    const readFileSyncImpl =
+        deps.readFileSyncImpl ??
+        ((path: string, encoding: "utf-8") => fs.readFileSync(path, encoding));
+    const writeFileSyncImpl = deps.writeFileSyncImpl ?? fs.writeFileSync;
+    const readdirSyncImpl =
+        deps.readdirSyncImpl ??
+        ((path: string) => fs.readdirSync(path, {withFileTypes: true}));
+    const log = deps.log ?? console.log;
+
+    const workflowNames = readdirSyncImpl(WORKFLOWS_DIR)
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+
+    for (const name of workflowNames) {
+        // The release tag is named after the directory, not package.json's
+        // "name" field (see publishWorkflow in utils/publish.ts).
+        const pkgPath = `${WORKFLOWS_DIR}/${name}/package.json`;
+        const pkg = JSON.parse(readFileSyncImpl(pkgPath, "utf-8"));
+        if (!pkg.version) {
+            throw new Error(`No version found in ${pkgPath}`);
+        }
+
+        const markdownFiles = readdirSyncImpl(`${WORKFLOWS_DIR}/${name}`)
+            .filter(
+                (entry) =>
+                    entry.isFile() &&
+                    entry.name.endsWith(".md") &&
+                    // Changesets writes historic versions to the changelog;
+                    // those must stay as released.
+                    entry.name !== "CHANGELOG.md",
+            )
+            .map((entry) => entry.name);
+
+        for (const fileName of markdownFiles) {
+            const filePath = `${WORKFLOWS_DIR}/${name}/${fileName}`;
+            const content = readFileSyncImpl(filePath, "utf-8");
+            const {content: synced, replaced} = syncWorkflowVersionContent(
+                content,
+                name,
+                pkg.version,
+            );
+
+            if (replaced === 0) {
+                continue;
+            }
+
+            if (synced === content) {
+                log(`${filePath}: already at ${name}-v${pkg.version}`);
+                continue;
+            }
+
+            writeFileSyncImpl(filePath, synced);
+            log(
+                `${filePath}: synced ${replaced} ${name}-v literal(s) ` +
+                    `to ${name}-v${pkg.version}`,
+            );
+        }
+    }
+};
diff --git a/utils/sync-workflow-versions.ts b/utils/sync-workflow-versions.ts
new file mode 100644
index 00000000..680c92b1
--- /dev/null
+++ b/utils/sync-workflow-versions.ts
@@ -0,0 +1,14 @@
+/**
+ * Rewrite each workflow's `<name>-v<semver>` literals (e.g. the pinned
+ * Khan/actions checkout ref inside workflows/review/review.md) to that
+ * workflow's current package version.
+ *
+ * Runs as part of the changesets version command (root package.json
+ * "version-packages", wired into .github/workflows/release.yml) so the bump
+ * lands in the same Version Packages commit that gets tagged.
+ *
+ * Usage: node -r @swc-node/register utils/sync-workflow-versions.ts
+ */
+import {syncWorkflowVersions} from "./sync-workflow-versions-lib.ts";
+
+syncWorkflowVersions();
diff --git a/workflows/review/README.md b/workflows/review/README.md
index 793cec30..6f43c20b 100644
--- a/workflows/review/README.md
+++ b/workflows/review/README.md
@@ -221,8 +221,9 @@ resolves for `gh aw add`.
 
 The pinned checkout `ref:` inside `review.md` is part of the release: the version
 command (`pnpm run version-packages`, wired into `release.yml`) runs
-`utils/sync-review-version.ts` after `changeset version`, rewriting every
-`review-v<semver>` literal in `review.md` to the version being released, so the
+`utils/sync-workflow-versions.ts` after `changeset version`, rewriting every
+`<workflow>-v<semver>` literal in each workflow's markdown (for this workflow,
+every `review-v<semver>` in `review.md`) to the version being released, so the
 bump lands in the same Version Packages commit that gets tagged.
 `version-sync.test.ts` here is the CI backstop: it fails any PR where those
 literals do not match the `review` package version (releases v1.3.0 through
diff --git a/workflows/review/review.md b/workflows/review/review.md
index 86dd4e60..90f9a207 100644
--- a/workflows/review/review.md
+++ b/workflows/review/review.md
@@ -197,8 +197,9 @@ models:
 # release below. The `ref` is the single version
 # surface for prompt + code: it names the Khan/actions release this file ships in
 # (changesets tag, `review-v<version>`). The bump is automated, not manual: the
-# release flow's version step (utils/sync-review-version.ts, run alongside
-# `changeset version` by release.yml) rewrites this ref to the version being
+# release flow's version step (utils/sync-workflow-versions.ts, run alongside
+# `changeset version` by release.yml) rewrites every workflow's pinned
+# `<name>-v<semver>` literals, this ref included, to the version being
 # released, in the same Version Packages commit that gets tagged, and
 # workflows/review/version-sync.test.ts fails CI if the ref ever diverges from
 # the `review` package version. Steps that run lib scripts invoke them from
diff --git a/workflows/review/version-sync.test.ts b/workflows/review/version-sync.test.ts
index dfd64612..1c43f4f8 100644
--- a/workflows/review/version-sync.test.ts
+++ b/workflows/review/version-sync.test.ts
@@ -6,7 +6,7 @@
  * release the file ships in, or consumers get a prompt from one version
  * running code from another (review-v1.3.0 through v1.4.0 shipped this way,
  * still pointing at v1.2.2). The release flow keeps the ref true by running
- * utils/sync-review-version.ts alongside `changeset version`; this test fails
+ * utils/sync-workflow-versions.ts alongside `changeset version`; this test fails
  * any PR (the Version Packages PR included) where the literals in review.md
  * do not match the "review" package version.
  */