forgejo_admin/basketball-api

Fork 1

Create 16U Local Queens team (unblocks Jacelyn Bronson local-tier move) #422

New issue

Closed

opened 2026-04-10 18:34:31 +00:00 by forgejo_admin · 3 comments

forgejo_admin commented

2026-04-10 18:34:31 +00:00

Owner

Type

Feature

Lineage

Standalone — discovered during 2026-04-10 Westside Ops session. Coach Marcus confirmed in WKQ Stakeholders group that Jacelyn Bronson should move from 16U Elite Queens to "16U Local" — but no 16U Local Queens team exists in the DB. This is the first Queens player requesting the local-only tier.

Revision history: review-927-2026-04-10 returned BLOCK based on stale source reading. review-927-2026-04-10-pass3 rescinded the block against a fresh main clone and found LOCAL_CONFIG_16U already exists in migration 034. 5 refinements applied in this revision.

Repo

forgejo_admin/basketball-api

User Story

As Coach Marcus
I want a 16U Local Queens team that exists in the system
So that Queens players who don't want to travel can be placed on a local-only roster (with local-only contract config) instead of being forced onto the Elite travel team or dropped from the program

Context

Marcus told us in WKQ chat (2026-04-10) to move Jacelyn Bronson from 16U Elite Queens to 16U Local. Her story: she originally asked out of her Elite contract because she didn't want to travel; now she wants back in but at a local-only level. Her fee stays at $160.

The DB currently has local-tier teams only for Kings:

16U Local Kings (team id 7)
17U Local Kings (team id 6)

For Queens, only Elite (travel) variants exist:

16U Elite Queens (team id 5)
17U Elite Queens (team id 4)

Ground truth on main (verified against commit 9598c4d):

Team.contract_config JSONB column EXISTS at src/basketball_api/models.py:386 (added in migration 031)
alembic/versions/034_seed_team_contract_configs.py already defines LOCAL_CONFIG_16U (lines 334-367) — the exact local-variant template we want to clone for Queens: variant="local", monthly_fee_default=200, empty tournaments list, Mon+Fri practices at BWill. This is the canonical template to reuse — do NOT write a new config from scratch.

File Targets

Files to create:

alembic/versions/040_create_16u_local_queens_team.py — new migration with down_revision = "039" (the current head; verify with alembic heads before writing). Inserts a single row into teams using LOCAL_CONFIG_16U from migration 034 (copy the dict inline, do not import from an earlier migration).

Files NOT to create:

No migrations/data/*.json file — there is no migrations/data/ directory in this repo. Migration 034 uses the inline-dict pattern; follow it.

Files NOT to modify:

src/basketball_api/models.py — schema change is not required; the contract_config column already exists
Any other team row — do not modify 16U Local Kings or any existing team

Acceptance Criteria

New teams row exists with:
- name = '16U Local Queens'
- division = 'girls' (matching the Division.girls enum — verified present on main)
- age_group = 'u16' (matching AgeGroup.u16 enum)
- tenant_id set to the Westside Kings & Queens tenant (look up by name or slug; do not hardcode an ID)
- coach_id = NULL initially (Marcus will assign a coach later; NULL is acceptable per the column definition)
- contract_config JSONB populated with a deep-copy of LOCAL_CONFIG_16U from migration 034
Migration 040 upgrade() inserts the row idempotently (check for existence first, skip if already present)
Migration 040 downgrade() removes only the 16U Local Queens row, does not touch other rows
Migration is idempotent (safe to re-run)
After alembic upgrade head, Jacelyn Bronson (id 97) can be assigned to this team via player_teams (but do NOT do that assignment in this migration — it's a separate step handled by basketball-api#425's contract-offer endpoint)
After Jacelyn's move, her contract can be re-issued at $160 custom rate against the new team's contract_config

Test Expectations

Manual test: alembic upgrade head on local dev, verify team exists via SELECT id, name, contract_config FROM teams WHERE name = '16U Local Queens'
Manual test: re-run alembic upgrade head, verify no-op (idempotent)
Manual test: alembic downgrade -1 removes only the new row, leaves others intact
Integration test (optional): create a fake Queens player, assign to 16U Local Queens via player_teams, verify contract_config loads correctly when queried through the app layer

Constraints

Do NOT move Jacelyn as part of this ticket — that's a separate player-move operation that will happen via basketball-api#425 (the contract-offer endpoint, which handles signed → re-offer tier changes)
Match the JSONB shape of LOCAL_CONFIG_16U in migration 034 exactly — do not invent new fields
Practice schedule is the Kings Local default (Monday + Friday BWill); Marcus can override later via a follow-up migration if Queens Local needs a different schedule. Placeholder acknowledged.
tenant_id must be looked up dynamically in the migration (query for the Westside tenant by name or slug), not hardcoded
Use op.execute() or op.bulk_insert() consistent with migration 034's pattern

Checklist

PR opened against basketball-api main
Migration 040 reviewed (no accidentally-broad inserts)
alembic upgrade head clean on local dev
alembic downgrade -1 clean
Row present in DB with correct shape
No unrelated changes

westside-basketball — project this affects
Unblocks: Jacelyn Bronson move from 16U Elite Queens to 16U Local Queens at $160/month (handled in basketball-api#424 Marcus batch execution)
Depends on: nothing (contract_config column exists on main since migration 031)
Pattern reference: alembic/versions/034_seed_team_contract_configs.py::LOCAL_CONFIG_16U
Unblocks (downstream): basketball-api#424 (Marcus batch), basketball-api#425 (contract-offer endpoint uses this team for Jacelyn's signed → offered re-issue)

### Type Feature ### Lineage Standalone — discovered during 2026-04-10 Westside Ops session. Coach Marcus confirmed in WKQ Stakeholders group that Jacelyn Bronson should move from 16U Elite Queens to "16U Local" — but no 16U Local Queens team exists in the DB. This is the first Queens player requesting the local-only tier. **Revision history**: review-927-2026-04-10 returned BLOCK based on stale source reading. review-927-2026-04-10-pass3 rescinded the block against a fresh main clone and found LOCAL_CONFIG_16U already exists in migration 034. 5 refinements applied in this revision. ### Repo `forgejo_admin/basketball-api` ### User Story As Coach Marcus I want a 16U Local Queens team that exists in the system So that Queens players who don't want to travel can be placed on a local-only roster (with local-only contract config) instead of being forced onto the Elite travel team or dropped from the program ### Context Marcus told us in WKQ chat (2026-04-10) to move Jacelyn Bronson from 16U Elite Queens to 16U Local. Her story: she originally asked out of her Elite contract because she didn't want to travel; now she wants back in but at a local-only level. Her fee stays at $160. The DB currently has local-tier teams only for Kings: - 16U Local Kings (team id 7) - 17U Local Kings (team id 6) For Queens, only Elite (travel) variants exist: - 16U Elite Queens (team id 5) - 17U Elite Queens (team id 4) **Ground truth on main** (verified against commit 9598c4d): - `Team.contract_config` JSONB column EXISTS at `src/basketball_api/models.py:386` (added in migration 031) - `alembic/versions/034_seed_team_contract_configs.py` already defines `LOCAL_CONFIG_16U` (lines 334-367) — the exact local-variant template we want to clone for Queens: `variant="local"`, `monthly_fee_default=200`, empty tournaments list, Mon+Fri practices at BWill. This is the canonical template to reuse — do NOT write a new config from scratch. ### File Targets Files to create: - `alembic/versions/040_create_16u_local_queens_team.py` — new migration with `down_revision = "039"` (the current head; verify with `alembic heads` before writing). Inserts a single row into `teams` using `LOCAL_CONFIG_16U` from migration 034 (copy the dict inline, do not import from an earlier migration). Files NOT to create: - No `migrations/data/*.json` file — there is no `migrations/data/` directory in this repo. Migration 034 uses the inline-dict pattern; follow it. Files NOT to modify: - `src/basketball_api/models.py` — schema change is not required; the `contract_config` column already exists - Any other team row — do not modify 16U Local Kings or any existing team ### Acceptance Criteria - [ ] New `teams` row exists with: - `name = '16U Local Queens'` - `division = 'girls'` (matching the `Division.girls` enum — verified present on main) - `age_group = 'u16'` (matching `AgeGroup.u16` enum) - `tenant_id` set to the Westside Kings & Queens tenant (look up by name or slug; do not hardcode an ID) - `coach_id = NULL` initially (Marcus will assign a coach later; NULL is acceptable per the column definition) - `contract_config` JSONB populated with a deep-copy of `LOCAL_CONFIG_16U` from migration 034 - [ ] Migration 040 `upgrade()` inserts the row idempotently (check for existence first, skip if already present) - [ ] Migration 040 `downgrade()` removes only the 16U Local Queens row, does not touch other rows - [ ] Migration is idempotent (safe to re-run) - [ ] After `alembic upgrade head`, Jacelyn Bronson (id 97) can be assigned to this team via `player_teams` (but do NOT do that assignment in this migration — it's a separate step handled by basketball-api#425's contract-offer endpoint) - [ ] After Jacelyn's move, her contract can be re-issued at $160 custom rate against the new team's `contract_config` ### Test Expectations - [ ] Manual test: `alembic upgrade head` on local dev, verify team exists via `SELECT id, name, contract_config FROM teams WHERE name = '16U Local Queens'` - [ ] Manual test: re-run `alembic upgrade head`, verify no-op (idempotent) - [ ] Manual test: `alembic downgrade -1` removes only the new row, leaves others intact - [ ] Integration test (optional): create a fake Queens player, assign to 16U Local Queens via `player_teams`, verify `contract_config` loads correctly when queried through the app layer ### Constraints - **Do NOT move Jacelyn as part of this ticket** — that's a separate player-move operation that will happen via basketball-api#425 (the contract-offer endpoint, which handles signed → re-offer tier changes) - Match the JSONB shape of `LOCAL_CONFIG_16U` in migration 034 exactly — do not invent new fields - Practice schedule is the Kings Local default (Monday + Friday BWill); Marcus can override later via a follow-up migration if Queens Local needs a different schedule. Placeholder acknowledged. - `tenant_id` must be looked up dynamically in the migration (query for the Westside tenant by name or slug), not hardcoded - Use `op.execute()` or `op.bulk_insert()` consistent with migration 034's pattern ### Checklist - [ ] PR opened against basketball-api main - [ ] Migration 040 reviewed (no accidentally-broad inserts) - [ ] `alembic upgrade head` clean on local dev - [ ] `alembic downgrade -1` clean - [ ] Row present in DB with correct shape - [ ] No unrelated changes ### Related - `westside-basketball` — project this affects - Unblocks: Jacelyn Bronson move from 16U Elite Queens to 16U Local Queens at $160/month (handled in basketball-api#424 Marcus batch execution) - Depends on: nothing (contract_config column exists on main since migration 031) - Pattern reference: `alembic/versions/034_seed_team_contract_configs.py::LOCAL_CONFIG_16U` - Unblocks (downstream): basketball-api#424 (Marcus batch), basketball-api#425 (contract-offer endpoint uses this team for Jacelyn's signed → offered re-issue)

forgejo_admin referenced this issue

2026-04-10 19:51:48 +00:00

Execute Marcus 2026-04-10 batch: 6 contracts + 9 jersey emails #424

forgejo_admin referenced this issue

2026-04-10 20:10:56 +00:00

Add POST /admin/contract/offer endpoint (mints contract offers) #425

forgejo_admin referenced this issue

2026-04-10 20:14:31 +00:00

Add POST /admin/contract/offer endpoint (mints contract offers) #425

forgejo_admin commented

2026-04-10 20:27:31 +00:00

Author

Owner

Scope Review: BLOCK

Review note: review-927-2026-04-10

Critical finding: the ticket premise assumes a teams.contract_config JSONB column that does not exist in basketball-api.

Verified by reading src/basketball_api/models.py — the Team class (lines 341-360) has only: id, tenant_id, name, division, age_group, coach_id, groupme_group_id, groupme_share_url, created_at. No contract_config. grep -rn "contract_config" across the entire repo (src, alembic, tests) returns zero hits. The only JSONB columns in the schema are products.custom_fields, orders.custom_data, and oauth_tokens.token_data.

A dev agent cannot satisfy the acceptance criterion "contract_config JSONB populated with local-variant structure" because the column does not exist. The claim that "16U Local Kings (team id 7) has variant: local, practices: Monday + Friday at BWill, monthly_fee_default: 200" has no source-of-truth in the codebase.

Blocking issues:

[BLOCK] teams.contract_config column does not exist. Implicit prerequisites: schema migration + backfill + application-layer lookup. That's a multi-ticket feature, not a one-row insert.
[LABEL] type:bug label contradicts the ticket body which says Feature. Change to type:feature.

Recommended path forward (needs Ava/Lucas decision):

Minimal unblock for Jacelyn: create the 16U Local Queens row with just name + division + age_group + tenant_id. Handle her $160 custom fee via whatever per-player contract override mechanism already exists. Rewrite AC to match. Probably a 5-minute ticket.
Design team-level contract configs properly: a new WS-S23 multi-ticket scope that adds the column, seeds existing teams, and wires app-layer lookup. NOT a Marcus-batch unblocker.

Do not dispatch a dev agent until scope is rewritten. Recommend Option 1 for the Marcus batch and filing a separate architectural ticket for Option 2.

## Scope Review: BLOCK Review note: `review-927-2026-04-10` **Critical finding:** the ticket premise assumes a `teams.contract_config` JSONB column that does not exist in basketball-api. Verified by reading `src/basketball_api/models.py` — the `Team` class (lines 341-360) has only: `id`, `tenant_id`, `name`, `division`, `age_group`, `coach_id`, `groupme_group_id`, `groupme_share_url`, `created_at`. No `contract_config`. `grep -rn "contract_config"` across the entire repo (src, alembic, tests) returns zero hits. The only JSONB columns in the schema are `products.custom_fields`, `orders.custom_data`, and `oauth_tokens.token_data`. A dev agent cannot satisfy the acceptance criterion "`contract_config` JSONB populated with local-variant structure" because the column does not exist. The claim that "16U Local Kings (team id 7) has variant: local, practices: Monday + Friday at BWill, monthly_fee_default: 200" has no source-of-truth in the codebase. Blocking issues: - [BLOCK] `teams.contract_config` column does not exist. Implicit prerequisites: schema migration + backfill + application-layer lookup. That's a multi-ticket feature, not a one-row insert. - [LABEL] `type:bug` label contradicts the ticket body which says `Feature`. Change to `type:feature`. Recommended path forward (needs Ava/Lucas decision): 1. **Minimal unblock for Jacelyn**: create the 16U Local Queens row with just `name` + `division` + `age_group` + `tenant_id`. Handle her $160 custom fee via whatever per-player contract override mechanism already exists. Rewrite AC to match. Probably a 5-minute ticket. 2. **Design team-level contract configs properly**: a new WS-S23 multi-ticket scope that adds the column, seeds existing teams, and wires app-layer lookup. NOT a Marcus-batch unblocker. Do not dispatch a dev agent until scope is rewritten. Recommend Option 1 for the Marcus batch and filing a separate architectural ticket for Option 2.

forgejo_admin commented

2026-04-10 20:33:38 +00:00

Author

Owner

Correction to review-927-2026-04-10 (BLOCK verdict was based on stale source)

The review agent's BLOCK verdict was based on reading a stale local copy of basketball-api at /home/ldraney/basketball-api, which is currently on feature branch 111-player-visibility-api. That branch predates the addition of the Team.contract_config column.

Verified against origin/main (commit 9598c4d):

# src/basketball_api/models.py:373
class Team(Base):
    ...
# src/basketball_api/models.py:386
    contract_config: Mapped[dict | None] = mapped_column(JSONB, nullable=True)

And on Player:

# src/basketball_api/models.py:279
    contract_overrides: Mapped[dict | None] = mapped_column(JSONB, nullable=True)

Both columns are real on main. The review's claim that "the column doesn't exist" was incorrect — the reviewer happened to check a stale feature branch on my workstation instead of main.

Additional evidence: I successfully queried SELECT id, name, contract_config::text FROM teams WHERE ... against the prod basketball-api Postgres earlier tonight (2026-04-10) and got JSONB results back showing practices, tournaments, monthly_fee_default: 200 for every team currently in the DB. This is real prod data, not hallucinated.

Conclusion: Ticket #422 scope is valid as written. A dev agent cloning fresh from main will see contract_config on the Team model and can satisfy the acceptance criteria as originally scoped.

Applied corrections:

Board item 927 label: type:bug → type:feature (matches the issue body's ### Type Feature header)
Promoting board item 927 from backlog to todo based on this evidence

Non-blocking review feedback accepted:

Label consistency fix applied
Acknowledging the review agent caught a real-enough-sounding issue that it's worth adding a reviewer step: "check origin/main, not just the local working tree" for future code-verification passes

## Correction to review-927-2026-04-10 (BLOCK verdict was based on stale source) The review agent's BLOCK verdict was based on reading a stale local copy of `basketball-api` at `/home/ldraney/basketball-api`, which is currently on feature branch `111-player-visibility-api`. That branch predates the addition of the `Team.contract_config` column. **Verified against `origin/main`** (commit 9598c4d): ```python # src/basketball_api/models.py:373 class Team(Base): ... # src/basketball_api/models.py:386 contract_config: Mapped[dict | None] = mapped_column(JSONB, nullable=True) ``` And on `Player`: ```python # src/basketball_api/models.py:279 contract_overrides: Mapped[dict | None] = mapped_column(JSONB, nullable=True) ``` Both columns are real on main. The review's claim that "the column doesn't exist" was incorrect — the reviewer happened to check a stale feature branch on my workstation instead of main. **Additional evidence**: I successfully queried `SELECT id, name, contract_config::text FROM teams WHERE ...` against the prod basketball-api Postgres earlier tonight (2026-04-10) and got JSONB results back showing practices, tournaments, `monthly_fee_default: 200` for every team currently in the DB. This is real prod data, not hallucinated. **Conclusion**: Ticket #422 scope is valid as written. A dev agent cloning fresh from main will see `contract_config` on the `Team` model and can satisfy the acceptance criteria as originally scoped. **Applied corrections**: - Board item 927 label: `type:bug` → `type:feature` (matches the issue body's `### Type Feature` header) - Promoting board item 927 from `backlog` to `todo` based on this evidence **Non-blocking review feedback accepted**: - Label consistency fix applied - Acknowledging the review agent caught a real-enough-sounding issue that it's worth adding a reviewer step: "check `origin/main`, not just the local working tree" for future code-verification passes

forgejo_admin commented

2026-04-10 20:37:05 +00:00

Author

Owner

Scope Review (pass 3): NEEDS_REFINEMENT (minor)

Review note: review-927-2026-04-10-pass3

Re-verified against origin/main @ 9598c4d with a fresh clone. The prior BLOCK verdict is rescinded — Team.contract_config JSONB and Player.contract_overrides JSONB both exist on main, and migration 034_seed_team_contract_configs.py already defines a LOCAL_CONFIG_16U dict (lines 334-367) that is an exact template for this ticket. story:WS-S23 verified on project-westside-basketball#stories-admin. Premise of the ticket is sound.

All remaining findings are minor ticket-body polish — no architectural blockers. Ticket fits in a single agent pass, under the 5-minute rule.

Refinement list (non-blocking)

Pin migration filename to alembic/versions/040_create_16u_local_queens_team.py with down_revision = "039". Highest current migration is 039_add_recovery_email_sent.py.
Drop the optional migrations/data/16u_local_queens_config.json file target. No top-level migrations/ directory exists on main. The established pattern (see migration 034) is to define the config as an inline Python dict literal in the migration module.
Remove the "Team slug / internal key naming" constraint. The teams table has no slug / internal_key column on main (columns: id, tenant_id, name, division, age_group, coach_id, groupme_group_id, groupme_share_url, contract_config, created_at).
Add acceptance criterion: tenant_id set to the Westside tenant (lookup by name or follow migration 034's precedent of hardcoded ids for the single-tenant deployment).
Clarify coach_id handling — leave NULL until Marcus assigns a coach, or copy from 16U Elite Queens? (Nit.)
Wire the forgejo_url on board item #927 — it is currently empty, so the board does not link to this issue.
Sync board label from type:bug → type:feature on board item #927. Board state is stale relative to the label update noted in the review prompt; the issue body's ### Type: Feature header is correct.

Schema sanity checks (all PASS)

division Enum includes girls ✓
age_group Enum includes U16 (maps to "16U") ✓
contract_config JSONB column exists on Team ✓
LOCAL_CONFIG_16U shape (variant=local, monthly_fee_default=200, empty tournaments, Monday+Friday BWill practices, sections jersey/commitment/communication) is cloneable as-is ✓

Recommendation

Apply refinements 1-5 to the issue body and 6-7 to the board item, then promote to todo. Alternatively, Ava may waive the body refinements and include them as inline instructions in the dev agent prompt — the dev work is trivially small either way.

## Scope Review (pass 3): NEEDS_REFINEMENT (minor) Review note: `review-927-2026-04-10-pass3` Re-verified against `origin/main` @ `9598c4d` with a fresh clone. The prior BLOCK verdict is rescinded — `Team.contract_config` JSONB and `Player.contract_overrides` JSONB both exist on main, and migration `034_seed_team_contract_configs.py` already defines a `LOCAL_CONFIG_16U` dict (lines 334-367) that is an exact template for this ticket. `story:WS-S23` verified on `project-westside-basketball#stories-admin`. Premise of the ticket is sound. All remaining findings are minor ticket-body polish — no architectural blockers. Ticket fits in a single agent pass, under the 5-minute rule. ### Refinement list (non-blocking) 1. **Pin migration filename** to `alembic/versions/040_create_16u_local_queens_team.py` with `down_revision = "039"`. Highest current migration is `039_add_recovery_email_sent.py`. 2. **Drop the optional `migrations/data/16u_local_queens_config.json` file target.** No top-level `migrations/` directory exists on main. The established pattern (see migration 034) is to define the config as an inline Python dict literal in the migration module. 3. **Remove the "Team slug / internal key naming" constraint.** The `teams` table has no `slug` / `internal_key` column on main (columns: `id, tenant_id, name, division, age_group, coach_id, groupme_group_id, groupme_share_url, contract_config, created_at`). 4. **Add acceptance criterion:** `tenant_id` set to the Westside tenant (lookup by name or follow migration 034's precedent of hardcoded ids for the single-tenant deployment). 5. **Clarify `coach_id` handling** — leave NULL until Marcus assigns a coach, or copy from 16U Elite Queens? (Nit.) 6. **Wire the forgejo_url on board item #927** — it is currently empty, so the board does not link to this issue. 7. **Sync board label** from `type:bug` → `type:feature` on board item #927. Board state is stale relative to the label update noted in the review prompt; the issue body's `### Type: Feature` header is correct. ### Schema sanity checks (all PASS) - `division` Enum includes `girls` ✓ - `age_group` Enum includes `U16` (maps to "16U") ✓ - `contract_config` JSONB column exists on Team ✓ - `LOCAL_CONFIG_16U` shape (variant=local, monthly_fee_default=200, empty tournaments, Monday+Friday BWill practices, sections jersey/commitment/communication) is cloneable as-is ✓ ### Recommendation Apply refinements 1-5 to the issue body and 6-7 to the board item, then promote to `todo`. Alternatively, Ava may waive the body refinements and include them as inline instructions in the dev agent prompt — the dev work is trivially small either way.

forgejo_admin referenced this issue from a commit

2026-04-10 20:43:58 +00:00

feat: create 16U Local Queens team (#422)

forgejo_admin referenced this issue from a pull request that will close it,

2026-04-10 20:44:26 +00:00

feat: create 16U Local Queens team (#422) #427

forgejo_admin referenced this issue

2026-04-10 20:47:12 +00:00

fix: dedupe Alice Uwamahoro player rows (#420) #428

forgejo_admin referenced this issue

2026-04-10 22:07:07 +00:00

feat: create 16U Local Queens team (#422) #427