fplkit 2.5.0__tar.gz → 2.6.0__tar.gz

{fplkit-2.5.0 → fplkit-2.6.0}/CHANGELOG.md

@@ -1,6 +1,43 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [2.5.0] - 2026-09-07
+
+### Bug Fixes
+
+- stop the fpl-mate output style calling ep_next prior-informed (#261)
+- restore xG enrichment for players with an apostrophe in their name (#268)
+- keep coverage readable when one ledger file is damaged (#271)
+- stop the review scrubber deleting sentences naming full names (#270)
+- recap the last completed gameweek once the next one has kicked off (#274)
+- stop fpl xg table output crashing when custom analysis is off (#275)
+- cap httpx, pydantic and click below their next majors (#278)
+- stop a truncated LLM summary being saved without a warning (#276)
+- stop a draft replay erasing the league positions it recorded (#280)
+- validate FPL_CLI_DATA_DIR and FPL_CLI_CACHE_DIR eagerly like FPL_CLI_CONFIG_DIR (#281)
+- raise the click floor to 8.2 so the test suite can capture stderr (#283)
+- collapse a league-wide captain tie into one recap line (#282)
+- fill the blank Source column in a review's Standout Performers (#284)
+- exit 1 with the real reason when review or recap cannot run (#285)
+- point doctor's draft ID fix hints at `fpl init` (#288)
+- keep the current table's points out of a replayed gameweek's recap (#293)
+- report a failure the same way whatever the output format (#292)
+- keep league positions when one manager's replay data is partial (#295)
+- stop a replay renaming the player a stored red-card fine names (#290)
+- ground the review's "Next Week" advice in next gameweek's fixtures (#291)
+- rebuild the ratings prior when a football-data key appears (#289)
+- record the club a player played for in a replayed gameweek (#296)
+- keep `review --summarise` running when an LLM key is missing (#297)
+- derive season labels from GW1's deadline instead of the clock (#299)
+- correct award move direction and free-agent mislabelling (#302)
+
+### Features
+
+- flag stale quality-score calibration in `fpl doctor` (#298)
+- hand the league-recap editorial every manager's transfers (#300)
+- give the draft recap editorial every waiver and free-agent move (#303)
+- give the season-opener recap each manager's prior FPL seasons (#304)
+
 ## [2.4.1] - 2026-09-05
 
 ### Bug Fixes

{fplkit-2.5.0 → fplkit-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fplkit
-Version: 2.5.0
+Version: 2.6.0
 Summary: CLI tool for Fantasy Premier League analysis - classic and draft formats
 Project-URL: Homepage, https://github.com/rossgroomio/fpl-cli
 Project-URL: Repository, https://github.com/rossgroomio/fpl-cli

{fplkit-2.5.0 → fplkit-2.6.0}/docs/architecture.md

@@ -434,7 +434,7 @@ classDiagram
 
 All providers share the `LLMResponse` contract. `OpenAICompatProvider` supports OpenAI, Groq, Together, Ollama via configurable `base_url`. Provider selection configured in settings.
 
-`stop_reason` carries the provider's own verdict on why generation ended, verbatim in whichever vocabulary it used — Anthropic's `stop_reason`, an OpenAI-compatible API's `finish_reason`. `stopped_early` reads it against `NORMAL_STOP_REASONS`, a single set covering both dialects (the vocabularies do not collide), and every provider announces an abnormal one at WARNING via `log_abnormal_stop` — the same reason `_http` announces its retries there, so a truncation is visible on any command that talks to an LLM. `None` means the provider said nothing, which is never treated as evidence of truncation. Without this a cut-off response and a complete one were indistinguishable downstream, which is how a saved gameweek review shipped missing a whole format's verdict at exit 0 (#266).
+`stop_reason` carries the provider's own verdict on why generation ended, verbatim in whichever vocabulary it used — Anthropic's `stop_reason`, an OpenAI-compatible API's `finish_reason`. `stopped_early` reads it against `NORMAL_STOP_REASONS`, a single set covering both dialects (the vocabularies do not collide), and every provider announces an abnormal one at WARNING via `log_abnormal_stop` — the same reason `_http` announces its retries there, so a truncation is visible on any command that talks to an LLM. `None` means the provider said nothing, which is never treated as evidence of truncation. Without this a cut-off response and a complete one were indistinguishable downstream, which is how a saved gameweek review shipped missing a whole format's verdict at exit 0 (#266). `log_textless_response` is its companion for the other half of that failure: a reasoning model that reaches the ceiling mid-thought returns content with no text block in it at all, so the concatenated prose is `""` — honest, but indistinguishable from a model with nothing to say until the non-text blocks that did arrive are named (#306). Unlike `log_abnormal_stop` this one is Anthropic-only, because only the Messages API returns typed content blocks — an OpenAI-compatible reply carries a plain `message.content` string, so there is nothing to name when it comes back empty. What catches an empty answer whatever produced it is `check_synthesis_completeness`'s `empty` flag, one layer along, which reads the string the report would carry rather than the envelope it arrived in.
 
 Both HTTP providers post through `_http.post_json_with_retry`, the one place their error handling lives: it retries an HTTP 429 with `RetryPolicy` (exponential backoff with jitter, `Retry-After` honoured, the whole wait bounded by one budget, each retry announced at WARNING) and raises `RateLimitError` — a `ProviderError` subclass carrying the server's `retry_after` — once the attempts are spent, and turns every other error status, a timeout, or a non-JSON body into a sanitised `ProviderError`. That is the same 429-is-transient distinction `DatasetFetcher` draws for the historical datasets. The module also holds `QueryPacer`, which keeps request starts a configured interval apart for a caller that fires several queries at once; `fpl returnees --enrich` pairs it with an in-flight cap, reads the typed error to re-query only the rate-limited subset of its shortlist once, and reports a still-refused player as rate-limited rather than unanswered.
 
@@ -555,7 +555,7 @@ fpl_cli/
 │   ├── historical.py             # HistoricalDataProvider (composition: vaastav + Core-Insights) + historical_season_windows() (the disjoint source allocation) + merge_season_histories()
 │   ├── football_data.py          # FootballDataClient (standings, match results)
 │   └── providers/                # LLM provider abstraction
-│       ├── _models.py            # LLMResponse (incl. stop_reason/stopped_early), TokenUsage, NORMAL_STOP_REASONS, log_abnormal_stop, ProviderError, RateLimitError
+│       ├── _models.py            # LLMResponse (incl. stop_reason/stopped_early), TokenUsage, NORMAL_STOP_REASONS, log_abnormal_stop, log_textless_response, ProviderError, RateLimitError
 │       ├── _http.py              # Shared HTTP plumbing: 429 backoff (RetryPolicy, post_with_retry), the providers' one error path (post_json_with_retry), QueryPacer for batching callers
 │       ├── anthropic.py          # AnthropicProvider
 │       ├── openai_compat.py      # OpenAICompatProvider (OpenAI, Groq, Together, Ollama)
@@ -602,7 +602,7 @@ fpl_cli/
 ├── scraper/
 │   └── fpl_prices.py             # FPLPriceScraper (needs FPL_EMAIL/FPL_PASSWORD; behind TLS-inspecting proxies: FPL_BROWSER_IGNORE_CERTS=1 for cert MITM, or FPL_BROWSER_EXECUTABLE/CHANNEL/ARGS to swap the browser when the ClientHello itself is rejected)
 ├── paths.py                      # SHIPPED_CONFIG_DIR, TEMPLATE_DIR, user_config_dir(), user_data_dir(), user_cache_dir() — each user_* dir overridable via FPL_CLI_CONFIG_DIR / FPL_CLI_DATA_DIR / FPL_CLI_CACHE_DIR (absolute paths only; a relative one raises UserDirError rather than resolving against the cwd)
-├── season.py                     # season_label() (+ vaastav_season() alias), previous_season_year()/previous_season_label() (the newest *completed* season, one expression for the player prior, the calibration script's default and doctor's frozen-anchor check), understat_season(), core_insights_season(), TOTAL_GAMEWEEKS, CHIP_SPLIT_GW, PROMOTED_CLUBS_PER_SEASON. season_year_from_gameweeks() derives the year from GW1's deadline rather than the July-cutover clock (#91); resolve_season_year() composes it with the clock — GW1's year while its season is still live, the clock's once that season has fully concluded and the calendar has moved past it (the close-season gap before the next one's fixtures publish, when bootstrap-static keeps serving the finished season's events untouched). FPLClient.get_season_year() wraps resolve_season_year(), and review/league-recap/preview/status pass the result through explicitly so a season overrunning the cutover (2019-20, delayed into July 2020) still resolves to the year it started; league-fines, which reads the ledger with no network, instead defaults to services/league_history.py's most_recent_captured_season() so its default agrees with whatever league-recap actually wrote
+├── season.py                     # season_label() (+ vaastav_season() alias), previous_season_year()/previous_season_label() (the newest *completed* season, one expression for the player prior, the calibration script's default and doctor's frozen-anchor check), understat_season(), core_insights_season(), TOTAL_GAMEWEEKS, CHIP_SPLIT_GW, PROMOTED_CLUBS_PER_SEASON. season_year_from_gameweeks() derives the year from GW1's deadline rather than the July-cutover clock (#91); resolve_season_year() composes it with the clock — GW1's year while its season is still live, the clock's once that season has fully concluded and the calendar has moved past it (the close-season gap before the next one's fixtures publish, when bootstrap-static keeps serving the finished season's events untouched). FPLClient.get_season_year() wraps resolve_season_year(), and review/league-recap/preview/status/doctor pass the result through explicitly so a season overrunning the cutover (2019-20, delayed into July 2020) still resolves to the year it started -- doctor falls back to the clock only when the API is unreachable, and `fpl doctor --providers` reads the season off the bootstrap its FPL probe already fetched rather than downloading it twice. is_previous_season_year() is the ordered counterpart the staleness checks compare a timestamp's cutover year with: during an overrun a July timestamp lands a year *ahead* of the season it was written in, so exact comparison would call live data a previous season's (#308); league-fines, which reads the ledger with no network, instead defaults to services/league_history.py's most_recent_captured_season() so its default agrees with whatever league-recap actually wrote
 ├── constants.py                  # MIN_MINUTES_FOR_PER90
 └── utils/
     ├── gameweek.py                # is_opening_gameweek(gw) — shared GW1 check (transfers, waivers and league tables don't exist yet)

{fplkit-2.5.0 → fplkit-2.6.0}/docs/command-reference.md

@@ -96,6 +96,15 @@ about: the block is read on nearly every command, so the envelope naming it can
 from `fpl status` or `fpl league-recap` as readily as from `fpl league-fines`, and the
 message names the rule and the valid set.
 
+A relative `FPL_CLI_CONFIG_DIR` / `FPL_CLI_DATA_DIR` / `FPL_CLI_CACHE_DIR` override is
+rejected before any command runs, so this one case has no parsed `--format` to read when it
+fails — the CLI scans the raw command line for `--format json` instead. The envelope's
+`command` names your subcommand where that is unambiguous (`fpl status`, or a bare group like
+`fpl chips`), and falls back to `"fpl"` for a subgroup's own subcommand (`fpl chips timing`,
+`fpl squad grid`, `fpl intel show`) or a line that was nothing but options — those commands
+don't name their own envelope after either word you typed, and guessing wrong would be worse
+than saying so.
+
 **Table mode splits the same way.** Without `--format json` the output you asked for goes
 to stdout and everything else goes to stderr — warnings, progress notices, and the reason
 a command exited nonzero. `fpl squad grid 2>/dev/null` prints a grid or prints nothing;
@@ -556,7 +565,7 @@ These metrics appear in `fpl player`, `fpl xg`, and gameweek reports. If Underst
 
 **When a whole club fails to join.** FPL and Understat spell some clubs differently, so a `TEAM_NAME_MAP` gap costs one club's entire squad its npxG, xGChain and every score built on them, while the other 19 look fine. The commands that enrich from the live league payload — `fpl stats --value`, `fpl player`, `fpl allocate`, `fpl xg`, `fpl targets`, `fpl differentials` — report it once per club: on stderr in table mode, and as an `understat_team_unmatched` entry in JSON `metadata.warnings`, one per club, naming both the FPL club and the Understat name it was mapped to. `fpl doctor --providers` checks the same thing ahead of time. A club missing from a *past* season's payload is not this: `fpl returnees` scores a player's current club against the season they played, so the three clubs promoted since are absent from it every year by definition, and that stays a debug line rather than a warning about a map that is fine.
 
-**When one player fails to join.** A player whose club Understat *does* carry can still fail to match on name, and that is not always a defect: Understat has not ingested the gameweek in progress, spells a transliterated name differently, or simply has no row for the player. Those read as `null` quality and value scores rather than as zeros, so the player is ranked as "no data" rather than as bad. A few percent of a club's players missing this way is normal and stays a debug line naming each one with a running rate (`No Understat row matched ... — 3 of 351 FPL players with minutes unmatched so far this run`); the rate is what to watch, since a jump in it means the two sources have stopped agreeing about names rather than that one more cameo went un-ingested. `fpl doctor --providers` reports the same rate as an `Understat name join` row, which is where to look for it without turning on debug logging. Understat serves apostrophes HTML-escaped (`O'Shea`), which used to fail every apostrophe name silently; the payload is now decoded when it is fetched.
+**When one player fails to join.** A player whose club Understat *does* carry can still fail to match on name, and that is not always a defect: Understat has not ingested the gameweek in progress, names the player outright differently (FPL's `A.Becker` is Understat's `Alisson`), or simply has no row for them. Those read as `null` quality and value scores rather than as zeros, so the player is ranked as "no data" rather than as bad. A name the two sources merely *spell* differently does join, through a last-resort pass that stays inside the player's club and needs their minutes to agree and no second candidate: a transliteration variant (`Yarmoliuk` and `Yehor Yarmolyuk`), a double-barrelled or middle name one source drops (`Gannon-Doak` and `Ben Doak`, `Walle Egeli` and `Sindre Egeli`), or a mononym inside a longer name (`Jair Cunha` and `Jair`). A shared word alone is never enough — `João Pedro` and `Pedro Neto` share one — so a player whose row is genuinely missing stays `null` rather than wearing a club-mate's numbers. A few percent of a club's players missing this way is normal and stays a debug line naming each one with a running rate (`No Understat row matched ... — 3 of 351 FPL players with minutes unmatched so far this run`); the rate is what to watch, since a jump in it means the two sources have stopped agreeing about names rather than that one more cameo went un-ingested. `fpl doctor --providers` reports the same rate as an `Understat name join` row, which is where to look for it without turning on debug logging. Understat serves apostrophes HTML-escaped (`O'Shea`), which used to fail every apostrophe name silently; the payload is now decoded when it is fetched.
 
 #### Quality and Value Scores
 
@@ -769,13 +778,17 @@ on a run with no fixture data, is reported alongside the completeness findings b
 stderr, and as a warning callout in the saved report.
 
 **Incomplete summaries:** the personal analysis is checked against the sections its own prompt
-asked for before anything is written. A response that is missing a `## ` heading, ends without
-terminal punctuation, or that the provider reports it stopped early on is retried **once** — and
-if the second attempt is no better, the first one stands and the run says so on stderr, naming
-what is missing. Under `--debug` the detail lands in `data/debug/synthesis_corrections.txt`
-alongside `research_corrections.txt`. A saved report generated from such a response carries the
-same list as a warning callout above the summary, so a verdict the model dropped never reads as
-one deliberately omitted. A verdict for a format the run has no squad data for is not counted as
+asked for before anything is written. A response that comes back empty, is missing a `## `
+heading, ends without terminal punctuation, or that the provider reports it stopped early on is
+retried **once** — and if the second attempt is no better, the less damaged of the two stands
+and the run says so on stderr, naming what is missing. Under `--debug` the detail lands in
+`data/debug/synthesis_corrections.txt` alongside `research_corrections.txt`. A saved report
+generated from such a response carries the same list as a warning callout above the summary, so
+a verdict the model dropped never reads as one deliberately omitted. The callout does not depend
+on there being a summary to qualify: a response that returned no text at all — the shape a hard
+`max_tokens` truncation takes when the model was still thinking at the ceiling — is the one that
+most needs explaining, and is reported as a single "the response is empty" finding rather than
+as every section it happens to be short of. A verdict for a format the run has no squad data for is not counted as
 missing — the prompt tells the model to analyse only the format it was given.
 
 **Blanks and doubles:** a zero from a player whose club had no fixture is marked `[BGW]` rather
@@ -1291,6 +1304,8 @@ Rolling a setup into a new season silently invalidates IDs and per-team files: a
 
 **Environment** — which directory each of config/data/cache resolved to and whether an `FPL_CLI_*` override is in effect, plus whether `settings.yaml` exists.
 
+**Which season it is** — the season doctor reports in `metadata.season`, and judges "a previous season's" against, comes from GW1's `deadline_time` where the API answers and the July cutover only where it does not — the same rule `fpl status` uses, so the two commands cannot name different seasons for the same moment. A season that overruns 1 July (2019-20, COVID-delayed) therefore keeps its own label in both, and a `team_finances.json` scraped during that overrun reads as current rather than as a previous season's.
+
 Each finding is classified as **broken** (wrong answers now — fix it today), **stale** (self-corrects or needs one routine refresh), **skipped** (not configured/present), or **unchecked** (API unreachable). Exits non-zero when anything is broken, so it can gate scripts.
 
 **`--providers`** checks the external data sources instead of the local setup. None of them version anything, and the tool degrades gracefully everywhere, so upstream drift otherwise surfaces as plausible but wrong output — a renamed stat field zeroes every player's xG without an error. Each probe asserts shape and volume, not just reachability, and where a column check is not the contract it runs the parser itself:

{fplkit-2.5.0 → fplkit-2.6.0}/fpl_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.5.0'
-__version_tuple__ = version_tuple = (2, 5, 0)
+__version__ = version = '2.6.0'
+__version_tuple__ = version_tuple = (2, 6, 0)
 
 __commit_id__ = commit_id = None

{fplkit-2.5.0 → fplkit-2.6.0}/fpl_cli/api/providers/_models.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+from collections.abc import Sequence
 from dataclasses import dataclass, field
 
 logger = logging.getLogger(__name__)
@@ -97,3 +98,27 @@ def log_abnormal_stop(response: LLMResponse, label: str) -> None:
         "the response may be cut off",
         label, response.stop_reason, response.usage.output_tokens,
     )
+
+
+def log_textless_response(
+    response: LLMResponse, label: str, non_text_blocks: Sequence[str],
+) -> None:
+    """Announce a response whose content was blocks, none of them text.
+
+    A model that reasons before it answers emits its thinking first, so a
+    ceiling reached mid-thought returns content with no prose block in it at
+    all. The concatenated text is then `""` -- honest, but indistinguishable
+    downstream from a model that had nothing to say. Naming the blocks that
+    did arrive is what separates the two for anyone reading stderr (#306).
+
+    `non_text_blocks` is the types of the blocks that were *not* text, so an
+    answer of nothing but an empty text block stays silent: that is a model
+    with nothing to say, which is the case this has nothing to add to.
+    `log_abnormal_stop` has already spoken if it was cut off.
+    """
+    if response.content or not non_text_blocks:
+        return
+    logger.warning(
+        "%s returned no text content -- the response carried only %s block(s)",
+        label, ", ".join(sorted(set(non_text_blocks))),
+    )

{fplkit-2.5.0 → fplkit-2.6.0}/fpl_cli/api/providers/anthropic.py

@@ -8,7 +8,13 @@ from typing import Any, ClassVar, Self
 import httpx
 
 from fpl_cli.api.providers._http import RetryPolicy, post_json_with_retry
-from fpl_cli.api.providers._models import LLMResponse, ProviderError, TokenUsage, log_abnormal_stop
+from fpl_cli.api.providers._models import (
+    LLMResponse,
+    ProviderError,
+    TokenUsage,
+    log_abnormal_stop,
+    log_textless_response,
+)
 
 _BASE_URL = "https://api.anthropic.com/v1"
 _PROVIDER_LABEL = "Anthropic"
@@ -81,10 +87,21 @@ class AnthropicProvider:
             label=_PROVIDER_LABEL, policy=self.RETRY_POLICY,
         )
 
+        # Only text blocks carry prose, but the types that were *not* text are
+        # worth keeping: a ceiling reached while the model was still thinking
+        # returns a lone `thinking` block, and the empty string that falls out
+        # of this loop is otherwise indistinguishable from a model with
+        # nothing to say (#306). Text blocks are deliberately not collected --
+        # a response of nothing but an empty text block *is* a model with
+        # nothing to say, and naming "text" as the reason there was no text
+        # would contradict itself.
         content = ""
+        non_text_blocks: list[str] = []
         for block in data.get("content", []):
             if block.get("type") == "text":
                 content += block.get("text", "")
+            else:
+                non_text_blocks.append(str(block.get("type")))
 
         # Normalise usage: Anthropic returns input_tokens/output_tokens directly
         raw_usage = data.get("usage", {})
@@ -105,6 +122,7 @@ class AnthropicProvider:
             stop_reason=data.get("stop_reason") or None,
         )
         log_abnormal_stop(response, _PROVIDER_LABEL)
+        log_textless_response(response, _PROVIDER_LABEL, non_text_blocks)
         return response
 
     def post_process(self, content: str) -> str:

{fplkit-2.5.0 → fplkit-2.6.0}/fpl_cli/api/understat.py

@@ -491,6 +491,31 @@ def _normalise(text: str) -> str:
     return re.sub(r" +", " ", text).strip()  # Collapse whitespace
 
 
+# A consonant written twice, once `y` and `j` have already folded to `i`.
+_DOUBLED_CONSONANT_RE = re.compile(r"([b-df-hk-np-tv-xz])\1")
+
+
+@lru_cache(maxsize=4096)
+def _fold_transliteration(name_norm: str) -> str:
+    """Collapse the spellings a Latin transliteration commonly varies between.
+
+    Applied to an already-normalised name on *both* sides of a comparison, so
+    a pair that differs only by the fold compares equal: ``yarmoliuk`` and
+    ``yarmolyuk`` both fold to ``iarmoliuk`` (#310). The folds are #310's
+    list of the variants a Ukrainian transliteration commonly turns on --
+    ``y``/``i`` (``j`` too, which also covers ``ye`` against ``ie``),
+    ``kh``/``h``, and a doubled consonant -- of which only ``y``/``i`` has
+    caused a miss so far. Each coarsens both names rather than guessing at
+    the right spelling of either, so the result is a blunter key, never a
+    corrected name; a Western name the fold also touches ("Markham" to
+    "marham") can only meet a same-club row whose fold is the same, with
+    minutes agreeing, after every strict tier has failed both.
+    """
+    folded = name_norm.replace("kh", "h")
+    folded = re.sub(r"[yj]", "i", folded)
+    return _DOUBLED_CONSONANT_RE.sub(r"\1", folded)
+
+
 def split_team_titles(team_title: str) -> list[str]:
     """Split an Understat ``team_title`` into its constituent club names.
 
@@ -538,15 +563,32 @@ _NAME_EXACT = 10
 _NAME_ALL_WORDS = 8
 _NAME_PREFIX = 7
 
-# The lowest tier the club-gated pass will admit. It is every tier there is
-# today, and deliberately named rather than left implicit: a future
-# lower-confidence tier has to raise this floor to opt itself out.
+# The loose tiers (#310). Every tier above needs each FPL word found in the
+# Understat name, and that asymmetry is what keeps "João Pedro" off "Pedro
+# Neto" when the two share a club: a word FPL carries that Understat does not
+# usually means a different person. Usually. It also fails a player the two
+# sources simply name differently -- FPL's "Gannon-Doak" is Understat's "Ben
+# Doak", "Walle Egeli" its "Sindre Egeli", "Jair Cunha" its mononym "Jair" --
+# and a transliteration they spell differently ("Yarmoliuk" against "Yehor
+# Yarmolyuk", "Yeremy" against "Yeremi Pino"), which no prefix survives
+# because the divergence is mid-word. These sit below the floor, so neither
+# the club pass nor the club-blind pass admits them; only the last-resort
+# `_match_loosely_within_club` does, and it demands the club, the minutes and
+# an unambiguous answer -- more corroboration than the strict tiers ask for.
+# A shared word alone is not a tier: "Van Hecke" and "van de Ven" share one.
+_NAME_TRANSLITERATED = 5  # exact or all-words once transliteration variants fold
+_NAME_PARTIAL = 4  # surname agrees, or Understat's shorter name sits inside FPL's
+
+# The lowest tier the club-gated pass will admit: the strict tiers, and only
+# them. The loose floor is what the last-resort pass admits instead.
 _NAME_TIER_FLOOR = _NAME_PREFIX
+_NAME_LOOSE_FLOOR = _NAME_PARTIAL
 
-# How closely the two sources must agree on minutes before a club-blind match
-# is allowed to stand. Both count the same league's minutes, so a real match
-# agrees closely and a namesake at another club usually does not.
-_CROSS_CLUB_MIN_MINUTES_RATIO = 0.5
+# How closely the two sources must agree on minutes before a match missing one
+# of its usual corroborations -- the club, or the full name -- is allowed to
+# stand. Both count the same league's minutes, so a real match agrees closely
+# and a namesake usually does not.
+_CORROBORATING_MIN_MINUTES_RATIO = 0.5
 
 # FPL teams already reported as matching no Understat players, so the join-drop
 # warning below fires once per team per process rather than once per player.
@@ -742,6 +784,68 @@ def _minutes_ratio(fpl_minutes: int | None, player: dict[str, Any]) -> float | N
     return min(fpl_minutes, us_minutes) / high
 
 
+def _initials_agree(fpl_words: list[str], us_words: list[str]) -> bool:
+    """Whether every one-letter FPL word is the initial of a word Understat spells out.
+
+    FPL abbreviates a first name to its initial exactly when a surname is
+    shared -- ``J.Ramsey`` beside ``A.Ramsey`` -- so the initial is FPL's
+    own statement of which one this is, and a loose tier that ignored it
+    would join ``J.Ramsey`` to ``Aaron Ramsey`` the week Jacob's row is
+    missing. A full word absent from Understat is a name it dropped; an
+    initial it contradicts is a different player.
+    """
+    return all(
+        len(word) > 1 or any(us_word.startswith(word) for us_word in us_words)
+        for word in fpl_words
+    )
+
+
+def _name_tier(fpl_name_norm: str, fpl_words: list[str], understat_name: str) -> int:
+    """The confidence tier two normalised names match at, or 0 for none.
+
+    The three strict tiers first, then the loose ones (#310), which a caller
+    keeps out of its pass with a ``min_name_tier`` above them rather than by
+    asking for them not to be computed -- a tier is a fact about the two
+    names, and which tiers a pass trusts is that pass's decision.
+    """
+    us_words = understat_name.split()
+    if fpl_name_norm == understat_name:
+        return _NAME_EXACT
+    if not fpl_words:
+        return 0
+    if all(w in us_words for w in fpl_words):
+        return _NAME_ALL_WORDS
+    if all(any(uw.startswith(fw) for uw in us_words) for fw in fpl_words):
+        return _NAME_PREFIX
+
+    # Transliteration: the same two full-name tests, on both names folded.
+    folded_fpl = _fold_transliteration(fpl_name_norm)
+    folded_us = _fold_transliteration(understat_name)
+    folded_us_words = folded_us.split()
+    if folded_fpl == folded_us or all(w in folded_us_words for w in folded_fpl.split()):
+        return _NAME_TRANSLITERATED
+
+    # Partial: both sides carry a surname and agree on it ("Gannon-Doak" and
+    # "Ben Doak"), or Understat's whole, shorter name sits inside FPL's ("Jair"
+    # in "Jair Cunha") -- the direction all-words does not cover. Both shapes
+    # share the guards: the words the two names share must be words, since
+    # `_normalise` keeps digits and a shared number is a shared row index,
+    # not a shared name; and neither may override an initial FPL chose to
+    # disambiguate with, which a bare surname can never satisfy -- FPL
+    # abbreviates to an initial exactly when the surname alone is ambiguous.
+    if (
+        len(fpl_words) > 1
+        and all(w.isalpha() for w in us_words)
+        and _initials_agree(fpl_words, us_words)
+        and (
+            (len(us_words) > 1 and fpl_words[-1] == us_words[-1])
+            or all(w in fpl_words for w in us_words)
+        )
+    ):
+        return _NAME_PARTIAL
+    return 0
+
+
 def _score_candidate(
     player: dict[str, Any],
     fpl_name_norm: str,
@@ -752,33 +856,21 @@ def _score_candidate(
 ) -> tuple[int, int]:
     """Score one Understat candidate as ``(name_tier, bonus)``.
 
-    The pair is ordered lexicographically by both callers, which keeps the
+    The pair is ordered lexicographically by every caller, which keeps the
     position and minutes bonuses as tiebreakers *within* a name tier instead of
     letting them promote a looser name match above a stronger one.
 
     A tier of 0 means "not a candidate": no viable name match, or one below
-    ``min_name_tier``. Every field is read defensively — the fallback pass
+    ``min_name_tier``. Every field is read defensively — the club-blind pass
     scores rows belonging to clubs the caller never asked about, so one
     malformed row in an undocumented payload must not take out the lookup.
     """
     understat_name = _normalise(str(player.get("name") or ""))
     if not understat_name:
         return 0, 0
-    us_words = understat_name.split()
-
-    # Word-overlap name scoring
-    if fpl_name_norm == understat_name:
-        tier = _NAME_EXACT
-    elif fpl_words and all(w in us_words for w in fpl_words):
-        tier = _NAME_ALL_WORDS
-    elif fpl_words and all(
-        any(uw.startswith(fw) for uw in us_words) for fw in fpl_words
-    ):
-        tier = _NAME_PREFIX
-    else:
-        return 0, 0
 
-    if tier < min_name_tier:
+    tier = _name_tier(fpl_name_norm, fpl_words, understat_name)
+    if tier < min_name_tier:  # 0 is below every floor
         return 0, 0
 
     bonus = 0
@@ -803,38 +895,30 @@ def _score_candidate(
     return tier, bonus
 
 
-def _match_across_clubs(
+def _best_corroborated_match(
+    candidates: list[dict[str, Any]],
     fpl_name_norm: str,
     fpl_words: list[str],
-    understat_players: list[dict[str, Any]],
     fpl_position: str | None,
     fpl_minutes: int | None,
+    min_name_tier: int,
+    pass_name: str,
 ) -> dict[str, Any] | None:
-    """Match on name alone, for a player the club gate rejected outright (#234).
+    """The one candidate a pass missing its usual corroboration can stand on.
 
-    An Understat ``team_title`` names only the clubs a player has actually
-    turned out for, so a deadline-day mover who has not yet featured for their
-    new club carries the old club alone while FPL already lists them at the new
-    one. #151's comma-joined title never forms, every candidate fails the gate,
-    and they read as having no Understat data at all through exactly the weeks
-    people are deciding whether to buy.
-
-    Dropping the gate re-opens the homonym risk it existed to close, so this
-    pass is deliberately narrow. Only a full-name match counts (exact, or every
-    FPL word present — no prefix tier). Minutes must corroborate where both
-    sources report them, since a namesake at another club rarely has a season
-    the same length. A top pair two candidates share is refused rather than
-    guessed at. The caller adds the last condition: it only reaches here for a
-    club Understat *does* carry players for, so an unresolved club still fails
-    as a block rather than 20 players each guessing across the league.
+    Shared by the two fallback passes, which each relax a different thing --
+    the club-blind pass the club, the loose pass the name -- and so lean on
+    the same substitutes: minutes must corroborate where both sources report
+    them, since a namesake rarely has a season the same length, and a top
+    score two candidates share is refused rather than guessed at.
     """
     best_match: dict[str, Any] | None = None
     best_score = (0, 0)
     ambiguous = False
 
-    for player in understat_players:
+    for player in candidates:
         ratio = _minutes_ratio(fpl_minutes, player)
-        if ratio is not None and ratio < _CROSS_CLUB_MIN_MINUTES_RATIO:
+        if ratio is not None and ratio < _CORROBORATING_MIN_MINUTES_RATIO:
             continue
         score = _score_candidate(
             player,
@@ -842,7 +926,7 @@ def _match_across_clubs(
             fpl_words,
             fpl_position,
             fpl_minutes,
-            min_name_tier=_NAME_ALL_WORDS,
+            min_name_tier=min_name_tier,
         )
         if score[0] == 0:
             continue
@@ -853,15 +937,86 @@ def _match_across_clubs(
 
     if ambiguous:
         logger.debug(
-            "Understat name %r matches several players outside the FPL club — "
+            "Understat name %r has several equally good %s candidates — "
             "declining rather than guessing",
             fpl_name_norm,
+            pass_name,
         )
         return None
 
     return best_match
 
 
+def _match_across_clubs(
+    fpl_name_norm: str,
+    fpl_words: list[str],
+    understat_players: list[dict[str, Any]],
+    fpl_position: str | None,
+    fpl_minutes: int | None,
+) -> dict[str, Any] | None:
+    """Match on name alone, for a player the club gate rejected outright (#234).
+
+    An Understat ``team_title`` names only the clubs a player has actually
+    turned out for, so a deadline-day mover who has not yet featured for their
+    new club carries the old club alone while FPL already lists them at the new
+    one. #151's comma-joined title never forms, every candidate fails the gate,
+    and they read as having no Understat data at all through exactly the weeks
+    people are deciding whether to buy.
+
+    Dropping the gate re-opens the homonym risk it existed to close, so this
+    pass is deliberately narrow. Only a full-name match counts (exact, or every
+    FPL word present — no prefix tier, and none of the loose ones). Minutes
+    must corroborate and a shared top score is refused, as
+    `_best_corroborated_match` describes. The caller adds the last condition:
+    it only reaches here for a club Understat *does* carry players for, so an
+    unresolved club still fails as a block rather than 20 players each
+    guessing across the league.
+    """
+    return _best_corroborated_match(
+        understat_players,
+        fpl_name_norm,
+        fpl_words,
+        fpl_position,
+        fpl_minutes,
+        min_name_tier=_NAME_ALL_WORDS,
+        pass_name="club-blind",
+    )
+
+
+def _match_loosely_within_club(
+    fpl_name_norm: str,
+    fpl_words: list[str],
+    club_rows: list[dict[str, Any]],
+    fpl_position: str | None,
+    fpl_minutes: int | None,
+) -> dict[str, Any] | None:
+    """Match a player the two sources name differently, inside their club (#310).
+
+    The last resort, and ordered last on purpose: it runs only once the strict
+    tiers have failed within the club *and* the full-name pass has failed
+    across it, so a mover whose Understat row still shows the old club under
+    the full name reaches the club-blind pass before a same-surname teammate
+    at the new club can claim them here.
+
+    It admits the tiers below the floor -- a name that agrees once
+    transliteration variants fold, a shared surname beside a name one source
+    omits, a mononym inside a longer name -- and never leaves the club, since
+    across the league a shared surname is a namesake far more often than a
+    spelling. Minutes must corroborate and a shared top score is refused, as
+    `_best_corroborated_match` describes. The caller keeps it to the live
+    pool, where the club a row carries is the club being asked about.
+    """
+    return _best_corroborated_match(
+        club_rows,
+        fpl_name_norm,
+        fpl_words,
+        fpl_position,
+        fpl_minutes,
+        min_name_tier=_NAME_LOOSE_FLOOR,
+        pass_name="loose same-club",
+    )
+
+
 def match_fpl_to_understat(
     fpl_name: str,
     fpl_team: str,
@@ -876,13 +1031,17 @@ def match_fpl_to_understat(
     position and minutes played, and returns the most confident. A player whose
     own club carries no name match at all falls through to the name-only pass
     in ``_match_across_clubs`` (#234) — but only when the club itself resolved,
-    so a club no Understat row carries keeps failing as a block. Returns None
-    when neither pass is confident.
+    so a club no Understat row carries keeps failing as a block — and, failing
+    that too and only in the live pool, to ``_match_loosely_within_club``
+    (#310), which admits the looser name tiers back inside the club. Returns
+    None when no pass is confident.
 
     *season_label* names the season ``understat_players`` covers when that is
     not the one in progress; leaving it None says the pool is the live one. It
-    only steers the join-drop tripwire — see ``_report_unmatched_team`` for why
-    an absent club means something different in a past season's pool.
+    steers the join-drop tripwire — see ``_report_unmatched_team`` for why an
+    absent club means something different in a past season's pool — and
+    withholds the loose pass, whose club corroboration a past pool cannot
+    give: the club matched there is the player's current one.
     """
     fpl_name_norm = _normalise(fpl_name)
     fpl_words = fpl_name_norm.split()
@@ -890,18 +1049,14 @@ def match_fpl_to_understat(
 
     best_match = None
     best_score = (0, 0)
-    team_seen = False
-
-    for player in understat_players:
-        # The same gate `understat_club_rows` (and so `fpl doctor`) applies, so
-        # the health check and the enrichment can never disagree about which
-        # clubs resolve. Season totals stay cumulative across both clubs of a
-        # mid-season move, which is what the minutes bonus wants — FPL's
-        # minutes are cumulative too.
-        if not _carries_club(player.get("team"), fpl_team_mapped):
-            continue
-        team_seen = True
 
+    # The gate `fpl doctor` probes through, so the health check and the
+    # enrichment can never disagree about which clubs resolve. Season totals
+    # stay cumulative across both clubs of a mid-season move, which is what
+    # the minutes bonus wants — FPL's minutes are cumulative too.
+    club_rows = understat_club_rows(fpl_team, understat_players)
+
+    for player in club_rows:
         score = _score_candidate(
             player,
             fpl_name_norm,
@@ -914,10 +1069,10 @@ def match_fpl_to_understat(
             best_score = score
             best_match = player
 
-    if not team_seen and understat_players:
+    if not club_rows and understat_players:
         _report_unmatched_team(fpl_team, fpl_team_mapped, season_label)
 
-    if not team_seen:
+    if not club_rows:
         # Nothing carries this club, so every one of its players fails here
         # identically — a TEAM_NAME_MAP gap or a roster Understat has yet to
         # ingest, not a transfer. Sending 20 players off to guess across the
@@ -933,5 +1088,16 @@ def match_fpl_to_understat(
             fpl_name_norm, fpl_words, understat_players, fpl_position, fpl_minutes
         )
 
+    if best_match is None and season_label is None:
+        # Neither the strict tiers inside the club nor the full name across
+        # it: the two sources may simply spell this player differently. Live
+        # pool only. A past season's pool is matched against the player's
+        # *current* club, and for the mover that path calls its common case
+        # the club is the one corroboration the loose tiers lean on -- they
+        # would be scanning the current club's old roster for a surname twin.
+        best_match = _match_loosely_within_club(
+            fpl_name_norm, fpl_words, club_rows, fpl_position, fpl_minutes
+        )
+
     _record_name_join(fpl_name, fpl_team, fpl_minutes, best_match, season_label)
     return best_match