feat(empty-pr-guard): composite action + notify alert-card inputs

[tarpanpathak]

Alternative shape for #19. Same behaviour, packaged as a composite action instead of a reusable workflow, so callers write less YAML.

What

1. actions/enforce/action.yml (new). Merge-time gate as a composite action. On a push, resolves the PR behind github.sha and, if its body is empty or whitespace-only, reverts the merge on the pushed branch, edits the PR to explain, and returns block=true. Behaviour identical to the reusable-workflow prototype in feat(empty-pr-guard): reusable empty-PR-description gate + notify alert cards #19: PR-fetch fails safe, all three merge styles (merge / squash / rebase) fully undone, PR body edited with an auto-revert notice.

2. actions/notify/action.yml. Three optional inputs (header, color, status) that swap the deploy card into a general alert. Defaults reproduce the existing card byte-for-byte, so existing deploy callers are unaffected. Same change as feat(empty-pr-guard): reusable empty-PR-description gate + notify alert cards #19.

3. README.md. Contents table row for actions/enforce, an "enforce inputs & outputs" section with a worked example, and a "Why a composite action rather than a reusable workflow?" subsection recording the design rationale.

Why composite instead of reusable workflow

A reusable-workflow guard forces callers to declare two jobs: one to run the guard, and a second *-notify job that carries environment: so the env-scoped Slack webhook resolves. Cross-job output threading (needs.guard.outputs.header) glues them together.

A composite runs inside the caller's job, so:

• The env-scoped webhook is already in scope, no separate alert job needed.
• Alert content flows via step outputs, not needs.<x>.outputs.*.
• The caller declares one job with two steps.

Same internal script, same behaviour, less caller YAML and one fewer node in the pipeline graph.

Compatibility

• notify: additive. header / color / status default to "" and existing deploy callers produce byte-identical output.
• enforce: brand new, no existing callers.
• Ships by moving @v3 forward. Additive minor bump, no new major.

Caller-side comparison

Reusable-workflow shape (#19):

guard:
  uses: nurdsoft/ci-workflows/.github/workflows/empty-pr-guard.yml@v3
  permissions: { contents: write, pull-requests: write }
  with: { label: Service }

guard-notify:
  needs: [guard]
  if: ${{ always() && needs.guard.outputs.outcome != '' }}
  runs-on: ubuntu-latest
  environment: dev
  permissions: { contents: read, pull-requests: read }
  steps:
    - uses: nurdsoft/ci-workflows/actions/notify@v3
      with:
        result: failure
        webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
        label: Service
        header: ${{ needs.guard.outputs.header }}
        color:  ${{ needs.guard.outputs.color }}
        status: ${{ needs.guard.outputs.reason }}

Composite-action shape (this PR):

guard:
  runs-on: ubuntu-latest
  environment: dev
  permissions: { contents: write, pull-requests: write }
  outputs:
    block: ${{ steps.g.outputs.block }}
  steps:
    - id: g
      uses: nurdsoft/ci-workflows/actions/enforce@v3
      with: { label: Service }
    - if: ${{ steps.g.outputs.outcome != '' }}
      uses: nurdsoft/ci-workflows/actions/notify@v3
      with:
        result: failure
        webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
        label: Service
        header: ${{ steps.g.outputs.header }}
        color:  ${{ steps.g.outputs.color }}
        status: ${{ steps.g.outputs.reason }}

Two jobs become one. Cross-job output threading becomes step outputs. Everything downstream (needs.guard.outputs.block) works identically.

Test plan

• action.yml (both) validate as YAML.
• Notify defaults produce byte-identical output to the current deploy card.
• Wired into a real caller pinned at @feat/empty-pr-guard-composite and validated end-to-end on dev:
  • Control case (PR with a non-empty description, merge commit): guard step succeeded, notify step correctly skipped, downstream release/build/deploy/announce all ran green.
  • Empty-body case (PR merged with empty body, merge commit): guard reverted the merge via git revert -m 1, revert commit pushed to dev, notify step fired, downstream release/build/deploy/announce all skipped via needs.guard.outputs.block != 'true', PR body edited with the auto-revert notice.

For the reviewer (@arnavchachra)

Once you approve and merge this to main, please move the @v3 tag to the merge commit so callers pinned to @v3 pick this up. Minor bump is appropriate (matches the additive nature of the notify change).

Notes

• Supersedes feat(empty-pr-guard): reusable empty-PR-description gate + notify alert cards #19. Recommend closing feat(empty-pr-guard): reusable empty-PR-description gate + notify alert cards #19 if this shape is accepted, since carrying both leaves consumers guessing which to adopt.
• The internal revert/edit script is copied from feat(empty-pr-guard): reusable empty-PR-description gate + notify alert cards #19 without material change; only the packaging differs.