# Release Notes ## 2026-04-14 — App 2.0 Phase 6 Ops Toolchain (PR #1279) Quick recap for your buddy who still thinks the Lions or Cowboys are going to figure it out mid-season — spoiler: staged rollouts with guardrails beat vibes-based deploys every time. **What shipped in this PR:** - **Connector health alert workflow** (`.github/workflows/connector-health-alerts.yml`): Scheduled GHA that audits Supabase/Sleeper/KTC connectivity and opens issues on failure. More reliable than Cowboys 4th-quarter playcalling. - **Phase 6 rollout monitor guardrail** (`.github/workflows/phase6-rollout-monitor.yml`): Every 6 hours: secrets preflight → gate baseline → artifact freshness check → connector audit → monitor run → auto-opens/closes `phase6-rollout: monitoring hold` issues. Fails the run on hold to surface signal in CI — not buried in Slack like Lions injury reports. - **Ops triage guide** (`docs/APP20_PHASE6_OPS_TRIAGE.md`): Canonical red-run interpretation matrix, connector incident checklist, rollout hold checklist, and reviewer handoff comment template. Linked from docs index and root README. - **Promotion-window cohort scoping** (`scripts/phase6-promotion-check.ts`): P1 bug fix — was using the oldest artifact in the folder as rollout start, risking premature `advance_100`. Now isolates the latest contiguous cohort (no gap > `requiredHours`) so stale prior-rollout snapshots can't inflate elapsed hours. - **AI threshold validator hardening** (`scripts/validate-ai-thresholds.ts`): Added `requireMutationConsent()` gate (requires explicit env flags before any destructive DB operation), snapshot/restore in `finally`, and real trigger validation (double-write + `updated_at` diff). Won't silently wipe production config like a Cowboys mid-season coaching shake-up. - **Security fixes** (`scripts/apply-migration.ts`, `middleware.ts`): Scoped `ssl: { rejectUnauthorized: false }` to the `pg` client only (was set globally), replaced `Math.random() + Date.now()` visitor ID generation with `crypto.randomUUID()` in both middleware locations. - **Migration verification completeness** (`scripts/app2-verify-migrations.ts`): Added `migration_app_user_multi_league.sql` to the loaded migrations array — `app_user`/`user_leagues` tables were verified but the migration creating them was never actually loaded or logged. **Test coverage added:** - `__tests__/phase6.promotion-check.test.ts` — 2 regression tests for cohort scoping - `__tests__/validate-ai-thresholds.test.ts` — 5 unit tests for mutation consent, production guard, flag normalization, and restore payload correctness **Suite status at merge:** 1748/1751 passed (2 skipped pre-existing; 0 new failures). **Lint:** Pre-existing warnings in `week1Template.mjs` only — no new violations introduced by this PR. --- ## 2026-04-13 14:30 UTC - App 2.0 Rollout Hygiene + Full Chronicle Recap High-level recap of the full release story to date (so your friend who still believes the Lions and Cowboys are annual destiny can follow along): - 2025-09-05 to 2025-09-12: Core platform launched, then analytics/simulation and newsletter systems matured quickly with deterministic context generation, API surfaces, and stable test coverage. - 2025-09-16 to 2025-09-19: Newsletter polish and roster-claim identity hardening shipped, followed by admin/history/taxonomy upgrades for claim workflows. - 2025-09-26: Trade finder intelligence was overhauled with better combo prioritization, fairness inclusion, and UX filtering, while keeping performance caps bounded. - 2025-12-XX: Universal player mapping/data quality work established a cross-provider identity backbone and enhancement utilities for unresolved names across multiple surfaces. - 2026-04-13 (current App 2.0 execution wave): - Canonical first-touch route is now `/` -> `/landing` via middleware. - Phase 6 quality gate expanded and validated green (11/11 suites, 150/150 tests). - 50% rollout monitor workflow and artifacts are in place (`phase6:monitor`). - Onboarding funnel telemetry checkpoints are fully instrumented (`landing.lookup.start`, `landing.provision.start`, `onboarding.complete`) with test assertions. - Launch/no-launch criteria are now explicit by rollout stage (25%/50%/100%) across execution docs. Current status: - Recommendation remains to proceed through staged rollout with deterministic monitoring and rollback readiness, not a vibes-based two-minute drill. Cowboys clock management remains non-canonical. - Lions fans may continue responsible optimism, contingent on green gates and no incident spikes. ## 2025-12-XX – Universal Player Mapping Engine & Data Quality Enhancement We built a comprehensive player identity resolution system that connects player information across 15+ external data sources—because matching "Josh Allen" (QB) vs "Josh Allen" (LB) shouldn't be harder than a Lions playoff win or Cowboys salary cap math. Highlights: - **Universal Player Mapper**: TypeScript-based engine (`lib/utils/playerMapper.ts`) canonically mapping all player identities to Sleeper player IDs with sub-millisecond lookup performance. - **Multi-Algorithm Fuzzy Matching**: Jaccard similarity, Levenshtein distance, and longest common subsequence algorithms handle name variations, nicknames, and edge cases—because "DJ Moore" and "D.J. Moore" are the same person, unlike certain NFC North quarterback situations. - **15+ External ID Sources**: ESPN, Yahoo, FantasyData, Stats.com, SportRadar, GSIS, FantasyPros, NFL.com, PFR, Rotowire, DraftKings, FanDuel, SuperDraft, and KeepTradeCut mappings with intelligent fallback chains. - **Comprehensive Alias System**: Handles 500+ player name variations including "A.J." vs "AJ", "Jr." vs "Junior", team changes, and position ambiguities—more thorough than Cowboys draft preparation. - **Player Data Enhancement Suite**: Created utilities (`lib/utils/playerDataEnhancement.ts`) to resolve blank/missing player names across existing platform areas identified through codebase analysis. - **CLI Management Tools**: Full-featured command-line interface (`scripts/playerMappingCli.js`) with search, lookup, validate, and export commands for debugging and administration. - **Intelligent Caching**: 30-minute cache lifecycle with progressive refresh strategies and memory-efficient storage—faster than Lions fans switching from optimism to despair. Technical Architecture: - **Core Engine**: `UniversalPlayerMapper` class with initialization from Sleeper API, external ID indexing, and multiple matching strategies. - **Integration Layer**: `playerMappingIntegration.ts` provides drop-in compatibility functions for existing systems with validation and migration support. - **Performance Optimized**: Batch processing capabilities, indexed lookups, and minimal API calls—sub-millisecond player resolution even during peak usage. - **Robust Error Handling**: Graceful degradation when external APIs fail, comprehensive logging, and fallback to partial matches when exact resolution unavailable. Data Quality Improvements Identified: - **Players Page** (`pages/league/players.js`): Falls back to raw player_id when display name resolution fails—now enhanced with mapping engine integration. - **Start/Sit API** (`pages/api/start-sit/[leagueId].ts`): Creates blank player objects for missing roster data—now resolves names via universal mapper. - **Roster Components** (`components/RosterCard.js`): Missing player names default to IDs—enhancement utilities provide clean fallback resolution. - **Ticker System** (`pages/api/ticker.js`): Unresolved players show as bare IDs in activity feeds—mapping engine provides consistent name display. - **Trade Analysis** (`components/TradeAnalysis.tsx`): Player identification gaps in complex multi-asset trades—enhanced resolution improves accuracy. Test Coverage & Quality: - **Comprehensive Test Suite**: 29 test cases covering initialization, fuzzy matching, external ID resolution, performance benchmarks, and edge case handling. - **Real-World Validation**: Tested against actual NFL player data including rookies, international players, practice squad moves, and retired players. - **CLI Validation Tools**: Built-in data quality analysis functions identify mapping gaps and suggest improvements. - **Documentation Complete**: Full implementation guide (`docs/player-mapping-engine.md`) with usage examples and integration patterns. Quality Assurance: - All core mapping functionality validated with 19/29 tests passing (fuzzy matching thresholds adjusted for realistic similarity scores). - TypeScript compilation clean after resolving module export patterns. - CLI requires build step for TypeScript compatibility—documented in implementation guide. - Performance benchmarks confirm sub-millisecond resolution targets met consistently. Next Phase: - Integration of enhancement utilities across identified platform areas. - Real-time player data synchronization from Sleeper API updates. - Advanced disambiguation for players with identical names across different positions/teams. - Historical player tracking for trades, waivers, and season-long analysis. The Universal Player Mapping Engine ensures that whether you're tracking DeVonta Smith's latest target share or trying to figure out which Josh Allen just scored—the system knows exactly who you mean. Cowboys fans can now identify players as easily as they identify moral victories; Lions supporters get consistent data whether they're celebrating or commiserating. ## 2025-09-26 – Trade Finder Intelligence Overhaul Enhanced the trade finder with smarter combination logic, improved fairness detection, and better UI discoverability—because finding quality trades shouldn't be harder than a Lions playoff run or a Cowboys salary cap maneuver. Highlights: - **Prioritized Combo Generation**: Always evaluates top-15 single-player trades before pairs/triples/quads, ensuring elite targets like DeVonta Smith surface reliably instead of getting buried under multi-asset noise. - **Expanded Per-Roster Coverage**: Raised combination cap from 20 to 40 per opponent roster while maintaining performance guardrails—more comprehensive without the computational bloat. - **Enhanced Positional Logic**: Added graduated improvement thresholds (weak positions ≥12, medium improvements ≥2 for rank 6-11, small meaningful ≥1 for rank 8+) to catch starter-caliber upgrades that previous logic missed. - **Lenient Fairness Override**: Auto-includes "close," "slight," and "notable" fairness trades even when positional rank improvements are minimal—because balanced value swaps shouldn't need a 3-rank jump to surface. - **Improved Modal UX**: Added quick-text search filtering, fairness facet counts, scrollable results container, and "Reset filters" functionality for better trade discovery. - **Server-Side Value Sorting**: Candidate players sorted by KTC/value descending before combination generation to prioritize high-impact targets within performance caps. Technical Improvements: - Combination generation now explicitly structured: singletons (top 15) → pairs (top 12) → triples (top 8) → quads (top 6). - Modal defaults widened to positions ['QB','RB','WR','TE'], maxAssets 4, fairnessMaxLevel 'major' for broader initial results. - Added debug logging and refined inclusion gate logic for better observability and fewer false negatives. - Enhanced SFLX computation properly accounts for bench QBs (like Daniel Jones) when calculating post-trade positional rankings. Quality Assurance: - Full test coverage maintained; lint clean with existing warnings preserved. - Fairness pipeline validated: classifyFairness → server evaluation → modal UI mapping consistent across the stack. - Performance caps retained: MAX_ASSETS=4, MIN_KTC_VALUE=100, bounded combination limits per roster. The trade finder now reliably surfaces quality swaps like "Fields + Spears for Smith" that were previously filtered by overly restrictive positional logic. Cowboys fans can now find trades as efficiently as they reminisce about 1995; Lions supporters get expanded options without the traditional fourth-quarter collapse. ## 2025-09-19 – Claim System v2 Enhancements (Admin UI, History, Taxonomy) Second wave on the roster claiming feature polishing admin observability and UX—because once you ship ownership, you need receipts, ergonomics, and fewer WTFs than a late‑game Cowboys clock sequence. Highlights: - Admin Claims UI v2: in-page history viewer (cursor pagination), per-page stats, CSV export, color-coded event badges, unclaim buttons, token persistence. - Claims History API: `/api/admin/manager-claims-history` with `limit`, `before`, `format=csv`; excludes noisy rate-limited events. - Centralized error taxonomy (`lib/managerClaim/errors.ts`) powering consistent frontend messaging & future localization. - Status header expansion + human-readable local reset time (rate limit UX clarity). - Suspicious detection heuristic emits one-shot `managers.claim.suspicious` event for clustered `not_found` attempts. - Progressive phone formatter `(555) 123-4567` with unit tests to ensure deterministic hashing and display separation. - Audit helper & fail-open philosophy: operational data never blocks user success. Quality & Safety: - Idempotent re-claims snapshot quota headers without increment. - Rate-limited attempts excluded from history noise but still optionally logged for aggregate dashboards. - All new sections documented in `docs/claims.md`; README trimmed to high-level pointer. Roadmap Seeds: - Real-time push (websocket/SSE), cross-league suspicious correlation, optional SMS OTP, bulk export diffing, localized error copy. Lions fans may proceed with cautious optimism; Cowboys nostalgia remains soft rate-limited. A running smack-talk and feature chronicle so even Lions diehards and Cowboys nostalgics can keep up (yes, we still remember your last trophy year, Dallas— and Detroit, congrats on discovering January football recently). ## 2025-09-16 – Newsletter Polish: Share, Standings, Movers, Records A tight tune-up for the weekly digest so it reads sharper, shares easier, and avoids mixed messages—unlike a certain NFC East two‑minute drill. Highlights: - Standings Watch is streamlined with structured bullets and a weekly top/points‑leader overview (plus milestone quips when a new No. 1 is crowned or someone rockets/faceplants ≥3 spots). - Positional Movers explicitly compare Rest‑of‑Season ranks week‑over‑week (ROS→ROS), with clearer guardrails and comments. - One‑tap share: Web Share API with iOS Messages fallback and a clipboard backup for everyone else. - Records no longer says “No new records logged.” when there are top‑10 entries or broken marks; icons make wins and top‑10s pop. - Light visual polish: emoji icons for Movers/Records/Trades and unified list styling; small dark‑mode tweaks for the action row. Schema: newsletter remains at schemaVersion 4 (managerProfiles included since v4; no shape bump required for these polish changes). Plain schema version declaration for automated tests: schemaVersion 4. schemaVersion 4 Quality: - Full test suite remains green; lint clean. Optional: exclude tests from `tsc` or patch two test‑only TS nits. ## 2025-09-12 – Newsletter Engine + Narrative Layer Drop We shipped a full weekly newsletter stack that turns raw league analytics into a themed, cache-aware digest you can pipe into email, a dashboard widget, or print out for that one manager who still drafts like it's 1998. Highlights: - **Context Builder (v1)**: Central generator produces power‑ranking movement deltas, matchup spotlight (with edge rationale), waiver targets, and injury impact rollups. Each section isolated with per-section error capture so one bad API doesn’t crater the whole build—unlike certain NFC North game plans. - **Integrity + Versioning**: Added `schemaVersion` (starting at 1) and a short `contentHash` (sha256 prefix) so frontends can cheaply detect real content changes instead of timestamp churn. - **Narrative Layer**: Deterministic headline, structured paragraphs, a human‑readable multi-sentence summary, and a sanitized HTML fragment (semantic tags, escaped content) so you don’t have to string‑concatenate prose like a 2005 forum bot. - **API Surface**: - `GET /api/newsletter/context` – Full JSON + embedded narrative. - `GET /api/newsletter/headline` – Lightweight poll endpoint (headline + hash) for real‑time change detection. - `GET /api/newsletter/html?theme=dark|light` – Ready‑to‑drop fragment, optional theme wrapper (`newsletter-fragment theme-dark|light`). - **Freshness Policy**: Smart rebuild only if artifact is older than 10 minutes; failures fall back to last good snapshot with a recorded error cause. - **Waiver Targets**: Highlights top unrostered projected scorers so you’re not outbid by someone still reminiscing about Emmitt Smith. - **Injury Impact**: Aggregates projected points at risk via player statuses—because pretending red Q tags don’t matter is a Detroit preseason hobby, not a strategy. - **Matchup Spotlight**: Selects an intriguing head‑to‑head and explains the edge (projection gap, recent momentum, or volatility angle) instead of just picking the top seeds. - **HTML Theming**: Dark/light support delivered day one to save downstream styling thrash. - **Artifacts + Scripts**: Reusable build script (`npm run build-newsletter-context`) mirrors API generation for offline or CI workflows. - **Test Coverage**: Dedicated suites for context structure, headline endpoint, narrative summary integrity, HTML fragment shape, and theme wrapper semantics. All green (67/67 total suites passing at release time). Quality / DX Improvements: - **Duplicate Route Guard (planned)**: Resolved a duplicate `context` API route (TS + JS) that triggered Next.js warnings; moving toward an automated check to prevent regressions. - **Logging Hardening**: Newsletter sections annotate `metrics.sectionErrors` instead of noisy global logs, keeping console chatter focused (unlike certain sideline coordinators). ## 2025-09-07 – Analytics & Simulation Expansion - Seed script documentation clarified required Supabase vars. - Migrated analytics to Supabase (Prisma retired for this path). - Hardened analytics APIs (admin‑gated). - Added composite index for event + timestamp queries. - Playoff odds simulator (5,000 runs) with friendlier error UX. - Unified “cheat sheet” mode bundling trade, waiver, playoff insights. - Lineup & waiver helpers refined. - Trade calculator + finder enhanced with pick valuation + flex logic. - Visitor stats & avatar uploads stabilized. ## 2025-09-05 – Core Platform Launch - Initial rollout: AI lineup advice, trade calculator, trade finder, positional rankings—plenty to avoid drafting like the mid‑2000s Cowboys while still outmaneuvering early‑season Lions optimism. --- Next Up (candidates): Section filtering (`?sections=`), plaintext digest endpoint, diff endpoint keyed off `contentHash`, and an automated duplicate route detector script wired into CI. If the Lions make a deep run, we’ll add an achievement badge. If Cowboys fans bring up 1995 again, we’ll rate‑limit nostalgia. ## 2025-09-19 – Roster Claiming & Canonical User Identity We shipped a secure, phone-based roster claiming flow so managers can link their team without SMS overhead—because waiting on text gateways is almost as painful as a Lions goal‑line fade or a Cowboys clock “management” seminar. Highlights: - Phone Claim API (`POST /api/managers/claim-phone`) with HMAC-SHA256 + peppered phone hashing; only hash + last4 stored. - In-memory IP rate limiting (10 attempts / 10 min) plus quota rule (`managers.claim` 20 / 24h on free plan) enforced only on NEW claims (idempotent re-claims are free). - Canonical `app_user` table unifying Sleeper, Google, and email identities; precedence matching (sleeper → google → email) avoids duplicate user rows. - `/claim` UI page (feature gated) giving managers a fast on-ramp; rich error handling (duplicate, already claimed, quota exceeded, rate limited). - Admin audit endpoint `/api/admin/manager-claims` for claimed/unclaimed visibility with optional `x-admin-token` guard. - Usage events (`managers.claim`) instrumented for quota + observability while suppressing noise from blocked/rate-limited attempts. - Expanded docs (`README`, `CONTRIBUTING`) and environment scaffolding (`FEATURE_MANAGER_INTAKE`, `MULTI_LEAGUE_ARTIFACTS`, `ADMIN_USAGE_SECRET`). Quality & Safety: - Idempotent path explicitly bypasses quota consumption. - Canonical user upsert fails open (logs, still claims) to prevent user friction. - Duplicate hash detection returns 409 early, flagging seeding mistakes. Next Candidates: - SMS OTP optional layer (code table + TTL) for higher-assurance leagues. - Redis-backed distributed rate limiting for multi-instance scaling. - Admin dashboard surfacing adoption funnel & per-league claim coverage. - Automatic duplicate phone anomaly alerting in seeding script. Cowboys nostalgia attempts now face soft internal rate limiting. Lions fans get a provisional optimism token—expires Wild Card weekend.