From 73e0153a026a58ca9d4fa40e604336a547324865 Mon Sep 17 00:00:00 2001
From: Jacek <jacek@clerk.dev>
Date: Thu, 21 May 2026 15:58:51 -0500
Subject: [PATCH] ci(repo): add hotload boundary review gate

---
 .changeset/hotload-boundary-review-gate.md    |  2 +
 .github/PULL_REQUEST_TEMPLATE.md              | 14 ++++
 .github/workflows/hotload-boundary-review.yml | 72 +++++++++++++++++++
 3 files changed, 88 insertions(+)
 create mode 100644 .changeset/hotload-boundary-review-gate.md
 create mode 100644 .github/workflows/hotload-boundary-review.yml

diff --git a/.changeset/hotload-boundary-review-gate.md b/.changeset/hotload-boundary-review-gate.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/hotload-boundary-review-gate.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index a80ec1b0b37..1d6770b83c4 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -19,6 +19,20 @@
 - [ ] `pnpm build` runs as expected.
 - [ ] (If applicable) [JSDoc comments](https://jsdoc.app/about-getting-started.html) have been added or updated for any package exports
 - [ ] (If applicable) [Documentation](https://github.com/clerk/clerk-docs) has been updated
+- [ ] (If applicable) Hotload-boundary review completed for Clerk core / IsomorphicClerk changes.
+
+<!--
+  Complete the hotload-boundary review item when this PR changes:
+  - packages/clerk-js/src/core/clerk.ts
+  - packages/react/src/isomorphicClerk.ts
+
+  Non-major releases in packages/clerk-js and packages/ui can hotload into
+  applications that still have older framework SDKs or @clerk/shared installed.
+  If this PR removes, renames, or changes a Clerk / IsomorphicClerk member,
+  explicitly document whether older installed packages consume it across that
+  hotload boundary. A cross-boundary member needs a compatibility shim,
+  deprecation plan, or major-version removal plan.
+-->
 
 ## Type of change
 
diff --git a/.github/workflows/hotload-boundary-review.yml b/.github/workflows/hotload-boundary-review.yml
new file mode 100644
index 00000000000..5f4352246bf
--- /dev/null
+++ b/.github/workflows/hotload-boundary-review.yml
@@ -0,0 +1,72 @@
+name: Hotload Boundary Review
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened, ready_for_review]
+    branches:
+      - main
+      - release/v4
+      - release/core-2
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  clerk-core-review:
+    name: Clerk Core Review Gate
+    if: ${{ github.event.pull_request.draft == false }}
+    runs-on: ${{ vars.RUNNER_NORMAL || 'ubuntu-latest' }}
+    timeout-minutes: ${{ vars.TIMEOUT_MINUTES_SHORT && fromJSON(vars.TIMEOUT_MINUTES_SHORT) || 3 }}
+    steps:
+      - name: Verify hotload-boundary review
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const guardedPaths = new Set([
+              'packages/clerk-js/src/core/clerk.ts',
+              'packages/react/src/isomorphicClerk.ts',
+            ]);
+            const markerPattern =
+              /- \[[xX]\] \(If applicable\) Hotload-boundary review completed for Clerk core \/ IsomorphicClerk changes\./;
+
+            const { owner, repo } = context.repo;
+            const pull_number = context.payload.pull_request.number;
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner,
+              repo,
+              pull_number,
+              per_page: 100,
+            });
+            const touchedGuardedPaths = files
+              .map(file => file.filename)
+              .filter(filename => guardedPaths.has(filename));
+
+            if (touchedGuardedPaths.length === 0) {
+              core.info('No Clerk core hotload-boundary files changed.');
+              return;
+            }
+
+            await core.summary
+              .addHeading('Hotload Boundary Review')
+              .addRaw(
+                'This PR changes files that define Clerk runtime members consumed across hotloaded package boundaries.\n\n',
+              )
+              .addList(touchedGuardedPaths)
+              .addRaw(
+                '\nConfirm the PR template checklist item after reviewing whether changed `Clerk` / `IsomorphicClerk` members are consumed by older installed SDK packages.\n',
+              )
+              .write();
+
+            const body = context.payload.pull_request.body ?? '';
+            if (!markerPattern.test(body)) {
+              core.setFailed(
+                [
+                  'This PR changes Clerk core hotload-boundary files:',
+                  ...touchedGuardedPaths.map(path => `- ${path}`),
+                  '',
+                  'Check the PR template item "Hotload-boundary review completed for Clerk core / IsomorphicClerk changes." after documenting the compatibility decision.',
+                  'Non-major Clerk.js and UI releases can hotload into apps with older installed SDK packages, so removals or renames need a compatibility shim, deprecation plan, or major-version removal plan.',
+                ].join('\n'),
+              );
+            }