[gpmayorga]

Problem

Since #18, promote accepts a hotfix release (a tag not on main) only when its delta from where it left main reverse-applies to main's tree, i.e. main has every change line for line. That worked for invest-v3 v3.3.5: its two commits landed on main unchanged (centrifuge/apps-invest#363, centrifuge/apps-invest#341) and nobody touched those lines since.

It can never pass for a backport, where main already has the fix in another form. apps-management v2.5.3 is one:

• src/utils/holdings.ts and its test were added separately on both sides: on main by centrifuge/apps-management#1360 (Oct 7), and on top of v2.5.2 by centrifuge/apps-management#1416, with different comment text and an extra function on main.
• 066d1d65 bumps v2.5.2's dependency pins; main has moved past them differently.

All five files conflict even in a 3-way merge, so no merge-back PR can make main match without downgrading it. Ancestry is not an option either, since the app repos are squash-only. v2.5.3 went out through rollback.yml, but nothing told the deployer to do that: the release notification said to promote, and promote's refusal said "Merge the hotfix into main".

Change

Promote stays strict (no override input). Instead the two places a deployer reads now give the right command:

• Promote refusal (log ::error:: and the Slack failure reason): when the merged-back check fails, it says to merge the hotfix into main if it is not there yet, or otherwise to ship it with
  gh workflow run rollback.yml --repo <repo> --ref main -f tag=<tag> -f environment=prod.
• released notification (notify-production-promotion): checks out the tag with full history and runs the same test as promote's verify step. When promote would refuse, the Slack post and job summary give the rollback command (plus "if not on main, merge it first, then promote") instead of the promote one. The step is continue-on-error and defaults to the normal promote message, so it can never block the notification. Promote's own check remains the gate; if the copy drifts, the worst case is a wrong hint.

Docs:

• README: new Hotfix releases section with the full process, contract notes for release and promote, and a rule that the rollback caller must be named rollback.yml (both apps already are).
• CLAUDE.md: records the decision that backports ship through app-rollback.yml and promote gets no override input.
• Promote and release workflow headers updated to match.

Validation

• actionlint 1.7.7 (with shellcheck) and yamllint (relaxed, line-length off): clean.
• Ran the new route step, the notify step (Slack call stubbed) and promote's verify step, extracted from the workflows, against real tags:
  • apps-management v2.5.3 vs current main: route rollback; the Slack text and summary give the rollback command; promote's verify step refuses with the new message naming the 5 files.
  • apps-invest v3.3.5 vs current main: route promote; message unchanged from today; promote's verify step passes.

Rollout

No contract change: inputs, secrets and permissions are untouched (the notify job already has contents: read). Takes effect on the next released event and the next promote run after merge.

---

Generated by Claude Code