feat: persist and diagnose scoreboard correlation candidates

ai/tasks/done/TASK-147-persist-scoreboard-list-candidates.md

@@ -1,7 +1,7 @@
 ---
 id: TASK-147
 title: Persist public scoreboard list matches as RCON candidates
-status: pending
+status: done
 type: backend
 team: Backend Senior
 supporting_teams:
@@ -157,6 +157,42 @@ outcome.
 Document validation, candidate upsert decisions, counters added to the JSON
 report, and any follow-up task instead of widening this task.
 
+- Persisted list payload candidates before detail fetch through a focused
+  PostgreSQL upsert for `rcon_scoreboard_match_candidates`.
+- Built list candidate URLs only from the trusted scoreboard origin catalog and
+  numeric public match IDs. List rows are accepted only when the selected
+  historical server slug/base URL/server number and payload `server_number`
+  agree with the trusted origin.
+- Kept detail fetching for the existing `historical_*` match/player enrichment
+  path. The backfill report now exposes `list_candidates_inserted`,
+  `list_candidates_updated` and `list_candidates_skipped` independently from
+  the detail match counters.
+- Added focused regression coverage for the Foy list row `1562115`; detail
+  fetch failure still leaves the list candidate present, and a second run
+  updates the same candidate key instead of creating a duplicate.
+- Validation:
+  - `python -m compileall backend/app`
+  - `python -m unittest discover -s tests -p "*scoreboard*"` from `backend/`
+    passed with pre-existing SQLite `ResourceWarning` output in the scoreboard
+    regression file.
+  - `python -m app.storage_diagnostics` from `backend/`
+  - `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+    passed; the script reports no product integration tests configured for its
+    platform-only scope.
+  - `docker compose --profile advanced up -d --build backend frontend postgres`
+  - `docker compose exec backend python -m app.scoreboard_candidate_backfill
+    --server comunidad-hispana-02 --from 2026-05-20T00:00:00Z --to
+    2026-05-21T23:59:59Z --max-pages 5 --page-size 100`
+    reported list candidate inserts/updates with no errors.
+  - Queried PostgreSQL and verified external match id `1562115` exists for
+    `comunidad-hispana-02` with URL
+    `https://scoreboard.comunidadhll.es:5443/games/1562115`.
+  - Invoked `/api/historical/matches/detail` for
+    `comunidad-hispana-02:1779310451:1779315851:foywarfare`; payload `found`
+    was true and `match_url` used the expected trusted URL.
+- Scope review used `git diff --name-only`; changed implementation files stay
+  within this task plus this workflow task file.
+
 ## Change Budget
 
 - Prefer fewer than 5 modified files.

ai/tasks/done/TASK-148-relink-existing-rcon-matches-to-scoreboard-candidates.md

@@ -1,7 +1,7 @@
 ---
 id: TASK-148
 title: Relink existing RCON matches to scoreboard candidates
-status: pending
+status: done
 type: backend
 team: Backend Senior
 supporting_teams:
@@ -155,6 +155,47 @@ Document correlation scoring choices, time-window derivation, ambiguity
 handling, relink command output, validation, and any follow-up task instead of
 expanding scope.
 
+- Added `python -m app.rcon_scoreboard_relink` to scan already-materialized
+  ended RCON matches against the same trusted candidate resolution used by the
+  detail read model. The command reports `matches_scanned`,
+  `candidates_scanned`, `matches_linked`, `matches_skipped_no_candidate`,
+  `matches_skipped_ambiguous` and `errors` as JSON.
+- Kept URL availability dynamic in the read model instead of adding a second
+  persisted URL column to RCON matches. The new correlation resolution summary
+  preserves the existing deterministic map/time/duration/score scoring path,
+  returns explicit low-confidence/no-candidate/ambiguous reasons, and exposes
+  the selected external candidate only to command callers.
+- Reused the existing materialized window derivation for closed-at plus
+  server-time duration cases so relink and detail payloads evaluate the same
+  effective correlation window.
+- Added a Foy regression for materialized match key
+  `comunidad-hispana-02:1779310451:1779315851:foywarfare`: relink reports a
+  safe link and detail returns
+  `https://scoreboard.comunidadhll.es:5443/games/1562115`.
+- Validation:
+  - `python -m compileall backend/app`
+  - `python -m unittest discover -s tests -p "*scoreboard*"` from `backend/`
+    passed with existing SQLite `ResourceWarning` output in the scoreboard
+    regression file.
+  - `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+    passed; the script reports no product integration tests configured for its
+    platform-only scope.
+  - `docker compose --profile advanced up -d --build backend frontend postgres`
+  - Re-ran `app.scoreboard_candidate_backfill` for the requested May 20-21
+    window. Candidate refresh succeeded (`list_candidates_updated: 11`), while
+    detail enrichment returned a partial status because SQLite reported
+    `database is locked` for detail match `1562104`.
+  - `docker compose exec backend python -m app.rcon_scoreboard_relink --server
+    comunidad-hispana-02` reported 19 scanned matches, 13 linked matches, 6
+    no-candidate skips, 0 ambiguous skips and no errors.
+  - HTTP detail verification returned `found: true` and the expected Foy URL.
+    Existing Carentan detail key
+    `comunidad-hispana-02:1779178461:1779183861:carentanwarfare` also kept a
+    trusted `match_url`.
+- Scope review used `git diff --name-only`; relink changes stay within the
+  correlation/read-model command path, focused scoreboard tests and this task
+  file.
+
 ## Change Budget
 
 - Prefer fewer than 5 modified files.

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

@@ -1,7 +1,7 @@
 ---
 id: TASK-149
 title: Add scoreboard correlation diagnostics
-status: pending
+status: done
 type: backend
 team: Backend Senior
 supporting_teams:
@@ -139,6 +139,42 @@ Document diagnostic fields, known Foy output behavior, documentation added,
 validation performed, and any follow-up task instead of expanding normal UI
 payloads.
 
+- Added `python -m app.scoreboard_correlation_diagnostics` for one
+  materialized RCON match. JSON output includes match key, server, map,
+  timestamps, duration, score, candidate search window, safe top candidates,
+  selected candidate and `final_reason`.
+- Candidate summaries expose trusted public `match_url` values only. Untrusted
+  URLs are omitted and receive `unsafe-url`; non-scoring candidates report
+  `map-or-window-mismatch` where applicable.
+- Kept diagnostics out of normal detail and frontend payloads. The command
+  reuses the materialized correlation window and safe candidate scoring that
+  relink/detail use.
+- Added `docs/scoreboard-correlation-debugging.md` with the missing-button
+  sequence: candidate backfill, relink scan, diagnostics command and detail
+  endpoint check.
+- Extended focused Foy coverage so diagnostics select external match id
+  `1562115` with the expected Foy candidate summary.
+- Validation:
+  - `python -m compileall backend/app`
+  - `python -m unittest discover -s tests -p "*scoreboard*"` from `backend/`
+    passed with existing SQLite `ResourceWarning` output in the scoreboard
+    regression file.
+  - `python -m app.scoreboard_correlation_diagnostics --server
+    comunidad-hispana-02 --match
+    comunidad-hispana-02:1779310451:1779315851:foywarfare` from `backend/`
+    returned `final_reason: linked` and selected candidate `1562115`.
+  - `python -m app.storage_diagnostics`
+  - `node --check frontend/assets/js/historico-partida.js`
+  - `node --check frontend/assets/js/historico.js`
+  - `node --check frontend/assets/js/historico-recent-live.js`
+  - `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+    exited successfully after reporting its platform checks. Its later local
+    route probe printed a SQLite `database disk image is malformed` traceback
+    from `historical_storage`; this task did not alter or repair runtime DB
+    files.
+- Scope review used `git diff --name-only`; diagnostics changes stay in the
+  correlation command/test/doc path and this task file.
+
 ## Change Budget
 
 - Prefer fewer than 5 modified files.