FlexTime – Big 12 Scheduling Platform

FLEXTIME-SSOT — always start with docs/FLEXTIME-SSOT.md. every status update, plan, or feature reference must keep that doc current because it is the canonical source.

Unified Dev Stack Quick Commands

• Start full stack (web, API, workers, proxy): pnpm dev:up
• Tail combined container logs: pnpm dev:logs
• Stop the stack: pnpm dev:down
• Rebuild after dependency changes: pnpm dev:rebuild
• Single entry point: http://localhost:4000 (UI and CLI both use the Jobs API here)

Note: UI/UX Process SSOT

• For any UI/UX work, the single source of truth for process and guidance is docs/ui-ux/FT_UI_UX_SINGLE_SOURCE_OF_TRUTH.md. Other docs (AGENTS.md, CLAUDE.md, WARP.md) supplement with agent and workflow specifics.

Agentic Development: TDD‑First (SPARC)

• Default to test‑driven changes: write failing tests, implement, then refactor.
• Frontend uses next/jest with per‑test Supabase/realtime mocks; backend uses Node ESM (Jest 29) via the provided wrapper.
• Keep SportLogic (Supabase competition.sportlogic_v) as the source of truth in tests and code.
• Target ≥85% coverage for new code; document exceptions.

• Schedule‑first IDs (schedule_id) drive every flow; do not touch football/basketball paths without explicit request.

  • See web/.claude/commands/sparc/tdd.md for the workflow.

• Linear required: create/update a Linear issue for every task (schedule_id, impacted paths, acceptance criteria, PR links). Use scripts/linear/* helpers for triage/state transitions.

Commit Messages and Linear

• Include a Linear issue ID (e.g., FLEX-123) in the commit title or body.
• Examples:
  • feat(web): Phase 1 schedule workspace optimizations (FLEX-123)
  • fix(backend): phase2 context lock metrics (TEAM-88)
• Hooks:
  • Enable repo hooks: pnpm hooks:enable
  • Enforce Linear ID in commits (default on): set LINEAR_ENFORCE=0 to bypass.
  • Pre-push Linear transitions: export LINEAR_HOOKS=1.

⚠️ CRITICAL: Missions Deprecated — Schedule-First Architecture
FlexTime is now schedule-first. The legacy "mission" terminology and architecture have been fully deprecated.

• ✅ USE: schedule_id (TEXT) for ALL new development — Format: "SOC-2026", "BSB-2027"
• ❌ DON'T USE: mission_id (DEPRECATED — backward compatibility only)
• 🔄 Terminology: "Artifacts" are deprecated — use "Variants" (scheduling.phase{1,2,3}_variants)
• Migration: ✅ 100% COMPLETE (2025-11-03) — All Phase 1/2/3 routers updated
• Routing: All /api/ft-builder/schedules/* traffic now handled by SchedulesRouter.js
• Legacy Files: MissionsRouter.js and SchedulesV2Router.js are deprecated (NOT mounted)
• Guide: See docs/migrations/MISSIONS_DEPRECATED_SCHEDULES_FIRST.md for complete details

Agent Refactor Rule — Schedule-First: When code references mission/mission_id or artifact/artifactId, refactor to schedule-first terminology: use schedule_id, route under /api/ft-builder/schedules/* with :scheduleId/:variantId, switch DB tables to competition.schedules and scheduling.phase{1,2}_variants, update DTOs/tests, keep legacy reads only, and avoid football/basketball paths unless explicitly requested.

FlexTime is a schedule-first workspace built around the FlexTime two-phase pipeline (matrix → sequence) with optional post-generation optimization. The /flextime/schedules/[scheduleId]/workspace route orchestrates variant generation, optimization, analytics, and agent chat in one place.

AI‑Native Roadmap: see docs/planning/FTB_AI_Native_Roadmap.md for the living plan (Builder Card, Lab Mode, phase-aware tools, HIL apply) with links to specs and source.

Unified Process (Runbook + Agent + SSOT)

FlexTime uses one unified process for all scheduling operations. New features and enhancements must align with all three of the following at all times:

• FlexTime Runbook: docs/operations/runbooks/FT_LAB_RUNBOOK.md
• Standard Scheduling Workflow (canonical flow): docs/operations/runbooks/FT_STANDARD_SCHEDULING_WORKFLOW.md
• Scheduling Process & Orchestration blueprint hub: docs/architecture/orchestration/blueprints/README.md
• Scheduling Orchestrator: src/intelligence/solving/SchedulingOrchestrator.js
• SportLogic Single Source of Truth (SSOT): competition.sportlogic_v and feeder tables in Supabase
• Statsig Feature Management: All FlexTime feature gates, telemetry, and fallback alerts are controlled through Statsig with hybrid env-var fallback; see docs/operations/STATSIG_MIGRATION_GUIDE.md for the audit, gate mapping, and telemetry checklist.

Key rules:

• Always run through the unified pipeline (agent → tools → API). Avoid ad‑hoc scripts that bypass the agent or SSOT.
• Supabase MCP first for any data access or mutation; do not connect by other means.
• Phase 2 for soccer is sequencing‑only when a matrix is selected; hosts/opponents come from the selected matrix and are never changed in Phase 2.
• Schedule‑specific logic (for example, SOC‑2026 AAA start/finish parameters) must be encoded in SSOT and consumed by the Scheduling Orchestrator — not hardcoded.
• Repeated solver fallbacks emit phase1.solver.alert and phase2.solver.alert activity events (with fallback counts/window minutes) so Ops can monitor retry depth, circuit-breaker state, and solver health.

Scoring & Analytics (Unified)

• Unified scoring engine computes a final overall for both phases:
  • Matrix Quality (Phase 1) and Sequence Quality (Phase 2) are driven by the unified engine by default (FTB_SCORING_UNIFIED on).
  • Cumulative Quality is the average of P1 and P2 and is persisted to competition.schedules.metadata.cumulative_quality by the scoring agent.

Conference Reporting & MCP Tooling

• Reports rely on ConferenceReportGenerator + Supabase Storage bucket exports. Use pnpm run storage:create-exports before uploading.
• Generate exports locally:

  curl -X POST http://localhost:4004/api/reports/conference \
    -H "Content-Type: application/json" \
    -d '{"scheduleId":"SOC-2025","options":{"renderCharts":true,"includeHistorical":true,"uploadToStorage":true}}'

• Contract validator (commands + chart renderer): pnpm run reports:validate-contracts (requires SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, SCHEDULE_ID).
• MCP research: configure PERPLEXITY_API_KEY/FTB_MCP_ENABLED. Smoke test via pnpm run mcp:perplexity:smoke. SportLogic explainer uses MCP when enabled (/api/flextime/sportlogic/capabilities).
• CSV templates reflect these labels and now include a "Cumulative Quality:" row.
• Analytics snapshots for published schedules are stored under analytics.*.

Local Analytics with DuckDB

DuckDB provides embedded OLAP analytics for pattern analysis and solver performance tracking. No external account needed - runs entirely locally.

• Status: ✅ Installed & Ready (duckdb-async@1.4.2)
• Implementation: src/services/analytics/DuckDBAnalytics.js
• Setup Guide: docs/operations/DUCKDB_SETUP_GUIDE.md
• Test Script: node scripts/test-duckdb.mjs

Features:

• Pattern quality distribution analysis
• Solver performance trend tracking
• Cross-pattern correlation studies
• Team pair analytics (H/A balance, travel, rest)

Note: DuckDB requires native bindings. See the setup guide for troubleshooting or use the WASM version for instant setup without compilation.

Feature Flags with Statsig

Statsig provides feature flag management, A/B testing, and analytics for gradual rollouts and experimentation. Production-ready SDK integrated with graceful fallbacks.

• Status: ✅ Installed & Ready (statsig-node@6.5.1)
• Implementation: src/services/statsig/StatsigClient.js
• Setup Guide: docs/operations/STATSIG_SETUP_GUIDE.md
• Usage Examples: docs/operations/STATSIG_USAGE_EXAMPLES.md
• Test Script: node scripts/test-statsig.mjs

Features:

• Feature Gates: Boolean flags for gradual rollouts
• Dynamic Configs: Runtime parameters without deployments
• A/B Experiments: Test variants to optimize outcomes
• Event Logging: Track user actions and experiment results

Setup: Get your Server API Key from console.statsig.com and add STATSIG_SERVER_API_KEY to .env.local. The SDK auto-initializes in production/staging environments.

Common commands

# Ingest all published schedules into analytics.* (publication_snapshots, schedule_scores, components, aggregates)
DOTENV_CONFIG_PATH=.env.local pnpm analytics:ingest-published

# Ingest a subset by id
DOTENV_CONFIG_PATH=.env.local pnpm analytics:ingest-published --only SOC-2024,SOC-2025

# Persist cumulative quality for specific schedules (competition.schedules.metadata)
DOTENV_CONFIG_PATH=.env.local pnpm analytics:score-cumulative SOC-2024 SOC-2025

Auto‑ingest on publish

• The publish endpoint (POST /api/flextime/schedules/:scheduleId/publish) now triggers a best‑effort analytics snapshot write after status change.

Solver Defaults (Strongest-by-Default)

• Phase 1 (matrix): Hybrid CP‑SAT → MILP → LNS by default.

  • Entry: SchedulingOrchestrator → SolverTools.proposeMatrix().
  • SSOT preflight required (competition.sportlogic_v); quick‑solve (remote microservice only) is opt‑in via quickSolve: true or FT_SOLVER_PHASE1_MODE=quick.
  • Degree targets and alternation come from SSOT; rotation history is included when available.

• Phase 2 (sequence): Solver‑first with MILP polish when enabled in SSOT.

  • Entry: SchedulingOrchestrator → SolverTools.proposePhase2Sequence() → Phase2Router → OrtoolsClient.solveSequence().
  • SSOT drives rules (e.g., max_home_streak, max_away_streak, enable_milp_polish, milp_time_ms, polish_radius).
  • Soccer P2 is sequencing‑only with H/A locked to the selected matrix.
  • SOC‑2026: enable_milp_polish=true (SSOT) is set to make solver+polish the default for this schedule.

Reality Check (2025-11-04)

⚠️ Missions Deprecated - Schedules Router Consolidated

Migration Status: ✅ 100% COMPLETE (2025-11-03)

• All schedule operations now route through SchedulesRouter.js at /api/ft-builder/schedules/*
• Legacy MissionsRouter.js and intermediate SchedulesV2Router.js are DEPRECATED and NOT mounted
• Backward compatibility maintained via automatic fallback queries in Phase 1/2/3 routers
• See docs/migrations/MISSIONS_DEPRECATED_SCHEDULES_FIRST.md for migration guide

Architecture & Core Pipeline ✅ Working

• src/server.js mounts the modular FlexTime API (src/core/scheduling/api/FTBuilderAPI.refactored.js) and handles Supabase credential formats while ignoring unset feature flags. Preflight, generation, optimization, and analysis are all exposed via the Jobs API.
• Certified schedules write through competition.schedules.id (TEXT) with direct linkage to Phase 1/2 variants (scheduling.phase{1,2}_variants) and draft/published games tables. Publications promote draft → final games via schedule_id.
• Sport orchestrators (soccer, baseball, volleyball, etc.) mirror the two-phase pipeline end-to-end and now feed optional post-generation optimization. Other sports continue to lean on soccer heuristics or stub modules (softball, wrestling) for constraint coverage.

Schedule ID Architecture (Missions DEPRECATED)

Current Architecture (as of 2025-11-04):

• schedule_id (TEXT): The ONLY canonical identifier for ALL schedules
  • Format: "SOC-2026", "BSB-2027", etc.
  • Database: competition.schedules, scheduling.phase{1,2}_variants, competition.draft_games, competition.games
  • Routing: All /api/ft-builder/schedules/* requests handled by SchedulesRouter.js

Legacy (DEPRECATED):

• mission_id: DEPRECATED — historical only
  • Database: scheduling.missions has been removed in current environments
  • Router: MissionsRouter.js and SchedulesRouter.js (deprecated, NOT mounted in FTBuilderAPI)
  • Use: NOTHING in new code — automatic fallback queries provide backward compatibility

Migration Details: See docs/migrations/MISSIONS_DEPRECATED_SCHEDULES_FIRST.md

FT Venues SportLogic Studio 🚧 In Progress

• Frontend: UI mockup exists at /ft-builder/sportlogic/venues with read capability from Supabase tables
• Backend: API endpoints (/api/ft-builder/venues/constraints, /issues, /suggestions/:id/apply, /calendar) are NOT fully implemented
• Current Capability: Frontend can read competition.constraints, scheduling.venue_issues, competition.games but cannot write/update
• Migration Status: Schema 202510010001_ft_venues_infra.sql provisions tables but routes remain stubbed

Sequencing + Stage Context 🚧 In Progress

• Stage lifecycle still relies on StageContextManager with limited week1 -> firstHalf -> full cadence.
• Stage endpoints support initialize/advance/rollback/sign-off operations; websocket broadcast and repair budgets remain backlog items.
• Sequencing timeline UI surfaces current StageContext analytics.
• ⚠️ Sequencing generator still throws object is not iterable on Baseball schedules; use legacy variants until the fallback lands (tracked via FTB-BE-378).

HELiiX Analytics & Storage ✅

• Postseason Bid Potential and travel load analytics persist with Phase 1/2 variants and drive HELiiX Intelligence tiles.
• CSV exports upload to Supabase Storage (scheduling.exports) with signed URLs populated in the workspace file tree and CSV footers.
• Schedule-scoped backfill utility scripts/tools/backfill-heliix-analytics.mjs recomputes site rotation/travel metrics for historical variants and re-links selections on competition.schedules.

Phase 2 Chat & Gantt ✅ Added

• Sequencing Gantt view overlays month games from competition.games with SportLogic windows from competition.sportlogic_v (phase2 scope) and is surfaced inside the schedule workspace work surface (web/app/ft-builder/schedules/[scheduleId]/workspace/components/WorkspaceWorkSurface.tsx).
• Schedule-aware chat assistant (SSE) now lives in the HELiiX/Agent dock of the workspace, driving solver tools via the Vercel AI SDK bridge. Tool definitions remain in src/services/agents/tools/* with proxy route web/app/api/ft-builder/agents/chat/route.ts.
• Runbook: docs/operations/runbooks/phase2-gantt-and-chat.md

Supabase & Data 💾 Working (Required)

• Supabase is mandatory. pnpm supabase:init applies migrations and runs seeders (pnpm supabase:seed:venues, pnpm supabase:seed:baseline, pnpm supabase:seed:rotation)
• Without Supabase access, adapters degrade to stubbed reads with warning logs
• /api/ft-builder/schedules/* endpoints (via SchedulesRouter.js) generate schedules, persist variants, and maintain linkage in competition.schedules
• /api/ft-builder/supabase/drift surfaces migration/seed drift for preflight readiness dashboards.

Phase 1 Solver Mode (Hybrid vs Quick)

• Default mode is Hybrid (CP‑SAT ➜ MILP ➜ LNS) for matrix generation to reduce composite cost (including travel) with minimal drift from baseline.
• Quick‑solve uses only the remote CP‑SAT microservice (faster, no MILP polish).
• Control via:
  • Env: set FT_SOLVER_PHASE1_MODE=quick to prefer quick‑solve; omit or set to any other value to use Hybrid.
  • Per call (programmatic): pass { quickSolve: true } to SolverTools.proposeMatrix(...).
• Both paths require SportLogic SSOT preflight (reads competition.sportlogic_v). Runs fail fast if the view isn’t populated.

Unified Scoring Engine (Phase 1 + Phase 2)

• Default scoring is unified across phases and sport-aware via competition.sportlogic_v.
• Engine: src/core/scheduling/quality/UnifiedScoringEngine.js (used by Phase 1 and Phase 2 when FTB_SCORING_UNIFIED is not off).
• Toggle: set FTB_SCORING_UNIFIED=off to use legacy per-phase scorers.

Environment (AI Chat)

• OPENAI_API_KEY must be set for the chat assistant to function.
• Optional default model: OPENAI_MODEL (default: gpt-5.1-chat-latest).
• Optional UI toggle: NEXT_PUBLIC_FTB_PHASE2_CHAT (set to false to hide the chat panel).

Environment (SportLogic Validator – optional)

External matrix validation can be enabled to enrich Phase 1 status with additional metrics/violations.

• FTB_SPORTLOGIC_VALIDATOR (optional): set to true to enable external validation. Default: false.
• SPORTLOGIC_VALIDATOR_URL (optional): FastAPI validator base URL. Default: http://localhost:5000.
• SPORTLOGIC_VALIDATOR_TIMEOUT_MS (optional): request timeout in milliseconds. Default: 1500.

When enabled, the backend will POST to ${SPORTLOGIC_VALIDATOR_URL}/validate with { sport, season, teams, matrix } and surface the result under status.validator for Phase 1 status endpoints.

UI & Frontend ✅ Working

• The four-panel schedule workspace (/flextime/schedules/[scheduleId]/workspace) unifies Phase 1 matrices, Phase 2 sequencing, HELiiX analytics, and agent chat; panel sizing persists per schedule.
• Workspace left rail surfaces quick actions, schedule activity, and Supabase storage exports; the HELiiX Intelligence dock renders bid optimization, compliance, and quality telemetry sourced from variant analytics JSON.
• Schedule detail view retains publication controls and the download center drawer for operators who prefer the expanded workspace. Phase 3 certification checklists are now informational only; final quality comes from cumulative scoring.
• Navigation has been simplified: all CTAs funnel into the schedule workspace; breadcrumbs phase-hop by mutating the phase query parameter instead of redirecting to separate matrix or sequencing pages.
• Gated/Stubbed: Certification dashboards, publication tooling, variant dashboards, websocket scaffolding remain placeholders.

Analytics & AI 🔮 Aspirational

• Historical Schedule Analytics: Services were removed 2025-10-04 (pipelines never called them outside tests). Restore from git if initiative resumes.
• Knowledge Graph: Feature-flagged (FTB_KG_ENABLED), incomplete implementation - see PROJECT_STATE.md line 15
• AI Enhancement Gameplan: Epics defined in backlog but not started (see Next-Gen AI-Native Plan section)

Testing & Quality ⚠️ Partial

• Automated lint/test harnesses remain unreliable. Jest, Playwright, and TypeScript configs require rehab (see backlog items FTB-OPS-201 and FTB-UI-005)
• The web workspace TypeScript check (pnpm --filter web type-check) is green - use as lightweight validation while Jest/Playwright work continues
• Legacy Phase 3 smoke tests are archived; certification now relies on cumulative schedule scoring (analysis.cumulative) plus publication checks.

If you are onboarding, treat the older documentation as a roadmap, not as proof of what works.

Repository Layout

src/                   Express backend + scheduling engines
  core/scheduling/     FlexTime engine, StageContextManager, sport orchestrators
    api/schedulesV2/   ✅ ACTIVE: Schedule-first router (replaces MissionsRouter)
    api/missions/      ❌ DEPRECATED: Legacy MissionsRouter (not mounted)
    api/schedules/     ❌ DEPRECATED: Intermediate SchedulesRouter (not mounted)
    agents/            HistoricalScheduleAnalyzer for AI-powered schedule analysis
  services/
    database/          Supabase helpers, SupabaseAnalyticsAdapter for analytics
    analytics/         (legacy analytics services removed 2025-10-04)
web/                   Next.js 14 frontend (FlexTime command center)
docs/SPARC/            Phase blueprints (now annotated with reality checks)
  migrations/          Migration guides including MISSIONS_DEPRECATED_SCHEDULES_FIRST.md
  analytics/           Historical schedule analysis integration guide
data/migrations/      (deprecated) legacy SQL removed from active workflow
scripts/               Dev helpers and one-off prototypes
  tools/               Supabase bootstrap + seed utilities (`pnpm supabase:*`)
tests/                 Test suites (Jest + comprehensive analytics TDD coverage)

Getting Started Locally

1. Environment files

   cp .env.example .env
   cp .env.local.example .env.local  # create if it is missing

   Supply real Supabase service credentials (SUPABASE_URL, SUPABASE_SERVICE_KEY, SUPABASE_SECRET). Most API calls fail without them.

2. Install dependencies

   pnpm install
   cd web && pnpm install

3. Run services (unified dev)

   • One command: pnpm dev:up (api + web + worker + proxy).
   • Single entry: http://localhost:4000 (proxies /api and /jobs to backend).
   • Direct (optional): backend http://localhost:4004, frontend http://localhost:4003.

   See: docs/operations/dev-environment.md for details.

4. Seed data

   pnpm supabase:init

   • The init script applies SQL migrations when a PostgreSQL connection string is available and then runs the venues/baseline/rotation seeders. Use pnpm supabase:init -- --dry-run to preview actions or --skip-migrations/--skip-seeds to target a subset.
   • Dedicated helpers (pnpm supabase:seed:venues, pnpm supabase:seed:baseline, pnpm supabase:seed:rotation) still exist for ad-hoc re-seeding.

• FlexTime tooling seeds: pnpm supabase:seed:export-audit-log, pnpm supabase:seed:feature-flags, pnpm supabase:seed:activity-events, and pnpm supabase:seed:notifications (idempotent).
• The scripts provide deterministic baselines for soccer/baseball/softball. Other sports still depend on manual data entry.

Working with the Backend

• Entry point: src/server.js wires Express, middleware, and the FlexTime API.
• Engine: src/core/scheduling/core/engine/FTBuilder.js hosts orchestration glue for FlexTime scheduling flows. Many features are placeholders; read before relying on them.
• Schedule Router: src/core/scheduling/api/schedules/SchedulesRouter.js handles ALL schedule operations (replaces deprecated MissionsRouter)
• Stage management: src/core/scheduling/core/phase2/StageContextManager.js keeps stage seeds/locks in memory and mirrors them to Supabase when possible.
• Soccer pipeline (the only complete Phase 1-2 example) lives under src/core/scheduling/sports/soccer/pipeline/.
• Database helpers: src/services/database/SupabaseAdapter.js and friends require service-role access; they fall back to empty data when tables are missing.

Frontend Notes

• FlexTime workspace entry: web/app/flextime/page.tsx with controller logic in web/hooks/use-flextime-controller.ts.
• Matrix panel, Matrix Orchestration, variant list, CSV export button, sequencing timeline, and StageContext controls are live. Certification dashboards, publication flows, variant dashboards, and websocket scaffolding remain gated or stubbed.
• schoolOperations (in web/lib/supabase.ts) hydrates team logos/colors straight from competition.schools so Phase 1 components display real branding when Supabase credentials are present and degrade gracefully when mocks are enabled.
• Tailwind + shadcn are installed; pnpm lint and pnpm type-check inside web/ currently emit errors until FTB-OPS-201 restores the harness.

Testing & Tooling

• Jest, Playwright, and TypeScript pipelines are in flux. Expect pnpm test, pnpm --filter web test, and lint/type-check scripts to fail until FTB-OPS-201 lands and FTB-UI-005 backfills smoke tests.
• Manual smoke validation (lint subsets, targeted API calls, basic UI flows) remains the recommended stopgap.
• CI workflows under scripts/ci/ are placeholders; do not rely on automation until the harness is rebuilt.

Documentation

• UI/UX bundle: see docs/ui-ux/ for the Flow Design map, design-to-implementation mapping, brainstorming canvas, and button showcase references.

The SPARC documents inside docs/SPARC/ outline the intended architecture by phase. Each now opens with a "Reality Check" section describing what currently ships. The implementation backlog (docs/planning/FLEXTIME_BACKLOG.md) tracks ticket-level progress and dependencies; keep it in sync when statuses change. For day-to-day setup, refer to docs/onboarding/FTBuilder_Onboarding.md, for the consolidated FlexTime smoke guidance see docs/operations/runbooks/flextime-smoke-runbook.md, and for feature flag operations see docs/deployment/feature-flags.md.

AI‑Native Roadmap

• docs/planning/FTB_AI_Native_Roadmap.md — living overview of the AI‑native plan (Builder Card, Lab Mode, phase‑aware tools, HIL apply) with links to specs and code.

Contributing

1. Capture your changes in CLAUDE.md and update PROJECT_STATE.md.
2. Validate commands locally (lint, tests) once the harnesses are repaired.
3. Prefer incremental PRs that land Supabase seeds, API refactors, or UI gating one piece at a time.

---

Questions? Open an issue or drop notes in CLAUDE.md for the next operator.

Quick Utilities

• One-command API smoke (start → smoke → stop):
  • PORT_OVERRIDE=4011 ./scripts/tools/smoke-api-cycle.sh
• Validate schedule quality snapshots:
  • SCHEDULE_ID=<id> node scripts/tools/check-quality-snapshots.js
• Backfill quality metadata (if migrating legacy data):
  • pnpm supabase:backfill:quality-schedule-id
• Seed + test notifications:
  • pnpm supabase:seed:notifications
  • FT_BUILDER_NOTIFICATIONS=true FLEXTIME_ENV=development node scripts/tools/test-notification-dispatch.js

See: docs/operations/runbooks/quality-telemetry-and-notifications.md for details.

Latest Update — 2025-11-04 (Phase 2 export ordering + mirroring)

• Baseball sequencing CSV exports standardized
  • Canonical column order (pods by lowest sport id): ARIZ, ASU, BYU, UTAH, BU, UH, TCU, TTU, KU, KSU, OSU, UCF, CIN, WVU.
  • Team code synonyms normalized (e.g., AZ/U OF A → ARIZ, UU/UT → UTAH, UC/CINCINNATI → CIN).
  • Concept exports now mirror the selected variant’s week anchors (Week 1..10, chronological dates). If solver weeks are absent, we bin unique dates across 10 weeks deterministically.
  • Guarantee at most one series per team per week (overflow rebalanced to nearest open week).
• SportLogic calendar respected in sequencing
  • Reader falls back to sport‑level + global rows when schedule‑level rows are empty.
  • Date placement helpers honor a March→May cadence for baseball when calendar is missing.
• Touched files (high‑level)
  • scripts/templates/export-sequence-template-from-variant.mjs
  • scripts/templates/export-sequence-template-from-draft.mjs
  • src/core/scheduling/api/phase2/Phase2Router.js (canonical order + calendar helper)
  • src/services/agents/tools/sport-logic-reader.js (global + sport fallback)
• Ops docs updated
  • docs/operations/runbooks/agents/BSB_RUNBOOK.md and .../SPORTLOGIC_SOLVER_AGENT_RUNBOOK.md now document export order, code normalization, and week mirroring.