ci(policy): enforce one migration per PR

scripts/ci/one_migration_per_pr.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Enforce: if a PR adds migration files under backend/migrations/versions/, it must add <= 1.
+# Rationale: keeps review/rollback straightforward and avoids surprise multiple-head merges.
+
+if [ "${GITHUB_EVENT_NAME:-}" != "pull_request" ]; then
+  echo "Not a pull_request event; skipping one-migration-per-PR gate."
+  exit 0
+fi
+
+BASE_SHA="${GITHUB_BASE_SHA:-${GITHUB_EVENT_PULL_REQUEST_BASE_SHA:-}}"
+HEAD_SHA="${GITHUB_SHA:-}"
+
+if [ -z "$BASE_SHA" ] || [ -z "$HEAD_SHA" ]; then
+  echo "Missing BASE_SHA/HEAD_SHA (BASE_SHA='$BASE_SHA', HEAD_SHA='$HEAD_SHA')"
+  exit 2
+fi
+
+# Ensure base is present in shallow clones.
+git fetch --no-tags --depth=1 origin "$BASE_SHA" || true
+
+CHANGED=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" || true)
+if [ -z "$CHANGED" ]; then
+  echo "No changed files detected."
+  exit 0
+fi
+
+MIGRATIONS=$(echo "$CHANGED" | grep -E '^backend/migrations/versions/.*\.py$' || true)
+COUNT=$(echo "$MIGRATIONS" | sed '/^$/d' | wc -l | tr -d ' ')
+
+if [ "$COUNT" -le 1 ]; then
+  echo "Migration gate OK (migrations_added=$COUNT)."
+  exit 0
+fi
+
+echo "Migration gate FAILED: this PR adds $COUNT migration files; policy allows at most 1."
+echo
+
+echo "Migrations detected:"
+echo "$MIGRATIONS"
+echo
+
+echo "How to fix:"
+echo "- Consolidate schema changes into a single migration file (squash)."
+echo "- If you have multiple Alembic heads, create ONE merge migration instead of several."
+echo "- If you truly need multiple migrations, split into multiple PRs."
+
+exit 1