chore: add scoreboard correlation tasks

ai/tasks/pending/TASK-149-scoreboard-correlation-diagnostics.md

@@ -0,0 +1,146 @@
+---
+id: TASK-149
+title: Add scoreboard correlation diagnostics
+status: pending
+type: backend
+team: Backend Senior
+supporting_teams:
+  - PM
+roadmap_item: rcon-full-data
+priority: medium
+---
+
+# TASK-149 - Add scoreboard correlation diagnostics
+
+## Goal
+
+Make missing scoreboard links diagnosable without exposing debug clutter in the
+normal UI.
+
+## Background
+
+When the Foy match had `match_url` null, investigation required manual
+inspection of public pages, candidate tables, and historical tables. Backend
+diagnostics should explain whether:
+
+- no candidates exist
+- candidates exist but map/time/score mismatch
+- candidates were ambiguous
+- candidate URL was unsafe
+- relink was not run
+
+The known Foy diagnostic target is:
+
+- server: `comunidad-hispana-02`
+- RCON match key:
+  `comunidad-hispana-02:1779310451:1779315851:foywarfare`
+- expected candidate when available: external match id `1562115`
+
+## Constraints / DO NOT BREAK
+
+- Do not add visible debug text to `historico-partida.html`.
+- Do not add timeline/source/debug metadata back to normal UI.
+- Do not change recent card layout.
+- Do not require internet for unit tests.
+- Use fixtures/mocks for tests.
+
+## Allowed Changes
+
+- A focused backend scoreboard correlation diagnostic command.
+- Existing backend correlation/read helpers only when needed to reuse safe
+  candidate selection output.
+- Focused backend tests using fixtures or mocks.
+- Documentation explaining the missing-scoreboard-button debug sequence.
+- This task file when it moves through the task workflow.
+
+## Implementation Requirements
+
+1. Add backend diagnostic capability for a given RCON match:
+   - preferred command:
+     `python -m app.scoreboard_correlation_diagnostics --server comunidad-hispana-02 --match comunidad-hispana-02:1779310451:1779315851:foywarfare`
+   - optional alternative: also expose it inside `storage_diagnostics`, but
+     never in normal frontend payloads
+2. Diagnostic output must be JSON.
+3. Include:
+   - `rcon_match_key`
+   - `server`
+   - `map`
+   - `started_at` / `ended_at` / `closed_at` / `duration_seconds`
+   - score
+   - candidate search window
+   - `candidate_count`
+   - top candidate summaries:
+     - `external_match_id`
+     - `started_at`
+     - `ended_at`
+     - map
+     - score
+     - `match_url`
+     - `correlation_score`
+     - `rejection_reason` if rejected
+   - `selected_candidate` if any
+   - `final_reason`
+4. Add a specific diagnostic for the known Foy case.
+5. Add docs explaining how to debug a missing scoreboard button:
+   - run `scoreboard_candidate_backfill`
+   - run relink
+   - run `scoreboard_correlation_diagnostics`
+   - inspect detail endpoint
+6. Keep diagnostics out of normal UI.
+7. Do not emit raw sensitive data.
+8. Do not emit unsafe URLs.
+
+## Files to Read First
+
+- `AGENTS.md`
+- `ai/architecture-index.md`
+- `ai/repo-context.md`
+- `ai/orchestrator/backend-senior.md`
+- `backend/app/rcon_historical_read_model.py`
+- Backend correlation/relink code delivered by TASK-148.
+
+## Expected Files to Modify
+
+- One backend diagnostic command module or the existing diagnostics module.
+- Existing safe correlation/read helper files only if necessary.
+- Focused backend diagnostic tests using fixtures/mocks.
+- One focused documentation file for the debug workflow.
+- This task file after moving it through the workflow.
+
+Do not add frontend debug surfaces or widen the normal detail payload for this
+task.
+
+## Validation
+
+- `python -m compileall backend/app`
+- `python -m app.scoreboard_correlation_diagnostics --server comunidad-hispana-02 --match comunidad-hispana-02:1779310451:1779315851:foywarfare`
+- `python -m app.storage_diagnostics`
+- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+- `node --check frontend/assets/js/historico-partida.js`
+- `node --check frontend/assets/js/historico.js`
+- `node --check frontend/assets/js/historico-recent-live.js`
+- Review `git diff --name-only` and confirm the changed files match this task.
+
+## Manual Verification
+
+1. Run diagnostics for Foy and verify it explains why `1562115` is selected or
+   why no candidate is selected.
+2. Run diagnostics for a match without public candidate and verify it explains
+   no candidates found.
+3. Normal frontend pages do not show diagnostics.
+
+## Commit Message
+
+`chore: add scoreboard correlation diagnostics`
+
+## Outcome
+
+Document diagnostic fields, known Foy output behavior, documentation added,
+validation performed, and any follow-up task instead of expanding normal UI
+payloads.
+
+## Change Budget
+
+- Prefer fewer than 5 modified files.
+- Prefer changes under 200 lines when feasible.
+- Split follow-up work into a new task if the scope grows.