Implement monthly MVP V2 workflow and snapshots

ai/tasks/done/TASK-081-player-event-snapshots-and-api.md

@@ -0,0 +1,81 @@
+# TASK-081-player-event-snapshots-and-api
+
+## Goal
+Exponer por snapshots JSON y API propia del backend las nuevas métricas derivadas V2 de eventos de jugador, manteniendo la filosofía de lectura rápida y desacoplada del request path pesado.
+
+## Context
+La base V2 ya existe:
+- source adapter
+- raw ledger
+- incremental worker
+- derived aggregates
+
+Ahora hace falta convertir esas métricas derivadas en una capa consumible por producto y por futuras fórmulas de MVP V2 sin depender de consultas pesadas on-demand.
+
+Las primeras métricas que deben quedar listas para lectura rápida son:
+- most_killed
+- death_by
+- duel summaries
+- weapon kills
+- teamkills derivados
+
+## Steps
+1. Revisar los agregados V2 ya implementados.
+2. Diseñar snapshots JSON adecuados para estas métricas avanzadas por:
+   - servidor
+   - all-servers cuando aplique
+   - periodo mensual si corresponde
+3. Exponer endpoints claros y consistentes para leer esas métricas.
+4. Mantener la misma filosofía que el histórico actual:
+   - lectura rápida
+   - sin cálculos pesados en el request path
+5. Incluir metadatos claros en los snapshots cuando aplique:
+   - generated_at
+   - period/month_key
+   - source_range_start
+   - source_range_end
+   - found / is_stale si aplica
+6. Integrar la generación de estos snapshots con la operativa existente o con una vía equivalente razonable.
+7. No implementar todavía la UI V2 final.
+8. No romper el MVP V1 ni los snapshots actuales.
+9. Al completar la implementación:
+   - dejar el repositorio consistente
+   - hacer commit
+   - hacer push al remoto si el entorno lo permite
+
+## Files to Read First
+- AGENTS.md
+- backend/README.md
+- backend/app/historical_snapshots.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/player_event_aggregates.py
+- backend/app/player_event_storage.py
+- docs/player-event-pipeline-v2-design.md
+
+## Expected Files to Modify
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/historical_snapshots.py
+- backend/app/historical_snapshot_storage.py
+- backend/README.md
+- opcionalmente nuevos módulos auxiliares si mejoran claridad
+
+## Constraints
+- No recalcular estas métricas pesadas en cada request.
+- No romper la API histórica existente.
+- No tocar todavía la UI final del MVP V2.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en snapshots/API V2.
+
+## Validation
+- Existen snapshots JSON de métricas V2.
+- Existen endpoints backend para leerlas.
+- La lectura es rápida y coherente con la arquitectura actual.
+- No se rompe el MVP V1 ni el histórico actual.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 240 líneas cambiadas.

ai/tasks/done/TASK-082-monthly-mvp-v2-scoring-design-adjustment.md

@@ -0,0 +1,69 @@
+# TASK-082-monthly-mvp-v2-scoring-design-adjustment
+
+## Goal
+Diseñar o ajustar de forma precisa la fórmula del MVP mensual V2 incorporando las nuevas métricas derivadas de eventos de jugador ya disponibles.
+
+## Context
+La V1 del MVP mensual ya existe y se apoya en métricas persistidas básicas. Con la nueva capa V2 de eventos y agregados, ya se pueden plantear señales más ricas como:
+- kills por arma
+- teamkills derivados
+- duelos y rivalidades
+- most_killed / death_by
+- posible ponderación por tipo de kill si la señal es suficientemente fiable
+
+Antes de implementar el backend del MVP V2, hace falta cerrar la fórmula concreta y sus pesos.
+
+## Steps
+1. Revisar el diseño de scoring V1 y la nueva disponibilidad de métricas V2.
+2. Decidir qué métricas avanzadas entran realmente en la V2.
+3. Diseñar una fórmula concreta para el MVP mensual V2, incluyendo:
+   - pesos
+   - elegibilidad
+   - penalizaciones
+   - tratamiento de muestras pequeñas
+   - desempates
+4. Decidir si:
+   - las kills deben ponderarse por arma/tipo
+   - cómo influye teamkill
+   - cómo influye duelo/rivalidad
+   - qué parte de la V1 se mantiene
+5. Mantener la fórmula defendible y explicable, evitando complejidad artificial si la señal aún no es robusta.
+6. Dejar clara la compatibilidad o convivencia entre:
+   - MVP V1
+   - MVP V2
+7. No implementar todavía la UI.
+8. Al completar la implementación:
+   - dejar el repositorio consistente
+   - hacer commit
+   - hacer push al remoto si el entorno lo permite
+
+## Files to Read First
+- AGENTS.md
+- docs/monthly-mvp-ranking-scoring-design.md
+- docs/player-event-pipeline-v2-design.md
+- docs/monthly-player-ranking-data-audit.md
+- backend/README.md
+- backend/app/player_event_aggregates.py
+- cualquier snapshot/API V2 disponible tras la task previa
+
+## Expected Files to Modify
+- docs/monthly-mvp-v2-scoring-design.md
+- opcionalmente docs/decisions.md
+- opcionalmente ai/architecture-index.md
+
+## Constraints
+- No implementar todavía el cálculo backend del MVP V2.
+- No tocar producto visible.
+- No depender de métricas no confirmadas.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en diseño de scoring V2.
+
+## Validation
+- Existe un documento claro con la fórmula V2 propuesta.
+- Quedan definidos pesos, elegibilidad, penalizaciones y desempates.
+- Queda claro qué señales entran realmente en V2.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.

ai/tasks/done/TASK-083-monthly-mvp-v2-backend-calculation.md

@@ -0,0 +1,64 @@
+# TASK-083-monthly-mvp-v2-backend-calculation
+
+## Goal
+Implementar en backend el cálculo mensual del MVP V2 a partir de la fórmula aprobada y de las métricas derivadas V2 ya disponibles por snapshots/agregados.
+
+## Context
+La base V2 ya existe y, tras cerrar el diseño de scoring, hace falta materializar el ranking mensual MVP V2 en backend. Esta versión debe poder convivir con la V1 mientras se valida en producto.
+
+## Steps
+1. Revisar:
+   - scoring V2 aprobado
+   - agregados V2 disponibles
+   - snapshots/API de métricas avanzadas
+2. Implementar el cálculo del ranking mensual MVP V2 por:
+   - servidor
+   - all-servers cuando aplique
+3. Aplicar correctamente:
+   - pesos
+   - elegibilidad
+   - penalizaciones
+   - desempates
+4. Mantenerlo separado del MVP V1.
+5. Preparar el resultado para poder exponerlo después por snapshot/API y, más tarde, por UI.
+6. Documentar la nueva capacidad backend.
+7. No implementar todavía la UI final.
+8. Al completar la implementación:
+   - dejar el repositorio consistente
+   - hacer commit
+   - hacer push al remoto si el entorno lo permite
+
+## Files to Read First
+- AGENTS.md
+- docs/monthly-mvp-v2-scoring-design.md
+- backend/README.md
+- backend/app/player_event_aggregates.py
+- backend/app/historical_storage.py
+- backend/app/payloads.py
+- backend/app/routes.py
+- backend/app/historical_snapshots.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/payloads.py
+- backend/app/routes.py
+- backend/app/historical_storage.py
+- opcionalmente nuevos módulos, por ejemplo:
+  - backend/app/monthly_mvp_v2.py
+  - backend/app/monthly_mvp_v2_scoring.py
+
+## Constraints
+- No romper el MVP V1.
+- No tocar todavía la UI final.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en el cálculo backend del MVP V2.
+
+## Validation
+- Existe un cálculo backend funcional del monthly MVP V2.
+- Soporta servidor y/o all-servers según diseño.
+- Convive con la V1.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 240 líneas cambiadas.

ai/tasks/done/TASK-084-monthly-mvp-v2-snapshots-and-api.md

@@ -0,0 +1,65 @@
+# TASK-084-monthly-mvp-v2-snapshots-and-api
+
+## Goal
+Exponer el ranking mensual MVP V2 mediante snapshots JSON y API propia del backend, manteniéndolo separado del MVP V1 y preparado para una futura UI.
+
+## Context
+Una vez exista el cálculo backend del MVP V2, hace falta integrarlo en la capa de snapshots y API para lectura rápida, sin añadir cálculos pesados al request path.
+
+## Steps
+1. Revisar el cálculo backend del MVP V2.
+2. Diseñar snapshots adecuados para:
+   - MVP V2 por servidor
+   - MVP V2 all-servers si aplica
+3. Exponer endpoints claros y consistentes para leer estos snapshots.
+4. Incluir metadatos útiles:
+   - generated_at
+   - month_key / periodo
+   - found
+   - source_range_start / source_range_end si aplica
+5. Integrar la generación en la operativa existente de snapshots si corresponde.
+6. Mantener la separación explícita entre:
+   - MVP V1
+   - MVP V2
+7. No implementar todavía la UI V2 final en esta task.
+8. Al completar la implementación:
+   - dejar el repositorio consistente
+   - hacer commit
+   - hacer push al remoto si el entorno lo permite
+
+## Files to Read First
+- AGENTS.md
+- backend/README.md
+- backend/app/historical_snapshots.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/historical_runner.py
+- backend/app/config.py
+
+## Expected Files to Modify
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/historical_snapshots.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/historical_runner.py
+- backend/README.md
+- opcionalmente nuevos módulos auxiliares si mejoran claridad
+
+## Constraints
+- No romper snapshots existentes.
+- No mezclar MVP V1 y V2.
+- No tocar todavía la UI final.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en snapshots/API del MVP V2.
+
+## Validation
+- Existen snapshots JSON del MVP V2.
+- Existen endpoints backend para leerlos.
+- La lectura es rápida.
+- MVP V1 y V2 conviven claramente.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 240 líneas cambiadas.