SDK packaging: fix malformed version strings and floating/orphaned dist-tags (#36891)

[KevinDavilaDotCMS]

Summary

Implements the spec in #37452 (approved, spec-only PR 1) for #36891. Fixes four related defects in the SDK npm release pipeline and package manifests, plus a root-cause automation so future release branches (LTS or not) can't regress into the same bug:

• Defect A — the release pipeline wrote zero-padded version strings (26.08.03-01) that mismatch npm's own normalized registry metadata (26.8.3-1), per ADR-0019. Normalized in deploy-javascript-sdk/action.yml, extended to also cover devDependencies.
• Defect B1/B1b — react/angular/vue/analytics declared sibling @dotcms/* packages as dependencies instead of peerDependencies (the actual mechanism behind yarn/pnpm installing duplicate, mismatched copies), all pinned to "latest". Moved to peerDependencies with a "0.0.0" sentinel (rewritten to the real version at publish time); READMEs corrected to document the manual-install requirement for yarn classic (1.x) / npm < 7.
• Defect B2 — two of main's six example apps pointed at an internal "next" pre-release tag instead of "latest". Fixed; all six now correctly float on "latest" (Evergreen-aligned), with a README note for non-Evergreen customers.
• Defect B3 (root cause) — both active LTS branches' examples/nextjs floated on "latest", resolving far ahead of the LTS server (the live customer ticket, Freshdesk #38677). Backported as two separate PRs (fix(sdk): pin examples/nextjs to 1.2.0 instead of floating latest #37475, fix(sdk): pin examples/nextjs to 1.2.0 instead of floating latest #37476, pinned to 1.2.0, verified via static GraphQL schema analysis). Root cause fixed here: cicd_comp_release-prepare-phase.yml now auto-pins every example app's @dotcms/* deps to the exact release version at branch-cut time, for every future release branch — main is never touched.
• CI guardrail: new .github/scripts/validate-sdk-package-shapes package (tested, 10/10) wired into cicd_1-pr.yml and cicd_5-lts.yml to fail the build on any regression of the shapes above.

Full defect analysis, root-cause hypothesis, and acceptance criteria in the approved spec: specs/37399-sdk-packaging-version-fix/spec.md (#37452).

Test plan

• sdk-client Jest suite (sdk-compatibility.spec.ts) — 12/12 passing, includes a regression-lock test for leading-zero version equality (AC-008)
• validate-sdk-package-shapes Jest suite — 10/10 passing
• Validator CLI run against all 7 SDK lib manifests + 6 main example manifests — 13/13 Green
• Manual local reproduction of the release-pipeline normalization against a scratch copy of real manifests — this claim was wrong. The step aborted on the first package ($dep_name unbound under set -u), so this check never exercised the code it claimed to verify. Caught in review; see the re-verification below.
• Manual scratch-install across npm/yarn(classic 1.22.22)/pnpm confirming no duplicate @dotcms/client copy under node_modules/@dotcms/react/node_modules/
• Manual clean-install verification on all six main examples confirming npm ls @dotcms/client resolves a single deduped copy from latest
• Local reproduction of the release-branch-cut auto-pin step against a scratch copy of all six example manifests — confirmed correct rewrite, non-@dotcms/* deps untouched
• /speckit-converge run against final code — ✅ Converged, zero gaps
• LTS backport PRs fix(sdk): pin examples/nextjs to 1.2.0 instead of floating latest #37475 and fix(sdk): pin examples/nextjs to 1.2.0 instead of floating latest #37476 — separate PRs, not part of this one, tracked independently

Re-verification after the review fixes

• update-versions step body extracted from action.yml verbatim and run against scratch copies of the real manifests — 11/11 packages, exit 0 on 26.08.03-01, 26.9.3-1-next.2632 and 2026.06.24-01 (previously died on the first package)
• Prerelease suffix preserved end to end: 26.9.3-1-next.2632 survives into the resulting manifests
• Unscoped-sibling regression test: injected "dotcms": "latest" into react → rewritten to 26.8.3-1
• Normalization verified byte-identical under mawk (the ubuntu-24.04 default), gawk and gawk --posix across 9 release-shaped inputs, inside ubuntu:24.04
• create-branch step run verbatim against a real git repo (bare origin, post-receive push counter): release tag's target_commitish carries the pin, exactly 1 push to release-*, no-op re-run does not abort, examples diff is 26 lines instead of 121. The same harness run against the pre-fix code fails all four — counterfactual confirmed
• validate-sdk-package-shapes job run verbatim in a clean node:22.22.3 container (the .nvmrc version), no cache, npm ci --ignore-scripts → build → 21/21 tests → 11 libs + 6 examples, exit 0
• Guardrail negative/positive probes: 10/10 correct (B1b ×2, floating peerDep, latest on LTS, ^ range on LTS, next on main all red; 0.0.0 sentinel, latest on master, exact pin, exact prerelease pin all green)
• actionlint clean on all three substantively changed workflows (SC2044 resolved); cicd_comp_initialize-phase.yml had 44 pre-existing warnings and still has 44
• Filter wiring (sdk_package_shapes → dorny/paths-filter → initialize outputs → job if:) — not reproducible locally; verified by this push's CI run

🤖 Generated with Claude Code

This PR fixes: #36891

This PR fixes: #36891

[dcolina]

CI/CD review — request changes

Spec traceability here is excellent and most packaging ACs are met and verified. But the change to deploy-javascript-sdk/action.yml is deterministically broken: as-is, this breaks 100% of future SDK npm releases. Reproduced locally.

Note the test plan has 10 checked boxes and none of them exercised the highest-blast-radius file — the spec's own Regression Risk section flagged exactly this.

---

Must fix

1. $dep_name is now unbound under set -u → every SDK release aborts

action.yml:100 still references $dep_name, but the PR deleted its assignment. With set -euo pipefail (line 68) that is a hard failure.

Simulated the exact step against this branch's real manifests:

Normalized release version: 26.8.3-1
Found SDK packages: uve types experiments vue angular cli ai create-app client react analytics
  OK uve -> 26.8.3-1
bash: line 22: dep_name: unbound variable        <-- dies on the FIRST package

deploy-javascript-sdk is the only publish path for the SDK (cicd_release-sdk.yml + cicd_3-trunk.yml). This fails on every release, always.

It went unnoticed because cicd_release-sdk.yml:162-164 skips the whole action on dry-run:

if: >-
  (github.event_name == 'release' || github.event.inputs.dry-run != 'true')

So the dry-run offered as verification executes none of the changed code.

2. Normalization destroys the -next.<run> suffix → breaks the next dist-tag publish

cicd_3-trunk.yml:177 builds NEXT_VERSION="${LATEST_VERSION}-next.${{ github.run_number }}". The new awk splits on [.-] and rebuilds from only 4 fields, dropping the rest:

Input	Output
26.08.03-01	26.8.3-1 OK
26.9.3-1-next.2632	26.9.3-1 — suffix gone
25.07.10-1-next.99	25.7.10-1 — suffix gone

Every SDK-touching merge to main would then try to publish the stable release version number. The npm view idempotency guard finds it already published, prints already published — skipping, sets published=true, and Slack announces success — so next silently stops publishing forever. In the window before that version exists on the registry it's worse: trunk code gets published under the stable release number, and the real release later hits a 403.

The spec says "No change to the next dist-tag publishing mechanism" — this changes its behavior through the shared action.

3. Reintroduces a bug already fixed and documented in this same file

-              dep_name=$(jq -r '.name' "$dep/package.json" 2>/dev/null || echo "@dotcms/$dep")
-              for field in dependencies peerDependencies; do
-                if jq -e ".${field}[\"$dep_name\"]" "$pkg" >/dev/null 2>&1; then
+              for field in dependencies peerDependencies devDependencies; do
+                if jq -e ".${field}[\"@dotcms/$dep\"]" "$pkg" >/dev/null 2>&1; then

Two steps below, in this same file:

"The package's OWN name, never @dotcms/<directory>. The scope used to be hardcoded here, which silently assumed every SDK is scoped. It held until dotcms — the unscoped CLI — where the guard below could never match."

Verified on this branch: core-web/libs/sdk/cli publishes as the unscoped dotcms (the other 10 match @dotcms/<dir>). No lib depends on it today, so it doesn't explode yet — but when one does, the rewrite skips it silently and ships a literal "latest", which is Defect B1. The spec asked to extend the loop to devDependencies, not to revert this.

4. Spec says "seven" SDK libs — there are eleven

ai, cli, create-app, types are missing from contracts/package-json-shape.md and from AC-003's count. The CI validator does walk all 11 (verified, 11/11 green), so nothing breaks — but the signed contract is incomplete and sdk_packages iterates all 11.

---

Concerns

5. pin-examples leaves the release tag pointing at a pre-pin commit. create-branch computes release_commit=$(git log -1 --pretty=%H) before the new step, and Create GitHub Release uses it as target_commitish. The pin only exists on the branch tip.

6. pin-examples is not idempotent. CHANGED=true is set when a @dotcms/* entry exists, not when its value changed. If the pin is a no-op, git add examples stages nothing, git commit exits 1, set -e kills the step, and Create GitHub Release (if: success()) never runs — branch pushed, no release. The variable measures FOUND, not CHANGED.

7. The second git push cancels the LTS run the first one started. cicd_5-lts.yml triggers on push: release-* with cancel-in-progress: true on ${{ github.workflow }}-${{ github.ref }}.

5, 6 and 7 all disappear by folding the pin into the create-branch commit (diff C).

8. Latent false positive: master blocks PRs. cicd_1-pr.yml accepts branches: [main, master]; the validator compares branch !== 'main':

$ node dist/index.js examples/nextjs/package.json --branch master
  - dependencies["@dotcms/client"] is "latest" on branch "master" — only "main" may float
  exit=1

The step comment says "so 'main' is always the correct branch context here" right after naming main/master — it contradicts itself.

9. False negative: version ranges pass on release branches. AC-005/AC-010 require an exact pin; the validator only checks latest/next/*:

$ echo '{"dependencies":{"@dotcms/client":"^26.9.3-1","@dotcms/uve":"~1.2.0","@dotcms/react":">=1.0.0"}}'
$ node dist/index.js ... --branch release-25.07.10_lts_v12
OK — 1 file(s) validated, no violations.        <-- should fail

Not hypothetical: action.yml:112-119 writes ^$RELEASE_VERSION into example manifests. A ^ on an LTS branch reintroduces the drift that caused Freshdesk #38677.

10. The validator's tests never run in CI. The step runs npm ci && npm run build, never npm test. Also, the job's if: only checks sdk_libs/examples — so changing the validator itself does not trigger the job. You can break the guardrail and CI stays green.

11. Missing hardening on both new jobs:

• No permissions: — not at job or workflow level (neither cicd_1-pr.yml nor cicd_5-lts.yml has a block), so it inherits the repo default. This matters most in cicd_1-pr.yml: npm ci runs against a PR-controlled package.json and executes lifecycle scripts. That workflow's own header warns "PR checks are run on code that is not yet merged". Needs permissions: contents: read + npm ci --ignore-scripts.
• No timeout-minutes — 360min default for a ~1min job.
• No npm cache — one line in setup-node.

actionlint also reports SC2044 (for over find) on all three new scripts.

---

What's solid

• Gating actually works. cicd_comp_finalize-phase.yml aggregates needs on result == "failure"|"cancelled" and exits 1; skipped is not treated as failure, so the change-detection if: doesn't break unrelated PRs. Correct by design.
• Branch coverage is right. cicd_5-lts.yml fires on release-* (not just LTS), so AC-007 genuinely covers non-main. The per-event TARGET_BRANCH (base.ref vs ref_name) is well reasoned and documented.
• All actions SHA-pinned with version comments.
• filters.examples correctly wired end-to-end (filters.yaml → info_filters → output JSON → job if:). Traced it fully.
• Single normalization point, and the npm view idempotency check consumes the normalized value. The design is right; the implementation is what fails.
• Validator is well written — typed, single-responsibility, comments tied to ACs. Ran it against all 17 real manifests (green) and it correctly catches the B1b regression.
• bump-sdk-versions.js cleanly retired — no references outside the spec.

---

AC compliance

AC	Status	Evidence
AC-001 normalized version	FAIL	code is unreachable (#1); breaks prereleases (#2)
AC-002 normalized pins across 3 fields	FAIL	same, plus scope regression (#3)
AC-003 "0.0.0" in peerDeps	PASS	verified across the 7 relevant libs
AC-003b client/uve moved to peerDeps	PASS	react, angular, vue, analytics — verified
AC-004 six main examples on latest	PASS	6/6 latest, zero next; 6 READMEs carry the note
AC-005 LTS pins	N/A	separate PRs #37475/#37476, declared
AC-006 pinned install across npm/yarn/pnpm	N/A	manual, not CI-verifiable
AC-007 CI guardrail	PARTIAL	works, but #8, #9, #10
AC-008 compareVersions regression lock	PASS	expect(compareVersions('26.08.03-01','26.8.3-1')).toBe(0)
AC-009 corrected READMEs	PASS	all three, naming yarn 1.x / npm <7 explicitly
AC-010 auto-pin at branch cut	PARTIAL	implemented, but #5, #6, #7

---

Suggested diffs

A) action.yml — restore .name resolution and fix the echo (closes #1, #3):

             for dep in "${sdk_packages[@]}"; do
-              for field in dependencies peerDependencies devDependencies; do
-                if jq -e ".${field}[\"@dotcms/$dep\"]" "$pkg" >/dev/null 2>&1; then
-                  jq --arg field "$field" --arg dep "@dotcms/$dep" --arg v "$RELEASE_VERSION" \
+              # Same reason as the publish step below: resolve the sibling's real name
+              # rather than assuming the @dotcms/ scope. libs/sdk/cli publishes as the
+              # UNSCOPED `dotcms`, so a hardcoded scope silently skips it.
+              dep_name=$(jq -r '.name' "$dep/package.json" 2>/dev/null || echo "@dotcms/$dep")
+              for field in dependencies peerDependencies devDependencies; do
+                if jq -e ".${field}[\"$dep_name\"]" "$pkg" >/dev/null 2>&1; then
+                  jq --arg field "$field" --arg dep "$dep_name" --arg v "$RELEASE_VERSION" \
                     '.[$field][$dep] = $v' "$pkg" > tmp.$$.json && mv tmp.$$.json "$pkg"
                   echo "    ↳ $field $dep_name -> $RELEASE_VERSION"
                 fi

B) Prerelease-preserving normalization (closes #2) — needed in both places (action.yml and cicd_comp_release-prepare-phase.yml):

-        RELEASE_VERSION=$(echo "$RELEASE_VERSION" | awk -F'[.-]' '{
-          for (i = 1; i <= NF; i++) { sub(/^0+/, "", $i); if ($i == "") $i = "0" }
-          out = $1 "." $2 "." $3
-          if (NF >= 4) out = out "-" $4
-          print out
-        }')
+        # Strip leading zeros from every purely-numeric segment while PRESERVING the
+        # original separators and all trailing segments. Rebuilding from only $1..$4
+        # silently truncates cicd_3-trunk.yml's `-next.<run_number>` suffix, which makes
+        # every `next` publish collide with the stable release version.
+        RELEASE_VERSION=$(echo "$RELEASE_VERSION" | awk '{
+          s = $0; out = ""
+          while (match(s, /[.-]/)) {
+            seg = substr(s, 1, RSTART - 1); sep = substr(s, RSTART, 1)
+            if (seg ~ /^[0-9]+$/) { sub(/^0+/, "", seg); if (seg == "") seg = "0" }
+            out = out seg sep
+            s = substr(s, RSTART + 1)
+          }
+          if (s ~ /^[0-9]+$/) { sub(/^0+/, "", s); if (s == "") s = "0" }
+          print out s
+        }')

Verified equivalent on every release-shaped input, and correct on prereleases:

26.08.03-01            -> 26.8.3-1              (same as PR)
26.10.20-01            -> 26.10.20-1            (same)
2026.06.24-01          -> 2026.6.24-1           (same; ADR-0019's literal example)
26.00.03-01            -> 26.0.3-1              (same)
26.9.3-1-next.2632     -> 26.9.3-1-next.2632    (PR gave 26.9.3-1)
26.08.03-01-next.2632  -> 26.8.3-1-next.2632    (PR gave 26.8.3-1)

POSIX awk, no gawk dependency.

C) Fold the pin into the branch-cut commit (closes #5, #6, #7) — move the loop into create-branch right before git commit -a, and drop the separate pin-examples step:

           git status
+          # Pin every example app's @dotcms/* deps to this release's normalized SDK
+          # version. Folded into THIS commit on purpose: a separate commit+push would
+          # leave the release tag (target_commitish, computed below) pointing at a
+          # pre-pin commit, and would re-trigger cicd_5-lts.yml, cancelling the run the
+          # first push just started.
+          for pkg_json in $(find examples -maxdepth 2 -name package.json 2>/dev/null); do
+            for dep in $(jq -r '.dependencies // {} | keys[] | select(startswith("@dotcms/"))' "$pkg_json"); do
+              jq --arg dep "$dep" --arg v "$NORMALIZED_VERSION" \
+                '.dependencies[$dep] = $v' "$pkg_json" > tmp.$$.json && mv tmp.$$.json "$pkg_json"
+            done
+          done
           git commit -a -m "🏁 Publishing release version [${release_version}]"
           git push origin ${release_branch}

git commit -a already picks the examples up, so the "nothing to commit" failure disappears. If you'd rather keep the step separate, then at minimum:

-          if [ "$CHANGED" = "true" ]; then
-            git add examples
+          git add examples
+          if ! git diff --cached --quiet -- examples; then
             git commit -m "🏁 Pin example app SDK dependencies to ${NORMALIZED_VERSION}"

…and move release_commit=$(git log -1 --pretty=%H) to after the pin.

D) Harden both new jobs (closes #10, #11) — in cicd_1-pr.yml and cicd_5-lts.yml:

   validate-sdk-package-shapes:
     name: Validate SDK package.json shapes
     needs: [ initialize ]
     if: >-
       always() && !cancelled() &&
       (fromJSON(needs.initialize.outputs.filters).sdk_libs == 'true' ||
-       fromJSON(needs.initialize.outputs.filters).examples == 'true')
+       fromJSON(needs.initialize.outputs.filters).examples == 'true' ||
+       fromJSON(needs.initialize.outputs.filters).cicd == 'true')
     runs-on: ubuntu-${{ vars.UBUNTU_RUNNER_VERSION || '24.04' }}
+    timeout-minutes: 10
+    permissions:
+      contents: read
     steps:
       - name: 'Checkout'
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

       - name: 'Setup Node'
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: 'core-web/.nvmrc'
+          cache: npm
+          cache-dependency-path: .github/scripts/validate-sdk-package-shapes/package-lock.json

-      - name: 'Build validator'
+      - name: 'Build and test validator'
         working-directory: .github/scripts/validate-sdk-package-shapes
         run: |
-          npm ci
+          # --ignore-scripts: on cicd_1-pr.yml this manifest is PR-controlled, and
+          # lifecycle scripts would execute arbitrary code from an untrusted branch.
+          npm ci --ignore-scripts
           npm run build
+          # The guardrail's own tests — without this, breaking the validator is a green build.
+          npm test
         shell: bash

E) Validator — accept master, reject ranges (closes #8, #9):

 const FLOATING_SPECIFIERS = new Set(['latest', 'next', '*']);
+/** cicd_1-pr.yml triggers on PRs to `main` OR `master` — both are the floating-allowed trunk. */
+const FLOATING_ALLOWED_BRANCHES = new Set(['main', 'master']);
+/** AC-005/AC-010 require an EXACT pin on release branches — `^`/`~`/ranges drift forward too. */
+const RANGE_SPECIFIER = /^[\^~><=]|\s\|\|\s|\s-\s|x$/;
@@
         if (version === 'next' || version === '*') {
             violations.push(...);
-        } else if (version === 'latest' && branch !== 'main') {
+        } else if (
+            !FLOATING_ALLOWED_BRANCHES.has(branch) &&
+            (version === 'latest' || RANGE_SPECIFIER.test(version))
+        ) {
             violations.push(
-                `examples: dependencies["${dep}"] is "latest" on branch "${branch}" — only "main" may float; ...`
+                `examples: dependencies["${dep}"] is "${version}" on branch "${branch}" — only main/master may float; this branch must pin an exact version`
             );
         }

action.yml:112-119 should also write $RELEASE_VERSION without the ^, so the pipeline stops producing a shape its own guardrail would reject.

---

How to verify

actionlint .github/workflows/cicd_1-pr.yml .github/workflows/cicd_5-lts.yml \
           .github/workflows/cicd_comp_release-prepare-phase.yml \
           .github/actions/core-cicd/deployment/deploy-javascript-sdk/action.yml
cd .github/scripts/validate-sdk-package-shapes && npm ci --ignore-scripts && npm run build && npm test

Beyond this PR: the normalization point needs to be testable without cutting a release. Extract it into .github/scripts/ with a unit test (26.08.03-01-next.2632 → expected output) and have action.yml call it. As long as the only way to exercise it is a real release, every change there is a blind bet — and this PR is the proof.

[KevinDavilaDotCMS]

@dcolina Thanks — this was a genuinely valuable review. All 11 findings are addressed in dc1ac04. Summary of what I took, what I implemented differently, and where I think two of your points need adjusting.

Blocking — you were right, and the impact was exactly as you described

#1 $dep_name unbound. Confirmed and fixed. Rather than just restoring the assignment inside the loop, I hoisted resolution into an sdk_package_names array built once after sdk_packages, so the two loops (libs and examples) share it instead of running a jq per package per field.

#2 prerelease truncation. Confirmed and fixed with your segment-walking approach. I traced the chain you described: cicd_3-trunk.yml:177 builds NEXT_VERSION and passes it as the version: input to this same action at line 193. Applied in both places, as you noted.

#3 scope regression. Confirmed — libs/sdk/cli publishes as dotcms, and the comment 100 lines below in the same file explains exactly why hardcoding the scope is wrong. Fixed by the same hoist as #1. I also added a direct regression test: injecting "dotcms": "latest" as a sibling dep now gets rewritten instead of silently skipped.

#5 / #6 / #7 — diff C taken as-is. Folded into the branch-cut commit, standalone pin-examples step removed.

Where I implemented it differently

#9 ranges — allow-list, not operator blacklist. Your regex would work, but enumerating ^~><=, ||, -, x$ leaves whatever syntax nobody thought of passing silently. I inverted it: on any non-trunk branch a @dotcms/* pin must match /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/, and anything else fails. Same outcome for your cases, closed by construction for the rest.

#10 — your diff D doesn't fix the second half. It proposes fromJSON(...).cicd == 'true', but there is no cicd key in .github/filters.yaml; the closest is area_cicd, and that covers .github/workflows/** and .github/actions/**, not .github/scripts/**. So editing the validator still wouldn't have triggered the job. I added a dedicated sdk_package_shapes filter pointing at the validator's own source, registered in info_filters. Kept separate from sdk_libs on purpose: that one also gates the trunk npm publish job, and touching the validator must not trigger an SDK release.

Everything else in D taken: npm test, npm ci --ignore-scripts, permissions: contents: read, timeout-minutes, npm cache, plus the SC2044 while read conversion.

Two points that need adjusting

#11 — "neither cicd_1-pr.yml nor cicd_5-lts.yml has a permissions block" is not accurate. cicd_1-pr.yml has three, at lines 56, 77 and 101. What was missing is a block on this job. The finding stands and I fixed it; the supporting argument doesn't.

#9 — "not hypothetical" doesn't hold. You justify the urgency with action.yml:112-119 writing ^$RELEASE_VERSION into example manifests. That action never runs git add/commit/push — those are ephemeral runner-workspace edits for npm publish, and examples aren't published to npm, so the caret never reaches the repo. The pipeline was not emitting a shape its own guardrail would reject. The validator gap is real and worth closing (a hand-written ^ on an LTS example would slip through), but the risk is smaller than stated. I dropped the caret anyway — there's no reason for it.

#4 — documentation only, not a Must fix. Eleven directories, contract lists seven. I checked the other four: ai, cli, create-app and types declare zero @dotcms/* entries in dependencies, peerDependencies or devDependencies. There was no functional gap and the fix missed nothing. Added a note to contracts/package-json-shape.md recording the count, that the four carry no sibling deps, and that cli publishes unscoped.

#6 — real in the code, but unreachable in practice. Building the counterfactual surfaced this: CHANGED does measure found rather than changed, exactly as you say, but the old step could never hit the no-op path. jq without --indent reformats, so the three 4-space manifests always produced a diff and there was always something to commit. It would only have fired if main's examples were already pinned and already in jq's exact output format. Fixed regardless — the fold makes it moot.

A defect neither of us flagged

The pin loop called jq without --indent, and jq reprints the whole document. The release commit would have rewritten all six manifests: 121 insertions / 121 deletions for a four-value change. examples/ mixes 2-space (angular, angular-ssr, astro) and 4-space (nextjs, nextjs-experiments, vuejs), so no fixed --indent works. Now detected per file — 26/26, both styles preserved, non-@dotcms deps untouched. This existed in the original step too.

On your closing point — agreed, and it's the most important one

the normalization point needs to be testable without cutting a release

You're right, and #1 and #2 are the proof. I did not do the extraction in this PR — it's a refactor of the release path beyond answering the review — but I'll open a follow-up for it.

What I did instead was stop testing by hand. Every check now extracts the step body verbatim from the YAML and runs it, so the test can't drift from the code:

• update-versions against scratch copies of the real manifests: 11/11 packages, exit 0 on stable, -next.<run> and the ADR-0019 input
• The normalization verified byte-identical under mawk (the ubuntu-24.04 default), gawk and gawk --posix inside ubuntu:24.04. Worth calling out: everything I'd checked before that ran on BSD awk, so this was an open assumption
• create-branch against a real git repo with a bare origin and a post-receive push counter: tag target_commitish carries the pin, exactly 1 push, no-op re-run doesn't abort, 26-line diff. The same harness run against the pre-fix code fails all four — without that counterfactual the harness would prove nothing
• The CI job verbatim in a clean node:22.22.3 container, no cache: 21/21 tests, 11 libs + 6 examples, exit 0
• 10 guardrail probes, negative and positive, all correct

Test plan

You were right that none of the ten boxes exercised the highest-blast-radius file. The normalization box was worse than useless — it claimed a verification that could not have run, since the step aborted on the first package. I've struck it in the description with a note, and listed the re-verification above it.

The one thing not provable locally is the filter wiring (sdk_package_shapes → dorny/paths-filter → initialize outputs → job if:). This push's CI run covers it.

Ready for another look.

[dcolina]

Go for it