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

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Bug
• [x] Lineage — standalone, discovered during deploy of PRs #172 + #174
• [x] Repo — forgejo_admin/basketball-api
• [x] What Broke — detailed error message, pod status, chain analysis
• [x] Repro Steps — 6 clear steps
• [x] Expected Behavior — present
• [x] Environment — cluster, namespace, pod name, DB state
• [x] File Targets — 4 files listed with specific line claims
• [x] Acceptance Criteria — 5 criteria
• [x] Constraints — 3 fix options analyzed with trade-offs
• [x] Related — 3 blocked issues listed
• [ ] Test Expectations — present but states "all 555 tests pass" which only validates no regression, not the fix itself. No test for the migration chain resolution.

Traceability

• [ ] story:X label — missing from board item. This is a live outage / deploy blocker, so no user story applies. Foundational work, acceptable.
• [x] arch:admin-api label — present on board item (arch:admin-api maps to basketball-api)
• [x] Forgejo issue — forgejo_admin/basketball-api#179, open

File Targets

• [x] alembic/versions/019_player_teams_junction.py — verified: down_revision = "018" at line 13
• [x] alembic/versions/020_add_custom_notes_to_player.py — verified: down_revision = "018" at line 13 (confirms the fork)
• [x] alembic/versions/022_merge_heads.py — verified: down_revision = ("019", "021") at line 16
• [x] Dockerfile CMD — verified: alembic upgrade head at line 27

Repo Placement

Dependencies

• Blocks #170 (jersey sync fix, includes migration 023) — closed, PR already merged but deploy blocked by this migration crash
• Blocks #173 (teams/save fix) — closed, same situation
• Blocks #171 (Baby Betty data fix) — open, blocked by deploy
• Board item #430 (Public coaches endpoint, in_progress) — depends on bb-176 per labels, but basketball-api being down means no deploy of any basketball-api work until this is fixed

Acceptance Criteria Assessment

• [x] "Alembic migration chain resolves cleanly from 018 to 023" — agent-verifiable via kubectl exec, BUT 023 is stale (see below)
• [x] "Pod starts without CrashLoopBackOff" — agent-verifiable via kubectl get pods
• [ ] "alembic_version table shows 023" — WRONG: actual head is 025 (migrations 024_add_is_public_to_players and 025_add_coach_public_fields exist beyond 023). Must be updated to 025.
• [x] "No data loss" — verifiable by spot-checking row counts
• [x] "All 555 tests still pass" — agent-verifiable via pytest

Blast Radius

• Orphan migration detected: e09c9e678004_add_division_column_to_players.py has down_revision = "005" — this is an auto-generated Alembic migration (UUID-style revision ID) that creates a second orphan branch off revision 005. It is not in the numeric chain and could cause alembic heads to show multiple heads even after this fix. The agent should be instructed to delete or integrate this file.
• westside-contracts — no Alembic. No blast radius.
• No other repos in the platform use Alembic migrations, so the forked-chain pattern is isolated to basketball-api.

Recommendation

• Update acceptance criteria: Change "alembic_version shows 023" to "alembic_version shows 025" and "from 018 to 023" to "from 018 to 025". Migrations 024 and 025 exist on main and must be included in the upgrade target.
• Add file target for orphan migration: e09c9e678004_add_division_column_to_players.py (down_revision="005") creates a second chain branch. The agent should either delete this file or the ticket should explicitly state it is out of scope. Without addressing it, alembic heads may still show multiple heads after the fix.