Fix chess.com generic-guess false positives and stale broadcast search query

A bare single-word chess.com guess (e.g. "john") could coincidentally match
an unrelated stranger's account and score "high" purely from country/games/
recency when no rating was available to catch it — locking out the SearXNG
search path that would have found the real, differently-named account.
resolve_chesscom now tracks a fourth hard-cap signal, name_ok, and prefers a
well-evidenced search hit over an untrustworthy guess winner even at a lower
raw score.

Separately, lookup.broadcasts.find_broadcast_round_ids was still building the
pre-fix search query (exact-phrase-quoted, raw "Last, First" order, a
/broadcast path fragment) that lichess.py/chesscom.py's search already moved
away from — silently missing real, findable rounds. Also raised max_results
5 -> 10, since target rounds only reliably surfaced past the old default.

Also documents five new roadmap ideas: opening-theory/blunder insights,
feeding the user's own games into opponent dossiers, personal-repertoire
matching, cloud-hosted reports, and pipeline caching/perf.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: jlhe97

CLAUDE.md

@@ -118,6 +118,15 @@ Full URLs are auto-detected; `--site` is only needed for ID shorthands.
 - Also done: game-count-aware and rating-mismatch-aware match confidence, chess.com guessing scores every candidate instead of stopping at the first hit, web search migrated from Brave to self-hosted SearXNG, a client-side engine (Stockfish by default, off until toggled, top-3 multi-PV lines) with flip/eval/best-move in an enlarged/centered games viewer, a recent-games (last 12 months) viewer for high-confidence matches, and an opt-in cross-scan dossier database.
 - Verified against real data across two real tournament scans: with the games-count and rating-mismatch hard caps in place, a wrong-but-plausible candidate (large game count, matching country, but a rating far outside tolerance) correctly stays at *low* confidence instead of being fooled by the incidental signals; separately, fixing the search query construction (natural name order, unquoted, bare domain — see above) took a personalized-handle case that the guess-only path could never reach from "not discoverable at all" to "found, high confidence" once SearXNG was live, though a single self-hosted instance with only 1–2 reliably-responding engines means recall on any one query isn't 100% consistent call to call.
 - Remaining: combined PDF output. A SearXNG instance still needs a card-free signup-free way to run reliably 24/7 outside a sandbox with no Docker (the one used for development here was run from source in a venv — see the setup note below) — and even with search enabled, it depends on which upstream engines happen to be responding, so this stays a best-effort discovery path, not a guarantee.
+- Fixed 2026-07-10, both confirmed against real players in the recurring `WQ260708` tournament: `lookup.broadcasts.find_broadcast_round_ids` had never picked up the natural-order/unquoted/bare-domain query fix already applied to `lichess.py`/`chesscom.py`'s search (it was still exact-phrase-quoting the raw "Last, First" order and appending a `/broadcast` path fragment), silently missing real, findable rounds — and a chess.com generic single-word guess (e.g. "john") could collide with an unrelated stranger's real account and score "high" purely from country/games/recency when no rating was on file to catch it, locking out the search path entirely before it ever ran. See `_MIN_NAME_SCORE_FOR_HIGH`/`name_ok` in `pipeline/resolver.py`.
+
+### Future roadmap ideas (not yet started)
+
+- **Mistake/theory-deviation insights per opponent** — flag where an opponent's games diverge from known theory or contain outright blunders, not just which openings they play. Two different signals, both new: (1) "deviates from theory" doesn't need an external opening book — the megabase itself already has 11.7M games, so "theory" at any position can be derived from what the megabase's strongest/most-common continuations actually are, compared ply-by-ply against the opponent's games (`analysis/openings.py` already builds a move-tree per opponent; this would need the same tree built from megabase as a baseline to diff against). (2) "mistakes" needs actual eval, which today only exists client-side (the games-browser's Stockfish Web Worker, browser-only, nothing persisted) — a report-time version would need a server-side UCI engine pass (e.g. the `stockfish` PyPI binary wrapped via `python-chess`) over each opponent's games, which is a real new dependency and meaningfully slower per-dossier build, so probably opt-in (`--analyse-blunders` or similar) rather than default.
+- **Feed your own games against an opponent into their dossier** — right now `build_dossier()` only ever sees the opponent's own games from the 5 sourcing paths; there's no way to inject *your* games against them specifically. Would need: a way to supply your own PGN pool (a file, or your own Lichess/chess.com username reused through the existing `lookup.lichess`/`lookup.chesscom` fetchers), a head-to-head filter matching the opponent's name on the *other* side of the board from you, and a distinct "vs. you" section in the report (and, per the "combined reports and databases" ask, a way to keep accumulating this across scans rather than starting over each run — `dossier/db.py`'s existing cross-scan history is the natural place this could plug in, since it's already keyed by opponent name-slug).
+- **Personal repertoire vs. opponent tendencies** — let the user define their own opening repertoire (as White and Black) and have the report highlight which of the opponent's games actually entered one of those lines, i.e. "here's what they did the last N times they faced what you actually play," rather than their opening stats in the abstract. Representationally this is close to what `analysis/openings.py` already builds (a move-sequence tree per player) — the new part is a second tree (the user's own repertoire, probably authored as a small PGN of main lines) and a matching pass that walks each opponent game against it to find where the game and the repertoire diverge, then surfaces just those games instead of (or in addition to) the full opening breakdown.
+- **Cloud hosting for dossiers/history, accessible from multiple devices** — today everything is local-only: HTML/MD/JSON dossier files on disk, `dossier/db.py`'s SQLite history, and the 16GB `megabase.db`. The megabase itself is impractical to host remotely at that size for a personal tool (and read-only/build-once anyway, so it doesn't need to move), but the actual per-scan outputs (dossier files + the history db) are small and are the part worth syncing — e.g. pushing rendered HTML to a static host (S3/R2/GitHub Pages on a private repo) or standing up a minimal read-only web view backed by `dossier/db.py`. Needs a real answer on access control before anything ships, since dossiers currently contain other real players' names/data with no auth model at all today.
+- **Caching / faster pipeline runs** — a full `WQ260708`-sized scan (~33 players) takes on the order of 10+ minutes end to end, and re-running it (e.g. after a resolver change, or the tournament's entry list gaining a few late entrants) currently redoes *everything* from scratch for every player, including the ones that haven't changed. The known cost centers, concretely: `lookup.lichess` sleeps 1s before every game-fetch call (`_RATE_DELAY`) and `pipeline.runner` adds its own 1s sleeps around megabase/profile fetches (`time.sleep(1.0)`, `pipeline/runner.py`) — deliberate rate-limit courtesy, not accidental, so not just removable; chess.com guessing can issue up to 9 sequential profile HTTP requests per player before or in addition to a SearXNG search call; and nothing from a previous run is reused, so an unresolved or low-confidence player gets the identical (slow, and possibly still-failing) resolution attempt every single re-run. The most promising angle is probably a resolver-result cache keyed by player-name-slug with a TTL (skip re-resolving a player whose username/confidence was already established recently, similar to how `dossier/db.py` already dedupes a same-day rerun) — separately, megabase queries and broadcast-round PGN fetches (immutable once played) are also cacheable with no staleness concern at all, unlike a live Lichess/chess.com profile lookup.
 
 ### SearXNG setup
 

lookup/broadcasts.py

@@ -35,9 +35,32 @@ def _extract_round_id(url: str) -> str | None:
     return m.group(1) if m else None
 
 
-def find_broadcast_round_ids(player_name: str, searxng_url: str, max_results: int = 5) -> list[str]:
-    """Web-search for the player's name alongside Lichess broadcasts, return round IDs found."""
-    results = web_search(f'"{player_name}" lichess.org/broadcast', searxng_url, count=max_results)
+def _natural_name_order(name: str) -> str:
+    """'Last, First Middle' -> 'First Middle Last' — real web pages never
+    write a name in tournament-entry-list comma order."""
+    if "," not in name:
+        return name
+    last, _, first = name.partition(",")
+    return f"{first.strip()} {last.strip()}"
+
+
+def find_broadcast_round_ids(player_name: str, searxng_url: str, max_results: int = 10) -> list[str]:
+    """
+    Web-search for the player's name alongside Lichess broadcasts, return
+    round IDs found.
+
+    The query is natural-order, unquoted, and uses a bare domain — the
+    same fix already applied to lookup.lichess/chesscom's
+    find_usernames_via_search (see their docstrings/CLAUDE.md): exact-
+    phrase-quoting the raw "Last, First" order finds nothing (real pages
+    essentially never contain that literal comma-ordered substring), and
+    appending a path fragment like "lichess.org/broadcast" gets tokenized
+    as unrelated keyword noise rather than treated as a URL hint. This
+    module used to do both, which silently missed real, findable
+    broadcast rounds.
+    """
+    query_name = _natural_name_order(player_name)
+    results = web_search(f'{query_name} lichess.org', searxng_url, count=max_results)
     round_ids: list[str] = []
     for r in results:
         rid = _extract_round_id(r.get("url", ""))
@@ -53,7 +76,7 @@ def get_round_pgn(round_id: str) -> str:
     return resp.text
 
 
-def find_games(player_name: str, searxng_url: str, max_results: int = 5) -> list[str]:
+def find_games(player_name: str, searxng_url: str, max_results: int = 10) -> list[str]:
     """
     Search for broadcasts mentioning `player_name`, fetch matching rounds,
     and return every game in them as a PGN string. Games not actually

pipeline/resolver.py

@@ -57,6 +57,21 @@
 # strict cutoff — it only nudges the score, never hard-rejects.
 _RATING_TOLERANCE = 800
 
+# A real production case exposed this: chess.com's bare single-word guesses
+# ("john") get a low placeholder name score (0.4, see
+# _resolve_chesscom_by_guessing) precisely because they're generic enough to
+# collide with an unrelated stranger — but when that stranger's account also
+# happens to have a "preferred" country, plenty of games, and recent
+# activity, those three signals alone (none of which is actually
+# person-specific — country is broad, games/recency just prove "a real
+# active account", not "the right one") can still drag the composite score
+# past _HIGH_THRESHOLD, with no rating comparison available at all to catch
+# the mismatch the way _RATING_TOLERANCE normally would. 0.65 mirrors
+# _name_score's own surname-substring floor, so any guess/search hit that's
+# genuinely tied to the name (compound guess, real-name match, or a search
+# result whose surname actually appears) already clears it.
+_MIN_NAME_SCORE_FOR_HIGH = 0.65
+
 # Tournaments on the two supported sites (kingregistration.com,
 # chessaction.com) are US-based, so a US-located profile is weak
 # positive evidence and a clearly non-US one is weak negative evidence.
@@ -335,15 +350,17 @@ def _resolve_lichess_by_search(
 
 
 def _confidence_for(score: float, games_count: int | None, rating_ok: bool = True,
-                    recency_ok: bool = True) -> str | None:
+                    recency_ok: bool = True, name_ok: bool = True) -> str | None:
     """
-    Map a composite score to a confidence label, with three hard overrides
+    Map a composite score to a confidence label, with four hard overrides
     that can only ever pull "high" down to "low", never the reverse:
       - a match backed by very few games (see _MIN_GAMES_FOR_HIGH)
       - a match whose rating comparison was catastrophically bad (see
         _composite_score's rating_ok)
       - a match whose account has had no activity in ~5 years (see
         _composite_score's recency_ok)
+      - a match whose name evidence is a generic, uncorroborated guess
+        (see _MIN_NAME_SCORE_FOR_HIGH)
     Any one alone means "score says high, but the strongest piece of
     corroborating evidence actively argues against it" — not a case to
     present as a confident identity match.
@@ -355,6 +372,8 @@ def _confidence_for(score: float, games_count: int | None, rating_ok: bool = Tru
             return "low"
         if not recency_ok:
             return "low"
+        if not name_ok:
+            return "low"
         return "high"
     if score >= _LOW_THRESHOLD:
         return "low"
@@ -408,7 +427,7 @@ def resolve_lichess(name: str, rating: int | None = None,
 
 def _resolve_chesscom_by_guessing(
     name: str, rating: int | None, fide_country: str | None = None
-) -> tuple[str | None, float, list[str], int | None, bool, bool]:
+) -> tuple[str | None, float, list[str], int | None, bool, bool, bool]:
     """
     Try every guessed chess.com username, scoring each one that resolves
     to a real profile and keeping the best-scoring candidate — rather than
@@ -428,11 +447,11 @@ def _resolve_chesscom_by_guessing(
     try:
         from lookup.chesscom import guess_usernames, get_profile
     except Exception:
-        return None, -1.0, [], None, True, True
+        return None, -1.0, [], None, True, True, True
 
     guesses = guess_usernames(name)
     best_username, best_score, best_reasons = None, -1.0, []
-    best_games, best_rating_ok, best_recency_ok = None, True, True
+    best_games, best_rating_ok, best_recency_ok, best_name_ok = None, True, True, True
     for i, username in enumerate(guesses):
         try:
             profile = get_profile(username)
@@ -455,6 +474,13 @@ def _resolve_chesscom_by_guessing(
             if real_s > name_s:
                 name_s, name_reason = real_s, f"real name match {real_s:.2f} ({real_name})"
 
+        # A weak, generic guess (bare "john") is only trustworthy if
+        # something else actually ties it to *this* person — a rating
+        # comparison genuinely happened (entry rating known and the
+        # account has one on file), not just "no data to contradict it".
+        # See _MIN_NAME_SCORE_FOR_HIGH.
+        rating_corroborated = bool(rating) and bool(profile.get("ratings"))
+
         score, reasons, rating_ok, recency_ok = _composite_score(
             name_s, name_reason,
             profile.get("ratings", {}), profile.get("country"), rating,
@@ -465,13 +491,14 @@ def _resolve_chesscom_by_guessing(
         if score > best_score:
             best_username, best_score, best_reasons = username, score, reasons
             best_games, best_rating_ok, best_recency_ok = profile.get("games_count"), rating_ok, recency_ok
+            best_name_ok = name_s >= _MIN_NAME_SCORE_FOR_HIGH or rating_corroborated
 
-    return best_username, best_score, best_reasons, best_games, best_rating_ok, best_recency_ok
+    return best_username, best_score, best_reasons, best_games, best_rating_ok, best_recency_ok, best_name_ok
 
 
 def _resolve_chesscom_by_search(
     name: str, rating: int | None, searxng_url: str, fide_country: str | None = None
-) -> tuple[str | None, float, list[str], int | None, bool, bool]:
+) -> tuple[str | None, float, list[str], int | None, bool, bool, bool]:
     """
     Web-search for the player's chess.com profile and score every
     candidate found on real name/rating/country — catches personalized
@@ -481,10 +508,10 @@ def _resolve_chesscom_by_search(
     try:
         from lookup.chesscom import find_usernames_via_search, get_profile
     except Exception:
-        return None, -1.0, [], None, True, True
+        return None, -1.0, [], None, True, True, True
 
     best_username, best_score, best_reasons = None, -1.0, []
-    best_games, best_rating_ok, best_recency_ok = None, True, True
+    best_games, best_rating_ok, best_recency_ok, best_name_ok = None, True, True, True
     for username in find_usernames_via_search(name, searxng_url):
         try:
             profile = get_profile(username)
@@ -505,8 +532,9 @@ def _resolve_chesscom_by_search(
         if score > best_score:
             best_username, best_score, best_reasons = username, score, reasons
             best_games, best_rating_ok, best_recency_ok = profile.get("games_count"), rating_ok, recency_ok
+            best_name_ok = name_s >= _MIN_NAME_SCORE_FOR_HIGH
 
-    return best_username, best_score, best_reasons, best_games, best_rating_ok, best_recency_ok
+    return best_username, best_score, best_reasons, best_games, best_rating_ok, best_recency_ok, best_name_ok
 
 
 def resolve_chesscom(name: str, rating: int | None = None,
@@ -527,27 +555,43 @@ def resolve_chesscom(name: str, rating: int | None = None,
     """
     name = _strip_title(name)
 
-    best_username, best_score, best_reasons, best_games, best_rating_ok, best_recency_ok = (
+    best_username, best_score, best_reasons, best_games, best_rating_ok, best_recency_ok, best_name_ok = (
         _resolve_chesscom_by_guessing(name, rating, fide_country))
 
-    if searxng_url and best_score < _HIGH_THRESHOLD:
-        s_username, s_score, s_reasons, s_games, s_rating_ok, s_recency_ok = _resolve_chesscom_by_search(
+    # Even if guessing already scored "high", a generic guess with no
+    # rating corroboration (best_name_ok False) isn't trustworthy enough to
+    # skip search on — the win could be a same-first-name stranger, and
+    # search is the only path that can find the real, differently-named
+    # account instead. See _MIN_NAME_SCORE_FOR_HIGH.
+    if searxng_url and (best_score < _HIGH_THRESHOLD or not best_name_ok):
+        s_username, s_score, s_reasons, s_games, s_rating_ok, s_recency_ok, s_name_ok = _resolve_chesscom_by_search(
             name, rating, searxng_url, fide_country)
-        if s_score > best_score:
+        # Prefer the search hit outright, even at a lower raw score, when
+        # the guess winner is a generic, uncorroborated guess (untrusted —
+        # see above) and search found a candidate whose name evidence is
+        # actually solid: a same-first-name stranger's inflated score from
+        # non-discriminating signals (country/games/recency) shouldn't
+        # outrank the real, differently-named account search just found.
+        if s_username is not None and (
+            s_score > best_score
+            or (not best_name_ok and s_name_ok and s_score >= _LOW_THRESHOLD)
+        ):
             best_username, best_score, best_reasons = s_username, s_score, s_reasons
-            best_games, best_rating_ok, best_recency_ok = s_games, s_rating_ok, s_recency_ok
+            best_games, best_rating_ok, best_recency_ok, best_name_ok = s_games, s_rating_ok, s_recency_ok, s_name_ok
 
     if best_username is None:
         return None, None, 0.0, []
 
-    confidence = _confidence_for(best_score, best_games, best_rating_ok, best_recency_ok)
+    confidence = _confidence_for(best_score, best_games, best_rating_ok, best_recency_ok, best_name_ok)
     if confidence == "low" and best_score >= _HIGH_THRESHOLD:
         if best_games is not None and best_games < _MIN_GAMES_FOR_HIGH:
             best_reasons = best_reasons + [f"capped from high: only {best_games} games on record"]
         elif not best_rating_ok:
             best_reasons = best_reasons + ["capped from high: rating far outside tolerance"]
         elif not best_recency_ok:
             best_reasons = best_reasons + ["capped from high: no recent activity"]
+        elif not best_name_ok:
+            best_reasons = best_reasons + ["capped from high: generic username guess with no rating/real-name corroboration"]
     if confidence is None:
         return None, None, best_score, best_reasons
     return best_username, confidence, best_score, best_reasons

pipeline/runner.py

@@ -115,7 +115,7 @@ def _fetch_megabase_games(name: str, db_path: str, limit: int | None = None,
         return []
 
 
-def _fetch_broadcast_games(name: str, searxng_url: str, max_results: int = 5) -> list[str]:
+def _fetch_broadcast_games(name: str, searxng_url: str, max_results: int = 10) -> list[str]:
     try:
         from lookup.broadcasts import find_games
         return find_games(name, searxng_url, max_results=max_results)