fplkit 2.6.0__tar.gz → 2.6.1__tar.gz

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

@@ -1,6 +1,19 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [2.6.0] - 2026-09-07
+
+### Bug Fixes
+
+- drop ratings update's dead -v hint for a kept prior (#311)
+- carry the --format json envelope through a relative FPL_CLI_* rejection (#312)
+- derive `fpl doctor`'s season from GW1's deadline like `fpl status` (#314)
+- warn in the saved review when the summary came back empty (#313)
+
+### Features
+
+- join Understat rows for players the two sources spell differently (#315)
+
 ## [2.5.0] - 2026-09-07
 
 ### Bug Fixes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fplkit
-Version: 2.6.0
+Version: 2.6.1
 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.6.0 → fplkit-2.6.1}/docs/architecture.md

@@ -572,7 +572,7 @@ fpl_cli/
 │   │   ├── shrinkage.py          # Single-GW early-season shrinkage + the shared hold-out helpers
 │   │   └── data_prep.py          # ScoringContext / ScoringData + prepare_scoring_data()
 │   ├── player_prior.py           # Player prior (Bayesian early-season confidence)
-│   ├── team_ratings.py           # TeamRatingsService + Calculator (1-7 scale)
+│   ├── team_ratings.py           # TeamRatingsService + Calculator (1-7 scale). The service judges the file's `metadata.season` stamp against the season it is told is in progress, discarding a previous season's ratings outright (they rate relegated clubs, and serving them is worse than serving none) — which means the season it uses has to be the resolved one, not the clock: an overrunning season had its own live ratings thrown away from 1 July, dropping every fixture to a neutral 4.0 mid-season (#318). `ensure_fresh(client)` resolves it from GW1's deadline before anything else and re-reads if a property access already forced a load on the clock; `fpl doctor` passes the label it resolved; writes are stamped with the same season, so a file written during an overrun is not stamped into the future
 │   ├── team_ratings_prior.py     # Previous-season prior + Bayesian blending (cutoff GW12); every pool it reads (the PL pool from either source, the Championship division) takes full-season records only, and every club's basis is written to the cache as `inputs`. The cache is invalidated by the methodology version, the league's club list, and a one-directional provenance check (`_inputs_have_improved`) that rebuilds only when an input the cached run lacked is available now — so setting `FOOTBALL_DATA_API_KEY` reaches the promoted sides without the file being deleted (#112). A rebuild is then held to `_is_worse_than_cache` (source rank and count of clubs on an estimate) before it may replace the cached prior, and `_record_attempt` stamps the file either way so a down provider costs one retry, not one per command
 │   ├── matchup.py                # Fixture matchup scoring (0-10)
 │   ├── fixture_predictions.py    # BGW/DGW predictions from YAML + live detection, plus the point-in-time "did his club have a fixture, and how many" read a past gameweek needs

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

@@ -412,7 +412,7 @@ A club that has played only one venue is rated on it. Once GW1 finishes, every c
 
 Early-season results are shrunk toward that previous-season prior, by the automatic refresh and by `fpl ratings update` alike: a one-gameweek sample carries 1/7 of the weight, six gameweeks half, and the prior drops out entirely once GW12 has completed. Shrinkage is gated on how far the season has run, so a narrow window late on is not blended -- `--since-gw 30` at GW34 saves recent form alone. Inside the early-season window the weight follows the size of that window rather than the gameweek number, so `--since-gw 8` at GW10 is weighted as three gameweeks of evidence. Blended files are stamped `calculated_blended` / `understat_xg_blended` / `auto_calculated_blended` so `fpl ratings` shows that shrinkage was applied. While the sample is shorter than six gameweeks the prior still carries most of the weight, and every fixture-difficulty view says so - `Ratings are mostly last season's prior - 1 gameweek of results carries 14% of the weight`. That replaces the pre-season estimate warning, which stops applying the moment a gameweek completes.
 
-Ratings are tied to the season that produced them. A file carried across a season boundary is ignored rather than served, because it rates the three relegated clubs and knows nothing about the three promoted ones. Ratings that cover the wrong set of clubs are called out by name — `team_ratings.yaml is missing COV, HUL, IPS and still rates BUR, WHU, WOL` — which catches a rollover that a "days old" check cannot: a file rebuilt in early August is new by date and still describes last season's league.
+Ratings are tied to the season that produced them. A file carried across a season boundary is ignored rather than served, because it rates the three relegated clubs and knows nothing about the three promoted ones. Which season is "in progress" comes from GW1's deadline, not the July clock, so a season overrunning 1 July keeps its own ratings instead of having them discarded with a third of the run-in still to play. Ratings that cover the wrong set of clubs are called out by name — `team_ratings.yaml is missing COV, HUL, IPS and still rates BUR, WHU, WOL` — which catches a rollover that a "days old" check cannot: a file rebuilt in early August is new by date and still describes last season's league.
 
 See [Team Ratings](custom-analysis.md#team-ratings) for calculation methodology, axes, early-season blending, pre-season estimates, and manual overrides.
 
@@ -791,6 +791,11 @@ most needs explaining, and is reported as a single "the response is empty" findi
 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.
 
+A call that never lands at all — a timeout, a 500, a 429 that outlasted its retries, a revoked
+key — is reported through the same callout, naming the failure. The run still exits **0** with
+the rest of the review intact, but the saved report says the analysis was attempted and lost
+rather than leaving a reader to wonder whether the template ever had one.
+
 **Blanks and doubles:** a zero from a player whose club had no fixture is marked `[BGW]` rather
 than read as a choice that failed, and such a player is kept off the Blankers list entirely; a
 player whose club played twice is marked `[DGW]`. Which clubs those were is read off the
@@ -1291,7 +1296,7 @@ Rolling a setup into a new season silently invalidates IDs and per-team files: a
 
 **Data files:**
 
-- `team_ratings.yaml` — season stamp and team set vs the live league (problems here are stale, not broken: the ratings service already ignores or rebuilds bad files)
+- `team_ratings.yaml` — season stamp and team set vs the live league, judged against the same resolved season the report names (problems here are stale, not broken: the ratings service already ignores or rebuilds bad files)
 - `team_managers.yaml` — merged shipped + user copy covers exactly the current twenty clubs
 - `previews/` — optional season preview intel: a file for a club not in the current league is flagged (it loads and inflates the coverage gate), and files the loader skipped (previous season, malformed) are surfaced with `fpl intel` as the follow-up
 - `team_finances.json` — `scraped_at` falls within the current season
@@ -1413,7 +1418,7 @@ llm:
     model: claude-sonnet-5
     timeout: 60
     query_defaults:
-      max_tokens: 4096
+      max_tokens: 8000
 ```
 
 ### LLM Providers

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

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

{fplkit-2.6.0 → fplkit-2.6.1}/fpl_cli/cli/_review_summarisation.py

@@ -208,6 +208,21 @@ def _report_synthesis_completeness(
     if debug_dir is None:
         error_console.print("[dim]    Re-run with --debug to save the detail[/dim]")
         return None
+    return _write_synthesis_corrections(problems, debug_dir)
+
+
+def _write_synthesis_corrections(
+    problems: Sequence[str], debug_dir: Path | None,
+) -> str | None:
+    """Save the problem lines to `synthesis_corrections.txt`; return its path.
+
+    Shared by both paths that produce problems, so a `--debug` bundle carries
+    the same artefact whether the response came back damaged or the call never
+    returned at all -- an asymmetry there is one more thing to reason about
+    when reading someone's bug report. `None` when the run has no debug dir.
+    """
+    if debug_dir is None:
+        return None
     corrections_file = debug_dir / "synthesis_corrections.txt"
     corrections_file.write_text("\n".join(problems) + "\n", encoding="utf-8")
     error_console.print("[dim]    → Saved synthesis_corrections.txt[/dim]")
@@ -1142,22 +1157,50 @@ async def _review_llm_summarise(
             synthesis_summary = ""
             console.print("[green]  ✓[/green] Prompts saved to data/debug/")
         else:
+            console.print("[dim]  Generating personal analysis...[/dim]")
+            # The prompt asks for both formats' verdicts unconditionally, but
+            # it also tells the model to analyse only the format it was given
+            # data for -- so a verdict the run has no squad behind is an
+            # instructed omission, not a section the guard should chase.
+            omit_sections = [
+                *([] if team_points_data else ["Classic Verdict"]),
+                *([] if draft_squad_points_data else ["Draft Verdict"]),
+            ]
+            # The call, and only the call. Graceful degradation is for the
+            # things a provider does to us -- a timeout, a 500, a spent 429, a
+            # revoked key -- and everything downstream of the response is our
+            # own code: a bug in the grounding checker or an unwritable debug
+            # dir surfaces as a traceback rather than being reported as a
+            # failure of a call that in fact returned. A wider `try` would also
+            # throw away the good summary it had already been handed (#322
+            # review).
             try:
-                console.print("[dim]  Generating personal analysis...[/dim]")
-                # The prompt asks for both formats' verdicts unconditionally, but
-                # it also tells the model to analyse only the format it was given
-                # data for -- so a verdict the run has no squad behind is an
-                # instructed omission, not a section the guard should chase.
-                omit_sections = [
-                    *([] if team_points_data else ["Classic Verdict"]),
-                    *([] if draft_squad_points_data else ["Draft Verdict"]),
-                ]
                 synthesis_summary, completeness, attempts = await _synthesise_with_completeness_check(
                     synthesis_provider,
                     prompt=synthesis_prompt,
                     system_prompt=synthesis_system,
                     omit_sections=omit_sections,
                 )
+            except Exception as e:  # noqa: BLE001 — graceful degradation
+                error_console.print(f"[red]  ✗ Synthesis failed: {rich_escape(str(e))}[/red]")
+                synthesis_summary = ""
+                # The report has to carry it too. Degrading gracefully ends at
+                # stderr, which is gone by the time the file is read: with no
+                # summary and no callout, a call that never landed reads as a
+                # report that never had a personal analysis in it. That is the
+                # silence #306 closed for a call that returned nothing, reached
+                # by the other route (#317). Whitespace is collapsed because
+                # the callout renders each line as a blockquote bullet, and a
+                # provider error wrapped across lines would break out of it.
+                message = " ".join(str(e).split())
+                # A bare `raise SomeError()` has no message, and "SomeError:"
+                # with nothing after the colon reads as truncated output.
+                detail = f"{type(e).__name__}: {message}" if message else type(e).__name__
+                synthesis_problems = [f"the synthesis call failed ({detail})"]
+                synthesis_corrections_path = _write_synthesis_corrections(
+                    synthesis_problems, debug_dir if debug else None,
+                )
+            else:
                 # The grounding guard rides the same channel as the completeness
                 # one: both answer "is this response usable as written", and a
                 # reader weeks later needs them in the same place -- stderr now,
@@ -1179,9 +1222,6 @@ async def _review_llm_summarise(
                     (debug_dir / "synthesis_prompt.txt").write_text(synthesis_prompt, encoding="utf-8")
                     (debug_dir / "synthesis_response.txt").write_text(synthesis_summary, encoding="utf-8")
                     console.print("[dim]    → Saved synthesis_*.txt[/dim]")
-            except Exception as e:  # noqa: BLE001 — graceful degradation
-                error_console.print(f"[red]  ✗ Synthesis failed: {rich_escape(str(e))}[/red]")
-                synthesis_summary = ""
 
     return {
         "research_summary": research_summary,

{fplkit-2.6.0 → fplkit-2.6.1}/fpl_cli/cli/doctor.py

@@ -375,11 +375,15 @@ async def _draft_entry_check(
 # ---------------------------------------------------------------------------
 
 
-def _team_ratings_check(teams: list[str] | None) -> CheckResult:
+def _team_ratings_check(teams: list[str] | None, season: str) -> CheckResult:
     from fpl_cli.services.team_ratings import TeamRatingsService
 
     name = "team_ratings.yaml"
-    service = TeamRatingsService()
+    # The resolved season, not the clock (#318): doctor mirrors the service's
+    # own verdict, so handing it the label the rest of the report uses is what
+    # keeps the row from disagreeing with `metadata.season` -- and the service
+    # reaches the same verdict here as it does under a live client.
+    service = TeamRatingsService(season=season)
     if not service.config_path.exists():
         return CheckResult(
             name,
@@ -670,7 +674,7 @@ def _file_checks(teams: list[str] | None, season_year: int) -> list[CheckResult]
     that diagnosed the override) and, under --format json, the envelope.
     """
     checks: list[tuple[str, Callable[[], CheckResult]]] = [
-        ("team_ratings.yaml", lambda: _team_ratings_check(teams)),
+        ("team_ratings.yaml", lambda: _team_ratings_check(teams, season_label(season_year))),
         ("team_managers.yaml", lambda: _team_managers_check(teams)),
         ("previews/", lambda: _previews_check(teams)),
         ("team_finances.json", lambda: _team_finances_check(season_year)),

{fplkit-2.6.0 → fplkit-2.6.1}/fpl_cli/config/defaults.yaml

@@ -48,7 +48,7 @@ llm:
     model: claude-sonnet-5
     timeout: 60
     query_defaults:
-      max_tokens: 4096
+      max_tokens: 8000  # thinking + output share this ceiling (#316); 4096 left no room for prose once the model reasoned first
 
 # Fines: opt-in via settings.yaml or `fpl init`. Example config:
 #

{fplkit-2.6.0 → fplkit-2.6.1}/fpl_cli/services/team_ratings.py

@@ -224,16 +224,59 @@ class TeamRatingsService:
 
     _refreshed_this_session: ClassVar[bool] = False
 
-    def __init__(self, config_path: Path | str | None = None) -> None:
+    def __init__(
+        self, config_path: Path | str | None = None, season: str | None = None
+    ) -> None:
         # Left unresolved when not supplied so the default follows FPL_CLI_DATA_DIR
         # even if it is set after this module is imported.
         self._config_path = Path(config_path) if config_path else None
+        self._season = season
         self._ratings: dict[str, TeamRating] = {}
         self._metadata: RatingsMetadata | None = None
         self._loaded = False
         self._stale_season: str | None = None
         self._team_set_warning: str | None = None
 
+    @property
+    def season(self) -> str:
+        """The season this service treats as the one in progress.
+
+        The July-cutover clock unless a caller supplied a label resolved from
+        GW1's deadline. The distinction is load-bearing rather than cosmetic:
+        a season overrunning the cutover (2019-20, delayed into July 2020) has
+        the clock naming the *following* season from 1 July, so a ratings file
+        stamped with the live season looked like a previous season's and was
+        discarded -- taking every fixture down to a neutral 4.0 mid-season
+        (#318). `ensure_fresh` resolves it from the API; `fpl doctor` passes
+        the label it already resolved.
+        """
+        return self._season or season_label()
+
+    def _adopt_season(self, season: str) -> None:
+        """Adopt a resolved season, re-reading the file if it was judged early.
+
+        `_load_ratings` may already have run against the clock -- a property
+        read before `ensure_fresh` is enough -- and if it discarded the
+        ratings on that basis the verdict has to be retaken, not just
+        relabelled.
+
+        Everything derived from the discarded load goes with it, the team-set
+        warning included: `check_team_set` diffs the live league against
+        `self._ratings`, so a warning cached under the old season describes a
+        rating set that is no longer loaded. `ensure_fresh` happens to
+        recompute it immediately afterwards, which is not something a reset
+        contract should depend on.
+        """
+        if season == self._season:
+            return
+        self._season = season
+        if self._loaded:
+            self._ratings = {}
+            self._metadata = None
+            self._stale_season = None
+            self._team_set_warning = None
+            self._loaded = False
+
     @property
     def config_path(self) -> Path:
         """Path of the ratings YAML file this service reads and writes."""
@@ -273,7 +316,7 @@ class TeamRatingsService:
             based_on_gws = None
 
         file_season = _season_of(meta.get("season"), last_updated)
-        if file_season and file_season != season_label():
+        if file_season and file_season != self.season:
             # A file from a previous season describes a different league: it
             # still rates the relegated clubs and knows nothing about the
             # promoted ones. Serving those numbers is worse than serving none,
@@ -282,7 +325,7 @@ class TeamRatingsService:
             logger.info(
                 "Team ratings stale (season %s != %s) - ignoring",
                 file_season,
-                season_label(),
+                self.season,
             )
             self._stale_season = file_season
             self._metadata = _empty_metadata()
@@ -346,7 +389,19 @@ class TeamRatingsService:
         The team-set check runs whether or not a refresh happened: a file that
         is fresh by date can still describe last season's twenty clubs, and
         that is the mismatch a date can never catch.
+
+        Resolving the season is the first thing done, and is why every async
+        consumer routes through here: the file's own stamp is judged against
+        GW1's deadline rather than the clock, so a season overrunning 1 July
+        keeps its ratings instead of having them thrown away mid-season
+        (#318). A client that cannot answer leaves the clock in place, which
+        is the answer the service had before.
         """
+        try:
+            self._adopt_season(season_label(await client.get_season_year()))
+        except Exception:  # noqa: BLE001 — the clock is a usable fallback
+            logger.debug("Season resolution skipped; using the clock", exc_info=True)
+
         if not TeamRatingsService._refreshed_this_session:
             try:
                 await self._refresh(client)
@@ -538,7 +593,7 @@ class TeamRatingsService:
         """
         data = {
             "metadata": {
-                "season": season_label(),
+                "season": self.season,
                 "last_updated": datetime.now().strftime("%Y-%m-%d"),
                 "source": source,
                 "staleness_threshold_days": 30,
@@ -582,7 +637,7 @@ class TeamRatingsService:
             staleness_threshold_days=30,
             based_on_gws=based_on_gws,
             calculation_method=calculation_method,
-            season=season_label(),
+            season=self.season,
         )
         self._loaded = True
         # Whatever was wrong with the old file has just been replaced.
@@ -870,7 +925,7 @@ class TeamRatingsService:
 
         if self._stale_season:
             return (
-                f"⚠️ Team ratings are from {self._stale_season}, not {season_label()} - "
+                f"⚠️ Team ratings are from {self._stale_season}, not {self.season} - "
                 "they describe a different league, so they were ignored and every "
                 "fixture will score a neutral 4.0. Run `fpl ratings update`."
             )

{fplkit-2.6.0 → fplkit-2.6.1}/fpl_cli/templates/gw_review.md.j2

@@ -13,8 +13,8 @@
 {% if synthesis_problems %}
 
 > [!WARNING]
-> **This summary failed its completeness check.** Whatever is named below was lost in
-> generation, not deliberately left out:
+> **The personal analysis did not come through intact.** Whatever is named below was
+> lost on the way, not deliberately left out:
 {% for problem in synthesis_problems %}
 > - {{ problem }}
 {% endfor %}

{fplkit-2.6.0 → fplkit-2.6.1}/tests/test_cli_doctor.py

@@ -258,6 +258,101 @@ class TestSeasonResolution:
         assert "not this season's league" not in _flat(result)
 
 
+class TestDataFileRowsShareTheReportedSeason:
+    """No `data_files` row may quietly judge on the clock (#318).
+
+    #314 threaded the resolved season through the checks it touched and
+    missed `team_ratings.yaml`, which went on comparing against the clock —
+    so in an overrunning season doctor called a live file stale and told the
+    user their fixture difficulty had collapsed. This asserts the property
+    rather than the row, so the next check added on the wrong basis fails
+    here instead of shipping.
+
+    Two rows are on the clock deliberately and are listed, not exempted by
+    accident: their loaders really do discard on a clock-derived label
+    mismatch, so the row is predicting runtime behaviour.
+    """
+
+    CLOCK_DERIVED = {"player_prior.yaml", "returnee_snapshot.json"}
+
+    def test_every_row_agrees_with_metadata_season_or_is_listed(self):
+        """The API names a season a year behind the clock — an overrun."""
+        live = PREVIOUS_SEASON
+        (_data_dir() / "team_finances.json").write_text(
+            json.dumps({"scraped_at": f"{CURRENT_YEAR}-07-05T12:00:00"}), encoding="utf-8"
+        )
+        _write_snapshot(live)
+        (_data_dir() / "player_prior.yaml").write_text(
+            yaml.dump({"metadata": {"season": live, "gameweek": 38}, "priors": {}}),
+            encoding="utf-8",
+        )
+        (_data_dir() / "team_ratings.yaml").write_text(
+            yaml.dump({
+                "metadata": {
+                    "season": live,
+                    "last_updated": f"{CURRENT_YEAR}-07-01",
+                    "source": "calculated",
+                    "staleness_threshold_days": 30,
+                    "based_on_gws": [1, 36],
+                    "calculation_method": "full_season",
+                },
+                "ratings": {
+                    t: {"atk_home": 1, "atk_away": 2, "def_home": 3, "def_away": 4}
+                    for t in ("ARS", "MCI")
+                },
+            }),
+            encoding="utf-8",
+        )
+
+        result = _run(
+            _mock_client(season_year=CURRENT_YEAR - 1), args=["--format", "json"]
+        )
+        payload = json.loads(result.output)
+        assert payload["metadata"]["season"] == live
+
+        offenders = [
+            row["name"]
+            for row in payload["data"]["data_files"]
+            if row["name"] not in self.CLOCK_DERIVED
+            and CURRENT_SEASON in row["detail"]
+        ]
+        assert offenders == [], (
+            f"{offenders} named the clock's season {CURRENT_SEASON!r} while the "
+            f"report is for {live!r}"
+        )
+
+    def test_the_ratings_row_does_not_call_a_live_file_stale(self):
+        """The #318 row itself, from the outside."""
+        live = PREVIOUS_SEASON
+        (_data_dir() / "team_ratings.yaml").write_text(
+            yaml.dump({
+                "metadata": {
+                    "season": live,
+                    "last_updated": f"{CURRENT_YEAR}-07-01",
+                    "source": "calculated",
+                    "staleness_threshold_days": 30,
+                    "based_on_gws": [1, 36],
+                    "calculation_method": "full_season",
+                },
+                "ratings": {
+                    t: {"atk_home": 1, "atk_away": 2, "def_home": 3, "def_away": 4}
+                    for t in ("ARS", "MCI")
+                },
+            }),
+            encoding="utf-8",
+        )
+        result = _run(
+            _mock_client(season_year=CURRENT_YEAR - 1), args=["--format", "json"]
+        )
+        row = next(
+            r
+            for r in json.loads(result.output)["data"]["data_files"]
+            if r["name"] == "team_ratings.yaml"
+        )
+        assert "different league" not in row["detail"]
+        assert "neutral 4.0" not in row["detail"]
+
+
 class TestEnvironmentSection:
     def test_reports_dirs_and_override_source(self):
         result = _run(_mock_client())

{fplkit-2.6.0 → fplkit-2.6.1}/tests/test_cli_review.py

@@ -2167,6 +2167,13 @@ class TestReportSynthesisCompleteness:
         assert "## Draft Verdict" in err
 
 
+class _Boom:
+    """A synthesis provider whose call never lands (timeout, 500, spent 429)."""
+
+    async def query(self, *a, **k):
+        raise RuntimeError("provider exploded")
+
+
 class TestReviewLlmSummariseSurfacesAnIncompleteSynthesis:
     """#266: end to end, a truncated synthesis must not reach the report silently."""
 
@@ -2227,16 +2234,86 @@ class TestReviewLlmSummariseSurfacesAnIncompleteSynthesis:
         assert pathlib.Path(result["synthesis_corrections_path"]).resolve() == written.resolve()
         assert "## Draft Verdict" in written.read_text(encoding="utf-8")
 
-    async def test_a_synthesis_failure_still_returns_no_problems(self, capsys):
-        class _Boom:
+    async def test_a_call_that_never_landed_is_reported_like_one_that_did(self, capsys):
+        # #317: this used to assert the opposite, on the reasoning that an
+        # empty summary was visible on its own. #306 disproved that -- an empty
+        # summary renders as nothing at all -- so an exception has to reach the
+        # report through the same channel a damaged response does.
+        result = await _review_llm_summarise(**self._kwargs(_Boom()))
+
+        assert result["synthesis_summary"] == ""
+        problems = result["synthesis_problems"]
+        assert len(problems) == 1
+        assert "the synthesis call failed" in problems[0]
+        assert "RuntimeError: provider exploded" in problems[0]
+        assert "Synthesis failed: provider exploded" in capsys.readouterr().err
+
+    async def test_a_multiline_provider_error_stays_one_callout_bullet(self):
+        # Each problem renders as `> - {{ problem }}`, so an error wrapped
+        # across lines would break out of the blockquote mid-callout.
+        class _WordyBoom:
+            async def query(self, *a, **k):
+                raise ConnectionError("connection refused\n  while posting to /v1/messages")
+
+        result = await _review_llm_summarise(**self._kwargs(_WordyBoom()))
+        problem = result["synthesis_problems"][0]
+        assert "\n" not in problem
+        assert "connection refused while posting to /v1/messages" in problem
+
+    async def test_a_failure_after_the_call_returned_is_not_blamed_on_the_call(self, monkeypatch):
+        # The `try` used to cover the grounding check and the debug writes as
+        # well, so a defect in any of them discarded a summary the provider had
+        # already handed over and reported "the synthesis call failed" -- a
+        # confident lie about which half broke. Only the call is guarded now,
+        # so our own bug surfaces as itself (#322 review).
+        def _boom(*a, **k):
+            raise ZeroDivisionError("a bug in the grounding checker")
+
+        # Imported inside the function, so the source module is what to patch.
+        monkeypatch.setattr("fpl_cli.prompts.review.check_next_week_grounding", _boom)
+        provider = _StubSynthesisProvider(_reply(_WHOLE, "end_turn"))
+
+        with pytest.raises(ZeroDivisionError):
+            await _review_llm_summarise(**self._kwargs(provider))
+
+    async def test_an_exception_carrying_no_message_names_only_its_type(self):
+        class _Silent:
             async def query(self, *a, **k):
-                raise RuntimeError("provider exploded")
+                raise RuntimeError
+
+        result = await _review_llm_summarise(**self._kwargs(_Silent()))
+        # Not "RuntimeError:" with nothing after the colon, which reads as
+        # output that was itself cut off.
+        assert result["synthesis_problems"] == ["the synthesis call failed (RuntimeError)"]
+
+    async def test_debug_saves_the_failure_beside_the_other_corrections(self, tmp_path, monkeypatch):
+        # Same artefact whichever way the analysis was lost, so a `--debug`
+        # bundle does not need explaining.
+        monkeypatch.chdir(tmp_path)
+        result = await _review_llm_summarise(**self._kwargs(_Boom(), debug=True))
+
+        written = tmp_path / "data" / "debug" / "synthesis_corrections.txt"
+        assert pathlib.Path(result["synthesis_corrections_path"]).resolve() == written.resolve()
+        assert "the synthesis call failed (RuntimeError: provider exploded)" in written.read_text(
+            encoding="utf-8",
+        )
+
+    async def test_the_failure_reaches_the_saved_report_as_a_callout(self):
+        # The two halves pinned against each other: whatever the guard puts in
+        # `synthesis_problems`, the template has to render it -- which is the
+        # branch #306 fixed and this failure path now shares.
+        from fpl_cli.agents.orchestration.report import ReportAgent
 
         result = await _review_llm_summarise(**self._kwargs(_Boom()))
-        # The existing graceful-degradation path owns this case: an empty
-        # summary is already visible, so the guard adds nothing to it.
-        assert result["synthesis_summary"] == ""
-        assert result["synthesis_problems"] == []
+        report = ReportAgent()._generate_review_report(7, {
+            "generated_at": "Sun 7 Sep 2026, 08:00 BST",
+            "synthesis_summary": result["synthesis_summary"],
+            "synthesis_problems": result["synthesis_problems"],
+        })
+
+        assert "[!WARNING]" in report
+        assert "did not come through intact" in report
+        assert "> - the synthesis call failed (RuntimeError: provider exploded)" in report
 
 
 # ---------------------------------------------------------------------------

{fplkit-2.6.0 → fplkit-2.6.1}/tests/test_providers.py

@@ -1024,3 +1024,19 @@ class TestGetLlmProvider:
         """No provider configured at all."""
         with pytest.raises(UnknownProviderError):
             get_llm_provider("research", {})
+
+
+class TestShippedSynthesisMaxTokens:
+    """#316: a synthesis `max_tokens` cap shares its ceiling with the model's
+    thinking, so a cap too small produces a structurally empty response no
+    retry can fix (see AnthropicProvider.query). 4096 was that cap; 8000 was
+    the smallest value the issue's own repro table found clean. Pin a floor
+    on the shipped default so it cannot silently regress back below it.
+    """
+
+    def test_shipped_default_leaves_headroom_for_a_full_review(self):
+        from fpl_cli.cli._context import load_settings
+
+        settings = load_settings()
+        max_tokens = settings["llm"]["synthesis"]["query_defaults"]["max_tokens"]
+        assert max_tokens >= 8000

{fplkit-2.6.0 → fplkit-2.6.1}/tests/test_report_agent.py

@@ -622,7 +622,7 @@ class TestSynthesisProblemsCallout:
             "missing section(s): ## Draft Verdict, ## Next Week",
             "response ends without terminal punctuation (likely cut off mid-sentence)",
         ])
-        assert "failed its completeness check" in output
+        assert "did not come through intact" in output
         assert "## Draft Verdict" in output
         assert "terminal punctuation" in output
 
@@ -631,10 +631,10 @@ class TestSynthesisProblemsCallout:
         assert "A shrug of a week." in output
 
     def test_a_clean_run_adds_no_callout(self):
-        assert "completeness check" not in self._render(synthesis_problems=[])
+        assert "did not come through intact" not in self._render(synthesis_problems=[])
 
     def test_a_run_that_never_set_the_key_adds_no_callout(self):
-        assert "completeness check" not in self._render()
+        assert "did not come through intact" not in self._render()
 
     def test_an_empty_summary_still_carries_the_callout(self):
         # The worst truncation is the one that returns nothing at all, and it
@@ -648,7 +648,7 @@ class TestSynthesisProblemsCallout:
                 "the response is empty (the provider returned no text)",
             ],
         )
-        assert "failed its completeness check" in output
+        assert "did not come through intact" in output
         assert "max_tokens" in output
         assert "the provider returned no text" in output
 
@@ -656,7 +656,7 @@ class TestSynthesisProblemsCallout:
         # A reader needs to know the text is incomplete before reading it, not
         # after -- and the missing-key callout above it already reads that way.
         output = self._render(synthesis_problems=["missing section(s): ## Draft Verdict"])
-        assert output.index("failed its completeness check") < output.index("A shrug of a week.")
+        assert output.index("did not come through intact") < output.index("A shrug of a week.")
 
     def test_a_clean_run_is_spaced_exactly_as_it_was(self):
         # The callout moving above the summary must cost the ordinary report
@@ -681,7 +681,7 @@ class TestSynthesisProblemsCallout:
 
     def test_a_whitespace_only_summary_alone_writes_no_block_at_all(self):
         output = self._render(synthesis_summary="   ", synthesis_problems=[])
-        assert "completeness check" not in output
+        assert "did not come through intact" not in output
         assert "*Generated:" in output
         assert output.split("\n")[1].startswith("#")