feat(workflows): Add Claude AI SDK breaking change check workflow

[KevinDavilaDotCMS]

Automate MinSdkVersion.VALUE maintenance via the release pipeline

Closes #36698

Problem

Follow-up to #36609 / #36678 (the SDK compatibility handshake). That work shipped
MinSdkVersion.java — a constant read by SdkVersionWebInterceptor and sent to every
@dotcms/* SDK consumer via the X-DotCMS-Min-SDK response header — but left its maintenance
fully manual: a developer had to remember to edit the constant by hand in their PR whenever a
change broke SDK compatibility ("Option A" from the original ticket: set it to whatever
@dotcms/client version was currently latest on npm at PR time).

That's fragile in two ways:

• Nothing stops a developer from simply forgetting.
• The "npm latest at PR time" heuristic has a known gap when the breaking change also needs an
  SDK-side fix — the version that's latest at PR time necessarily predates that fix.

This PR replaces the manual edit with a release-pipeline-driven mechanism with a safety net at
both ends: PR-time detection and release-time enforcement.

What this ships

1. SDK Breaking Change label + AI detector (ai_claude-sdk-breaking-change.yml) — runs on
   every PR, evaluates the diff against a new reference doc, and labels PRs that break SDK
   compatibility.
2. docs/core/SDK_BREAKING_CHANGE_CATEGORIES.md — the reference doc the AI (and human
   reviewers) use to judge what counts as SDK-breaking, grounded in the actual @dotcms/client
   surface (GraphQL page/content API, REST responses, the UVE postMessage protocol, the
   compatibility headers themselves).
3. A new bump_min_sdk_version release input on cicd_6-release.yml — "does this release
   include an SDK-breaking change?"
4. A release-time validation gate — fails the release outright if a merged PR since the last
   release carries the label but the operator left the checkbox unchecked.
5. A post-release bump job — once the release fully succeeds, opens a PR (never a direct
   push) bumping MinSdkVersion.VALUE to the release version and pings Slack for human review.
6. Updated Javadoc on MinSdkVersion.java describing this procedure.

Design decisions worth knowing about for review

Why the bump happens after the release succeeds, not during release-prepare.
The obvious-looking approach — folding the bump into release-prepare's existing automated
commit (the same one that already updates LICENSE and .mvn/maven.config) — is wrong for this
value specifically. That commit only ever lives on the disposable release-${version} branch,
which is never merged back to main. That's fine for LICENSE, because
update-license-date.sh recomputes the date fresh from "today" on every run — it never depends
on prior state. MinSdkVersion.VALUE is the opposite: it's a ratchet that must persist forward
across releases. If it only ever lived on the release branch, the next release-prepare run would
silently start again from main's stale value.

That in turn means timing matters: the bump can only safely happen once we know the release
shipped (build + deployment both green). If we bumped main eagerly in release-prepare and the
release then failed downstream, main would advertise a stricter compatibility floor for a
dotCMS version that customers never actually received — breaking currently-valid SDK installs for
nothing.

Why it's a PR, never a direct push to main.
Confirmed via the exact historical precedent for this same problem: the now-retired
cicd_manual-release-sdks.yml had to persist a version bump (core-web/libs/sdk/VERSION) onto
main after a release, and its solution was a dedicated "Open post-release PR to bump VERSION on
main" step — never a direct push. The PR it produced (#36563) was opened by github-actions[bot]
but merged by a human. There's no auto-merge anywhere in this repo's workflows to lean on instead.

Why one label, not four.
An earlier draft of this mechanism mirrored ai_claude-rollback-safety.yml's label scheme
exactly: AI: X / AI: Not X / Human: X / Human: Not X. For rollback-safety that split earns
its keep — a "clear stale AI labels on every push" preflight needs to not clobber a human's
deliberate override. For this mechanism we simplified to a single label, SDK Breaking Change:

• The AI only ever adds it when it detects a break (with an explanatory PR comment). It never
  removes it.
• Removing the label — because a human disagrees with the AI's verdict — is a plain manual
  action, available to anyone with write access. No separate Human: ... label needed.
• A human can just as easily add the label manually — covering both a false negative from the
  AI, and PRs from external contributors, where the AI never runs at all (the org-membership
  security gate blocks it).
• Net effect: no "stale label" preflight step needed, no risk of the AI clobbering a human
  decision on the next push, one label to reason about.

How it works end to end

1. PR time

Every PR triggers ai_claude-sdk-breaking-change.yml:

• security-check — gates on dotCMS org membership (same mechanism as rollback-safety).
• claude-sdk-breaking-change-check — reads docs/core/SDK_BREAKING_CHANGE_CATEGORIES.md, diffs
  the PR, and either:
  • posts a comment explaining which category matched + adds SDK Breaking Change, or
  • does nothing (no label, no comment) if it judges the change non-breaking.

A human reviewer can add or remove the label manually at any time regardless of the AI's verdict.

2. Release time — the checkbox is forgotten

Say a PR merged with the SDK Breaking Change label (correctly, from the AI or a human), two
more unrelated PRs merge after it, and then someone cuts a release without checking
bump_min_sdk_version. The very first job, verify-branch, runs a new step
(Validate bump_min_sdk_version against merged PR labels) that:

• resolves the previous standard release tag,

• pulls every PR merged since that tag (via squash-merge commit messages, same convention the
  existing release-qa-status tool relies on),

• checks each one's labels,

• and if any carries SDK Breaking Change while bump_min_sdk_version is false, fails the
  release immediately, before release-prepare even creates a branch or tag:

  ::error::This release (v26.10.01-1) includes PR(s) labeled 'SDK Breaking Change' (#36800) since v26.7.14-1, but 'bump_min_sdk_version' was left false. Re-run with bump_min_sdk_version=true, or remove the label from those PRs first if none of them actually break SDK compatibility.

The operator sees the error, realizes what happened, and re-runs with the checkbox checked.

If the checkbox is checked but no labeled PR is found in range, the release still proceeds — it
just prints a non-fatal warning, since a human explicitly opted in and may know something the
labels don't capture:

::warning::bump_min_sdk_version=true but no merged PR since v26.7.14-1 carries an SDK-breaking label. Proceeding, since a human explicitly opted in — but double-check this is intentional.

LTS releases (_lts_v##) skip this validation entirely — @dotcms/* SDKs track the @latest npm
cadence, not LTS patch cadence.

3. Release time — the release fails partway through

Say the checkbox was checked correctly, but the release fails during build or deployment
for unrelated reasons. The new bump-min-sdk-version job is gated with a strict success() on
needs: [release-prepare, build, deployment] — not the always() && !failure() && !cancelled()
idiom used by sibling jobs. If any of those three didn't fully succeed, this job doesn't run at
all:

• MinSdkVersion.VALUE is not touched.
• No PR is opened.
• No Slack message fires (the job never starts).

Nothing needs to be rolled back, because nothing was ever written. Once the operator fixes the
issue and re-runs the same release successfully, the bump job runs then instead.

4. Release time — the release succeeds

Once release-prepare, build, and deployment are all green, bump-min-sdk-version runs:

• Checks out fresh main.

• Idempotency check update with latest SVN #1: if MinSdkVersion.VALUE already equals this release's version
  (already-bumped, or a retry after a previous bump PR already merged), it no-ops — no duplicate
  commit, no duplicate PR.

• Otherwise, creates branch sdk/bump-min-sdk-version-<version> off main, edits the constant,
  and verifies the edit actually took effect (guards against the VALUE = "..." literal
  silently failing to match if the file is ever reformatted — in which case it fails loudly
  instead of quietly opening an empty PR).

• Commits, force-pushes the branch.

• Idempotency check Test Branch and Commit #2: reuses an already-open PR for the same branch/version instead of
  opening a duplicate on a retried run.

• Opens the PR (title: chore(sdk): bump MinSdkVersion.VALUE to <version>, body explains why),
  and posts to Slack (log-sdk-libs channel):

  :large_orange_circle: Attention dotters: dotCMS 26.10.01-1 was released with an
  SDK-breaking change.

  A PR bumping MinSdkVersion.VALUE to 26.10.01-1 is open on main.
  Please review and merge the post-release PR ASAP: [View PR]
  [View workflow run]

  If the job itself fails partway (e.g. gh pr create errors), a separate failure message goes
  to the same channel instead. The PR does not auto-merge — a human always reviews and merges
  it manually, same as the retired SDK-VERSION-bump precedent.

Test scenarios walked through during design (not yet live-fire tested — see Known limitations)

#	Scenario	Expected outcome	Confirmed by
1	AI detects a breaking change; human agrees and leaves the label	Label stays; release-time gate later catches it if the checkbox is forgotten	Design walkthrough + exact error message traced above
2	AI flags a PR as breaking; human disagrees	Human removes SDK Breaking Change manually; no separate label needed, no re-add risk since the AI never removes/re-adds on its own	Confirmed the AI check only ever adds, per the workflow's own prompt instructions
3	AI misses a real breaking change (false negative), or PR is from an external contributor (AI never runs — blocked by the org-membership gate)	A human adds SDK Breaking Change manually; the release-time gate treats it identically to an AI-applied label	Confirmed via the gate's label check (grep -qxF 'SDK Breaking Change') — no distinction by origin
4	Dev forgets bump_min_sdk_version on a release that includes a labeled PR	Release fails immediately in verify-branch, before any release branch/tag is created	Exact ::error:: message traced above
5	Dev checks bump_min_sdk_version but release fails in build/deployment	bump-min-sdk-version job doesn't run at all — nothing written, nothing to roll back	Confirmed via the job's strict success() gate semantics (cross-checked against this repo's own promote-latest job, which relies on the same implicit behavior)
6	Release succeeds with the checkbox checked	PR opens against main, Slack notification fires to log-sdk-libs	Exact PR title/body and Slack message traced above
7	Same release re-run after a transient failure, or bump PR already merged	No duplicate PR, no duplicate commit (idempotency checks #1 and #2)	Traced through the exact grep/gh pr list dedupe logic
8	VALUE = "..." literal gets reformatted some day	Job fails loudly with a clear error instead of silently opening an empty, misleading PR	Locally simulated a reformatted file against the sed + verify logic — confirmed the mismatch is caught
9	Interaction with the existing next npm dist-tag publish job (cicd_3-trunk.yml)	No interference — MinSdkVersion.java falls under the backend change-detection filter, not sdk_libs, so merging the bump PR never triggers publish-sdk-next	Verified directly against .github/filters.yaml

Known limitations / accepted risk (not fixed here, flagged for awareness)

• Two releases in flight at once, both flagged as SDK-breaking, would open two separate bump
  PRs (different branch names, keyed by version) — no collision, but a human merging both should
  merge the later version last.
• A stale, unmerged bump PR from a previous release isn't caught by this run's own dedupe
  (different branch name). The validation step does emit a non-fatal ::warning:: if it finds an
  already-open sdk/bump-min-sdk-version-* PR against main, nudging the operator to merge it
  first.
• Squash-merge dependency: both this mechanism's PR-label lookup and the existing
  release-qa-status tool assume squash-merge commit messages (... (#12345)) to map commits back
  to PR numbers. If the repo's merge policy ever changes, both silently stop finding PR numbers —
  fails safe (never blocks a release), but a real breaking PR could then slip through undetected.
  Pre-existing repo-wide assumption, not new to this PR.
• This has not yet been live-fire tested against a real GitHub Actions run in this repo (only
  reasoned through carefully and unit-tested locally where possible — e.g. the sed/grep
  verification logic). A parallel attempt to validate this end-to-end in the disposable
  core-workflow-test fork hit an org-level branch-protection wall (a required status check that
  neither --admin merge nor a direct push could bypass with the available token permissions), so
  the AI-labeling behavior, the release-time gate, and the bump job's real GitHub Actions execution
  should be watched closely on this repo's first real usage.

Files changed

• .github/workflows/cicd_6-release.yml — new bump_min_sdk_version input, new validation step
  in verify-branch, new bump-min-sdk-version job.
• .github/workflows/ai_claude-sdk-breaking-change.yml (new).
• docs/core/SDK_BREAKING_CHANGE_CATEGORIES.md (new).
• dotCMS/src/main/java/com/dotcms/rest/config/MinSdkVersion.java — Javadoc updated to describe
  the automated procedure.

One-time setup already done

The SDK Breaking Change label has been created on this repo (color #b60205).

This PR fixes: #36698

[claude]

Claude finished @KevinDavilaDotCMS's task in 2m 36s —— View job

---

Claude PR Review

• Gather context (diff, prior review findings)
• Review new logic ((#N) subject fix, monotonicity guard)
• Recheck prior findings
• Post review

I reviewed the current state of the diff, focusing on the two findings @dcolina raised and confirming the earlier review rounds' fixes are still in place.

Resolved

• ✅ cicd_6-release.yml:155-157 — False-block from body (#N) matches is fixed. The jq filter now uses .commits[].commit.message | split("\n")[0], so only the commit subject is scanned for (#N). Verified the \(#[0-9]+\)$ anchor still extracts one PR number per squash commit.

• ✅ cicd_6-release.yml:373-381 — Non-monotonic bump is fixed. The new guard computes HIGHEST=$(printf ... | sort -V | tail -1) and exit 1s when HIGHEST != RELEASE_VERSION, refusing to lower the floor on a backfill/re-run. I ran sort -V against the real version shape and it orders correctly in every case that matters here:

  • max(26.7.14-1, 26.10.01-1) → 26.10.01-1 (month rolls forward)
  • max(26.7.14-1, 26.7.14-2) → 26.7.14-2 (counter)
  • max(26.10.20-1, 26.7.14-1) → 26.10.20-1 (backfill correctly refused)
  • max(26.7.14-2, 26.7.14-10) → 26.7.14-10 (numeric, not lexical)
  • max(0.0.0, 26.7.14-1) → 26.7.14-1 (baseline bump proceeds)

  The guard exit 1 lives inside the continue-on-error: true step, so a refused backward bump surfaces via the failure Slack notification rather than reddening an already-shipped release — consistent with the design.

• ✅ cicd_6-release.yml:341-455 — prior review's finding 4 (bump-job failure reddening the whole release run) remains fixed: continue-on-error: true on the bump step plus the failure notification gated on steps.bump.outcome == 'failure' (outcome, not the masked conclusion). Correct.

New Issues

No new issues. The two reported findings are correctly addressed and the surrounding logic (idempotency check #1/#2, post-sed verification, strict success() gate on needs: [release-prepare, build, deployment], LTS skip) is internally consistent.

One low-severity observation, not blocking and fine to leave as-is:

• 🟡 Minor: cicd_6-release.yml:366 — if the VALUE = "..." literal is ever reformatted (e.g. VALUE="x" with no spaces), CURRENT comes back empty, so the equality/idempotency and monotonicity checks are effectively bypassed. It still fails safe — the post-sed NEW_VALUE verification at line 393 catches the mismatch and exit 1s loudly — so no bad PR is opened. Just noting the earlier guards silently no-op in that scenario; the tail check is what actually saves you.

This PR is in good shape. All findings from this and prior rounds are resolved; the remaining known limitations are already documented in the PR description as accepted risk.
• 36698-automate-min_sdk_version-bump...

[KevinDavilaDotCMS]

Went through all 4 findings from the Claude Code review against the actual code — verified two empirically, one against direct precedent in this repo, and applied a real fix for the last one.

Applied

Finding 4 — bump-job failure would redden the whole release run — real, fixed

Confirmed: cicd_comp_finalize-phase.yml's prepare-report-data job scans every job in the run via the GitHub API (not just its own needs:), excluding only names matching ^(Finalize|Final Status|.*[Ff]inalize.*). "Bump MinSdkVersion.java" doesn't match that exclusion, so a transient git/gh error in that step — happening after the release has already fully shipped (build + deployment green) — would have marked the entire release run red over a best-effort housekeeping PR. This is the same class of issue already fixed for the SDK next-tag publish job in #36722.

Fix: added continue-on-error: true to the "Bump MinSdkVersion.VALUE and open PR" step, and changed the failure Slack notification's condition from if: failure() to if: steps.bump.outcome == 'failure' — continue-on-error masks the step's conclusion to success (which failure() checks), but outcome still reflects the real pre-mask result, so the failure notification still fires correctly.

Reviewed, findings don't hold

Finding 1 (partially) — 250-commit cap on the compare endpoint

Tested this directly rather than take it on faith: ran the exact command our validation step uses (gh api repos/dotCMS/core/compare/<sha>...main --paginate) against a real range of 824 commits in this repo. It returned all 824 — --paginate does correctly page past the default 250-commit page size on this endpoint. The claim that "--paginate does not lift it" doesn't hold up empirically here.

The other half of that finding — that the PR-number extraction only matches squash-merge commit subjects ((#N)) and would miss merge-commit-merged PRs — is accurate, but it's an existing, already-documented limitation shared with the release-qa-status tool this repo already relies on for release QA reporting. Not new to this PR, and already called out as an accepted risk in the PR description.

Finding 2 — shallow checkout could break git diff base...head in the AI prompt

Checked this against direct precedent: ai_claude-rollback-safety.yml uses the byte-for-byte identical git diff ${{ base.sha }}...${{ head.sha }} construct, via the same claude-orchestrator.yml@v3 reusable workflow. We've seen that exact mechanism successfully execute this diff and produce specific, code-referencing review comments on real PRs in this repo multiple times already. If checkout depth were insufficient, that already-shipped mechanism would already be failing. No changes made.

Finding 3 — label doesn't exist

Was accurate when the review ran, but already resolved — the SDK Breaking Change label was created on this repo before this PR was opened. Confirmed still present.

Notes, agreed as-is

• The "unreachable nothing-to-commit branch" observation is technically correct (the preceding idempotency guard + the post-sed verification together guarantee a diff exists by that point) but harmless dead code — not changing it.
• Thanks for the callout on the doc quality and the H-1 self-referential note — that one was intentional.

[dcolina]

@KevinDavilaDotCMS — two findings specific to the new logic (not caught in the prior review rounds). #1 can take down a legitimate release, so I'd fix it before this ships.

1. verify-branch can falsely block a legitimate release from a (#N) in a commit body — cicd_6-release.yml:148-163

PR_NUMBERS=$(gh api ".../compare/${PREV_TAG}...main" --paginate \
  --jq '.commits[].commit.message' \
  | grep -oE '\(#[0-9]+\)$' | grep -oE '[0-9]+' | sort -un || true)

--jq '.commits[].commit.message' emits the full message (subject + body), and grep runs per line. Squash-merge bodies routinely carry lines ending in (#N) — rolled-up bullets, revert/cherry-pick footers. Every one of those Ns gets treated as a PR in this release's range.

Failure case: a commit body has a line ending in (#450); #450 is an old, unrelated PR that still carries the SDK Breaking Change label. BREAKING_PRS becomes non-empty → with bump_min_sdk_version=false → exit 1, release blocked. Worse, the error message then tells the operator to re-run with bump_min_sdk_version=true, triggering an unwarranted floor bump. The earlier review only flagged the false-pass direction (merge commits missing (#N)); this is the false-block direction.

Fix — match only the subject line:

--jq '.commits[].commit.message | split("\n")[0]'

2. The bump isn't monotonic — a re-run/backfill of an older release lowers the floor — cicd_6-release.yml:~360-369

The job only guards CURRENT == RELEASE_VERSION; it never checks RELEASE_VERSION >= CURRENT. If main is already at VALUE = "25.10.20-1" and someone backfills/re-runs an older 25.10.10-5 with bump=true, the sed rewrites VALUE to the older version, the NEW_VALUE check passes, and a PR is opened that loosens the compatibility contract — easy to merge without noticing.

MinSdkVersion.VALUE is a floor; it should only ever move forward. Suggest comparing with sort -V and no-op'ing (or failing loud) when RELEASE_VERSION < CURRENT.

[dcolina]

I'll approve it but it would be fine to fix the potential issues I've reported.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[KevinDavilaDotCMS]

@dcolina Both real, both fixed — verified with concrete evidence from this repo's actual history before applying anything.

1. (#N) matches from the commit body, not just the subject

Confirmed this is not just theoretically possible — it's already happening in this repo. Scanned the last 3000 commits on main: 20 of them have a body line (not the subject) ending in (#N), e.g.:

commit c53feafbe | subject: fix(content-drive): field-based search follow-up fixes...
  body line: feature (issue #36384), on top of the merged frontend feature (#36452)

Your fix is exactly right. Applied:

- --jq '.commits[].commit.message' \
+ --jq '.commits[].commit.message | split("\n")[0]' \

Re-verified against the real compare range used in testing (825 commits) — this now extracts exactly one PR number per commit, from the subject only, with zero stray matches.

2. Non-monotonic bump (backfill could lower the floor)

Also confirmed — the code only guarded the exact-match no-op case, never checked direction. Added a monotonicity guard right after the existing idempotency check:

HIGHEST=$(printf '%s\n%s\n' "${CURRENT}" "${RELEASE_VERSION}" | sort -V | tail -1)
if [ "${HIGHEST}" != "${RELEASE_VERSION}" ]; then
  echo "::error::Refusing to bump MinSdkVersion.VALUE backward: main is already at '${CURRENT}', which is newer than this release's version '${RELEASE_VERSION}'. ..."
  exit 1
fi

Verified sort -V handles our date-lockstep version shape correctly (26.7.14-1 vs 26.10.20-1 vs 26.7.14-2, etc.) before relying on it. Since this lives inside the step that already has continue-on-error: true (from the earlier review round's fix), tripping this guard surfaces via the failure Slack notification without reddening the whole release run — the release already shipped by the time this step runs, so a refused bump is a "needs human attention" signal, not a release failure.

Both fixes pushed. Thanks for catching these — #2 especially, since a silently-loosened floor is exactly the kind of failure mode this whole mechanism exists to prevent.

[KevinDavilaDotCMS]

Following up on the two remaining findings from the second Claude Code review round (PR review comment above dcolina's) — reviewed both, no code changes for either.

PREV_TAG resolution assumes chronological order (cicd_6-release.yml — the sort -V | tail -1 over standard release tags). Confirmed the theoretical gap: if a release were ever cut out of chronological order (an older-dated backfill release after a higher-versioned one already shipped), the compare range would be wrong. No evidence this repo's release process ever cuts backfills out of order — every release we've observed moves strictly forward in time. Accepting as a known, low-probability limitation; not changing the resolution logic (which would otherwise need to switch to ordering by actual release creation date, like release-qa-status's findPreviousTag does, rather than by version-string sort).

git push --force runs before checking for an already-open PR (the bump job). Confirmed: a retried run would force-reset the bot's branch from origin/main before checking if a PR already exists, which would clobber any commits a human manually pushed onto that branch in the meantime. This is intentionally the same convention already established by the retired cicd_manual-release-sdks.yml's equivalent mechanism (its own comment: "these are bot-managed branches so force push is safe") — not a new risk introduced here, and consistent with how this kind of bot-owned branch is expected to be handled: review/merge the PR, don't push directly to the bot's branch. Leaving as-is.