Review: Alembic migration crash (R3 — v2 refinement)

Verdict: READY

Template Completeness

• [x] Type — Bug
• [x] Lineage — standalone, discovered during deploy
• [x] Repo — forgejo_admin/basketball-api
• [x] What Broke — CrashLoopBackOff, alembic error message, fork diagram
• [x] Repro Steps — 6 steps, clear and accurate
• [x] Expected Behavior — present
• [x] Environment — cluster, namespace, pod names, DB state
• [x] Acceptance Criteria — 5 criteria (updated in v2 refinement comment)
• [x] Constraints — 3 fix options enumerated with tradeoff analysis
• [x] Related — 3 blocked issues identified (#170, #173, #171)
• [x] File Targets — 3 files (updated in v2 refinement, e09c9e678004 correctly removed)
• [ ] Test Expectations — present but slightly stale: says "555 tests" — agent should run tests and accept whatever count returns. Minor, not blocking.

Traceability

• [ ] story:X label — no story label on board item. Acceptable: this is an unplanned bug/outage, not a user story deliverable. Label scope:unplanned covers it.
• [x] arch:admin-api label — matches basketball-api (admin-api is the arch component name)
• [x] Forgejo issue — forgejo_admin/basketball-api#179, open

File Targets

• [x] alembic/versions/019_player_teams_junction.py — verified: down_revision = "018" (line 13), branch 1 of fork
• [x] alembic/versions/020_add_custom_notes_to_player.py — verified: down_revision = "018" (line 13), branch 2 of fork
• [x] alembic/versions/022_merge_heads.py — verified: down_revision = ("019", "021") (line 16), merge point
• [x] Dockerfile CMD — verified: alembic upgrade head on line 27, confirms migration runs on startup

Chain Verification (independent analysis)

Repo Placement

Dependencies

• Blocks #170 (jersey sync fix with migration 023)
• Blocks #173 (teams/save fix — code only, but deploy blocked)
• Blocks #171 (Baby Betty data fix — deploy blocked)
• Board item #431 (SvelteKit public site) is in_progress on westside-app — independent, not blocked by this
• Board item #430 (public coaches endpoint) is in todo — depends on bb-176, not directly on this, but deploy-blocked until API is up
• No upstream blockers — this can proceed immediately

Acceptance Criteria

• "Chain resolves cleanly from 018 to current head" — agent can run alembic upgrade head in test DB
• "Pod starts without CrashLoopBackOff" — agent can verify via kubectl get pods
• "alembic_version shows current head" — agent can query DB
• "No data loss" — agent can verify table/column existence
• "All tests still pass" — agent can run pytest

Blast Radius

• mcd-tracker-api has alembic migrations (001-004) but a simple linear chain — no fork risk there
• No other repos in the platform use alembic
• The fix (linearizing 020 to depend on 019 instead of 018) only changes the down_revision pointer — no schema changes, no data migration code affected
• 022_merge_heads.py may need adjustment if the chain becomes linear (merge of a single branch is a no-op but not harmful)

Recommendation