promote: dev → beta (supersede stale beta, adopt new ladder)

.github/workflows/promotion-guard.yml

@@ -0,0 +1,82 @@
+name: Promotion Guard
+
+# Enforces the promotion ladder so environment branches can only receive merges
+# from the tier directly below them:
+#
+#   dev  ->  beta  ->  main
+#
+# (dev is the team integration + final-QA environment; beta is a disposable
+# infra rehearsal for selected testers; main is production. Staging was dropped —
+# per-PR preview envs + dev cover pre-beta testing.)
+#
+# GitHub rulesets can require a review and status checks, but they cannot
+# restrict which *source* branch a PR merges from. This guard fills that gap:
+# it fails any PR into a protected branch whose head is not the allowed source.
+# Mark the "guard" check as a required status check in each branch's ruleset
+# (beta, main) for it to actually block a merge.
+#
+# PRs into a protected branch must come from a branch in this repo (not a fork).
+# Emergency bypass: add the `hotfix` label to skip the ladder — allowed only on
+# PRs targeting `main`, for a critical fix that must land out of order.
+
+on:
+  pull_request:
+    branches: [main, beta]
+    types: [opened, reopened, synchronize, edited, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+jobs:
+  guard:
+    name: guard
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check promotion source branch
+        env:
+          BASE: ${{ github.base_ref }}
+          HEAD: ${{ github.head_ref }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          REPO: ${{ github.repository }}
+          # contains() over the label-name array is an exact element match, so a
+          # label like "needs hotfix review" does NOT count as the hotfix label.
+          IS_HOTFIX: ${{ contains(github.event.pull_request.labels.*.name, 'hotfix') }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          # Allowed source for each protected target branch.
+          declare -A ALLOWED=( [main]="beta" [beta]="dev" )
+          expected="${ALLOWED[$BASE]:-}"
+
+          echo "PR: $HEAD -> $BASE (from $HEAD_REPO)"
+
+          if [ -z "$expected" ]; then
+            echo "::notice::No promotion rule defined for base '$BASE'; nothing to enforce."
+            exit 0
+          fi
+
+          # Promotions and hotfixes to protected branches must originate from a
+          # branch in this repository, never a fork — otherwise a fork branch
+          # named 'dev' could satisfy 'staging <- dev' and skip the ladder.
+          if [ "$HEAD_REPO" != "$REPO" ]; then
+            echo "::error::PRs into '$BASE' must come from a branch in '$REPO', not a fork ('$HEAD_REPO')."
+            exit 1
+          fi
+
+          # Emergency bypass with the 'hotfix' label — permitted only into main.
+          if [ "$IS_HOTFIX" = "true" ]; then
+            if [ "$BASE" != "main" ]; then
+              echo "::error::The 'hotfix' label may only bypass the ladder on PRs into 'main', not '$BASE'."
+              exit 1
+            fi
+            echo "::warning::'hotfix' label present — bypassing the promotion ladder for 'main'."
+            exit 0
+          fi
+
+          if [ "$HEAD" != "$expected" ]; then
+            echo "::error::Promotion ladder violation: '$BASE' only accepts merges from '$expected', but this PR is from '$HEAD'. Follow the ladder dev -> beta -> main, or add the 'hotfix' label (main only) to bypass."
+            exit 1
+          fi
+
+          echo "OK: '$BASE' is correctly receiving a promotion from '$expected'."

.gitignore

@@ -106,9 +106,26 @@ TWIZRR_BACKEND_TASKS.md
 TWIZRR_WEB_TASKS.md
 TWIZRR_WHATSAPP_TASKS.md
 TWIZRR_CLEANUP_REPORT.md
+TWIZRR_REALTIME_ARCHITECTURE.md
+TWIZRR_REMAINING_BALANCE_COLLECTION_DESIGN.md
+TWIZRR_SETTLEMENT_ROLLOUT_READINESS.md
+TWIZRR_SHOPPER_WALLET_OVERPAYMENT_DESIGN.md
+Twizrr_StorePass.md
+TWIZRR_MONNIFY_PROVIDER_ASSESSMENT.md
+TWIZRR_MERCHANT_EARNINGS_WALLET_DESIGN.md
+TWIZRR_MEDIA_ARCHITECTURE.md
+TWIZRR_MEDIA_STORAGE.md
+TWIZRR_PAYMENT_EXCEPTION_SANDBOX_RUNBOOK.md
+TWIZRR_PAYMENT_AMOUNT_EXCEPTION_DESIGN.md
+TWIZRR_PLATFORM_FEE_ANALYSIS.md
 
 # Audit and report files
 *_AUDIT_REPORT.md
 *_CLEANUP_REPORT.md
 *_HANDOFF.md
 
+# Neon CLI / agent skills tooling (local setup artifacts)
+.neon
+.agents/
+skills-lock.json
+