docs: extend roadmap with themed releases

docs/development/roadmap.md

@@ -2,6 +2,14 @@
 
 This roadmap is based on a senior-developer inspection of the current FastAPI, Jinja, and SQLAlchemy codebase.
 
+## Roadmap Execution (GitHub)
+
+This document describes outcomes and acceptance criteria. Execution is tracked in GitHub:
+
+- Umbrella roadmap issue: https://github.com/christianlouis/LeagueLedger/issues/144
+- GitHub milestones track versions (`v0.3.0` → `v1.0.0`).
+- Each version has a release epic (label: `roadmap`) with sub-issues for the scoped work.
+
 ## Current Findings
 
 - LeagueLedger currently treats teams, QR sets, events, redemptions, and leaderboards as global records. That blocks multiple pubs or organizers from sharing one installation cleanly.
@@ -10,11 +18,64 @@ This roadmap is based on a senior-developer inspection of the current FastAPI, J
 - Several workflows still include compatibility branches for removed model names, which makes behavior harder to reason about.
 - QR redemption did not consistently record the redeeming user on the QR code record, weakening auditability.
 
+## Feature Landscape (Themes)
+
+These themes reflect what a modern, operator-friendly loyalty + league product typically needs beyond the foundational multi-league work.
+
+### Foundation & Governance (P0)
+
+- Multi-league operations: league creation, archival, and delegation.
+- Role-based access control (RBAC) and strict data isolation by league.
+- Migration safety and release hygiene (CI, smoke tests, release checklist).
+
+### QR Trust, Fraud Prevention & Auditability (P0/P1)
+
+- Rotating/expiring QR codes, replay protection, and rate limits.
+- Clear redemption audit trails and admin review tooling.
+
+### Engagement, Rewards & Retention (P1)
+
+- Rewards catalog and redemption flow (points → rewards).
+- Seasons (timeboxed leaderboards) and historical archives.
+- Notifications, announcements, and team communication.
+- Optional Apple/Google Wallet passes for “always-on” engagement.
+
+### Integrations & Automation (P1/P2)
+
+- Webhooks + exports as the baseline “integration surface”.
+- Slack/Discord notifications and calendar feeds (ICS).
+- PWA + offline QR scanning to make the mobile experience resilient.
+
+### Analytics, Insights & Reporting (P2)
+
+- Admin reports, retention/cohort analytics, and operational dashboards.
+
+### Platform Extensibility + MCP/AI (P2/P3)
+
+- Public API (read-first) with rate limits and scoped auth.
+- MCP server for safe “tools” (create event, generate QR sets, query stats).
+- Guardrailed AI operator UX built on top of MCP tools.
+
+## Release Plan (GitHub Milestones)
+
+| Version | Focus | Tracking Epic | Target (UTC) |
+| --- | --- | --- | --- |
+| v0.2.0 | Multi-league foundation (shipped) | Release notes: https://github.com/christianlouis/LeagueLedger/releases/tag/v0.2.0 | 2026-05-22 |
+| v0.3.0 | League administration | https://github.com/christianlouis/LeagueLedger/issues/145 | 2026-06-30 |
+| v0.4.0 | Data isolation + RBAC | https://github.com/christianlouis/LeagueLedger/issues/151 | 2026-07-31 |
+| v0.5.0 | Migrations + release hardening | https://github.com/christianlouis/LeagueLedger/issues/156 | 2026-08-31 |
+| v0.6.0 | QR trust + security | https://github.com/christianlouis/LeagueLedger/issues/162 | 2026-09-30 |
+| v0.7.0 | Engagement layer | https://github.com/christianlouis/LeagueLedger/issues/165 | 2026-10-31 |
+| v0.8.0 | Integrations + automation | https://github.com/christianlouis/LeagueLedger/issues/168 | 2026-11-30 |
+| v0.9.0 | Analytics + reporting | https://github.com/christianlouis/LeagueLedger/issues/173 | 2026-12-31 |
+| v1.0.0 | Platform + MCP + AI operator | https://github.com/christianlouis/LeagueLedger/issues/176 | 2027-03-31 |
+
 ## Milestones
 
 ### 1. Multi-League Foundation
 
 Status: implemented in this branch.
+Release: `v0.2.0` (shipped).
 
 Acceptance criteria:
 - Add a `League` model with a default league for existing data.
@@ -25,6 +86,8 @@ Acceptance criteria:
 
 ### 2. League Administration
 
+Release: `v0.3.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/145).
+
 Acceptance criteria:
 - Add a dedicated admin workflow for creating, editing, activating, and archiving leagues.
 - Allow league managers to administer only their own league.
@@ -33,6 +96,8 @@ Acceptance criteria:
 
 ### 3. Data Isolation and Permissions
 
+Release: `v0.4.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/151).
+
 Acceptance criteria:
 - Introduce league-level roles for owners, quiz masters, and staff.
 - Enforce league boundaries in every query that reads or mutates teams, events, QR sets, QR codes, achievements, and leaderboards.
@@ -40,6 +105,8 @@ Acceptance criteria:
 
 ### 4. Migration Cleanup
 
+Release: `v0.5.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/156).
+
 Acceptance criteria:
 - Consolidate schema migrations into one approach.
 - Add repeatable migration tests against a fresh database and a simulated legacy database.
@@ -47,7 +114,62 @@ Acceptance criteria:
 
 ### 5. Release Hardening
 
+Release: `v0.5.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/156).
+
 Acceptance criteria:
 - Add CI checks for syntax, tests, and a lightweight app smoke test.
 - Document local development with 1Password-injected environment secrets.
 - Add a release checklist with migration, rollback, and verification steps.
+
+### 6. QR Trust + Security
+
+Release: `v0.6.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/162).
+
+Acceptance criteria:
+- Support rotating/dynamic QR codes where appropriate (see https://github.com/christianlouis/LeagueLedger/issues/96).
+- Support expiration and scheduling for QR codes (see https://github.com/christianlouis/LeagueLedger/issues/102).
+- Provide QR usage statistics (see https://github.com/christianlouis/LeagueLedger/issues/98).
+- Add a redemption audit trail + admin review workflow.
+- Add anti-fraud controls (rate limits, replay protection, optional constraints) with tests.
+
+### 7. Engagement Layer
+
+Release: `v0.7.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/165).
+
+Acceptance criteria:
+- Rewards catalog primitives and a redemption flow (see https://github.com/christianlouis/LeagueLedger/issues/166).
+- Seasons and controlled leaderboard resets with archives (see https://github.com/christianlouis/LeagueLedger/issues/167).
+- Notifications and team comms are usable and league-scoped (see https://github.com/christianlouis/LeagueLedger/issues/75 and https://github.com/christianlouis/LeagueLedger/issues/92).
+- Wallet passes are available as an opt-in enhancement (see https://github.com/christianlouis/LeagueLedger/issues/180).
+
+### 8. Integrations + Automation
+
+Release: `v0.8.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/168).
+
+Acceptance criteria:
+- Webhook framework exists for core events (see https://github.com/christianlouis/LeagueLedger/issues/169).
+- Slack/Discord notifications are available (see https://github.com/christianlouis/LeagueLedger/issues/170).
+- Calendar feeds (ICS) are available (see https://github.com/christianlouis/LeagueLedger/issues/171).
+- Exports v1 exist for core objects (see https://github.com/christianlouis/LeagueLedger/issues/172).
+- PWA can be installed and supports offline scan queue + sync (see https://github.com/christianlouis/LeagueLedger/issues/181).
+
+### 9. Analytics + Reporting
+
+Release: `v0.9.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/173).
+
+Acceptance criteria:
+- Admin reports exist for key operational views (see https://github.com/christianlouis/LeagueLedger/issues/23).
+- Basic performance/health metrics are tracked (see https://github.com/christianlouis/LeagueLedger/issues/85).
+- Cohort/retention analytics and report templates exist (see https://github.com/christianlouis/LeagueLedger/issues/174 and https://github.com/christianlouis/LeagueLedger/issues/175).
+
+### 10. Platform + MCP + AI Operator
+
+Release: `v1.0.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/176).
+
+Acceptance criteria:
+- Public API v1 exists with scoped auth + rate limits (see https://github.com/christianlouis/LeagueLedger/issues/177).
+- MCP server exists for safe operator tooling (see https://github.com/christianlouis/LeagueLedger/issues/178).
+- AI operator UX uses MCP tools with explicit guardrails (see https://github.com/christianlouis/LeagueLedger/issues/179).
+- Security baseline is in place (see https://github.com/christianlouis/LeagueLedger/issues/64, https://github.com/christianlouis/LeagueLedger/issues/66, https://github.com/christianlouis/LeagueLedger/issues/68).
+- Backup/restore is available (see https://github.com/christianlouis/LeagueLedger/issues/82).
+- API documentation is up to date (see https://github.com/christianlouis/LeagueLedger/issues/104).