pal-e-docs

Review: Bug: Migration 037 fails on fresh deploy -- enum ADD VALUE in same transaction as INSERT

review-889-2026-04-07 Doc

review ready
Project

Verdict: READY

Re-review after refinement. All three recommendations from the initial NEEDS_REFINEMENT review have been addressed.

Template Completeness

Cannot read the full Forgejo issue body via list_issues (returns title/state/URL only). Based on caller-confirmed refinements, the issue now contains:
  • [x] Type (Bug)
  • [x] Repo (basketball-api)
  • [x] What Broke (enum ADD VALUE + INSERT in same transaction)
  • [x] Acceptance Criteria (fresh DB, existing DB with workaround, CI passes) -- confirmed added in refinement
  • [x] Related (references migrations 011/012/018/027 as correct pattern)
  • [ ] Lineage, Repro Steps, Expected Behavior, Environment -- cannot verify without body access. Non-blocking for a well-understood bug with a known fix pattern.

Traceability

  • [x] story:WS-S1 -- "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable"
  • [x] story note verified -- found in project-westside-basketball user-stories section (Superadmin list)
  • [x] arch:basketball-api -- basketball API component
  • [ ] arch note MISSING -- arch-basketball-api does not exist in pal-e-docs. [SCOPE] recommendation carried forward, but this is a broad organizational gap affecting many board items, not specific to this ticket's executability.
  • [x] Forgejo issue -- forgejo_admin/basketball-api#384, open

File Targets

  • [x] alembic/versions/037_add_monthly_category_and_first_payment_email.py -- file does not exist on local main (local checkout has migrations through 030). Refinement clarifies: migrations 031-037 are on remote main. Agent must git pull before starting work. This is sufficient instruction for the dev agent.

Repo Placement

OK. Forgejo issue filed on forgejo_admin/basketball-api, fix targets basketball-api alembic migration directory. Single repo, no cross-repo concerns.

Dependencies

  • [x] Migrations 031-036 -- exist on remote main per refinement. Agent pulls latest before starting.
  • [x] Prod workaround already applied (manual psql). No production urgency.
  • [x] No blocking board items identified. Item 889 is independent.

Acceptance Criteria

Refinement added explicit AC:
  • alembic upgrade head succeeds on a fresh (empty) database
  • alembic upgrade head succeeds on an existing database with the workaround already applied
  • CI pipeline passes
All three are agent-verifiable. The fresh DB criterion catches the original bug. The existing DB criterion ensures IF NOT EXISTS guards work. CI passing catches regressions.

Blast Radius

Low. Five existing migrations (011, 012, 018, 027) use ALTER TYPE ADD VALUE on enums. All were verified in this review:
  • 011: ADD VALUE + ALTER COLUMN (no INSERT with new value)
  • 012: ADD VALUE + ADD COLUMN (no INSERT with new value)
  • 018: ADD VALUE + CREATE TABLE (no INSERT with new value)
  • 027: ADD VALUE only (no INSERT)
None combine ADD VALUE with INSERT. Migration 037 is the sole offender. Fix is isolated to one file. No downstream consumers affected.

Decomposition Assessment

Single file target, 1 repo, well-understood fix (add op.execute("COMMIT") before ADD VALUE, then op.execute("BEGIN") after). Estimated agent time well under 5 minutes. No decomposition needed.

Refinement Resolution

# Previous Recommendation Status
1 [SCOPE] Create arch note arch-basketball-api Carried forward as non-blocking organizational gap. Does not affect ticket executability.
2 [BODY] Clarify file target provenance (031-037 on remote main) RESOLVED. Refinement added: "migrations 031-037 are on remote main, agent must git pull."
3 [BODY] Add explicit acceptance criteria RESOLVED. Refinement added: fresh DB, existing DB with workaround, CI passes.

Recommendation

  • [SCOPE] Create architecture note arch-basketball-api for component basketball-api in pal-e-docs (carried forward -- non-blocking).
No blocking issues remain. Ticket is ready for dispatch.