Review: Alembic migration crash — app down (deploy blocker)

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Bug
• [x] Lineage — standalone, discovered during deploy
• [x] Repo — forgejo_admin/basketball-api
• [x] What Broke — detailed CrashLoopBackOff + error message
• [x] Repro Steps — 6 clear steps
• [x] Expected Behavior — clean upgrade path described
• [x] Environment — cluster, namespace, pod names, DB state
• [x] File Targets — 4 files listed (+ 1 added in refinement)
• [x] Acceptance Criteria — 6 criteria (updated in refinement)
• [x] Related — 3 blocked issues referenced
• [x] Constraints — 3 fix options analyzed with tradeoffs

Traceability

• [ ] story:X label — missing, but acceptable: unplanned live outage, no user story applies
• [x] arch:admin-api label — present on board item #433
• [x] Forgejo issue — forgejo_admin/basketball-api#179, open

File Targets

• [x] alembic/versions/019_player_teams_junction.py — verified: down_revision = "018" (branch 1 of fork)
• [x] alembic/versions/020_add_custom_notes_to_player.py — verified: down_revision = "018" (branch 2 of fork)
• [x] alembic/versions/022_merge_heads.py — verified: down_revision = ("019", "021") (merge point)
• [x] App startup — verified: Dockerfile line 27: CMD ["sh", "-c", "alembic upgrade head && uvicorn ..."]
• [ ] alembic/versions/e09c9e678004_add_division_column_to_players.py — ISSUE: NOT an orphan. Migration 007 has down_revision = "e09c9e678004". This file is part of the main chain: 005 to e09c9e678004 to 007 to 008 to ... to 018. Deleting it would break the entire migration chain from 007 onward. Chain analysis confirms exactly 1 head (025) and only 1 fork (at 018). The refinement Fix 2 is based on a misidentification.

Repo Placement

Dependencies

• #170 (jersey sync fix, migration 023) — closed, already merged. No longer blocked.
• #173 (teams/save fix) — closed, already merged. No longer blocked.
• #171 (Baby Betty data fix) — open, still blocked by this deploy blocker.
• Board item #430 (public coaches endpoint) in todo — depends on bb-176, but deploy blocker means no new API deploys until resolved.

Acceptance Criteria

• [x] "Migration chain resolves cleanly from 018 to current head" — agent can run alembic upgrade head in test
• [x] "alembic heads shows exactly 1 head" — already true on current codebase (head = 025), misleading as an AC
• [x] "Pod starts without CrashLoopBackOff" — agent can verify via kubectl
• [x] "alembic_version shows current head" — agent can query
• [x] "No data loss" — hard to verify automatically, but agent can check table schemas
• [x] "All tests still pass" — agent can run test suite

Blast Radius

• The division column added by e09c9e678004 is deeply integrated — 70+ references across models.py, admin.py, coaches_api.py, jersey.py, register.py, tryouts.py, players.py, teams.py, account.py, email.py. Deleting this migration would be catastrophic.
• The real fix scope is narrow: the 018 fork (019 and 020 both descending from 018) needs resolution at the DB level. The merge migration 022 exists — the issue is that alembic cannot traverse a fork from a single DB stamp.
• Fix option 2 from the ticket (manual stamp + startup script logic) is safest and avoids rewriting migration files.

Recommendation

• Remove the file target e09c9e678004_add_division_column_to_players.py from the issue scope
• Remove or reword the AC "alembic heads shows exactly 1 head" — this is already true on the current codebase. The real problem is the DB stamp at 018 hitting a fork, not multiple heads in the code. Consider rewording to: "alembic upgrade head succeeds from DB stamp 018 without manual intervention"
• Keep all other ACs and the core fix scope (resolving the 018 fork so the pod can start)