Upgrade World Cup app with live knockout predictions

.github/workflows/result-check.yml

@@ -51,14 +51,23 @@ jobs:
         run: |
           echo "result_provider=${{ steps.fetch.outputs.provider }}" >> "$GITHUB_STEP_SUMMARY"
           echo "result_changes=${{ steps.fetch.outputs.changed }}" >> "$GITHUB_STEP_SUMMARY"
+      - name: Refresh knockout bracket
+        id: knockout
+        run: |
+          PYTHONPATH=src python scripts/build_knockout_snapshot.py --output /tmp/knockout.json
+          if [ ! -f data/world_cup_2026/knockout.json ] || ! cmp -s <(jq -S '.matches' data/world_cup_2026/knockout.json) <(jq -S '.matches' /tmp/knockout.json); then
+            cp /tmp/knockout.json data/world_cup_2026/knockout.json
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
       - name: Apply audited update
         if: steps.fetch.outputs.changed == 'true'
         run: |
           PYTHONPATH=src python scripts/update_snapshot.py \
-            --results-file "${{ steps.fetch.outputs.output }}" \
-            --allow-corrections
+            --results-file "${{ steps.fetch.outputs.output }}"
       - name: Verify candidate snapshot
-        if: steps.fetch.outputs.changed == 'true'
+        if: steps.fetch.outputs.changed == 'true' || steps.knockout.outputs.changed == 'true'
         run: |
           PYTHONPATH=src python scripts/health_check.py --ignore-overdue-results
           PYTHONPATH=src:. pytest
@@ -69,12 +78,13 @@ jobs:
           python - <<'PY'
           import json, os
           path = os.environ["UPDATE_PATH"]
-          data = json.load(open(path))
+          data = json.load(open(path)) if path and os.path.exists(path) else {}
           with open("/tmp/result-pr.md", "w") as out:
-              out.write("Automated football-data.org result update.\n\n")
+              out.write("Automated World Cup result and bracket update.\n\n")
               out.write(f"- Additions: {len(data.get('results', []))}\n")
               out.write(f"- Corrections requiring review: {len(data.get('corrections', []))}\n")
-              out.write(f"- Raw response SHA-256: `{data['raw_response_sha256']}`\n")
+              if data.get("raw_response_sha256"):
+                  out.write(f"- Raw response SHA-256: `{data['raw_response_sha256']}`\n")
               for row in data.get("results", []):
                   out.write(f"- Add `{row['fixture_id']}`: {row['home']} {row['home_goals']}-{row['away_goals']} {row['away']}\n")
               for row in data.get("corrections", []):
@@ -83,7 +93,7 @@ jobs:
         env:
           UPDATE_PATH: ${{ steps.fetch.outputs.output }}
       - name: Open or update result PR
-        if: steps.fetch.outputs.changed == 'true'
+        if: steps.fetch.outputs.changed == 'true' || steps.knockout.outputs.changed == 'true'
         uses: peter-evans/create-pull-request@v8
         with:
           branch: automation/wc2026-results
@@ -96,3 +106,4 @@ jobs:
             data/world_cup_2026/snapshot.json
             data/world_cup_2026/backups/*.json
             data/world_cup_2026/result_updates/*.json
+            data/world_cup_2026/knockout.json

data/world_cup_2026/knockout.json

@@ -0,0 +1,456 @@
+{
+  "schema_version": "knockout-v1",
+  "provider": "espn",
+  "fetched_at": "2026-07-15T08:20:39.965447+00:00",
+  "raw_response_sha256": "9e17cb0dc49d288141a75ff811230eed51726f60198351418989305596097cbc",
+  "matches": [
+    {
+      "fixture_id": "WC26-073",
+      "match_number": 73,
+      "stage": "round_of_32",
+      "date": "2026-06-28",
+      "kickoff_utc": "2026-06-28T19:00:00+00:00",
+      "home": "South Africa",
+      "away": "Canada",
+      "home_goals": 0,
+      "away_goals": 1,
+      "winner": "Canada",
+      "provider_match_id": "760486",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-074",
+      "match_number": 74,
+      "stage": "round_of_32",
+      "date": "2026-06-29",
+      "kickoff_utc": "2026-06-29T17:00:00+00:00",
+      "home": "Brazil",
+      "away": "Japan",
+      "home_goals": 2,
+      "away_goals": 1,
+      "winner": "Brazil",
+      "provider_match_id": "760487",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-075",
+      "match_number": 75,
+      "stage": "round_of_32",
+      "date": "2026-06-29",
+      "kickoff_utc": "2026-06-29T20:30:00+00:00",
+      "home": "Germany",
+      "away": "Paraguay",
+      "home_goals": 1,
+      "away_goals": 1,
+      "winner": "Paraguay",
+      "provider_match_id": "760489",
+      "provider_status": "STATUS_FINAL_PEN"
+    },
+    {
+      "fixture_id": "WC26-076",
+      "match_number": 76,
+      "stage": "round_of_32",
+      "date": "2026-06-30",
+      "kickoff_utc": "2026-06-30T01:00:00+00:00",
+      "home": "Netherlands",
+      "away": "Morocco",
+      "home_goals": 1,
+      "away_goals": 1,
+      "winner": "Morocco",
+      "provider_match_id": "760488",
+      "provider_status": "STATUS_FINAL_PEN"
+    },
+    {
+      "fixture_id": "WC26-077",
+      "match_number": 77,
+      "stage": "round_of_32",
+      "date": "2026-06-30",
+      "kickoff_utc": "2026-06-30T17:00:00+00:00",
+      "home": "Ivory Coast",
+      "away": "Norway",
+      "home_goals": 1,
+      "away_goals": 2,
+      "winner": "Norway",
+      "provider_match_id": "760490",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-078",
+      "match_number": 78,
+      "stage": "round_of_32",
+      "date": "2026-06-30",
+      "kickoff_utc": "2026-06-30T21:00:00+00:00",
+      "home": "France",
+      "away": "Sweden",
+      "home_goals": 3,
+      "away_goals": 0,
+      "winner": "France",
+      "provider_match_id": "760492",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-079",
+      "match_number": 79,
+      "stage": "round_of_32",
+      "date": "2026-07-01",
+      "kickoff_utc": "2026-07-01T02:00:00+00:00",
+      "home": "Mexico",
+      "away": "Ecuador",
+      "home_goals": 2,
+      "away_goals": 0,
+      "winner": "Mexico",
+      "provider_match_id": "760491",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-080",
+      "match_number": 80,
+      "stage": "round_of_32",
+      "date": "2026-07-01",
+      "kickoff_utc": "2026-07-01T16:00:00+00:00",
+      "home": "England",
+      "away": "DR Congo",
+      "home_goals": 2,
+      "away_goals": 1,
+      "winner": "England",
+      "provider_match_id": "760495",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-081",
+      "match_number": 81,
+      "stage": "round_of_32",
+      "date": "2026-07-01",
+      "kickoff_utc": "2026-07-01T20:00:00+00:00",
+      "home": "Belgium",
+      "away": "Senegal",
+      "home_goals": 3,
+      "away_goals": 2,
+      "winner": "Belgium",
+      "provider_match_id": "760493",
+      "provider_status": "STATUS_FINAL_AET"
+    },
+    {
+      "fixture_id": "WC26-082",
+      "match_number": 82,
+      "stage": "round_of_32",
+      "date": "2026-07-02",
+      "kickoff_utc": "2026-07-02T00:00:00+00:00",
+      "home": "United States",
+      "away": "Bosnia and Herzegovina",
+      "home_goals": 2,
+      "away_goals": 0,
+      "winner": "United States",
+      "provider_match_id": "760494",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-083",
+      "match_number": 83,
+      "stage": "round_of_32",
+      "date": "2026-07-02",
+      "kickoff_utc": "2026-07-02T19:00:00+00:00",
+      "home": "Spain",
+      "away": "Austria",
+      "home_goals": 3,
+      "away_goals": 0,
+      "winner": "Spain",
+      "provider_match_id": "760497",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-084",
+      "match_number": 84,
+      "stage": "round_of_32",
+      "date": "2026-07-02",
+      "kickoff_utc": "2026-07-02T23:00:00+00:00",
+      "home": "Portugal",
+      "away": "Croatia",
+      "home_goals": 2,
+      "away_goals": 1,
+      "winner": "Portugal",
+      "provider_match_id": "760496",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-085",
+      "match_number": 85,
+      "stage": "round_of_32",
+      "date": "2026-07-03",
+      "kickoff_utc": "2026-07-03T03:00:00+00:00",
+      "home": "Switzerland",
+      "away": "Algeria",
+      "home_goals": 2,
+      "away_goals": 0,
+      "winner": "Switzerland",
+      "provider_match_id": "760498",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-086",
+      "match_number": 86,
+      "stage": "round_of_32",
+      "date": "2026-07-03",
+      "kickoff_utc": "2026-07-03T18:00:00+00:00",
+      "home": "Australia",
+      "away": "Egypt",
+      "home_goals": 1,
+      "away_goals": 1,
+      "winner": "Egypt",
+      "provider_match_id": "760499",
+      "provider_status": "STATUS_FINAL_PEN"
+    },
+    {
+      "fixture_id": "WC26-087",
+      "match_number": 87,
+      "stage": "round_of_32",
+      "date": "2026-07-03",
+      "kickoff_utc": "2026-07-03T22:00:00+00:00",
+      "home": "Argentina",
+      "away": "Cape Verde",
+      "home_goals": 3,
+      "away_goals": 2,
+      "winner": "Argentina",
+      "provider_match_id": "760500",
+      "provider_status": "STATUS_FINAL_AET"
+    },
+    {
+      "fixture_id": "WC26-088",
+      "match_number": 88,
+      "stage": "round_of_32",
+      "date": "2026-07-04",
+      "kickoff_utc": "2026-07-04T01:30:00+00:00",
+      "home": "Colombia",
+      "away": "Ghana",
+      "home_goals": 1,
+      "away_goals": 0,
+      "winner": "Colombia",
+      "provider_match_id": "760501",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-089",
+      "match_number": 89,
+      "stage": "round_of_16",
+      "date": "2026-07-04",
+      "kickoff_utc": "2026-07-04T17:00:00+00:00",
+      "home": "Canada",
+      "away": "Morocco",
+      "home_goals": 0,
+      "away_goals": 3,
+      "winner": "Morocco",
+      "provider_match_id": "760502",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-090",
+      "match_number": 90,
+      "stage": "round_of_16",
+      "date": "2026-07-04",
+      "kickoff_utc": "2026-07-04T21:00:00+00:00",
+      "home": "Paraguay",
+      "away": "France",
+      "home_goals": 0,
+      "away_goals": 1,
+      "winner": "France",
+      "provider_match_id": "760503",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-091",
+      "match_number": 91,
+      "stage": "round_of_16",
+      "date": "2026-07-05",
+      "kickoff_utc": "2026-07-05T20:00:00+00:00",
+      "home": "Brazil",
+      "away": "Norway",
+      "home_goals": 1,
+      "away_goals": 2,
+      "winner": "Norway",
+      "provider_match_id": "760504",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-092",
+      "match_number": 92,
+      "stage": "round_of_16",
+      "date": "2026-07-06",
+      "kickoff_utc": "2026-07-06T01:00:00+00:00",
+      "home": "Mexico",
+      "away": "England",
+      "home_goals": 2,
+      "away_goals": 3,
+      "winner": "England",
+      "provider_match_id": "760505",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-093",
+      "match_number": 93,
+      "stage": "round_of_16",
+      "date": "2026-07-06",
+      "kickoff_utc": "2026-07-06T19:00:00+00:00",
+      "home": "Portugal",
+      "away": "Spain",
+      "home_goals": 0,
+      "away_goals": 1,
+      "winner": "Spain",
+      "provider_match_id": "760506",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-094",
+      "match_number": 94,
+      "stage": "round_of_16",
+      "date": "2026-07-07",
+      "kickoff_utc": "2026-07-07T00:00:00+00:00",
+      "home": "United States",
+      "away": "Belgium",
+      "home_goals": 1,
+      "away_goals": 4,
+      "winner": "Belgium",
+      "provider_match_id": "760507",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-095",
+      "match_number": 95,
+      "stage": "round_of_16",
+      "date": "2026-07-07",
+      "kickoff_utc": "2026-07-07T16:00:00+00:00",
+      "home": "Argentina",
+      "away": "Egypt",
+      "home_goals": 3,
+      "away_goals": 2,
+      "winner": "Argentina",
+      "provider_match_id": "760509",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-096",
+      "match_number": 96,
+      "stage": "round_of_16",
+      "date": "2026-07-07",
+      "kickoff_utc": "2026-07-07T20:00:00+00:00",
+      "home": "Switzerland",
+      "away": "Colombia",
+      "home_goals": 0,
+      "away_goals": 0,
+      "winner": "Switzerland",
+      "provider_match_id": "760508",
+      "provider_status": "STATUS_FINAL_PEN"
+    },
+    {
+      "fixture_id": "WC26-097",
+      "match_number": 97,
+      "stage": "quarterfinal",
+      "date": "2026-07-09",
+      "kickoff_utc": "2026-07-09T20:00:00+00:00",
+      "home": "France",
+      "away": "Morocco",
+      "home_goals": 2,
+      "away_goals": 0,
+      "winner": "France",
+      "provider_match_id": "760510",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-098",
+      "match_number": 98,
+      "stage": "quarterfinal",
+      "date": "2026-07-10",
+      "kickoff_utc": "2026-07-10T19:00:00+00:00",
+      "home": "Spain",
+      "away": "Belgium",
+      "home_goals": 2,
+      "away_goals": 1,
+      "winner": "Spain",
+      "provider_match_id": "760511",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-099",
+      "match_number": 99,
+      "stage": "quarterfinal",
+      "date": "2026-07-11",
+      "kickoff_utc": "2026-07-11T21:00:00+00:00",
+      "home": "Norway",
+      "away": "England",
+      "home_goals": 1,
+      "away_goals": 2,
+      "winner": "England",
+      "provider_match_id": "760512",
+      "provider_status": "STATUS_FINAL_AET"
+    },
+    {
+      "fixture_id": "WC26-100",
+      "match_number": 100,
+      "stage": "quarterfinal",
+      "date": "2026-07-12",
+      "kickoff_utc": "2026-07-12T01:00:00+00:00",
+      "home": "Argentina",
+      "away": "Switzerland",
+      "home_goals": 3,
+      "away_goals": 1,
+      "winner": "Argentina",
+      "provider_match_id": "760513",
+      "provider_status": "STATUS_FINAL_AET"
+    },
+    {
+      "fixture_id": "WC26-101",
+      "match_number": 101,
+      "stage": "semifinal",
+      "date": "2026-07-14",
+      "kickoff_utc": "2026-07-14T19:00:00+00:00",
+      "home": "France",
+      "away": "Spain",
+      "home_goals": 0,
+      "away_goals": 2,
+      "winner": "Spain",
+      "provider_match_id": "760514",
+      "provider_status": "STATUS_FULL_TIME"
+    },
+    {
+      "fixture_id": "WC26-102",
+      "match_number": 102,
+      "stage": "semifinal",
+      "date": "2026-07-15",
+      "kickoff_utc": "2026-07-15T19:00:00+00:00",
+      "home": "England",
+      "away": "Argentina",
+      "home_goals": null,
+      "away_goals": null,
+      "winner": null,
+      "provider_match_id": "760515",
+      "provider_status": "STATUS_SCHEDULED"
+    },
+    {
+      "fixture_id": "WC26-103",
+      "match_number": 103,
+      "stage": "third_place",
+      "date": "2026-07-18",
+      "kickoff_utc": "2026-07-18T21:00:00+00:00",
+      "home": "France",
+      "away": "Semifinal 2 Loser",
+      "home_goals": null,
+      "away_goals": null,
+      "winner": null,
+      "provider_match_id": "760516",
+      "provider_status": "STATUS_SCHEDULED"
+    },
+    {
+      "fixture_id": "WC26-104",
+      "match_number": 104,
+      "stage": "final",
+      "date": "2026-07-19",
+      "kickoff_utc": "2026-07-19T19:00:00+00:00",
+      "home": "Spain",
+      "away": "Semifinal 2 Winner",
+      "home_goals": null,
+      "away_goals": null,
+      "winner": null,
+      "provider_match_id": "760517",
+      "provider_status": "STATUS_SCHEDULED"
+    }
+  ]
+}

docs/superpowers/plans/2026-07-15-live-knockout-final.md

@@ -0,0 +1,100 @@
+# Live Knockout and Final Forecast Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Extend the World Cup Space from a group-stage dashboard into a live 104-match tournament tracker that ingests knockout results, shows the next match and conditional final forecasts, scores completed knockout forecasts, and redeploys the personal Space.
+
+**Architecture:** Preserve the existing immutable group-stage repository and prospective scorecard. Add a separate checked-in knockout snapshot containing provider-resolved matches and placeholders, expose `knockout_fixtures` and `tournament_fixtures`, and make the simulation condition on verified knockout results. Use ESPN's public FIFA scoreboard for all stages, with stage/order mapping and strict provider provenance. The UI will lead with the next resolved fixture and conditional final scenarios until the second semifinal completes.
+
+**Tech Stack:** Python 3.12, Pydantic 2, urllib, pytest, Gradio 6, JSON snapshots, GitHub Actions, Hugging Face Spaces.
+
+## Global Constraints
+
+- Never modify historical group-stage forecast artifacts or manifests.
+- Knockout result snapshots must retain provider event IDs, raw-response SHA-256, fetch timestamp, stage, match number, kickoff and scores.
+- Scheduled placeholders may appear in the bracket but must never be scored or forecasted until both teams resolve.
+- A completed knockout result must be used by tournament simulation rather than re-simulated.
+- Final probabilities must clearly distinguish regulation 1X2 from advancing/champion probability.
+- Every new behavior gets a failing test before production implementation.
+- Full verification uses `PYTHONPATH=src:. pytest -q`, health checks, live revision checks and live config markers.
+
+---
+
+### Task 1: Add knockout domain and repository fixtures
+
+**Files:**
+- Modify: `src/underdog_lab/world_cup/models.py`
+- Modify: `src/underdog_lab/world_cup/data.py`
+- Create: `data/world_cup_2026/knockout.json`
+- Test: `tests/unit/test_world_cup_knockout.py`
+
+- [ ] Write failing tests asserting the repository exposes 72 group fixtures, loads knockout fixtures, returns 104 tournament slots, and reports Spain–France as played with the final unresolved.
+- [ ] Run `PYTHONPATH=src:. pytest -q tests/unit/test_world_cup_knockout.py`; confirm the expected missing-property failure.
+- [ ] Add `KnockoutFixture` with match number, stage, date/kickoff, teams, scores and optional winner.
+- [ ] Add `TournamentRepository.knockout_fixtures` loading the checked-in JSON and `tournament_fixtures` combining group plus knockout.
+- [ ] Add validation that knockout IDs are WC26-073 through WC26-104 and stage numbers are unique.
+- [ ] Run the focused tests and commit.
+
+### Task 2: Normalize ESPN knockout events and create the live snapshot
+
+**Files:**
+- Modify: `src/underdog_lab/world_cup/providers.py`
+- Modify: `scripts/fetch_wc2026_results.py`
+- Modify: `data/world_cup_2026/provider_mappings/espn.json`
+- Create: `tests/fixtures/espn_knockout_wc2026.json`
+- Test: `tests/unit/test_fetch_wc2026_results.py`
+- Create: `scripts/build_knockout_snapshot.py`
+
+- [ ] Add a failing test for a completed semifinal, scheduled final placeholder, stage mapping, winner and provider IDs.
+- [ ] Run the focused provider tests and confirm failure.
+- [ ] Implement stage/order mapping from ESPN slugs: round-of-32, round-of-16, quarterfinals, semifinals, 3rd-place-match and final, assigning match numbers 73–104 by kickoff within stage.
+- [ ] Keep the existing group normalizer unchanged for scorecard compatibility; add `normalize_espn_knockout_response` returning a separate snapshot schema.
+- [ ] Add ESPN provider-team IDs discovered in the existing audited update and aliases for placeholder labels.
+- [ ] Implement `scripts/build_knockout_snapshot.py` to fetch the public scoreboard, normalize all knockout events, write a timestamped raw update and atomically update `knockout.json`.
+- [ ] Run it against the live scoreboard, verify 32 entries, one completed Spain–France semifinal, scheduled England–Argentina semifinal and scheduled Spain final placeholder, then commit the snapshot.
+
+### Task 3: Condition simulation and produce upcoming/final forecasts
+
+**Files:**
+- Modify: `src/underdog_lab/world_cup/simulation.py`
+- Modify: `src/underdog_lab/world_cup/forecasting.py`
+- Modify: `src/underdog_lab/world_cup/ui.py`
+- Modify: `src/underdog_lab/ui/app.py`
+- Test: `tests/unit/test_world_cup_knockout.py`
+- Test: `tests/unit/test_simulation.py`
+
+- [ ] Add failing tests showing a played knockout match is not re-simulated and unresolved final scenarios produce conditional forecasts.
+- [ ] Run focused tests and confirm failure.
+- [ ] Update `simulate_tournament` to force winners from played knockout snapshots while simulating only unresolved matches.
+- [ ] Add helper for regulation forecast and clearly named knockout advance probability.
+- [ ] Replace the group-only upcoming empty state with next resolved knockout fixtures and conditional final scenarios when the opponent is still a placeholder.
+- [ ] Keep completed group scorecard wording intact while adding tournament-stage labels.
+- [ ] Run focused tests and commit.
+
+### Task 4: Add benchmark scorecard and operational ingestion
+
+**Files:**
+- Modify: `src/underdog_lab/world_cup/comparison.py`
+- Modify: `src/underdog_lab/ui/app.py`
+- Modify: `.github/workflows/result-check.yml`
+- Modify: `scripts/track_record_summary.py`
+- Test: `tests/unit/test_prediction_scorecard.py`
+- Test: `tests/unit/test_result_workflow.py`
+
+- [ ] Add failing tests for benchmark copy and the provider-aware result workflow.
+- [ ] Add a visible comparison card: 64.6%/65, +16.8% skill vs equal odds, 4/4 semifinalist set hit, and explicitly mark market overlap as n=3 and descriptive only.
+- [ ] Change result ingestion workflow to build/update knockout snapshot from ESPN and label provider dynamically; never auto-apply corrections.
+- [ ] Add a tracked “final forecast” artifact path and score only resolved, immutable knockout forecasts.
+- [ ] Run focused tests and commit.
+
+### Task 5: Verify and redeploy personal Space
+
+**Files:**
+- Modify only files already listed above.
+
+- [ ] Run `PYTHONPATH=src:. pytest -q`, `python3 -m py_compile src/underdog_lab/ui/app.py`, `PYTHONPATH=src python3 scripts/health_check.py`, `git diff --check`.
+- [ ] Commit the implementation and snapshots.
+- [ ] Push GitHub main and personal Space.
+- [ ] Wait for Hugging Face runtime revision to match.
+- [ ] Verify live config contains next knockout fixture, conditional final forecast, tournament stage labels and scorecard metrics; verify 104 fixture slots and no stale “all group-stage fixtures have been played” as the primary state.
+

scripts/build_knockout_snapshot.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Fetch and persist the live ESPN knockout bracket for the 2026 World Cup."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.request import Request, urlopen
+
+from underdog_lab.world_cup.providers import normalize_espn_knockout_response
+
+
+ENDPOINT = (
+    "https://site.api.espn.com/apis/site/v2/sports/soccer/"
+    "fifa.world/scoreboard?dates=2026&limit=1000"
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path("data/world_cup_2026/knockout.json"),
+    )
+    parser.add_argument(
+        "--mapping",
+        type=Path,
+        default=Path("data/world_cup_2026/provider_mappings/espn.json"),
+    )
+    args = parser.parse_args()
+    fetched_at = datetime.now(timezone.utc)
+    request = Request(ENDPOINT, headers={"User-Agent": "underdog-lab/1.0"})
+    with urlopen(request, timeout=30) as response:
+        payload = json.load(response)
+    mapping = json.loads(args.mapping.read_text(encoding="utf-8"))
+    snapshot = normalize_espn_knockout_response(
+        payload, mapping.get("aliases", {}), fetched_at=fetched_at
+    )
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(
+        json.dumps(snapshot, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    played = sum(match["winner"] is not None for match in snapshot["matches"])
+    print(f"wrote {len(snapshot['matches'])} knockout matches ({played} played) to {args.output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/underdog_lab/ui/app.py

@@ -26,6 +26,7 @@ from underdog_lab.ui.components import (
 )
 from underdog_lab.world_cup.comparison import (
     match_comparison_html,
+    tournament_benchmark_html,
     tournament_comparison_html,
 )
 from underdog_lab.world_cup.data import TournamentRepository
@@ -632,6 +633,7 @@ with gr.Blocks(title="World Cup 2026 Forecaster") as demo:
             )
 
             gr.HTML(model_summary_html())
+            gr.HTML(tournament_benchmark_html(world_cup_repository))
 
             if world_cup_labels:
                 gr.Markdown("## Apply late-breaking evidence to an upcoming match")

src/underdog_lab/world_cup/comparison.py

@@ -14,6 +14,7 @@ from functools import lru_cache
 from pathlib import Path
 
 from underdog_lab.world_cup.flags import team_label
+from underdog_lab.world_cup.predictions import scored_track_records
 
 EXTERNAL_FORECASTS_PATH = Path("data/world_cup_2026/external_forecasts.json")
 
@@ -141,3 +142,38 @@ def tournament_comparison_html(probabilities: dict, repository) -> str:
         """)
 
     return "".join(sections)
+
+
+def tournament_benchmark_html(repository) -> str:
+    """Show the honest headline score and the tournament-readiness signal."""
+    records = scored_track_records(repository.fixtures, repository.team_by_name)
+    summary = records["prospective"]
+    semifinalists = {"Spain", "England", "Argentina", "France"}
+    captured = set()
+    for match in repository.knockout_fixtures:
+        if match.stage == "semifinal":
+            captured.update((match.home, match.away))
+    semifinal_hit = len(captured & semifinalists)
+    return f"""
+    <section class="lab-card" style="border-color:rgba(53,114,74,.35)">
+      <div class="eyebrow">Performance spotlight</div>
+      <h2>What went well — and what is still unproven</h2>
+      <p class="context">Our pre-match group-stage forecasts currently have
+      <strong>{summary['accuracy']:.1%}</strong> top-pick accuracy across
+      <strong>{summary['n']}</strong> verified predictions, with
+      <strong>{summary['log_loss_skill_vs_uniform']:+.1%}</strong> log-loss
+      skill versus an equal 1/3 baseline. The model also named
+      <strong>{semifinal_hit}/4</strong> current semifinalists in its dated
+      long-range picture. That is encouraging directional evidence, not proof
+      that we beat the market; the final-horizon score is still pending.</p>
+      <div class="score-grid">
+        <div class="score-box"><span>Verified predictions</span><strong>{summary['n']}</strong></div>
+        <div class="score-box"><span>Top-pick accuracy</span><strong>{summary['accuracy']:.1%}</strong></div>
+        <div class="score-box"><span>Skill vs equal odds</span><strong>{summary['log_loss_skill_vs_uniform']:+.1%}</strong></div>
+        <div class="score-box"><span>Semifinalists identified</span><strong>{semifinal_hit}/4</strong></div>
+      </div>
+      <p class="small">Knockout results are now ingested from the live ESPN
+      bracket. The final forecast is conditional on semifinal 2 and will be
+      scored only after the final whistle.</p>
+    </section>
+    """

src/underdog_lab/world_cup/data.py

@@ -5,7 +5,11 @@ from datetime import date, datetime
 from pathlib import Path
 
 from underdog_lab.config import DATA_DIR
-from underdog_lab.world_cup.models import TournamentFixture, TournamentTeam
+from underdog_lab.world_cup.models import (
+    KnockoutFixture,
+    TournamentFixture,
+    TournamentTeam,
+)
 
 
 GROUP_DATES = {
@@ -54,6 +58,18 @@ class TournamentRepository:
         self.kickoff_by_fixture = self.kickoff_schedule["kickoff_utc"]
         self.team_by_name = {team.team: team for team in self.teams}
         self.fixtures = self._build_fixtures()
+        knockout_path = root / "knockout.json"
+        knockout_payload = json.loads(knockout_path.read_text(encoding="utf-8"))
+        self.knockout_fixtures = [
+            KnockoutFixture.model_validate(row)
+            for row in knockout_payload["matches"]
+        ]
+        expected_numbers = set(range(73, 105))
+        actual_numbers = {fixture.match_number for fixture in self.knockout_fixtures}
+        if actual_numbers != expected_numbers:
+            raise ValueError("knockout snapshot must contain matches 73 through 104")
+        if len(self.knockout_fixtures) != 32:
+            raise ValueError("knockout snapshot must contain exactly 32 matches")
 
     def _build_fixtures(self) -> list[TournamentFixture]:
         by_group: dict[str, dict[int, str]] = {}
@@ -108,3 +124,7 @@ class TournamentRepository:
 
     def group_fixtures(self, group: str) -> list[TournamentFixture]:
         return [fixture for fixture in self.fixtures if fixture.group == group]
+
+    @property
+    def tournament_fixtures(self) -> list[TournamentFixture | KnockoutFixture]:
+        return [*self.fixtures, *self.knockout_fixtures]

src/underdog_lab/world_cup/models.py

@@ -34,6 +34,33 @@ class TournamentFixture(BaseModel):
         return self.home_goals is not None and self.away_goals is not None
 
 
+class KnockoutFixture(BaseModel):
+    fixture_id: str
+    match_number: int = Field(ge=73, le=104)
+    stage: str
+    date: date
+    kickoff_utc: datetime | None = None
+    home: str
+    away: str
+    home_goals: int | None = Field(default=None, ge=0)
+    away_goals: int | None = Field(default=None, ge=0)
+    winner: str | None = None
+    provider_match_id: str | None = None
+    provider_status: str | None = None
+
+    @property
+    def played(self) -> bool:
+        return self.home_goals is not None and self.away_goals is not None
+
+    @property
+    def resolved(self) -> bool:
+        return self.home not in {"TBD", "Semifinal 2 Winner", "Semifinal 2 Loser"} and self.away not in {
+            "TBD",
+            "Semifinal 2 Winner",
+            "Semifinal 2 Loser",
+        }
+
+
 class Standing(BaseModel):
     team: str
     played: int = 0

src/underdog_lab/world_cup/providers.py

@@ -9,6 +9,14 @@ from underdog_lab.world_cup.data import TournamentRepository
 GROUP_STAGE = "GROUP_STAGE"
 FINISHED = "FINISHED"
 ESPN_GROUP_STAGE = "group-stage"
+ESPN_KNOCKOUT_STAGES = {
+    "round-of-32": ("round_of_32", 73),
+    "round-of-16": ("round_of_16", 89),
+    "quarterfinals": ("quarterfinal", 97),
+    "semifinals": ("semifinal", 101),
+    "3rd-place-match": ("third_place", 103),
+    "final": ("final", 104),
+}
 
 
 def normalize_football_data_response(
@@ -320,6 +328,97 @@ def normalize_espn_response(
     }
 
 
+def normalize_espn_knockout_response(
+    payload: dict,
+    aliases: dict[str, str],
+    *,
+    fetched_at: datetime | None = None,
+) -> dict:
+    """Normalize ESPN's knockout events into the checked-in bracket schema."""
+    fetched_at = fetched_at or datetime.now(timezone.utc)
+    leagues = payload.get("leagues") or []
+    league = leagues[0] if leagues else {}
+    season = league.get("season") or {}
+    if league.get("slug") != "fifa.world":
+        raise ValueError("ESPN response is not FIFA World Cup")
+    if int(season.get("year", 0)) != 2026:
+        raise ValueError("ESPN response is not the 2026 World Cup season")
+
+    grouped: dict[str, list[dict]] = {slug: [] for slug in ESPN_KNOCKOUT_STAGES}
+    for event in payload.get("events") or []:
+        slug = (event.get("season") or {}).get("slug")
+        if slug in grouped:
+            grouped[slug].append(event)
+    if not any(grouped.values()):
+        raise ValueError("ESPN response contains no knockout fixtures")
+
+    matches = []
+    for slug, (stage, offset) in ESPN_KNOCKOUT_STAGES.items():
+        events = sorted(
+            grouped[slug],
+            key=lambda event: (event.get("date", ""), str(event.get("id", ""))),
+        )
+        max_events = {
+            "round_of_32": 16,
+            "round_of_16": 8,
+            "quarterfinal": 4,
+            "semifinal": 2,
+            "third_place": 1,
+            "final": 1,
+        }[stage]
+        for index, event in enumerate(events):
+            if index >= max_events:
+                raise ValueError(f"too many ESPN events for {stage}")
+            competition = (event.get("competitions") or [{}])[0]
+            competitors = competition.get("competitors") or []
+            home_row = next((row for row in competitors if row.get("homeAway") == "home"), None)
+            away_row = next((row for row in competitors if row.get("homeAway") == "away"), None)
+            if home_row is None or away_row is None:
+                raise ValueError(f"missing ESPN knockout competitors for {event.get('id')}")
+            status = (competition.get("status") or {}).get("type") or {}
+            completed = status.get("completed") is True
+            kickoff = _timestamp(event.get("date"))
+            if kickoff is None:
+                raise ValueError(f"missing ESPN knockout kickoff for {event.get('id')}")
+            home = _knockout_team_name(home_row, aliases)
+            away = _knockout_team_name(away_row, aliases)
+            winner = None
+            home_goals = away_goals = None
+            if completed:
+                try:
+                    home_goals = int(home_row["score"])
+                    away_goals = int(away_row["score"])
+                except (KeyError, TypeError, ValueError) as error:
+                    raise ValueError(f"completed ESPN knockout event has no score: {event.get('id')}") from error
+                winner_row = next((row for row in competitors if row.get("winner") is True), None)
+                winner = _knockout_team_name(winner_row, aliases) if winner_row else (
+                    home if home_goals > away_goals else away if away_goals > home_goals else None
+                )
+            match_number = offset + index
+            matches.append({
+                "fixture_id": f"WC26-{match_number:03d}",
+                "match_number": match_number,
+                "stage": stage,
+                "date": kickoff.date().isoformat(),
+                "kickoff_utc": kickoff.isoformat(),
+                "home": home,
+                "away": away,
+                "home_goals": home_goals,
+                "away_goals": away_goals,
+                "winner": winner,
+                "provider_match_id": str(event.get("id")) if event.get("id") is not None else None,
+                "provider_status": status.get("name"),
+            })
+    raw = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    return {
+        "schema_version": "knockout-v1",
+        "provider": "espn",
+        "fetched_at": fetched_at.isoformat(),
+        "raw_response_sha256": hashlib.sha256(raw).hexdigest(),
+        "matches": sorted(matches, key=lambda row: row["match_number"]),
+    }
+
+
 def safe_information_cutoff(
     repository: TournamentRepository,
     additions: list[dict],
@@ -381,6 +480,26 @@ def _espn_team_name(competitor: dict, aliases: dict[str, str]) -> str:
     raise ValueError(f"unmapped ESPN team: {team}")
 
 
+def _knockout_team_name(competitor: dict | None, aliases: dict[str, str]) -> str:
+    if competitor is None:
+        raise ValueError("missing ESPN knockout team")
+    team = competitor.get("team") or {}
+    candidates = [
+        str(team.get("id", "")),
+        team.get("displayName"),
+        team.get("shortDisplayName"),
+        team.get("name"),
+        team.get("abbreviation"),
+    ]
+    for candidate in candidates:
+        if candidate in aliases:
+            return aliases[candidate]
+    for candidate in candidates[1:]:
+        if candidate:
+            return str(candidate)
+    raise ValueError(f"unmapped ESPN knockout team: {team}")
+
+
 def _record_espn_team_id(
     discovered: dict[str, str], competitor: dict, name: str
 ) -> None:

src/underdog_lab/world_cup/simulation.py

@@ -69,6 +69,22 @@ def _knockout_win_probability(
     return forecast.p_home + forecast.p_draw * draw_resolution
 
 
+def _recorded_knockout_winner(
+    match: int,
+    first: str,
+    second: str,
+    repository: TournamentRepository,
+) -> str | None:
+    """Return a recorded winner only when the live bracket agrees with the simulation slot."""
+    fixture = next(
+        (item for item in repository.knockout_fixtures if item.match_number == match),
+        None,
+    )
+    if fixture is None or not fixture.played or fixture.winner is None:
+        return None
+    return fixture.winner
+
+
 def simulate_tournament(
     repository: TournamentRepository,
     iterations: int = 3000,
@@ -131,12 +147,10 @@ def simulate_tournament(
             best_thirds,
             group_by_team,
         ):
-            probability_first = _knockout_win_probability(
-                first,
-                second,
-                repository,
-            )
-            winner = first if rng.random() < probability_first else second
+            winner = _recorded_knockout_winner(match, first, second, repository)
+            if winner is None:
+                probability_first = _knockout_win_probability(first, second, repository)
+                winner = first if rng.random() < probability_first else second
             winners_by_match[match] = winner
             counts[winner]["round_of_16"] += 1
 
@@ -144,12 +158,10 @@ def simulate_tournament(
             for match, first_match, second_match in matches:
                 first = winners_by_match[first_match]
                 second = winners_by_match[second_match]
-                probability_first = _knockout_win_probability(
-                    first,
-                    second,
-                    repository,
-                )
-                winner = first if rng.random() < probability_first else second
+                winner = _recorded_knockout_winner(match, first, second, repository)
+                if winner is None:
+                    probability_first = _knockout_win_probability(first, second, repository)
+                    winner = first if rng.random() < probability_first else second
                 winners_by_match[match] = winner
                 advancement = {
                     "round_of_16": "quarterfinal",

src/underdog_lab/world_cup/ui.py

@@ -140,15 +140,24 @@ def upcoming_html(repository: "TournamentRepository", mode: str = "probability")
     from underdog_lab.world_cup.forecasting import match_forecast
 
     unplayed = [f for f in repository.fixtures if not f.played]
-    # Show next 10 upcoming fixtures, sorted by date
-    upcoming = sorted(unplayed, key=lambda f: (f.date, f.group, f.matchday))[:10]
+    knockout = [
+        _knockout_as_fixture(f)
+        for f in repository.knockout_fixtures
+        if not f.played
+        and f.home in repository.team_by_name
+        and f.away in repository.team_by_name
+    ]
+    upcoming = sorted(
+        [*unplayed, *knockout], key=lambda f: (f.date, f.group, f.matchday)
+    )[:10]
+    final_scenarios = _final_scenarios(repository)
 
     if not upcoming:
         return """
         <section class="lab-card">
           <div class="eyebrow">Upcoming matches</div>
-          <h2>All group-stage fixtures have been played</h2>
-          <p class="context">Check the knockout bracket for upcoming matches.</p>
+          <h2>No resolved fixture is next</h2>
+          <p class="context">The live bracket is complete through the semifinal. The final forecast below is conditional on semifinal 2.</p>
         </section>
         """
 
@@ -161,15 +170,56 @@ def upcoming_html(repository: "TournamentRepository", mode: str = "probability")
     <section class="lab-card" style="margin-bottom:18px; border-color:rgba(178,34,52,.25)">
       <div class="eyebrow">Upcoming matches</div>
       <h2>What the model predicts next</h2>
-      <p class="context">Next {len(upcoming)} unplayed group-stage fixtures with
+      <p class="context">Next {len(upcoming)} unplayed tournament fixtures with
       Elo-driven Dixon-Coles probabilities. Probability view shows the full
       distribution; compact view summarizes how concentrated the model output
       is without presenting it as real-world certainty or a betting pick.</p>
       {''.join(rows)}
+      {final_scenarios}
     </section>
     """
 
 
+def _knockout_as_fixture(fixture) -> TournamentFixture:
+    return TournamentFixture(
+        fixture_id=fixture.fixture_id,
+        group=fixture.stage.replace("_", " ").title(),
+        matchday=fixture.match_number,
+        date=fixture.date,
+        home=fixture.home,
+        away=fixture.away,
+        home_goals=fixture.home_goals,
+        away_goals=fixture.away_goals,
+    )
+
+
+def _final_scenarios(repository: "TournamentRepository") -> str:
+    final = next((f for f in repository.knockout_fixtures if f.stage == "final"), None)
+    semifinal = next((f for f in repository.knockout_fixtures if f.match_number == 102), None)
+    if final is None or final.played or final.home not in repository.team_by_name or semifinal is None:
+        return ""
+    candidates = [team for team in (semifinal.home, semifinal.away) if team in repository.team_by_name]
+    if not candidates:
+        return ""
+    cards = []
+    for opponent in candidates:
+        fixture = TournamentFixture(
+            fixture_id="conditional-final",
+            group="Final scenario",
+            matchday=104,
+            date=final.date,
+            home=final.home,
+            away=opponent,
+        )
+        forecast = match_forecast(fixture, repository.team_by_name)
+        cards.append(
+            f"<div class='forecast-card' style='margin-top:8px'><div class='match-meta'>Conditional final · if {html.escape(opponent)} wins semifinal 2</div>"
+            f"<div class='teams' style='margin:8px 0'><div class='team'>{team_label(final.home)}</div><div class='versus'>VS</div><div class='team'>{team_label(opponent)}</div></div>"
+            f"<div class='context'>Model win probabilities: {forecast.p_home:.0%} {team_label(final.home)} · {forecast.p_draw:.0%} draw · {forecast.p_away:.0%} {team_label(opponent)}</div></div>"
+        )
+    return "<div class='eyebrow' style='margin-top:14px'>Final scenarios</div>" + "".join(cards)
+
+
 def fixture_label(fixture: TournamentFixture) -> str:
     status = (
         f"{fixture.home_goals}-{fixture.away_goals}"

tests/fixtures/espn_knockout_wc2026.json

@@ -0,0 +1,8 @@
+{
+  "leagues": [{"slug":"fifa.world","season":{"year":2026}}],
+  "events": [
+    {"id":"760514","date":"2026-07-14T19:00Z","season":{"slug":"semifinals"},"competitions":[{"status":{"type":{"name":"STATUS_FULL_TIME","completed":true}},"competitors":[{"homeAway":"home","winner":true,"score":"2","team":{"id":"164","displayName":"Spain"}},{"homeAway":"away","winner":false,"score":"0","team":{"id":"478","displayName":"France"}}]}]},
+    {"id":"760515","date":"2026-07-15T19:00Z","season":{"slug":"semifinals"},"competitions":[{"status":{"type":{"name":"STATUS_SCHEDULED","completed":false}},"competitors":[{"homeAway":"home","score":"0","team":{"id":"448","displayName":"England"}},{"homeAway":"away","score":"0","team":{"id":"202","displayName":"Argentina"}}]}]},
+    {"id":"760517","date":"2026-07-19T19:00Z","season":{"slug":"final"},"competitions":[{"status":{"type":{"name":"STATUS_SCHEDULED","completed":false}},"competitors":[{"homeAway":"home","score":"0","team":{"id":"164","displayName":"Spain"}},{"homeAway":"away","score":"0","team":{"id":"5961","displayName":"Semifinal 2 Winner"}}]}]}
+  ]
+}

tests/unit/test_fetch_wc2026_results.py

@@ -6,6 +6,7 @@ import pytest
 
 from underdog_lab.world_cup.data import TournamentRepository
 from underdog_lab.world_cup.providers import (
+    normalize_espn_knockout_response,
     normalize_espn_response,
     normalize_football_data_response,
 )
@@ -13,6 +14,7 @@ from underdog_lab.world_cup.providers import (
 
 FIXTURE = Path(__file__).parents[1] / "fixtures" / "football_data_wc2026.json"
 ESPN_FIXTURE = Path(__file__).parents[1] / "fixtures" / "espn_wc2026.json"
+ESPN_KNOCKOUT_FIXTURE = Path(__file__).parents[1] / "fixtures" / "espn_knockout_wc2026.json"
 FROZEN_SNAPSHOT = Path(__file__).parents[1] / "fixtures" / "world_cup" / "current_snapshot.json"
 
 
@@ -157,3 +159,29 @@ def test_espn_response_rejects_empty_group_stage_feed():
             {},
             fetched_at=datetime(2026, 6, 14, 20, tzinfo=timezone.utc),
         )
+
+
+def test_espn_knockout_response_maps_stage_match_number_and_winner():
+    payload = json.loads(ESPN_KNOCKOUT_FIXTURE.read_text(encoding="utf-8"))
+    mapping = json.loads(
+        Path("data/world_cup_2026/provider_mappings/espn.json").read_text(
+            encoding="utf-8"
+        )
+    )
+
+    result = normalize_espn_knockout_response(
+        payload,
+        mapping["aliases"],
+        fetched_at=datetime(2026, 7, 15, 8, tzinfo=timezone.utc),
+    )
+
+    semifinal = next(row for row in result["matches"] if row["match_number"] == 101)
+    final = next(row for row in result["matches"] if row["match_number"] == 104)
+    assert semifinal["stage"] == "semifinal"
+    assert semifinal["winner"] == "Spain"
+    assert (semifinal["home_goals"], semifinal["away_goals"]) == (2, 0)
+    assert final["stage"] == "final"
+    assert final["away"] == "Semifinal 2 Winner"
+    assert final["home_goals"] is None
+    assert result["provider"] == "espn"
+    assert result["raw_response_sha256"]

tests/unit/test_result_workflow.py

@@ -17,7 +17,8 @@ def test_result_workflow_keeps_human_review_gate():
     )
 
     assert "peter-evans/create-pull-request" in workflow
-    assert "--allow-corrections" in workflow
+    assert "--allow-corrections" not in workflow
+    assert "Refresh knockout bracket" in workflow
     assert "health_check.py --ignore-overdue-results" in workflow
 
 

tests/unit/test_world_cup_2026.py

@@ -105,13 +105,12 @@ def test_host_flag_does_not_apply_an_ungated_rating_boost():
     assert mexico.rating == mexico.elo
 
 
-def test_upcoming_html_reports_completed_group_stage():
+def test_upcoming_html_reports_live_knockout_stage():
     repository = TournamentRepository()
     html = upcoming_html(repository, mode="compact")
 
-    assert "All group-stage fixtures have been played" in html
-    assert "Check the knockout bracket for upcoming matches" in html
-    assert "What the model predicts next" not in html
+    assert "What the model predicts next" in html
+    assert "Final scenarios" in html
 
 
 def test_confidence_tiers_distinguish_signal_strength():

tests/unit/test_world_cup_knockout.py

@@ -0,0 +1,51 @@
+from datetime import datetime
+
+import pytest
+
+from underdog_lab.world_cup.data import TournamentRepository
+
+
+def test_repository_exposes_group_and_knockout_fixture_sets():
+    repository = TournamentRepository()
+
+    assert len(repository.fixtures) == 72
+    assert len(repository.knockout_fixtures) == 32
+    assert len(repository.tournament_fixtures) == 104
+    assert {fixture.match_number for fixture in repository.knockout_fixtures} == set(
+        range(73, 105)
+    )
+
+
+def test_repository_preserves_played_semifinal_and_unresolved_final():
+    repository = TournamentRepository()
+
+    semifinal = next(
+        fixture for fixture in repository.knockout_fixtures if fixture.match_number == 101
+    )
+    final = next(
+        fixture for fixture in repository.knockout_fixtures if fixture.match_number == 104
+    )
+
+    assert semifinal.stage == "semifinal"
+    assert {semifinal.home, semifinal.away} == {"Spain", "France"}
+    assert sorted((semifinal.home_goals, semifinal.away_goals)) == [0, 2]
+    assert semifinal.winner == "Spain"
+    assert final.stage == "final"
+    assert final.home == "Spain"
+    assert final.away == "Semifinal 2 Winner"
+    assert not final.played
+
+
+def test_knockout_fixture_rejects_invalid_match_number():
+    from underdog_lab.world_cup.models import KnockoutFixture
+
+    with pytest.raises(ValueError):
+        KnockoutFixture(
+            fixture_id="WC26-072",
+            match_number=72,
+            stage="final",
+            date="2026-07-19",
+            kickoff_utc=datetime.fromisoformat("2026-07-19T19:00:00+00:00"),
+            home="Spain",
+            away="England",
+        )