From 4ab69ce355e3d6c9f968ce89b61574b8a079eb77 Mon Sep 17 00:00:00 2001
From: Max Haarhaus <max@seekinsights.com>
Date: Mon, 10 Aug 2026 02:09:16 -0400
Subject: [PATCH] chore(ci): update release pr notes template

---
 .github/workflows/release-pr.yml | 17 ++++++++++++++++-
 .github/workflows/release.yml    |  2 +-
 tests/release-workflows.test.ts  | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 49 insertions(+), 2 deletions(-)
 create mode 100644 tests/release-workflows.test.ts

diff --git a/.github/workflows/release-pr.yml b/.github/workflows/release-pr.yml
index b5804fc0..f0edbcc8 100644
--- a/.github/workflows/release-pr.yml
+++ b/.github/workflows/release-pr.yml
@@ -57,9 +57,24 @@ jobs:
           PR_BODY_FILE=$(mktemp)
           cat > "$PR_BODY_FILE" <<'EOF'
           <!-- release-notes -->
+          <!-- release-notes:todo — remove this line once the notes below are final. While this marker is present, merging falls back to GitHub's auto-generated notes. -->
           ## Release notes
 
-          _Replace this paragraph with a short narrative for the release. If left unchanged, GitHub's auto-generated notes will be used instead._
+          ### Highlights
+
+          <!-- One narrative bullet per theme: what changed and why it matters to a user. Group related work; don't echo commit messages. -->
+
+          ### Behavior changes to know about
+
+          <!-- Observable deltas: changed defaults, renamed output, compatibility notes. Omit the section when empty. -->
+
+          ### Fixes
+
+          <!-- Bugs fixed: the observable symptom, then the cause. Omit the section when empty. -->
+
+          ### Internal changes
+
+          <!-- Refactors, test and infrastructure work. Omit the section when empty. -->
           EOF
 
           PR_URL=$(gh pr create \
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c829f67b..50ee0682 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -54,7 +54,7 @@ jobs:
             --json body \
             --jq '.[0].body // ""')
 
-          if [ -n "$PR_BODY" ] && ! echo "$PR_BODY" | grep -q "Replace this paragraph"; then
+          if [ -n "$PR_BODY" ] && ! echo "$PR_BODY" | grep -q "release-notes:todo"; then
             echo "Using release PR body for notes."
             printf '%s\n' "$PR_BODY" > /tmp/release-notes.md
           else
diff --git a/tests/release-workflows.test.ts b/tests/release-workflows.test.ts
new file mode 100644
index 00000000..1297c579
--- /dev/null
+++ b/tests/release-workflows.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+
+const REPO_ROOT = path.resolve(import.meta.dir, "..");
+
+describe("release notes workflow contract", () => {
+  const releasePrWorkflow = fs.readFileSync(
+    path.join(REPO_ROOT, ".github/workflows/release-pr.yml"),
+    "utf8",
+  );
+  const releaseWorkflow = fs.readFileSync(
+    path.join(REPO_ROOT, ".github/workflows/release.yml"),
+    "utf8",
+  );
+
+  test("release PRs start with the structured notes skeleton", () => {
+    expect(releasePrWorkflow).toContain("<!-- release-notes -->");
+    expect(releasePrWorkflow).toContain("<!-- release-notes:todo");
+    expect(releasePrWorkflow).toContain("## Release notes");
+    expect(releasePrWorkflow).toContain("### Highlights");
+    expect(releasePrWorkflow).toContain("### Behavior changes to know about");
+    expect(releasePrWorkflow).toContain("### Fixes");
+    expect(releasePrWorkflow).toContain("### Internal changes");
+    expect(releasePrWorkflow).not.toContain("Replace this paragraph");
+  });
+
+  test("release creation falls back while the todo marker remains", () => {
+    expect(releaseWorkflow).toContain('grep -q "release-notes:todo"');
+    expect(releaseWorkflow).not.toContain("Replace this paragraph");
+  });
+});