Review: Fix Alembic multiple heads — migration branch conflict

Verdict: READY

Template Completeness

• [x] Type — Bug
• [x] User Story — story:WS-S1, superadmin deploy via IaC
• [x] What Broke — clear error message, CrashLoopBackOff described
• [x] Repro Steps — 4-step reproduction path
• [x] Expected Behavior — single head, clean pod start
• [x] Environment — namespace, cluster, migration directory identified
• [x] Lineage — story, arch, blocked-by, blocks all documented
• [x] Repo — forgejo_admin/basketball-api
• [x] Context — explains PR #334 triggered the restart that exposed the latent bug
• [x] File Targets — alembic/versions/ directory and specific hash-named migration
• [x] Acceptance Criteria — 3 testable criteria
• [x] Test Expectations — alembic check, existing tests, pod healthcheck
• [x] Constraints — no data loss, additive only
• [x] Checklist — 4 discrete steps
• [x] Related — basketball-api#334 linked

Traceability

• [x] story:WS-S1 — "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable." Verified in project-westside-basketball user-stories section under Superadmin (Lucas).
• [x] arch:basketball-api — label present on board item
• [ ] arch note MISSING — No arch-basketball-api note exists in pal-e-docs. This is a pre-existing systemic gap across many basketball-api board items, not specific to this ticket. Acceptable for now.
• [x] Forgejo issue — forgejo_admin/basketball-api#337, state: open

File Targets

• [x] alembic/versions/ — verified: directory exists with 29 migration files (001-030 numbered + e09c9e678004 hash-named)
• [x] alembic/versions/e09c9e678004_add_division_column_to_players.py — verified: exists, revision e09c9e678004, down_revision = '005'

Repo Placement

Dependencies

• [x] No upstream blockers — confirmed in issue lineage ("Blocked by: Nothing")
• [x] Blocks all basketball-api functionality — pod CrashLoopBackOff prevents any API access
• [x] Board item #815 (basketball-api#333, PR #334) triggered the exposure — currently in needs_approval column (not blocking this fix)
• [x] Board item #823 (basketball-api#340) is in_progress — may be affected if it needs a running pod, but not a dependency of this fix
• [x] Prior resolved: board item #352 (basketball-api#166, "Alembic forked history — 019 and 020 both descend from 018") — done column. Same class of bug recurring.

Acceptance Criteria

• [x] alembic heads returns exactly 1 head — testable, specific, programmatically verifiable
• [x] alembic upgrade head succeeds — testable, specific, programmatically verifiable
• [x] Pod starts without CrashLoopBackOff — testable via kubectl after deploy

Blast Radius

• The division column added by e09c9e678004 is already used across 38 files in the codebase (models, routes, tests). The column exists in production — only the alembic revision graph is broken, not the DB schema.
• The merge migration will be a no-op (additive merge point only), so no schema changes occur.
• The Dockerfile CMD runs alembic upgrade head && uvicorn ... on every pod start, so this blocks ALL basketball-api deployments and pod restarts until fixed.
• No other repos in the platform use alembic — blast radius is fully contained to basketball-api.
• Rollback is straightforward: revert the merge migration commit if anything goes wrong.

Decomposition Assessment

• Does the ticket have >3 discrete changes? No — 1-2 files (merge migration output + possibly re-parenting e09c9e678004's down_revision).
• Would an agent need >5 minutes? No — estimated 2-3 minutes. alembic merge heads is a single command that generates a merge migration file.
• Are there independent subtasks that could be parallelized? No — this is a single atomic operation.

Recommendation